cry-search 2.0.0 → 2.0.2

package/CLAUDE.md

@@ -433,3 +433,23 @@ src/
    1. Memory: numeric ~45% less
    2. Build time: ~same
    3. Search time: varies by match mode
+
+## Phone number normalization
+
+- `DEFAULT_PHONE_FIELDS`: `telefon`, `phone`, `gsm`, `msisdn`.
+- `SearchableObjectSpec.phoneFields` compares exact field paths; configure
+  nested values such as `kontakt.telefon` explicitly. `[]` preserves legacy
+  tokenization.
+- Phone values are converted directly to one ASCII digit token and encoded with
+  `phoneMatchMode` (default `anywhere`); they do not pass through the ordinary
+  date/preprocess/sanitize/tokenize pipeline.
+- `phoneNormalizer` returns ASCII digits or `undefined`. Invalid non-digit
+  custom output throws at indexing time.
+- A complete phone-like query gets canonical phone variants before raw tokens;
+  if a phone variant has candidates, raw matching is only a fallback.
+- `phoneQueryNormalizer` overrides query recognition. `SearchUniverse` derives
+  its normalizers from collection specs; direct custom search passes
+  `resolvePhoneQueryNormalizer(spec)` in `SearchOpts.phoneQueryNormalizers`.
+- `extractSearchableStringFn` is an explicit escape hatch and bypasses automatic
+  phone-field processing. Phone fields are excluded from `keyFields` positional
+  ranking.

package/README.md

