@orion-js/helpers 3.11.6 → 3.11.15

package/lib/createMapArray.d.ts

@@ -1 +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/lib/createMapArray.js

@@ -1,5 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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')
+ */
 function createMapArray(array, key = '_id') {
     const map = {};
     for (const item of array) {

package/lib/createMapArray.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/createMapArray.test.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const createMapArray_1 = __importDefault(require("./createMapArray"));
+describe('createMapArray', () => {
+    it('should create a map of arrays using the default _id key', () => {
+        const array = [
+            { _id: '1', name: 'Item 1' },
+            { _id: '2', name: 'Item 2' },
+            { _id: '1', name: 'Item 1 Duplicate' }
+        ];
+        const result = (0, createMapArray_1.default)(array);
+        expect(result).toEqual({
+            '1': [
+                { _id: '1', name: 'Item 1' },
+                { _id: '1', name: 'Item 1 Duplicate' }
+            ],
+            '2': [
+                { _id: '2', name: 'Item 2' }
+            ]
+        });
+    });
+    it('should create a map of arrays using a custom key', () => {
+        const array = [
+            { category: 'A', name: 'Item A1' },
+            { category: 'B', name: 'Item B1' },
+            { category: 'A', name: 'Item A2' },
+            { category: 'C', name: 'Item C1' },
+            { category: 'B', name: 'Item B2' }
+        ];
+        const result = (0, createMapArray_1.default)(array, 'category');
+        expect(result).toEqual({
+            'A': [
+                { category: 'A', name: 'Item A1' },
+                { category: 'A', name: 'Item A2' }
+            ],
+            'B': [
+                { category: 'B', name: 'Item B1' },
+                { category: 'B', name: 'Item B2' }
+            ],
+            'C': [
+                { category: 'C', name: 'Item C1' }
+            ]
+        });
+    });
+    it('should handle empty arrays', () => {
+        const result = (0, createMapArray_1.default)([]);
+        expect(result).toEqual({});
+    });
+    it('should preserve the original order of items within each group', () => {
+        const array = [
+            { type: 'fruit', name: 'apple', order: 1 },
+            { type: 'vegetable', name: 'carrot', order: 1 },
+            { type: 'fruit', name: 'banana', order: 2 },
+            { type: 'fruit', name: 'cherry', order: 3 },
+            { type: 'vegetable', name: 'broccoli', order: 2 }
+        ];
+        const result = (0, createMapArray_1.default)(array, 'type');
+        // Items should be grouped by type and maintain their original order
+        expect(result.fruit.map(item => item.order)).toEqual([1, 2, 3]);
+        expect(result.vegetable.map(item => item.order)).toEqual([1, 2]);
+    });
+    it('should handle various key types', () => {
+        const array = [
+            { key: 1, value: 'Number key 1' },
+            { key: 1, value: 'Number key 2' },
+            { key: 'string', value: 'String key 1' },
+            { key: 'string', value: 'String key 2' },
+            { key: true, value: 'Boolean key' }
+        ];
+        const result = (0, createMapArray_1.default)(array, 'key');
+        expect(result).toEqual({
+            '1': [
+                { key: 1, value: 'Number key 1' },
+                { key: 1, value: 'Number key 2' }
+            ],
+            'string': [
+                { key: 'string', value: 'String key 1' },
+                { key: 'string', value: 'String key 2' }
+            ],
+            'true': [
+                { key: true, value: 'Boolean key' }
+            ]
+        });
+    });
+    it('should handle items with missing keys by using undefined', () => {
+        const array = [
+            { id: '1', name: 'Has ID' },
+            { name: 'No ID' },
+            { id: '2', name: 'Has ID 2' }
+        ];
+        const result = (0, createMapArray_1.default)(array, 'id');
+        expect(result).toEqual({
+            '1': [{ id: '1', name: 'Has ID' }],
+            '2': [{ id: '2', name: 'Has ID 2' }],
+            'undefined': [{ name: 'No ID' }]
+        });
+    });
+});

package/lib/generateUUID.d.ts

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

package/lib/generateUUID.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateUUID = void 0;
+exports.generateUUIDWithPrefix = exports.generateUUID = void 0;
 const uuid_1 = require("uuid");
 function generateUUID() {
     return (0, uuid_1.v4)();
 }
 exports.generateUUID = generateUUID;
+function generateUUIDWithPrefix(prefix) {
+    return `${prefix}-${generateUUID()}`;
+}
+exports.generateUUIDWithPrefix = generateUUIDWithPrefix;

package/lib/generateUUID.test.js

@@ -9,3 +9,7 @@ it('should generate random uuid v4', async () => {
     expect((0, generateUUID_1.generateUUID)()).not.toBe((0, generateUUID_1.generateUUID)());
     expect((0, isString_1.default)((0, generateUUID_1.generateUUID)())).toBe(true);
 });
+it('should generate uuid with prefix', async () => {
+    expect((0, generateUUID_1.generateUUIDWithPrefix)('test')).not.toBe((0, generateUUID_1.generateUUIDWithPrefix)('test'));
+    expect((0, isString_1.default)((0, generateUUID_1.generateUUIDWithPrefix)('test'))).toBe(true);
+});

package/lib/index.d.ts

@@ -2,11 +2,12 @@ import sleep from './sleep';
 import hashObject from './hashObject';
 import generateId from './generateId';
 import createMap from './createMap';
-import { OrionError, OrionErrorInformation } from './Errors/OrionError';
-import PermissionsError from './Errors/PermissionsError';
-import UserError from './Errors/UserError';
 import createMapArray from './createMapArray';
+import { OrionError, OrionErrorInformation, PermissionsError, UserError, isOrionError, isUserError, isPermissionsError } from './Errors';
 export * from './composeMiddlewares';
 export * from './retries';
 export * from './generateUUID';
-export { createMap, createMapArray, generateId, hashObject, sleep, OrionError, PermissionsError, UserError, OrionErrorInformation };
+export * from './normalize';
+export * from './searchTokens';
+export * from './shortenMongoId';
+export { createMap, createMapArray, generateId, hashObject, sleep, OrionError, PermissionsError, UserError, OrionErrorInformation, isOrionError, isUserError, isPermissionsError };

package/lib/index.js

@@ -13,7 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UserError = exports.PermissionsError = exports.OrionError = exports.sleep = exports.hashObject = exports.generateId = exports.createMapArray = exports.createMap = void 0;
+exports.isPermissionsError = exports.isUserError = exports.isOrionError = exports.UserError = exports.PermissionsError = exports.OrionError = exports.sleep = exports.hashObject = exports.generateId = exports.createMapArray = exports.createMap = void 0;
 const sleep_1 = __importDefault(require("./sleep"));
 exports.sleep = sleep_1.default;
 const hashObject_1 = __importDefault(require("./hashObject"));
@@ -22,14 +22,19 @@ const generateId_1 = __importDefault(require("./generateId"));
 exports.generateId = generateId_1.default;
 const createMap_1 = __importDefault(require("./createMap"));
 exports.createMap = createMap_1.default;
-const OrionError_1 = require("./Errors/OrionError");
-Object.defineProperty(exports, "OrionError", { enumerable: true, get: function () { return OrionError_1.OrionError; } });
-const PermissionsError_1 = __importDefault(require("./Errors/PermissionsError"));
-exports.PermissionsError = PermissionsError_1.default;
-const UserError_1 = __importDefault(require("./Errors/UserError"));
-exports.UserError = UserError_1.default;
 const createMapArray_1 = __importDefault(require("./createMapArray"));
 exports.createMapArray = createMapArray_1.default;
+// Import all error-related exports from the Errors module
+const Errors_1 = require("./Errors");
+Object.defineProperty(exports, "OrionError", { enumerable: true, get: function () { return Errors_1.OrionError; } });
+Object.defineProperty(exports, "PermissionsError", { enumerable: true, get: function () { return Errors_1.PermissionsError; } });
+Object.defineProperty(exports, "UserError", { enumerable: true, get: function () { return Errors_1.UserError; } });
+Object.defineProperty(exports, "isOrionError", { enumerable: true, get: function () { return Errors_1.isOrionError; } });
+Object.defineProperty(exports, "isUserError", { enumerable: true, get: function () { return Errors_1.isUserError; } });
+Object.defineProperty(exports, "isPermissionsError", { enumerable: true, get: function () { return Errors_1.isPermissionsError; } });
 __exportStar(require("./composeMiddlewares"), exports);
 __exportStar(require("./retries"), exports);
 __exportStar(require("./generateUUID"), exports);
+__exportStar(require("./normalize"), exports);
+__exportStar(require("./searchTokens"), exports);
+__exportStar(require("./shortenMongoId"), exports);

package/lib/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/lib/normalize.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeForFileKey = exports.normalizeForSearchToken = exports.normalizeForCompactSearch = exports.normalizeForSearch = exports.removeAccentsAndTrim = exports.removeAccentsOnly = void 0;
+/**
+ * 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
+ */
+function removeAccentsOnly(text) {
+    if (!text)
+        return '';
+    // biome-ignore lint/suspicious/noMisleadingCharacterClass: Removes diacritical marks (accents)
+    return text.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+exports.removeAccentsOnly = removeAccentsOnly;
+/**
+ * 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
+ */
+function removeAccentsAndTrim(text) {
+    if (!text)
+        return '';
+    return removeAccentsOnly(text).trim();
+}
+exports.removeAccentsAndTrim = removeAccentsAndTrim;
+/**
+ * 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
+ */
+function normalizeForSearch(text) {
+    if (!text)
+        return '';
+    return removeAccentsAndTrim(text).toLowerCase();
+}
+exports.normalizeForSearch = normalizeForSearch;
+/**
+ * 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
+ */
+function normalizeForCompactSearch(text) {
+    if (!text)
+        return '';
+    return normalizeForSearch(text).replace(/\s/g, '');
+}
+exports.normalizeForCompactSearch = normalizeForCompactSearch;
+/**
+ * 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
+ */
+function normalizeForSearchToken(text) {
+    if (!text)
+        return '';
+    return normalizeForSearch(text).replace(/[^0-9a-z]/gi, ' ');
+}
+exports.normalizeForSearchToken = normalizeForSearchToken;
+/**
+ * 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
+ */
+function normalizeForFileKey(text) {
+    if (!text)
+        return '';
+    return removeAccentsOnly(text)
+        // Replace spaces and unwanted characters with hyphens
+        .replace(/[^a-zA-Z0-9-._]/g, '-')
+        // Replace multiple consecutive hyphens with single hyphen
+        .replace(/-+/g, '-')
+        // Remove leading/trailing hyphens
+        .trim()
+        .replace(/^-+|-+$/g, '');
+}
+exports.normalizeForFileKey = normalizeForFileKey;

package/lib/normalize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/normalize.test.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const normalize_1 = require("./normalize");
+describe('Text normalization functions', () => {
+    describe('removeAccentsAndTrim', () => {
+        it('should remove accents and trim whitespace', () => {
+            expect((0, normalize_1.removeAccentsAndTrim)('  héllô wôrld  ')).toBe('hello world');
+        });
+        it('should handle empty string', () => {
+            expect((0, normalize_1.removeAccentsAndTrim)('')).toBe('');
+        });
+        it('should handle null or undefined', () => {
+            expect((0, normalize_1.removeAccentsAndTrim)(null)).toBe('');
+            expect((0, normalize_1.removeAccentsAndTrim)(undefined)).toBe('');
+        });
+        it('should preserve case', () => {
+            expect((0, normalize_1.removeAccentsAndTrim)('HÉLLÔ')).toBe('HELLO');
+        });
+    });
+    describe('normalizeForSearch', () => {
+        it('should remove accents, trim whitespace, and convert to lowercase', () => {
+            expect((0, normalize_1.normalizeForSearch)('  HÉLLÔ WÔRLD  ')).toBe('hello world');
+        });
+        it('should handle empty string', () => {
+            expect((0, normalize_1.normalizeForSearch)('')).toBe('');
+        });
+        it('should handle null or undefined', () => {
+            expect((0, normalize_1.normalizeForSearch)(null)).toBe('');
+            expect((0, normalize_1.normalizeForSearch)(undefined)).toBe('');
+        });
+    });
+    describe('normalizeForCompactSearch', () => {
+        it('should remove accents, spaces, trim whitespace, and convert to lowercase', () => {
+            expect((0, normalize_1.normalizeForCompactSearch)('  HÉLLÔ WÔRLD  ')).toBe('helloworld');
+        });
+        it('should handle empty string', () => {
+            expect((0, normalize_1.normalizeForCompactSearch)('')).toBe('');
+        });
+        it('should handle null or undefined', () => {
+            expect((0, normalize_1.normalizeForCompactSearch)(null)).toBe('');
+            expect((0, normalize_1.normalizeForCompactSearch)(undefined)).toBe('');
+        });
+        it('should remove all types of whitespace', () => {
+            expect((0, normalize_1.normalizeForCompactSearch)('hello\tworld\nnew\rline')).toBe('helloworldnewline');
+        });
+    });
+    describe('normalizeForFileKey', () => {
+        it('should normalize text for file key usage', () => {
+            expect((0, normalize_1.normalizeForFileKey)('Héllô Wôrld!')).toBe('Hello-World');
+        });
+        it('should replace special characters with hyphens', () => {
+            expect((0, normalize_1.normalizeForFileKey)('file@name#with$special&chars')).toBe('file-name-with-special-chars');
+        });
+        it('should handle empty string', () => {
+            expect((0, normalize_1.normalizeForFileKey)('')).toBe('');
+        });
+        it('should handle null or undefined', () => {
+            expect((0, normalize_1.normalizeForFileKey)(null)).toBe('');
+            expect((0, normalize_1.normalizeForFileKey)(undefined)).toBe('');
+        });
+        it('should replace multiple consecutive hyphens with a single hyphen', () => {
+            expect((0, normalize_1.normalizeForFileKey)('multiple---hyphens')).toBe('multiple-hyphens');
+        });
+        it('should remove leading and trailing hyphens', () => {
+            expect((0, normalize_1.normalizeForFileKey)('-leading-and-trailing-')).toBe('leading-and-trailing');
+        });
+        it('should preserve periods and underscores', () => {
+            expect((0, normalize_1.normalizeForFileKey)('file.name_with.underscore')).toBe('file.name_with.underscore');
+        });
+    });
+    describe('removeAccentsOnly', () => {
+        it('should remove accents without trimming whitespace', () => {
+            expect((0, normalize_1.removeAccentsOnly)('  héllô wôrld  ')).toBe('  hello world  ');
+        });
+        it('should handle empty string', () => {
+            expect((0, normalize_1.removeAccentsOnly)('')).toBe('');
+        });
+        it('should handle null or undefined', () => {
+            expect((0, normalize_1.removeAccentsOnly)(null)).toBe('');
+            expect((0, normalize_1.removeAccentsOnly)(undefined)).toBe('');
+        });
+        it('should preserve case', () => {
+            expect((0, normalize_1.removeAccentsOnly)('HÉLLÔ')).toBe('HELLO');
+        });
+    });
+    describe('normalizeForSearchToken', () => {
+        it('should remove accents, trim, lowercase, and replace non-alphanumeric with spaces', () => {
+            expect((0, normalize_1.normalizeForSearchToken)('  HÉLLÔ-WÔRLD!  ')).toBe('hello world ');
+        });
+        it('should handle empty string', () => {
+            expect((0, normalize_1.normalizeForSearchToken)('')).toBe('');
+        });
+        it('should handle null or undefined', () => {
+            expect((0, normalize_1.normalizeForSearchToken)(null)).toBe('');
+            expect((0, normalize_1.normalizeForSearchToken)(undefined)).toBe('');
+        });
+        it('should replace all special characters with spaces', () => {
+            expect((0, normalize_1.normalizeForSearchToken)('hello@world#123')).toBe('hello world 123');
+        });
+    });
+});

package/lib/retries.d.ts

@@ -1 +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/lib/retries.js

@@ -1,6 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeWithRetries = void 0;
+/**
+ * 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
+ * );
+ */
 function executeWithRetries(fn, retries, timeout) {
     return new Promise((resolve, reject) => {
         const retry = async (retries) => {

package/lib/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 declare 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)[];
+};