tiny-essentials 1.28.18 → 1.29.0

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

@@ -0,0 +1,379 @@
+import TinyUriParser from '../TinyUriParser.mjs';
+/**
+ * Matrix Protocol (matrix.org)
+ * Official Documentation: https://spec.matrix.org/latest/appendices/#identifier-grammar
+ */
+/**
+ * Defines the valid types for Matrix resource identifiers.
+ * @typedef {'roomId' | 'room' | 'user'} IdTypes
+ */
+/**
+ * Represents the data structure for parsed Matrix Content (MXC) URIs.
+ * @typedef {Object} MXCData
+ * @property {'mxc'} dataType - The category of the data.
+ * @property {string} server - The Matrix server domain (e.g., 'matrix.org').
+ * @property {string} dataId - The unique identifier for the data.
+ */
+/**
+ * Represents the data structure for parsed Matrix scheme URIs.
+ * @typedef {Object} MatrixSchemeData
+ * @property {'matrix_scheme'} dataType - The category of the data.
+ * @property {IdTypes | 'event'} type - The type of the matrix resource.
+ * @property {null|IdTypes} subType - The sub type of the matrix resource.
+ * @property {string} resourceId - The primary identifier (room ID or user ID).
+ * @property {string} [eventId] - The specific event ID (only if type is 'event').
+ * @property {string|null} server - The matrix server domain.
+ * @property {Record<string, string>} params - Key-value pairs of query parameters (e.g., { via: 'server.com' }).
+ */
+/**
+ * Represents the data structure for parsed Matrix Web URLs.
+ * @typedef {Object} MatrixWebData
+ * @property {'matrix_web_url'} dataType - The category of the data.
+ * @property {string} decodedFragment - The decoded string from the URL fragment.
+ * @property {MatrixSchemeData | MXCData} parsed - The result of the parsed resource.
+ */
+/**
+ * Regular expression used to match and extract components from an MXC (Matrix Content) URI.
+ * @type {RegExp}
+ */
+const parseMxcRegex = /^mxc:\/\/([^/]+)\/(.+)$/;
+/**
+ * Regex handles: matrix:<type>/<resource>[/e/<event>][<query>]
+ *
+ * Types supported: r (room), u (user), roomid (room), e (event)
+ * @type {RegExp}
+ */
+const matrixSchemeRegex = /^matrix:(?<prefix>r|u|roomid|e)\/(?<resource>[^?/\s]+)(?:\/e\/(?<event>[^?/\s]+))?(?<query>\?.*)?$/;
+/**
+ * Reconstructs a Matrix ID shorthand from MatrixSchemeData.
+ *
+ * This function reconstructs the shorthand and includes any provided query parameters.
+ *
+ * @param {MatrixSchemeData} parsed - The parsed Matrix scheme data object.
+ * @returns {string} The Matrix ID shorthand (e.g., '#room:server.com', '@user:server.com', '$eventid').
+ * @throws {TypeError} If the provided data is invalid or the type is unsupported.
+ */
+const reconstructMatrixShorthand = (parsed) => {
+    // Validate the input object using the existing validation logic
+    validateMatrixSchemeData(parsed);
+    const typeToPrefix = {
+        room: '#',
+        roomId: '!',
+        user: '@',
+        event: '$',
+    };
+    const prefix = typeToPrefix[parsed.type];
+    if (!prefix) {
+        throw new TypeError(`reconstructMatrixShorthand: Unsupported type "${parsed.type}".`);
+    }
+    // Start with the resource ID (e.g., the room ID or user ID)
+    let resource = parsed.resourceId;
+    // If a server is present, append it to the resource (e.g., 'room_id:matrix.org')
+    if (parsed.server) {
+        resource += `:${parsed.server}`;
+    }
+    let result = `${prefix}${resource}`;
+    // Append query parameters if the params object is not empty
+    if (parsed.params && Object.keys(parsed.params).length > 0) {
+        const query = new URLSearchParams(parsed.params).toString();
+        result += `?${query}`;
+    }
+    return result;
+};
+/**
+ * Reconstructs an MXC URI from parsed data.
+ * @param {MXCData} parsed
+ * @returns {string}
+ */
+const reconstructMxc = (parsed) => {
+    const { server, dataId } = parsed;
+    return `mxc://${server}/${dataId}`;
+};
+/**
+ * Reconstructs a Matrix Scheme URI from parsed data.
+ * @param {MatrixSchemeData} parsed
+ * @returns {string}
+ */
+const reconstructMatrixScheme = (parsed) => {
+    const { type, subType, resourceId, eventId, server, params } = parsed;
+    const typeToPrefix = { room: 'r', user: 'u', roomId: 'roomid', event: 'e' };
+    const subTypeToPrefix = { room: 'r', user: 'u', roomId: 'roomid' };
+    // Determine the prefix based on the type or the subType if it's an event
+    // @ts-ignore
+    let prefix = typeToPrefix[type];
+    if (type === 'event' && subType) {
+        // @ts-ignore
+        prefix = subTypeToPrefix[subType];
+    }
+    let resource = resourceId;
+    if (server) {
+        resource += `:${server}`;
+    }
+    let result = `matrix:${prefix}/${resource}`;
+    if (type === 'event' && eventId) {
+        let eventPart = eventId;
+        // if (server) eventPart += `:${server}`;
+        result += `/e/${eventPart}`;
+    }
+    if (params && Object.keys(params).length > 0) {
+        const query = new URLSearchParams(params).toString();
+        result += `?${query}`;
+    }
+    return result;
+};
+/**
+ * Rebuilds the `matrix.to` fragment for a parsed Matrix scheme resource.
+ * @param {MatrixSchemeData} parsed - The parsed Matrix scheme data.
+ * @returns {string} The `matrix.to` fragment (e.g., `#room:server.com`).
+ * @throws {TypeError} If the resource type is unsupported.
+ */
+const buildMatrixToFragment = (parsed) => {
+    const baseType = parsed.type === 'event' ? parsed.subType : parsed.type;
+    const prefixMap = { room: '#', roomId: '!', user: '@' };
+    // @ts-ignore
+    const prefix = prefixMap[baseType];
+    if (!prefix) {
+        throw new TypeError(`MatrixWebData: unsupported resource type "${baseType}".`);
+    }
+    let fragment = `${prefix}${parsed.resourceId}`;
+    if (parsed.server) {
+        fragment += `:${parsed.server}`;
+    }
+    if (parsed.type === 'event' && parsed.eventId) {
+        fragment += `/${parsed.eventId.startsWith('$') ? parsed.eventId : `$${parsed.eventId}`}`;
+    }
+    return fragment;
+};
+/**
+ * Reconstructs a Matrix Web URL from parsed data.
+ *
+ * The URL is rebuilt from the structured `parsed` payload, so the object does
+ * not need to keep a redundant copy of the original string in memory.
+ *
+ * @param {MatrixWebData} data - The parsed web URL data.
+ * @returns {string} The reconstructed Matrix Web URL.
+ * @throws {TypeError} If the data is malformed.
+ */
+const reconstructMatrixWebUrl = (data) => {
+    if (data === null || typeof data !== 'object') {
+        throw new TypeError('MatrixWebData: data must be an object.');
+    }
+    const { parsed } = data;
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new TypeError('MatrixWebData: parsed must be an object.');
+    }
+    if (parsed.dataType === 'mxc') {
+        return `https://matrix.to/#/${reconstructMxc(parsed)}`;
+    }
+    const query = parsed.params && Object.keys(parsed.params).length > 0
+        ? `?${new URLSearchParams(parsed.params)}`
+        : '';
+    return `https://matrix.to/#/${buildMatrixToFragment(parsed)}${query}`;
+};
+/**
+ * Parses MXC (Matrix Content) URIs.
+ *
+ * @param {string} uri - The raw MXC URI string.
+ * @returns {MXCData} The parsed MXC data object.
+ * @throws {Error} If the URI does not match the expected MXC format.
+ */
+const parseMxc = (uri) => {
+    const match = uri.match(parseMxcRegex);
+    if (!match) {
+        throw new Error(`Invalid MXC URI format: ${uri}`);
+    }
+    const [_, server, dataId] = match;
+    /** @type {MXCData} */
+    const data = { server, dataId, dataType: 'mxc' };
+    validateMXCData(data);
+    return data;
+};
+/**
+ * Parses Matrix Scheme URIs (e.g., matrix:r/..., matrix:u/..., matrix:e/..., etc).
+ *
+ * @param {string} uri - The Matrix scheme URI string.
+ * @returns {MatrixSchemeData} The parsed Matrix scheme data object.
+ * @throws {Error} If the URI does not match the expected Matrix scheme format.
+ */
+const parseMatrixScheme = (uri) => {
+    const match = uri.match(matrixSchemeRegex);
+    if (!match) {
+        throw new Error(`Invalid Matrix Scheme URI: ${uri}`);
+    }
+    const { prefix, resource, event, query } = match.groups ?? {};
+    const prefixType = prefix === 'r' ? '#' : prefix === 'e' ? '$' : prefix === 'roomid' ? '!' : '@';
+    /** @param {string} p */
+    const genType = (p) => p === 'r' ? 'room' : p === 'e' ? 'event' : p === 'roomid' ? 'roomId' : 'user';
+    // Capture the original type (room, user, etc.) before checking if it is an event
+    const baseType = genType(prefix);
+    /** @type {MatrixSchemeData} */
+    const data = {
+        dataType: 'matrix_scheme',
+        subType: null,
+        type: baseType,
+        resourceId: resource,
+        server: null,
+        params: {},
+    };
+    // Transforms the query string into a key/value object
+    if (query) {
+        const searchParams = new URLSearchParams(query);
+        data.params = Object.fromEntries(searchParams.entries());
+    }
+    // Always remove the identifier symbol if it is present, regardless of the server
+    let actualResource = resource;
+    if (actualResource.startsWith(prefixType)) {
+        actualResource = actualResource.substring(1);
+    }
+    // Handles the extraction of resourceId, server and all types
+    const lastColonIndex = actualResource.lastIndexOf(':');
+    if (lastColonIndex !== -1) {
+        data.server = actualResource.substring(lastColonIndex + 1);
+        data.resourceId = actualResource.substring(0, lastColonIndex);
+    }
+    else {
+        data.resourceId = actualResource;
+    }
+    if (prefix === 'e') {
+        // Since the resourceId has already been cleaned in the block above, simply reference it
+        data.eventId = data.resourceId;
+        data.type = 'event';
+        data.subType = null;
+    }
+    // If the URI contains a nested event (matrix:r/room/e/event)
+    if (event) {
+        let actualEvent = event;
+        if (actualEvent.startsWith('$')) {
+            actualEvent = actualEvent.substring(1);
+        }
+        // Ensures that the nested eventId is also cleaned, in case it has an associated server
+        const eventColonIndex = actualEvent.lastIndexOf(':');
+        if (eventColonIndex !== -1) {
+            data.eventId = actualEvent.substring(0, eventColonIndex);
+        }
+        else {
+            data.eventId = actualEvent;
+        }
+        data.type = 'event';
+        data.subType = baseType !== 'event' ? baseType : null;
+    }
+    validateMatrixSchemeData(data);
+    return data;
+};
+/**
+ * Parses Matrix Web URLs by decoding the URL fragment.
+ *
+ * @param {string} url - The full web URL (e.g., https://matrix.to/#/...).
+ * @returns {MatrixWebData} The parsed web URL data object.
+ * @throws {Error} If the URL is invalid or the fragment cannot be parsed.
+ */
+const parseWebUrl = (url) => {
+    const urlObj = new URL(url);
+    const fragment = urlObj.hash.substring(2); // Remove '#/'
+    const decodedFragment = decodeURIComponent(fragment);
+    // Split into parts to support events contained within the matrix.to URL
+    // Ex: !room:server.com/$event_id -> mainPart: "!room:server.com", eventPart: "$event_id"
+    const parts = decodedFragment.split('/');
+    const mainPart = parts[0];
+    const eventPart = parts.length > 1 ? parts[1] : null;
+    let parsedResource;
+    if (mainPart.startsWith('#') || mainPart.startsWith('!')) {
+        const isId = mainPart.startsWith('!');
+        const type = !isId ? 'r' : 'roomid';
+        // Always construct by removing the initial symbol (!) or (#)
+        let normalizedResource = `matrix:${type}/${mainPart.substring(1)}`;
+        if (eventPart) {
+            // Remove the '$' if it exists to properly construct the scheme route
+            const safeEventPart = eventPart.startsWith('$') ? eventPart.substring(1) : eventPart;
+            normalizedResource += `/e/${safeEventPart}`;
+        }
+        parsedResource = parseMatrixScheme(normalizedResource);
+    }
+    else if (mainPart.startsWith('@')) {
+        // It's a user
+        const normalizedResource = `matrix:u/${mainPart.substring(1)}`;
+        parsedResource = parseMatrixScheme(normalizedResource);
+    }
+    else {
+        // Fallback: treat decoded fragment as a direct matrix scheme
+        parsedResource = parseMatrixScheme(`matrix:${decodedFragment}`);
+    }
+    return {
+        dataType: 'matrix_web_url',
+        decodedFragment,
+        parsed: parsedResource,
+    };
+};
+/**
+ * Validates the MXC data object for required properties and correct types.
+ *
+ * @param {MXCData} data - The MXC data object to validate.
+ * @throws {TypeError} If any property is missing or of an invalid type.
+ */
+const validateMXCData = (data) => {
+    if (typeof data.server !== 'string' || data.server.length === 0) {
+        throw new TypeError('MXCData: server must be a non-empty string.');
+    }
+    if (typeof data.dataId !== 'string' || data.dataId.length === 0) {
+        throw new TypeError('MXCData: dataId must be a non-empty string.');
+    }
+};
+/**
+ * Validates the Matrix Scheme data object for required properties and correct types.
+ *
+ * @param {MatrixSchemeData} data - The Matrix scheme data object to validate.
+ * @throws {TypeError} If any property is missing or of an invalid type.
+ */
+const validateMatrixSchemeData = (data) => {
+    const validTypes = ['roomId', 'room', 'user', 'event'];
+    if (!validTypes.includes(data.type)) {
+        throw new TypeError(`MatrixSchemeData: Invalid type "${data.type}".`);
+    }
+    if (typeof data.resourceId !== 'string' || data.resourceId.length === 0) {
+        throw new TypeError('MatrixSchemeData: resourceId must be a non-empty string.');
+    }
+    if (data.server !== null && (typeof data.server !== 'string' || data.server.length === 0)) {
+        throw new TypeError('MatrixSchemeData: server must be a non-empty string.');
+    }
+    if (data.type === 'event' && (typeof data.eventId !== 'string' || data.eventId.length === 0)) {
+        throw new TypeError('MatrixSchemeData: eventId must be a non-empty string when type is "event".');
+    }
+    if (data.params && typeof data.params !== 'object') {
+        throw new TypeError('MatrixSchemeData: params must be an object.');
+    }
+};
+/**
+ * A parser pair for MXC (Matrix Content) URIs, consisting of a predicate to check for the 'mxc://' prefix and a callback to parse the URI.
+ */
+export const MatrixMcxParser = TinyUriParser.buildParserPair('mxc', (uriString) => uriString.startsWith('mxc://'), parseMxc, reconstructMxc);
+/**
+ * A parser pair for Matrix scheme URIs, consisting of a predicate to check for the 'matrix:' prefix and a callback to parse the URI.
+ */
+export const MatrixSchemeParser = TinyUriParser.buildParserPair('matrix_scheme', (uriString) => uriString.startsWith('matrix:'), parseMatrixScheme, reconstructMatrixScheme);
+/**
+ * Handle Matrix ID shorthands (#room, !event, $event, @user)
+ */
+export const MatrixShortHandParser = TinyUriParser.buildParserPair('matrix_shorthand', (uriString) => uriString.startsWith('#') ||
+    uriString.startsWith('!') ||
+    uriString.startsWith('$') ||
+    uriString.startsWith('@'), (uriString) => {
+    const prefixMap = { '#': 'r/', '!': 'roomid/', $: 'e/', '@': 'u/' };
+    // @ts-ignore
+    const prefix = prefixMap[uriString[0]];
+    if (!prefix)
+        throw new Error(`Unable to determine the protocol for the provided URI: ${uriString}`);
+    return parseMatrixScheme(`matrix:${prefix}${uriString.substring(1)}`);
+}, reconstructMatrixShorthand);
+/**
+ * Check for Web URLs (e.g., https://matrix.to/#/...)
+ */
+export const MatrixWebUrlParser = TinyUriParser.buildParserPair('matrix_web_url', (uriString) => uriString.includes('://') && uriString.includes('#/'), parseWebUrl, reconstructMatrixWebUrl);
+/**
+ * An array of Matrix Protocol parser pairs, where each pair contains a matching predicate and a parsing callback.
+ */
+export const MatrixProtocolParsers = Object.freeze([
+    MatrixMcxParser,
+    MatrixSchemeParser,
+    MatrixShortHandParser,
+    MatrixWebUrlParser,
+]);

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

@@ -0,0 +1,217 @@
+'use strict';
+
+var tools = require('../utils/tools.cjs');
+var objChecker = require('../../basics/objChecker.cjs');
+
+const checkDestroy = tools.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 (!objChecker.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;
+  }
+}
+
+module.exports = TinyUriParser;