@orion-js/helpers 3.11.15 → 4.0.0-alpha.3

package/dist/index.d.ts

@@ -0,0 +1,362 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Creates a timeout with a promise
+ */
+declare const _default: (time: number) => Promise<void>;
+declare function _default$1(object: any): string;
+/**
+ * Returns a random ID
+ * @param charsCount length of the ID
+ * @param chars characters used to generate the ID
+ */
+export 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')
+ */
+export 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')
+ */
+export 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.
+ */
+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;
+}
+/**
+ * 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 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
+ */
+export 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);
+}
+/**
+ * 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;
+/**
+ * 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>;
+/**
+ * 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>>;
+export declare function generateUUID(): any;
+export 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
+ */
+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;
+/**
+ * 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)[];
+};
+export declare function shortenMongoId(string: string): string;
+
+export {
+	_default as sleep,
+	_default$1 as hashObject,
+};
+
+export {};