@orion-js/helpers 4.3.1 → 4.4.0

package/LICENSE

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

package/dist/Errors/OrionError.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Interface representing the standardized error information structure for Orion errors.
+ * This is used by the getInfo method to provide consistent error reporting.
+ */
+export 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
+ */
+export 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;
+}

package/dist/Errors/PermissionsError.d.ts

@@ -0,0 +1,37 @@
+import { OrionError } from './OrionError';
+/**
+ * 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
+ */
+export default 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);
+}

package/dist/Errors/UserError.d.ts

@@ -0,0 +1,33 @@
+import { OrionError } from './OrionError';
+/**
+ * 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
+ */
+export default 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);
+}

package/dist/Errors/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Exports all error classes used in the Orion framework
+ */
+import { OrionError } from './OrionError';
+import type { OrionErrorInformation } from './OrionError';
+import PermissionsError from './PermissionsError';
+import UserError from './UserError';
+/**
+ * Re-export all error types for convenient importing
+ */
+export { OrionError, PermissionsError, UserError };
+export type { OrionErrorInformation };
+/**
+ * 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
+ *   }
+ * }
+ */
+export 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
+ */
+export 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
+ */
+export declare function isPermissionsError(error: any): error is PermissionsError;

package/dist/clone.d.ts

@@ -0,0 +1 @@
+export declare function clone<T>(value: T): T;

package/dist/composeMiddlewares.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compose `middleware` returning
+ * a fully valid middleware comprised
+ * of all those which are passed.
+ */
+export declare function composeMiddlewares(middleware: any): (context: any, next?: any) => Promise<any>;

package/dist/createMap.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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')
+ */
+export default function createMap<T>(array: Array<T>, key?: string): Record<string, T>;

package/dist/createMapArray.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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')
+ */
+export default function createMapArray<T>(array: Array<T>, key?: string): Record<string, Array<T>>;

package/dist/generateId.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a random ID
+ * @param charsCount length of the ID
+ * @param chars characters used to generate the ID
+ */
+export default function generateId(charsCount?: number, chars?: string): string;

package/dist/generateUUID.d.ts

@@ -0,0 +1,2 @@
+export declare function generateUUID(): string;
+export declare function generateUUIDWithPrefix(prefix: string): string;

package/dist/hashObject.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Receives any javascript object, string, number, boolean, array, or object and returns a hash of it.
+ */
+export default function hashObject(object: any): string;

package/dist/index.d.ts

@@ -1,378 +1,16 @@
-/**
- * Creates a timeout with a promise
- */
-declare const _default: (time: number) => Promise<void>;
-
-/**
- * Receives any javascript object, string, number, boolean, array, or object and returns a hash of it.
- */
-declare function hashObject(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>>;
-
-declare function clone<T>(value: T): 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(): string;
-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, clone, composeMiddlewares, createMap, createMapArray, executeWithRetries, generateId, generateUUID, generateUUIDWithPrefix, getSearchQueryForTokens, getSearchTokens, hashObject, isOrionError, isPermissionsError, isUserError, normalizeForCompactSearch, normalizeForFileKey, normalizeForSearch, normalizeForSearchToken, removeAccentsAndTrim, removeAccentsOnly, shortenMongoId, _default as sleep };
+import sleep from './sleep';
+import hashObject from './hashObject';
+import generateId from './generateId';
+import createMap from './createMap';
+import createMapArray from './createMapArray';
+export * from './clone';
+import { OrionError, PermissionsError, UserError, isOrionError, isUserError, isPermissionsError } from './Errors';
+import type { OrionErrorInformation } from './Errors';
+export * from './composeMiddlewares';
+export * from './retries';
+export * from './generateUUID';
+export * from './normalize';
+export * from './searchTokens';
+export * from './shortenMongoId';
+export { createMap, createMapArray, generateId, hashObject, sleep, OrionError, PermissionsError, UserError, isOrionError, isUserError, isPermissionsError, };
+export type { OrionErrorInformation };

package/dist/normalize.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function normalizeForFileKey(text: string): string;

package/dist/retries.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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
+ * );
+ */
+export declare function executeWithRetries<TFunc extends () => Promise<any>>(fn: TFunc, retries: number, timeout: number): Promise<ReturnType<TFunc>>;

package/dist/searchTokens.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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' })
+ */
+export 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
+ */
+export interface SearchQueryForTokensParams {
+    filter?: string;
+    [key: string]: string;
+}
+/**
+ * Options for customizing the search query generation behavior.
+ * Currently empty but provided for future extensibility.
+ */
+export 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' })
+ */
+export declare function getSearchQueryForTokens(params?: SearchQueryForTokensParams, _options?: SearchQueryForTokensOptions): {
+    $all: (string | RegExp)[];
+};

package/dist/shortenMongoId.d.ts

@@ -0,0 +1 @@
+export declare function shortenMongoId(string: string): string;

package/dist/sleep.d.ts

@@ -0,0 +1,5 @@
+export default _default;
+/**
+ * Creates a timeout with a promise
+ */
+declare function _default(time: number): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orion-js/helpers",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,27 +14,26 @@
   ],
   "author": "nicolaslopezj",
   "license": "MIT",
-  "scripts": {
-    "test": "bun test",
-    "prepare": "bun run build",
-    "clean": "rm -rf ./dist",
-    "build": "tsup",
-    "dev": "tsup --watch"
-  },
   "dependencies": {
     "uuid": "^11.1.0"
   },
   "peerDependencies": {
-    "@orion-js/logger": "4.3.1"
+    "@orion-js/logger": "4.4.0"
   },
   "devDependencies": {
     "@types/node": "^18.0.0",
     "tsup": "^8.0.1",
-    "typescript": "^5.4.5"
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "gitHead": "a485b1fe6a1840ee6cb58fd69d6de62585f1ed10",
-  "type": "module"
-}
+  "type": "module",
+  "scripts": {
+    "test": "bun test",
+    "clean": "rm -rf ./dist",
+    "build": "tsup && bun run ../../scripts/emit-declarations.ts",
+    "dev": "tsup --watch"
+  }
+}

package/dist/index.d.cts

@@ -1,378 +0,0 @@
-/**
- * Creates a timeout with a promise
- */
-declare const _default: (time: number) => Promise<void>;
-
-/**
- * Receives any javascript object, string, number, boolean, array, or object and returns a hash of it.
- */
-declare function hashObject(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>>;
-
-declare function clone<T>(value: T): 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(): string;
-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, clone, composeMiddlewares, createMap, createMapArray, executeWithRetries, generateId, generateUUID, generateUUIDWithPrefix, getSearchQueryForTokens, getSearchTokens, hashObject, isOrionError, isPermissionsError, isUserError, normalizeForCompactSearch, normalizeForFileKey, normalizeForSearch, normalizeForSearchToken, removeAccentsAndTrim, removeAccentsOnly, shortenMongoId, _default as sleep };