@ucdjs-internal/shared 0.1.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Lucas Nørgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @ucdjs-internal/shared
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![codecov][codecov-src]][codecov-href]
+
+> [!IMPORTANT]
+> This is an internal package. It may change without warning and is not subject to semantic versioning. Use at your own risk.
+
+A collection of utility functions and filesystem bridge implementations for the UCD project.
+
+## Installation
+
+```bash
+npm install @ucdjs-internal/shared
+```
+
+## Usage
+
+### Path Filtering
+
+Creates a filter function that checks if a file path should be included or excluded based on glob patterns.
+
+```typescript
+import { createPathFilter } from "@ucdjs-internal/shared";
+
+const filter = createPathFilter(["*.txt", "!*Test*"]);
+filter("Data.txt"); // true
+filter("DataTest.txt"); // false
+```
+
+#### PathFilter Methods
+
+The `PathFilter` object provides additional methods:
+
+```typescript
+const filter = createPathFilter(["*.js"]);
+
+// Extend with additional patterns
+filter.extend(["*.ts", "!*.test.*"]);
+
+// Get current patterns
+const patterns = filter.patterns(); // ['*.js', '*.ts', '!*.test.*']
+
+// Use with extra filters temporarily
+filter("app.js", ["!src/**"]); // Apply extra exclusions
+```
+
+### Preconfigured Filters
+
+Pre-defined filter patterns for common exclusions:
+
+```typescript
+import { createPathFilter, PRECONFIGURED_FILTERS } from "@ucdjs-internal/shared";
+
+const filter = createPathFilter([
+  "*.txt",
+  PRECONFIGURED_FILTERS.EXCLUDE_TEST_FILES,
+  PRECONFIGURED_FILTERS.EXCLUDE_README_FILES,
+  PRECONFIGURED_FILTERS.EXCLUDE_HTML_FILES
+]);
+```
+
+Available filters:
+- `EXCLUDE_TEST_FILES`: Excludes files containing "Test" in their name
+- `EXCLUDE_README_FILES`: Excludes ReadMe.txt files
+- `EXCLUDE_HTML_FILES`: Excludes all HTML files
+
+## 📄 License
+
+Published under [MIT License](./LICENSE).
+
+[npm-version-src]: https://img.shields.io/npm/v/@ucdjs-internal/shared?style=flat&colorA=18181B&colorB=4169E1
+[npm-version-href]: https://npmjs.com/package/@ucdjs-internal/shared
+[npm-downloads-src]: https://img.shields.io/npm/dm/@ucdjs-internal/shared?style=flat&colorA=18181B&colorB=4169E1
+[npm-downloads-href]: https://npmjs.com/package/@ucdjs-internal/shared
+[codecov-src]: https://img.shields.io/codecov/c/gh/ucdjs/ucd?style=flat&colorA=18181B&colorB=4169E1
+[codecov-href]: https://codecov.io/gh/ucdjs/ucd

package/dist/index.d.mts

