cry-search 1.0.7 → 1.0.8

package/CLAUDE.md

@@ -19,18 +19,13 @@ Documentation is spread across multiple files that must be kept in sync:
 
 ## Architecture
 
-The library has two implementations:
-1. **Numeric (default)** - Memory-optimized using Uint32Array for token storage
-   - Location: `src/common/numeric/`
-   - ~45% less memory than string implementation
-   - Global token registry with array-based lookups
-   - Tokens stored as numeric IDs in Uint32Array
-2. **String (legacy)** - Original string-based implementation
-   - Location: `src/common/string/`
-   - Uses string arrays for token storage
-   - Available with `*String` suffix (e.g., `createSearchArrayMetadataString`)
+The library has a single implementation: memory-optimized using `Uint32Array` for token storage.
+- Location: `src/common/numeric/`
+- Global token registry (`src/utils/tokenRegistry.ts`) with array-based lookups
+- Tokens stored as numeric IDs in `Uint32Array` per item; strings interned globally
+- Match modes encoded in high 3 bits of each Uint32 token ID
 
-### Token Registry (Numeric Implementation)
+### Token Registry
 
 The numeric implementation uses a global token registry (`src/utils/tokenRegistry.ts`):
 - `tokens: string[]` - Global array of all tokens (preallocated 10k)
