@objectstack/plugin-pinyin-search 15.1.0

package/dist/index.js

@@ -0,0 +1,233 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PINYIN_SEARCH_HOOK_PACKAGE: () => PINYIN_SEARCH_HOOK_PACKAGE,
+  PinyinSearchPlugin: () => PinyinSearchPlugin,
+  backfillSearchCompanion: () => backfillSearchCompanion,
+  bindSearchCompanionHooks: () => bindSearchCompanionHooks,
+  computeSearchCompanionValue: () => computeSearchCompanionValue,
+  rebuildSearchCompanion: () => rebuildSearchCompanion
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/pinyin-search-plugin.ts
+var import_types = require("@objectstack/types");
+
+// src/companion-projection.ts
+var import_objectql2 = require("@objectstack/objectql");
+
+// src/pinyin.ts
+var import_objectql = require("@objectstack/objectql");
+var _pinyin = null;
+function loadPinyin() {
+  _pinyin ?? (_pinyin = import("pinyin-pro").then((m) => m.pinyin ?? m.default?.pinyin));
+  return _pinyin;
+}
+function squash(syllables) {
+  const joined = Array.isArray(syllables) ? syllables.join("") : String(syllables ?? "");
+  return joined.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+async function computeSearchCompanionValue(values) {
+  const cjkValues = values.filter((v) => (0, import_objectql.containsCJK)(v));
+  if (cjkValues.length === 0) return null;
+  const pinyin = await loadPinyin();
+  const parts = [];
+  for (const value of cjkValues) {
+    const full = squash(pinyin(value, { toneType: "none", type: "array", nonZh: "consecutive" }));
+    const initials = squash(pinyin(value, { pattern: "first", toneType: "none", type: "array", nonZh: "consecutive" }));
+    if (full) parts.push(full);
+    if (initials && initials !== full) parts.push(initials);
+  }
+  if (parts.length === 0) return null;
+  return [...new Set(parts)].join(" ");
+}
+
+// src/companion-projection.ts
+var SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] };
+var PINYIN_SEARCH_HOOK_PACKAGE = "plugin-pinyin-search:companion";
+async function stampCompanion(engine, ctx, logger) {
+  const object = ctx?.object;
+  if (!object) return;
+  const schema = engine.registry?.getObject?.(object);
+  if (!schema?.fields?.[import_objectql2.SEARCH_COMPANION_FIELD]) return;
+  const data = ctx?.input?.data;
+  if (!data || typeof data !== "object" || Array.isArray(data)) return;
+  const sources = (0, import_objectql2.resolveSearchCompanionSources)(schema);
+  if (sources.length === 0) return;
+  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));
+  if (touched.length === 0) return;
+  try {
+    data[import_objectql2.SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));
+  } catch (err) {
+    logger?.warn?.("[pinyin-search] companion normalization failed \u2014 write proceeds without it", {
+      object,
+      error: err?.message
+    });
+  }
+}
+function bindSearchCompanionHooks(engine, logger) {
+  if (typeof engine.registerHook !== "function") return;
+  if (typeof engine.unregisterHooksByPackage === "function") {
+    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);
+  }
+  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };
+  const handler = (ctx) => stampCompanion(engine, ctx, logger);
+  engine.registerHook("beforeInsert", handler, opts);
+  engine.registerHook("beforeUpdate", handler, opts);
+  logger?.info?.("[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)");
+}
+async function backfillSearchCompanion(engine, logger, options) {
+  const batchSize = Math.max(1, options?.batchSize ?? 1e3);
+  const all = options?.object ? [engine.registry?.getObject?.(options.object)].filter(Boolean) : engine.registry?.getAllObjects?.() ?? [];
+  const result = { objects: 0, scanned: 0, updated: 0 };
+  for (const schema of all) {
+    if (!schema?.name || !schema?.fields?.[import_objectql2.SEARCH_COMPANION_FIELD]) continue;
+    const sources = (0, import_objectql2.resolveSearchCompanionSources)(schema);
+    if (sources.length === 0) continue;
+    result.objects++;
+    let offset = 0;
+    for (; ; ) {
+      let rows = [];
+      try {
+        rows = await engine.find(schema.name, {
+          fields: ["id", ...sources, import_objectql2.SEARCH_COMPANION_FIELD],
+          limit: batchSize,
+          offset,
+          context: SYSTEM_CTX
+        });
+      } catch (err) {
+        logger?.warn?.("[pinyin-search] backfill scan failed", { object: schema.name, error: err?.message });
+        break;
+      }
+      if (!rows?.length) break;
+      result.scanned += rows.length;
+      for (const row of rows) {
+        if (row?.id == null) continue;
+        const hasBlob = typeof row[import_objectql2.SEARCH_COMPANION_FIELD] === "string" && row[import_objectql2.SEARCH_COMPANION_FIELD] !== "";
+        const hasCjkSource = sources.some((s) => (0, import_objectql2.containsCJK)(row[s]));
+        if (!options?.force && (hasBlob || !hasCjkSource)) continue;
+        try {
+          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));
+          if (!options?.force && value == null) continue;
+          if (value === row[import_objectql2.SEARCH_COMPANION_FIELD]) continue;
+          await engine.update(
+            schema.name,
+            { id: row.id, [import_objectql2.SEARCH_COMPANION_FIELD]: value },
+            { context: SYSTEM_CTX }
+          );
+          result.updated++;
+        } catch (err) {
+          logger?.warn?.("[pinyin-search] backfill row skipped", {
+            object: schema.name,
+            id: row.id,
+            error: err?.message
+          });
+        }
+      }
+      if (rows.length < batchSize) break;
+      offset += batchSize;
+    }
+  }
+  if (result.updated > 0) {
+    logger?.info?.("[pinyin-search] companion backfill complete", result);
+  }
+  return result;
+}
+function rebuildSearchCompanion(engine, logger, options) {
+  return backfillSearchCompanion(engine, logger, { ...options, force: true });
+}
+
+// src/pinyin-search-plugin.ts
+var PinyinSearchPlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.plugin.pinyin-search";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.engine.objectql"];
+    this.options = options;
+  }
+  get enabled() {
+    return this.options.enabled ?? (0, import_types.resolveSearchPinyinEnabled)();
+  }
+  async init(_ctx) {
+  }
+  async start(ctx) {
+    if (!this.enabled) {
+      ctx.logger.debug?.("PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off \u2014 inert");
+      return;
+    }
+    ctx.hook("kernel:ready", async () => {
+      const engine = this.resolveEngine(ctx);
+      if (!engine) {
+        ctx.logger.warn("PinyinSearchPlugin: no ObjectQL engine \u2014 companion hooks NOT bound");
+        return;
+      }
+      try {
+        bindSearchCompanionHooks(engine, ctx.logger);
+      } catch (err) {
+        ctx.logger.warn("PinyinSearchPlugin: companion hooks not bound", { error: err?.message });
+      }
+    });
+    if (this.options.backfill !== false) {
+      ctx.hook("kernel:bootstrapped", async () => {
+        const engine = this.resolveEngine(ctx);
+        if (!engine) return;
+        try {
+          await backfillSearchCompanion(engine, ctx.logger);
+        } catch (err) {
+          ctx.logger.warn("PinyinSearchPlugin: companion backfill failed", { error: err?.message });
+        }
+      });
+    }
+  }
+  resolveEngine(ctx) {
+    try {
+      return ctx.getService("objectql");
+    } catch {
+      try {
+        return ctx.getService("data");
+      } catch {
+        return null;
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PINYIN_SEARCH_HOOK_PACKAGE,
+  PinyinSearchPlugin,
+  backfillSearchCompanion,
+  bindSearchCompanionHooks,
+  computeSearchCompanionValue,
+  rebuildSearchCompanion
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/pinyin-search-plugin.ts","../src/companion-projection.ts","../src/pinyin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { PinyinSearchPlugin } from './pinyin-search-plugin.js';\nexport type { PinyinSearchPluginOptions } from './pinyin-search-plugin.js';\nexport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n  rebuildSearchCompanion,\n  PINYIN_SEARCH_HOOK_PACKAGE,\n} from './companion-projection.js';\nexport type {\n  CompanionBackfillOptions,\n  CompanionBackfillResult,\n} from './companion-projection.js';\nexport { computeSearchCompanionValue } from './pinyin.js';\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.\n *\n * Pure hook plugin: the `__search` companion column is declared at object\n * compile time by the SchemaRegistry (gated on the SAME\n * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the\n * `$search` filter, and this plugin fills the value:\n *\n *   - before-save hooks: recompute full pinyin + initials of the\n *     display/name field when it changes;\n *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the\n *     switch or arrived via hook-bypassing writes;\n *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.\n *\n * When the flag is off the plugin is inert: no hooks, no backfill, and\n * `pinyin-pro` is never imported.\n */\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { resolveSearchPinyinEnabled } from '@objectstack/types';\nimport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n} from './companion-projection.js';\n\nexport interface PinyinSearchPluginOptions {\n  /**\n   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /\n   * embedders). Default: `resolveSearchPinyinEnabled()`.\n   */\n  enabled?: boolean;\n  /** Skip the boot backfill (default: run it once per boot). */\n  backfill?: boolean;\n}\n\nexport class PinyinSearchPlugin implements Plugin {\n  name = 'com.objectstack.plugin.pinyin-search';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: PinyinSearchPluginOptions;\n\n  constructor(options: PinyinSearchPluginOptions = {}) {\n    this.options = options;\n  }\n\n  private get enabled(): boolean {\n    return this.options.enabled ?? resolveSearchPinyinEnabled();\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // Nothing to register: the companion column is provisioned by the\n    // SchemaRegistry's compile-time seam, not injected at runtime.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (!this.enabled) {\n      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');\n      return;\n    }\n\n    ctx.hook('kernel:ready', async () => {\n      const engine = this.resolveEngine(ctx);\n      if (!engine) {\n        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');\n        return;\n      }\n      try {\n        bindSearchCompanionHooks(engine, ctx.logger as any);\n      } catch (err: any) {\n        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });\n      }\n    });\n\n    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every\n    // `kernel:ready` hook — including seed loading — has completed), so\n    // seeded rows written before/around hook binding are reconciled too.\n    if (this.options.backfill !== false) {\n      ctx.hook('kernel:bootstrapped', async () => {\n        const engine = this.resolveEngine(ctx);\n        if (!engine) return;\n        try {\n          await backfillSearchCompanion(engine, ctx.logger as any);\n        } catch (err: any) {\n          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });\n        }\n      });\n    }\n  }\n\n  private resolveEngine(ctx: PluginContext): any {\n    try {\n      return ctx.getService<any>('objectql');\n    } catch {\n      try {\n        return ctx.getService<any>('data');\n      } catch {\n        return null;\n      }\n    }\n  }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `__search` companion-column projection (#2486).\n *\n * The column itself is DECLARED at object compile time by the SchemaRegistry\n * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this\n * module only FILLS the value — the `plugin-sharing` primary-BU projection\n * pattern (column on the object, plugin maintains it via hooks).\n *\n * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp\n * `data.__search` whenever a companion source field (the object's\n * display/name field) is present in the write — i.e. only when the source\n * actually changed, avoiding write amplification. Writes that bypass hooks\n * (bulk import, direct migration) leave the companion empty; the boot\n * backfill and the `rebuildSearchCompanion` reconcile entry cover that.\n */\n\nimport {\n  SEARCH_COMPANION_FIELD,\n  resolveSearchCompanionSources,\n  containsCJK,\n} from '@objectstack/objectql';\nimport { computeSearchCompanionValue } from './pinyin.js';\n\nconst SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;\n\nexport const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';\n\ninterface MinimalEngine {\n  registerHook(\n    event: string,\n    handler: (ctx: any) => any | Promise<any>,\n    options?: { object?: string | string[]; priority?: number; packageId?: string },\n  ): void;\n  unregisterHooksByPackage(packageId: string): number;\n  find(object: string, query?: any, options?: any): Promise<any[]>;\n  update(object: string, data: any, options?: any): Promise<any>;\n  registry?: {\n    getObject(name: string): any;\n    getAllObjects?(packageId?: string): any[];\n  };\n}\n\ninterface MinimalLogger {\n  info?: (msg: any, ...rest: any[]) => void;\n  warn?: (msg: any, ...rest: any[]) => void;\n  debug?: (msg: any, ...rest: any[]) => void;\n}\n\n/**\n * Stamp `data.__search` on a before-save hook context when a companion source\n * field is part of the write. Recomputes from the NEW value; a non-CJK new\n * value clears the companion (null) so stale pinyin never recalls a renamed\n * record. Never throws — a normalization failure must not fail the write.\n */\nasync function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {\n  const object = ctx?.object;\n  if (!object) return;\n  const schema = engine.registry?.getObject?.(object);\n  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;\n\n  const data = ctx?.input?.data;\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return;\n\n  const sources = resolveSearchCompanionSources(schema);\n  if (sources.length === 0) return;\n  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));\n  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)\n\n  try {\n    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));\n  } catch (err: any) {\n    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {\n      object,\n      error: err?.message,\n    });\n  }\n}\n\n/**\n * Bind the global before-save hooks that keep `__search` in step. Idempotent\n * (unbinds the package first). Hooks are global (no object filter) with a\n * cheap early-out: objects without a provisioned companion column return\n * immediately. They run for system-context writes too — the projection must\n * stay correct regardless of who writes (seeds, imports, admin UI).\n */\nexport function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {\n  if (typeof engine.registerHook !== 'function') return;\n  if (typeof engine.unregisterHooksByPackage === 'function') {\n    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);\n  }\n  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };\n  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);\n  engine.registerHook('beforeInsert', handler, opts);\n  engine.registerHook('beforeUpdate', handler, opts);\n  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');\n}\n\nexport interface CompanionBackfillOptions {\n  /** Rows fetched per page during the scan. Default 1000. */\n  batchSize?: number;\n  /** Restrict to one object (reconcile entry); default: every provisioned object. */\n  object?: string;\n  /**\n   * Recompute EVERY row's companion, not just missing ones — the periodic\n   * reconcile/rebuild mode. Default false (backfill: only rows whose\n   * companion is empty but whose source has CJK content).\n   */\n  force?: boolean;\n}\n\nexport interface CompanionBackfillResult {\n  objects: number;\n  scanned: number;\n  updated: number;\n}\n\n/**\n * Backfill / reconcile the companion column.\n *\n * Denormalized-on-write columns go stale when writes bypass hooks (bulk\n * import, direct migration) and are empty for rows that predate the switch\n * being enabled. This scans every object that carries the companion column\n * (paged, system context) and fills the gaps; with `force: true` it\n * recomputes unconditionally (the periodic reconcile / rebuild entry).\n * Idempotent; per-row failures are skipped so one bad row never aborts the\n * pass.\n */\nexport async function backfillSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: CompanionBackfillOptions,\n): Promise<CompanionBackfillResult> {\n  const batchSize = Math.max(1, options?.batchSize ?? 1000);\n  const all = options?.object\n    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)\n    : engine.registry?.getAllObjects?.() ?? [];\n\n  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };\n\n  for (const schema of all) {\n    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;\n    const sources = resolveSearchCompanionSources(schema);\n    if (sources.length === 0) continue;\n    result.objects++;\n\n    let offset = 0;\n    for (;;) {\n      let rows: any[] = [];\n      try {\n        rows = await engine.find(schema.name, {\n          fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n          limit: batchSize,\n          offset,\n          context: SYSTEM_CTX,\n        });\n      } catch (err: any) {\n        logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n        break;\n      }\n      if (!rows?.length) break;\n      result.scanned += rows.length;\n\n      for (const row of rows) {\n        if (row?.id == null) continue;\n        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';\n        const hasCjkSource = sources.some((s) => containsCJK(row[s]));\n        // Backfill mode: touch only rows missing a blob they should have.\n        // Force mode: recompute everything (also clears stale blobs).\n        if (!options?.force && (hasBlob || !hasCjkSource)) continue;\n        try {\n          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));\n          if (!options?.force && value == null) continue;\n          if (value === row[SEARCH_COMPANION_FIELD]) continue;\n          await engine.update(\n            schema.name,\n            { id: row.id, [SEARCH_COMPANION_FIELD]: value },\n            { context: SYSTEM_CTX },\n          );\n          result.updated++;\n        } catch (err: any) {\n          logger?.warn?.('[pinyin-search] backfill row skipped', {\n            object: schema.name,\n            id: row.id,\n            error: err?.message,\n          });\n        }\n      }\n\n      if (rows.length < batchSize) break;\n      offset += batchSize;\n    }\n  }\n\n  if (result.updated > 0) {\n    logger?.info?.('[pinyin-search] companion backfill complete', result);\n  }\n  return result;\n}\n\n/**\n * Periodic reconcile / rebuild entry: recompute the companion for every row\n * (optionally one object). Alias for `backfillSearchCompanion` with\n * `force: true` — exposed under its own name so operators/jobs have an\n * explicit \"rebuild the pinyin index\" handle.\n */\nexport function rebuildSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: Omit<CompanionBackfillOptions, 'force'>,\n): Promise<CompanionBackfillResult> {\n  return backfillSearchCompanion(engine, logger, { ...options, force: true });\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Pinyin normalization for the `__search` companion column (#2486).\n *\n * One normalized blob per record — full pinyin AND initials in the same\n * column — so a single `$contains` recalls every latin input shape:\n *\n *   \"张伟\"  →  \"zhangwei zw\"\n *     `zhang` / `wei` / `zhangwei`  → substring of the full form\n *     `zw`                          → substring of the initials form\n *\n * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag\n * off → hooks never bound) never import it and pay zero cost.\n *\n * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486\n * \"待定\" — surname polyphone dictionaries are a P2 follow-up).\n */\n\nimport { containsCJK } from '@objectstack/objectql';\n\ntype PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];\n\nlet _pinyin: Promise<PinyinFn> | null = null;\n\n/** Lazy-load `pinyin-pro` (cached module-wide). */\nfunction loadPinyin(): Promise<PinyinFn> {\n  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);\n  return _pinyin;\n}\n\n/** Lowercase and strip everything that is not a latin letter or digit. */\nfunction squash(syllables: string | string[]): string {\n  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');\n  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');\n}\n\n/**\n * Compute the companion value for the given source-field values.\n *\n * Returns the normalized blob (`\"<full-pinyin> <initials>\"`, deduplicated)\n * when at least one value contains CJK characters, else `null` — a `null`\n * companion means \"nothing pinyin-searchable here\" and clears any stale blob\n * when a name is edited away from CJK. Non-CJK values need no companion:\n * their source column already matches latin input directly.\n */\nexport async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {\n  const cjkValues = values.filter((v): v is string => containsCJK(v));\n  if (cjkValues.length === 0) return null;\n\n  const pinyin = await loadPinyin();\n  const parts: string[] = [];\n  for (const value of cjkValues) {\n    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed\n    // values (\"张伟2号\" → \"zhangwei2hao\"), so mixed names stay one token.\n    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    if (full) parts.push(full);\n    if (initials && initials !== full) parts.push(initials);\n  }\n  if (parts.length === 0) return null;\n  return [...new Set(parts)].join(' ');\n}\n"],"mappings":"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","names":["import_objectql"]}

package/dist/index.mjs

@@ -0,0 +1,195 @@
+// src/pinyin-search-plugin.ts
+import { resolveSearchPinyinEnabled } from "@objectstack/types";
+
+// src/companion-projection.ts
+import {
+  SEARCH_COMPANION_FIELD,
+  resolveSearchCompanionSources,
+  containsCJK as containsCJK2
+} from "@objectstack/objectql";
+
+// src/pinyin.ts
+import { containsCJK } from "@objectstack/objectql";
+var _pinyin = null;
+function loadPinyin() {
+  _pinyin ?? (_pinyin = import("pinyin-pro").then((m) => m.pinyin ?? m.default?.pinyin));
+  return _pinyin;
+}
+function squash(syllables) {
+  const joined = Array.isArray(syllables) ? syllables.join("") : String(syllables ?? "");
+  return joined.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+async function computeSearchCompanionValue(values) {
+  const cjkValues = values.filter((v) => containsCJK(v));
+  if (cjkValues.length === 0) return null;
+  const pinyin = await loadPinyin();
+  const parts = [];
+  for (const value of cjkValues) {
+    const full = squash(pinyin(value, { toneType: "none", type: "array", nonZh: "consecutive" }));
+    const initials = squash(pinyin(value, { pattern: "first", toneType: "none", type: "array", nonZh: "consecutive" }));
+    if (full) parts.push(full);
+    if (initials && initials !== full) parts.push(initials);
+  }
+  if (parts.length === 0) return null;
+  return [...new Set(parts)].join(" ");
+}
+
+// src/companion-projection.ts
+var SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] };
+var PINYIN_SEARCH_HOOK_PACKAGE = "plugin-pinyin-search:companion";
+async function stampCompanion(engine, ctx, logger) {
+  const object = ctx?.object;
+  if (!object) return;
+  const schema = engine.registry?.getObject?.(object);
+  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;
+  const data = ctx?.input?.data;
+  if (!data || typeof data !== "object" || Array.isArray(data)) return;
+  const sources = resolveSearchCompanionSources(schema);
+  if (sources.length === 0) return;
+  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));
+  if (touched.length === 0) return;
+  try {
+    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));
+  } catch (err) {
+    logger?.warn?.("[pinyin-search] companion normalization failed \u2014 write proceeds without it", {
+      object,
+      error: err?.message
+    });
+  }
+}
+function bindSearchCompanionHooks(engine, logger) {
+  if (typeof engine.registerHook !== "function") return;
+  if (typeof engine.unregisterHooksByPackage === "function") {
+    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);
+  }
+  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };
+  const handler = (ctx) => stampCompanion(engine, ctx, logger);
+  engine.registerHook("beforeInsert", handler, opts);
+  engine.registerHook("beforeUpdate", handler, opts);
+  logger?.info?.("[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)");
+}
+async function backfillSearchCompanion(engine, logger, options) {
+  const batchSize = Math.max(1, options?.batchSize ?? 1e3);
+  const all = options?.object ? [engine.registry?.getObject?.(options.object)].filter(Boolean) : engine.registry?.getAllObjects?.() ?? [];
+  const result = { objects: 0, scanned: 0, updated: 0 };
+  for (const schema of all) {
+    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;
+    const sources = resolveSearchCompanionSources(schema);
+    if (sources.length === 0) continue;
+    result.objects++;
+    let offset = 0;
+    for (; ; ) {
+      let rows = [];
+      try {
+        rows = await engine.find(schema.name, {
+          fields: ["id", ...sources, SEARCH_COMPANION_FIELD],
+          limit: batchSize,
+          offset,
+          context: SYSTEM_CTX
+        });
+      } catch (err) {
+        logger?.warn?.("[pinyin-search] backfill scan failed", { object: schema.name, error: err?.message });
+        break;
+      }
+      if (!rows?.length) break;
+      result.scanned += rows.length;
+      for (const row of rows) {
+        if (row?.id == null) continue;
+        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === "string" && row[SEARCH_COMPANION_FIELD] !== "";
+        const hasCjkSource = sources.some((s) => containsCJK2(row[s]));
+        if (!options?.force && (hasBlob || !hasCjkSource)) continue;
+        try {
+          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));
+          if (!options?.force && value == null) continue;
+          if (value === row[SEARCH_COMPANION_FIELD]) continue;
+          await engine.update(
+            schema.name,
+            { id: row.id, [SEARCH_COMPANION_FIELD]: value },
+            { context: SYSTEM_CTX }
+          );
+          result.updated++;
+        } catch (err) {
+          logger?.warn?.("[pinyin-search] backfill row skipped", {
+            object: schema.name,
+            id: row.id,
+            error: err?.message
+          });
+        }
+      }
+      if (rows.length < batchSize) break;
+      offset += batchSize;
+    }
+  }
+  if (result.updated > 0) {
+    logger?.info?.("[pinyin-search] companion backfill complete", result);
+  }
+  return result;
+}
+function rebuildSearchCompanion(engine, logger, options) {
+  return backfillSearchCompanion(engine, logger, { ...options, force: true });
+}
+
+// src/pinyin-search-plugin.ts
+var PinyinSearchPlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.plugin.pinyin-search";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.engine.objectql"];
+    this.options = options;
+  }
+  get enabled() {
+    return this.options.enabled ?? resolveSearchPinyinEnabled();
+  }
+  async init(_ctx) {
+  }
+  async start(ctx) {
+    if (!this.enabled) {
+      ctx.logger.debug?.("PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off \u2014 inert");
+      return;
+    }
+    ctx.hook("kernel:ready", async () => {
+      const engine = this.resolveEngine(ctx);
+      if (!engine) {
+        ctx.logger.warn("PinyinSearchPlugin: no ObjectQL engine \u2014 companion hooks NOT bound");
+        return;
+      }
+      try {
+        bindSearchCompanionHooks(engine, ctx.logger);
+      } catch (err) {
+        ctx.logger.warn("PinyinSearchPlugin: companion hooks not bound", { error: err?.message });
+      }
+    });
+    if (this.options.backfill !== false) {
+      ctx.hook("kernel:bootstrapped", async () => {
+        const engine = this.resolveEngine(ctx);
+        if (!engine) return;
+        try {
+          await backfillSearchCompanion(engine, ctx.logger);
+        } catch (err) {
+          ctx.logger.warn("PinyinSearchPlugin: companion backfill failed", { error: err?.message });
+        }
+      });
+    }
+  }
+  resolveEngine(ctx) {
+    try {
+      return ctx.getService("objectql");
+    } catch {
+      try {
+        return ctx.getService("data");
+      } catch {
+        return null;
+      }
+    }
+  }
+};
+export {
+  PINYIN_SEARCH_HOOK_PACKAGE,
+  PinyinSearchPlugin,
+  backfillSearchCompanion,
+  bindSearchCompanionHooks,
+  computeSearchCompanionValue,
+  rebuildSearchCompanion
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pinyin-search-plugin.ts","../src/companion-projection.ts","../src/pinyin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.\n *\n * Pure hook plugin: the `__search` companion column is declared at object\n * compile time by the SchemaRegistry (gated on the SAME\n * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the\n * `$search` filter, and this plugin fills the value:\n *\n *   - before-save hooks: recompute full pinyin + initials of the\n *     display/name field when it changes;\n *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the\n *     switch or arrived via hook-bypassing writes;\n *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.\n *\n * When the flag is off the plugin is inert: no hooks, no backfill, and\n * `pinyin-pro` is never imported.\n */\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { resolveSearchPinyinEnabled } from '@objectstack/types';\nimport {\n  bindSearchCompanionHooks,\n  backfillSearchCompanion,\n} from './companion-projection.js';\n\nexport interface PinyinSearchPluginOptions {\n  /**\n   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /\n   * embedders). Default: `resolveSearchPinyinEnabled()`.\n   */\n  enabled?: boolean;\n  /** Skip the boot backfill (default: run it once per boot). */\n  backfill?: boolean;\n}\n\nexport class PinyinSearchPlugin implements Plugin {\n  name = 'com.objectstack.plugin.pinyin-search';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: PinyinSearchPluginOptions;\n\n  constructor(options: PinyinSearchPluginOptions = {}) {\n    this.options = options;\n  }\n\n  private get enabled(): boolean {\n    return this.options.enabled ?? resolveSearchPinyinEnabled();\n  }\n\n  async init(_ctx: PluginContext): Promise<void> {\n    // Nothing to register: the companion column is provisioned by the\n    // SchemaRegistry's compile-time seam, not injected at runtime.\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (!this.enabled) {\n      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');\n      return;\n    }\n\n    ctx.hook('kernel:ready', async () => {\n      const engine = this.resolveEngine(ctx);\n      if (!engine) {\n        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');\n        return;\n      }\n      try {\n        bindSearchCompanionHooks(engine, ctx.logger as any);\n      } catch (err: any) {\n        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });\n      }\n    });\n\n    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every\n    // `kernel:ready` hook — including seed loading — has completed), so\n    // seeded rows written before/around hook binding are reconciled too.\n    if (this.options.backfill !== false) {\n      ctx.hook('kernel:bootstrapped', async () => {\n        const engine = this.resolveEngine(ctx);\n        if (!engine) return;\n        try {\n          await backfillSearchCompanion(engine, ctx.logger as any);\n        } catch (err: any) {\n          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });\n        }\n      });\n    }\n  }\n\n  private resolveEngine(ctx: PluginContext): any {\n    try {\n      return ctx.getService<any>('objectql');\n    } catch {\n      try {\n        return ctx.getService<any>('data');\n      } catch {\n        return null;\n      }\n    }\n  }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `__search` companion-column projection (#2486).\n *\n * The column itself is DECLARED at object compile time by the SchemaRegistry\n * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this\n * module only FILLS the value — the `plugin-sharing` primary-BU projection\n * pattern (column on the object, plugin maintains it via hooks).\n *\n * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp\n * `data.__search` whenever a companion source field (the object's\n * display/name field) is present in the write — i.e. only when the source\n * actually changed, avoiding write amplification. Writes that bypass hooks\n * (bulk import, direct migration) leave the companion empty; the boot\n * backfill and the `rebuildSearchCompanion` reconcile entry cover that.\n */\n\nimport {\n  SEARCH_COMPANION_FIELD,\n  resolveSearchCompanionSources,\n  containsCJK,\n} from '@objectstack/objectql';\nimport { computeSearchCompanionValue } from './pinyin.js';\n\nconst SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;\n\nexport const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';\n\ninterface MinimalEngine {\n  registerHook(\n    event: string,\n    handler: (ctx: any) => any | Promise<any>,\n    options?: { object?: string | string[]; priority?: number; packageId?: string },\n  ): void;\n  unregisterHooksByPackage(packageId: string): number;\n  find(object: string, query?: any, options?: any): Promise<any[]>;\n  update(object: string, data: any, options?: any): Promise<any>;\n  registry?: {\n    getObject(name: string): any;\n    getAllObjects?(packageId?: string): any[];\n  };\n}\n\ninterface MinimalLogger {\n  info?: (msg: any, ...rest: any[]) => void;\n  warn?: (msg: any, ...rest: any[]) => void;\n  debug?: (msg: any, ...rest: any[]) => void;\n}\n\n/**\n * Stamp `data.__search` on a before-save hook context when a companion source\n * field is part of the write. Recomputes from the NEW value; a non-CJK new\n * value clears the companion (null) so stale pinyin never recalls a renamed\n * record. Never throws — a normalization failure must not fail the write.\n */\nasync function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {\n  const object = ctx?.object;\n  if (!object) return;\n  const schema = engine.registry?.getObject?.(object);\n  if (!schema?.fields?.[SEARCH_COMPANION_FIELD]) return;\n\n  const data = ctx?.input?.data;\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return;\n\n  const sources = resolveSearchCompanionSources(schema);\n  if (sources.length === 0) return;\n  const touched = sources.filter((s) => Object.prototype.hasOwnProperty.call(data, s));\n  if (touched.length === 0) return; // source unchanged → no recompute (no write amplification)\n\n  try {\n    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));\n  } catch (err: any) {\n    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {\n      object,\n      error: err?.message,\n    });\n  }\n}\n\n/**\n * Bind the global before-save hooks that keep `__search` in step. Idempotent\n * (unbinds the package first). Hooks are global (no object filter) with a\n * cheap early-out: objects without a provisioned companion column return\n * immediately. They run for system-context writes too — the projection must\n * stay correct regardless of who writes (seeds, imports, admin UI).\n */\nexport function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {\n  if (typeof engine.registerHook !== 'function') return;\n  if (typeof engine.unregisterHooksByPackage === 'function') {\n    engine.unregisterHooksByPackage(PINYIN_SEARCH_HOOK_PACKAGE);\n  }\n  const opts = { packageId: PINYIN_SEARCH_HOOK_PACKAGE, priority: 150 };\n  const handler = (ctx: any) => stampCompanion(engine, ctx, logger);\n  engine.registerHook('beforeInsert', handler, opts);\n  engine.registerHook('beforeUpdate', handler, opts);\n  logger?.info?.('[pinyin-search] companion hooks bound (beforeInsert/beforeUpdate, all objects)');\n}\n\nexport interface CompanionBackfillOptions {\n  /** Rows fetched per page during the scan. Default 1000. */\n  batchSize?: number;\n  /** Restrict to one object (reconcile entry); default: every provisioned object. */\n  object?: string;\n  /**\n   * Recompute EVERY row's companion, not just missing ones — the periodic\n   * reconcile/rebuild mode. Default false (backfill: only rows whose\n   * companion is empty but whose source has CJK content).\n   */\n  force?: boolean;\n}\n\nexport interface CompanionBackfillResult {\n  objects: number;\n  scanned: number;\n  updated: number;\n}\n\n/**\n * Backfill / reconcile the companion column.\n *\n * Denormalized-on-write columns go stale when writes bypass hooks (bulk\n * import, direct migration) and are empty for rows that predate the switch\n * being enabled. This scans every object that carries the companion column\n * (paged, system context) and fills the gaps; with `force: true` it\n * recomputes unconditionally (the periodic reconcile / rebuild entry).\n * Idempotent; per-row failures are skipped so one bad row never aborts the\n * pass.\n */\nexport async function backfillSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: CompanionBackfillOptions,\n): Promise<CompanionBackfillResult> {\n  const batchSize = Math.max(1, options?.batchSize ?? 1000);\n  const all = options?.object\n    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)\n    : engine.registry?.getAllObjects?.() ?? [];\n\n  const result: CompanionBackfillResult = { objects: 0, scanned: 0, updated: 0 };\n\n  for (const schema of all) {\n    if (!schema?.name || !schema?.fields?.[SEARCH_COMPANION_FIELD]) continue;\n    const sources = resolveSearchCompanionSources(schema);\n    if (sources.length === 0) continue;\n    result.objects++;\n\n    let offset = 0;\n    for (;;) {\n      let rows: any[] = [];\n      try {\n        rows = await engine.find(schema.name, {\n          fields: ['id', ...sources, SEARCH_COMPANION_FIELD],\n          limit: batchSize,\n          offset,\n          context: SYSTEM_CTX,\n        });\n      } catch (err: any) {\n        logger?.warn?.('[pinyin-search] backfill scan failed', { object: schema.name, error: err?.message });\n        break;\n      }\n      if (!rows?.length) break;\n      result.scanned += rows.length;\n\n      for (const row of rows) {\n        if (row?.id == null) continue;\n        const hasBlob = typeof row[SEARCH_COMPANION_FIELD] === 'string' && row[SEARCH_COMPANION_FIELD] !== '';\n        const hasCjkSource = sources.some((s) => containsCJK(row[s]));\n        // Backfill mode: touch only rows missing a blob they should have.\n        // Force mode: recompute everything (also clears stale blobs).\n        if (!options?.force && (hasBlob || !hasCjkSource)) continue;\n        try {\n          const value = await computeSearchCompanionValue(sources.map((s) => row[s]));\n          if (!options?.force && value == null) continue;\n          if (value === row[SEARCH_COMPANION_FIELD]) continue;\n          await engine.update(\n            schema.name,\n            { id: row.id, [SEARCH_COMPANION_FIELD]: value },\n            { context: SYSTEM_CTX },\n          );\n          result.updated++;\n        } catch (err: any) {\n          logger?.warn?.('[pinyin-search] backfill row skipped', {\n            object: schema.name,\n            id: row.id,\n            error: err?.message,\n          });\n        }\n      }\n\n      if (rows.length < batchSize) break;\n      offset += batchSize;\n    }\n  }\n\n  if (result.updated > 0) {\n    logger?.info?.('[pinyin-search] companion backfill complete', result);\n  }\n  return result;\n}\n\n/**\n * Periodic reconcile / rebuild entry: recompute the companion for every row\n * (optionally one object). Alias for `backfillSearchCompanion` with\n * `force: true` — exposed under its own name so operators/jobs have an\n * explicit \"rebuild the pinyin index\" handle.\n */\nexport function rebuildSearchCompanion(\n  engine: MinimalEngine,\n  logger?: MinimalLogger,\n  options?: Omit<CompanionBackfillOptions, 'force'>,\n): Promise<CompanionBackfillResult> {\n  return backfillSearchCompanion(engine, logger, { ...options, force: true });\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Pinyin normalization for the `__search` companion column (#2486).\n *\n * One normalized blob per record — full pinyin AND initials in the same\n * column — so a single `$contains` recalls every latin input shape:\n *\n *   \"张伟\"  →  \"zhangwei zw\"\n *     `zhang` / `wei` / `zhangwei`  → substring of the full form\n *     `zw`                          → substring of the initials form\n *\n * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag\n * off → hooks never bound) never import it and pay zero cost.\n *\n * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486\n * \"待定\" — surname polyphone dictionaries are a P2 follow-up).\n */\n\nimport { containsCJK } from '@objectstack/objectql';\n\ntype PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];\n\nlet _pinyin: Promise<PinyinFn> | null = null;\n\n/** Lazy-load `pinyin-pro` (cached module-wide). */\nfunction loadPinyin(): Promise<PinyinFn> {\n  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);\n  return _pinyin;\n}\n\n/** Lowercase and strip everything that is not a latin letter or digit. */\nfunction squash(syllables: string | string[]): string {\n  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');\n  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');\n}\n\n/**\n * Compute the companion value for the given source-field values.\n *\n * Returns the normalized blob (`\"<full-pinyin> <initials>\"`, deduplicated)\n * when at least one value contains CJK characters, else `null` — a `null`\n * companion means \"nothing pinyin-searchable here\" and clears any stale blob\n * when a name is edited away from CJK. Non-CJK values need no companion:\n * their source column already matches latin input directly.\n */\nexport async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {\n  const cjkValues = values.filter((v): v is string => containsCJK(v));\n  if (cjkValues.length === 0) return null;\n\n  const pinyin = await loadPinyin();\n  const parts: string[] = [];\n  for (const value of cjkValues) {\n    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed\n    // values (\"张伟2号\" → \"zhangwei2hao\"), so mixed names stay one token.\n    const full = squash(pinyin(value, { toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    const initials = squash(pinyin(value, { pattern: 'first', toneType: 'none', type: 'array', nonZh: 'consecutive' }));\n    if (full) parts.push(full);\n    if (initials && initials !== full) parts.push(initials);\n  }\n  if (parts.length === 0) return null;\n  return [...new Set(parts)].join(' ');\n}\n"],"mappings":"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","names":["containsCJK","containsCJK"]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@objectstack/plugin-pinyin-search",
+  "version": "15.1.0",
+  "license": "Apache-2.0",
+  "description": "Pinyin search recall for ObjectStack — populates the hidden `__search` companion column (full pinyin + initials of the display/name field) so `$search` hits CJK names typed as pinyin. Locale-gated via OS_SEARCH_PINYIN_ENABLED (#2486).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "pinyin-pro": "^3.28.1",
+    "@objectstack/core": "15.1.0",
+    "@objectstack/objectql": "15.1.0",
+    "@objectstack/types": "15.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "keywords": [
+    "objectstack",
+    "plugin",
+    "search",
+    "pinyin",
+    "i18n"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  }
+}