cry-search 1.0.7 → 2.0.0

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

@@ -1,4 +1,27 @@
-import type { MatchMode, NumericSearchMetadata, NumericTokenSortedList, SearchableObject, SearchableData, SearchableObjectSpec } from '../../types';
+import type { MatchMode, NumericSearchMetadata, NumericTokenSortedList, NumericTokenUnsortedList, SearchableObject, SearchableData, SearchableObjectSpec } from '../../types';
+/**
+ * Checks if an object is deleted or blocked and should be excluded from search.
+ *
+ * @param obj - The searchable object to check
+ * @returns True if the object has _deleted or _blocked set
+ *
+ * @example
+ * ```typescript
+ * isDeletedOrBlocked({ _id: '1', name: 'Test' })                    // false
+ * isDeletedOrBlocked({ _id: '1', name: 'Test', _deleted: new Date() }) // true
+ * ```
+ */
+export declare function isDeletedOrBlocked(obj: SearchableObject): boolean;
+/**
+ * Prefix characters for per-field match modes (used in {@link SearchableObjectSpec.fieldMatchModes}).
+ * Tokens from designated fields are stored with these prefixes so they match using the specified mode.
+ */
+export declare const MATCH_MODE_PREFIXES: Record<MatchMode, string>;
+/**
+ * Reverse mapping from query prefix to match mode.
+ * Used to parse user query strings like `=word`, `!word`, `?word`, `<word`, `>word`, `+word`, `*word`.
+ */
+export declare const PREFIX_TO_MATCH_MODE: Record<string, MatchMode>;
 /**
  * Prefix characters for per-field match modes.
  * Note: With numeric tokens, prefixes are encoded differently.
@@ -27,14 +50,29 @@ export declare function decodeTokenId(encoded: number): number;
  */
 export declare function decodeMatchMode(encoded: number): MatchMode;
 /**
- * Prepares an object for search, returning numeric token IDs.
+ * Per-item result of {@link prepareObjectForSearchNumeric}.
+ *
+ * - `sorted`: deduplicated, ASC-sorted token IDs (with per-field mode bits) for retrieval.
+ * - `firstN`: first N tokens of `spec.keyFields` content in source order — for
+ *   positional ranking. `undefined` when `keyFields` is not declared or yields no tokens.
+ */
+export interface PreparedObjectTokens {
+    sorted: NumericTokenSortedList;
+    firstN: NumericTokenUnsortedList | undefined;
+}
+/**
+ * Prepares an object for search, returning numeric token IDs for both retrieval and ranking.
+ *
+ * Two parallel outputs:
+ * - `sorted`: full sorted union of tokens from `searchInFields` (or all fields).
+ *   Per-field match modes are encoded in the high bits of each token ID.
+ * - `firstN`: tokens from `keyFields` (in declared order, concatenated), tokenized
+ *   without sort, capped to `spec.firstTokensN` (default 8). Used by
+ *   positional ranking. `undefined` when `keyFields` is not set.
  *
- * @param obj - The searchable object to prepare
- * @param spec - Optional specification for extraction and match modes
- * @param tokensMap - Map for string->number conversion
- * @returns undefined if object is _deleted or _blocked, otherwise sorted Uint32Array
+ * Returns `undefined` for `_deleted` / `_blocked` items.
  */
-export declare function prepareObjectForSearchNumeric<T extends SearchableObject, C = unknown>(obj: T, spec: SearchableObjectSpec<T, C> | undefined, tokensMap: Map<string, number>): NumericTokenSortedList | undefined;
+export declare function prepareObjectForSearchNumeric<T extends SearchableObject, C = unknown>(obj: T, spec: SearchableObjectSpec<T, C> | undefined, tokensMap: Map<string, number>): PreparedObjectTokens | undefined;
 /**
  * Creates numeric search metadata for a collection of items.
  *
@@ -62,4 +100,6 @@ export declare function prepareObjectForSearchNumeric<T extends SearchableObject
  * ```
  */
 export declare function createSearchArrayMetadataNumeric<T extends SearchableObject, C = unknown>(data: SearchableData<T>, spec?: SearchableObjectSpec<T, C>): NumericSearchMetadata;
