cry-search 1.0.0

package/UNIVERSE.md

@@ -0,0 +1,818 @@
+# cry-search Data Structures
+
+This document provides a graphical representation of the data structures used in the cry-search library.
+
+## Core Types
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              CORE TYPES                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Id = string                    // Unique identifier, e.g. "abc123"         │
+│                                                                             │
+│  SearchableObject = {           // Base interface for searchable items      │
+│    _id: Id,                                                                 │
+│    _deleted?: Date,                                                         │
+│    _blocked?: Date,                                                         │
+│    ...other fields                                                          │
+│  }                                                                          │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  NUMERIC (Default - Memory Optimized):                                      │
+│                                                                             │
+│  NumericToken = number          // Index into global tokens array           │
+│                                                                             │
+│  NumericTokenSortedList = Uint32Array  // Sorted token IDs                  │
+│                           ┌─────────────────────────────────────┐           │
+│                           │ Uint32Array [42, 156, 891]          │           │
+│                           │              ↓    ↓    ↓            │           │
+│                           │ tokens[42]="doe" [156]="john" [891]="smith"     │
+│                           └─────────────────────────────────────┘           │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  STRING (Legacy):                                                           │
+│                                                                             │
+│  SearchToken = string           // Single preprocessed token, e.g. "john"   │
+│                                                                             │
+│  SearchTokenSortedList = string[]   // Sorted array of tokens               │
+│                          ┌─────────────────────────────────────┐            │
+│                          │ ["doe", "john", "smith"]            │            │
+│                          └─────────────────────────────────────┘            │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Token Registry (Numeric Implementation)
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         GLOBAL TOKEN REGISTRY                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  tokens: string[]          // Global array, preallocated ~200k slots        │
+│                                                                             │
+│    Index    Token                                                           │
+│   ┌──────┬─────────────────────────────────────────────────────────────┐    │
+│   │  0   │  "berlin"                                                   │    │
+│   │  1   │  "bob"                                                      │    │
+│   │  2   │  "doe"                                                      │    │
+│   │  3   │  "jane"                                                     │    │
+│   │  4   │  "john"                                                     │    │
+│   │  5   │  "london"                                                   │    │
+│   │  6   │  "paris"                                                    │    │
+│   │  7   │  "smith"                                                    │    │
+│   │  8   │  "wilson"                                                   │    │
+│   │ ...  │  ...                                                        │    │
+│   └──────┴─────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  During metadata build:                                                     │
+│    tokensMap: Map<string, number>  // Temporary fast lookup                 │
+│    ┌──────────┬─────────────────────────────────────────────────────────┐   │
+│    │ "john"   │  4                                                      │   │
+│    │ "smith"  │  7                                                      │   │
+│    └──────────┴─────────────────────────────────────────────────────────┘   │
+│    → Cleared after build (only global tokens[] stays in memory)             │
+│                                                                             │
+│  During search:                                                             │
+│    findTokenId(token) → linear search in tokens[] (no Map in memory)        │
+│                                                                             │
+│  Match modes encoded in high 3 bits of Uint32 token ID:                     │
+│    Bits 0-28: token index (up to ~268M unique tokens)                       │
+│    Bits 29-31: match mode (0=start, 1=end, 2=startEnd, 3=anywhere, 4=whole) │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Storage
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         SearchableData<T>                                   │
+│                         Map<Id, T>                                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│    Key (Id)          Value (T extends SearchableObject)                     │
+│   ┌──────────┬─────────────────────────────────────────────────────────┐    │
+│   │  "s1"    │  { _id: "s1", name: "John Smith", city: "London" }      │    │
+│   ├──────────┼─────────────────────────────────────────────────────────┤    │
+│   │  "s2"    │  { _id: "s2", name: "Jane Doe", city: "Paris" }         │    │
+│   ├──────────┼─────────────────────────────────────────────────────────┤    │
+│   │  "s3"    │  { _id: "s3", name: "Bob Wilson", city: "Berlin" }      │    │
+│   └──────────┴─────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Metadata Storage
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    NumericSearchMetadata (Default)                          │
+│                    Map<Id, Uint32Array>                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│    Key (Id)          Value (sorted token IDs as Uint32Array)                │
+│   ┌──────────┬─────────────────────────────────────────────────────────┐    │
+│   │  "s1"    │  Uint32Array [4, 5, 7]                                  │    │
+│   │          │  → tokens[4]="john", [5]="london", [7]="smith"          │    │
+│   ├──────────┼─────────────────────────────────────────────────────────┤    │
+│   │  "s2"    │  Uint32Array [2, 3, 6]                                  │    │
+│   │          │  → tokens[2]="doe", [3]="jane", [6]="paris"             │    │
+│   ├──────────┼─────────────────────────────────────────────────────────┤    │
+│   │  "s3"    │  Uint32Array [0, 1, 8]                                  │    │
+│   │          │  → tokens[0]="berlin", [1]="bob", [8]="wilson"          │    │
+│   └──────────┴─────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│   Note: Token IDs are sorted numerically for binary search matching         │
+│         ~45% less memory than string-based implementation                   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    StringSearchMetadata (Legacy)                            │
+│                    Map<Id, string[]>                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│    Key (Id)          Value (sorted token strings)                           │
+│   ┌──────────┬─────────────────────────────────────────────────────────┐    │
+│   │  "s1"    │  ["john", "london", "smith"]                            │    │
+│   ├──────────┼─────────────────────────────────────────────────────────┤    │
+│   │  "s2"    │  ["doe", "jane", "paris"]                               │    │
+│   ├──────────┼─────────────────────────────────────────────────────────┤    │
+│   │  "s3"    │  ["berlin", "bob", "wilson"]                            │    │
+│   └──────────┴─────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│   Note: Tokens sorted alphabetically for efficient matching                 │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Linked Search Structures
+
+When searching across related entities (e.g., owners and their pets):
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    LinkedSearchMetadata                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  primaryMeta: SearchMetadata                                        │    │
+│  │  ┌──────────┬───────────────────────────────────────────────────┐   │    │
+│  │  │  "o1"    │  ["john", "london", "smith"]                      │   │    │
+│  │  │  "o2"    │  ["doe", "jane", "paris"]                         │   │    │
+│  │  └──────────┴───────────────────────────────────────────────────┘   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  linkedMeta: SearchMetadata                                         │    │
+│  │  ┌──────────┬───────────────────────────────────────────────────┐   │    │
+│  │  │  "p1"    │  ["cat", "fluffy"]                                │   │    │
+│  │  │  "p2"    │  ["dog", "rex"]                                   │   │    │
+│  │  │  "p3"    │  ["cat", "whiskers"]                              │   │    │
+│  │  └──────────┴───────────────────────────────────────────────────┘   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  primaryToLinked: Map<Id, Id[]>     (reverse index)                 │    │
+│  │  ┌──────────┬───────────────────────────────────────────────────┐   │    │
+│  │  │  "o1"    │  ["p1", "p2"]          (John owns Fluffy & Rex)   │   │    │
+│  │  │  "o2"    │  ["p3"]                (Jane owns Whiskers)       │   │    │
+│  │  └──────────┴───────────────────────────────────────────────────┘   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## SearchLinkedMetadataWithData
+
+Extended structure that includes data references for convenient access:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                SearchLinkedMetadataWithData<TPrimary, TLinked>              │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Extends LinkedSearchMetadata with:                                         │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  primaryData: SearchableData<TPrimary>                              │    │
+│  │  ┌──────────┬───────────────────────────────────────────────────┐   │    │
+│  │  │  "o1"    │  { _id: "o1", name: "John Smith", city: "London" }│   │    │
+│  │  │  "o2"    │  { _id: "o2", name: "Jane Doe", city: "Paris" }   │   │    │
+│  │  └──────────┴───────────────────────────────────────────────────┘   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  linkedData: SearchableData<TLinked>                                │    │
+│  │  ┌──────────┬───────────────────────────────────────────────────┐   │    │
+│  │  │  "p1"    │  { _id: "p1", name: "Fluffy", species: "cat" }    │   │    │
+│  │  │  "p2"    │  { _id: "p2", name: "Rex", species: "dog" }       │   │    │
+│  │  │  "p3"    │  { _id: "p3", name: "Whiskers", species: "cat" }  │   │    │
+│  │  └──────────┴───────────────────────────────────────────────────┘   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## SearchUniverse
+
+Manages multiple collections with their relationships using numeric tokens:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           SearchUniverse                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Uses numeric implementation for memory efficiency (~45% less than string)  │
+│                                                                             │
+│  collections: Map<string, Collection>                                       │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  "stranke" (standalone collection)                                  │    │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │    │
+│  │  │  data: SearchableData<Stranka>                              │    │    │
+│  │  │  metadata: NumericSearchMetadata  ← Uint32Array tokens      │    │    │
+│  │  │  config: { spec: {...} }                                    │    │    │
+│  │  └─────────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  "pacienti" (linked to "stranke")                                   │    │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │    │
+│  │  │  data: SearchableData<Pacient>                              │    │    │
+│  │  │  metadata: NumericSearchMetadata  ← Uint32Array tokens      │    │    │
+│  │  │  config: {                                                  │    │    │
+│  │  │    spec: {...},                                             │    │    │
+│  │  │    linkedTo: {                                              │    │    │
+│  │  │      collectionName: "stranke",                             │    │    │
+│  │  │      foreignKeyGetter: (p) => p.stranka_id                  │    │    │
+│  │  │    }                                                        │    │    │
+│  │  │  }                                                          │    │    │
+│  │  │  primaryToLinked: Map<Id, Id[]>  ← reverse index            │    │    │
+│  │  └─────────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  "artikli" (standalone collection)                                  │    │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │    │
+│  │  │  data: SearchableData<Artikel>                              │    │    │
+│  │  │  metadata: NumericSearchMetadata  ← Uint32Array tokens      │    │    │
+│  │  │  config: { spec: {...} }                                    │    │    │
+│  │  └─────────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow: Token Preparation Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    prepareStringForSearch Pipeline                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Input: "Čokolada 100g SI123 27.12.2025"                                    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 1. normalizeDates()                                                 │    │
+│  │    "Čokolada 100g SI123 20251227"                                   │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 2. preprocessString()                                               │    │
+│  │    - decimal comma → period                                         │    │
+│  │    - remove leading zeros                                           │    │
+│  │    - split letter-digit boundaries                                  │    │
+│  │    "Čokolada 100 g SI 123 20251227"                                 │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 3. sanitiseString()                                                 │    │
+│  │    - lowercase                                                      │    │
+│  │    - remove diacritics                                              │    │
+│  │    - keep only [a-z0-9.-]                                           │    │
+│  │    "cokolada 100 g si 123 20251227"                                 │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 4. tokenize()                                                       │    │
+│  │    - split on spaces                                                │    │
+│  │    - trim and filter empty                                          │    │
+│  │    ["cokolada", "100", "g", "si", "123", "20251227"]                 │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 5. sort()                                                           │    │
+│  │    ["100", "123", "20251227", "cokolada", "g", "si"]                 │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  Output: SearchTokenSortedList                                              │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Match Modes & Encoding
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      MatchMode Encoding                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  MatchMode        Behavior                                                  │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│  'start'          "rex" matches "rexona" not "ceporex"                      │
+│  'end'            "rex" matches "ceporex" not "rexona"                      │
+│  'startEnd'       "rex" matches both "rexona" and "ceporex"                 │
+│  'anywhere'       "rex" matches "unrexy", "rexona", "ceporex"               │
+│  'whole'          "rex" matches only "rex" exactly                          │
+│                                                                             │
+│  Default behavior (via SearchOpts):                                         │
+│    matchWords: 'start'      (words match from beginning)                    │
+│    matchNumbers: 'startEnd' (numbers match from start or end)               │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  NUMERIC Implementation:                                                    │
+│                                                                             │
+│  Match mode encoded in high 3 bits of Uint32 token ID:                      │
+│                                                                             │
+│    31  30  29  28 ─────────────────────────────── 0                         │
+│   ┌───┬───┬───┬─────────────────────────────────────┐                       │
+│   │ M │ M │ M │         TOKEN INDEX (29 bits)       │                       │
+│   └───┴───┴───┴─────────────────────────────────────┘                       │
+│     └─────┬─────┘                                                           │
+│      Match Mode:  0=start, 1=end, 2=startEnd, 3=anywhere, 4=whole           │
+│                                                                             │
+│  Example: token "barcode123" at index 42 with 'startEnd' mode               │
+│    = (2 << 29) | 42 = 0x40000000 | 0x2A = 1073741866                        │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  STRING Implementation (Legacy):                                            │
+│                                                                             │
+│  Match mode encoded as single-char prefix:                                  │
+│    Prefix    Mode                                                           │
+│    <         start                                                          │
+│    >         end                                                            │
+│    +         startEnd                                                       │
+│    *         anywhere                                                       │
+│    !         whole                                                          │
+│                                                                             │
+│  Example: metadata: ["<barcode123", "!exactcode", "*anywhere"]              │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Search Flow: Linked Search
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    findInLinkedArrays Flow                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Query: "john fluffy"                                                       │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ prepareStringForSearch("john fluffy") → ["fluffy", "john"]          │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ For each primary (owner):                                           │    │
+│  │   1. Collect tokens: primary + all linked items                     │    │
+│  │      Owner o1: ["john", "london", "smith"]                          │    │
+│  │      + Pet p1: ["cat", "fluffy"]                                    │    │
+│  │      + Pet p2: ["dog", "rex"]                                       │    │
+│  │      = Combined: ["cat","dog","fluffy","john","london","rex","smith"]│    │
+│  │                                                                     │    │
+│  │   2. Check if ALL query tokens match combined                       │    │
+│  │      "fluffy" matches "fluffy" ✓                                    │    │
+│  │      "john" matches "john" ✓                                        │    │
+│  │      → All match!                                                   │    │
+│  │                                                                     │    │
+│  │   3. Determine matchedIn:                                           │    │
+│  │      "john" matches in primary → anyMatchInPrimary = true           │    │
+│  │      "fluffy" matches in linked → anyMatchInLinked = true           │    │
+│  │      → matchedIn = 'both'                                           │    │
+│  │                                                                     │    │
+│  │   4. Return only contributing linked items:                         │    │
+│  │      p1 (Fluffy) matched "fluffy" → included                        │    │
+│  │      p2 (Rex) didn't contribute → excluded                          │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  Result:                                                                    │
+│  {                                                                          │
+│    queryTokens: ["fluffy", "john"],                                         │
+│    results: [{                                                              │
+│      primary: { _id: "o1", name: "John Smith", city: "London" },            │
+│      linked: [{ _id: "p1", name: "Fluffy", species: "cat" }],               │
+│      matchedIn: "both"                                                      │
+│    }]                                                                       │
+│  }                                                                          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Memory Layout Example
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Typical Memory Layout                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  For 10,000 items with ~5 tokens each:                                      │
+│                                                                             │
+│  SearchableData<T>:                                                         │
+│    └── Map with 10,000 entries                                              │
+│        └── Each entry: Id string + full object reference                    │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  NUMERIC (Default):                                                         │
+│                                                                             │
+│  Global Token Registry:                                                     │
+│    └── Single string[] with all unique tokens (~50k-200k entries typical)   │
+│        └── Each token stored once, referenced by index                      │
+│                                                                             │
+│  NumericSearchMetadata:                                                     │
+│    └── Map with 10,000 entries                                              │
+│        └── Each entry: Id string + Uint32Array(5) ← 20 bytes fixed          │
+│                                                                             │
+│  Memory savings: ~45% less than string implementation                       │
+│    String: 10,000 × 5 tokens × ~10 chars = ~500KB in token strings          │
+│    Numeric: 10,000 × 5 × 4 bytes = ~200KB + shared registry                 │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  STRING (Legacy):                                                           │
+│                                                                             │
+│  StringSearchMetadata:                                                      │
+│    └── Map with 10,000 entries                                              │
+│        └── Each entry: Id string + array of 5 token strings                 │
+│            └── Each token string duplicated per item                        │
+│                                                                             │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│                                                                             │
+│  Linked Index (primaryToLinked):                                            │
+│    └── Map with N primary entries                                           │
+│        └── Each entry: Id string + array of linked Id strings               │
+│                                                                             │
+│  Note: Objects are stored by reference, not duplicated.                     │
+│        Metadata stores only preprocessed tokens, not original text.         │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Modifying Data After Creation
+
+SearchUniverse provides methods to update data and metadata after initial load.
+
+### Single Item Update
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│           universe.updateSearchMetadata(collectionName, id, item)           │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Handles all cases automatically:                                           │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  CASE 1: Add new item                                               │    │
+│  │  ─────────────────────────────────────────────────────────────────  │    │
+│  │  Input: { _id: "s4", name: "New Person", city: "Rome" }             │    │
+│  │                                                                     │    │
+│  │  Actions:                                                           │    │
+│  │    1. data.set("s4", item)                                          │    │
+│  │    2. metadata.set("s4", ["new", "person", "rome"])                  │    │
+│  │    3. If linked: primaryToLinked updated                            │    │
+│  │                                                                     │    │
+│  │  Returns: { added: true }                                           │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  CASE 2: Update existing item                                       │    │
+│  │  ─────────────────────────────────────────────────────────────────  │    │
+│  │  Input: { _id: "s1", name: "John Smith", city: "Madrid" }           │    │
+│  │                   (was London, now Madrid)                          │    │
+│  │                                                                     │    │
+│  │  Actions:                                                           │    │
+│  │    1. data.set("s1", item)  ← replaces old                          │    │
+│  │    2. metadata.set("s1", ["john", "madrid", "smith"])               │    │
+│  │                                                                     │    │
+│  │  Returns: { added: false }                                          │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  CASE 3: Delete/Block item                                          │    │
+│  │  ─────────────────────────────────────────────────────────────────  │    │
+│  │  Input: { _id: "s1", ..., _deleted: new Date() }                    │    │
+│  │                                                                     │    │
+│  │  Actions:                                                           │    │
+│  │    1. data.set("s1", item)  ← keeps item                            │    │
+│  │    2. metadata.delete("s1") ← removes from search                   │    │
+│  │    3. If linked: removed from primaryToLinked                       │    │
+│  │                                                                     │    │
+│  │  Note: Item stays in data but is unsearchable                       │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  CASE 4: Pass null/undefined                                        │    │
+│  │  ─────────────────────────────────────────────────────────────────  │    │
+│  │  Input: null or undefined                                           │    │
+│  │                                                                     │    │
+│  │  Actions:                                                           │    │
+│  │    1. metadata.delete("s1") ← removes from search                   │    │
+│  │    2. If linked: removed from primaryToLinked                       │    │
+│  │                                                                     │    │
+│  │  Note: Equivalent to removeFromSearchMetadata(). Use when you       │    │
+│  │        don't have the object but need to remove from search.        │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Linked Item Foreign Key Change
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│              Updating Linked Item with FK Change                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Scenario: Pet "p1" (Fluffy) moves from owner "o1" to "o2"                  │
+│                                                                             │
+│  BEFORE:                                                                    │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  primaryToLinked:                                                   │    │
+│  │    "o1" → ["p1", "p2"]    (John owns Fluffy & Rex)                  │    │
+│  │    "o2" → ["p3"]          (Jane owns Whiskers)                      │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  Call: universe.updateSearchMetadata("pacienti", "p1",                      │
+│           { _id: "p1", name: "Fluffy", owner_id: "o2" })                    │
+│                       ↑ was "o1", now "o2"                                  │
+│                                                                             │
+│  AFTER:                                                                     │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  primaryToLinked:                                                   │    │
+│  │    "o1" → ["p2"]          (John owns only Rex now)                  │    │
+│  │    "o2" → ["p3", "p1"]    (Jane owns Whiskers & Fluffy)             │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│                                                                             │
+│  Returns: { added: false, previousPrimaryId: "o1" }                         │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Batch Updates
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│        universe.updateSearchMetadataBatch(collectionName, items)            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Input: Array of items to update                                            │
+│                                                                             │
+│  items = [                                                                  │
+│    { _id: "s1", name: "Updated John", city: "Madrid" },    ← update         │
+│    { _id: "s5", name: "New Person", city: "Vienna" },      ← add            │
+│    { _id: "s2", name: "Jane", _deleted: new Date() },      ← delete         │
+│  ]                                                                          │
+│                                                                             │
+│  Returns: { added: 1, updated: 1, removed: 1 }                              │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Remove Item
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│           universe.removeFromSearchMetadata(collectionName, id)             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Completely removes item from universe (vs _deleted which keeps it)         │
+│                                                                             │
+│  Call: universe.removeFromSearchMetadata("stranke", "s1")                   │
+│                                                                             │
+│  Actions:                                                                   │
+│    1. data.delete("s1")                                                     │
+│    2. metadata.delete("s1")                                                 │
+│    3. If linked: remove from primaryToLinked index                          │
+│                                                                             │
+│  Returns: true (found and removed) or false (not found)                     │
+│                                                                             │
+│  Batch version:                                                             │
+│    universe.removeFromSearchMetadataBatch("stranke", ["s1", "s2"])          │
+│    Returns: number of items removed                                         │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Clear Universe
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│           universe.clear()                                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Clears all collections, removing all data, metadata, and linked indexes.  │
+│                                                                             │
+│  Call: universe.clear()                                                     │
+│                                                                             │
+│  Actions:                                                                   │
+│    1. For each collection:                                                  │
+│       - data.clear()                                                        │
+│       - metadata.clear()                                                    │
+│       - primaryToLinked.clear() (if linked)                                 │
+│    2. collections.clear()                                                   │
+│                                                                             │
+│  Note: The global token registry is NOT cleared. Use resetTokenRegistry()   │
+│        directly if you need to clear it (e.g., in tests or full app reset). │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Update Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    updateSearchMetadata Flow                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Input: (collectionName, id, item)                                          │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 1. Check if item exists                                             │    │
+│  │    existingItem = data.get(id)                                      │    │
+│  │    wasAdded = !existingItem                                         │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 2. If linked collection: handle FK changes                          │    │
+│  │    ┌───────────────────────────────────────────────────────────┐    │    │
+│  │    │ previousPrimaryId = fkGetter(existingItem)                │    │    │
+│  │    │ newPrimaryId = fkGetter(item)                             │    │    │
+│  │    │                                                           │    │    │
+│  │    │ if (previousPrimaryId !== newPrimaryId) {                 │    │    │
+│  │    │   Remove id from primaryToLinked[previousPrimaryId]       │    │    │
+│  │    │   Add id to primaryToLinked[newPrimaryId]                 │    │    │
+│  │    │ }                                                         │    │    │
+│  │    │                                                           │    │    │
+│  │    │ if (item._deleted || item._blocked) {                     │    │    │
+│  │    │   Remove id from primaryToLinked[previousPrimaryId]       │    │    │
+│  │    │ }                                                         │    │    │
+│  │    └───────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 3. Update data                                                      │    │
+│  │    data.set(id, item)                                               │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │ 4. Update metadata (numeric)                                        │    │
+│  │    tokensMap = createTokensMap()                                    │    │
+│  │    tokens = prepareObjectForSearchNumeric(item, spec, tokensMap)    │    │
+│  │    clearTokensMap(tokensMap)                                        │    │
+│  │                                                                     │    │
+│  │    if (tokens !== undefined) {                                      │    │
+│  │      metadata.set(id, tokens)     ← Uint32Array searchable          │    │
+│  │    } else {                                                         │    │
+│  │      metadata.delete(id)          ← _deleted or _blocked            │    │
+│  │    }                                                                │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│           │                                                                 │
+│           ▼                                                                 │
+│  Return: { added: wasAdded, previousPrimaryId }                             │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Standalone Functions (without SearchUniverse)
+
+For direct metadata manipulation without SearchUniverse:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Standalone Update Functions                              │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  NUMERIC (Default) - import from 'cry-search':                              │
+│                                                                             │
+│  createSearchArrayMetadata(data, spec)                                      │
+│    Creates NumericSearchMetadata with Uint32Array tokens                    │
+│    Creates/clears temporary tokensMap internally                            │
+│                                                                             │
+│  updateSearchMetadata(metadata, id, obj, spec)                              │
+│    Updates a single item's tokens in the metadata map                       │
+│                                                                             │
+│  updateSearchMetadataBatch(metadata, batch, spec)                           │
+│    batch = [{ objectId, obj }, ...]                                         │
+│    Updates multiple items efficiently                                       │
+│    Creates/clears temporary tokensMap internally                            │
+│                                                                             │
+│  removeFromSearchMetadata(metadata, id)                                     │
+│    Removes item from metadata                                               │
+│                                                                             │
+│  removeFromSearchMetadataBatch(metadata, ids)                               │
+│    Removes multiple items from metadata                                     │
+│                                                                             │
+│  searchInData(query, metadata) / searchInDataReturnIds(query, metadata)     │
+│    Returns matching IDs                                                     │
+│                                                                             │
+│  searchInDataReturnObjects(query, metadata, data)                           │
+│    Returns matching objects                                                 │
+│                                                                             │
+│  ──────────────────────────────────────────────────────────────────────     │
+│                                                                             │
+│  STRING (Legacy) - import with *String suffix:                              │
+│                                                                             │
+│  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                                   │
+│    Returns: { added, updated, removed, addedIds, updatedIds, removedIds }   │
+│                                                                             │
+│  ──────────────────────────────────────────────────────────────────────     │
+│                                                                             │
+│  For linked metadata (String-based):                                        │
+│                                                                             │
+│  upsertPrimaryItem(linked, id, item, spec)                                  │
+│    Adds/updates primary item in linked structure                            │
+│                                                                             │
+│  upsertLinkedItem(linked, id, item, fkGetter, spec)                         │
+│    Adds/updates linked item, handles FK changes                             │
+│                                                                             │
+│  removePrimaryItem(linked, id)                                              │
+│    Removes primary item                                                     │
+│                                                                             │
+│  removeLinkedItem(linked, id, primaryId)                                    │
+│    Removes linked item from structure and index                             │
+│                                                                             │
+│  syncLinkedItemsForPrimary(linked, primaryId, items, fkGetter, spec)        │
+│    Syncs all linked items for a specific primary                            │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Token Registry Functions
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Token Registry API                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  tokens: string[]                    // Global array (read-only export)     │
+│                                                                             │
+│  getTokenCount(): number             // Current number of registered tokens │
+│                                                                             │
+│  getTokenById(id: number): string | undefined                               │
+│    Returns token string for given ID                                        │
+│                                                                             │
+│  findTokenId(token: string): number                                         │
+│    Returns token ID or -1 if not found                                      │
+│    Uses linear search (no Map overhead during search)                       │
+│                                                                             │
+│  registerToken(token: string): number                                       │
+│    Registers new token, returns its ID                                      │
+│    If token exists, returns existing ID                                     │
+│                                                                             │
+│  getOrCreateTokenId(token: string, tokensMap): number                       │
+│    Fast lookup/create using temporary Map                                   │
+│    Used during metadata building                                            │
+│                                                                             │
+│  createTokensMap(): Map<string, number>                                     │
+│    Creates temporary Map for fast lookups during build                      │
+│                                                                             │
+│  clearTokensMap(tokensMap): void                                            │
+│    Clears the temporary Map to free memory                                  │
+│                                                                             │
+│  resetTokenRegistry(): void                                                 │
+│    Clears all tokens (for testing only)                                     │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```