tiny-essentials 1.28.18 → 1.29.0

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

@@ -0,0 +1,469 @@
+'use strict';
+
+var TinyUriParser = require('../TinyUriParser.cjs');
+
+/**
+ * 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.
+ */
+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.
+ */
+const MatrixSchemeParser = TinyUriParser.buildParserPair(
+  'matrix_scheme',
+  (uriString) => uriString.startsWith('matrix:'),
+  parseMatrixScheme,
+  reconstructMatrixScheme,
+);
+
+/**
+ * Handle Matrix ID shorthands (#room, !event, $event, @user)
+ */
+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/#/...)
+ */
+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.
+ */
+const MatrixProtocolParsers = Object.freeze([
+  MatrixMcxParser,
+  MatrixSchemeParser,
+  MatrixShortHandParser,
+  MatrixWebUrlParser,
+]);
+
+exports.MatrixMcxParser = MatrixMcxParser;
+exports.MatrixProtocolParsers = MatrixProtocolParsers;
+exports.MatrixSchemeParser = MatrixSchemeParser;
+exports.MatrixShortHandParser = MatrixShortHandParser;
+exports.MatrixWebUrlParser = MatrixWebUrlParser;

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

@@ -0,0 +1,80 @@
+export type IdTypes = 'roomId' | 'room' | 'user';
+export type MXCData = {
+    /**
+     * - The category of the data.
+     */
+    dataType: 'mxc';
+    /**
+     * - The Matrix server domain (e.g., 'matrix.org').
+     */
+    server: string;
+    /**
+     * - The unique identifier for the data.
+     */
+    dataId: string;
+};
+export type MatrixSchemeData = {
+    /**
+     * - The category of the data.
+     */
+    dataType: 'matrix_scheme';
+    /**
+     * - The type of the matrix resource.
+     */
+    type: IdTypes | 'event';
+    /**
+     * - The sub type of the matrix resource.
+     */
+    subType: null | IdTypes;
+    /**
+     * - The primary identifier (room ID or user ID).
+     */
+    resourceId: string;
+    /**
+     * - The specific event ID (only if type is 'event').
+     */
+    eventId?: string;
+    /**
+     * - The matrix server domain.
+     */
+    server: string | null;
+    /**
+     * - Key-value pairs of query parameters (e.g., { via: 'server.com' }).
+     */
+    params: Record<string, string>;
+};
+export type MatrixWebData = {
+    /**
+     * - The category of the data.
+     */
+    dataType: 'matrix_web_url';
+    /**
+     * - The decoded string from the URL fragment.
+     */
+    decodedFragment: string;
+    /**
+     * - The result of the parsed resource.
+     */
+    parsed: MatrixSchemeData | MXCData;
+};
+/**
+ * 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 declare const MatrixMcxParser: import("../TinyUriParser.mjs").ParserPair<"mxc", MXCData>;
+/**
+ * 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 declare const MatrixSchemeParser: import("../TinyUriParser.mjs").ParserPair<"matrix_scheme", MatrixSchemeData>;
+/**
+ * Handle Matrix ID shorthands (#room, !event, $event, @user)
+ */
+export declare const MatrixShortHandParser: import("../TinyUriParser.mjs").ParserPair<"matrix_shorthand", MatrixSchemeData>;
+/**
+ * Check for Web URLs (e.g., https://matrix.to/#/...)
+ */
+export declare const MatrixWebUrlParser: import("../TinyUriParser.mjs").ParserPair<"matrix_web_url", MatrixWebData>;
+/**
+ * An array of Matrix Protocol parser pairs, where each pair contains a matching predicate and a parsing callback.
+ */
+export declare const MatrixProtocolParsers: readonly (import("../TinyUriParser.mjs").ParserPair<"matrix_scheme", MatrixSchemeData> | import("../TinyUriParser.mjs").ParserPair<"matrix_shorthand", MatrixSchemeData> | import("../TinyUriParser.mjs").ParserPair<"matrix_web_url", MatrixWebData> | import("../TinyUriParser.mjs").ParserPair<"mxc", MXCData>)[];
+//# sourceMappingURL=MatrixProtocol.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MatrixProtocol.d.mts","sourceRoot":"","sources":["../../../../../src/v1/libs/tools/TinyUriParser/MatrixProtocol.mjs"],"names":[],"mappings":"AASG,YAAsC,OAAO,GAAnC,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAS;AAK7C,YAAkB,OAAO,GACzB;;;;IAAkB,QAAQ,EAAf,KAAK,CAChB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACnB;CAAA,CAAA;AAIE,YAAkB,gBAAgB,GAClC;;;;IAA4B,QAAQ,EAAzB,eAAe,CAC1B;;;;IAA8B,IAAI,EAAvB,OAAO,GAAG,OAAO,CAC5B;;;;IAAyB,OAAO,EAArB,IAAI,GAAC,OAAO,CACvB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAoB,OAAO,AAA3B,CACA,EADW,MAAM,CACjB;;;;IAAwB,MAAM,EAAnB,MAAM,GAAC,IAAI,CACtB;;;;IAAmC,MAAM,EAA9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CACnC;CAAA,CAAA;AAIE,YAAkB,aAAa,GAC/B;;;;IAA6B,QAAQ,EAA1B,gBAAgB,CAC3B;;;;IAAmB,eAAe,EAAvB,MAAM,CACjB;;;;IAAuC,MAAM,EAAlC,gBAAgB,GAAG,OAAO,CACvC;CAAA,CAAA;AA2WD;;GAEG;AACH,eAAO,MAAM,eAAe,2DAK3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,8EAK9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,iFAgBjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,4EAK9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,sTAKhC,CAAC"}