+/** Constructs an empty {@link NumericSearchMetadata}. */
+export declare function emptyNumericSearchMetadata(): NumericSearchMetadata;
 //# sourceMappingURL=createSearchArrayMetadata.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"createSearchArrayMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/createSearchArrayMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACrB,MAAM,aAAa,CAAC;AASrB;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMrD,CAAC;AAKF,mDAAmD;AACnD,eAAO,MAAM,aAAa,QAAwB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAS1D;AAoED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACnF,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,sBAAsB,GAAG,SAAS,CAgBpC;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACtF,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,qBAAqB,CAmBvB"}
+{"version":3,"file":"createSearchArrayMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/createSearchArrayMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACrB,MAAM,aAAa,CAAC;AASrB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAEjE;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMzD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAS1D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMrD,CAAC;AAKF,mDAAmD;AACnD,eAAO,MAAM,aAAa,QAAwB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAS1D;AAoED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACnF,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,oBAAoB,GAAG,SAAS,CAoBlC;AA6GD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACtF,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,qBAAqB,CAoBvB;AAED,yDAAyD;AACzD,wBAAgB,0BAA0B,IAAI,qBAAqB,CAElE"}

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

@@ -1,12 +1,17 @@
 import type { SearchableObject, SearchOpts, LinkedSearchResult, LinkedSearchResultWithMeta } from '../../types';
 import type { NumericLinkedSearchMetadataWithData } from './createSearchLinkedMetadata';
 /**
- * Searches across linked data sets using numeric tokens.
+ * Searches across linked data sets using numeric tokens, ranked by positional relevance.
  *
- * For each primary item, collects all tokens from the primary and all its linked items,
+ * For each primary item, collects all tokens from the primary and its linked items,
  * then matches query tokens against this combined pool. Returns primary items with
  * only the linked items that contributed to the match.
  *
+ * **Ranking:** results are sorted by positional score (using `metadata.unsorted`
+ * of primary + matched linked items, in source order). Items with `keyFields`
+ * declared at build time get accurate positional scoring; items without retain
+ * primary insertion order via the deterministic tiebreaker.
+ *
  * **Key behaviors:**
  * - Tokens that match in the primary are excluded from linked matching (prevents
  *   foreign key redundancy)
@@ -25,8 +30,6 @@ import type { NumericLinkedSearchMetadataWithData } from './createSearchLinkedMe
 export declare function findInLinkedArraysNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject>(query: string, linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, limit?: number, opts?: SearchOpts): LinkedSearchResultWithMeta<TPrimary, TLinked>;
 /**
  * Simplified version of {@link findInLinkedArraysNumeric} that returns just the results.
- *
- * Use this when you don't need the query tokens metadata.
  */
 export declare function findInLinkedArraysSimpleNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject>(query: string, linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, limit?: number, opts?: SearchOpts): LinkedSearchResult<TPrimary, TLinked>[];
 //# sourceMappingURL=findInLinkedArrays.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"findInLinkedArrays.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/findInLinkedArrays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,8BAA8B,CAAC;AAQxF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAEhC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,KAAK,GAAE,MAAW,EAClB,IAAI,CAAC,EAAE,UAAU,GAChB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,CAAC,CAyJ/C;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAEhC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,KAAK,GAAE,MAAW,EAClB,IAAI,CAAC,EAAE,UAAU,GAChB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAEzC"}
+{"version":3,"file":"findInLinkedArrays.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/findInLinkedArrays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,8BAA8B,CAAC;AAUxF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAEhC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,KAAK,GAAE,MAAW,EAClB,IAAI,CAAC,EAAE,UAAU,GAChB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,CAAC,CA6K/C;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,SAAS,gBAAgB,EACjC,OAAO,SAAS,gBAAgB,EAEhC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mCAAmC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC9D,KAAK,GAAE,MAAW,EAClB,IAAI,CAAC,EAAE,UAAU,GAChB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAEzC"}

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

