From 70d6986a9ebd1427d21c97094b93d841362133fa Mon Sep 17 00:00:00 2001 From: acalcutt Date: Sun, 29 Dec 2024 17:05:01 -0500 Subject: [PATCH] cleanup utils.js Co-Authored-By: Andrew Calcutt --- src/utils.js | 110 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 81 insertions(+), 29 deletions(-) diff --git a/src/utils.js b/src/utils.js index 14e5871..5d01b5f 100644 --- a/src/utils.js +++ b/src/utils.js @@ -9,9 +9,10 @@ import { existsP } from './promises.js'; /** * Restrict user input to an allowed set of options. - * @param opts - * @param root0 - * @param root0.defaultValue + * @param {string[]} opts - An array of allowed option strings. + * @param {object} [config] - Optional configuration object. + * @param {string} [config.defaultValue] - The default value to return if input doesn't match. + * @returns {function(string): string} - A function that takes a value and returns it if valid or a default. */ export function allowedOptions(opts, { defaultValue } = {}) { const values = Object.fromEntries(opts.map((key) => [key, key])); @@ -19,10 +20,11 @@ export function allowedOptions(opts, { defaultValue } = {}) { } /** - * Replace local:// urls with public http(s):// urls - * @param req - * @param url - * @param publicUrl + * Replaces local:// URLs with public http(s):// URLs. + * @param {object} req - Express request object. + * @param {string} url - The URL string to fix. + * @param {string} publicUrl - The public URL prefix to use for replacements. + * @returns {string} - The fixed URL string. */ export function fixUrl(req, url, publicUrl) { if (!url || typeof url !== 'string' || url.indexOf('local://') !== 0) { @@ -40,12 +42,11 @@ export function fixUrl(req, url, publicUrl) { } /** - * Generate new URL object - * @param req - * @params {object} req - Express request - * @returns {URL} object + * Generates a new URL object from the Express request. + * @param {object} req - Express request object. + * @returns {URL} - URL object with correct host and optionally path. */ -const getUrlObject = (req) => { +function getUrlObject(req) { const urlObject = new URL(`${req.protocol}://${req.headers.host}/`); // support overriding hostname by sending X-Forwarded-Host http header urlObject.hostname = req.hostname; @@ -56,16 +57,33 @@ const getUrlObject = (req) => { urlObject.pathname = path.posix.join(xForwardedPath, urlObject.pathname); } return urlObject; -}; +} -export const getPublicUrl = (publicUrl, req) => { +/** + * Gets the public URL, either from a provided publicUrl or generated from the request. + * @param {string} publicUrl - The optional public URL to use. + * @param {object} req - The Express request object. + * @returns {string} - The final public URL string. + */ +export function getPublicUrl(publicUrl, req) { if (publicUrl) { return publicUrl; } return getUrlObject(req).toString(); -}; +} -export const getTileUrls = ( +/** + * Generates an array of tile URLs based on given parameters. + * @param {object} req - Express request object. + * @param {string | string[]} domains - Domain(s) to use for tile URLs. + * @param {string} path - The base path for the tiles. + * @param {number} [tileSize] - The size of the tile (optional). + * @param {string} format - The format of the tiles (e.g., 'png', 'jpg'). + * @param {string} publicUrl - The public URL to use (if not using domains). + * @param {object} [aliases] - Aliases for format extensions. + * @returns {string[]} An array of tile URL strings. + */ +export function getTileUrls( req, domains, path, @@ -73,7 +91,7 @@ export const getTileUrls = ( format, publicUrl, aliases, -) => { +) { const urlObject = getUrlObject(req); if (domains) { if (domains.constructor === String && domains.length > 0) { @@ -132,9 +150,14 @@ export const getTileUrls = ( } return uris; -}; +} -export const fixTileJSONCenter = (tileJSON) => { +/** + * Fixes the center in the tileJSON if no center is available. + * @param {object} tileJSON - The tileJSON object to process. + * @returns {void} + */ +export function fixTileJSONCenter(tileJSON) { if (tileJSON.bounds && !tileJSON.center) { const fitWidth = 1024; const tiles = fitWidth / 256; @@ -147,10 +170,19 @@ export const fixTileJSONCenter = (tileJSON) => { ), ]; } -}; +} -const getFontPbf = (allowedFonts, fontPath, name, range, fallbacks) => - new Promise((resolve, reject) => { +/** + * Retrieves font data for a given font and range. + * @param {object} allowedFonts - An object of allowed fonts. + * @param {string} fontPath - The path to the font directory. + * @param {string} name - The name of the font. + * @param {string} range - The range (e.g., '0-255') of the font to load. + * @param {object} [fallbacks] - Optional fallback font list. + * @returns {Promise} A promise that resolves with the font data Buffer or rejects with an error. + */ +function getFontPbf(allowedFonts, fontPath, name, range, fallbacks) { + return new Promise((resolve, reject) => { if (!allowedFonts || (allowedFonts[name] && fallbacks)) { const filename = path.join(fontPath, name, `${range}.pbf`); if (!fallbacks) { @@ -192,14 +224,24 @@ const getFontPbf = (allowedFonts, fontPath, name, range, fallbacks) => reject(`Font not allowed: ${name}`); } }); +} -export const getFontsPbf = async ( +/** + * Combines multiple font pbf buffers into one. + * @param {object} allowedFonts - An object of allowed fonts. + * @param {string} fontPath - The path to the font directory. + * @param {string} names - Comma-separated font names. + * @param {string} range - The range of the font (e.g., '0-255'). + * @param {object} [fallbacks] - Fallback font list. + * @returns {Promise} - A promise that resolves to the combined font data buffer. + */ +export async function getFontsPbf( allowedFonts, fontPath, names, range, fallbacks, -) => { +) { const fonts = names.split(','); const queue = []; for (const font of fonts) { @@ -216,9 +258,14 @@ export const getFontsPbf = async ( const combined = combine(await Promise.all(queue), names); return Buffer.from(combined.buffer, 0, combined.buffer.length); -}; +} -export const listFonts = async (fontPath) => { +/** + * Lists available fonts in a given font directory. + * @param {string} fontPath - The path to the font directory. + * @returns {Promise} - Promise that resolves with an object where keys are the font names. + */ +export async function listFonts(fontPath) { const existingFonts = {}; const files = await fsPromises.readdir(fontPath); @@ -233,9 +280,14 @@ export const listFonts = async (fontPath) => { } return existingFonts; -}; +} -export const isValidHttpUrl = (string) => { +/** + * Checks if a string is a valid HTTP or HTTPS URL. + * @param {string} string - The string to validate. + * @returns {boolean} True if the string is a valid HTTP/HTTPS URL, false otherwise. + */ +export function isValidHttpUrl(string) { let url; try { @@ -245,4 +297,4 @@ export const isValidHttpUrl = (string) => { } return url.protocol === 'http:' || url.protocol === 'https:'; -}; +}