cry-search 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Core types for cry-search library
+ */
+/** Unique identifier for searchable objects */
+export type Id = string;
+/** A single search token (preprocessed and sanitized) */
+export type SearchToken = string;
+/** Sorted array of search tokens for efficient matching */
+export type SearchTokenSortedList = SearchToken[];
+/** Numeric token ID (index into global tokens array) */
+export type NumericToken = number;
+/** Sorted Uint32Array of numeric token IDs for memory-efficient storage */
+export type NumericTokenSortedList = Uint32Array;
+/** Metadata mapping object IDs to their sorted token lists (string-based) */
+export type SearchMetadata = Map<Id, SearchTokenSortedList>;
+/** Metadata mapping object IDs to their sorted numeric token lists */
+export type NumericSearchMetadata = Map<Id, NumericTokenSortedList>;
+/** Map of objects by their ID for efficient lookup */
+export type SearchableData<T extends SearchableObject> = Map<Id, T>;
+/** Base interface for searchable objects - must have unique _id */
+export interface SearchableObject {
+    _id: Id;
+    _deleted?: Date;
+    _blocked?: Date;
+}
+/**
+ * Match mode for search tokens
+ * - 'start': match from beginning only - "rex" matches "rexona" but not "ceporex"
+ * - 'end': match from end only - "rex" matches "ceporex" but not "rexona"
+ * - 'startEnd': match from start OR end - "rex" matches both "rexona" and "ceporex" but not "unrexy"
+ * - 'anywhere': match anywhere - "rex" matches "unrexy", "ceporex", "rexona"
+ * - 'whole': exact match only - "rex" matches "rex" but not "rexona" or "ceporex"
+ */
+export type MatchMode = 'start' | 'end' | 'startEnd' | 'anywhere' | 'whole';
+/**
+ * Specification for how to extract searchable text from objects
+ */
+export interface SearchableObjectSpec<T extends SearchableObject, C = unknown> {
+    /** Fields to include in search (if not specified, all string fields are used) */
+    searchInFields?: (keyof T)[];
+    /** Fields to exclude from search */
+    dontSearchInFields?: (keyof T)[];
+    /** Optional context passed to enrichSearchObjectFn */
+    searchContext?: C;
+    /** Custom function to extract searchable string from object */
+    extractSearchableStringFn?: (obj: T) => string | undefined;
+    /** Function to enrich object with additional searchable fields before extraction */
+    enrichSearchObjectFn?: (obj: T, searchContext: C) => void;
+    /**
+     * Per-field match mode overrides. Tokens from these fields will have a prefix
+     * that forces the specified match mode, ignoring global SearchOpts.
+     * Prefixes: < (start), > (end), + (startEnd), * (anywhere), ! (whole)
+     */
+    fieldMatchModes?: Partial<Record<keyof T, MatchMode>>;
+}
+/**
+ * Options for controlling how search matching works
+ */
+export interface SearchOpts {
+    /**
+     * How to match words (non-numeric tokens)
+     * @default 'start'
+     */
+    matchWords?: MatchMode;
+    /**
+     * How to match numbers (numeric tokens)
+     * @default 'startEnd'
+     */
+    matchNumbers?: MatchMode;
+}
+/** Default search options */
+export declare const DEFAULT_SEARCH_OPTS: Required<SearchOpts>;
+/** Linked search metadata for searching across related arrays */
+export interface LinkedSearchMetadata {
+    /** Metadata for primary items */
+    primaryMeta: SearchMetadata;
+    /** Metadata for linked/secondary items */
+    linkedMeta: SearchMetadata;
+    /** Index: primary._id -> linked._id[] */
+    primaryToLinked: Map<Id, Id[]>;
+}
+/**
+ * Extended linked search metadata that includes data references for convenient access during search.
+ *
+ * Extends {@link LinkedSearchMetadata} with direct references to the primary and linked data maps,
+ * so search functions don't need to pass them separately.
+ *
+ * @typeParam TPrimary - Type of primary items (e.g., Stranka)
+ * @typeParam TLinked - Type of linked items (e.g., Pacient)
+ */
+export interface SearchLinkedMetadataWithData<TPrimary extends SearchableObject, TLinked extends SearchableObject> extends LinkedSearchMetadata {
+    /** Reference to primary data map */
+    primaryData: SearchableData<TPrimary>;
+    /** Reference to linked data map */
+    linkedData: SearchableData<TLinked>;
+}
+/**
+ * Specification for linked search across two related arrays
+ */
+export interface SearchableLinkedObjectsSpec<TPrimary extends SearchableObject, TLinked extends SearchableObject, CPrimary = unknown, CLinked = unknown> {
+    /** Spec for primary items */
+    primarySpec?: SearchableObjectSpec<TPrimary, CPrimary>;
+    /** Spec for linked items */
+    linkedSpec?: SearchableObjectSpec<TLinked, CLinked>;
+    /** Function to get primary ID from linked item (foreign key) */
+    foreignKeyGetter: (linked: TLinked) => Id | undefined;
+}
+/**
+ * Result of a linked search operation.
+ *
+ * Contains the primary item and the linked items that contributed to the match,
+ * along with information about where the match was found.
+ *
+ * @typeParam TPrimary - Type of primary items (e.g., Stranka)
+ * @typeParam TLinked - Type of linked items (e.g., Pacient)
+ */
+export interface LinkedSearchResult<TPrimary, TLinked> {
+    /** The primary item (e.g., stranka) */
+    primary: TPrimary;
+    /** Linked items that contributed to the match (not all linked items) */
+    linked: TLinked[];
+    /** Where the match was found: primary only, linked only, or both */
+    matchedIn: 'primary' | 'linked' | 'both';
+}
+/**
+ * Result of a linked search with query metadata.
+ *
+ * Includes the tokenized query for debugging/highlighting purposes.
+ *
+ * @typeParam TPrimary - Type of primary items (e.g., Stranka)
+ * @typeParam TLinked - Type of linked items (e.g., Pacient)
+ */
+export interface LinkedSearchResultWithMeta<TPrimary, TLinked> {
+    /** The search query tokens (after preprocessing) */
+    queryTokens: SearchTokenSortedList;
+    /** Array of matching results */
+    results: LinkedSearchResult<TPrimary, TLinked>[];
+}
+/**
+ * Result of a search operation with metadata included.
+ *
+ * Contains the tokenized query and matching items along with their
+ * pre-computed tokens. Useful for debugging, highlighting, or
+ * understanding why items matched.
+ *
+ * @typeParam T - Type of items being searched
+ */
+export interface SearchResultWithMeta<T extends SearchableObject> {
+    /** The search query tokens (after preprocessing) */
+    queryTokens: SearchTokenSortedList;
+    /** Array of matching items with their token metadata */
+    results: Array<{
+        /** The matched item */
+        item: T;
+        /** Pre-computed tokens for this item */
+        tokens: SearchTokenSortedList;
+    }>;
+}
+/**
+ * Result of a sync operation.
+ *
+ * Contains counts and IDs of items that were added, updated, or removed
+ * during the sync process.
+ */
+export interface SyncResult {
+    /** Number of items added */
+    added: number;
+    /** Number of items updated (tokens changed) */
+    updated: number;
+    /** Number of items removed */
+    removed: number;
+    /** IDs of added items */
+    addedIds: Id[];
+    /** IDs of updated items */
+    updatedIds: Id[];
+    /** IDs of removed items */
+    removedIds: Id[];
+}
+/**
+ * Options for sync operations.
+ */
+export interface SyncOptions {
+    /**
+     * If true, skips checking if existing items have changed.
+     * Useful when you know items haven't changed to save processing time.
+     * @default false
+     */
+    skipUpdateCheck?: boolean;
+}
+/**
+ * Result of syncing linked items for a primary.
+ */
+export interface SyncLinkedResult {
+    /** Number of new linked items added */
+    added: number;
+    /** Number of existing linked items updated */
+    updated: number;
+    /** Number of linked items removed */
+    removed: number;
+}
+/**
+ * Result of upserting an item to linked metadata.
+ */
+export interface UpsertResult {
+    /** True if the item was newly added, false if it was updated */
+    added: boolean;
+    /** Previous primary ID if the foreign key changed (only for linked items) */
+    previousPrimaryId?: Id | undefined;
+}
+/**
+ * Batch item for updating search metadata.
+ *
+ * @typeParam T - Type of the searchable object
+ */
+export interface UpdateSearchMetadataBatchItem<T extends SearchableObject> {
+    /** The ID of the object to update */
+    objectId: Id;
+    /** The object to update (may be null, undefined, deleted, or blocked - null/undefined removes from search) */
+    obj: T | null | undefined;
+}
+/**
+ * Extended search options for the {@link SearchUniverse.searchUniversally} method.
+ *
+ * Inherits all options from {@link SearchOpts} and adds collection filtering.
+ */
+export interface UniversalSearchOpts extends SearchOpts {
+    /**
+     * If specified, only search in these collections.
+     * Use collection name for standalone collections (e.g., "artikli")
+     * Use "linked-primary" format for linked collections (e.g., "pacienti-stranke", "racuni-pacienti")
+     */
+    inCollections?: string[];
+}
+/**
+ * Configuration for a collection in SearchUniverse.
+ *
+ * @typeParam T - Type of items in this collection
+ * @typeParam C - Type of the search context
+ */
+export interface CollectionConfig<T extends SearchableObject, C = unknown> {
+    /** Specification for how to extract searchable text */
+    spec?: SearchableObjectSpec<T, C>;
+    /** Links to other collections (this collection is the "linked" side) */
+    linkedTo?: {
+        /** Name of the primary collection */
+        collectionName: string;
+        /** Function to get primary ID from this item (foreign key) */
+        foreignKeyGetter: (item: T) => Id | undefined;
+    };
+}
+/**
+ * Result of an update operation via {@link SearchUniverse.updateSearchMetadata}.
+ */
+export interface UpdateResult {
+    /** true if item was added, false if updated */
+    added: boolean;
+    /** Previous foreign key value (only for linked items that changed FK) */
+    previousPrimaryId?: Id | undefined;
+}
+/**
+ * Result of a batch update operation via {@link SearchUniverse.updateSearchMetadataBatch}.
+ */
+export interface BatchUpdateResult {
+    /** Number of items added */
+    added: number;
+    /** Number of items updated */
+    updated: number;
+    /** Number of items removed (due to _deleted/_blocked) */
+    removed: number;
+}
+/**
+ * Helper to convert an array to SearchableData Map
+ */
+export declare function arrayToSearchableData<T extends SearchableObject>(items: T[]): SearchableData<T>;
+/**
+ * Helper to convert SearchableData Map back to array
+ */
+export declare function searchableDataToArray<T extends SearchableObject>(data: SearchableData<T>): T[];
+/**
+ * Legacy type alias for backwards compatibility.
+ * @deprecated Use SearchMetadata directly instead
+ */
+export type SearchArrayMetadata = {
+    items: SearchMetadata;
+};
+/**
+ * Legacy type alias for backwards compatibility.
+ * @deprecated Use SearchableObject directly instead
+ */
+export interface SearchableItem extends SearchableObject {
+    searchableText?: string;
+}
+/**
+ * Legacy type alias for backwards compatibility.
+ * @deprecated Use SearchTokenSortedList directly instead
+ */
+export interface SearchItemMetadata {
+    tokens: SearchTokenSortedList;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export all types from the types directory for backwards compatibility.
+ * @module
+ */
+export * from './types/index';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC"}

package/dist/utils/matchToken.d.ts

@@ -0,0 +1,65 @@
+import type { SearchOpts, SearchTokenSortedList } from '../types';
+/**
+ * Checks if a search token matches a target token.
+ *
+ * If target token has a prefix (<, >, +, *, !), that prefix determines the match mode
+ * and global SearchOpts are ignored for that token.
+ *
+ * Otherwise, matching rules depend on SearchOpts:
+ * - For words (non-numeric): uses matchWords option (default: 'start')
+ * - For numbers: uses matchNumbers option (default: 'startEnd')
+ *
+ * @param searchToken - The token to search for
+ * @param targetToken - The token to match against (may have a prefix)
+ * @param opts - Optional search options for match mode
+ * @returns True if the search token matches the target token
+ *
+ * @example
+ * ```typescript
+ * // Default word matching (start)
+ * matchToken('rex', 'rexona')    // true
+ * matchToken('rex', 'ceporex')   // false
+ *
+ * // Default number matching (startEnd)
+ * matchToken('123', '12345')     // true
+ * matchToken('123', '45123')     // true
+ *
+ * // With prefix (overrides opts)
+ * matchToken('rex', '!rex')      // true (whole match)
+ * matchToken('rex', '!rexona')   // false (whole match)
+ * matchToken('rex', '*unrexy')   // true (anywhere match)
+ * ```
+ */
+export declare function matchToken(searchToken: string, targetToken: string, opts?: SearchOpts): boolean;
+/**
+ * Checks if a search token matches any token in a sorted list.
+ * Leverages sorted order for early exit when using 'start' match mode.
+ *
+ * @param searchToken - The token to search for
+ * @param targetTokens - Sorted list of tokens to search in
+ * @param opts - Optional search options for match mode
+ * @returns True if any target token matches the search token
+ *
+ * @example
+ * ```typescript
+ * matchTokenInSortedList('rex', ['labrador', 'rexona'])  // true
+ * matchTokenInSortedList('cat', ['labrador', 'rexona']) // false
+ * ```
+ */
+export declare function matchTokenInSortedList(searchToken: string, targetTokens: SearchTokenSortedList, opts?: SearchOpts): boolean;
+/**
+ * Checks if all search tokens match at least one token in the target sorted list.
+ *
+ * @param searchTokens - Array of tokens to search for
+ * @param targetTokens - Sorted list of tokens to search in
+ * @param opts - Optional search options for match mode
+ * @returns True only if every search token has at least one match
+ *
+ * @example
+ * ```typescript
+ * allTokensMatch(['rex', 'lab'], ['labrador', 'rexona'])  // true
+ * allTokensMatch(['rex', 'cat'], ['labrador', 'rexona']) // false
+ * ```
+ */
+export declare function allTokensMatch(searchTokens: SearchTokenSortedList, targetTokens: SearchTokenSortedList, opts?: SearchOpts): boolean;
+//# sourceMappingURL=matchToken.d.ts.map

package/dist/utils/matchToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchToken.d.ts","sourceRoot":"","sources":["../../src/utils/matchToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,UAAU,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAuC7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAmBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,qBAAqB,EACnC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CA0CT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,qBAAqB,EACnC,YAAY,EAAE,qBAAqB,EACnC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAOT"}

package/dist/utils/matchTokenNumeric.d.ts

@@ -0,0 +1,94 @@
+import type { MatchMode, NumericTokenSortedList, SearchOpts } from '../types';
+/**
+ * A prepared query token with pre-computed ID and numeric flag.
+ * Used to avoid repeated findTokenId calls during search.
+ */
+export interface PreparedQueryToken {
+    str: string;
+    id: number;
+    isNumeric: boolean;
+    /** Optional override mode from query prefix (e.g., !word for whole match) */
+    overrideMode?: MatchMode;
+    /** If true, this token must NOT appear in the target (negation with -- or ~ prefix) */
+    negated?: boolean;
+}
+/**
+ * Prepares query tokens by pre-computing their IDs.
+ * Call this ONCE at the start of a search to avoid repeated findTokenId calls.
+ *
+ * Supports query prefixes/suffixes to override match modes:
+ * - `!word` or `=word` = whole (exact match)
+ * - `<word` = start (prefix match)
+ * - `>word` or `..word` = end (suffix match)
+ * - `+word` = startEnd (prefix or suffix)
+ * - `*word` or `?word` = anywhere (substring match)
+ * - `word..` = start (prefix match, suffix notation)
+ * - `--word` or `~word` = negation (token must NOT appear)
+ *
+ * @param queryTokenStrs - Array of query token strings
+ * @returns Array of prepared tokens with pre-computed IDs
+ */
+export declare function prepareQueryTokens(queryTokenStrs: string[]): PreparedQueryToken[];
+/**
+ * Binary search to find if a token ID exists in a sorted Uint32Array.
+ *
+ * @param arr - Sorted Uint32Array of token IDs
+ * @param target - Token ID to find
+ * @returns True if found, false otherwise
+ */
+export declare function binarySearchUint32(arr: Uint32Array, target: number): boolean;
+/**
+ * Checks if a prepared search token matches any token in a sorted numeric list.
+ * Uses pre-computed token ID for efficiency.
+ *
+ * @param preparedToken - The prepared token with pre-computed ID
+ * @param targetTokens - Sorted Uint32Array of target token IDs
+ * @param opts - Optional search options for match mode
+ * @returns True if any target token matches the search token
+ */
+export declare function matchPreparedTokenInSortedList(preparedToken: PreparedQueryToken, targetTokens: NumericTokenSortedList, opts?: SearchOpts): boolean;
+/**
+ * Checks if a search token (string) matches any token in a sorted numeric list.
+ * Note: For better performance when searching multiple items, use prepareQueryTokens
+ * and matchPreparedTokenInSortedList instead.
+ *
+ * Supports query prefixes/suffixes to override match modes:
+ * - `!word` or `=word` = whole
+ * - `<word` = start
+ * - `>word` or `..word` = end
+ * - `+word` = startEnd
+ * - `*word` or `?word` = anywhere
+ * - `word..` = start
+ * - `--word` or `~word` = negation (returns true if NOT found)
+ *
+ * @param searchTokenStr - The string token to search for (may include prefix/suffix)
+ * @param targetTokens - Sorted Uint32Array of target token IDs
+ * @param opts - Optional search options for match mode
+ * @returns True if any target token matches the search token (or no match for negated tokens)
+ */
+export declare function matchTokenInSortedListNumeric(searchTokenStr: string, targetTokens: NumericTokenSortedList, opts?: SearchOpts): boolean;
+/**
+ * Checks if all prepared search tokens match at least one token in the target sorted list.
+ * Uses pre-computed token IDs for efficiency.
+ *
+ * For negated tokens (--word or ~word), the logic is inverted:
+ * the token must NOT match any target token.
+ *
+ * @param preparedTokens - Array of prepared tokens with pre-computed IDs
+ * @param targetTokens - Sorted Uint32Array of target token IDs
+ * @param opts - Optional search options for match mode
+ * @returns True only if every search token has at least one match (or no match for negated tokens)
+ */
+export declare function allPreparedTokensMatch(preparedTokens: PreparedQueryToken[], targetTokens: NumericTokenSortedList, opts?: SearchOpts): boolean;
+/**
+ * Checks if all search tokens match at least one token in the target sorted list.
+ * Note: For better performance when searching multiple items, use prepareQueryTokens
+ * and allPreparedTokensMatch instead.
+ *
+ * @param searchTokenStrs - Array of string tokens to search for
+ * @param targetTokens - Sorted Uint32Array of target token IDs
+ * @param opts - Optional search options for match mode
+ * @returns True only if every search token has at least one match
+ */
+export declare function allTokensMatchNumeric(searchTokenStrs: string[], targetTokens: NumericTokenSortedList, opts?: SearchOpts): boolean;
+//# sourceMappingURL=matchTokenNumeric.d.ts.map

package/dist/utils/matchTokenNumeric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchTokenNumeric.d.ts","sourceRoot":"","sources":["../../src/utils/matchTokenNumeric.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAS9E;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,kBAAkB,EAAE,CAoDjF;AAmED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAiB5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,kBAAkB,EACjC,YAAY,EAAE,sBAAsB,EACpC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAmCT;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,sBAAsB,EACpC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAsDT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,kBAAkB,EAAE,EACpC,YAAY,EAAE,sBAAsB,EACpC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAYT;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,MAAM,EAAE,EACzB,YAAY,EAAE,sBAAsB,EACpC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAGT"}

package/dist/utils/normalizeDates.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Normalizes date patterns in a string to YYYYMMDD or YYYYMM format for searchability.
+ *
+ * This is the first step in the search preparation pipeline. Date normalization allows
+ * users to search for dates using partial prefixes (e.g., "202503" finds all March 2025 dates).
+ *
+ * Patterns recognized:
+ * | Input Format | Example | Normalized |
+ * |--------------|---------|------------|
+ * | ISO 8601 | `2025-12-27T11:35:25.814Z` | `20251227` |
+ * | ISO date only | `2025-12-27` | `20251227` |
+ * | ISO year-month | `2025-12` | `202512` |
+ * | d.m.yyyy | `1.3.2025` or `01.03.2025` | `20250301` |
+ * | d.m.yy | `27.12.25` | `20251227` (2-digit year assumes 2000s) |
+ * | m.yyyy | `3.2025` or `03.2025` | `202503` |
+ * | MM-YYYY | `11-2025` | `202511` (year must be 2001-2099) |
+ * | MM/YYYY | `11/2025` | `202511` (year must be 2001-2099) |
+ * | MM/YY | `11/25` | `202511` (2-digit year assumes 2000s) |
+ * | DDMMYYYY | `22112025` | `20251122` (DD 01-31, MM 01-12, year 20xx) |
+ * | MMYYYY | `112025` | `202511` (MM must be 01-12, year 20xx) |
+ * | month name + year | `mar 2025`, `march 2025`, `marec 2025` | `202503` |
+ *
+ * @param input - The string potentially containing date patterns
+ * @returns String with date patterns normalized to YYYYMMDD/YYYYMM format
+ *
+ * @example
+ * ```typescript
+ * normalizeDates('2025-12-27T11:35:25.814Z')
+ * // Returns: '20251227'
+ *
+ * normalizeDates('Datum: 1.3.2025 je pomemben')
+ * // Returns: 'Datum: 20250301 je pomemben'
+ *
+ * normalizeDates('v mar 2025 smo')
+ * // Returns: 'v 202503 smo'
+ * ```
+ */
+export declare function normalizeDates(input: string): string;
+//# sourceMappingURL=normalizeDates.d.ts.map

package/dist/utils/normalizeDates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeDates.d.ts","sourceRoot":"","sources":["../../src/utils/normalizeDates.ts"],"names":[],"mappings":"AA8EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkEpD"}

package/dist/utils/prepareStringForSearch.d.ts

@@ -0,0 +1,28 @@
+import type { SearchTokenSortedList } from '../types';
+/**
+ * Prepares a string for search by applying the full transformation pipeline.
+ *
+ * Processing pipeline:
+ * 1. **Date normalization** - Convert date patterns to YYYYMMDD/YYYYMM format
+ * 2. **Preprocessing** - Handle decimal commas, leading zeros, letter-digit boundaries
+ * 3. **Sanitation** - Lowercase, remove diacritics, keep only allowed characters
+ * 4. **Tokenization** - Split on spaces, trim, filter empty strings
+ * 5. **Sorting** - Sort alphabetically for efficient matching
+ *
+ * @param input - The raw input string to prepare for search
+ * @returns Sorted array of tokens ready for matching
+ *
+ * @example
+ * ```typescript
+ * prepareStringForSearch('Čokolada 100g SI123')
+ * // Returns: ['100', '123', 'cokolada', 'g', 'si']
+ *
+ * prepareStringForSearch('1.3.2025')
+ * // Returns: ['20250301']
+ *
+ * prepareStringForSearch('John Doe')
+ * // Returns: ['doe', 'john']
+ * ```
+ */
+export declare function prepareStringForSearch(input: string): SearchTokenSortedList;
+//# sourceMappingURL=prepareStringForSearch.d.ts.map

package/dist/utils/prepareStringForSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareStringForSearch.d.ts","sourceRoot":"","sources":["../../src/utils/prepareStringForSearch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAMtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAO3E"}

package/dist/utils/prepareStringForSearchNumeric.d.ts

@@ -0,0 +1,42 @@
+import type { NumericTokenSortedList } from '../types';
+/**
+ * Prepares a string for search, returning numeric token IDs.
+ *
+ * Processing pipeline:
+ * 1. **Date normalization** - Convert date patterns to YYYYMMDD/YYYYMM format
+ * 2. **Preprocessing** - Handle decimal commas, leading zeros, letter-digit boundaries
+ * 3. **Sanitation** - Lowercase, remove diacritics, keep only allowed characters
+ * 4. **Tokenization** - Split on spaces, trim, filter empty strings
+ * 5. **Numeric conversion** - Convert strings to numeric IDs via tokensMap
+ * 6. **Sorting** - Sort numerically for efficient matching
+ *
+ * @param input - The raw input string to prepare for search
+ * @param tokensMap - Map for string->number conversion (required for metadata creation)
+ * @returns Sorted Uint32Array of numeric token IDs
+ *
+ * @example
+ * ```typescript
+ * const tokensMap = createTokensMap();
+ * prepareStringForSearchNumeric('Čokolada 100g', tokensMap)
+ * // Returns: Uint32Array of numeric IDs, sorted
+ * ```
+ */
+export declare function prepareStringForSearchNumeric(input: string, tokensMap: Map<string, number>): NumericTokenSortedList;
+/**
+ * Prepares a search query string, returning numeric token IDs.
+ *
+ * Unlike prepareStringForSearchNumeric, this uses findTokenId for lookups
+ * since search queries should only match existing tokens.
+ * Tokens not in the registry are returned as -1.
+ *
+ * @param input - The raw search query string
+ * @returns Sorted array of numeric token IDs (-1 for unknown tokens)
+ *
+ * @example
+ * ```typescript
+ * prepareQueryForSearchNumeric('čokolada 100g')
+ * // Returns: sorted number[] of IDs (-1 for tokens not in registry)
+ * ```
+ */
+export declare function prepareQueryForSearchNumeric(input: string): number[];
+//# sourceMappingURL=prepareStringForSearchNumeric.d.ts.map

package/dist/utils/prepareStringForSearchNumeric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareStringForSearchNumeric.d.ts","sourceRoot":"","sources":["../../src/utils/prepareStringForSearchNumeric.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAOvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,sBAAsB,CAgBxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBpE"}

package/dist/utils/preprocessString.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Preprocesses a string for search by normalizing number formats and splitting mixed alphanumeric tokens.
+ *
+ * Processing steps:
+ * 1. Replaces decimal commas with periods (e.g., "12,3" → "12.3")
+ * 2. Drops leading zeros from numbers (e.g., "007" → "7", "0,3" → ".3")
+ * 3. Removes spaces in digit-dash-digit patterns (e.g., "12 - 25" → "12-25")
+ * 4. Inserts spaces at letter-to-digit boundaries (e.g., "SI123" → "SI 123", "123SI" → "123 SI")
+ *
+ * @param input - The raw input string to preprocess
+ * @returns Preprocessed string ready for sanitization
+ *
+ * @example
+ * ```typescript
+ * preprocessString('SI123 Čokolada 0,5kg')
+ * // Returns: 'SI 123 Čokolada .5kg'
+ *
+ * preprocessString('007')
+ * // Returns: '7'
+ *
+ * preprocessString('12 - 25')
+ * // Returns: '12-25'
+ * ```
+ */
+export declare function preprocessString(input: string): string;
+//# sourceMappingURL=preprocessString.d.ts.map

package/dist/utils/preprocessString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preprocessString.d.ts","sourceRoot":"","sources":["../../src/utils/preprocessString.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBtD"}