@@ -0,0 +1,95 @@
+/**
+ * Tokenize a string preserving source token order (no alphabetic sort).
+ *
+ * Mirrors `prepareStringForSearch` but skips the trailing `.sort()` —
+ * required for positional / order-aware scoring.
+ *
+ * NOTE: do NOT pass the result to retrieval functions (`searchInData...`); those
+ * assume sorted lists for efficient AND-match.
+ */
+export declare function orderedTokenize(input: string): string[];
+/**
+ * Compute relevance score against a query using positional signals.
+ *
+ * Scoring components (additive):
+ * - **+100_000** if raw `query` equals any `exactKeys` value.
+ * - **+50** base for any subsequence-prefix match in `itemTokens`.
+ * - **+100** if ALL query tokens match (in order).
+ * - **+50** if first matched position is 0 (itemTokens starts with first query token).
+ * - **+80** if matched positions form a contiguous prefix `[0..k-1]` (perfect prefix).
+ * - **+30 * (matchedCount / span)** density bonus.
+ * - **-0.1 * itemTokensJoinedLen** length penalty (weak tiebreaker).
+ *
+ * Returns **1** if no query token matched (e.g. item is in the candidate set
+ * only via a secondary field). Returns **0** for empty query.
+ *
+ * @param query - Raw query string (used only for exact-key match)
+ * @param qTokens - Query tokens in source order (from {@link orderedTokenize})
+ * @param itemTokens - Item tokens in source order
+ * @param exactKeys - Optional values for the +100_000 exact-match boost
+ */
+export declare function scoreOne(query: string, qTokens: string[], itemTokens: string[], exactKeys?: readonly string[] | undefined): number;
+/**
+ * Order-agnostic scoring: each query token that exists anywhere in `itemTokens`
+ * contributes `perTokenWeight`. Source order of either side is ignored.
+ *
+ * Use for fields where token order is conventional but not semantic — typically
+ * **person names** ("Janez Novak" === "Novak Janez"), tag lists, or pet breeds.
+ *
+ * Each query token contributes at most once, and each item token can be consumed
+ * by at most one query token (greedy left-to-right matching).
+ *
+ * Examples (default `perTokenWeight = 30`):
+ * - `query=[janez, novak]`, `item=[janez, novak]` → **60**
+ * - `query=[novak, janez]`, `item=[janez, novak]` → **60**  ← key invariant
+ * - `query=[janez, novak]`, `item=[novak, janez]` → **60**
+ * - `query=[janez, krajnik]`, `item=[janez, novak]` → 30 (only "janez" matches)
+ *
+ * Compare with order-sensitive {@link scoreOrderAndPresence}, which would give
+ * the reversed case (60 vs 40) different scores.
+ *
+ * @param qTokens - Query tokens
+ * @param itemTokens - Item tokens
+ * @param perTokenWeight - Bonus per matched query token (default 30)
+ */
+export declare function scoreBag(qTokens: string[], itemTokens: string[], perTokenWeight?: number): number;
+/**
+ * Per-token bonus weights for {@link scoreOrderAndPresence}.
+ *
+ * `ordered` should be larger than `presence` — in-order matches are stronger
+ * signals than out-of-order presence.
+ */
+export interface OrderAndPresenceWeights {
+    /** Bonus per query token that matches in subsequence-prefix order. @default 30 */
+    ordered?: number;
+    /** Bonus per query token that exists somewhere in `itemTokens` but not in order. @default 10 */
+    presence?: number;
+}
+/**
+ * Compute an additive bonus signal from `metadata.unsorted` ordered tokens.
+ *
+ * Designed to be ADDED to a base score (e.g. `scoreOne` result). Distinguishes
+ * three cases per query token:
+ * 1. **Ordered match** — query token appears in `itemTokens` at a position
+ *    consistent with the previous matches (subsequence-prefix in source order)
+ *    → adds `weights.ordered` (default 30).
+ * 2. **Presence-only** — query token appears somewhere in `itemTokens` but
+ *    breaks the source order → adds `weights.presence` (default 10).
+ * 3. **Absent** — no match in `itemTokens` → adds 0.
+ *
+ * Each query token contributes **at most once** (no double-counting): a token
+ * matched in phase 1 cannot also earn the presence bonus.
+ *
+ * Examples (defaults: ordered=30, presence=10):
+ * - `query=[izdaja, recepta]`, `item=[izdaja, recepta]` → 60 (both in order)
+ * - `query=[izdaja, recepta]`, `item=[izdaja]` → 30 (one in order, second absent)
+ * - `query=[izdaja, recepta]`, `item=[recepta, izdaja]` → 40 (first ordered + second presence)
+ *
+ * @param qTokens - Query tokens in source order (from {@link orderedTokenize})
+ * @param itemTokens - Item tokens in source order (typically from
+ *   `metadata.unsorted` via `tokens[id]` lookup)
+ * @param weights - Optional weight overrides
+ * @returns Additive bonus, ≥ 0
+ */
+export declare function scoreOrderAndPresence(qTokens: string[], itemTokens: string[], weights?: OrderAndPresenceWeights): number;
+//# sourceMappingURL=scoring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/scoring.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKvD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,EACpB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACxC,MAAM,CAyCR;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,EACpB,cAAc,SAAK,GAClB,MAAM,CAgBR;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAkCR"}

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

