cry-search 1.0.1 → 1.0.3

package/CLAUDE.md

@@ -71,8 +71,8 @@ The numeric implementation uses a global token registry (`src/utils/tokenRegistr
       3. sanitation
          1. case-insensitive
          2. diacritics-insensitive (č,ć,c -> same c)
-tsc         3. we only keep letters (a-z), digits (0-9), periods (.), minuses (-), tildes (~), query prefixes (<>+*!=?), spaces (" ") in search
-         4. other characters are replaced with space (" ")
+         3. we only keep letters (`a-z`), digits (`0-9`), periods (`.`), minuses (`-`), tildes (`~`), query prefixes (`<>+*!=?`), spaces (` `) in search
+         4. other characters are replaced with space (` `)
    2. tokenization
       1. we split strings on spaces
       2. then we trim all substrings
@@ -130,6 +130,32 @@ tsc         3. we only keep letters (a-z), digits (0-9), periods (.), minuses (-
       4. example use case
          1. search "krajnik angie" matches stranka "Krajnik" with pacient "Angie"
          2. returns: { primary: Stranka, secondaries: [matching Pacient], matchedIn: 'both' }
+   9.  augmented metadata
+      1. purpose: add local/temporary searchable data to existing metadata without modifying the base metadata
+      2. use case: search for items combined with page-specific data (e.g., match status, local flags, computed properties)
+      3. class AugmentedMetadata
+         1. wraps existing NumericSearchMetadata
+         2. allows adding additional search tokens dynamically
+         3. memory efficient: items without augmentation reuse original Uint32Array
+         4. items with augmentation get merged sorted token array (base + augmented)
+         5. constructor takes: baseMetadata, optional spec, optional initial augmented data
+         6. spec controls tokenization: searchInFields, fieldMatchModes, etc.
+      4. updating augmented data
+         1. updateAugmented(id, obj) - single item update
+         2. updateAugmentedBatch(map) - batch update (more efficient)
+         3. clearAugmented(id) - remove augmentation for one item
+         4. clearAllAugmented() - remove all augmentations
+      5. searching
+         1. implements NumericSearchMetadata interface
+         2. works with all search functions (searchInDataReturnIds, etc.)
+         3. combines base + augmented tokens during search
+         4. supports all query prefixes and match modes
+      6. example use case
+         1. global zdravila metadata with names, manufacturers
+         2. page-local augmented metadata adds "uparjen"/"neuparjen" status
+         3. search "aspirin uparjen" finds Aspirin items with "uparjen" status
+         4. updating status doesn't modify global metadata
+         5. removing augmentation reverts to base metadata only
 
 ## Types
 
@@ -222,6 +248,54 @@ Override match behavior per token at search time. Priority: query prefix > field
 8. updateSearchMetadataBatch(metadata, batch, spec)
    1. creates temporary tokensMap, clears after use
    2. updates or deletes metadata for batch of objects
+9. syncSearchArrayMetadata(metadata, newData, spec?)
+   1. syncs metadata with new data (inkrementalno posodabljanje)
+   2. adds new items, updates changed items, removes old items
+   3. compares token arrays - skips unchanged items (performance optimization)
+   4. more efficient than full rebuild for partial updates
+   5. uses single tokensMap for all operations (memory efficient)
+10. syncSearchArrayMetadataWithPrevious(metadata, previousData, newData, options?, spec?)
+   1. more efficient than syncSearchArrayMetadata when you have both datasets
+   2. uses previousData to determine removals (no metadata.keys() iteration)
+   3. skipUpdateCheck option - skip checking for updates (even faster)
+   4. best for regular refresh cycles (e.g., every 30s from server)
+11. AugmentedMetadata class
+   1. constructor(baseMetadata, spec?, augmentedDataMap?)
+      1. baseMetadata: NumericSearchMetadata - base metadata to wrap (not modified)
+      2. spec?: SearchableObjectSpec - controls tokenization of augmented objects
+      3. augmentedDataMap?: Map<Id, any> - optional initial augmented data
+   2. updateAugmented(id, obj) - add/update augmented data for one item
+   3. updateAugmentedBatch(map) - batch update (more efficient than multiple single updates)
+   4. clearAugmented(id) - remove augmentation for one item
+   5. clearAllAugmented() - remove all augmentations
+   6. implements NumericSearchMetadata interface (get, has, size, keys, values, entries, forEach)
+   7. Map mutation methods (set, delete, clear) throw errors - use update methods instead
+12. Linked metadata update functions (incremental updates to linked metadata)
+   1. upsertPrimaryItem(linked, item, spec?)
+      1. adds or updates a primary item in linked metadata
+      2. updates primaryData, primaryMeta, and initializes primaryToLinked index
+      3. handles _deleted/_blocked by removing metadata
+      4. returns { added: boolean } - true if item was new
+   2. removePrimaryItem(linked, primaryId)
+      1. removes primary item from data, metadata, and primaryToLinked index
+      2. does NOT remove linked items (they become orphans)
+      3. returns true if found and removed, false otherwise
+   3. upsertLinkedItem(linked, item, foreignKeyGetter, spec?)
+      1. adds or updates a linked item in linked metadata
+      2. updates linkedData, linkedMeta, and primaryToLinked index
+      3. handles foreign key changes (moves item between primaries)
+      4. handles _deleted/_blocked by removing metadata
+      5. returns { added: boolean, previousPrimaryId?: Id }
+   4. removeLinkedItem(linked, linkedId, foreignKeyGetter)
+      1. removes linked item from data, metadata, and primaryToLinked index
+      2. returns true if found and removed, false otherwise
+   5. syncLinkedItemsForPrimary(linked, primaryId, newLinkedItems, foreignKeyGetter, spec?)
+      1. full sync of linked items for a single primary
+      2. removes items not in newLinkedItems
+      3. updates items with changed tokens
+      4. adds new items
+      5. only processes items whose foreign key matches primaryId
+      6. returns { added: number, updated: number, removed: number }
 
 ## Token Registry Functions
 
@@ -237,15 +311,38 @@ Override match behavior per token at search time. Priority: query prefix > field
 
 ## String Implementation (Legacy)
 
-Available with `*String` suffix:
+The string-based implementation is available as a separate entry point for backwards compatibility.
+
+**Import from `cry-search/string`:**
+```typescript
+import {
+  createSearchArrayMetadataString,
+  updateSearchMetadataString,
+  findInArray,
+  // ... other string-based functions
+} from 'cry-search/string';
+```
+
+**Available functions with `*String` suffix:**
 - createSearchArrayMetadataString
 - createSearchLinkedMetadataString
 - updateSearchMetadataString
 - updateSearchMetadataBatchString
+- syncSearchArrayMetadataString
+- syncSearchArrayMetadataStringWithPrevious
+- upsertPrimaryItemString
+- removePrimaryItemString
+- upsertLinkedItemString
+- removeLinkedItemString
+- syncLinkedItemsForPrimaryString
 - findInArray (uses string metadata)
 - findInArrayReturnDataAndMeta
 - findInLinkedArrays
 
+**Bundle sizes:**
+- Main bundle (`cry-search`): ~49 KB - includes only numeric implementation
+- String bundle (`cry-search/string`): ~26 KB - includes only string implementation
+
 ## File Structure
 
 ```
@@ -256,7 +353,10 @@ src/
 │   │   ├── createSearchArrayMetadata.ts
 │   │   ├── createSearchLinkedMetadata.ts
 │   │   ├── updateSearchMetadata.ts
-│   │   └── searchInData.ts
+│   │   ├── updateSearchLinkedMetadata.ts
+│   │   ├── searchInData.ts
+│   │   ├── syncSearchArrayMetadata.ts
+│   │   └── AugmentedMetadata.ts
 │   ├── string/            # Legacy string implementation
 │   │   ├── index.ts
 │   │   ├── createSearchArrayMetadata.ts

package/README.md

@@ -7,6 +7,7 @@ A fast, memory-efficient search library for large datasets with support for toke
 - **Fast search** - Pre-built metadata enables instant queries on large datasets
 - **Memory efficient** - Numeric token storage uses ~45% less memory than string-based approaches
 - **Updatable** - Add, update, or remove items without rebuilding metadata
+- **Augmented metadata** - Add local/temporary searchable data without modifying global metadata
 - **Flexible matching** - Per-field match modes and query prefixes for prefix, suffix, anywhere, exact, and negation
 - **Search prefixes** - use `-word`, `--word`, or `~word` to exclude, `..word` for suffix, `=word` for exact match
 - **Automatic normalization** - Handles diacritics, case, dates, and number formatting
@@ -22,6 +23,7 @@ A fast, memory-efficient search library for large datasets with support for toke
     - [Single Table Search](#single-table-search)
     - [SearchUniverse with Linked Collections](#searchuniverse-with-linked-collections)
     - [Updating Existing Data](#updating-existing-data)
+    - [Augmented Metadata - Local Search Context](#augmented-metadata---local-search-context)
   - [Architecture](#architecture)
     - [Text Processing Pipeline](#text-processing-pipeline)
     - [Metadata Building](#metadata-building)
@@ -196,6 +198,86 @@ universe.updateSearchMetadata('pacienti', 'p1', {
 });
 ```
 
+### Augmented Metadata - Local Search Context
+
+Sometimes you need to search items combined with page-specific data (like match status, local flags, computed properties) without modifying the global metadata. `AugmentedMetadata` wraps existing metadata and allows adding temporary searchable data.
+
+```typescript
+import {
+  createSearchArrayMetadata,
+  searchInDataReturnIds,
+  AugmentedMetadata,
+  arrayToSearchableData,
+  type SearchableObject,
+} from 'cry-search';
+
+interface Medicine extends SearchableObject {
+  _id: string;
+  name: string;
+  manufacturer: string;
+}
+
+// Global data - shared across application
+const medicines: Medicine[] = [
+  { _id: '1', name: 'Aspirin', manufacturer: 'Bayer' },
+  { _id: '2', name: 'Paracetamol', manufacturer: 'Krka' },
+  { _id: '3', name: 'Ibuprofen', manufacturer: 'Lek' },
+];
+
+const data = arrayToSearchableData(medicines);
+const globalMetadata = createSearchArrayMetadata(data);
+
+// Page-specific: matching medicines with external registry
+// Create augmented metadata with local match status
+const augmented = new AugmentedMetadata(
+  globalMetadata,
+  { searchInFields: ['status', 'notes'] }  // Control which fields to index
+);
+
+// User matches medicines with external registry
+augmented.updateAugmented('1', { status: 'matched', notes: 'verified' });
+augmented.updateAugmented('2', { status: 'unmatched', notes: '' });
+augmented.updateAugmented('3', { status: 'matching in progress', notes: 'awaiting approval' });
+
+// Search by base data + augmented status
+const matchedAspirin = searchInDataReturnIds('aspirin matched', augmented);
+// Returns: ['1']
+
+const unmatchedItems = searchInDataReturnIds('unmatched', augmented);
+// Returns: ['2']
+
+const inProgress = searchInDataReturnIds('progress', augmented);
+// Returns: ['3']
+
+// Search with negation
+const notMatched = searchInDataReturnIds('bayer -matched', augmented);
+// Returns: [] (Bayer Aspirin is matched)
+
+// Batch update for efficiency
+augmented.updateAugmentedBatch(new Map([
+  ['1', { status: 'matched', notes: 'final' }],
+  ['2', { status: 'matched', notes: 'approved' }],
+  ['3', undefined], // Remove augmentation
+]));
+
+// Clear specific item
+augmented.clearAugmented('1');  // Reverts to global metadata only
+
+// Clear all augmentations
+augmented.clearAllAugmented();  // Reset to global state
+
+// AugmentedMetadata is memory efficient:
+// - Items without augmentation reuse original Uint32Array (no memory duplication)
+// - Items with augmentation get merged sorted token array (base + augmented)
+// - Global metadata remains unchanged
+```
+
+**Use cases:**
+- Medicine matching with external registries (matched/unmatched status)
+- Products with local pricing or availability flags
+- Documents with review status or approval state
+- Items with computed scores or temporary categories
+
 ## Architecture
 
 cry-search uses a two-phase approach: **build** metadata once, then **search** instantly.
@@ -281,16 +363,18 @@ Priority: query prefix > field match mode > global SearchOpts default.
 
 ## Legacy String Implementation
 
-A string-based implementation is available for backwards compatibility. Import with the `String` suffix:
+A string-based implementation is available for backwards compatibility. Import from the `/string` subpath:
 
 ```typescript
 import {
   createSearchArrayMetadataString,
   updateSearchMetadataString,
   findInArray,  // String-based search function
-} from 'cry-search';
+} from 'cry-search/string';
 ```
 
+The string implementation is excluded from the main bundle. The default import (`cry-search`) only includes the modern numeric implementation, keeping bundle sizes smaller.
+
 ## Specification
 
 See [CLAUDE.md](./CLAUDE.md) for the complete technical specification including:

package/dist/common/numeric/AugmentedMetadata.d.ts

@@ -0,0 +1,111 @@
+import type { Id, NumericSearchMetadata, NumericTokenSortedList, SearchableObjectSpec } from '../../types/index.js';
+/**
+ * AugmentedMetadata wraps existing NumericSearchMetadata and allows adding
+ * additional search tokens dynamically without modifying the base metadata.
+ *
+ * Use case: Add local/temporary data (e.g., "uparjen"/"neuparjen" status) to
+ * existing global metadata for searching.
+ *
+ * Items without augmentation reuse the original Uint32Array (no memory duplication).
+ * Items with augmentation get a merged sorted token array.
+ *
+ * @example
+ * const augmented = new AugmentedMetadata(zdravilaMeta, { searchInFields: ['status', 'notes'] });
+ * augmented.updateAugmented(id1, { status: "uparjen", notes: "v teku" });
+ * augmented.updateAugmented(id2, { status: "neuparjen" });
+ *
+ * // Now search works with augmented tokens
+ * const results = searchInDataReturnIds("aspirin uparjen", augmented);
+ */
+export declare class AugmentedMetadata implements NumericSearchMetadata {
+    private baseMetadata;
+    private augmentedTokens;
+    private spec;
+    /**
+     * @param baseMetadata - Base search metadata (not modified)
+     * @param spec - Optional spec for tokenizing augmented objects (searchInFields, fieldMatchModes, etc.)
+     * @param augmentedDataMap - Optional initial augmented data map (id -> object)
+     */
+    constructor(baseMetadata: NumericSearchMetadata, spec?: SearchableObjectSpec<any>, augmentedDataMap?: Map<Id, any>);
+    /**
+     * Update augmented data for a single item.
+     * Pass undefined to remove augmentation for this item.
+     *
+     * @param id - Item ID
+     * @param augmentedData - Additional searchable object (will be tokenized using spec)
+     */
+    updateAugmented(id: Id, augmentedData: any): void;
+    /**
+     * Batch update augmented data for multiple items.
+     * More efficient than calling updateAugmented multiple times.
+     *
+     * @param augmentedDataMap - Map of id -> augmented object (will be tokenized using spec)
+     */
+    updateAugmentedBatch(augmentedDataMap: Map<Id, any>): void;
+    /**
+     * Remove augmentation for a single item (reverts to base metadata only).
+     */
+    clearAugmented(id: Id): void;
+    /**
+     * Remove all augmentations (reverts to base metadata for all items).
+     */
+    clearAllAugmented(): void;
+    /**
+     * Get merged tokens for an item (base + augmented).
+     * Returns undefined if item doesn't exist in base metadata.
+     */
+    get(id: Id): NumericTokenSortedList | undefined;
+    /**
+     * Check if item exists in base metadata.
+     */
+    has(id: Id): boolean;
+    /**
+     * Get number of items in base metadata.
+     */
+    get size(): number;
+    /**
+     * Iterate over all items (id -> merged tokens).
+     */
+    [Symbol.iterator](): MapIterator<[Id, NumericTokenSortedList]>;
+    /**
+     * Iterate over all IDs.
+     */
+    keys(): MapIterator<Id>;
+    /**
+     * Iterate over all merged token arrays.
+     */
+    values(): MapIterator<NumericTokenSortedList>;
+    /**
+     * Iterate over all [id, merged tokens] entries.
+     */
+    entries(): MapIterator<[Id, NumericTokenSortedList]>;
+    /**
+     * Execute callback for each item.
+     */
+    forEach(callbackfn: (value: NumericTokenSortedList, key: Id, map: Map<Id, NumericTokenSortedList>) => void): void;
+    /**
+     * Not supported - this is a read-only wrapper.
+     * Use updateAugmented() or updateAugmentedBatch() instead.
+     */
+    set(_key: Id, _value: NumericTokenSortedList): this;
+    /**
+     * Not supported - this is a read-only wrapper.
+     * Use clearAugmented() instead.
+     */
+    delete(_key: Id): boolean;
+    /**
+     * Not supported - this is a read-only wrapper.
+     * Use clearAllAugmented() instead.
+     */
+    clear(): void;
+    /**
+     * Symbol.toStringTag for Map interface.
+     */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Merge two sorted Uint32Arrays into a new sorted Uint32Array.
+     * Removes duplicates.
+     */
+    private mergeSortedTokenArrays;
+}
+//# sourceMappingURL=AugmentedMetadata.d.ts.map

package/dist/common/numeric/AugmentedMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AugmentedMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/AugmentedMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAInH;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,IAAI,CAAuC;IAEnD;;;;OAIG;gBAED,YAAY,EAAE,qBAAqB,EACnC,IAAI,CAAC,EAAE,oBAAoB,CAAC,GAAG,CAAC,EAChC,gBAAgB,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC;IAWjC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,GAAG,IAAI;IAkBjD;;;;;OAKG;IACH,oBAAoB,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI;IAqB1D;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI;IAI5B;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,sBAAsB,GAAG,SAAS;IAW/C;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO;IAIpB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAC;IAwB9D;;OAEG;IACH,IAAI,IAAI,WAAW,CAAC,EAAE,CAAC;IAIvB;;OAEG;IACH,MAAM,IAAI,WAAW,CAAC,sBAAsB,CAAC;IAsB7C;;OAEG;IACH,OAAO,IAAI,WAAW,CAAC,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAC;IAIpD;;OAEG;IACH,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,sBAAsB,CAAC,KAAK,IAAI,GAAG,IAAI;IAMjH;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAInD;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO;IAIzB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED;;;OAGG;IACH,OAAO,CAAC,sBAAsB;CAoD/B"}

package/dist/common/numeric/index.d.ts

@@ -6,4 +6,7 @@ export { createSearchLinkedMetadataNumeric, type NumericLinkedSearchMetadataWith
 export { updateSearchMetadataNumeric, updateSearchMetadataBatchNumeric, removeFromSearchMetadataNumeric, removeFromSearchMetadataBatchNumeric, } from './updateSearchMetadata';
 export { searchInDataReturnIdsNumeric, searchInDataReturnObjectsNumeric, searchInDataReturnIdsWithLimitNumeric, } from './searchInData';
 export { findInLinkedArraysNumeric, findInLinkedArraysSimpleNumeric, } from './findInLinkedArrays';
+export { AugmentedMetadata } from './AugmentedMetadata';
+export { syncSearchArrayMetadataNumeric, syncSearchArrayMetadataNumericWithPrevious, } from './syncSearchArrayMetadata';
+export { upsertPrimaryItemNumeric, removePrimaryItemNumeric, upsertLinkedItemNumeric, removeLinkedItemNumeric, syncLinkedItemsForPrimaryNumeric, } from './updateSearchLinkedMetadata';
 //# sourceMappingURL=index.d.ts.map

package/dist/common/numeric/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gCAAgC,EAChC,6BAA6B,EAC7B,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,iCAAiC,EACjC,KAAK,mCAAmC,GACzC,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,2BAA2B,EAC3B,gCAAgC,EAChC,+BAA+B,EAC/B,oCAAoC,GACrC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gCAAgC,EAChC,6BAA6B,EAC7B,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,iCAAiC,EACjC,KAAK,mCAAmC,GACzC,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,2BAA2B,EAC3B,gCAAgC,EAChC,+BAA+B,EAC/B,oCAAoC,GACrC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EACL,8BAA8B,EAC9B,0CAA0C,GAC3C,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,gCAAgC,GACjC,MAAM,8BAA8B,CAAC"}

package/dist/common/numeric/syncSearchArrayMetadata.d.ts

@@ -0,0 +1,64 @@
+import type { NumericSearchMetadata, SearchableData, SearchableObject, SearchableObjectSpec, SyncResult, SyncOptions } from '../../types/index.js';
+export type { SyncResult, SyncOptions } from '../../types/index.js';
+/**
+ * Syncs numeric search metadata with new data.
+ *
+ * This function performs a full sync of metadata against the provided data:
+ * - Adds metadata for new items
+ * - Removes metadata for items no longer in data (or marked `_deleted`/`_blocked`)
+ * - Updates metadata for items whose tokens have changed
+ *
+ * Use this when you have completely new data to sync with. If you have both
+ * previous and new data available, use {@link syncSearchArrayMetadataNumericWithPrevious}
+ * for more efficient diffing.
+ *
+ * @typeParam T - Type of the searchable objects
+ * @typeParam C - Type of the search context
+ *
+ * @param metadata - The NumericSearchMetadata map to update (mutated in place)
+ * @param newData - The new data to sync with
+ * @param spec - Optional specification for how to extract searchable text
+ * @returns SyncResult with counts and IDs of added/updated/removed items
+ *
+ * @example
+ * ```typescript
+ * const newProducts = arrayToSearchableData(freshProductsFromServer);
+ * const result = syncSearchArrayMetadataNumeric(metadata, newProducts, spec);
+ *
+ * console.log(`Added: ${result.added}, Updated: ${result.updated}, Removed: ${result.removed}`);
+ * ```
+ */
+export declare function syncSearchArrayMetadataNumeric<T extends SearchableObject, C = unknown>(metadata: NumericSearchMetadata, newData: SearchableData<T>, spec?: SearchableObjectSpec<T, C>): SyncResult;
+/**
+ * Syncs numeric search metadata using previous and new data for efficient diffing.
+ *
+ * More efficient than {@link syncSearchArrayMetadataNumeric} when you have both the
+ * previous and new data available. Uses the previous data to determine
+ * what was removed without iterating through all metadata keys.
+ *
+ * @typeParam T - Type of the searchable objects
+ * @typeParam C - Type of the search context
+ *
+ * @param metadata - The NumericSearchMetadata map to update (mutated in place)
+ * @param previousData - The previous data (used to determine what was removed)
+ * @param newData - The new data to sync with
+ * @param options - Optional sync options (e.g., skipUpdateCheck)
+ * @param spec - Optional specification for how to extract searchable text
+ * @returns SyncResult with counts and IDs of added/updated/removed items
+ *
+ * @example
+ * ```typescript
+ * const previousProducts = currentData;
+ * const newProducts = arrayToSearchableData(freshProductsFromServer);
+ *
+ * const result = syncSearchArrayMetadataNumericWithPrevious(
+ *   metadata,
+ *   previousProducts,
+ *   newProducts,
+ *   { skipUpdateCheck: false },
+ *   spec
+ * );
+ * ```
+ */
+export declare function syncSearchArrayMetadataNumericWithPrevious<T extends SearchableObject, C = unknown>(metadata: NumericSearchMetadata, previousData: SearchableData<T>, newData: SearchableData<T>, options?: SyncOptions, spec?: SearchableObjectSpec<T, C>): SyncResult;
+//# sourceMappingURL=syncSearchArrayMetadata.d.ts.map

package/dist/common/numeric/syncSearchArrayMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncSearchArrayMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/syncSearchArrayMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EAEpB,UAAU,EACV,WAAW,EACZ,MAAM,sBAAsB,CAAA;AAK7B,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAkBnE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACpF,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,UAAU,CAoDZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,0CAA0C,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EAChG,QAAQ,EAAE,qBAAqB,EAC/B,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC,EAC/B,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,WAAW,EACrB,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,UAAU,CAsDZ"}

package/dist/common/numeric/updateSearchLinkedMetadata.d.ts

@@ -0,0 +1,130 @@
+import type { Id, SearchableData, SearchableObject, SearchableObjectSpec, UpsertResult, SyncLinkedResult } from '../../types/index.js';
+import type { NumericLinkedSearchMetadataWithData } from './createSearchLinkedMetadata.js';
+export type { UpsertResult, SyncLinkedResult } from '../../types/index.js';
+/**
+ * Upserts a primary item into the linked metadata (numeric version).
+ *
+ * - If the item doesn't exist, adds it to data, metadata, and initializes primaryToLinked index
+ * - If the item exists, updates data and metadata
+ * - Handles `_deleted`/`_blocked` items by removing their metadata
+ *
+ * @typeParam TPrimary - Type of primary items
+ * @typeParam TLinked - Type of linked items
+ * @typeParam C - Type of the search context
+ *
+ * @param linked - The linked metadata to update (mutated in place)
+ * @param item - The primary item to upsert
+ * @param spec - Optional specification for how to extract searchable text
+ * @returns UpsertResult indicating if item was added or updated
+ *
+ * @example
+ * ```typescript
+ * const stranka = { _id: 's1', ime: 'Janez', priimek: 'Novak' };
+ * const result = upsertPrimaryItemNumeric(linkedMeta, stranka, spec);
+ * // result.added === true if stranka was new
+ * ```
+ */
+export declare function upsertPrimaryItemNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject, C = unknown>(linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, item: TPrimary, spec?: SearchableObjectSpec<TPrimary, C>): UpsertResult;
+/**
+ * Removes a primary item from the linked metadata (numeric version).
+ *
+ * Removes the item from data, metadata, and the primaryToLinked index.
+ * Note: This does NOT automatically remove linked items - they will become orphans.
+ * If you want to also remove linked items, call {@link removeLinkedItemNumeric} for each.
+ *
+ * @typeParam TPrimary - Type of primary items
+ * @typeParam TLinked - Type of linked items
+ *
+ * @param linked - The linked metadata to update (mutated in place)
+ * @param primaryId - The ID of the primary item to remove
+ * @returns true if item was found and removed, false if not found
+ */
+export declare function removePrimaryItemNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject>(linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, primaryId: Id): boolean;
+/**
+ * Upserts a linked item into the linked metadata (numeric version).
+ *
+ * - If the item doesn't exist, adds it
+ * - If the item exists, updates it
+ * - Handles foreign key changes by updating the primaryToLinked index
+ *   (removes from old primary's list, adds to new primary's list)
+ * - Handles `_deleted`/`_blocked` items by removing their metadata
+ *
+ * @typeParam TPrimary - Type of primary items
+ * @typeParam TLinked - Type of linked items
+ * @typeParam C - Type of the search context
+ *
+ * @param linked - The linked metadata to update (mutated in place)
+ * @param item - The linked item to upsert
+ * @param foreignKeyGetter - Function to get the primary ID from a linked item
+ * @param spec - Optional specification for how to extract searchable text
+ * @returns UpsertResult indicating if item was added or updated, and previous primary ID if FK changed
+ *
+ * @example
+ * ```typescript
+ * const pacient = { _id: 'p1', ime: 'Rex', stranka_id: 's1' };
+ * const result = upsertLinkedItemNumeric(linkedMeta, pacient, (p) => p.stranka_id, spec);
+ *
+ * // If the pacient moved to a different stranka:
+ * pacient.stranka_id = 's2';
+ * const result2 = upsertLinkedItemNumeric(linkedMeta, pacient, (p) => p.stranka_id, spec);
+ * // result2.previousPrimaryId === 's1'
+ * ```
+ */
+export declare function upsertLinkedItemNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject, C = unknown>(linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, item: TLinked, foreignKeyGetter: (item: TLinked) => Id | undefined, spec?: SearchableObjectSpec<TLinked, C>): UpsertResult;
+/**
+ * Removes a linked item from the linked metadata (numeric version).
+ *
+ * Removes the item from data, metadata, and the primaryToLinked index.
+ *
+ * @typeParam TPrimary - Type of primary items
+ * @typeParam TLinked - Type of linked items
+ *
+ * @param linked - The linked metadata to update (mutated in place)
+ * @param linkedId - The ID of the linked item to remove
+ * @param foreignKeyGetter - Function to get the primary ID from a linked item
+ * @returns true if item was found and removed, false if not found
+ *
+ * @example
+ * ```typescript
+ * removeLinkedItemNumeric(linkedMeta, 'pacient-id', (p) => p.stranka_id);
+ * ```
+ */
+export declare function removeLinkedItemNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject>(linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, linkedId: Id, foreignKeyGetter: (item: TLinked) => Id | undefined): boolean;
+/**
+ * Syncs all linked items for a specific primary item (numeric version).
+ *
+ * This function performs a full sync of linked items belonging to a single primary:
+ * - Removes linked items that are no longer in the new data
+ * - Updates existing linked items if their tokens changed
+ * - Adds new linked items
+ * - Only processes items whose foreign key points to the given primary
+ *
+ * Use this when you have a complete new set of linked items for a primary
+ * and want to update the metadata to match.
+ *
+ * @typeParam TPrimary - Type of primary items
+ * @typeParam TLinked - Type of linked items
+ * @typeParam C - Type of the search context
+ *
+ * @param linked - The linked metadata to update (mutated in place)
+ * @param primaryId - The primary ID to sync linked items for
+ * @param newLinkedItems - The new linked items (only items with matching FK will be processed)
+ * @param foreignKeyGetter - Function to get the primary ID from a linked item
+ * @param spec - Optional specification for how to extract searchable text
+ * @returns SyncLinkedResult with counts of added/updated/removed items
+ *
+ * @example
+ * ```typescript
+ * const newPacienti = arrayToSearchableData(freshPacientiFromServer);
+ * const result = syncLinkedItemsForPrimaryNumeric(
+ *   linkedMeta,
+ *   'stranka-1',
+ *   newPacienti,
+ *   (p) => p.stranka_id,
+ *   spec
+ * );
+ * console.log(`Added: ${result.added}, Updated: ${result.updated}, Removed: ${result.removed}`);
+ * ```
+ */
+export declare function syncLinkedItemsForPrimaryNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject, C = unknown>(linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, primaryId: Id, newLinkedItems: SearchableData<TLinked>, foreignKeyGetter: (item: TLinked) => Id | undefined, spec?: SearchableObjectSpec<TLinked, C>): SyncLinkedResult;
+//# sourceMappingURL=updateSearchLinkedMetadata.d.ts.map

package/dist/common/numeric/updateSearchLinkedMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateSearchLinkedMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/updateSearchLinkedMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAEjB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,iCAAiC,CAAA;AAK1F,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAkB1E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAChC,CAAC,GAAG,OAAO,EAEX,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,CAAC,GACvC,YAAY,CAwBd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAChC,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,EAAE,GAAG,OAAO,CAUxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAChC,CAAC,GAAG,OAAO,EAEX,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,IAAI,EAAE,OAAO,EACb,gBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,EAAE,GAAG,SAAS,EACnD,IAAI,CAAC,EAAE,oBAAoB,CAAC,OAAO,EAAE,CAAC,CAAC,GACtC,YAAY,CA0Dd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAEhC,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,QAAQ,EAAE,EAAE,EACZ,gBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,EAAE,GAAG,SAAS,GAClD,OAAO,CAyBT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAChC,CAAC,GAAG,OAAO,EAEX,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,SAAS,EAAE,EAAE,EACb,cAAc,EAAE,cAAc,CAAC,OAAO,CAAC,EACvC,gBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,EAAE,GAAG,SAAS,EACnD,IAAI,CAAC,EAAE,oBAAoB,CAAC,OAAO,EAAE,CAAC,CAAC,GACtC,gBAAgB,CA8DlB"}