tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/tools/TinyUriParser.d.mts

@@ -0,0 +1,109 @@
+export type ParsedData = Record<any, any>;
+export type ParsedUri<Type extends string, Data extends ParsedData> = {
+    /**
+     * - The category of the URI.
+     */
+    type: Type;
+    /**
+     * - The parsed content.
+     */
+    data: Data;
+};
+export type ParseChecker = (uri: string) => boolean;
+export type ParserCallback<Type extends string, Data extends ParsedData> = (uri: string) => ParsedUri<Type, Data>;
+export type StringifyCallback<Type extends string, Data extends ParsedData> = (parsed: Data) => string;
+export type ParserPair<Type extends string, Data extends ParsedData> = readonly [Type, ParseChecker, ParserCallback<Type, Data>, StringifyCallback<Type, Data>];
+/**
+ * A generic template for parsed URI results.
+ * @typedef {Record<any, any>} ParsedData
+ */
+/**
+ * A generic template for parsed URI results.
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {Object} ParsedUri
+ * @property {Type} type - The category of the URI.
+ * @property {Data} data - The parsed content.
+ */
+/**
+ * A function type used to validate whether a provided URI string matches a specific pattern or protocol.
+ * @typedef {(uri: string) => boolean} ParseChecker
+ */
+/**
+ * A function type that accepts a URI string and returns a structured `ParsedUri` object.
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {(uri: string) => ParsedUri<Type, Data>} ParserCallback
+ */
+/**
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {(parsed: Data) => string} StringifyCallback
+ */
+/**
+ * A tuple representing a single parsing unit, consisting of a validation function,
+ * its corresponding parsing function, and an reconstruction function.
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {readonly [Type, ParseChecker, ParserCallback<Type, Data>, StringifyCallback<Type, Data>]} ParserPair
+ */
+/**
+ * A utility class designed to parse various Matrix-related URI formats into structured objects.
+ * @template {ParserPair<any, any>} Parser
+ */
+declare class TinyUriParser<Parser extends ParserPair<any, any>> {
+    #private;
+    /**
+     * Creates a frozen, immutable tuple containing the type, validation condition, parsing function, and stringification function for a specific URI type.
+     * @template {string} Type
+     * @template {ParsedData} Data
+     * @param {Type} type - The unique string identifier representing the URI category.
+     * @param {ParseChecker} conditions - A validation function that returns `true` if the URI matches the specific pattern.
+     * @param {(uri: string) => Data} parser - A function that extracts and returns the parsed data from the URI string.
+     * @param {StringifyCallback<Type, Data>} stringify - A function used to convert the parsed data back into a URI string.
+     * @returns {ParserPair<Type, Data>} An immutable tuple containing the type, validation checker, parser, and stringifier.
+     */
+    static buildParserPair<Type extends string, Data extends ParsedData>(type: Type, conditions: ParseChecker, parser: (uri: string) => Data, stringify: StringifyCallback<Type, Data>): ParserPair<Type, Data>;
+    /**
+     * Indicates whether this instance has been destroyed.
+     * @type {boolean}
+     */
+    get isDestroyed(): boolean;
+    /**
+     * Returns an array containing shallow copies of the registered parser pairs to prevent direct mutation of the internal set.
+     * @type {Parser[]}
+     */
+    get parsers(): Parser[];
+    /**
+     * Returns the total number of registered parser pairs.
+     * @type {number}
+     */
+    get size(): number;
+    /**
+     * Initializes the TinyUriParser instance with a collection of parser pairs.
+     * @param {...Parser} parsers
+     * @throws {TypeError} If any provided parser is not a valid ParserPair.
+     */
+    constructor(...parsers: Parser[]);
+    /**
+     * Main entry point for parsing.
+     * @param {string} uriString - The raw URI string to parse.
+     * @returns {ReturnType<Parser[2]>} The parsed object.
+     * @throws {TypeError | RangeError | Error} If the input is invalid or parsing fails.
+     */
+    parse(uriString: string): ReturnType<Parser[2]>;
+    /**
+     * Reconstructs the original URI string from a parsed object.
+     * @param {ReturnType<Parser[2]>} parsedObject - The object returned by the parse method.
+     * @returns {string} The reconstructed URI string.
+     * @throws {TypeError | Error} If the object is invalid or no reconstructor is found.
+     */
+    stringify(parsedObject: ReturnType<Parser[2]>): string;
+    /**
+     * Cleans up internal parsers and marks the instance as destroyed to prevent memory leaks.
+     * @returns {void}
+     */
+    destroy(): void;
+}
+export default TinyUriParser;
+//# sourceMappingURL=TinyUriParser.d.mts.map