@@ -1,90 +1,48 @@
 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[];
+export { scoreOne, orderedTokenize, scoreOrderAndPresence, scoreBag } from "./scoring";
+export type { OrderAndPresenceWeights } from "./scoring";
 /**
  * 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.
+ * Options controlling {@link searchAndRankNumeric} 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`).
+     * Extracts the primary display text for an item. Used as **fallback** when
+     * `metadata.unsorted` has no entry for this id (i.e. spec didn't declare
+     * `keyFields`), and for locale-aware tiebreaker sorting.
      */
     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.
+     * Optional: extracts values that must equal the raw query string for the
+     * top-priority +100_000 exact-key boost (e.g. crtnaKoda / barcode).
      */
     exactKeysFn?: (item: T) => readonly string[] | undefined;
-    /** Maximum number of ranked results to return. Default: Infinity. */
+    /** Maximum number of ranked results returned. 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.
+ * Search with positional relevance scoring and return ranked results.
  *
- * Results are sorted by score descending, with a stable tiebreaker on
- * locale-aware primary-text comparison.
+ * Combines candidate retrieval ({@link searchInDataReturnIdsNumeric}, AND-match
+ * over sorted token lists) with positional scoring per candidate. For best
+ * performance, declare `spec.keyFields` so item tokens are pre-stored in
+ * `metadata.unsorted` and `searchAndRank` avoids re-tokenizing at query time.
  *
- * @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
+ * When `metadata.unsorted` has no entry for an id (i.e. `keyFields` not
+ * declared at build time), this function falls back to `orderedTokenize(
+ * primaryTextFn(item))` — same behavior as before the `keyFields` optimization.
  *
- * @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"
- * ```
+ * Sort: score DESC, locale-aware `primaryTextFn(item)` ASC as tiebreaker.
  */
 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

@@ -1 +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"}
+{"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;AAMrB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACvF,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAgBzD;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,gBAAgB;IACtD,EAAE,EAAE,EAAE,CAAC;IACP,IAAI,EAAE,CAAC,CAAC;IACR,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB;IAC9D;;;;OAIG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACzD,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;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,CAiCnB"}

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