@@ -450,6 +450,39 @@ Match mode for numbers is determined by the **target token's length** (not the q
 // Use "=12" for exact match on short numbers
 ```
 
+### Phone Number Normalization
+
+Phone fields are indexed as one canonical digit token, so the following values
+converge without adding a dependency on a country-specific phone library:
+
+```text
+041/123-456      → 041123456
+041 123 456      → 041123456
++386 41 123 456  → 38641123456
+```
+
+`telefon`, `phone`, `gsm`, and `msisdn` are normalized by default. Configure
+additional nested paths explicitly, or opt out per collection:
+
+```typescript
+const spec = {
+  searchInFields: ['name', 'kontakt.telefon'],
+  phoneFields: ['kontakt.telefon'],
+  // phoneFields: [], // preserve legacy segment tokenization
+};
+```
+
+A complete phone-like query is normalized before the ordinary tokenized query.
+Phone results take priority; raw tokens are used only when no phone variant
+matches. This keeps `041 123 456` precise while preserving raw-code search as a
+fallback. Mixed text such as `Janez 041/123-456` is intentionally not parsed
+as a phone query.
+
+For custom canonicalization, configure `phoneNormalizer`. `SearchUniverse`
+uses its matching query normalizer automatically. A direct `searchInData*`
+caller must pass `resolvePhoneQueryNormalizer(spec)` via
+`phoneQueryNormalizers` when using a custom normalizer.
+
 ### Hyphen Splitting
 
 Tokens are split at letter-dash-digit, digit-dash-letter and letter-dash-letter boundaries during preprocessing. Digit-dash-digit ranges (e.g., `12-25`) are preserved.

package/UNIVERSE.md

@@ -862,3 +862,16 @@ For direct metadata manipulation without SearchUniverse:
 │                                                                             │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
+
+## Phone number normalization
+
+`SearchUniverse.searchUniversally` derives a phone query normalizer from each
+collection's `spec`. A standalone collection uses its own normalizer. A linked
+search evaluates normalizers from both the primary and linked specs, so a
+custom primary phone format remains searchable through a linked collection.
+
+For a complete phone-like query, matching canonical phone variants takes
+priority over the ordinary segmented query. If no phone variant finds a result,
+SearchUniverse falls back to its usual raw-token search. Caller-supplied
+`phoneQueryNormalizers` are additional variants; they do not replace the
+collection-derived normalizers.

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

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

package/dist/common/numeric/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,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"}
+{"version":3,"file":"createSearchArrayMetadata.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/createSearchArrayMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAUrB;;;;;;;;;;;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,CA0BlC;AAgID;;;;;;;;;;;;;;;;;;;;;;;;;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,31 +1,9 @@
 import type { SearchableObject, SearchOpts, LinkedSearchResult, LinkedSearchResultWithMeta } from '../../types';
 import type { NumericLinkedSearchMetadataWithData } from './createSearchLinkedMetadata';
 /**
- * Searches across linked data sets using numeric tokens, ranked by positional relevance.
+ * Searches linked metadata with canonical phone variants before raw query tokens.
  *
- * 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)
- * - Only linked items that match ALL remaining tokens are included in results
- * - `matchedIn` indicates where the match was found: 'primary', 'linked', or 'both'
- *
- * @typeParam TPrimary - Type of primary items (e.g., Stranka)
- * @typeParam TLinked - Type of linked items (e.g., Pacient)
- *
- * @param query - The search query string (will be tokenized)
- * @param linked - Linked metadata from {@link createSearchLinkedMetadataNumeric}
- * @param limit - Maximum number of results to return (default: 10)
- * @param opts - Optional search options for controlling match behavior
- * @returns Search results with query tokens, matching items, and hasNegation flag
+ * @feature [phone-search]
  */
 export declare function findInLinkedArraysNumeric<TPrimary extends SearchableObject, TLinked extends SearchableObject>(query: string, linked: NumericLinkedSearchMetadataWithData<TPrimary, TLinked>, limit?: number, opts?: SearchOpts): LinkedSearchResultWithMeta<TPrimary, TLinked>;
 /**

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;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"}
+{"version":3,"file":"findInLinkedArrays.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/findInLinkedArrays.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,8BAA8B,CAAC;AA6QxF;;;;GAIG;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,CAoC/C;AAiCD;;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/prepareQueryVariants.d.ts

@@ -0,0 +1,15 @@
+import type { PreparedQueryToken } from '../../utils/matchTokenNumeric';
+import type { SearchOpts } from '../../types';
+/** Prepared raw and canonical-phone alternatives for one search query. */
+export interface PreparedQueryVariants {
+    rawTokenStrs: string[];
+    rawTokens: PreparedQueryToken[];
+    phoneTokens: PreparedQueryToken[][];
+}
+/**
+ * Produces deduplicated phone alternatives without changing ordinary query tokens.
+ *
+ * @feature [phone-search]
+ */
+export declare function prepareQueryVariants(query: string, opts?: SearchOpts): PreparedQueryVariants;
+//# sourceMappingURL=prepareQueryVariants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareQueryVariants.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/prepareQueryVariants.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAIxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,WAAW,EAAE,kBAAkB,EAAE,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,qBAAqB,CAmB5F"}

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;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"}
+{"version":3,"file":"searchInData.d.ts","sourceRoot":"","sources":["../../../src/common/numeric/searchInData.ts"],"names":[],"mappings":"AACA,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,CA4CN"}

package/dist/index.cjs

@@ -2,27 +2,37 @@ var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
+function __accessProp(key) {
+  return this[key];
+}
 var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
     return entry;
   entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
   __moduleCache.set(from, entry);
   return entry;
 };
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -49,6 +59,7 @@ __export(exports_src, {
   scoreOne: () => scoreOne,
   scoreBag: () => scoreBag,
   sanitiseString: () => sanitiseString,
+  resolvePhoneQueryNormalizer: () => resolvePhoneQueryNormalizer,
   resetTokenRegistry: () => resetTokenRegistry,
   removePrimaryItem: () => removePrimaryItemNumeric,
   removeLinkedItem: () => removeLinkedItemNumeric,
@@ -71,6 +82,8 @@ __export(exports_src, {
   findInLinkedArraysSimpleNumeric: () => findInLinkedArraysSimpleNumeric,
   findInLinkedArraysNumeric: () => findInLinkedArraysNumeric,
   encodeTokenWithMode: () => encodeTokenWithMode,
+  defaultQueryPhoneNormalizer: () => defaultQueryPhoneNormalizer,
+  defaultPhoneNormalizer: () => defaultPhoneNormalizer,
   decodeTokenId: () => decodeTokenId,
   decodeMatchMode: () => decodeMatchMode,
   createTokensMap: () => createTokensMap,
@@ -87,11 +100,13 @@ __export(exports_src, {
   MATCH_MODE_PREFIXES: () => MATCH_MODE_PREFIXES,
   MATCH_MODE_BITS: () => MATCH_MODE_BITS,
   DEFAULT_SEARCH_OPTS: () => DEFAULT_SEARCH_OPTS,
+  DEFAULT_PHONE_FIELDS: () => DEFAULT_PHONE_FIELDS,
   AugmentedMetadata: () => AugmentedMetadata
 });
 module.exports = __toCommonJS(exports_src);
 
 // src/types/index.ts
+var DEFAULT_PHONE_FIELDS = ["telefon", "phone", "gsm", "msisdn"];
 var DEFAULT_FIRST_TOKENS_N = 8;
 var DEFAULT_SEARCH_OPTS = {
   matchWords: "start",
@@ -304,6 +319,37 @@ function prepareStringForSearch(input) {
   const tokens = tokenize(sanitised, DEFAULT_TOKENIZE_CONFIG);
   return tokens.sort();
 }
+// src/utils/phoneNormalization.ts
+var RE_ASCII_DIGITS = /^[0-9]+$/;
+var RE_PHONE_LIKE_QUERY = /^[\d+()/\-. ]+$/;
+var MIN_PHONE_DIGITS = 4;
+var defaultPhoneNormalizer = (value) => {
+  const digits = value.replace(/\D/g, "");
+  return digits.length >= MIN_PHONE_DIGITS ? digits : undefined;
+};
+var defaultQueryPhoneNormalizer = (query) => {
+  if (!RE_PHONE_LIKE_QUERY.test(query))
+    return;
+  return defaultPhoneNormalizer(query);
+};
+function validateNormalizedPhone(normalized, normalizerName) {
+  if (normalized === undefined)
+    return;
+  if (typeof normalized !== "string" || !RE_ASCII_DIGITS.test(normalized)) {
+    throw new Error(`${normalizerName} must return an ASCII digit string or undefined`);
+  }
+  return normalized;
+}
+function resolvePhoneQueryNormalizer(spec) {
+  if (spec?.phoneQueryNormalizer)
+    return spec.phoneQueryNormalizer;
+  const phoneNormalizer = spec?.phoneNormalizer ?? defaultPhoneNormalizer;
+  return (query) => {
+    if (!RE_PHONE_LIKE_QUERY.test(query))
+      return;
+    return phoneNormalizer(query);
+  };
+}
 // src/utils/tokenRegistry.ts
 var INITIAL_CAPACITY = 10 * 1000;
 var tokens = new Array(INITIAL_CAPACITY);
@@ -481,7 +527,7 @@ function prepareObjectForSearchNumeric(obj, spec, tokensMap) {
   const sorted = spec?.extractSearchableStringFn ? buildSortedFromExtractFn(obj, spec.extractSearchableStringFn, tokensMap) : buildSortedFromFields(obj, spec, tokensMap);
   if (sorted === undefined)
     return;
-  const firstN = spec?.keyFields && spec.keyFields.length > 0 ? buildFirstNFromKeyFields(obj, spec.keyFields, spec.firstTokensN ?? DEFAULT_FIRST_TOKENS_N, tokensMap) : undefined;
+  const firstN = spec?.keyFields && spec.keyFields.length > 0 ? buildFirstNFromKeyFields(obj, spec.keyFields, spec.firstTokensN ?? DEFAULT_FIRST_TOKENS_N, spec.phoneFields ?? DEFAULT_PHONE_FIELDS, tokensMap) : undefined;
   return { sorted, firstN };
 }
 function buildSortedFromExtractFn(obj, extractFn, tokensMap) {
@@ -494,7 +540,9 @@ function buildSortedFromFields(obj, spec, tokensMap) {
   const allTokens = [];
   const fieldMatchModes = spec?.fieldMatchModes;
   const fieldsToSearch = spec?.searchInFields ?? Object.keys(obj);
-  const fieldsToExclude = new Set(spec?.dontSearchInFields ?? []);
+  const fieldsToExclude = new Set((spec?.dontSearchInFields ?? []).map(String));
+  const phoneFields = new Set(spec?.phoneFields ?? DEFAULT_PHONE_FIELDS);
+  const phoneNormalizer = spec?.phoneNormalizer ?? defaultPhoneNormalizer;
   for (const key of fieldsToSearch) {
     const keyStr = key;
     if (!spec?.searchInFields && DEFAULT_EXCLUDED_FIELDS.has(keyStr))
@@ -502,36 +550,50 @@ function buildSortedFromFields(obj, spec, tokensMap) {
     if (fieldsToExclude.has(key))
       continue;
     const isDot = isDotNotation(keyStr);
-    const value = isDot ? getValueByPath(obj, keyStr) : obj[key];
+    const value = isDot ? getValueByPath(obj, keyStr) : obj[keyStr];
     if (value == null)
       continue;
     const matchMode = fieldMatchModes?.[key];
     const fieldStrings = [];
     extractStringsFromValue(value, fieldStrings);
-    if (fieldStrings.length > 0) {
-      const fieldText = fieldStrings.join(" ");
-      const datesNormalized = normalizeDates(fieldText);
-      const preprocessed = preprocessString(datesNormalized);
-      const sanitised = sanitiseString(preprocessed);
-      const stringTokens = tokenize(sanitised, DEFAULT_TOKENIZE_CONFIG);
-      const effectiveMode = matchMode ?? (keyStr === "_id" ? "whole" : undefined);
-      for (const token of stringTokens) {
-        const tokenId = getOrCreateTokenId(token, tokensMap);
-        if (effectiveMode) {
-          allTokens.push(encodeTokenWithMode(tokenId, effectiveMode));
-        } else {
-          allTokens.push(tokenId);
-        }
+    if (phoneFields.has(keyStr)) {
+      const phoneMatchMode = spec?.phoneMatchMode ?? "anywhere";
+      for (const fieldString of fieldStrings) {
+        const normalized = validateNormalizedPhone(phoneNormalizer(fieldString), `Phone normalizer for field "${keyStr}"`);
+        if (normalized === undefined)
+          continue;
+        const tokenId = getOrCreateTokenId(normalized, tokensMap);
+        allTokens.push(encodeTokenWithMode(tokenId, phoneMatchMode));
+      }
+      continue;
+    }
+    if (fieldStrings.length === 0)
+      continue;
+    const fieldText = fieldStrings.join(" ");
+    const datesNormalized = normalizeDates(fieldText);
+    const preprocessed = preprocessString(datesNormalized);
+    const sanitised = sanitiseString(preprocessed);
+    const stringTokens = tokenize(sanitised, DEFAULT_TOKENIZE_CONFIG);
+    const effectiveMode = matchMode ?? (keyStr === "_id" ? "whole" : undefined);
+    for (const token of stringTokens) {
+      const tokenId = getOrCreateTokenId(token, tokensMap);
+      if (effectiveMode) {
+        allTokens.push(encodeTokenWithMode(tokenId, effectiveMode));
+      } else {
+        allTokens.push(tokenId);
       }
     }
   }
   const uniqueTokens = [...new Set(allTokens)].sort((a, b) => a - b);
   return new Uint32Array(uniqueTokens);
 }
-function buildFirstNFromKeyFields(obj, keyFields, n, tokensMap) {
+function buildFirstNFromKeyFields(obj, keyFields, n, phoneFields, tokensMap) {
   const strings = [];
+  const phoneFieldPaths = new Set(phoneFields);
   for (const field of keyFields) {
     const keyStr = field;
+    if (phoneFieldPaths.has(keyStr))
+      continue;
     const value = isDotNotation(keyStr) ? getValueByPath(obj, keyStr) : obj[field];
     if (value == null)
       continue;
@@ -834,6 +896,23 @@ function allTokensMatchNumeric(searchTokenStrs, targetTokens, opts) {
   return allPreparedTokensMatch(preparedTokens, targetTokens, opts);
 }
 
+// src/common/numeric/prepareQueryVariants.ts
+function prepareQueryVariants(query, opts) {
+  const rawTokenStrs = prepareStringForSearch(query);
+  const rawTokens = prepareQueryTokens(rawTokenStrs);
+  const normalizers = opts?.phoneQueryNormalizers ?? [defaultQueryPhoneNormalizer];
+  const seenPhones = new Set;
+  const phoneTokens = [];
+  for (const normalizer of normalizers) {
+    const normalized = validateNormalizedPhone(normalizer(query), "Phone query normalizer");
+    if (normalized === undefined || seenPhones.has(normalized))
+      continue;
+    seenPhones.add(normalized);
+    phoneTokens.push(prepareQueryTokens([normalized]));
+  }
+  return { rawTokenStrs, rawTokens, phoneTokens };
+}
+
 // src/common/numeric/scoring.ts
 function orderedTokenize(input) {
   return tokenize(sanitiseString(preprocessString(normalizeDates(input))), DEFAULT_TOKENIZE_CONFIG);
@@ -950,16 +1029,9 @@ function searchInDataReturnObjectsNumeric(query, metadata, data, opts) {
   return results;
 }
 function searchInDataReturnIdsWithLimitNumeric(query, metadata, limit, opts) {
-  const queryTokenStrs = prepareStringForSearch(query);
-  if (queryTokenStrs.length === 0)
-    return [];
-  const preparedTokens = prepareQueryTokens(queryTokenStrs);
-  const candidates = [];
-  for (const [id, targetTokens] of metadata.sorted) {
-    if (allPreparedTokensMatch(preparedTokens, targetTokens, opts)) {
-      candidates.push(id);
-    }
-  }
+  const { rawTokenStrs, rawTokens, phoneTokens } = prepareQueryVariants(query, opts);
+  const phoneCandidates = findMatchingCandidates(metadata, phoneTokens, opts);
+  const candidates = phoneCandidates.length > 0 ? phoneCandidates : findMatchingCandidates(metadata, rawTokens.length > 0 ? [rawTokens] : [], opts);
   if (candidates.length === 0)
     return [];
   const qTokens = orderedTokenize(query);
@@ -994,13 +1066,22 @@ function searchInDataReturnIdsWithLimitNumeric(query, metadata, limit, opts) {
     out.push(scored[i].id);
   return out;
 }
-// src/common/numeric/findInLinkedArrays.ts
-function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
-  const queryTokenStrs = prepareStringForSearch(query);
-  if (queryTokenStrs.length === 0) {
-    return { queryTokens: queryTokenStrs, results: [], hasNegation: false };
+function findMatchingCandidates(metadata, variants, opts) {
+  if (variants.length === 0)
+    return [];
+  const candidates = [];
+  for (const [id, targetTokens] of metadata.sorted) {
+    for (const preparedTokens of variants) {
+      if (allPreparedTokensMatch(preparedTokens, targetTokens, opts)) {
+        candidates.push(id);
+        break;
+      }
+    }
   }
-  const preparedTokens = prepareQueryTokens(queryTokenStrs);
+  return candidates;
+}
+// src/common/numeric/findInLinkedArrays.ts
+function findInLinkedArraysForPreparedTokens(query, queryTokenStrs, preparedTokens, linked, limit, opts) {
   const positiveTokens = preparedTokens.filter((t) => !t.negated);
   const negatedTokens = preparedTokens.filter((t) => t.negated);
   const scored = [];
@@ -1019,6 +1100,30 @@ function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
     }
     if (negatedMatchesInPrimary)
       continue;
+    let allPositiveMatchInPrimary = true;
+    for (const token of positiveTokens) {
+      if (!matchPreparedTokenInSortedList(token, primaryTokens, opts)) {
+        allPositiveMatchInPrimary = false;
+        break;
+      }
+    }
+    if (allPositiveMatchInPrimary && negatedTokens.length === 0) {
+      const matchedLinked2 = linkedIds.map((id) => linked.linkedData.get(id)).filter((item) => item !== undefined);
+      scored.push({
+        result: {
+          primary,
+          linked: matchedLinked2,
+          matchedIn: "primary"
+        },
+        score: 0,
+        order: orderCounter++,
+        primaryId,
+        matchedLinkedIds: matchedLinked2.map((l) => l._id)
+      });
+      continue;
+    }
+    if (!allPositiveMatchInPrimary && linkedIds.length === 0)
+      continue;
     let totalLength = primaryTokens.length;
     for (const linkedId of linkedIds) {
       const linkedTokens = linked.linkedMeta.sorted.get(linkedId);
@@ -1037,24 +1142,31 @@ function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
       }
     }
     allTokens.sort();
-    let allPositiveMatch = true;
-    for (const token of positiveTokens) {
-      if (!matchPreparedTokenInSortedList(token, allTokens, opts)) {
-        allPositiveMatch = false;
-        break;
+    if (!allPositiveMatchInPrimary) {
+      let allPositiveMatch = true;
+      for (const token of positiveTokens) {
+        if (!matchPreparedTokenInSortedList(token, allTokens, opts)) {
+          allPositiveMatch = false;
+          break;
+        }
       }
+      if (!allPositiveMatch)
+        continue;
     }
-    if (!allPositiveMatch)
-      continue;
-    let anyMatchInPrimary = false;
+    let anyMatchInPrimary = allPositiveMatchInPrimary;
     let anyMatchInLinked = false;
     const matchingLinkedIds = new Set;
     const tokensMatchingPrimary = new Set;
-    for (const preparedToken of positiveTokens) {
-      if (matchPreparedTokenInSortedList(preparedToken, primaryTokens, opts)) {
-        anyMatchInPrimary = true;
-        tokensMatchingPrimary.add(preparedToken);
+    if (!allPositiveMatchInPrimary) {
+      for (const preparedToken of positiveTokens) {
+        if (matchPreparedTokenInSortedList(preparedToken, primaryTokens, opts)) {
+          anyMatchInPrimary = true;
+          tokensMatchingPrimary.add(preparedToken);
+        }
       }
+    } else {
+      for (const t of positiveTokens)
+        tokensMatchingPrimary.add(t);
     }
     const tokensForLinkedMatching = positiveTokens.filter((t) => !tokensMatchingPrimary.has(t));
     if (tokensForLinkedMatching.length > 0 || negatedTokens.length > 0) {
@@ -1139,6 +1251,46 @@ function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
     results[i] = scored[i].result;
   return { queryTokens: queryTokenStrs, results, hasNegation: negatedTokens.length > 0 };
 }
+function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
+  const { rawTokenStrs, rawTokens, phoneTokens } = prepareQueryVariants(query, opts);
+  const phoneResults = [];
+  for (const preparedTokens of phoneTokens) {
+    const result = findInLinkedArraysForPreparedTokens(query, rawTokenStrs, preparedTokens, linked, Infinity, opts);
+    phoneResults.push(...result.results);
+  }
+  if (phoneResults.length > 0) {
+    return {
+      queryTokens: rawTokenStrs,
+      results: mergePhoneResults(phoneResults).slice(0, limit),
+      hasNegation: false
+    };
+  }
+  if (rawTokens.length === 0) {
+    return { queryTokens: rawTokenStrs, results: [], hasNegation: false };
+  }
+  return findInLinkedArraysForPreparedTokens(query, rawTokenStrs, rawTokens, linked, limit, opts);
+}
+function mergePhoneResults(results) {
+  const byPrimaryId = new Map;
+  for (const result of results) {
+    const existing = byPrimaryId.get(result.primary._id);
+    if (existing === undefined) {
+      byPrimaryId.set(result.primary._id, result);
+      continue;
+    }
+    const linkedById = new Map(existing.linked.map((item) => [item._id, item]));
+    for (const item of result.linked)
+      linkedById.set(item._id, item);
+    existing.linked = Array.from(linkedById.values());
+    existing.matchedIn = mergeMatchLocation(existing.matchedIn, result.matchedIn);
+  }
+  return Array.from(byPrimaryId.values());
+}
+function mergeMatchLocation(first, second) {
+  if (first === "both" || second === "both" || first !== second)
+    return "both";
+  return first;
+}
 function findInLinkedArraysSimpleNumeric(query, linked, limit = 10, opts) {
   return findInLinkedArraysNumeric(query, linked, limit, opts).results;
 }
@@ -1652,6 +1804,15 @@ function firstNEqual3(a, b) {
     return false;
   return tokensEqual3(a, b);
 }
+function withCollectionPhoneNormalizers(opts, specs) {
+  return {
+    ...opts,
+    phoneQueryNormalizers: [
+      ...specs.map((spec) => resolvePhoneQueryNormalizer(spec)),
+      ...opts.phoneQueryNormalizers ?? []
+    ]
+  };
+}
 
 class SearchUniverse {
   collections = new Map;
@@ -2012,7 +2173,11 @@ class SearchUniverse {
           primaryData: primaryCollection.data,
           linkedData: collection.data
         };
-        const linkedSearchResults = findInLinkedArraysNumeric(query, linkedMetadata, limit, searchOpts);
+        const linkedSearchOpts = withCollectionPhoneNormalizers(searchOpts, [
+          primaryCollection.config.spec,
+          collection.config.spec
+        ]);
+        const linkedSearchResults = findInLinkedArraysNumeric(query, linkedMetadata, limit, linkedSearchOpts);
         if (linkedSearchResults.results.length > 0) {
           const combinedResults = [];
           const hasNegation = linkedSearchResults.hasNegation;
@@ -2035,7 +2200,7 @@ class SearchUniverse {
         if (inCollections && !inCollections.includes(name)) {
           continue;
         }
-        const matchingIds = searchInDataReturnIdsWithLimitNumeric(query, collection.metadata, limit, searchOpts);
+        const matchingIds = searchInDataReturnIdsWithLimitNumeric(query, collection.metadata, limit, withCollectionPhoneNormalizers(searchOpts, [collection.config.spec]));
         if (matchingIds.length > 0) {
           const collectionResults = [];
           for (const id of matchingIds) {

package/dist/index.d.cts

@@ -2,15 +2,16 @@
  * cry-search - A fast, memory-efficient search library for large datasets
  * @packageDocumentation
  */
-export type { Id, SearchToken, SearchTokenSortedList, SearchableData, NumericToken, NumericTokenSortedList, NumericSearchMetadata, SearchableObject, MatchMode, SearchableObjectSpec, SearchOpts, SearchableLinkedObjectsSpec, LinkedSearchResult, LinkedSearchResultWithMeta, SearchResultWithMeta, SyncResult, SyncOptions, SyncLinkedResult, UpsertResult, UpdateSearchMetadataBatchItem, UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult, } from './types';
+export type { Id, SearchToken, SearchTokenSortedList, SearchableData, NumericToken, NumericTokenSortedList, NumericSearchMetadata, SearchableObject, MatchMode, PhoneNormalizer, PhoneQueryNormalizer, SearchableObjectSpec, SearchOpts, SearchableLinkedObjectsSpec, LinkedSearchResult, LinkedSearchResultWithMeta, SearchResultWithMeta, SyncResult, SyncOptions, SyncLinkedResult, UpsertResult, UpdateSearchMetadataBatchItem, UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult, } from './types';
 export type { NumericSearchMetadata as SearchMetadata } from './types';
-export { DEFAULT_SEARCH_OPTS } from './types';
+export { DEFAULT_SEARCH_OPTS, DEFAULT_PHONE_FIELDS } from './types';
 export { arrayToSearchableData, searchableDataToArray } from './types';
 export { prepareStringForSearch } from './utils/prepareStringForSearch';
 export { preprocessString } from './utils/preprocessString';
 export { sanitiseString } from './utils/sanitiseString';
 export { tokenize } from './utils/tokenize';
 export { normalizeDates } from './utils/normalizeDates';
+export { defaultPhoneNormalizer, defaultQueryPhoneNormalizer, resolvePhoneQueryNormalizer, } from './utils/phoneNormalization';
 export { tokens, getTokenCount, getTokenById, findTokenId, registerToken, getOrCreateTokenId, createTokensMap, clearTokensMap, resetTokenRegistry, } from './utils/tokenRegistry';
 export { createSearchArrayMetadataNumeric as createSearchArrayMetadata, prepareObjectForSearchNumeric as prepareObjectForSearch, encodeTokenWithMode, decodeTokenId, decodeMatchMode, TOKEN_ID_MASK, MATCH_MODE_BITS, MATCH_MODE_PREFIXES, PREFIX_TO_MATCH_MODE, isDeletedOrBlocked, } from './common/numeric/createSearchArrayMetadata';
 export { createSearchLinkedMetadataNumeric as createSearchLinkedMetadata, type NumericLinkedSearchMetadataWithData, } from './common/numeric/createSearchLinkedMetadata';

package/dist/index.d.ts

@@ -2,15 +2,16 @@
  * cry-search - A fast, memory-efficient search library for large datasets
  * @packageDocumentation
  */
-export type { Id, SearchToken, SearchTokenSortedList, SearchableData, NumericToken, NumericTokenSortedList, NumericSearchMetadata, SearchableObject, MatchMode, SearchableObjectSpec, SearchOpts, SearchableLinkedObjectsSpec, LinkedSearchResult, LinkedSearchResultWithMeta, SearchResultWithMeta, SyncResult, SyncOptions, SyncLinkedResult, UpsertResult, UpdateSearchMetadataBatchItem, UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult, } from './types';
+export type { Id, SearchToken, SearchTokenSortedList, SearchableData, NumericToken, NumericTokenSortedList, NumericSearchMetadata, SearchableObject, MatchMode, PhoneNormalizer, PhoneQueryNormalizer, SearchableObjectSpec, SearchOpts, SearchableLinkedObjectsSpec, LinkedSearchResult, LinkedSearchResultWithMeta, SearchResultWithMeta, SyncResult, SyncOptions, SyncLinkedResult, UpsertResult, UpdateSearchMetadataBatchItem, UniversalSearchOpts, CollectionConfig, UpdateResult, BatchUpdateResult, } from './types';
 export type { NumericSearchMetadata as SearchMetadata } from './types';
-export { DEFAULT_SEARCH_OPTS } from './types';
+export { DEFAULT_SEARCH_OPTS, DEFAULT_PHONE_FIELDS } from './types';
 export { arrayToSearchableData, searchableDataToArray } from './types';
 export { prepareStringForSearch } from './utils/prepareStringForSearch';
 export { preprocessString } from './utils/preprocessString';
 export { sanitiseString } from './utils/sanitiseString';
 export { tokenize } from './utils/tokenize';
 export { normalizeDates } from './utils/normalizeDates';
+export { defaultPhoneNormalizer, defaultQueryPhoneNormalizer, resolvePhoneQueryNormalizer, } from './utils/phoneNormalization';
 export { tokens, getTokenCount, getTokenById, findTokenId, registerToken, getOrCreateTokenId, createTokensMap, clearTokensMap, resetTokenRegistry, } from './utils/tokenRegistry';
 export { createSearchArrayMetadataNumeric as createSearchArrayMetadata, prepareObjectForSearchNumeric as prepareObjectForSearch, encodeTokenWithMode, decodeTokenId, decodeMatchMode, TOKEN_ID_MASK, MATCH_MODE_BITS, MATCH_MODE_PREFIXES, PREFIX_TO_MATCH_MODE, isDeletedOrBlocked, } from './common/numeric/createSearchArrayMetadata';
 export { createSearchLinkedMetadataNumeric as createSearchLinkedMetadata, type NumericLinkedSearchMetadataWithData, } from './common/numeric/createSearchLinkedMetadata';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/types/index.ts
+var DEFAULT_PHONE_FIELDS = ["telefon", "phone", "gsm", "msisdn"];
 var DEFAULT_FIRST_TOKENS_N = 8;
 var DEFAULT_SEARCH_OPTS = {
   matchWords: "start",
@@ -211,6 +212,37 @@ function prepareStringForSearch(input) {
   const tokens = tokenize(sanitised, DEFAULT_TOKENIZE_CONFIG);
   return tokens.sort();
 }
+// src/utils/phoneNormalization.ts
+var RE_ASCII_DIGITS = /^[0-9]+$/;
+var RE_PHONE_LIKE_QUERY = /^[\d+()/\-. ]+$/;
+var MIN_PHONE_DIGITS = 4;
+var defaultPhoneNormalizer = (value) => {
+  const digits = value.replace(/\D/g, "");
+  return digits.length >= MIN_PHONE_DIGITS ? digits : undefined;
+};
+var defaultQueryPhoneNormalizer = (query) => {
+  if (!RE_PHONE_LIKE_QUERY.test(query))
+    return;
+  return defaultPhoneNormalizer(query);
+};
+function validateNormalizedPhone(normalized, normalizerName) {
+  if (normalized === undefined)
+    return;
+  if (typeof normalized !== "string" || !RE_ASCII_DIGITS.test(normalized)) {
+    throw new Error(`${normalizerName} must return an ASCII digit string or undefined`);
+  }
+  return normalized;
+}
+function resolvePhoneQueryNormalizer(spec) {
+  if (spec?.phoneQueryNormalizer)
+    return spec.phoneQueryNormalizer;
+  const phoneNormalizer = spec?.phoneNormalizer ?? defaultPhoneNormalizer;
+  return (query) => {
+    if (!RE_PHONE_LIKE_QUERY.test(query))
+      return;
+    return phoneNormalizer(query);
+  };
+}
 // src/utils/tokenRegistry.ts
 var INITIAL_CAPACITY = 10 * 1000;
 var tokens = new Array(INITIAL_CAPACITY);
@@ -388,7 +420,7 @@ function prepareObjectForSearchNumeric(obj, spec, tokensMap) {
   const sorted = spec?.extractSearchableStringFn ? buildSortedFromExtractFn(obj, spec.extractSearchableStringFn, tokensMap) : buildSortedFromFields(obj, spec, tokensMap);
   if (sorted === undefined)
     return;
-  const firstN = spec?.keyFields && spec.keyFields.length > 0 ? buildFirstNFromKeyFields(obj, spec.keyFields, spec.firstTokensN ?? DEFAULT_FIRST_TOKENS_N, tokensMap) : undefined;
+  const firstN = spec?.keyFields && spec.keyFields.length > 0 ? buildFirstNFromKeyFields(obj, spec.keyFields, spec.firstTokensN ?? DEFAULT_FIRST_TOKENS_N, spec.phoneFields ?? DEFAULT_PHONE_FIELDS, tokensMap) : undefined;
   return { sorted, firstN };
 }
 function buildSortedFromExtractFn(obj, extractFn, tokensMap) {
@@ -401,7 +433,9 @@ function buildSortedFromFields(obj, spec, tokensMap) {
   const allTokens = [];
   const fieldMatchModes = spec?.fieldMatchModes;
   const fieldsToSearch = spec?.searchInFields ?? Object.keys(obj);
-  const fieldsToExclude = new Set(spec?.dontSearchInFields ?? []);
+  const fieldsToExclude = new Set((spec?.dontSearchInFields ?? []).map(String));
+  const phoneFields = new Set(spec?.phoneFields ?? DEFAULT_PHONE_FIELDS);
+  const phoneNormalizer = spec?.phoneNormalizer ?? defaultPhoneNormalizer;
   for (const key of fieldsToSearch) {
     const keyStr = key;
     if (!spec?.searchInFields && DEFAULT_EXCLUDED_FIELDS.has(keyStr))
@@ -409,36 +443,50 @@ function buildSortedFromFields(obj, spec, tokensMap) {
     if (fieldsToExclude.has(key))
       continue;
     const isDot = isDotNotation(keyStr);
-    const value = isDot ? getValueByPath(obj, keyStr) : obj[key];
+    const value = isDot ? getValueByPath(obj, keyStr) : obj[keyStr];
     if (value == null)
       continue;
     const matchMode = fieldMatchModes?.[key];
     const fieldStrings = [];
     extractStringsFromValue(value, fieldStrings);
-    if (fieldStrings.length > 0) {
-      const fieldText = fieldStrings.join(" ");
-      const datesNormalized = normalizeDates(fieldText);
-      const preprocessed = preprocessString(datesNormalized);
-      const sanitised = sanitiseString(preprocessed);
-      const stringTokens = tokenize(sanitised, DEFAULT_TOKENIZE_CONFIG);
-      const effectiveMode = matchMode ?? (keyStr === "_id" ? "whole" : undefined);
-      for (const token of stringTokens) {
-        const tokenId = getOrCreateTokenId(token, tokensMap);
-        if (effectiveMode) {
-          allTokens.push(encodeTokenWithMode(tokenId, effectiveMode));
-        } else {
-          allTokens.push(tokenId);
-        }
+    if (phoneFields.has(keyStr)) {
+      const phoneMatchMode = spec?.phoneMatchMode ?? "anywhere";
+      for (const fieldString of fieldStrings) {
+        const normalized = validateNormalizedPhone(phoneNormalizer(fieldString), `Phone normalizer for field "${keyStr}"`);
+        if (normalized === undefined)
+          continue;
+        const tokenId = getOrCreateTokenId(normalized, tokensMap);
+        allTokens.push(encodeTokenWithMode(tokenId, phoneMatchMode));
+      }
+      continue;
+    }
+    if (fieldStrings.length === 0)
+      continue;
+    const fieldText = fieldStrings.join(" ");
+    const datesNormalized = normalizeDates(fieldText);
+    const preprocessed = preprocessString(datesNormalized);
+    const sanitised = sanitiseString(preprocessed);
+    const stringTokens = tokenize(sanitised, DEFAULT_TOKENIZE_CONFIG);
+    const effectiveMode = matchMode ?? (keyStr === "_id" ? "whole" : undefined);
+    for (const token of stringTokens) {
+      const tokenId = getOrCreateTokenId(token, tokensMap);
+      if (effectiveMode) {
+        allTokens.push(encodeTokenWithMode(tokenId, effectiveMode));
+      } else {
+        allTokens.push(tokenId);
       }
     }
   }
   const uniqueTokens = [...new Set(allTokens)].sort((a, b) => a - b);
   return new Uint32Array(uniqueTokens);
 }
-function buildFirstNFromKeyFields(obj, keyFields, n, tokensMap) {
+function buildFirstNFromKeyFields(obj, keyFields, n, phoneFields, tokensMap) {
   const strings = [];
+  const phoneFieldPaths = new Set(phoneFields);
   for (const field of keyFields) {
     const keyStr = field;
+    if (phoneFieldPaths.has(keyStr))
+      continue;
     const value = isDotNotation(keyStr) ? getValueByPath(obj, keyStr) : obj[field];
     if (value == null)
       continue;
@@ -741,6 +789,23 @@ function allTokensMatchNumeric(searchTokenStrs, targetTokens, opts) {
   return allPreparedTokensMatch(preparedTokens, targetTokens, opts);
 }
 
+// src/common/numeric/prepareQueryVariants.ts
+function prepareQueryVariants(query, opts) {
+  const rawTokenStrs = prepareStringForSearch(query);
+  const rawTokens = prepareQueryTokens(rawTokenStrs);
+  const normalizers = opts?.phoneQueryNormalizers ?? [defaultQueryPhoneNormalizer];
+  const seenPhones = new Set;
+  const phoneTokens = [];
+  for (const normalizer of normalizers) {
+    const normalized = validateNormalizedPhone(normalizer(query), "Phone query normalizer");
+    if (normalized === undefined || seenPhones.has(normalized))
+      continue;
+    seenPhones.add(normalized);
+    phoneTokens.push(prepareQueryTokens([normalized]));
+  }
+  return { rawTokenStrs, rawTokens, phoneTokens };
+}
+
 // src/common/numeric/scoring.ts
 function orderedTokenize(input) {
   return tokenize(sanitiseString(preprocessString(normalizeDates(input))), DEFAULT_TOKENIZE_CONFIG);
@@ -857,16 +922,9 @@ function searchInDataReturnObjectsNumeric(query, metadata, data, opts) {
   return results;
 }
 function searchInDataReturnIdsWithLimitNumeric(query, metadata, limit, opts) {
-  const queryTokenStrs = prepareStringForSearch(query);
-  if (queryTokenStrs.length === 0)
-    return [];
-  const preparedTokens = prepareQueryTokens(queryTokenStrs);
-  const candidates = [];
-  for (const [id, targetTokens] of metadata.sorted) {
-    if (allPreparedTokensMatch(preparedTokens, targetTokens, opts)) {
-      candidates.push(id);
-    }
-  }
+  const { rawTokenStrs, rawTokens, phoneTokens } = prepareQueryVariants(query, opts);
+  const phoneCandidates = findMatchingCandidates(metadata, phoneTokens, opts);
+  const candidates = phoneCandidates.length > 0 ? phoneCandidates : findMatchingCandidates(metadata, rawTokens.length > 0 ? [rawTokens] : [], opts);
   if (candidates.length === 0)
     return [];
   const qTokens = orderedTokenize(query);
@@ -901,13 +959,22 @@ function searchInDataReturnIdsWithLimitNumeric(query, metadata, limit, opts) {
     out.push(scored[i].id);
   return out;
 }
-// src/common/numeric/findInLinkedArrays.ts
-function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
-  const queryTokenStrs = prepareStringForSearch(query);
-  if (queryTokenStrs.length === 0) {
-    return { queryTokens: queryTokenStrs, results: [], hasNegation: false };
+function findMatchingCandidates(metadata, variants, opts) {
+  if (variants.length === 0)
+    return [];
+  const candidates = [];
+  for (const [id, targetTokens] of metadata.sorted) {
+    for (const preparedTokens of variants) {
+      if (allPreparedTokensMatch(preparedTokens, targetTokens, opts)) {
+        candidates.push(id);
+        break;
+      }
+    }
   }
-  const preparedTokens = prepareQueryTokens(queryTokenStrs);
+  return candidates;
+}
+// src/common/numeric/findInLinkedArrays.ts
+function findInLinkedArraysForPreparedTokens(query, queryTokenStrs, preparedTokens, linked, limit, opts) {
   const positiveTokens = preparedTokens.filter((t) => !t.negated);
   const negatedTokens = preparedTokens.filter((t) => t.negated);
   const scored = [];
@@ -926,6 +993,30 @@ function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
     }
     if (negatedMatchesInPrimary)
       continue;
+    let allPositiveMatchInPrimary = true;
+    for (const token of positiveTokens) {
+      if (!matchPreparedTokenInSortedList(token, primaryTokens, opts)) {
+        allPositiveMatchInPrimary = false;
+        break;
+      }
+    }
+    if (allPositiveMatchInPrimary && negatedTokens.length === 0) {
+      const matchedLinked2 = linkedIds.map((id) => linked.linkedData.get(id)).filter((item) => item !== undefined);
+      scored.push({
+        result: {
+          primary,
+          linked: matchedLinked2,
+          matchedIn: "primary"
+        },
+        score: 0,
+        order: orderCounter++,
+        primaryId,
+        matchedLinkedIds: matchedLinked2.map((l) => l._id)
+      });
+      continue;
+    }
+    if (!allPositiveMatchInPrimary && linkedIds.length === 0)
+      continue;
     let totalLength = primaryTokens.length;
     for (const linkedId of linkedIds) {
       const linkedTokens = linked.linkedMeta.sorted.get(linkedId);
@@ -944,24 +1035,31 @@ function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
       }
     }
     allTokens.sort();
-    let allPositiveMatch = true;
-    for (const token of positiveTokens) {
-      if (!matchPreparedTokenInSortedList(token, allTokens, opts)) {
-        allPositiveMatch = false;
-        break;
+    if (!allPositiveMatchInPrimary) {
+      let allPositiveMatch = true;
+      for (const token of positiveTokens) {
+        if (!matchPreparedTokenInSortedList(token, allTokens, opts)) {
+          allPositiveMatch = false;
+          break;
+        }
       }
+      if (!allPositiveMatch)
+        continue;
     }
-    if (!allPositiveMatch)
-      continue;
-    let anyMatchInPrimary = false;
+    let anyMatchInPrimary = allPositiveMatchInPrimary;
     let anyMatchInLinked = false;
     const matchingLinkedIds = new Set;
     const tokensMatchingPrimary = new Set;
-    for (const preparedToken of positiveTokens) {
-      if (matchPreparedTokenInSortedList(preparedToken, primaryTokens, opts)) {
-        anyMatchInPrimary = true;
-        tokensMatchingPrimary.add(preparedToken);
+    if (!allPositiveMatchInPrimary) {
+      for (const preparedToken of positiveTokens) {
+        if (matchPreparedTokenInSortedList(preparedToken, primaryTokens, opts)) {
+          anyMatchInPrimary = true;
+          tokensMatchingPrimary.add(preparedToken);
+        }
       }
+    } else {
+      for (const t of positiveTokens)
+        tokensMatchingPrimary.add(t);
     }
     const tokensForLinkedMatching = positiveTokens.filter((t) => !tokensMatchingPrimary.has(t));
     if (tokensForLinkedMatching.length > 0 || negatedTokens.length > 0) {
@@ -1046,6 +1144,46 @@ function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
     results[i] = scored[i].result;
   return { queryTokens: queryTokenStrs, results, hasNegation: negatedTokens.length > 0 };
 }
+function findInLinkedArraysNumeric(query, linked, limit = 10, opts) {
+  const { rawTokenStrs, rawTokens, phoneTokens } = prepareQueryVariants(query, opts);
+  const phoneResults = [];
+  for (const preparedTokens of phoneTokens) {
+    const result = findInLinkedArraysForPreparedTokens(query, rawTokenStrs, preparedTokens, linked, Infinity, opts);
+    phoneResults.push(...result.results);
+  }
+  if (phoneResults.length > 0) {
+    return {
+      queryTokens: rawTokenStrs,
+      results: mergePhoneResults(phoneResults).slice(0, limit),
+      hasNegation: false
+    };
+  }
+  if (rawTokens.length === 0) {
+    return { queryTokens: rawTokenStrs, results: [], hasNegation: false };
+  }
+  return findInLinkedArraysForPreparedTokens(query, rawTokenStrs, rawTokens, linked, limit, opts);
+}
+function mergePhoneResults(results) {
+  const byPrimaryId = new Map;
+  for (const result of results) {
+    const existing = byPrimaryId.get(result.primary._id);
+    if (existing === undefined) {
+      byPrimaryId.set(result.primary._id, result);
+      continue;
+    }
+    const linkedById = new Map(existing.linked.map((item) => [item._id, item]));
+    for (const item of result.linked)
+      linkedById.set(item._id, item);
+    existing.linked = Array.from(linkedById.values());
+    existing.matchedIn = mergeMatchLocation(existing.matchedIn, result.matchedIn);
+  }
+  return Array.from(byPrimaryId.values());
+}
+function mergeMatchLocation(first, second) {
+  if (first === "both" || second === "both" || first !== second)
+    return "both";
+  return first;
+}
 function findInLinkedArraysSimpleNumeric(query, linked, limit = 10, opts) {
   return findInLinkedArraysNumeric(query, linked, limit, opts).results;
 }
@@ -1559,6 +1697,15 @@ function firstNEqual3(a, b) {
     return false;
   return tokensEqual3(a, b);
 }
+function withCollectionPhoneNormalizers(opts, specs) {
+  return {
+    ...opts,
+    phoneQueryNormalizers: [
+      ...specs.map((spec) => resolvePhoneQueryNormalizer(spec)),
+      ...opts.phoneQueryNormalizers ?? []
+    ]
+  };
+}
 
 class SearchUniverse {
   collections = new Map;
@@ -1919,7 +2066,11 @@ class SearchUniverse {
           primaryData: primaryCollection.data,
           linkedData: collection.data
         };
-        const linkedSearchResults = findInLinkedArraysNumeric(query, linkedMetadata, limit, searchOpts);
+        const linkedSearchOpts = withCollectionPhoneNormalizers(searchOpts, [
+          primaryCollection.config.spec,
+          collection.config.spec
+        ]);
+        const linkedSearchResults = findInLinkedArraysNumeric(query, linkedMetadata, limit, linkedSearchOpts);
         if (linkedSearchResults.results.length > 0) {
           const combinedResults = [];
           const hasNegation = linkedSearchResults.hasNegation;
@@ -1942,7 +2093,7 @@ class SearchUniverse {
         if (inCollections && !inCollections.includes(name)) {
           continue;
         }
-        const matchingIds = searchInDataReturnIdsWithLimitNumeric(query, collection.metadata, limit, searchOpts);
+        const matchingIds = searchInDataReturnIdsWithLimitNumeric(query, collection.metadata, limit, withCollectionPhoneNormalizers(searchOpts, [collection.config.spec]));
         if (matchingIds.length > 0) {
           const collectionResults = [];
           for (const id of matchingIds) {
@@ -1990,6 +2141,7 @@ export {
   scoreOne,
   scoreBag,
   sanitiseString,
+  resolvePhoneQueryNormalizer,
   resetTokenRegistry,
   removePrimaryItemNumeric as removePrimaryItem,
   removeLinkedItemNumeric as removeLinkedItem,
@@ -2012,6 +2164,8 @@ export {
   findInLinkedArraysSimpleNumeric,
   findInLinkedArraysNumeric,
   encodeTokenWithMode,
+  defaultQueryPhoneNormalizer,
+  defaultPhoneNormalizer,
   decodeTokenId,
   decodeMatchMode,
   createTokensMap,
@@ -2028,5 +2182,6 @@ export {
   MATCH_MODE_PREFIXES,
   MATCH_MODE_BITS,
   DEFAULT_SEARCH_OPTS,
+  DEFAULT_PHONE_FIELDS,
   AugmentedMetadata
 };

package/dist/types/index.d.ts

@@ -45,12 +45,18 @@ export interface SearchableObject {
  * - 'whole': exact match only - "rex" matches "rex" but not "rexona" or "ceporex"
  */
 export type MatchMode = 'start' | 'end' | 'startEnd' | 'anywhere' | 'whole';
+/** Default root field names treated as phone numbers during metadata construction. */
+export declare const DEFAULT_PHONE_FIELDS: readonly ["telefon", "phone", "gsm", "msisdn"];
+/** Converts a stored phone value to canonical ASCII digits. */
+export type PhoneNormalizer = (value: string) => string | undefined;
+/** Recognizes a complete phone query and returns canonical ASCII digits. */
+export type PhoneQueryNormalizer = (query: string) => string | undefined;
 /**
  * Specification for how to extract searchable text from objects
  */
 export interface SearchableObjectSpec<T extends SearchableObject, C = unknown> {
     /** Fields to include in search (if not specified, all string fields are used) */
-    searchInFields?: (keyof T)[];
+    searchInFields?: readonly string[];
     /** Fields to exclude from search */
     dontSearchInFields?: (keyof T)[];
     /** Optional context passed to enrichSearchObjectFn */
@@ -65,6 +71,17 @@ export interface SearchableObjectSpec<T extends SearchableObject, C = unknown> {
      * Prefixes: < (start), > (end), + (startEnd), * (anywhere), ! (whole)
      */
     fieldMatchModes?: Partial<Record<keyof T, MatchMode>>;
+    /**
+     * Exact field paths whose values are normalized as phone numbers.
+     * @default DEFAULT_PHONE_FIELDS
+     */
+    phoneFields?: readonly string[];
+    /** Build normalizer for phone field values. @default defaultPhoneNormalizer */
+    phoneNormalizer?: PhoneNormalizer;
+    /** Query recognizer used by SearchUniverse for this collection. */
+    phoneQueryNormalizer?: PhoneQueryNormalizer;
+    /** Match mode for canonical phone tokens. @default 'anywhere' */
+    phoneMatchMode?: MatchMode;
     /**
      * Fields whose tokens are also stored in `metadata.unsorted` in SOURCE order
      * (no sort, no de-dup) for positional ranking. Fields are concatenated in
@@ -73,7 +90,7 @@ export interface SearchableObjectSpec<T extends SearchableObject, C = unknown> {
      * If omitted, `metadata.unsorted` has no entry for this item, and
      * positional ranking falls back to re-tokenizing primary text at query time.
      */
-    keyFields?: (keyof T | string)[];
+    keyFields?: readonly string[];
     /**
      * Max number of tokens stored in `metadata.unsorted` per item.
      * Applied AFTER tokenization of concatenated `keyFields` content.
@@ -112,9 +129,14 @@ export interface SearchOpts {
      * @default 6
      */
     matchNumbersThreshold?: number;
+    /**
+     * Phone query recognizers evaluated before the ordinary tokenized query.
+     * When a phone variant finds candidates, it takes precedence over raw tokens.
+     */
+    phoneQueryNormalizers?: readonly PhoneQueryNormalizer[];
 }
-/** Default search options */
-export declare const DEFAULT_SEARCH_OPTS: Required<SearchOpts>;
+/** Default match-mode options. Phone query normalizers are resolved per search. */
+export declare const DEFAULT_SEARCH_OPTS: Required<Pick<SearchOpts, 'matchWords' | 'matchNumbers' | 'matchNumbersShort' | 'matchNumbersThreshold'>>;
 /**
  * Specification for linked search across two related arrays
  */

package/dist/types/index.d.ts.map

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

package/dist/utils/phoneNormalization.d.ts

@@ -0,0 +1,26 @@
+import type { PhoneNormalizer, PhoneQueryNormalizer, SearchableObject, SearchableObjectSpec } from '../types';
+/**
+ * Converts a stored phone value to its canonical ASCII digit representation.
+ *
+ * @feature [phone-search]
+ */
+export declare const defaultPhoneNormalizer: PhoneNormalizer;
+/**
+ * Recognizes a complete phone query before applying default canonicalization.
+ *
+ * @feature [phone-search]
+ */
+export declare const defaultQueryPhoneNormalizer: PhoneQueryNormalizer;
+/**
+ * Verifies that a custom normalizer returned the canonical phone representation.
+ *
+ * @feature [phone-search]
+ */
+export declare function validateNormalizedPhone(normalized: string | undefined, normalizerName: string): string | undefined;
+/**
+ * Resolves the query normalizer that converges with a collection's build normalizer.
+ *
+ * @feature [phone-search]
+ */
+export declare function resolvePhoneQueryNormalizer<T extends SearchableObject>(spec?: SearchableObjectSpec<T>): PhoneQueryNormalizer;
+//# sourceMappingURL=phoneNormalization.d.ts.map

package/dist/utils/phoneNormalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoneNormalization.d.ts","sourceRoot":"","sources":["../../src/utils/phoneNormalization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAMlB;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAGpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,oBAGzC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,cAAc,EAAE,MAAM,GACrB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,gBAAgB,EACpE,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC7B,oBAAoB,CAQtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-search",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",