@@ -0,0 +1,403 @@
+import { Debugger } from "obug";
+import { PicomatchOptions } from "picomatch";
+import { ApiError, UCDWellKnownConfig, UnicodeFileTreeNodeWithoutLastModified } from "@ucdjs/schemas";
+import { ZodType } from "zod";
+
+//#region src/async/promise-concurrency.d.ts
+type ConcurrencyLimitFn = <Args extends unknown[], T>(fn: (...args: Args) => PromiseLike<T> | T, ...args: Args) => Promise<T>;
+declare function ensureIsPositiveConcurrency(concurrency: unknown, ErrorClazz: new (message: string) => Error): void;
+/**
+ * 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")
+ * ]);
+ * ```
+ */
+declare function createConcurrencyLimiter(concurrency: number): ConcurrencyLimitFn;
+//#endregion
+//#region src/async/try-catch.d.ts
+type OperationSuccess<T> = readonly [data: T, error: null];
+type OperationFailure<E> = readonly [data: null, error: E];
+type OperationResult<T, E> = OperationSuccess<T> | OperationFailure<E>;
+declare function wrapTry<T, E = Error>(operation: Promise<T>): Promise<OperationResult<T, E>>;
+declare function wrapTry<_T, E = Error>(operation: () => never): OperationResult<never, E>;
+declare function wrapTry<T, E = Error>(operation: () => Promise<T>): Promise<OperationResult<T, E>>;
+declare function wrapTry<T, E = Error>(operation: () => T): OperationResult<T, E>;
+type InferErrorType<TTry, TErr> = TErr extends readonly never[] ? TTry extends readonly (infer E)[] ? E[] : TTry extends (infer E)[] ? E[] : TErr : TErr extends readonly [] ? TTry extends readonly (infer E)[] ? E[] : TTry extends (infer E)[] ? E[] : TErr : TErr;
+declare function tryOr<TTry, TErr = TTry>(config: {
+  try: Promise<TTry>;
+  err: (error: unknown) => Promise<TErr>;
+}): Promise<TTry | InferErrorType<TTry, TErr>>;
+declare function tryOr<TTry, TErr = TTry>(config: {
+  try: Promise<TTry>;
+  err: (error: unknown) => TErr;
+}): Promise<TTry | InferErrorType<TTry, TErr>>;
+declare function tryOr<TTry, TErr = TTry>(config: {
+  try: () => Promise<TTry>;
+  err: (error: unknown) => Promise<TErr>;
+}): Promise<TTry | InferErrorType<TTry, TErr>>;
+declare function tryOr<TTry, TErr = TTry>(config: {
+  try: () => Promise<TTry>;
+  err: (error: unknown) => TErr;
+}): Promise<TTry | InferErrorType<TTry, TErr>>;
+declare function tryOr<TTry, TErr = TTry>(config: {
+  try: () => TTry;
+  err: (error: unknown) => Promise<TErr>;
+}): Promise<TTry | InferErrorType<TTry, TErr>>;
+declare function tryOr<TTry, TErr = TTry>(config: {
+  try: () => TTry;
+  err: (error: unknown) => TErr;
+}): TTry | InferErrorType<TTry, TErr>;
+//#endregion
+//#region src/debugger.d.ts
+declare function createDebugger(namespace: `ucdjs:${string}`): Debugger | undefined;
+//#endregion
+//#region src/fetch/error.d.ts
+declare class FetchError<T = any> extends Error {
+  readonly request?: RequestInfo;
+  readonly options?: FetchOptions;
+  readonly response?: FetchResponse<T>;
+  readonly data?: T;
+  readonly status?: number;
+  readonly statusText?: string;
+  constructor(message: string, opts?: {
+    cause: unknown;
+  });
+  static from<T = any, R extends ResponseType = ResponseType>(ctx: FetchContext<T, R>): FetchError<T>;
+}
+declare class FetchSchemaValidationError<T = any> extends FetchError<T> {
+  readonly issues?: unknown;
+  constructor(message: string, opts?: {
+    cause: unknown;
+    issues?: unknown;
+  });
+}
+//#endregion
+//#region src/fetch/types.d.ts
+interface CustomFetch {
+  <T = any, R extends ResponseType = "json">(request: RequestInfo, options?: FetchOptions<R, T>): Promise<FetchResponse<MappedResponseType<R, T>>>;
+  safe: <T = any, R extends ResponseType = "json">(request: RequestInfo, options?: FetchOptions<R, T>) => Promise<SafeFetchResponse<MappedResponseType<R, T>>>;
+}
+interface ResponseMap {
+  blob: Blob;
+  text: string;
+  arrayBuffer: ArrayBuffer;
+  stream: ReadableStream<Uint8Array>;
+}
+type ResponseType = keyof ResponseMap | "json";
+type MappedResponseType<R extends ResponseType, JsonType = any> = R extends keyof ResponseMap ? ResponseMap[R] : JsonType;
+interface SafeFetchResponse<T = any> {
+  data: T | null;
+  error: FetchError<T> | FetchSchemaValidationError<T> | null;
+  response?: FetchResponse<T>;
+}
+interface FetchResponse<T> extends Response {
+  data?: T;
+}
+interface FetchOptions<R extends ResponseType = ResponseType, T = any> extends Omit<RequestInit, "body"> {
+  body?: RequestInit["body"] | Record<string, any>;
+  parseAs?: R;
+  /**
+   * Zod schema to validate the response data against.
+   * If validation fails, an error will be returned/thrown.
+   *
+   * TODO(@luxass): figure out how we can hide the true value of
+   *  `schema` from the user. Since it is very large, it can be
+   *  confusing to see it in error messages.
+   */
+  schema?: ZodType<T>;
+  /**
+   * @experimental Set to "half" to enable duplex streaming.
+   * Will be automatically set to "half" when using a ReadableStream as body.
+   * @see https://fetch.spec.whatwg.org/#enumdef-requestduplex
+   */
+  duplex?: "half" | undefined;
+  /** timeout in milliseconds */
+  timeout?: number;
+  retry?: number | false;
+  /** Delay between retries in milliseconds. */
+  retryDelay?: number | ((context: FetchContext<T, R> & {
+    retryAttempt: number;
+  }) => number);
+  /** Default is [408, 409, 425, 429, 500, 502, 503, 504] */
+  retryStatusCodes?: number[];
+}
+interface FetchContext<T = any, R extends ResponseType = ResponseType> {
+  request: RequestInfo;
+  options: FetchOptions<R> & {
+    headers: Headers;
+  };
+  response?: FetchResponse<MappedResponseType<R, T>>;
+  error?: Error;
+}
+//#endregion
+//#region src/fetch/fetch.d.ts
+declare const customFetch: CustomFetch;
+//#endregion
+//#region src/files.d.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"
+ * ```
+ */
+declare function normalizePathForFiltering(version: string, rawPath: string): string;
+/**
+ * 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" }]
+ * ```
+ */
+declare function normalizeTreeForFiltering<T extends UnicodeFileTreeNodeWithoutLastModified>(version: string, entries: T[]): T[];
+/**
+ * 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
+ */
+declare function findFileByPath<T extends UnicodeFileTreeNodeWithoutLastModified>(entries: T[], targetPath: string): T | undefined;
+/**
+ * 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"]
+ * ```
+ */
+declare function flattenFilePaths<T extends UnicodeFileTreeNodeWithoutLastModified>(entries: T[], prefix?: string): string[];
+//#endregion
+//#region src/filter.d.ts
+/**
+ * File extensions excluded by default in createPathFilter.
+ * These are archive and document formats that are typically not needed for Unicode data processing.
+ */
+declare const DEFAULT_EXCLUDED_EXTENSIONS: readonly [".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
+ *   ]
+ * });
+ * ```
+ */
+declare const PRECONFIGURED_FILTERS: {
+  /** Excludes files containing "Test" in their name (e.g., DataTest.txt, TestFile.js) */readonly TEST_FILES: readonly ["**/*Test*"]; /** Excludes ReadMe.txt files from any directory */
+  readonly README_FILES: readonly ["**/ReadMe.txt"]; /** Excludes all HTML files */
+  readonly HTML_FILES: readonly ["**/*.html"];
+};
+type PathFilterFn = (path: string, extraOptions?: Pick<PathFilterOptions, "include" | "exclude">) => boolean;
+interface PathFilter extends PathFilterFn {
+  extend: (additionalOptions: Pick<PathFilterOptions, "include" | "exclude">) => void;
+  patterns: () => Readonly<PathFilterOptions>;
+}
+interface PathFilterOptions {
+  /**
+   * Glob patterns for files to include.
+   * If empty or not set, includes everything using "**" pattern
+   */
+  include?: string[];
+  /**
+   * Glob patterns for files to exclude.
+   * These override include patterns
+   */
+  exclude?: string[];
+  /**
+   * Whether to disable default exclusions (.zip, .pdf).
+   * If true, no default exclusions will be applied.
+   *
+   * @default false
+   */
+  disableDefaultExclusions?: boolean;
+}
+/**
+ * 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,
+ *   ]
+ * });
+ * ```
+ */
+declare function createPathFilter(options?: PathFilterOptions): PathFilter;
+declare function filterTreeStructure<T extends UnicodeFileTreeNodeWithoutLastModified>(pathFilter: PathFilter, entries: T[], extraOptions?: Pick<PathFilterOptions, "include" | "exclude">): T[];
+//#endregion
+//#region src/glob.d.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 `.`)
+ */
+declare const DEFAULT_PICOMATCH_OPTIONS: PicomatchOptions;
+interface GlobMatchOptions {
+  /**
+   * Whether matching should be case-insensitive.
+   * @default true
+   */
+  nocase?: boolean;
+  /**
+   * Whether to match dotfiles.
+   * @default true
+   */
+  dot?: boolean;
+}
+declare function matchGlob(pattern: string, value: string, options?: GlobMatchOptions): boolean;
+type GlobMatchFn = (value: string) => boolean;
+declare function createGlobMatcher(pattern: string, options?: GlobMatchOptions): GlobMatchFn;
+interface GlobValidationLimits {
+  maxLength?: number;
+  maxSegments?: number;
+  maxBraceExpansions?: number;
+  maxStars?: number;
+  maxQuestions?: number;
+}
+declare function isValidGlobPattern(pattern: string, limits?: GlobValidationLimits): boolean;
+//#endregion
+//#region src/guards.d.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);
+ * }
+ * ```
+ */
+declare function isApiError(error: unknown): error is ApiError;
+//#endregion
+//#region src/json.d.ts
+/**
+ * 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
+ */
+declare function safeJsonParse<T>(content: string): T | null;
+//#endregion
+//#region src/ucd-config.d.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
+ */
+declare function discoverEndpointsFromConfig(baseUrl: string): Promise<UCDWellKnownConfig>;
+/**
+ * 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.
+ */
+declare function getDefaultUCDEndpointConfig(): UCDWellKnownConfig;
+//#endregion
+export { ConcurrencyLimitFn, DEFAULT_EXCLUDED_EXTENSIONS, DEFAULT_PICOMATCH_OPTIONS, type FetchOptions, type FetchResponse, type GlobMatchFn, type GlobMatchOptions, OperationFailure, OperationResult, OperationSuccess, PRECONFIGURED_FILTERS, type PathFilter, type PathFilterOptions, type SafeFetchResponse, createConcurrencyLimiter, createDebugger, createGlobMatcher, createPathFilter, customFetch, discoverEndpointsFromConfig, ensureIsPositiveConcurrency, filterTreeStructure, findFileByPath, flattenFilePaths, getDefaultUCDEndpointConfig, isApiError, isValidGlobPattern, matchGlob, normalizePathForFiltering, normalizeTreeForFiltering, safeJsonParse, tryOr, wrapTry };