@@ -2,30 +2,38 @@ import type { Id, NumericSearchMetadata, SearchableData, SearchableObject, Searc
 /**
  * Searches in numeric metadata and returns matching IDs.
  *
+ * Results are RANKED by positional relevance when `spec.keyFields` is declared
+ * for the source data: items whose `metadata.unsorted` carries pre-ordered key
+ * tokens get scored via `scoreOne`. Items without an `unsorted` entry land at
+ * the bottom (score 0) in original insertion order.
+ *
  * @param query - The search query string
  * @param metadata - The NumericSearchMetadata to search in
  * @param opts - Optional search options for match mode
- * @returns Array of matching object IDs
+ * @returns Array of matching object IDs sorted by relevance DESC
  */
 export declare function searchInDataReturnIdsNumeric(query: string, metadata: NumericSearchMetadata, opts?: SearchOpts): Id[];
 /**
- * Searches in numeric metadata and returns matching objects.
+ * Searches in numeric metadata and returns matching objects, ranked.
  *
  * @param query - The search query string
  * @param metadata - The NumericSearchMetadata to search in
  * @param data - The SearchableData map for object lookup
  * @param opts - Optional search options for match mode
- * @returns Map of matching objects by ID
+ * @returns Map of matching objects by ID. Iteration order = relevance DESC.
  */
 export declare function searchInDataReturnObjectsNumeric<T extends SearchableObject>(query: string, metadata: NumericSearchMetadata, data: SearchableData<T>, opts?: SearchOpts): Map<Id, T>;
 /**
- * Searches with a limit and returns matching IDs.
+ * Searches with a limit and returns matching IDs, RANKED by positional relevance.
  *
- * @param query - The search query string
- * @param metadata - The NumericSearchMetadata to search in
- * @param limit - Maximum number of results to return
- * @param opts - Optional search options for match mode
- * @returns Array of matching object IDs (up to limit)
+ * Retrieval: AND-match of query tokens against each item's `metadata.sorted` —
+ * same as before. Result order changes: candidates are scored using
+ * `metadata.unsorted` (if present) and sorted by score DESC before `limit` is
+ * applied. Items without `unsorted` entries fall back to score 0 and retain
+ * insertion order among themselves.
+ *
+ * To preserve raw insertion order (no ranking), use a metadata built without
+ * `spec.keyFields` — items will all score 0 and remain in iteration order.
  */
 export declare function searchInDataReturnIdsWithLimitNumeric(query: string, metadata: NumericSearchMetadata, limit: number, opts?: SearchOpts): Id[];
 //# sourceMappingURL=searchInData.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"searchInData.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/searchInData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACX,MAAM,aAAa,CAAC;AAIrB;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,CAAC,EAAE,UAAU,GAChB,EAAE,EAAE,CAEN;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,gBAAgB,EACzE,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,CAAC,EAAE,UAAU,GAChB,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAYZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,UAAU,GAChB,EAAE,EAAE,CAsBN"}
+{"version":3,"file":"searchInData.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/searchInData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACX,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,CAAC,EAAE,UAAU,GAChB,EAAE,EAAE,CAEN;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,gBAAgB,EACzE,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,CAAC,EAAE,UAAU,GAChB,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAYZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,UAAU,GAChB,EAAE,EAAE,CAiDN"}

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

@@ -3,62 +3,19 @@ export type { SyncResult, SyncOptions } from '../../types/index.js';
 /**
  * Syncs numeric search metadata with new data.
  *
- * This function performs a full sync of metadata against the provided data:
- * - Adds metadata for new items
- * - Removes metadata for items no longer in data (or marked `_deleted`/`_blocked`)
- * - Updates metadata for items whose tokens have changed
+ * Iterates `metadata.sorted.keys()` to find items absent from `newData` (removals).
+ * Then walks `newData`, tokenizing each item and updating metadata only when the
+ * resulting `sorted` or `firstN` differ from existing entries.
  *
- * Use this when you have completely new data to sync with. If you have both
- * previous and new data available, use {@link syncSearchArrayMetadataNumericWithPrevious}
- * for more efficient diffing.
- *
- * @typeParam T - Type of the searchable objects
- * @typeParam C - Type of the search context
- *
- * @param metadata - The NumericSearchMetadata map to update (mutated in place)
- * @param newData - The new data to sync with
- * @param spec - Optional specification for how to extract searchable text
- * @returns SyncResult with counts and IDs of added/updated/removed items
- *
- * @example
- * ```typescript
- * const newProducts = arrayToSearchableData(freshProductsFromServer);
- * const result = syncSearchArrayMetadataNumeric(metadata, newProducts, spec);
- *
- * console.log(`Added: ${result.added}, Updated: ${result.updated}, Removed: ${result.removed}`);
- * ```
+ * Use {@link syncSearchArrayMetadataNumericWithPrevious} when both previous and new
+ * datasets are on hand — it skips the `metadata.sorted.keys()` scan.
  */
 export declare function syncSearchArrayMetadataNumeric<T extends SearchableObject, C = unknown>(metadata: NumericSearchMetadata, newData: SearchableData<T>, spec?: SearchableObjectSpec<T, C>): SyncResult;
 /**
  * Syncs numeric search metadata using previous and new data for efficient diffing.
  *
- * More efficient than {@link syncSearchArrayMetadataNumeric} when you have both the
- * previous and new data available. Uses the previous data to determine
- * what was removed without iterating through all metadata keys.
- *
- * @typeParam T - Type of the searchable objects
- * @typeParam C - Type of the search context
- *
- * @param metadata - The NumericSearchMetadata map to update (mutated in place)
- * @param previousData - The previous data (used to determine what was removed)
- * @param newData - The new data to sync with
- * @param options - Optional sync options (e.g., skipUpdateCheck)
- * @param spec - Optional specification for how to extract searchable text
- * @returns SyncResult with counts and IDs of added/updated/removed items
- *
- * @example
- * ```typescript
- * const previousProducts = currentData;
- * const newProducts = arrayToSearchableData(freshProductsFromServer);
- *
- * const result = syncSearchArrayMetadataNumericWithPrevious(
- *   metadata,
- *   previousProducts,
- *   newProducts,
- *   { skipUpdateCheck: false },
- *   spec
- * );
- * ```
+ * Determines removals from `previousData` (no scan of metadata.sorted.keys()) and
+ * uses `options.skipUpdateCheck` to avoid re-tokenizing items that already existed.
  */
 export declare function syncSearchArrayMetadataNumericWithPrevious<T extends SearchableObject, C = unknown>(metadata: NumericSearchMetadata, previousData: SearchableData<T>, newData: SearchableData<T>, options?: SyncOptions, spec?: SearchableObjectSpec<T, C>): SyncResult;
 //# sourceMappingURL=syncSearchArrayMetadata.d.ts.map

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

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

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

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

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"updateSearchMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/updateSearchMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,6BAA6B,EAC9B,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACjF,QAAQ,EAAE,qBAAqB,EAC/B,QAAQ,EAAE,EAAE,EACZ,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EACzB,IAAI,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAUT;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACtF,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,6BAA6B,CAAC,CAAC,CAAC,EAAE,EACzC,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA0BtC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,qBAAqB,EAC/B,QAAQ,EAAE,EAAE,GACX,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,qBAAqB,EAC/B,SAAS,EAAE,EAAE,EAAE,GACd,MAAM,CAYR"}
+{"version":3,"file":"updateSearchMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/updateSearchMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,EAAE,EACF,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,6BAA6B,EAC9B,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACjF,QAAQ,EAAE,qBAAqB,EAC/B,QAAQ,EAAE,EAAE,EACZ,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EACzB,IAAI,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAgBT;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,GAAG,OAAO,EACtF,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,6BAA6B,CAAC,CAAC,CAAC,EAAE,EACzC,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA0BtC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,qBAAqB,EAC/B,QAAQ,EAAE,EAAE,GACX,OAAO,CAIT;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,qBAAqB,EAC/B,SAAS,EAAE,EAAE,EAAE,GACd,MAAM,CAYR"}