cry-search 1.0.5 → 1.0.7

package/CLAUDE.md

@@ -315,6 +315,31 @@ 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>[]
+    1. searchAndRank = searchAndRankNumeric (alias for the numeric implementation)
+    2. wraps searchInDataReturnIds + positional scoring over the candidate set
+    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[]
+    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
+
 ## Token Registry Functions
 
 1. tokens: string[] - global array (read-only)
@@ -373,6 +398,7 @@ src/
 │   │   ├── updateSearchMetadata.ts
 │   │   ├── updateSearchLinkedMetadata.ts
 │   │   ├── searchInData.ts
+│   │   ├── searchAndRank.ts        # Ranked search with positional scoring
 │   │   ├── syncSearchArrayMetadata.ts
 │   │   └── AugmentedMetadata.ts
 │   ├── string/            # Legacy string implementation

package/README.md

@@ -11,6 +11,7 @@ A fast, memory-efficient search library for large datasets with support for toke
 - **Flexible matching** - Per-field match modes and query prefixes for prefix, suffix, anywhere, exact, and negation
 - **Search prefixes** - use `-word`, `--word`, or `~word` to exclude, `..word` for suffix, `=word` for exact match
 - **Automatic normalization** - Handles diacritics, case, dates, and number formatting
+- **Ranked search** - `searchAndRank` returns results scored by positional relevance (token order, contiguity, perfect-prefix, length)
 - **[Universal search](./UNIVERSE.md)** - Search and update across linked collections (e.g., customers with their pets)
 
 ## Table of Contents