package/dist/v1/libs/tools/TinyUriParser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyUriParser.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/tools/TinyUriParser.mjs"],"names":[],"mappings":"AAOG,YAA4B,UAAU,GAA5B,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAY;AAOtC,YAAkB,SAAS,CAFR,IAAI,SAAZ,MAAY,EACA,IAAI,SAAhB,UAAgB,IAE3B;;;;IAAiB,IAAI,EAAV,IAAI,CACf;;;;IAAiB,IAAI,EAAV,IAAI,CACjB;CAAA,CAAA;AAIE,YAAoC,YAAY,GAAtC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAc;AAOhD,YAAkD,cAAc,CAF7C,IAAI,SAAZ,MAAY,EACA,IAAI,SAAhB,UAAgB,IACjB,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAgB;AAMhE,YAAoC,iBAAiB,CAFlC,IAAI,SAAZ,MAAY,EACA,IAAI,SAAhB,UAAgB,IACjB,CAAC,MAAM,EAAE,IAAI,KAAK,MAAM,CAAmB;AAQrD,YAAoG,UAAU,CAF3F,IAAI,SAAZ,MAAY,EACA,IAAI,SAAhB,UAAgB,IACjB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAY;AArCjH;;;GAGG;AAEH;;;;;;;GAOG;AAEH;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AACH,cAAM,aAAa,CAFiB,MAAM,SAA5B,UAAU,CAAC,GAAG,EAAE,GAAG,CAAS;;IAGxC;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,CARA,IAAI,SAAZ,MAAY,EACA,IAAI,SAAhB,UAAgB,EAOP,IAAI,EANhB,IAMgB,EAAE,UAAU,EAL5B,YAK4B,EAAE,MAAM,EAJpC,CAAC,GAAG,EAAE,MAAM,KAAK,IAImB,EAAE,SAAS,EAH/C,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAGmB,GAF7C,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAYlC;IAQD;;;OAGG;IACH,IAAI,WAAW,IAFL,OAAO,CAIhB;IAQD;;;OAGG;IACH,IAAI,OAAO,IAFD,MAAM,EAAE,CAMjB;IAED;;;OAGG;IACH,IAAI,IAAI,IAFE,MAAM,CAKf;IAED;;;;OAIG;IACH,YAAY,GAAG,OAAO,EAHR,MAAM,EAGE,EA0CrB;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAJJ,MAII,GAHF,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAajC;IAED;;;;;OAKG;IACH,SAAS,CAAC,YAAY,EAJX,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAIT,GAHT,MAAM,CAoBlB;IAED;;;OAGG;IACH,OAAO,IAFM,IAAI,CAMhB;CACF;eAEc,aAAa"}

package/dist/v1/libs/tools/TinyUriParser.mjs

