@orion-js/helpers 4.0.0-next.0 → 4.0.0-next.2

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/sleep.ts","../src/hashObject.ts","../src/generateId.ts","../src/createMap.ts","../src/createMapArray.ts","../src/Errors/OrionError.ts","../src/Errors/PermissionsError.ts","../src/Errors/UserError.ts","../src/Errors/index.ts","../src/composeMiddlewares.ts","../src/retries.ts","../../../node_modules/uuid/dist/esm-node/rng.js","../../../node_modules/uuid/dist/esm-node/regex.js","../../../node_modules/uuid/dist/esm-node/validate.js","../../../node_modules/uuid/dist/esm-node/stringify.js","../../../node_modules/uuid/dist/esm-node/v4.js","../src/generateUUID.ts","../src/normalize.ts","../src/searchTokens.ts","../src/shortenMongoId.ts"],"sourcesContent":["import sleep from './sleep'\nimport hashObject from './hashObject'\nimport generateId from './generateId'\nimport createMap from './createMap'\nimport createMapArray from './createMapArray'\n\n// Import all error-related exports from the Errors module\nimport {\n  OrionError,\n  PermissionsError,\n  UserError,\n  isOrionError,\n  isUserError,\n  isPermissionsError\n} from './Errors'\nimport type {OrionErrorInformation} from './Errors'\n\nexport * from './composeMiddlewares'\nexport * from './retries'\nexport * from './generateUUID'\nexport * from './normalize'\nexport * from './searchTokens'\nexport * from './shortenMongoId'\nexport {\n  // Utility functions\n  createMap,\n  createMapArray,\n  generateId,\n  hashObject,\n  sleep,\n\n  // Error classes\n  OrionError,\n  PermissionsError,\n  UserError,\n\n  // Error type guards\n  isOrionError,\n  isUserError,\n  isPermissionsError\n}\n\nexport type {OrionErrorInformation}\n","/**\n * Creates a timeout with a promise\n */\nexport default (time: number): Promise<void> => {\n  return new Promise(resolve => setTimeout(resolve, time))\n}\n","import hash from 'object-hash'\n\nexport default function (object: any): string {\n  return hash(object)\n}\n","import crypto from 'crypto'\n\nconst UNMISTAKABLE_CHARS = '23456789ABCDEFGHJKLMNPQRSTWXYZabcdefghjkmnopqrstuvwxyz'\n\nconst hexString = function (digits) {\n  var numBytes = Math.ceil(digits / 2)\n  var bytes\n  // Try to get cryptographically strong randomness. Fall back to\n  // non-cryptographically strong if not available.\n  try {\n    bytes = crypto.randomBytes(numBytes)\n  } catch (e) {\n    // XXX should re-throw any error except insufficient entropy\n    bytes = crypto.pseudoRandomBytes(numBytes)\n  }\n  var result = bytes.toString('hex')\n  // If the number of digits is odd, we'll have generated an extra 4 bits\n  // of randomness, so we need to trim the last digit.\n  return result.substring(0, digits)\n}\n\nconst fraction = function () {\n  var numerator = parseInt(hexString(8), 16)\n  return numerator * 2.3283064365386963e-10 // 2^-32\n}\n\nconst choice = function (arrayOrString) {\n  var index = Math.floor(fraction() * arrayOrString.length)\n  if (typeof arrayOrString === 'string') return arrayOrString.substr(index, 1)\n  else return arrayOrString[index]\n}\n\nconst randomString = function (charsCount, alphabet) {\n  var digits = []\n  for (var i = 0; i < charsCount; i++) {\n    digits[i] = choice(alphabet)\n  }\n  return digits.join('')\n}\n\n/**\n * Returns a random ID\n * @param charsCount length of the ID\n * @param chars characters used to generate the ID\n */\nexport default function generateId(\n  charsCount?: number,\n  chars: string = UNMISTAKABLE_CHARS\n): string {\n  if (!charsCount) {\n    charsCount = 17\n  }\n\n  return randomString(charsCount, chars)\n}\n","/**\n * Creates a map (object) from an array of items, using a specified property as the key.\n * \n * This utility transforms an array of objects into a lookup object/dictionary where\n * each item in the array becomes a value in the map, indexed by the specified property.\n * If multiple items have the same key value, only the last one will be preserved.\n * \n * @template T The type of items in the input array\n * @param array - The input array of items to transform into a map\n * @param key - The property name to use as keys in the resulting map (defaults to '_id')\n * @returns A record object where keys are values of the specified property and values are the original items\n * \n * @example\n * // Returns { '1': { id: 1, name: 'Item 1' }, '2': { id: 2, name: 'Item 2' } }\n * createMap([{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }], 'id')\n */\nexport default function createMap<T>(array: Array<T>, key: string = '_id'): Record<string, T> {\n  const map = {}\n\n  for (const item of array) {\n    map[item[key]] = item\n  }\n\n  return map\n}\n","/**\n * Creates a grouped map from an array of items, using a specified property as the key.\n * \n * This utility transforms an array of objects into a lookup object/dictionary where\n * each value is an array of items sharing the same key value. Unlike createMap,\n * this function preserves all items with the same key by grouping them in arrays.\n * \n * @template T The type of items in the input array\n * @param array - The input array of items to transform into a grouped map\n * @param key - The property name to use as keys in the resulting map (defaults to '_id')\n * @returns A record object where keys are values of the specified property and values are arrays of items\n * \n * @example\n * // Returns { 'category1': [{ id: 1, category: 'category1' }, { id: 3, category: 'category1' }], \n * //           'category2': [{ id: 2, category: 'category2' }] }\n * createMapArray([\n *   { id: 1, category: 'category1' }, \n *   { id: 2, category: 'category2' }, \n *   { id: 3, category: 'category1' }\n * ], 'category')\n */\nexport default function createMapArray<T>(\n  array: Array<T>,\n  key: string = '_id'\n): Record<string, Array<T>> {\n  const map = {}\n\n  for (const item of array) {\n    map[item[key]] = map[item[key]] || []\n    map[item[key]].push(item)\n  }\n\n  return map\n}\n","/**\n * Interface representing the standardized error information structure for Orion errors.\n * This is used by the getInfo method to provide consistent error reporting.\n */\nexport interface OrionErrorInformation {\n  /** The error code or identifier */\n  error: string\n  /** Human-readable error message */\n  message: string\n  /** Additional error metadata or context */\n  extra: any\n  /** The sub-type of error. For example for permissions errors it could be 'read', 'write', 'admin' */\n  type?: string\n}\n\n/**\n * Base error class for all Orion-specific errors.\n * \n * This abstract class provides common properties and methods for all error types\n * used in the Orion framework. It's extended by more specific error classes\n * like UserError and PermissionsError.\n * \n * @property isOrionError - Flag indicating this is an Orion error (always true)\n * @property isUserError - Flag indicating if this is a user-facing error\n * @property isPermissionsError - Flag indicating if this is a permissions-related error\n * @property code - Error code for identifying the error type\n * @property extra - Additional error context or metadata\n */\nexport class OrionError extends Error {\n  isOrionError = true\n\n  isUserError: boolean\n  isPermissionsError: boolean\n  code: string\n  extra: any\n\n  /**\n   * Returns a standardized representation of the error information.\n   * @returns An object containing error details in a consistent format\n   */\n  getInfo: () => OrionErrorInformation\n}\n","import { OrionError } from './OrionError'\n\n/**\n * Error class for permission-related errors in the Orion framework.\n * \n * PermissionsError represents authorization failures where a user or client \n * attempts to perform an action they don't have permission to execute.\n * This is used to distinguish security/permissions errors from other types\n * of errors for proper error handling and user feedback.\n * \n * @extends OrionError\n */\nexport default class PermissionsError extends OrionError {\n  /**\n   * Creates a new PermissionsError instance.\n   * \n   * @param permissionErrorType - Identifies the specific permission that was violated\n   *                              (e.g., 'read', 'write', 'admin')\n   * @param extra - Additional error context or metadata. Can include a custom message\n   *                via the message property.\n   * \n   * @example\n   * // Basic usage\n   * throw new PermissionsError('delete_document')\n   * \n   * @example\n   * // With custom message\n   * throw new PermissionsError('access_admin', { message: 'Admin access required' })\n   * \n   * @example\n   * // With additional context\n   * throw new PermissionsError('edit_user', { \n   *   userId: 'user123',\n   *   requiredRole: 'admin'\n   * })\n   */\n  constructor(permissionErrorType, extra: any = {}) {\n    // Calling parent constructor of base Error class.\n    const message =\n      extra.message || `Client is not allowed to perform this action [${permissionErrorType}]`\n\n    super(message)\n    Error.captureStackTrace(this, this.constructor)\n\n    this.isOrionError = true\n    this.isPermissionsError = true\n    this.code = 'PermissionsError'\n    this.extra = extra\n\n    this.getInfo = () => {\n      return {\n        ...extra,\n        error: 'PermissionsError',\n        message,\n        type: permissionErrorType\n      }\n    }\n  }\n}\n","import { OrionError } from './OrionError'\n\n/**\n * Error class for user-facing errors in the Orion framework.\n * \n * UserError is designed to represent errors that should be displayed to end users,\n * as opposed to system errors or unexpected failures. These errors typically represent\n * validation issues, business rule violations, or other expected error conditions.\n * \n * @extends OrionError\n */\nexport default class UserError extends OrionError {\n  /**\n   * Creates a new UserError instance.\n   * \n   * @param code - Error code identifier. If only one parameter is provided,\n   *               this will be used as the message and code will default to 'error'.\n   * @param message - Human-readable error message. Optional if code is provided.\n   * @param extra - Additional error context or metadata.\n   * \n   * @example\n   * // Basic usage\n   * throw new UserError('invalid_input', 'The provided email is invalid')\n   * \n   * @example\n   * // Using only a message (code will be 'error')\n   * throw new UserError('Input validation failed')\n   * \n   * @example\n   * // With extra metadata\n   * throw new UserError('rate_limit', 'Too many requests', { maxRequests: 100 })\n   */\n  constructor(code: string, message?: string, extra?: any) {\n    if (!message && code) {\n      message = code\n      code = 'error'\n    }\n\n    super(message)\n    Error.captureStackTrace(this, this.constructor)\n\n    this.isOrionError = true\n    this.isUserError = true\n    this.code = code\n    this.extra = extra\n\n    this.getInfo = () => {\n      return {\n        error: code,\n        message,\n        extra\n      }\n    }\n  }\n}\n","/**\n * @file Exports all error classes used in the Orion framework\n */\n\nimport {OrionError} from './OrionError'\nimport type {OrionErrorInformation} from './OrionError'\nimport PermissionsError from './PermissionsError'\nimport UserError from './UserError'\n\n/**\n * Re-export all error types for convenient importing\n */\nexport {OrionError, PermissionsError, UserError}\nexport type {OrionErrorInformation}\n\n/**\n * Type guard to check if an error is an OrionError\n *\n * @param error - Any error object to test\n * @returns True if the error is an OrionError instance\n *\n * @example\n * try {\n *   // some code that might throw\n * } catch (error) {\n *   if (isOrionError(error)) {\n *     // Handle Orion-specific error\n *     console.log(error.code, error.getInfo())\n *   } else {\n *     // Handle general error\n *   }\n * }\n */\nexport function isOrionError(error: any): error is OrionError {\n  return Boolean(error && typeof error === 'object' && error.isOrionError === true)\n}\n\n/**\n * Type guard to check if an error is a UserError\n *\n * @param error - Any error object to test\n * @returns True if the error is a UserError instance\n */\nexport function isUserError(error: any): error is UserError {\n  return Boolean(\n    error && typeof error === 'object' && error.isOrionError === true && error.isUserError === true,\n  )\n}\n\n/**\n * Type guard to check if an error is a PermissionsError\n *\n * @param error - Any error object to test\n * @returns True if the error is a PermissionsError instance\n */\nexport function isPermissionsError(error: any): error is PermissionsError {\n  return Boolean(\n    error &&\n      typeof error === 'object' &&\n      error.isOrionError === true &&\n      error.isPermissionsError === true,\n  )\n}\n","// from https://github.com/koajs/compose/blob/master/index.js\n\n/**\n * Compose `middleware` returning\n * a fully valid middleware comprised\n * of all those which are passed.\n */\nexport function composeMiddlewares(middleware) {\n  if (!Array.isArray(middleware)) throw new TypeError('Middleware stack must be an array!')\n  for (const fn of middleware) {\n    if (typeof fn !== 'function') throw new TypeError('Middleware must be composed of functions!')\n  }\n\n  /**\n   * @param {Object} context\n   * @return {Promise}\n   * @api public\n   */\n\n  return function (context, next?) {\n    // last called middleware #\n    let index = -1\n    return dispatch(0)\n    function dispatch(i) {\n      if (i <= index) return Promise.reject(new Error('next() called multiple times'))\n      index = i\n      let fn = middleware[i]\n      if (i === middleware.length) fn = next\n      if (!fn) return Promise.resolve()\n      try {\n        return Promise.resolve(fn(context, dispatch.bind(null, i + 1)))\n      } catch (err) {\n        return Promise.reject(err)\n      }\n    }\n  }\n}\n","/**\n * Executes an asynchronous function with automatic retries on failure.\n * \n * This utility attempts to execute the provided function and automatically\n * retries if it fails, with a specified delay between attempts. It will\n * continue retrying until either the function succeeds or the maximum\n * number of retries is reached.\n * \n * @template TFunc Type of the function to execute (must return a Promise)\n * @param fn - The asynchronous function to execute\n * @param retries - The maximum number of retry attempts after the initial attempt\n * @param timeout - The delay in milliseconds between retry attempts\n * @returns A promise that resolves with the result of the function or rejects with the last error\n * \n * @example\n * // Retry an API call up to 3 times with 1 second between attempts\n * const result = await executeWithRetries(\n *   () => fetchDataFromApi(),\n *   3,\n *   1000\n * );\n */\nexport function executeWithRetries<TFunc extends () => Promise<any>>(\n  fn: TFunc,\n  retries: number,\n  timeout: number\n): Promise<ReturnType<TFunc>> {\n  return new Promise((resolve, reject) => {\n    const retry = async (retries: number) => {\n      try {\n        const result = await fn()\n        resolve(result)\n      } catch (error) {\n        if (retries > 0) {\n          setTimeout(() => retry(retries - 1), timeout)\n        } else {\n          reject(error)\n        }\n      }\n    }\n    retry(retries)\n  })\n}\n","import crypto from 'crypto';\nconst rnds8Pool = new Uint8Array(256); // # of random values to pre-allocate\n\nlet poolPtr = rnds8Pool.length;\nexport default function rng() {\n  if (poolPtr > rnds8Pool.length - 16) {\n    crypto.randomFillSync(rnds8Pool);\n    poolPtr = 0;\n  }\n\n  return rnds8Pool.slice(poolPtr, poolPtr += 16);\n}","export default /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i;","import REGEX from './regex.js';\n\nfunction validate(uuid) {\n  return typeof uuid === 'string' && REGEX.test(uuid);\n}\n\nexport default validate;","import validate from './validate.js';\n/**\n * Convert array of 16 byte values to UUID string format of the form:\n * XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\n */\n\nconst byteToHex = [];\n\nfor (let i = 0; i < 256; ++i) {\n  byteToHex.push((i + 0x100).toString(16).substr(1));\n}\n\nfunction stringify(arr, offset = 0) {\n  // Note: Be careful editing this code!  It's been tuned for performance\n  // and works in ways you may not expect. See https://github.com/uuidjs/uuid/pull/434\n  const uuid = (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + '-' + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + '-' + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + '-' + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + '-' + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase(); // Consistency check for valid UUID.  If this throws, it's likely due to one\n  // of the following:\n  // - One or more input array values don't map to a hex octet (leading to\n  // \"undefined\" in the uuid)\n  // - Invalid input values for the RFC `version` or `variant` fields\n\n  if (!validate(uuid)) {\n    throw TypeError('Stringified UUID is invalid');\n  }\n\n  return uuid;\n}\n\nexport default stringify;","import rng from './rng.js';\nimport stringify from './stringify.js';\n\nfunction v4(options, buf, offset) {\n  options = options || {};\n  const rnds = options.random || (options.rng || rng)(); // Per 4.4, set bits for version and `clock_seq_hi_and_reserved`\n\n  rnds[6] = rnds[6] & 0x0f | 0x40;\n  rnds[8] = rnds[8] & 0x3f | 0x80; // Copy bytes to buffer, if provided\n\n  if (buf) {\n    offset = offset || 0;\n\n    for (let i = 0; i < 16; ++i) {\n      buf[offset + i] = rnds[i];\n    }\n\n    return buf;\n  }\n\n  return stringify(rnds);\n}\n\nexport default v4;","import { v4 as uuidv4 } from 'uuid'\n\nexport function generateUUID() {\n  return uuidv4()\n}\n\nexport function generateUUIDWithPrefix(prefix: string) {\n  return `${prefix}-${generateUUID()}`\n}\n","/**\n * Removes diacritical marks (accents) from text without any other modifications.\n * This is the most basic normalization function that others build upon.\n * \n * @param text - The input string to process\n * @returns String with accents removed but otherwise unchanged\n */\nexport function removeAccentsOnly(text: string) {\n  if (!text) return ''\n  // biome-ignore lint/suspicious/noMisleadingCharacterClass: Removes diacritical marks (accents)\n  return text.normalize('NFD').replace(/[\\u0300-\\u036f]/g, '')\n}\n\n/**\n * Normalizes text by removing diacritical marks (accents) and trimming whitespace.\n * Builds on removeAccentsOnly and adds whitespace trimming.\n * \n * @param text - The input string to normalize\n * @returns Normalized string with accents removed and whitespace trimmed\n */\nexport function removeAccentsAndTrim(text: string) {\n  if (!text) return ''\n  return removeAccentsOnly(text).trim()\n}\n\n/**\n * Normalizes text for search purposes by:\n * - Removing diacritical marks (accents)\n * - Converting to lowercase\n * - Trimming whitespace\n * \n * Builds on removeAccentsAndTrim and adds lowercase conversion.\n * Useful for case-insensitive and accent-insensitive text searching.\n * \n * @param text - The input string to normalize for search\n * @returns Search-optimized string in lowercase with accents removed\n */\nexport function normalizeForSearch(text: string) {\n  if (!text) return ''\n  return removeAccentsAndTrim(text).toLowerCase()\n}\n\n/**\n * Normalizes text for search purposes by:\n * - Removing diacritical marks (accents)\n * - Converting to lowercase\n * - Trimming whitespace\n * - Removing all spaces\n * \n * Builds on normalizeForSearch and removes all whitespace.\n * Useful for compact search indexes or when spaces should be ignored in searches.\n * \n * @param text - The input string to normalize for compact search\n * @returns Compact search-optimized string with no spaces\n */\nexport function normalizeForCompactSearch(text: string) {\n  if (!text) return ''\n  return normalizeForSearch(text).replace(/\\s/g, '')\n}\n\n/**\n * Normalizes text for search token processing by:\n * - Removing diacritical marks (accents)\n * - Converting to lowercase\n * - Trimming whitespace\n * - Replacing all non-alphanumeric characters with spaces\n * \n * Builds on normalizeForSearch and replaces non-alphanumeric characters with spaces.\n * Useful for tokenizing search terms where special characters should be treated as word separators.\n * \n * @param text - The input string to normalize for tokenized search\n * @returns Search token string with only alphanumeric characters and spaces\n */\nexport function normalizeForSearchToken(text: string) {\n  if (!text) return ''\n  return normalizeForSearch(text).replace(/[^0-9a-z]/gi, ' ')\n}\n\n/**\n * Normalizes a string specifically for use as a file key (e.g., in S3 or other storage systems).\n * Performs the following transformations:\n * - Removes accents/diacritical marks\n * - Replaces special characters with hyphens\n * - Ensures only alphanumeric characters, hyphens, periods, and underscores remain\n * - Replaces multiple consecutive hyphens with a single hyphen\n * - Removes leading/trailing hyphens\n * \n * @param text - The input string to normalize for file key usage\n * @returns A storage-safe string suitable for use as a file key\n */\nexport function normalizeForFileKey(text: string) {\n  if (!text) return ''\n  return removeAccentsOnly(text)\n    // Replace spaces and unwanted characters with hyphens\n    .replace(/[^a-zA-Z0-9-._]/g, '-')\n    // Replace multiple consecutive hyphens with single hyphen\n    .replace(/-+/g, '-')\n    // Remove leading/trailing hyphens\n    .trim()\n    .replace(/^-+|-+$/g, '')\n}\n","import { normalizeForSearchToken } from './normalize'\n\n/**\n * Generates an array of search tokens from input text and optional metadata.\n * \n * This function processes text by:\n * 1. Converting it to an array of strings (if not already)\n * 2. Filtering out falsy values\n * 3. Normalizing each string (removing accents, special characters)\n * 4. Splitting by spaces to create individual tokens\n * 5. Optionally adding metadata tokens in the format \"_key:value\"\n * \n * @param text - String or array of strings to tokenize\n * @param meta - Optional metadata object where each key-value pair becomes a token\n * @returns Array of normalized search tokens\n * \n * @example\n * // Returns ['hello', 'world']\n * getSearchTokens('Hello, World!') \n * \n * @example\n * // Returns ['hello', 'world', '_id:123']\n * getSearchTokens('Hello, World!', { id: '123' })\n */\nexport function getSearchTokens(text: string[] | string, meta?: Record<string, string>) {\n  const stringArray = Array.isArray(text) ? text : [text]\n  const tokens = stringArray\n    .filter(Boolean)\n    .map(text => String(text))\n    .flatMap(word => {\n      return normalizeForSearchToken(word).split(' ').filter(Boolean)\n    })\n\n  if (meta) {\n    for (const key in meta) {\n      tokens.push(`_${key}:${meta[key]}`)\n    }\n  }\n\n  return tokens\n}\n\n/**\n * Interface for parameters used in generating search queries from tokens.\n * \n * @property filter - Optional string to filter search results\n * @property [key: string] - Additional key-value pairs for metadata filtering\n */\nexport interface SearchQueryForTokensParams {\n  filter?: string\n  [key: string]: string\n}\n\n/**\n * Options for customizing the search query generation behavior.\n * Currently empty but provided for future extensibility.\n */\nexport type SearchQueryForTokensOptions = {}\n\n/**\n * Generates a MongoDB-compatible query object based on the provided parameters.\n * \n * This function:\n * 1. Processes any filter text into RegExp tokens for prefix matching\n * 2. Adds metadata filters based on additional properties in the params object\n * 3. Returns a query object with the $all operator for MongoDB queries\n * \n * @param params - Parameters for generating the search query\n * @param _options - Options for customizing search behavior (reserved for future use)\n * @returns A MongoDB-compatible query object with format { $all: [...tokens] }\n * \n * @example\n * // Returns { $all: [/^hello/, /^world/] }\n * getSearchQueryForTokens({ filter: 'Hello World' })\n * \n * @example\n * // Returns { $all: [/^search/, '_category:books'] }\n * getSearchQueryForTokens({ filter: 'search', category: 'books' })\n */\nexport function getSearchQueryForTokens(\n  params: SearchQueryForTokensParams = {},\n  _options: SearchQueryForTokensOptions = {},\n) {\n  const searchTokens: (string | RegExp)[] = []\n\n  if (params.filter) {\n    const filterTokens = getSearchTokens(params.filter).map(token => new RegExp(`^${token}`))\n    searchTokens.push(...filterTokens)\n  }\n\n  for (const key in params) {\n    if (key === 'filter') continue\n    if (!params[key]) continue\n    searchTokens.push(`_${key}:${params[key]}`)\n  }\n\n  return { $all: searchTokens }\n}\n","function lastOfString(string: string, last: number) {\n  return string.substring(string.length - last, string.length)\n}\n\nexport function shortenMongoId(string: string) {\n  return lastOfString(string, 5).toUpperCase()\n}\n"],"mappings":"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","names":["time","Promise","resolve","setTimeout","object","hash","UNMISTAKABLE_CHARS","hexString","digits","numBytes","Math","ceil","bytes","crypto","randomBytes","e","pseudoRandomBytes","result","toString","substring","fraction","numerator","parseInt","choice","arrayOrString","index","floor","length","substr","randomString","charsCount","alphabet","i","join","chars","generateId","array","key","map","item","createMap","array","key","map","item","push","createMapArray","OrionError","Error","isOrionError","isUserError","isPermissionsError","code","extra","getInfo","PermissionsError","OrionError","constructor","permissionErrorType","extra","message","Error","captureStackTrace","isOrionError","isPermissionsError","code","getInfo","error","type","UserError","OrionError","constructor","code","message","extra","Error","captureStackTrace","isOrionError","isUserError","getInfo","error","isOrionError","error","Boolean","isUserError","isPermissionsError","composeMiddlewares","middleware","Array","isArray","TypeError","fn","context","next","index","dispatch","i","Promise","reject","Error","length","resolve","bind","err","executeWithRetries","fn","retries","timeout","Promise","resolve","reject","retry","result","error","setTimeout","import_crypto","rnds8Pool","Uint8Array","poolPtr","length","rng","crypto","randomFillSync","slice","validate","uuid","REGEX","test","byteToHex","i","push","toString","substr","stringify","arr","offset","uuid","toLowerCase","validate","TypeError","v4","options","buf","offset","rnds","random","rng","i","stringify","generateUUID","uuidv4","generateUUIDWithPrefix","prefix","removeAccentsOnly","text","normalize","replace","removeAccentsAndTrim","trim","normalizeForSearch","toLowerCase","normalizeForCompactSearch","normalizeForSearchToken","normalizeForFileKey","getSearchTokens","text","meta","stringArray","Array","isArray","tokens","filter","Boolean","map","String","flatMap","word","normalizeForSearchToken","split","key","push","getSearchQueryForTokens","params","_options","searchTokens","filterTokens","token","RegExp","$all","lastOfString","string","last","substring","length","shortenMongoId","toUpperCase"]}

