@ucdjs-internal/shared 0.1.1-beta.1

package/dist/index.mjs

@@ -0,0 +1,914 @@
+import { createDebug } from "obug";
+import { isMSWError } from "@luxass/msw-utils/runtime-guards";
+import { prependLeadingSlash, trimLeadingSlash, trimTrailingSlash } from "@luxass/utils";
+import { hasUCDFolderPath } from "@unicode-utils/core";
+import picomatch from "picomatch";
+import { UCDWellKnownConfigSchema } from "@ucdjs/schemas";
+
+//#region src/async/promise-concurrency.ts
+function ensureIsPositiveConcurrency(concurrency, ErrorClazz) {
+	if (concurrency !== Number.POSITIVE_INFINITY && !Number.isInteger(concurrency) || typeof concurrency !== "number" || concurrency < 1) throw new ErrorClazz("Concurrency must be a positive integer");
+}
+/**
+* Creates a concurrency limiter that restricts the number of concurrent executions.
+*
+* @param {number} concurrency - The maximum number of concurrent executions allowed.
+* @returns {} A function that wraps any function to enforce the concurrency limit
+* @throws {Error} When concurrency is not a positive integer
+*
+* @example
+* ```typescript
+* import { createConcurrencyLimiter } from "@ucdjs-internal/shared";
+*
+* const limiter = createConcurrencyLimiter(2);
+*
+* // Only 2 of these will run concurrently
+* const results = await Promise.all([
+*   limiter(fetchData, "url1"),
+*   limiter(fetchData, "url2"),
+*   limiter(fetchData, "url3"),
+*   limiter(fetchData, "url4")
+* ]);
+* ```
+*/
+function createConcurrencyLimiter(concurrency) {
+	ensureIsPositiveConcurrency(concurrency, Error);
+	let activeTasks = 0;
+	let head;
+	let tail;
+	function finish() {
+		activeTasks--;
+		if (head) {
+			head[0]();
+			head = head[1];
+			tail = head && tail;
+		}
+	}
+	return (fn, ...args) => {
+		return new Promise((resolve) => {
+			if (activeTasks++ < concurrency) resolve();
+			else if (tail) tail = tail[1] = [resolve];
+			else head = tail = [resolve];
+		}).then(() => fn(...args)).finally(finish);
+	};
+}
+
+//#endregion
+//#region src/debugger.ts
+function createDebugger(namespace) {
+	const debug = createDebug(namespace);
+	if (debug.enabled) return debug;
+}
+
+//#endregion
+//#region src/async/try-catch.ts
+const debug$1 = createDebugger("ucdjs:shared:try-catch");
+function wrapTry(operation) {
+	debug$1?.("wrapTry: called", { operationType: typeof operation === "function" ? "function" : "promise" });
+	try {
+		const result = typeof operation === "function" ? operation() : operation;
+		if (isPromise(result)) {
+			debug$1?.("wrapTry: executing async operation");
+			return Promise.resolve(result).then((data) => {
+				debug$1?.("wrapTry: async operation succeeded", {
+					hasData: data != null,
+					dataType: typeof data
+				});
+				return onSuccess(data);
+			}).catch((error) => {
+				debug$1?.("wrapTry: async operation failed", {
+					errorName: error instanceof Error ? error.name : "Unknown",
+					errorMessage: error instanceof Error ? error.message : String(error)
+				});
+				return onFailure(error);
+			});
+		}
+		debug$1?.("wrapTry: sync operation succeeded", {
+			hasData: result != null,
+			dataType: typeof result
+		});
+		return onSuccess(result);
+	} catch (error) {
+		debug$1?.("wrapTry: sync operation failed", {
+			errorName: error instanceof Error ? error.name : "Unknown",
+			errorMessage: error instanceof Error ? error.message : String(error)
+		});
+		return onFailure(error);
+	}
+}
+function onSuccess(value) {
+	return [value, null];
+}
+function onFailure(error) {
+	return [null, error instanceof Error ? error : new Error(String(error))];
+}
+function isPromise(value) {
+	return !!value && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+function tryOr(config) {
+	const tryType = typeof config.try === "function" ? "function" : "promise";
+	debug$1?.("tryOr: called", { tryType });
+	try {
+		const tryResult = typeof config.try === "function" ? config.try() : config.try;
+		if (isPromise(tryResult)) {
+			debug$1?.("tryOr: executing async try");
+			return Promise.resolve(tryResult).then((data) => {
+				debug$1?.("tryOr: async try succeeded", {
+					hasData: data != null,
+					dataType: typeof data
+				});
+				return data;
+			}).catch((error) => {
+				debug$1?.("tryOr: async try failed, invoking error handler", {
+					errorName: error instanceof Error ? error.name : "Unknown",
+					errorMessage: error instanceof Error ? error.message : String(error)
+				});
+				const errResult = config.err(error);
+				if (isPromise(errResult)) {
+					debug$1?.("tryOr: error handler returned promise");
+					return errResult;
+				}
+				debug$1?.("tryOr: error handler returned sync value");
+				return errResult;
+			});
+		}
+		debug$1?.("tryOr: sync try succeeded", {
+			hasData: tryResult != null,
+			dataType: typeof tryResult
+		});
+		return tryResult;
+	} catch (err) {
+		debug$1?.("tryOr: sync try failed, invoking error handler", {
+			errorName: err instanceof Error ? err.name : "Unknown",
+			errorMessage: err instanceof Error ? err.message : String(err)
+		});
+		const errResult = config.err(err);
+		if (isPromise(errResult)) {
+			debug$1?.("tryOr: error handler returned promise");
+			return errResult;
+		}
+		debug$1?.("tryOr: error handler returned sync value");
+		return errResult;
+	}
+}
+
+//#endregion
+//#region src/json.ts
+const debug = createDebugger("ucdjs:shared:json");
+/**
+* Safely parses a JSON string into an object of type T.
+* Returns null if the parsing fails.
+*
+* @template T - The expected type of the parsed JSON
+* @param {string} content - The JSON string to parse
+* @returns {T | null} The parsed object of type T or null if parsing fails
+*/
+function safeJsonParse(content) {
+	try {
+		return JSON.parse(content);
+	} catch (err) {
+		debug?.("Failed to parse JSON", {
+			content,
+			error: err instanceof Error ? err.message : String(err)
+		});
+		return null;
+	}
+}
+
+//#endregion
+//#region src/fetch/error.ts
+var FetchError = class FetchError extends Error {
+	request;
+	options;
+	response;
+	data;
+	status;
+	statusText;
+	constructor(message, opts) {
+		super(message, opts);
+		this.name = "FetchError";
+		if (opts?.cause && !this.cause) this.cause = opts.cause;
+	}
+	static from(ctx) {
+		const errorMessage = ctx.error?.message || ctx.error?.toString() || "";
+		const method = ctx.request?.method || ctx.options?.method || "GET";
+		const url = ctx.request?.url || String(ctx.request) || "/";
+		const fetchError = new FetchError(`${`[${method}] ${JSON.stringify(url)}`}: ${ctx.response ? `${ctx.response.status} ${ctx.response.statusText}` : "<no response>"}${errorMessage ? ` ${errorMessage}` : ""}`, ctx.error ? { cause: ctx.error } : void 0);
+		Object.assign(fetchError, {
+			request: ctx.request,
+			options: ctx.options,
+			response: ctx.response,
+			data: ctx.response?.data,
+			status: ctx.response?.status,
+			statusText: ctx.response?.statusText
+		});
+		return fetchError;
+	}
+};
+var FetchSchemaValidationError = class extends FetchError {
+	issues;
+	constructor(message, opts) {
+		super(message, opts);
+		this.name = "FetchSchemaValidationError";
+		if (opts?.issues !== void 0) this.issues = opts.issues;
+	}
+};
+
+//#endregion
+//#region src/fetch/utils.ts
+const HTTP_METHODS_WITH_PAYLOADS = new Set([
+	"PATCH",
+	"POST",
+	"PUT",
+	"DELETE"
+]);
+function isPayloadMethod(method) {
+	return HTTP_METHODS_WITH_PAYLOADS.has(method?.toUpperCase() || "");
+}
+function isJSONSerializable(value) {
+	if (value === void 0) return false;
+	if (value === null) return true;
+	const t = typeof value;
+	if (t === "string" || t === "number" || t === "boolean") return true;
+	if (t !== "object") return false;
+	if (Array.isArray(value)) return true;
+	if (value && value.buffer) return false;
+	if (value instanceof FormData || value instanceof URLSearchParams) return false;
+	return !!value && value.constructor && value.constructor.name === "Object" || typeof value.toJSON === "function";
+}
+const TEXT_TYPES = new Set([
+	"image/svg",
+	"application/xml",
+	"application/xhtml",
+	"application/html"
+]);
+const JSON_RE = /^application\/(?:[\w!#$%&*.^`~-]*\+)?json(?:;.+)?$/i;
+function detectResponseType(_contentType = "") {
+	if (!_contentType) return "json";
+	const contentType = _contentType.split(";").shift() || "";
+	if (JSON_RE.test(contentType)) return "json";
+	if (contentType === "text/event-stream") return "stream";
+	if (TEXT_TYPES.has(contentType) || contentType.startsWith("text/")) return "text";
+	return "blob";
+}
+
+//#endregion
+//#region src/fetch/fetch.ts
+const DEFAULT_RETRY_STATUS_CODES = new Set([
+	408,
+	409,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const nullBodyResponses = new Set([
+	101,
+	204,
+	205,
+	304
+]);
+function createCustomFetch() {
+	async function handleError(context) {
+		const isAbort = context.error && context.error.name === "AbortError" && !context.options.timeout || false;
+		const isMSW = context.error && isMSWError(context.error);
+		if (context.options.retry !== false && !isAbort && !isMSW) {
+			let retries;
+			if (typeof context.options.retry === "number") retries = context.options.retry;
+			else retries = isPayloadMethod(context.options.method) ? 0 : 1;
+			const responseCode = context.response && context.response.status || 500;
+			if (retries > 0 && (Array.isArray(context.options.retryStatusCodes) ? context.options.retryStatusCodes.includes(responseCode) : DEFAULT_RETRY_STATUS_CODES.has(responseCode))) {
+				const retryDelay = typeof context.options.retryDelay === "function" ? context.options.retryDelay({
+					...context,
+					retryAttempt: context.options.retry - retries + 1
+				}) : context.options.retryDelay || 0;
+				if (retryDelay > 0) await new Promise((resolve) => setTimeout(resolve, retryDelay));
+				return executeFetch(context.request, {
+					...context.options,
+					retry: retries - 1
+				});
+			}
+		}
+		let error;
+		if (context.error instanceof FetchError) {
+			error = context.error;
+			Object.assign(error, {
+				request: error.request ?? context.request,
+				options: error.options ?? context.options,
+				response: error.response ?? context.response,
+				data: error.data ?? context.response?.data,
+				status: error.status ?? context.response?.status,
+				statusText: error.statusText ?? context.response?.statusText
+			});
+		} else error = FetchError.from(context);
+		if (Error.captureStackTrace) Error.captureStackTrace(error, executeFetch);
+		throw error;
+	}
+	async function executeFetch(_request, _options = {}) {
+		const context = {
+			request: _request,
+			options: {
+				..._options,
+				headers: new Headers(_options.headers ?? _request?.headers)
+			},
+			response: void 0,
+			error: void 0
+		};
+		if (context.options.method) context.options.method = context.options.method.toUpperCase();
+		if (context.options.body && isPayloadMethod(context.options.method)) {
+			if (isJSONSerializable(context.options.body)) {
+				const contentType = context.options.headers.get("content-type");
+				if (typeof context.options.body !== "string") context.options.body = contentType === "application/x-www-form-urlencoded" ? new URLSearchParams(context.options.body).toString() : JSON.stringify(context.options.body);
+				context.options.headers = new Headers(context.options.headers || {});
+				if (!contentType) context.options.headers.set("content-type", "application/json");
+				if (!context.options.headers.has("accept")) context.options.headers.set("accept", "application/json");
+			} else if ("pipeTo" in context.options.body && typeof context.options.body.pipeTo === "function" || typeof context.options.body.pipe === "function") {
+				if (!("duplex" in context.options)) context.options.duplex = "half";
+			}
+		}
+		let abortTimeout;
+		if (!context.options.signal && context.options.timeout) {
+			const controller = new AbortController();
+			abortTimeout = setTimeout(() => {
+				const error = /* @__PURE__ */ new Error("[TimeoutError]: The operation was aborted due to timeout");
+				error.name = "TimeoutError";
+				error.code = 23;
+				controller.abort(error);
+			}, context.options.timeout);
+			context.options.signal = controller.signal;
+		}
+		try {
+			context.response = await fetch(context.request, context.options);
+		} catch (error) {
+			context.error = error;
+			return await handleError(context);
+		} finally {
+			if (abortTimeout) clearTimeout(abortTimeout);
+		}
+		if ((context.response.body || context.response._bodyInit) && !nullBodyResponses.has(context.response.status) && context.options.method !== "HEAD") {
+			const responseType = context.options.parseAs || detectResponseType(context.response.headers.get("content-type") || "");
+			switch (responseType) {
+				case "json": {
+					const data = await context.response.text();
+					context.response.data = safeJsonParse(data) ?? void 0;
+					break;
+				}
+				case "stream":
+					context.response.data = context.response.body || context.response._bodyInit;
+					break;
+				default: context.response.data = await context.response[responseType]();
+			}
+			if (context.options.schema && context.response.data !== void 0 && context.response.status < 400) {
+				const result = await context.options.schema.safeParseAsync(context.response.data);
+				if (!result.success) {
+					context.error = new FetchSchemaValidationError(`Response validation failed: ${result.error.message}`, {
+						cause: result.error,
+						issues: result.error.issues
+					});
+					return await handleError(context);
+				}
+				context.response.data = result.data;
+			}
+		}
+		if (context.response.status >= 400 && context.response.status < 600) return await handleError(context);
+		return context.response;
+	}
+	async function safeFetch(request, options) {
+		try {
+			const response = await executeFetch(request, options);
+			return {
+				data: response.data ?? null,
+				response,
+				error: null
+			};
+		} catch (err) {
+			if (!(err instanceof FetchError)) return {
+				data: null,
+				error: FetchError.from({
+					request,
+					options: {
+						...options,
+						headers: new Headers(options?.headers || {})
+					},
+					response: void 0,
+					error: err
+				}),
+				response: void 0
+			};
+			return {
+				data: null,
+				error: err,
+				response: err.response
+			};
+		}
+	}
+	const customFetch = executeFetch;
+	customFetch.safe = safeFetch;
+	return customFetch;
+}
+const customFetch = createCustomFetch();
+
+//#endregion
+//#region src/files.ts
+/**
+* Normalizes an API file-tree path to a version-relative path suitable for filtering.
+*
+* This strips:
+* - Leading/trailing slashes
+* - Version prefix (e.g., "16.0.0/")
+* - "ucd/" prefix for versions that have it
+*
+* @param {string} version - The Unicode version string
+* @param {string} rawPath - The raw path from the API file tree (e.g., "/16.0.0/ucd/Blocks.txt")
+* @returns {string} The normalized path (e.g., "Blocks.txt")
+*
+* @example
+* ```typescript
+* normalizePathForFiltering("16.0.0", "/16.0.0/ucd/Blocks.txt");
+* // Returns: "Blocks.txt"
+*
+* normalizePathForFiltering("16.0.0", "/16.0.0/ucd/auxiliary/GraphemeBreakProperty.txt");
+* // Returns: "auxiliary/GraphemeBreakProperty.txt"
+* ```
+*/
+function normalizePathForFiltering(version, rawPath) {
+	let path = trimTrailingSlash(trimLeadingSlash(rawPath));
+	const versionPrefix = `${version}/`;
+	if (path.startsWith(versionPrefix)) path = path.slice(versionPrefix.length);
+	if (hasUCDFolderPath(version) && path.startsWith("ucd/")) path = path.slice(4);
+	return path;
+}
+/**
+* Creates a normalized view of a file tree for filtering purposes.
+*
+* This recursively maps all `path` properties to version-relative paths,
+* so that filter patterns like "Blocks.txt" or "auxiliary/**" will match
+* against paths like "/16.0.0/ucd/Blocks.txt".
+*
+* @template {UnicodeFileTreeNodeWithoutLastModified} T - A tree node type that extends the base TreeNode interface
+* @param {string} version - The Unicode version string
+* @param {T[]} entries - Array of file tree nodes from the API
+* @returns {T[]} A new tree with normalized paths suitable for filtering
+*
+* @example
+* ```typescript
+* const apiTree = [{ type: "file", name: "Blocks.txt", path: "/16.0.0/ucd/Blocks.txt" }];
+* const normalizedTree = normalizeTreeForFiltering("16.0.0", apiTree);
+* // Returns: [{ type: "file", name: "Blocks.txt", path: "Blocks.txt" }]
+* ```
+*/
+function normalizeTreeForFiltering(version, entries) {
+	return entries.map((entry) => {
+		const normalizedPath = normalizePathForFiltering(version, entry.path);
+		if (entry.type === "directory" && entry.children) return {
+			...entry,
+			path: normalizedPath,
+			children: normalizeTreeForFiltering(version, entry.children)
+		};
+		return {
+			...entry,
+			path: normalizedPath
+		};
+	});
+}
+/**
+* Recursively find a node (file or directory) by its path in the tree.
+*
+* @template T - A tree node type that extends the base TreeNode interface
+* @param {T[]} entries - Array of file tree nodes that may contain nested children
+* @param {string} targetPath - The path to search for
+* @returns {T | undefined} The found node or undefined
+*/
+function findFileByPath(entries, targetPath) {
+	for (const fileOrDirectory of entries) {
+		if ((fileOrDirectory.path ?? fileOrDirectory.name) === targetPath) return fileOrDirectory;
+		if (fileOrDirectory.type === "directory" && fileOrDirectory.children) {
+			const found = findFileByPath(fileOrDirectory.children, targetPath);
+			if (found) return found;
+		}
+	}
+}
+/**
+* Recursively flattens a hierarchical file structure into an array of file paths.
+*
+* @template T - A tree node type that extends the base TreeNode interface
+* @param {T[]} entries - Array of file tree nodes that may contain nested children
+* @param {string} [prefix] - Optional path prefix to prepend to each file path (default: "")
+* @returns {string[]} Array of flattened file paths as strings
+*
+* @example
+* ```typescript
+* import { flattenFilePaths } from "@ucdjs-internal/shared";
+*
+* const files = [
+*   { type: "directory", name: "folder1", path: "/folder1", children: [{ type: "file", name: "file1.txt", path: "/folder1/file1.txt" }] },
+*   { type: "file", name: "file2.txt", path: "/file2.txt" }
+* ];
+* const paths = flattenFilePaths(files);
+* // Returns: ["/folder1/file1.txt", "/file2.txt"]
+* ```
+*/
+function flattenFilePaths(entries, prefix = "") {
+	const paths = [];
+	if (!Array.isArray(entries)) throw new TypeError("Expected 'entries' to be an array of file tree nodes.");
+	for (const file of entries) {
+		const fullPath = prefix ? `${prefix}${prependLeadingSlash(file.path)}` : file.path;
+		if (file.type === "directory" && file.children) paths.push(...flattenFilePaths(file.children, prefix));
+		else paths.push(fullPath);
+	}
+	return paths;
+}
+
+//#endregion
+//#region src/glob.ts
+/**
+* Default picomatch options used across the shared package.
+* These options ensure consistent glob matching behavior:
+* - `nocase: true` - Case-insensitive matching
+* - `dot: true` - Match dotfiles (files starting with `.`)
+*/
+const DEFAULT_PICOMATCH_OPTIONS = {
+	nocase: true,
+	dot: true
+};
+function matchGlob(pattern, value, options = {}) {
+	const { nocase = DEFAULT_PICOMATCH_OPTIONS.nocase, dot = DEFAULT_PICOMATCH_OPTIONS.dot } = options;
+	return picomatch.isMatch(value, pattern, {
+		nocase,
+		dot
+	});
+}
+function createGlobMatcher(pattern, options = {}) {
+	const { nocase = DEFAULT_PICOMATCH_OPTIONS.nocase, dot = DEFAULT_PICOMATCH_OPTIONS.dot } = options;
+	const isMatch = picomatch(pattern, {
+		nocase,
+		dot
+	});
+	return (value) => isMatch(value);
+}
+const MAX_GLOB_LENGTH = 256;
+const MAX_GLOB_SEGMENTS = 16;
+const MAX_GLOB_BRACE_EXPANSIONS = 24;
+const MAX_GLOB_STARS = 32;
+const MAX_GLOB_QUESTIONS = 32;
+function countWildcards(pattern) {
+	let stars = 0;
+	let questions = 0;
+	for (let i = 0; i < pattern.length; i += 1) {
+		const ch = pattern.charAt(i);
+		if (ch === "\\") {
+			i += 1;
+			continue;
+		}
+		if (ch === "*") stars += 1;
+		if (ch === "?") questions += 1;
+	}
+	return {
+		stars,
+		questions
+	};
+}
+function analyzeBraces(pattern) {
+	let braceDepth = 0;
+	const topLevelGroups = [];
+	const topLevelOptions = [];
+	let currentNestedStack = [];
+	for (let i = 0; i < pattern.length; i += 1) {
+		const ch = pattern.charAt(i);
+		if (ch === "\\") {
+			i += 1;
+			continue;
+		}
+		if (ch === "{") {
+			braceDepth += 1;
+			if (braceDepth === 1) {
+				topLevelOptions.push({
+					base: 1,
+					nestedMultiplier: 1
+				});
+				currentNestedStack = [];
+			} else currentNestedStack.push(1);
+		} else if (ch === "}") {
+			if (braceDepth === 0) return {
+				expansions: 0,
+				valid: false
+			};
+			braceDepth -= 1;
+			if (braceDepth === 0) {
+				let totalExpansions = 0;
+				for (const option of topLevelOptions) totalExpansions += option.base * option.nestedMultiplier;
+				topLevelGroups.push(totalExpansions);
+				topLevelOptions.length = 0;
+				currentNestedStack = [];
+			} else if (currentNestedStack.length > 0) {
+				const nestedCount = currentNestedStack.pop();
+				if (currentNestedStack.length > 0) currentNestedStack[currentNestedStack.length - 1] *= nestedCount;
+				else if (topLevelOptions.length > 0) topLevelOptions[topLevelOptions.length - 1].nestedMultiplier *= nestedCount;
+			}
+		} else if (ch === ",") {
+			if (braceDepth === 1) topLevelOptions.push({
+				base: 1,
+				nestedMultiplier: 1
+			});
+			else if (braceDepth > 1) {
+				if (currentNestedStack.length > 0) currentNestedStack[currentNestedStack.length - 1] += 1;
+			}
+		}
+	}
+	if (braceDepth !== 0) return {
+		expansions: 0,
+		valid: false
+	};
+	if (topLevelGroups.length === 0) return {
+		expansions: 0,
+		valid: true
+	};
+	return {
+		expansions: topLevelGroups.reduce((product, count) => product * count, 1),
+		valid: true
+	};
+}
+function isValidGlobPattern(pattern, limits = {}) {
+	const { maxLength = MAX_GLOB_LENGTH, maxSegments = MAX_GLOB_SEGMENTS, maxBraceExpansions = MAX_GLOB_BRACE_EXPANSIONS, maxStars = MAX_GLOB_STARS, maxQuestions = MAX_GLOB_QUESTIONS } = limits;
+	if (typeof pattern !== "string") return false;
+	if (pattern.length === 0) return false;
+	if (pattern.trim().length === 0) return false;
+	if (pattern.length > maxLength) return false;
+	if (pattern.includes("\0")) return false;
+	if (pattern.split(/[/\\]+/).filter(Boolean).length > maxSegments) return false;
+	const { stars, questions } = countWildcards(pattern);
+	if (stars > maxStars) return false;
+	if (questions > maxQuestions) return false;
+	const { expansions, valid: braceValid } = analyzeBraces(pattern);
+	if (!braceValid) return false;
+	if (expansions > maxBraceExpansions) return false;
+	try {
+		picomatch.scan(pattern);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/filter.ts
+/**
+* File extensions excluded by default in createPathFilter.
+* These are archive and document formats that are typically not needed for Unicode data processing.
+*/
+const DEFAULT_EXCLUDED_EXTENSIONS = [
+	".zip",
+	".tar",
+	".gz",
+	".bz2",
+	".xz",
+	".7z",
+	".rar",
+	".pdf"
+];
+/**
+* Predefined filter patterns for common file exclusions.
+* These constants can be used with `createPathFilter` to easily exclude common file types.
+*
+* @example
+* ```ts
+* import { createPathFilter, PRECONFIGURED_FILTERS } from '@ucdjs-internal/shared';
+*
+* const filter = createPathFilter({
+*   include: ['*.txt'],
+*   exclude: [
+*     ...PRECONFIGURED_FILTERS.TEST_FILES,
+*     ...PRECONFIGURED_FILTERS.README_FILES
+*   ]
+* });
+* ```
+*/
+const PRECONFIGURED_FILTERS = {
+	TEST_FILES: ["**/*Test*"],
+	README_FILES: ["**/ReadMe.txt"],
+	HTML_FILES: ["**/*.html"]
+};
+/**
+* Creates a filter function that checks if a file path should be included or excluded
+* based on the provided filter configuration.
+*
+* @param {PathFilterOptions} options - Configuration object with include/exclude patterns
+* @returns {PathFilter} A function that takes a path and returns true if the path should be included, false otherwise
+*
+* @example
+* ```ts
+* import { createPathFilter, PRECONFIGURED_FILTERS } from '@ucdjs-internal/shared';
+*
+* // Include specific files, exclude others
+* const filter = createPathFilter({
+*   include: ['src/**\/*.{js,ts}', 'test/**\/*.{test.js}'],
+*   exclude: ['**\/node_modules/**', '**\/*.generated.*']
+* });
+*
+* // If include is empty/not set, includes everything
+* const excludeOnly = createPathFilter({
+*   exclude: ['**\/node_modules/**', '**\/dist/**']
+* });
+*
+* // Using preconfigured filters
+* const withPresets = createPathFilter({
+*   include: ['src/**\/*.txt'],
+*   exclude: [
+*     ...PRECONFIGURED_FILTERS.TEST_FILES,
+*   ]
+* });
+* ```
+*/
+function createPathFilter(options = {}) {
+	let currentConfig = { ...options };
+	let currentFilterFn = internal__createFilterFunction(currentConfig);
+	function filterFn(path, extraOptions = {}) {
+		if (!extraOptions.include && !extraOptions.exclude) return currentFilterFn(path);
+		return internal__createFilterFunction({
+			include: Array.from(new Set([...currentConfig.include || [], ...extraOptions.include || []])),
+			exclude: Array.from(new Set([...currentConfig.exclude || [], ...extraOptions.exclude || []])),
+			disableDefaultExclusions: currentConfig.disableDefaultExclusions
+		})(path);
+	}
+	filterFn.extend = (additionalOptions) => {
+		currentConfig = {
+			...currentConfig,
+			include: [...currentConfig.include || [], ...additionalOptions.include || []],
+			exclude: [...currentConfig.exclude || [], ...additionalOptions.exclude || []]
+		};
+		currentFilterFn = internal__createFilterFunction(currentConfig);
+	};
+	filterFn.patterns = () => {
+		return Object.freeze(structuredClone(currentConfig));
+	};
+	return filterFn;
+}
+function normalizeForMatching(value) {
+	let normalized = value.replace(/\\/g, "/");
+	normalized = normalized.replace(/^\.\/+/, "");
+	normalized = normalized.replace(/^\//, "");
+	normalized = normalized.replace(/\/$/, "");
+	return normalized;
+}
+function normalizePatterns(patterns) {
+	const normalized = [];
+	for (let i = 0; i < patterns.length; i += 1) normalized.push(normalizeForMatching(patterns[i]));
+	return normalized;
+}
+function internal__createFilterFunction(config) {
+	const includePatterns = config.include && config.include.length > 0 ? config.include : ["**"];
+	const rawExcludePatterns = config.disableDefaultExclusions ? [...config.exclude || []] : [...DEFAULT_EXCLUDED_EXTENSIONS.map((ext) => `**/*${ext}`), ...config.exclude || []];
+	const normalizedIncludePatterns = normalizePatterns(includePatterns);
+	const excludePatterns = expandDirectoryPatterns(normalizePatterns(rawExcludePatterns));
+	return (path) => {
+		const normalizedPath = normalizeForMatching(path);
+		return picomatch.isMatch(normalizedPath, normalizedIncludePatterns, {
+			...DEFAULT_PICOMATCH_OPTIONS,
+			ignore: excludePatterns
+		});
+	};
+}
+function expandDirectoryPatterns(patterns) {
+	const expanded = [];
+	for (const pattern of patterns) {
+		expanded.push(pattern);
+		if (isDirectoryOnlyPattern(pattern)) expanded.push(`${pattern}/**`);
+	}
+	return expanded;
+}
+function isDirectoryOnlyPattern(pattern) {
+	return !pattern.endsWith("/**") && !pattern.endsWith("/*") && !pattern.endsWith("/") && !pattern.includes(".") && !pattern.includes("*.") && (pattern.includes("/") || !pattern.includes("*"));
+}
+function filterTreeStructure(pathFilter, entries, extraOptions = {}) {
+	return internal__filterTreeStructure(pathFilter, entries, "", extraOptions);
+}
+function internal__filterTreeStructure(pathFilter, entries, parentPath, extraOptions) {
+	const filteredEntries = [];
+	for (const entry of entries) {
+		const fullPath = entry.path;
+		if (entry.type === "file") {
+			if (pathFilter(fullPath, extraOptions)) filteredEntries.push(entry);
+		} else if (entry.type === "directory") {
+			const filteredChildren = internal__filterTreeStructure(pathFilter, entry.children, fullPath, extraOptions);
+			const directoryMatches = pathFilter(fullPath, extraOptions);
+			const hasMatchingChildren = filteredChildren.length > 0;
+			if (directoryMatches || hasMatchingChildren) filteredEntries.push({
+				...entry,
+				children: filteredChildren
+			});
+		}
+	}
+	return filteredEntries;
+}
+
+//#endregion
+//#region src/guards.ts
+/**
+* Type guard function that checks if an unknown value is an ApiError object.
+*
+* This function performs runtime type checking to determine if the provided value
+* conforms to the ApiError interface structure by verifying the presence of
+* required properties: message, status, and timestamp.
+*
+* @param {unknown} error - The unknown value to check against the ApiError type
+* @returns {error is ApiError} True if the value is an ApiError, false otherwise
+*
+* @example
+* ```typescript
+* import { isApiError } from "@ucdjs-internal/shared";
+* import { client } from "@ucdjs/client";
+*
+* const { error, data } = await client.GET("/api/v1/versions");
+* if (isApiError(error)) {
+*   console.error("API Error:", error.message);
+* }
+* ```
+*/
+function isApiError(error) {
+	return typeof error === "object" && error !== null && "message" in error && "status" in error && "timestamp" in error && typeof error.message === "string" && typeof error.status === "number" && typeof error.timestamp === "string";
+}
+
+//#endregion
+//#region src/ucd-config.ts
+/**
+* Fetches and validates the UCD well-known configuration from a server
+*
+* @param {string} baseUrl - The base URL of the UCD server
+* @returns {Promise<UCDWellKnownConfig>} The validated well-known configuration
+* @throws {Error} If the config cannot be fetched or is invalid
+*/
+async function discoverEndpointsFromConfig(baseUrl) {
+	const url = new URL("/.well-known/ucd-config.json", baseUrl);
+	const fetchResult = await customFetch.safe(url.toString(), { parseAs: "json" });
+	if (fetchResult.error) throw fetchResult.error;
+	const result = UCDWellKnownConfigSchema.safeParse(fetchResult.data);
+	if (!result.success) throw new Error(`Invalid well-known config: ${result.error.message}`);
+	return result.data;
+}
+/**
+* Return the default UCD well-known configuration used by the library.
+*
+* This function returns the build-time injected __UCD_ENDPOINT_DEFAULT_CONFIG__ if present;
+* otherwise it falls back to a hard-coded default object containing a version and
+* the common API endpoint paths for files, manifest and versions.
+*
+* The returned value conforms to the UCDWellKnownConfig schema and is used when
+* discovery via discoverEndpointsFromConfig() is not possible or a local default
+* is required.
+*
+* @returns {UCDWellKnownConfig} The default well-known configuration.
+*/
+function getDefaultUCDEndpointConfig() {
+	return {
+		"version": "0.1",
+		"endpoints": {
+			"files": "/api/v1/files",
+			"manifest": "/.well-known/ucd-store/{version}.json",
+			"versions": "/api/v1/versions"
+		},
+		"versions": [
+			"17.0.0",
+			"16.0.0",
+			"15.1.0",
+			"15.0.0",
+			"14.0.0",
+			"13.0.0",
+			"12.1.0",
+			"12.0.0",
+			"11.0.0",
+			"10.0.0",
+			"9.0.0",
+			"8.0.0",
+			"7.0.0",
+			"6.3.0",
+			"6.2.0",
+			"6.1.0",
+			"6.0.0",
+			"5.2.0",
+			"5.1.0",
+			"5.0.0",
+			"4.1.0",
+			"4.0.1",
+			"4.0.0",
+			"3.2.0",
+			"3.1.1",
+			"3.1.0",
+			"3.0.1",
+			"3.0.0",
+			"2.1.9",
+			"2.1.8",
+			"2.1.5",
+			"2.1.2",
+			"2.0.0",
+			"1.1.5",
+			"1.1.0",
+			"1.0.1",
+			"1.0.0"
+		]
+	};
+}
+
+//#endregion
+export { DEFAULT_EXCLUDED_EXTENSIONS, DEFAULT_PICOMATCH_OPTIONS, PRECONFIGURED_FILTERS, createConcurrencyLimiter, createDebugger, createGlobMatcher, createPathFilter, customFetch, discoverEndpointsFromConfig, ensureIsPositiveConcurrency, filterTreeStructure, findFileByPath, flattenFilePaths, getDefaultUCDEndpointConfig, isApiError, isValidGlobPattern, matchGlob, normalizePathForFiltering, normalizeTreeForFiltering, safeJsonParse, tryOr, wrapTry };