@@ -0,0 +1,183 @@
+import { createCheckDestroyed } from '../utils/tools.mjs';
+import { isJsonObject } from '../../basics/objChecker.mjs';
+const checkDestroy = createCheckDestroyed('TinyUriParser');
+/**
+ * A generic template for parsed URI results.
+ * @typedef {Record<any, any>} ParsedData
+ */
+/**
+ * A generic template for parsed URI results.
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {Object} ParsedUri
+ * @property {Type} type - The category of the URI.
+ * @property {Data} data - The parsed content.
+ */
+/**
+ * A function type used to validate whether a provided URI string matches a specific pattern or protocol.
+ * @typedef {(uri: string) => boolean} ParseChecker
+ */
+/**
+ * A function type that accepts a URI string and returns a structured `ParsedUri` object.
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {(uri: string) => ParsedUri<Type, Data>} ParserCallback
+ */
+/**
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {(parsed: Data) => string} StringifyCallback
+ */
+/**
+ * A tuple representing a single parsing unit, consisting of a validation function,
+ * its corresponding parsing function, and an reconstruction function.
+ * @template {string} Type
+ * @template {ParsedData} Data
+ * @typedef {readonly [Type, ParseChecker, ParserCallback<Type, Data>, StringifyCallback<Type, Data>]} ParserPair
+ */
+/**
+ * A utility class designed to parse various Matrix-related URI formats into structured objects.
+ * @template {ParserPair<any, any>} Parser
+ */
+class TinyUriParser {
+    /**
+     * Creates a frozen, immutable tuple containing the type, validation condition, parsing function, and stringification function for a specific URI type.
+     * @template {string} Type
+     * @template {ParsedData} Data
+     * @param {Type} type - The unique string identifier representing the URI category.
+     * @param {ParseChecker} conditions - A validation function that returns `true` if the URI matches the specific pattern.
+     * @param {(uri: string) => Data} parser - A function that extracts and returns the parsed data from the URI string.
+     * @param {StringifyCallback<Type, Data>} stringify - A function used to convert the parsed data back into a URI string.
+     * @returns {ParserPair<Type, Data>} An immutable tuple containing the type, validation checker, parser, and stringifier.
+     */
+    static buildParserPair(type, conditions, parser, stringify) {
+        return Object.freeze([
+            type,
+            conditions,
+            (uriString) => ({
+                type: type,
+                data: parser(uriString),
+            }),
+            stringify,
+        ]);
+    }
+    /**
+     * Whether this instance has been destroyed.
+     * @type {boolean}
+     */
+    #isDestroyed = false;
+    /**
+     * Indicates whether this instance has been destroyed.
+     * @type {boolean}
+     */
+    get isDestroyed() {
+        return this.#isDestroyed;
+    }
+    /**
+     * A collection of parser pairs used to iterate through and match URI strings.
+     * @type {Set<Parser>}
+     */
+    #parsers;
+    /**
+     * Returns an array containing shallow copies of the registered parser pairs to prevent direct mutation of the internal set.
+     * @type {Parser[]}
+     */
+    get parsers() {
+        checkDestroy(this.#isDestroyed);
+        /** @type {Parser[]} */
+        return Array.from(this.#parsers).map((parserPair) => [...parserPair]);
+    }
+    /**
+     * Returns the total number of registered parser pairs.
+     * @type {number}
+     */
+    get size() {
+        checkDestroy(this.#isDestroyed);
+        return this.#parsers.size;
+    }
+    /**
+     * Initializes the TinyUriParser instance with a collection of parser pairs.
+     * @param {...Parser} parsers
+     * @throws {TypeError} If any provided parser is not a valid ParserPair.
+     */
+    constructor(...parsers) {
+        for (const [index, parser] of parsers.entries()) {
+            // 1. Check if the argument is an array (the base of a tuple/ParserPair)
+            if (!Array.isArray(parser)) {
+                throw new TypeError(`Parser at index ${index} must be an array representing a ParserPair.`);
+            }
+            // 2. Check if the array has exactly four elements [Type, ParseChecker, ParserCallback, StringifyCallback]
+            if (parser.length !== 4) {
+                throw new TypeError(`Parser at index ${index} must contain exactly 4 elements.`);
+            }
+            // 3. Validate that the first element is a string (Type)
+            if (typeof parser[0] !== 'string') {
+                throw new TypeError(`The first element of the parser at index ${index} must be a string (Type).`);
+            }
+            // 4. Validate that the second element is a function (ParseChecker)
+            if (typeof parser[1] !== 'function') {
+                throw new TypeError(`The second element of the parser at index ${index} must be a function (ParseChecker).`);
+            }
+            // 5. Validate that the third element is a function (ParserCallback)
+            if (typeof parser[2] !== 'function') {
+                throw new TypeError(`The third element of the parser at index ${index} must be a function (ParserCallback).`);
+            }
+            // 6. Validate that the fourth element is a function (StringifyCallback)
+            if (typeof parser[3] !== 'function') {
+                throw new TypeError(`The fourth element of the parser at index ${index} must be a function (StringifyCallback).`);
+            }
+        }
+        this.#parsers = new Set(parsers);
+    }
+    /**
+     * Main entry point for parsing.
+     * @param {string} uriString - The raw URI string to parse.
+     * @returns {ReturnType<Parser[2]>} The parsed object.
+     * @throws {TypeError | RangeError | Error} If the input is invalid or parsing fails.
+     */
+    parse(uriString) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof uriString !== 'string') {
+            throw new TypeError('The input must be a string.');
+        }
+        for (const parser of this.#parsers) {
+            // @ts-ignore
+            if (parser[1](uriString))
+                return parser[2](uriString);
+        }
+        throw new Error(`Unable to determine the protocol for the provided URI: ${uriString}`);
+    }
+    /**
+     * Reconstructs the original URI string from a parsed object.
+     * @param {ReturnType<Parser[2]>} parsedObject - The object returned by the parse method.
+     * @returns {string} The reconstructed URI string.
+     * @throws {TypeError | Error} If the object is invalid or no reconstructor is found.
+     */
+    stringify(parsedObject) {
+        checkDestroy(this.#isDestroyed);
+        if (!isJsonObject(parsedObject) || typeof parsedObject.type !== 'string') {
+            throw new TypeError('The input must be a valid ParsedUri object with a "type" property.');
+        }
+        for (const parser of this.#parsers) {
+            const [type, , , reconstructor] = parser;
+            if (type === parsedObject.type && typeof reconstructor === 'function') {
+                const result = reconstructor(parsedObject.data);
+                if (typeof result === 'string') {
+                    return result;
+                }
+            }
+        }
+        throw new Error(`No reconstructor found for the parsed type: ${parsedObject.type}`);
+    }
+    /**
+     * Cleans up internal parsers and marks the instance as destroyed to prevent memory leaks.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#isDestroyed)
+            return;
+        this.#parsers.clear();
+        this.#isDestroyed = true;
+    }
+}
+export default TinyUriParser;