package/dist/index.d.cts

@@ -0,0 +1,373 @@
+/**
+ * Creates a timeout with a promise
+ */
+declare const _default: (time: number) => Promise<void>;
+
+declare function export_default(object: any): string;
+
+/**
+ * Returns a random ID
+ * @param charsCount length of the ID
+ * @param chars characters used to generate the ID
+ */
+declare function generateId(charsCount?: number, chars?: string): string;
+
+/**
+ * Creates a map (object) from an array of items, using a specified property as the key.
+ *
+ * This utility transforms an array of objects into a lookup object/dictionary where
+ * each item in the array becomes a value in the map, indexed by the specified property.
+ * If multiple items have the same key value, only the last one will be preserved.
+ *
+ * @template T The type of items in the input array
+ * @param array - The input array of items to transform into a map
+ * @param key - The property name to use as keys in the resulting map (defaults to '_id')
+ * @returns A record object where keys are values of the specified property and values are the original items
+ *
+ * @example
+ * // Returns { '1': { id: 1, name: 'Item 1' }, '2': { id: 2, name: 'Item 2' } }
+ * createMap([{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }], 'id')
+ */
+declare function createMap<T>(array: Array<T>, key?: string): Record<string, T>;
+
+/**
+ * Creates a grouped map from an array of items, using a specified property as the key.
+ *
+ * This utility transforms an array of objects into a lookup object/dictionary where
+ * each value is an array of items sharing the same key value. Unlike createMap,
+ * this function preserves all items with the same key by grouping them in arrays.
+ *
+ * @template T The type of items in the input array
+ * @param array - The input array of items to transform into a grouped map
+ * @param key - The property name to use as keys in the resulting map (defaults to '_id')
+ * @returns A record object where keys are values of the specified property and values are arrays of items
+ *
+ * @example
+ * // Returns { 'category1': [{ id: 1, category: 'category1' }, { id: 3, category: 'category1' }],
+ * //           'category2': [{ id: 2, category: 'category2' }] }
+ * createMapArray([
+ *   { id: 1, category: 'category1' },
+ *   { id: 2, category: 'category2' },
+ *   { id: 3, category: 'category1' }
+ * ], 'category')
+ */
+declare function createMapArray<T>(array: Array<T>, key?: string): Record<string, Array<T>>;
+
+/**
+ * Interface representing the standardized error information structure for Orion errors.
+ * This is used by the getInfo method to provide consistent error reporting.
+ */
+interface OrionErrorInformation {
+    /** The error code or identifier */
+    error: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error metadata or context */
+    extra: any;
+    /** The sub-type of error. For example for permissions errors it could be 'read', 'write', 'admin' */
+    type?: string;
+}
+/**
+ * Base error class for all Orion-specific errors.
+ *
+ * This abstract class provides common properties and methods for all error types
+ * used in the Orion framework. It's extended by more specific error classes
+ * like UserError and PermissionsError.
+ *
+ * @property isOrionError - Flag indicating this is an Orion error (always true)
+ * @property isUserError - Flag indicating if this is a user-facing error
+ * @property isPermissionsError - Flag indicating if this is a permissions-related error
+ * @property code - Error code for identifying the error type
+ * @property extra - Additional error context or metadata
+ */
+declare class OrionError extends Error {
+    isOrionError: boolean;
+    isUserError: boolean;
+    isPermissionsError: boolean;
+    code: string;
+    extra: any;
+    /**
+     * Returns a standardized representation of the error information.
+     * @returns An object containing error details in a consistent format
+     */
+    getInfo: () => OrionErrorInformation;
+}
+
+/**
+ * Error class for permission-related errors in the Orion framework.
+ *
+ * PermissionsError represents authorization failures where a user or client
+ * attempts to perform an action they don't have permission to execute.
+ * This is used to distinguish security/permissions errors from other types
+ * of errors for proper error handling and user feedback.
+ *
+ * @extends OrionError
+ */
+declare class PermissionsError extends OrionError {
+    /**
+     * Creates a new PermissionsError instance.
+     *
+     * @param permissionErrorType - Identifies the specific permission that was violated
+     *                              (e.g., 'read', 'write', 'admin')
+     * @param extra - Additional error context or metadata. Can include a custom message
+     *                via the message property.
+     *
+     * @example
+     * // Basic usage
+     * throw new PermissionsError('delete_document')
+     *
+     * @example
+     * // With custom message
+     * throw new PermissionsError('access_admin', { message: 'Admin access required' })
+     *
+     * @example
+     * // With additional context
+     * throw new PermissionsError('edit_user', {
+     *   userId: 'user123',
+     *   requiredRole: 'admin'
+     * })
+     */
+    constructor(permissionErrorType: any, extra?: any);
+}
+
+/**
+ * Error class for user-facing errors in the Orion framework.
+ *
+ * UserError is designed to represent errors that should be displayed to end users,
+ * as opposed to system errors or unexpected failures. These errors typically represent
+ * validation issues, business rule violations, or other expected error conditions.
+ *
+ * @extends OrionError
+ */
+declare class UserError extends OrionError {
+    /**
+     * Creates a new UserError instance.
+     *
+     * @param code - Error code identifier. If only one parameter is provided,
+     *               this will be used as the message and code will default to 'error'.
+     * @param message - Human-readable error message. Optional if code is provided.
+     * @param extra - Additional error context or metadata.
+     *
+     * @example
+     * // Basic usage
+     * throw new UserError('invalid_input', 'The provided email is invalid')
+     *
+     * @example
+     * // Using only a message (code will be 'error')
+     * throw new UserError('Input validation failed')
+     *
+     * @example
+     * // With extra metadata
+     * throw new UserError('rate_limit', 'Too many requests', { maxRequests: 100 })
+     */
+    constructor(code: string, message?: string, extra?: any);
+}
+
+/**
+ * @file Exports all error classes used in the Orion framework
+ */
+
+/**
+ * Type guard to check if an error is an OrionError
+ *
+ * @param error - Any error object to test
+ * @returns True if the error is an OrionError instance
+ *
+ * @example
+ * try {
+ *   // some code that might throw
+ * } catch (error) {
+ *   if (isOrionError(error)) {
+ *     // Handle Orion-specific error
+ *     console.log(error.code, error.getInfo())
+ *   } else {
+ *     // Handle general error
+ *   }
+ * }
+ */
+declare function isOrionError(error: any): error is OrionError;
+/**
+ * Type guard to check if an error is a UserError
+ *
+ * @param error - Any error object to test
+ * @returns True if the error is a UserError instance
+ */
+declare function isUserError(error: any): error is UserError;
+/**
+ * Type guard to check if an error is a PermissionsError
+ *
+ * @param error - Any error object to test
+ * @returns True if the error is a PermissionsError instance
+ */
+declare function isPermissionsError(error: any): error is PermissionsError;
+
+/**
+ * Compose `middleware` returning
+ * a fully valid middleware comprised
+ * of all those which are passed.
+ */
+declare function composeMiddlewares(middleware: any): (context: any, next?: any) => Promise<any>;
+
+/**
+ * Executes an asynchronous function with automatic retries on failure.
+ *
+ * This utility attempts to execute the provided function and automatically
+ * retries if it fails, with a specified delay between attempts. It will
+ * continue retrying until either the function succeeds or the maximum
+ * number of retries is reached.
+ *
+ * @template TFunc Type of the function to execute (must return a Promise)
+ * @param fn - The asynchronous function to execute
+ * @param retries - The maximum number of retry attempts after the initial attempt
+ * @param timeout - The delay in milliseconds between retry attempts
+ * @returns A promise that resolves with the result of the function or rejects with the last error
+ *
+ * @example
+ * // Retry an API call up to 3 times with 1 second between attempts
+ * const result = await executeWithRetries(
+ *   () => fetchDataFromApi(),
+ *   3,
+ *   1000
+ * );
+ */
+declare function executeWithRetries<TFunc extends () => Promise<any>>(fn: TFunc, retries: number, timeout: number): Promise<ReturnType<TFunc>>;
+
+declare function generateUUID(): any;
+declare function generateUUIDWithPrefix(prefix: string): string;
+
+/**
+ * Removes diacritical marks (accents) from text without any other modifications.
+ * This is the most basic normalization function that others build upon.
+ *
+ * @param text - The input string to process
+ * @returns String with accents removed but otherwise unchanged
+ */
+declare function removeAccentsOnly(text: string): string;
+/**
+ * Normalizes text by removing diacritical marks (accents) and trimming whitespace.
+ * Builds on removeAccentsOnly and adds whitespace trimming.
+ *
+ * @param text - The input string to normalize
+ * @returns Normalized string with accents removed and whitespace trimmed
+ */
+declare function removeAccentsAndTrim(text: string): string;
+/**
+ * Normalizes text for search purposes by:
+ * - Removing diacritical marks (accents)
+ * - Converting to lowercase
+ * - Trimming whitespace
+ *
+ * Builds on removeAccentsAndTrim and adds lowercase conversion.
+ * Useful for case-insensitive and accent-insensitive text searching.
+ *
+ * @param text - The input string to normalize for search
+ * @returns Search-optimized string in lowercase with accents removed
+ */
+declare function normalizeForSearch(text: string): string;
+/**
+ * Normalizes text for search purposes by:
+ * - Removing diacritical marks (accents)
+ * - Converting to lowercase
+ * - Trimming whitespace
+ * - Removing all spaces
+ *
+ * Builds on normalizeForSearch and removes all whitespace.
+ * Useful for compact search indexes or when spaces should be ignored in searches.
+ *
+ * @param text - The input string to normalize for compact search
+ * @returns Compact search-optimized string with no spaces
+ */
+declare function normalizeForCompactSearch(text: string): string;
+/**
+ * Normalizes text for search token processing by:
+ * - Removing diacritical marks (accents)
+ * - Converting to lowercase
+ * - Trimming whitespace
+ * - Replacing all non-alphanumeric characters with spaces
+ *
+ * Builds on normalizeForSearch and replaces non-alphanumeric characters with spaces.
+ * Useful for tokenizing search terms where special characters should be treated as word separators.
+ *
+ * @param text - The input string to normalize for tokenized search
+ * @returns Search token string with only alphanumeric characters and spaces
+ */
+declare function normalizeForSearchToken(text: string): string;
+/**
+ * Normalizes a string specifically for use as a file key (e.g., in S3 or other storage systems).
+ * Performs the following transformations:
+ * - Removes accents/diacritical marks
+ * - Replaces special characters with hyphens
+ * - Ensures only alphanumeric characters, hyphens, periods, and underscores remain
+ * - Replaces multiple consecutive hyphens with a single hyphen
+ * - Removes leading/trailing hyphens
+ *
+ * @param text - The input string to normalize for file key usage
+ * @returns A storage-safe string suitable for use as a file key
+ */
+declare function normalizeForFileKey(text: string): string;
+
+/**
+ * Generates an array of search tokens from input text and optional metadata.
+ *
+ * This function processes text by:
+ * 1. Converting it to an array of strings (if not already)
+ * 2. Filtering out falsy values
+ * 3. Normalizing each string (removing accents, special characters)
+ * 4. Splitting by spaces to create individual tokens
+ * 5. Optionally adding metadata tokens in the format "_key:value"
+ *
+ * @param text - String or array of strings to tokenize
+ * @param meta - Optional metadata object where each key-value pair becomes a token
+ * @returns Array of normalized search tokens
+ *
+ * @example
+ * // Returns ['hello', 'world']
+ * getSearchTokens('Hello, World!')
+ *
+ * @example
+ * // Returns ['hello', 'world', '_id:123']
+ * getSearchTokens('Hello, World!', { id: '123' })
+ */
+declare function getSearchTokens(text: string[] | string, meta?: Record<string, string>): string[];
+/**
+ * Interface for parameters used in generating search queries from tokens.
+ *
+ * @property filter - Optional string to filter search results
+ * @property [key: string] - Additional key-value pairs for metadata filtering
+ */
+interface SearchQueryForTokensParams {
+    filter?: string;
+    [key: string]: string;
+}
+/**
+ * Options for customizing the search query generation behavior.
+ * Currently empty but provided for future extensibility.
+ */
+type SearchQueryForTokensOptions = {};
+/**
+ * Generates a MongoDB-compatible query object based on the provided parameters.
+ *
+ * This function:
+ * 1. Processes any filter text into RegExp tokens for prefix matching
+ * 2. Adds metadata filters based on additional properties in the params object
+ * 3. Returns a query object with the $all operator for MongoDB queries
+ *
+ * @param params - Parameters for generating the search query
+ * @param _options - Options for customizing search behavior (reserved for future use)
+ * @returns A MongoDB-compatible query object with format { $all: [...tokens] }
+ *
+ * @example
+ * // Returns { $all: [/^hello/, /^world/] }
+ * getSearchQueryForTokens({ filter: 'Hello World' })
+ *
+ * @example
+ * // Returns { $all: [/^search/, '_category:books'] }
+ * getSearchQueryForTokens({ filter: 'search', category: 'books' })
+ */
+declare function getSearchQueryForTokens(params?: SearchQueryForTokensParams, _options?: SearchQueryForTokensOptions): {
+    $all: (string | RegExp)[];
+};
+
+declare function shortenMongoId(string: string): string;
+
+export { OrionError, type OrionErrorInformation, PermissionsError, type SearchQueryForTokensOptions, type SearchQueryForTokensParams, UserError, composeMiddlewares, createMap, createMapArray, executeWithRetries, generateId, generateUUID, generateUUIDWithPrefix, getSearchQueryForTokens, getSearchTokens, export_default as hashObject, isOrionError, isPermissionsError, isUserError, normalizeForCompactSearch, normalizeForFileKey, normalizeForSearch, normalizeForSearchToken, removeAccentsAndTrim, removeAccentsOnly, shortenMongoId, _default as sleep };