@@ -24,6 +25,7 @@ A fast, memory-efficient search library for large datasets with support for toke
     - [SearchUniverse with Linked Collections](#searchuniverse-with-linked-collections)
     - [Updating Existing Data](#updating-existing-data)
     - [Augmented Metadata - Local Search Context](#augmented-metadata---local-search-context)
+    - [Ranked Search with Positional Scoring](#ranked-search-with-positional-scoring)
   - [Architecture](#architecture)
     - [Text Processing Pipeline](#text-processing-pipeline)
     - [Metadata Building](#metadata-building)
@@ -278,6 +280,69 @@ augmented.clearAllAugmented();  // Reset to global state
 - Documents with review status or approval state
 - Items with computed scores or temporary categories
 
+### 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.
+
+`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.
+
+```typescript
+import {
+  arrayToSearchableData,
+  createSearchArrayMetadata,
+  searchAndRank,
+  type SearchableObject,
+} from "cry-search";
+
+interface Product extends SearchableObject {
+  _id: string;
+  name: string;
+  barcodes?: string[];
+}
+
+const products: Product[] = [
+  { _id: "1", name: "POTROŠNI MATERIAL" },
+  { _id: "2", name: "POTROŠNI MATERIAL-SUCRALAN 1ML" },
+  { _id: "3", name: "KONTROLNI PREGLED" },
+  { _id: "4", name: "DERMATOLOŠKI KONTROLNI PREGLED" },
+];
+
+const data = arrayToSearchableData(products);
+const meta = createSearchArrayMetadata(data);
+
+// Returns items sorted by relevance, NOT discovery order:
+const results = searchAndRank("pot mat", data, meta, {
+  primaryTextFn: (p) => p.name,
+  exactKeysFn: (p) => p.barcodes,  // optional: exact-key boost (e.g. barcode)
+  limit: 10,
+});
+
+// results[0].item.name === "POTROŠNI MATERIAL"        (perfect prefix → +80)
+// results[1].item.name === "POTROŠNI MATERIAL-SUCRALAN 1ML"  (longer naziv)
+
+// 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):
+
+| 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` |
+| 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 |
+
+**Lower-level primitives** are also exported, for building custom rankers:
+
+- `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.
+
+**Important**: `orderedTokenize` output is NOT compatible with `searchInData...` retrieval functions — those require the sorted lists from `prepareStringForSearch`.
+
 ## Architecture
 
 cry-search uses a two-phase approach: **build** metadata once, then **search** instantly.

package/UNIVERSE.md

@@ -620,6 +620,59 @@ SearchUniverse provides methods to update data and metadata after initial load.
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
+### Sync Collection (Snapshot Diff)
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│        universe.syncCollection(collectionName, newItems, options?)          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ⚠️  newItems MUST be the FULL snapshot, not a partial delta.               │
+│      Anything currently in the collection whose _id is missing from         │
+│      newItems will be REMOVED (data + metadata + linked index).             │
+│      Passing a partial list will wipe out everything else.                  │
+│                                                                             │
+│  newItems = [                                                               │
+│    { _id: "s1", name: "Krajnik", address: "Ljubljana" },  ← unchanged       │
+│    { _id: "s2", name: "Novak",   address: "Celje" },      ← updated         │
+│    { _id: "s3", name: "Horvat",  address: "Koper" },      ← added           │
+│    // s4 from previous state is missing → removed                           │
+│  ]                                                                          │
+│                                                                             │
+│  Behavior:                                                                  │
+│    1. Items in collection but absent from newItems → removed                │
+│       (data + metadata + primaryToLinked all cleaned)                       │
+│    2. Items in both → tokens compared; metadata.set only if changed         │
+│    3. New items → tokenized, added to metadata + primaryToLinked            │
+│    4. _deleted/_blocked items in newItems → removed from metadata           │
+│       (kept in data, same convention as updateSearchMetadata)               │
+│                                                                             │
+│  Options:                                                                   │
+│    skipUpdateCheck: true → don't re-tokenize existing items (faster)        │
+│                            data refs still get updated                      │
+│                                                                             │
+│  Returns: SyncResult                                                        │
+│    { added, updated, removed, addedIds[], updatedIds[], removedIds[] }      │
+│                                                                             │
+│  Single shared tokensMap is used across the whole snapshot for efficiency.  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### When to use which update method
+
+| Scenario                                          | Method                                                       |
+|---------------------------------------------------|--------------------------------------------------------------|
+| Full snapshot from server (periodic refresh)      | `syncCollection(name, allItems)`                             |
+| Known delta — add/update some items               | `updateSearchMetadataBatch(name, changedItems)`              |
+| Known IDs to remove                               | `removeFromSearchMetadataBatch(name, ids)`                   |
+| Mark item as soft-deleted but keep in data        | `updateSearchMetadata(name, id, { ...item, _deleted: ... })` |
+| Initial load / full reset                         | `loadCollection(name, items)`                                |
+
+**Rule of thumb:** if you don't have the complete current state of the
+collection, do NOT use `syncCollection` — use the batch methods instead.
+They only touch the items you pass in and leave the rest alone.
+
 ### Clear Universe
 
 ```

package/dist/common/SearchUniverse.d.ts

@@ -1,4 +1,4 @@
-import type { Id, NumericSearchMetadata, SearchableData, SearchableObject, UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult } from '../types';
+import type { Id, NumericSearchMetadata, SearchableData, SearchableObject, UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult, SyncResult, SyncOptions } from '../types';
 export type { UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult } from '../types';
 /**
  * SearchUniverse manages multiple collections with their metadata and relationships.
@@ -154,6 +154,49 @@ export declare class SearchUniverse {
      * @returns Number of items actually removed
      */
     removeFromSearchMetadataBatch(collectionName: string, ids: Id[]): number;
+    /**
+     * Syncs a collection against a **full snapshot** of items.
+     *
+     * **IMPORTANT:** `newItems` MUST contain the entire desired state of the
+     * collection, not a partial delta. Any item currently in the collection
+     * whose `_id` is missing from `newItems` will be **completely removed**
+     * (data + metadata + linked indexes). Passing a partial list will wipe
+     * out everything else.
+     *
+     * Compares `newItems` to the current collection state and applies the diff:
+     * - items absent from `newItems` → removed
+     * - new IDs in `newItems` → added
+     * - existing IDs with changed tokens → updated
+     * - items marked `_deleted` or `_blocked` → removed from metadata
+     *   (kept in `collection.data` for reference — same convention as
+     *   {@link updateSearchMetadata})
+     *
+     * **When to use which method:**
+     * - Full snapshot from server (periodic refresh): `syncCollection`
+     * - Known delta of changes: {@link updateSearchMetadataBatch}
+     * - Known IDs to delete: {@link removeFromSearchMetadataBatch}
+     *
+     * For partial delta updates, prefer the batch methods — they leave untouched
+     * items unaffected.
+     *
+     * @typeParam T - Type of items in the collection
+     * @param collectionName - Name of the collection
+     * @param newItems - **Full** new dataset (complete snapshot, not a delta)
+     * @param options - Optional sync options (e.g. `skipUpdateCheck` to avoid re-tokenizing existing items)
+     * @returns SyncResult with counts and IDs of added/updated/removed items
+     *
+     * @example
+     * ```typescript
+     * // Full refresh from server — pass ALL current products
+     * const fresh = await fetchAllProducts();
+     * const result = universe.syncCollection('products', fresh);
+     * // { added: 3, updated: 12, removed: 1, addedIds: [...], ... }
+     *
+     * // ⚠️ DO NOT do this — would delete all other products:
+     * // universe.syncCollection('products', [oneChangedProduct]);
+     * ```
+     */
+    syncCollection<T extends SearchableObject>(collectionName: string, newItems: T[], options?: SyncOptions): SyncResult;
     /**
      * Gets collection or throws an error if not found.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"SearchUniverse.d.ts","sourceRoot":"","sources":["../../src/common/SearchUniverse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAEhB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAWlB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAcvG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAiC;IAEpD;;;;;OAKG;IACH,kBAAkB,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACxD,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAM,GAClC,IAAI;IAmBP;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,SAAS,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAsC1E;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,SAAS,gBAAgB,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,GAAG,SAAS;IAKlF;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,SAAS,gBAAgB,EAAE,cAAc,EAAE,MAAM,GAAG,CAAC,EAAE;IAKjE;;;;;OAKG;IACH,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAKjD;;;;;OAKG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,qBAAqB;IAK1D;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,SAAS,gBAAgB,EAAE,cAAc,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC;IAK9E;;;;;;;OAOG;IACH,YAAY,CAAC,oBAAoB,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,EAAE;IAQ/D;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,SAAS,gBAAgB,EACvC,oBAAoB,EAAE,MAAM,EAC5B,SAAS,EAAE,EAAE,GACZ,CAAC,EAAE;IAMN;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,EAC7C,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,CAAC,GACN,YAAY;IAoFf;;;;;;OAMG;IACH,yBAAyB,CAAC,CAAC,SAAS,gBAAgB,EAClD,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,CAAC,EAAE,GACT,iBAAiB;IA0BpB;;;;;;OAMG;IACH,wBAAwB,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO;IAmCjE;;;;;;OAMG;IACH,6BAA6B,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,MAAM;IAcxE;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,EAClB,IAAI,CAAC,EAAE,mBAAmB,GACzB,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;QAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QAAC,OAAO,EAAE,gBAAgB,CAAC;QAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IA6FlJ;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;CAUd"}
+{"version":3,"file":"SearchUniverse.d.ts","sourceRoot":"","sources":["../../src/common/SearchUniverse.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,90 @@
+import type { Id, NumericSearchMetadata, SearchableData, SearchableObject, SearchOpts } from "../../types";
+/**
+ * Tokenizes a string preserving source order (no alphabetic sort).
+ *
+ * Mirrors {@link prepareStringForSearch} pipeline minus the trailing `.sort()`,
+ * which is required for any positional / order-aware scoring.
+ *
+ * NOTE: do NOT use these tokens for cry-search candidate retrieval; those APIs
+ * assume sorted lists for efficient binary search.
+ */
+export declare function orderedTokenize(input: string): string[];
+/**
+ * Result of a scored / ranked search.
+ */
+export interface ScoredResult<T extends SearchableObject> {
+    /** Item id. */
+    id: Id;
+    /** The matched item. */
+    item: T;
+    /** Relevance score (higher = better). 100_000 for exact-key match. */
+    score: number;
+}
+/**
+ * Options controlling {@link searchAndRank} scoring and retrieval.
+ */
+export interface SearchAndRankOptions<T extends SearchableObject> {
+    /**
+     * Extracts the primary display text used for positional scoring.
+     * Typically the human-readable label (`item => item.naziv`).
+     */
+    primaryTextFn: (item: T) => string | undefined;
+    /**
+     * Optional: extracts values that must match the raw query string exactly
+     * for a top-priority boost (e.g. crtnaKoda for invoice items).
+     * Returns score 100_000 on exact equality.
+     */
+    exactKeysFn?: (item: T) => readonly string[] | undefined;
+    /** Maximum number of ranked results to return. Default: Infinity. */
+    limit?: number;
+    /** Underlying search options passed to candidate retrieval. */
+    opts?: SearchOpts;
+}
+/**
+ * Computes a relevance score for one item against a query.
+ *
+ * Scoring components (additive):
+ * - **+100_000** if the raw `query` equals any `exactKeys` value (e.g. crtnaKoda).
+ * - **+50** base for any subsequence-prefix match of query tokens in primary text.
+ * - **+100** if ALL query tokens match (in order) in primary text.
+ * - **+50** if first matched position is 0 (primary text starts with first query token).
+ * - **+80** if matched positions form a contiguous prefix `[0..k-1]` (perfect prefix).
+ * - **+30 * (matchedCount / span)** density bonus (rewards contiguous matches).
+ * - **-0.1 * primaryText.length** length penalty (weak tiebreaker — shorter wins).
+ *
+ * Returns **1** if the item was retrieved as a candidate but its primary text
+ * contains no query token (match came from a secondary field).
+ *
+ * Returns **0** if the query is empty.
+ */
+export declare function scoreOne<T extends SearchableObject>(item: T, query: string, qTokens: string[], primaryTextFn: (item: T) => string | undefined, exactKeys?: readonly string[] | undefined): number;
+/**
+ * Searches with positional relevance scoring and returns ranked results.
+ *
+ * Combines candidate retrieval ({@link searchInDataReturnIdsNumeric}, sorted-token
+ * AND-match) with a positional scoring layer that rewards in-order matches,
+ * first-word matches, perfect prefixes, dense (contiguous) matches, and shorter
+ * primary text.
+ *
+ * Results are sorted by score descending, with a stable tiebreaker on
+ * locale-aware primary-text comparison.
+ *
+ * @typeParam T - Item type (must extend SearchableObject)
+ * @param query - Raw query string (tokenized internally)
+ * @param data - SearchableData built via {@link arrayToSearchableData}
+ * @param metadata - NumericSearchMetadata built via {@link createSearchArrayMetadata}
+ * @param options - Scoring + retrieval options
+ * @returns Array of `{ id, item, score }` ordered by score descending
+ *
+ * @example
+ * ```typescript
+ * const results = searchAndRank("pot mat", data, meta, {
+ *   primaryTextFn: (a) => a.naziv,
+ *   exactKeysFn: (a) => a.crtneKode,
+ *   limit: 20,
+ * });
+ * // results[0].item.naziv === "POTROŠNI MATERIAL"
+ * ```
+ */
+export declare function searchAndRankNumeric<T extends SearchableObject>(query: string, data: SearchableData<T>, metadata: NumericSearchMetadata, options: SearchAndRankOptions<T>): ScoredResult<T>[];
+//# sourceMappingURL=searchAndRank.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"searchAndRank.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/searchAndRank.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACX,MAAM,aAAa,CAAC;AAOrB;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKvD;AACD;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,gBAAgB;IACtD,eAAe;IACf,EAAE,EAAE,EAAE,CAAC;IACP,wBAAwB;IACxB,IAAI,EAAE,CAAC,CAAC;IACR,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB;IAC9D;;;OAGG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACzD,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AACD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,gBAAgB,EACjD,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,EAC9C,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACxC,MAAM,CAyCR;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,EAC7D,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,YAAY,CAAC,CAAC,CAAC,EAAE,CA0BnB"}

package/dist/index.cjs

@@ -43,6 +43,9 @@ __export(exports_src, {
   searchInDataReturnObjects: () => searchInDataReturnObjectsNumeric,
   searchInDataReturnIds: () => searchInDataReturnIdsNumeric,
   searchInData: () => searchInDataReturnIdsNumeric,
+  searchAndRankNumeric: () => searchAndRankNumeric,
+  searchAndRank: () => searchAndRankNumeric,
+  scoreOne: () => scoreOne,
   sanitiseString: () => sanitiseString,
   resetTokenRegistry: () => resetTokenRegistry,
   removePrimaryItem: () => removePrimaryItemNumeric,
@@ -54,6 +57,7 @@ __export(exports_src, {
   prepareStringForSearch: () => prepareStringForSearch,
   prepareQueryTokens: () => prepareQueryTokens,
   prepareObjectForSearch: () => prepareObjectForSearchNumeric,
+  orderedTokenize: () => orderedTokenize,
   normalizeDates: () => normalizeDates,
   matchTokenInSortedListNumeric: () => matchTokenInSortedListNumeric,
   matchPreparedTokenInSortedList: () => matchPreparedTokenInSortedList,
@@ -1331,7 +1335,93 @@ function syncLinkedItemsForPrimaryNumeric(linked, primaryId, newLinkedItems, for
   clearTokensMap(tokensMap);
   return result;
 }
+// src/common/numeric/searchAndRank.ts
+function orderedTokenize(input) {
+  return tokenize(sanitiseString(preprocessString(normalizeDates(input))), DEFAULT_TOKENIZE_CONFIG);
+}
+function scoreOne(item, query, qTokens, primaryTextFn, exactKeys) {
+  if (exactKeys && exactKeys.length > 0) {
+    for (let i = 0;i < exactKeys.length; i++) {
+      if (exactKeys[i] === query)
+        return 1e5;
+    }
+  }
+  if (qTokens.length === 0)
+    return 0;
+  const primaryText = primaryTextFn(item) || "";
+  const itemTokens = orderedTokenize(primaryText);
+  if (itemTokens.length === 0)
+    return 1;
+  let qi = 0;
+  const positions = [];
+  for (let i = 0;i < itemTokens.length; i++) {
+    if (qi < qTokens.length && itemTokens[i].startsWith(qTokens[qi])) {
+      positions.push(i);
+      qi++;
+    }
+  }
+  if (qi === 0)
+    return 1;
+  let score = 50;
+  if (qi === qTokens.length)
+    score += 100;
+  if (positions[0] === 0)
+    score += 50;
+  let perfect = qi === qTokens.length;
+  if (perfect) {
+    for (let i = 0;i < positions.length; i++) {
+      if (positions[i] !== i) {
+        perfect = false;
+        break;
+      }
+    }
+  }
+  if (perfect)
+    score += 80;
+  if (positions.length >= 2) {
+    const span = positions[positions.length - 1] - positions[0] + 1;
+    score += positions.length / span * 30;
+  }
+  score -= primaryText.length * 0.1;
+  return score;
+}
+function searchAndRankNumeric(query, data, metadata, options) {
+  const { primaryTextFn, exactKeysFn, limit, opts } = options;
+  const ids = searchInDataReturnIdsNumeric(query, metadata, opts);
+  if (ids.length === 0)
+    return [];
+  const qTokens = orderedTokenize(query);
+  const scored = [];
+  for (const id of ids) {
+    const item = data.get(id);
+    if (!item)
+      continue;
+    const exactKeys = exactKeysFn?.(item);
+    const score = scoreOne(item, query, qTokens, primaryTextFn, exactKeys);
+    scored.push({ id, item, score });
+  }
+  scored.sort((x, y) => {
+    if (y.score !== x.score)
+      return y.score - x.score;
+    const xText = primaryTextFn(x.item) || "";
+    const yText = primaryTextFn(y.item) || "";
+    return xText.localeCompare(yText);
+  });
+  if (limit === undefined || limit === Infinity || limit >= scored.length)
+    return scored;
+  return scored.slice(0, limit);
+}
 // src/common/SearchUniverse.ts
+function tokensEqual3(a, b) {
+  if (a.length !== b.length)
+    return false;
+  for (let i = 0;i < a.length; i++) {
+    if (a[i] !== b[i])
+      return false;
+  }
+  return true;
+}
+
 class SearchUniverse {
   collections = new Map;
   registerCollection(name, config = {}) {
@@ -1535,6 +1625,113 @@ class SearchUniverse {
     }
     return removed;
   }
+  syncCollection(collectionName, newItems, options) {
+    const collection = this.getCollectionOrThrow(collectionName);
+    const result = {
+      added: 0,
+      updated: 0,
+      removed: 0,
+      addedIds: [],
+      updatedIds: [],
+      removedIds: []
+    };
+    const skipUpdateCheck = options?.skipUpdateCheck ?? false;
+    const fkGetter = collection.config.linkedTo ? collection.config.linkedTo.foreignKeyGetter : undefined;
+    const newIds = new Set;
+    for (const item of newItems)
+      newIds.add(item._id);
+    const toRemove = [];
+    for (const id of collection.data.keys()) {
+      if (!newIds.has(id))
+        toRemove.push(id);
+    }
+    for (const id of toRemove) {
+      const existing = collection.data.get(id);
+      if (fkGetter && collection.primaryToLinked) {
+        const fk = fkGetter(existing);
+        if (fk) {
+          const list = collection.primaryToLinked.get(fk);
+          if (list) {
+            const idx = list.indexOf(id);
+            if (idx !== -1) {
+              list.splice(idx, 1);
+              if (list.length === 0)
+                collection.primaryToLinked.delete(fk);
+            }
+          }
+        }
+      }
+      const hadMetadata = collection.metadata.has(id);
+      collection.data.delete(id);
+      collection.metadata.delete(id);
+      if (hadMetadata) {
+        result.removed++;
+        result.removedIds.push(id);
+      }
+    }
+    const tokensMap = createTokensMap();
+    try {
+      for (const item of newItems) {
+        const id = item._id;
+        const existing = collection.data.get(id);
+        const hadMetadata = collection.metadata.has(id);
+        const shouldTokenize = !existing || !skipUpdateCheck;
+        let newTokens;
+        if (shouldTokenize) {
+          newTokens = prepareObjectForSearchNumeric(item, collection.config.spec, tokensMap);
+        }
+        if (fkGetter && collection.primaryToLinked) {
+          const newFk = fkGetter(item);
+          const oldFk = existing ? fkGetter(existing) : undefined;
+          const wasInIndex = hadMetadata;
+          const shouldBeInIndex = !!newFk && !item._deleted && !item._blocked;
+          if (oldFk !== newFk || wasInIndex !== shouldBeInIndex) {
+            if (oldFk && wasInIndex) {
+              const list = collection.primaryToLinked.get(oldFk);
+              if (list) {
+                const idx = list.indexOf(id);
+                if (idx !== -1) {
+                  list.splice(idx, 1);
+                  if (list.length === 0)
+                    collection.primaryToLinked.delete(oldFk);
+                }
+              }
+            }
+            if (shouldBeInIndex && newFk) {
+              const list = collection.primaryToLinked.get(newFk) || [];
+              if (!list.includes(id))
+                list.push(id);
+              collection.primaryToLinked.set(newFk, list);
+            }
+          }
+        }
+        collection.data.set(id, item);
+        if (!shouldTokenize)
+          continue;
+        if (newTokens === undefined) {
+          if (hadMetadata) {
+            collection.metadata.delete(id);
+            result.removed++;
+            result.removedIds.push(id);
+          }
+        } else if (!hadMetadata) {
+          collection.metadata.set(id, newTokens);
+          result.added++;
+          result.addedIds.push(id);
+        } else {
+          const existingTokens = collection.metadata.get(id);
+          if (!tokensEqual3(existingTokens, newTokens)) {
+            collection.metadata.set(id, newTokens);
+            result.updated++;
+            result.updatedIds.push(id);
+          }
+        }
+      }
+    } finally {
+      clearTokensMap(tokensMap);
+    }
+    return result;
+  }
   getCollectionOrThrow(name) {
     const collection = this.collections.get(name);
     if (!collection) {

package/dist/index.d.cts

@@ -22,5 +22,6 @@ export { syncSearchArrayMetadataNumeric as syncSearchArrayMetadata, syncSearchAr
 export { upsertPrimaryItemNumeric as upsertPrimaryItem, removePrimaryItemNumeric as removePrimaryItem, upsertLinkedItemNumeric as upsertLinkedItem, removeLinkedItemNumeric as removeLinkedItem, syncLinkedItemsForPrimaryNumeric as syncLinkedItemsForPrimary, } from './common/numeric/updateSearchLinkedMetadata';
 export { matchTokenInSortedListNumeric, allTokensMatchNumeric, binarySearchUint32, prepareQueryTokens, matchPreparedTokenInSortedList, allPreparedTokensMatch, type PreparedQueryToken, } from './utils/matchTokenNumeric';
 export { isDeletedOrBlocked } from './common/string/createSearchArrayMetadata';
+export { searchAndRankNumeric as searchAndRank, searchAndRankNumeric, scoreOne, orderedTokenize, type ScoredResult, type SearchAndRankOptions, } from './common/numeric/searchAndRank';
 export { SearchUniverse } from './common/SearchUniverse';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -22,5 +22,6 @@ export { syncSearchArrayMetadataNumeric as syncSearchArrayMetadata, syncSearchAr
 export { upsertPrimaryItemNumeric as upsertPrimaryItem, removePrimaryItemNumeric as removePrimaryItem, upsertLinkedItemNumeric as upsertLinkedItem, removeLinkedItemNumeric as removeLinkedItem, syncLinkedItemsForPrimaryNumeric as syncLinkedItemsForPrimary, } from './common/numeric/updateSearchLinkedMetadata';
 export { matchTokenInSortedListNumeric, allTokensMatchNumeric, binarySearchUint32, prepareQueryTokens, matchPreparedTokenInSortedList, allPreparedTokensMatch, type PreparedQueryToken, } from './utils/matchTokenNumeric';
 export { isDeletedOrBlocked } from './common/string/createSearchArrayMetadata';
+export { searchAndRankNumeric as searchAndRank, searchAndRankNumeric, scoreOne, orderedTokenize, type ScoredResult, type SearchAndRankOptions, } from './common/numeric/searchAndRank';
 export { SearchUniverse } from './common/SearchUniverse';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,YAAY,EAEV,EAAE,EACF,WAAW,EACX,qBAAqB,EACrB,cAAc,EAEd,YAAY,EACZ,sBAAsB,EACtB,qBAAqB,EAErB,gBAAgB,EAChB,SAAS,EACT,oBAAoB,EAEpB,UAAU,EAEV,oBAAoB,EACpB,4BAA4B,EAC5B,2BAA2B,EAC3B,kBAAkB,EAClB,0BAA0B,EAE1B,oBAAoB,EAEpB,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,6BAA6B,EAE7B,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EAEjB,cAAc,IAAI,oBAAoB,EACtC,mBAAmB,EACnB,cAAc,EACd,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,qBAAqB,IAAI,cAAc,EAAE,MAAM,SAAS,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAKxD,OAAO,EACL,MAAM,EACN,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EACL,gCAAgC,IAAI,yBAAyB,EAC7D,6BAA6B,IAAI,sBAAsB,EACvD,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,iCAAiC,IAAI,0BAA0B,EAC/D,KAAK,mCAAmC,GACzC,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EACL,2BAA2B,IAAI,oBAAoB,EACnD,gCAAgC,IAAI,yBAAyB,EAC7D,+BAA+B,IAAI,wBAAwB,EAC3D,oCAAoC,IAAI,6BAA6B,GACtE,MAAM,uCAAuC,CAAC;AAG/C,OAAO,EACL,4BAA4B,IAAI,YAAY,EAC5C,4BAA4B,IAAI,qBAAqB,EACrD,gCAAgC,IAAI,yBAAyB,EAC7D,qCAAqC,IAAI,qBAAqB,GAC/D,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,qCAAqC,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAGvE,OAAO,EACL,8BAA8B,IAAI,uBAAuB,EACzD,0CAA0C,IAAI,mCAAmC,GAClF,MAAM,0CAA0C,CAAC;AAGlD,OAAO,EACL,wBAAwB,IAAI,iBAAiB,EAC7C,wBAAwB,IAAI,iBAAiB,EAC7C,uBAAuB,IAAI,gBAAgB,EAC3C,uBAAuB,IAAI,gBAAgB,EAC3C,gCAAgC,IAAI,yBAAyB,GAC9D,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,kBAAkB,EAElB,kBAAkB,EAClB,8BAA8B,EAC9B,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAK/E,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1246,7 +1246,93 @@ function syncLinkedItemsForPrimaryNumeric(linked, primaryId, newLinkedItems, for
   clearTokensMap(tokensMap);
   return result;
 }
+// src/common/numeric/searchAndRank.ts
+function orderedTokenize(input) {
+  return tokenize(sanitiseString(preprocessString(normalizeDates(input))), DEFAULT_TOKENIZE_CONFIG);
+}
+function scoreOne(item, query, qTokens, primaryTextFn, exactKeys) {
+  if (exactKeys && exactKeys.length > 0) {
+    for (let i = 0;i < exactKeys.length; i++) {
+      if (exactKeys[i] === query)
+        return 1e5;
+    }
+  }
+  if (qTokens.length === 0)
+    return 0;
+  const primaryText = primaryTextFn(item) || "";
+  const itemTokens = orderedTokenize(primaryText);
+  if (itemTokens.length === 0)
+    return 1;
+  let qi = 0;
+  const positions = [];
+  for (let i = 0;i < itemTokens.length; i++) {
+    if (qi < qTokens.length && itemTokens[i].startsWith(qTokens[qi])) {
+      positions.push(i);
+      qi++;
+    }
+  }
+  if (qi === 0)
+    return 1;
+  let score = 50;
+  if (qi === qTokens.length)
+    score += 100;
+  if (positions[0] === 0)
+    score += 50;
+  let perfect = qi === qTokens.length;
+  if (perfect) {
+    for (let i = 0;i < positions.length; i++) {
+      if (positions[i] !== i) {
+        perfect = false;
+        break;
+      }
+    }
+  }
+  if (perfect)
+    score += 80;
+  if (positions.length >= 2) {
+    const span = positions[positions.length - 1] - positions[0] + 1;
+    score += positions.length / span * 30;
+  }
+  score -= primaryText.length * 0.1;
+  return score;
+}
+function searchAndRankNumeric(query, data, metadata, options) {
+  const { primaryTextFn, exactKeysFn, limit, opts } = options;
+  const ids = searchInDataReturnIdsNumeric(query, metadata, opts);
+  if (ids.length === 0)
+    return [];
+  const qTokens = orderedTokenize(query);
+  const scored = [];
+  for (const id of ids) {
+    const item = data.get(id);
+    if (!item)
+      continue;
+    const exactKeys = exactKeysFn?.(item);
+    const score = scoreOne(item, query, qTokens, primaryTextFn, exactKeys);
+    scored.push({ id, item, score });
+  }
+  scored.sort((x, y) => {
+    if (y.score !== x.score)
+      return y.score - x.score;
+    const xText = primaryTextFn(x.item) || "";
+    const yText = primaryTextFn(y.item) || "";
+    return xText.localeCompare(yText);
+  });
+  if (limit === undefined || limit === Infinity || limit >= scored.length)
+    return scored;
+  return scored.slice(0, limit);
+}
 // src/common/SearchUniverse.ts
+function tokensEqual3(a, b) {
+  if (a.length !== b.length)
+    return false;
+  for (let i = 0;i < a.length; i++) {
+    if (a[i] !== b[i])
+      return false;
+  }
+  return true;
+}
+
 class SearchUniverse {
   collections = new Map;
   registerCollection(name, config = {}) {
@@ -1450,6 +1536,113 @@ class SearchUniverse {
     }
     return removed;
   }
+  syncCollection(collectionName, newItems, options) {
+    const collection = this.getCollectionOrThrow(collectionName);
+    const result = {
+      added: 0,
+      updated: 0,
+      removed: 0,
+      addedIds: [],
+      updatedIds: [],
+      removedIds: []
+    };
+    const skipUpdateCheck = options?.skipUpdateCheck ?? false;
+    const fkGetter = collection.config.linkedTo ? collection.config.linkedTo.foreignKeyGetter : undefined;
+    const newIds = new Set;
+    for (const item of newItems)
+      newIds.add(item._id);
+    const toRemove = [];
+    for (const id of collection.data.keys()) {
+      if (!newIds.has(id))
+        toRemove.push(id);
+    }
+    for (const id of toRemove) {
+      const existing = collection.data.get(id);
+      if (fkGetter && collection.primaryToLinked) {
+        const fk = fkGetter(existing);
+        if (fk) {
+          const list = collection.primaryToLinked.get(fk);
+          if (list) {
+            const idx = list.indexOf(id);
+            if (idx !== -1) {
+              list.splice(idx, 1);
+              if (list.length === 0)
+                collection.primaryToLinked.delete(fk);
+            }
+          }
+        }
+      }
+      const hadMetadata = collection.metadata.has(id);
+      collection.data.delete(id);
+      collection.metadata.delete(id);
+      if (hadMetadata) {
+        result.removed++;
+        result.removedIds.push(id);
+      }
+    }
+    const tokensMap = createTokensMap();
+    try {
+      for (const item of newItems) {
+        const id = item._id;
+        const existing = collection.data.get(id);
+        const hadMetadata = collection.metadata.has(id);
+        const shouldTokenize = !existing || !skipUpdateCheck;
+        let newTokens;
+        if (shouldTokenize) {
+          newTokens = prepareObjectForSearchNumeric(item, collection.config.spec, tokensMap);
+        }
+        if (fkGetter && collection.primaryToLinked) {
+          const newFk = fkGetter(item);
+          const oldFk = existing ? fkGetter(existing) : undefined;
+          const wasInIndex = hadMetadata;
+          const shouldBeInIndex = !!newFk && !item._deleted && !item._blocked;
+          if (oldFk !== newFk || wasInIndex !== shouldBeInIndex) {
+            if (oldFk && wasInIndex) {
+              const list = collection.primaryToLinked.get(oldFk);
+              if (list) {
+                const idx = list.indexOf(id);
+                if (idx !== -1) {
+                  list.splice(idx, 1);
+                  if (list.length === 0)
+                    collection.primaryToLinked.delete(oldFk);
+                }
+              }
+            }
+            if (shouldBeInIndex && newFk) {
+              const list = collection.primaryToLinked.get(newFk) || [];
+              if (!list.includes(id))
+                list.push(id);
+              collection.primaryToLinked.set(newFk, list);
+            }
+          }
+        }
+        collection.data.set(id, item);
+        if (!shouldTokenize)
+          continue;
+        if (newTokens === undefined) {
+          if (hadMetadata) {
+            collection.metadata.delete(id);
+            result.removed++;
+            result.removedIds.push(id);
+          }
+        } else if (!hadMetadata) {
+          collection.metadata.set(id, newTokens);
+          result.added++;
+          result.addedIds.push(id);
+        } else {
+          const existingTokens = collection.metadata.get(id);
+          if (!tokensEqual3(existingTokens, newTokens)) {
+            collection.metadata.set(id, newTokens);
+            result.updated++;
+            result.updatedIds.push(id);
+          }
+        }
+      }
+    } finally {
+      clearTokensMap(tokensMap);
+    }
+    return result;
+  }
   getCollectionOrThrow(name) {
     const collection = this.collections.get(name);
     if (!collection) {
@@ -1541,6 +1734,9 @@ export {
   searchInDataReturnObjectsNumeric as searchInDataReturnObjects,
   searchInDataReturnIdsNumeric as searchInDataReturnIds,
   searchInDataReturnIdsNumeric as searchInData,
+  searchAndRankNumeric,
+  searchAndRankNumeric as searchAndRank,
+  scoreOne,
   sanitiseString,
   resetTokenRegistry,
   removePrimaryItemNumeric as removePrimaryItem,
@@ -1552,6 +1748,7 @@ export {
   prepareStringForSearch,
   prepareQueryTokens,
   prepareObjectForSearchNumeric as prepareObjectForSearch,
+  orderedTokenize,
   normalizeDates,
   matchTokenInSortedListNumeric,
   matchPreparedTokenInSortedList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-search",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A fast, memory-efficient search library for large datasets with support for tokenized matching, linked collections, and per-field match modes.",
   "type": "module",
   "main": "./dist/index.js",