@@ -176,10 +171,10 @@ The numeric implementation uses a global token registry (`src/utils/tokenRegistr
 
 1. Id: string
 2. NumericToken: number (index into global tokens array)
-3. NumericTokenSortedList: Uint32Array (sorted numeric token IDs)
-4. NumericSearchMetadata: Map<Id, NumericTokenSortedList> (default SearchMetadata)
-5. StringSearchMetadata: Map<Id, string[]> (legacy, string-based)
-6. LinkedSearchMetadata: { primaryMeta, linkedMeta, primaryToLinked: Map<Id, Id[]> }
+3. NumericTokenSortedList: Uint32Array (sorted ASC numeric token IDs — retrieval)
+4. NumericTokenUnsortedList: Uint32Array (first-N tokens in SOURCE order — positional scoring)
+5. NumericSearchMetadata: { sorted: Map<Id, NumericTokenSortedList>, unsorted: Map<Id, NumericTokenUnsortedList> }
+6. NumericLinkedSearchMetadataWithData: { primaryMeta, linkedMeta, primaryToLinked, primaryData, linkedData }
 7. SearchableObject: { _id: Id, _deleted?: Date, _blocked?: Date }
 8. SearchableData<T>: Map<Id, T> where T extends SearchableObject
 9. SearchableObjectSpec<T extends SearchableObject, C = any>:
@@ -189,6 +184,8 @@ The numeric implementation uses a global token registry (`src/utils/tokenRegistr
    4. extractSearchableStringFn?: (obj: SearchableObject) => string | undefined
    5. enrichSearchObjectFn?: (obj: SearchableObject, searchContext: C) => void
    6. fieldMatchModes?: Partial<Record<keyof T | string, MatchMode>> - per-field match modes
+   7. keyFields?: (keyof T | string)[] - fields whose tokens populate `metadata.unsorted` (source order) for positional ranking
+   8. firstTokensN?: number (default 8) - cap on per-item `metadata.unsorted` length
 10. MatchMode: 'start' | 'end' | 'startEnd' | 'anywhere' | 'whole'
     1. Field token prefixes: '<' (start), '>' (end), '+' (startEnd), '*' (anywhere), '!' (whole)
     2. Numeric: encoded in high 3 bits of Uint32 token ID
@@ -252,14 +249,20 @@ Override match behavior per token at search time. Priority: query prefix > field
    2. stores tokens as Uint32Array per item
    3. clears tokensMap after use (only global tokens[] remains)
    4. for _deleted or _blocked nothing is added
-3. prepareObjectForSearch(obj, spec?, tokensMap): NumericTokenSortedList | undefined
+3. prepareObjectForSearch(obj, spec?, tokensMap): { sorted, firstN } | undefined
    1. returns undefined if _deleted or _blocked
-   2. if custom extractSearchableStringFn provided, uses simple processing
-   3. otherwise processes fields individually to support per-field match modes
-   4. recursively extracts strings from nested objects/arrays
-4. searchInData / searchInDataReturnIds(query: string, metadata): Id[]
-5. searchInDataReturnObjects<T>(query, metadata, data): Map<Id, T>
-6. searchInDataWithLimit(query, metadata, limit): Id[]
+   2. sorted: full sorted token IDs (with per-field mode bits)
+   3. firstN: first N ordered tokens from spec.keyFields (undefined if keyFields not set)
+   4. if custom extractSearchableStringFn provided, uses simple processing
+   5. otherwise processes fields individually to support per-field match modes
+   6. recursively extracts strings from nested objects/arrays
+4. searchInData / searchInDataReturnIds(query, metadata, opts?): Id[]
+   1. returns RANKED IDs (by score DESC) when metadata.unsorted is populated
+   2. falls back to insertion order when no keyFields declared
+5. searchInDataReturnObjects<T>(query, metadata, data, opts?): Map<Id, T>
+   1. iteration order = relevance DESC
+6. searchInDataWithLimit(query, metadata, limit, opts?): Id[]
+   1. ranks all candidates first, then slices to limit (so top N are truly best)
 7. updateSearchMetadata(metadata, objectId, obj, spec)
    1. updates or deletes metadata for this object
    2. taking into account _blocked and _deleted
@@ -277,7 +280,7 @@ Override match behavior per token at search time. Priority: query prefix > field
    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
+11. AugmentedMetadata class (implements NumericSearchMetadata)
    1. constructor(baseMetadata, spec?, augmentedDataMap?)
       1. baseMetadata: NumericSearchMetadata - base metadata to wrap (not modified)
       2. spec?: SearchableObjectSpec - controls tokenization of augmented objects
@@ -286,8 +289,10 @@ Override match behavior per token at search time. Priority: query prefix > field
    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
+   6. fields:
+      - sorted: Map subclass that lazily merges base + augmented tokens on .get()
+      - unsorted: direct reference to base.unsorted (augmentation does NOT participate in positional ranking)
+   7. sorted.set / sorted.delete / sorted.clear throw — augmentation must go through update methods
 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
@@ -315,30 +320,39 @@ Override match behavior per token at search time. Priority: query prefix > field
       5. only processes items whose foreign key matches primaryId
       6. returns { added: number, updated: number, removed: number }
 
-13. searchAndRank(query, data, metadata, options): ScoredResult<T>[]
+13. findInLinkedArrays(query, linkedMeta, limit?, opts?): LinkedSearchResultWithMeta
+    1. returns RANKED results (by combined primary.unsorted + matched-linked.unsorted score)
+    2. ordering: score DESC, primary insertion-order ASC as deterministic tiebreaker
+    3. matchedIn: 'primary' | 'linked' | 'both' — where positive tokens matched
+    4. tokens that match in primary are excluded from linked matching to prevent FK redundancy
+14. searchAndRank(query, data, metadata, options): ScoredResult<T>[]
     1. searchAndRank = searchAndRankNumeric (alias for the numeric implementation)
-    2. wraps searchInDataReturnIds + positional scoring over the candidate set
+    2. like searchInDataReturnIdsNumeric but adds:
+       - exactKeysFn boost (+100_000 when raw query equals any extracted value)
+       - locale-aware primary-text tiebreaker
+       - fallback to orderedTokenize(primaryTextFn(item)) when metadata.unsorted is empty
     3. options: { primaryTextFn, exactKeysFn?, limit?, opts? }
-       - primaryTextFn: (item) => string (e.g. item.naziv) — used for positional scoring
-       - exactKeysFn: (item) => readonly string[] | undefined (e.g. crtnaKoda)
-         exact equality with raw query returns score 100_000
-    4. results sorted by score desc, locale-aware primary-text asc as tiebreaker
-    5. scoring components (additive):
-       - +100_000 exact key match
-       - +50 base for any subsequence-prefix match in primary text
-       - +100 all query tokens matched (in order)
-       - +50 first matched position is 0
-       - +80 perfect prefix (positions === [0..k-1])
-       - +30 * (matchedCount / span) density
-       - -0.1 * primaryText.length length penalty
-    6. returns 1 if candidate matched only via secondary field (no primary token match)
-14. orderedTokenize(input: string): string[]
+    4. results sorted by score desc, primaryTextFn(item) localeCompare asc as tiebreaker
+15. orderedTokenize(input: string): string[]
     1. prepareStringForSearch pipeline minus the trailing .sort()
     2. required for any positional / order-aware scoring
     3. do NOT use these tokens for candidate retrieval (sorted lists required)
-15. scoreOne(item, query, qTokens, primaryTextFn, exactKeys?): number
-    1. single-item scoring primitive — use to compose custom rankers
-    2. callers must pre-tokenize the query with orderedTokenize for correct positional semantics
+16. Scoring primitives (in src/common/numeric/scoring.ts, re-exported from main)
+    1. scoreOne(query, qTokens, itemTokens, exactKeys?): number
+       - feature-rich scoring: +100_000 exact, +50 base, +100 all-matched, +50 first-word,
+         +80 perfect prefix, +30*(matched/span) density, -0.1*Σitemtoken.length penalty
+       - returns 1 when no primary token matched (secondary-field-only signal)
+       - DEFAULT used internally by searchInData* and findInLinkedArrays
+    2. scoreOrderAndPresence(qTokens, itemTokens, weights?): number
+       - additive bonus: weights.ordered (default 30) per in-order match,
+         weights.presence (default 10) per out-of-order presence
+       - each query token contributes at most once
+       - "izdaja recepta":"izdaja recepta"=60, ":izdaja"=30, ":recepta izdaja"=40
+    3. scoreBag(qTokens, itemTokens, perTokenWeight=30): number
+       - ORDER-AGNOSTIC: same score regardless of query/item token order
+       - use for person names, tags, breeds where word order is conventional but not semantic
+       - "Janez Novak" vs "Novak Janez" = SAME score (invariant verified by tests)
+       - each item token consumed by at most one query token (greedy left-to-right)
 
 ## Token Registry Functions
 
@@ -352,75 +366,36 @@ Override match behavior per token at search time. Priority: query prefix > field
 8. clearTokensMap(tokensMap): void
 9. resetTokenRegistry(): void (for testing only)
 
-## String Implementation (Legacy)
-
-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
 
 ```
 src/
 ├── common/
-│   ├── numeric/           # Default numeric implementation
+│   ├── numeric/                       # Numeric implementation (only impl)
 │   │   ├── index.ts
 │   │   ├── createSearchArrayMetadata.ts
 │   │   ├── createSearchLinkedMetadata.ts
 │   │   ├── updateSearchMetadata.ts
 │   │   ├── updateSearchLinkedMetadata.ts
-│   │   ├── searchInData.ts
-│   │   ├── searchAndRank.ts        # Ranked search with positional scoring
+│   │   ├── searchInData.ts            # Ranked search via metadata.unsorted
+│   │   ├── findInLinkedArrays.ts      # Ranked linked search
+│   │   ├── searchAndRank.ts           # Wrapper w/ exactKeysFn boost + fallback
+│   │   ├── scoring.ts                 # scoreOne, scoreOrderAndPresence, scoreBag
 │   │   ├── syncSearchArrayMetadata.ts
 │   │   └── AugmentedMetadata.ts
-│   ├── string/            # Legacy string implementation
-│   │   ├── index.ts
-│   │   ├── createSearchArrayMetadata.ts
-│   │   ├── createSearchLinkedMetadata.ts
-│   │   └── updateSearchMetadata.ts
-│   ├── findInArray.ts           # String-based search
-│   ├── findInLinkedArrays.ts    # String-based linked search
-│   ├── syncSearchArrayMetadata.ts
-│   ├── updateSearchLinkedMetadata.ts
-│   └── SearchUniverse.ts        # Multi-collection manager (uses numeric)
+│   └── SearchUniverse.ts              # Multi-collection manager
 ├── utils/
-│   ├── tokenRegistry.ts         # Global tokens array
-│   ├── prepareStringForSearch.ts
-│   ├── prepareStringForSearchNumeric.ts
-│   ├── matchToken.ts            # String-based matching
-│   ├── matchTokenNumeric.ts     # Numeric matching
-│   └── ...
+│   ├── tokenRegistry.ts               # Global tokens array
+│   ├── prepareStringForSearch.ts      # Shared query tokenization (returns sorted strings)
+│   ├── prepareStringForSearchNumeric.ts  # For metadata build (returns Uint32Array of token IDs)
+│   ├── matchTokenNumeric.ts
+│   ├── normalizeDates.ts
+│   ├── preprocessString.ts
+│   ├── sanitiseString.ts
+│   └── tokenize.ts
 ├── types/
 │   └── index.ts
-└── index.ts                     # Main exports (numeric as default)
+└── index.ts                           # Public API
 ```
 
 ## Coding rules

package/README.md

@@ -5,7 +5,7 @@ A fast, memory-efficient search library for large datasets with support for toke
 ## Features
 
 - **Fast search** - Pre-built metadata enables instant queries on large datasets
-- **Memory efficient** - Numeric token storage uses ~45% less memory than string-based approaches
+- **Memory efficient** - Numeric token storage (`Uint32Array`) keeps metadata compact
 - **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
@@ -32,7 +32,6 @@ A fast, memory-efficient search library for large datasets with support for toke
     - [Searching](#searching)
     - [Memory Optimization](#memory-optimization)
   - [Query Prefixes](#query-prefixes)
-  - [Legacy String Implementation](#legacy-string-implementation)
   - [Specification](#specification)
   - [License](#license)
 
@@ -282,9 +281,11 @@ augmented.clearAllAugmented();  // Reset to global state
 
 ### Ranked Search with Positional Scoring
 
-`searchInDataReturnIds` returns matching candidates but no ordering signal — useful when the caller needs raw IDs (e.g., for further filtering) but not when the UI needs the *most relevant* match first.
+**Since 2.0.0** all search functions return ranked results by default. `searchInData*` and `findInLinkedArrays` automatically score candidates and sort by relevance DESC. To activate positional scoring, declare `spec.keyFields` — those fields are tokenized in source order at build time and stored in `metadata.unsorted` for fast query-time scoring.
 
-`searchAndRank` wraps candidate retrieval with positional relevance scoring. Each item gets a score that rewards in-order token matches, first-word matches, perfect-prefix matches, contiguous matches, and shorter primary text.
+`searchAndRank` is a thin wrapper that additionally supports:
+- **`exactKeysFn`** — +100 000 boost when raw query equals a designated field value (e.g. barcode)
+- **`primaryTextFn`** — fallback when `keyFields` not declared, plus locale-aware tiebreaker sorting
 
 ```typescript
 import {
@@ -308,7 +309,11 @@ const products: Product[] = [
 ];
 
 const data = arrayToSearchableData(products);
-const meta = createSearchArrayMetadata(data);
+// Declare keyFields so positional ranking has pre-stored ordered tokens (faster).
+const meta = createSearchArrayMetadata(data, {
+  keyFields: ['name'],
+  firstTokensN: 8,
+});
 
 // Returns items sorted by relevance, NOT discovery order:
 const results = searchAndRank("pot mat", data, meta, {
@@ -323,25 +328,45 @@ const results = searchAndRank("pot mat", data, meta, {
 // Each result: { id: Id, item: T, score: number }
 ```
 
-**Scoring formula** (`scoreOne` is exported as a primitive — useful if you want to compose your own scoring):
+**Performance optimization via `keyFields`**: When the spec declares `keyFields`, the first N tokens (`firstTokensN`, default 8) of those fields are stored in `metadata.unsorted` at build time. `searchAndRank` reads those at query time instead of re-tokenizing — typically **10-50× faster scoring**. Without `keyFields`, `searchAndRank` falls back to tokenizing `primaryTextFn(item)` per candidate at query time (same correctness, slower).
+
+**Scoring formula** (`scoreOne` is exported as a primitive — useful for composing your own scorer):
 
 | Component | Value | When |
 |---|---|---|
 | Exact-key match | **+100 000** | `query === any(exactKeys)` (e.g. barcode equality) |
-| Base | +50 | Any in-order subsequence-prefix match of query tokens in `primaryText` |
+| Base | +50 | Any in-order subsequence-prefix match of query tokens in itemTokens |
 | All tokens matched | +100 | Every query token had a target |
 | First-word match | +50 | First match at position 0 |
 | Perfect prefix | +80 | Matches at positions `[0,1,…,k-1]` (contiguous from start) |
 | Density | +30 × (matched / span) | Rewards contiguous matches over gapped |
-| Length penalty | -0.1 × `primaryText.length` | Weak tiebreaker — shorter wins |
-| Secondary-field-only | 1 | Item matched (via search) but `primaryText` contains no query token |
+| Length penalty | -0.1 × `Σ itemToken.length` | Weak tiebreaker — shorter wins |
+| Secondary-field-only | 1 | Item matched (via retrieval) but no query token appears in itemTokens |
+
+**Lower-level scoring primitives** for composing custom rankers:
+
+| Function | Use case | Order-sensitive? |
+|---|---|---|
+| `scoreOne(query, qTokens, itemTokens, exactKeys?)` | Full-featured (perfect prefix, density, length penalty, exact-key boost) — default used by `searchInData*` and `searchAndRank` | yes |
+| `scoreOrderAndPresence(qTokens, itemTokens, weights?)` | Simpler additive bonus: ordered match (+30) + presence (+10) per token. Tunable via weights | yes |
+| `scoreBag(qTokens, itemTokens, perTokenWeight?)` | Order-agnostic: each query token present in itemTokens contributes equally. Use for **person names**, tags, pet breeds where word order is conventional but not semantic — `scoreBag(["janez","novak"], item)` === `scoreBag(["novak","janez"], item)` | no |
+| `orderedTokenize(input)` | Tokenize without alphabetic sort (required for any positional scoring). Output is NOT compatible with `searchInData*` retrieval (which requires sorted lists from `prepareStringForSearch`) | n/a |
+
+```typescript
+import { scoreBag, scoreOne, scoreOrderAndPresence, orderedTokenize, tokens, findTokenId } from 'cry-search';
 
-**Lower-level primitives** are also exported, for building custom rankers:
+// Combine signals per field in a custom ranker:
+const qTokens = orderedTokenize(query);
 
-- `orderedTokenize(input: string): string[]` — tokenize *without* alphabetic sort. `prepareStringForSearch` sorts tokens alphabetically (required for binary-search retrieval), which loses positional info. Use this for any order-aware scoring.
-- `scoreOne(item, query, qTokens, primaryTextFn, exactKeys?): number` — score one item against a pre-tokenized query. Compose with your own retrieval or filtering.
+// From metadata.unsorted (numeric IDs → strings via global tokens):
+const unsortedIds = meta.unsorted.get(itemId);
+const itemTokens = unsortedIds ? Array.from(unsortedIds, (id) => tokens[id]!) : [];
 
-**Important**: `orderedTokenize` output is NOT compatible with `searchInData...` retrieval functions — those require the sorted lists from `prepareStringForSearch`.
+const baseScore = scoreOne(query, qTokens, itemTokens, item.barcodes);
+const nameBoost = scoreBag(qTokens, nameTokens);                 // order-agnostic for "Janez Novak"
+const titleBoost = scoreOrderAndPresence(qTokens, titleTokens);  // order-sensitive for "RTG slika"
+const total = baseScore + nameBoost + titleBoost;
+```
 
 ## Architecture
 
@@ -372,7 +397,7 @@ Query tokens are matched against metadata using binary search. All query tokens
 
 ### Memory Optimization
 
-The numeric implementation stores tokens as `Uint32Array` indices instead of string arrays, reducing memory usage by ~45% compared to the string-based implementation.
+Tokens are stored as `Uint32Array` indices into a global `tokens: string[]` registry. Each metadata entry is a compact sorted Uint32Array per item — tokens themselves are interned once globally.
 
 ## Query Prefixes
 
@@ -448,20 +473,6 @@ This enables matching by either part:
 
 Priority: query prefix > field match mode > global SearchOpts default.
 
-## Legacy String Implementation
-
-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/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/UNIVERSE.md

@@ -794,36 +794,29 @@ For direct metadata manipulation without SearchUniverse:
 │                                                                             │
 │  ──────────────────────────────────────────────────────────────────────     │
 │                                                                             │
-│  STRING (Legacy) - import with *String suffix:                              │
+│  SYNC:                                                                      │
 │                                                                             │
-│  createSearchArrayMetadataString(data, spec)                                │
-│  updateSearchMetadataString(metadata, id, obj, spec)                        │
-│  updateSearchMetadataBatchString(metadata, batch, spec)                     │
-│  removeFromSearchMetadataString(metadata, id)                               │
-│  findInArray(query, data, metadata)                                         │
-│                                                                             │
-│  ──────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  SYNC (String-based):                                                       │
-│                                                                             │
-│  syncSearchArrayMetadata(data, metadata, spec)                              │
-│    Syncs metadata with current data state                                   │
+│  syncSearchArrayMetadata(metadata, newData, spec)                           │
+│    Syncs metadata with new full data snapshot                               │
 │    Returns: { added, updated, removed, addedIds, updatedIds, removedIds }   │
 │                                                                             │
+│  syncSearchArrayMetadataWithPrevious(metadata, prev, newData, opts?, spec)  │
+│    Same but uses previous data to skip metadata.keys() iteration            │
+│                                                                             │
 │  ──────────────────────────────────────────────────────────────────────     │
 │                                                                             │
-│  For linked metadata (String-based):                                        │
+│  Linked metadata (incremental):                                             │
 │                                                                             │
-│  upsertPrimaryItem(linked, id, item, spec)                                  │
+│  upsertPrimaryItem(linked, item, spec)                                      │
 │    Adds/updates primary item in linked structure                            │
 │                                                                             │
-│  upsertLinkedItem(linked, id, item, fkGetter, spec)                         │
+│  upsertLinkedItem(linked, item, fkGetter, spec)                             │
 │    Adds/updates linked item, handles FK changes                             │
 │                                                                             │
-│  removePrimaryItem(linked, id)                                              │
+│  removePrimaryItem(linked, primaryId)                                       │
 │    Removes primary item                                                     │
 │                                                                             │
-│  removeLinkedItem(linked, id, primaryId)                                    │
+│  removeLinkedItem(linked, linkedId, fkGetter)                               │
 │    Removes linked item from structure and index                             │
 │                                                                             │
 │  syncLinkedItemsForPrimary(linked, primaryId, items, fkGetter, spec)        │

package/dist/common/SearchUniverse.d.ts.map

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

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

@@ -1,111 +1,46 @@
-import type { Id, NumericSearchMetadata, NumericTokenSortedList, SearchableObjectSpec } from '../../types/index.js';
+import type { Id, NumericSearchMetadata, NumericTokenSortedList, NumericTokenUnsortedList, SearchableObjectSpec } from '../../types/index.js';
 /**
- * AugmentedMetadata wraps existing NumericSearchMetadata and allows adding
- * additional search tokens dynamically without modifying the base metadata.
+ * Wraps a base {@link NumericSearchMetadata} and exposes a view that overlays
+ * additional ("augmented") tokens onto `sorted` per item, without modifying base.
  *
- * Use case: Add local/temporary data (e.g., "uparjen"/"neuparjen" status) to
- * existing global metadata for searching.
+ * Use case: layer page-local or session-specific searchable data (e.g. status
+ * flags) onto a globally-built metadata snapshot.
  *
- * Items without augmentation reuse the original Uint32Array (no memory duplication).
- * Items with augmentation get a merged sorted token array.
+ * Augmentation policy:
+ * - `sorted` (retrieval) — base tokens **merged** with augmented tokens. Both
+ *   participate in `searchInData` matching.
+ * - `unsorted` (positional ranking) — **base only**. Augmented tokens are NOT
+ *   included; positional scoring uses base order as authoritative.
  *
  * @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);
+ * ```typescript
+ * const aug = new AugmentedMetadata(zdravilaMeta, { searchInFields: ['status'] });
+ * aug.updateAugmented('id1', { status: 'uparjen' });
+ * const ids = searchInDataReturnIds('aspirin uparjen', aug);
+ * ```
  */
 export declare class AugmentedMetadata implements NumericSearchMetadata {
-    private baseMetadata;
-    private augmentedTokens;
-    private spec;
+    readonly sorted: Map<Id, NumericTokenSortedList>;
+    readonly unsorted: Map<Id, NumericTokenUnsortedList>;
+    private readonly augmentedTokens;
+    private readonly 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)
+     * @param spec - Optional spec for tokenizing augmented objects
+     * @param augmentedDataMap - Optional initial map of id → augmented 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)
+     * Update augmented data for a single item. Pass `null`/`undefined` to clear.
+     * Augmented tokens are merged into `sorted` at lookup time; `unsorted` is
+     * unaffected.
      */
     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)
-     */
+    /** Batch update augmented data for multiple items. */
     updateAugmentedBatch(augmentedDataMap: Map<Id, any>): void;
-    /**
-     * Remove augmentation for a single item (reverts to base metadata only).
-     */
+    /** Remove augmentation for a single item (reverts to base only). */
     clearAugmented(id: Id): void;
-    /**
-     * Remove all augmentations (reverts to base metadata for all items).
-     */
+    /** Remove all augmentations. */
     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

@@ -1 +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"}
+{"version":3,"file":"AugmentedMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/AugmentedMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,sBAAsB,CAAA;AAqJ7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,wBAAwB,CAAC,CAAA;IAEpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;IAEjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuC;IAE5D;;;;OAIG;gBAED,YAAY,EAAE,qBAAqB,EAEnC,IAAI,CAAC,EAAE,oBAAoB,CAAC,GAAG,CAAC,EAEhC,gBAAgB,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC;IAcjC;;;;OAIG;IAEH,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,GAAG,IAAI;IAiBjD,sDAAsD;IAEtD,oBAAoB,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI;IAmB1D,oEAAoE;IACpE,cAAc,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI;IAI5B,gCAAgC;IAChC,iBAAiB,IAAI,IAAI;CAG1B"}