@objectstack/plugin-pinyin-search 15.1.0

package/src/companion-projection.test.ts

@@ -0,0 +1,168 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #2486 — companion projection: before-save stamping, no-write-amplification
+ * guard, backfill and rebuild reconcile. Uses a minimal fake engine (the
+ * boot-backfill.test.ts pattern) with a stub registry.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  bindSearchCompanionHooks,
+  backfillSearchCompanion,
+  rebuildSearchCompanion,
+  PINYIN_SEARCH_HOOK_PACKAGE,
+} from './companion-projection.js';
+
+interface Row { [k: string]: any }
+
+const contactSchema = {
+  name: 'crm_contact',
+  nameField: 'name',
+  fields: {
+    name: { type: 'text' },
+    email: { type: 'email' },
+    __search: { type: 'text', hidden: true, readonly: true, system: true },
+  },
+};
+
+const plainSchema = {
+  name: 'crm_note',
+  fields: { title: { type: 'text' } }, // no companion provisioned
+};
+
+function makeEngine(schemas: any[]) {
+  const tables: Record<string, Row[]> = {};
+  const hooks: Record<string, Array<{ handler: (ctx: any) => any; opts: any }>> = {};
+  const byName = new Map(schemas.map((s) => [s.name, s]));
+  const engine = {
+    _tables: tables,
+    registry: {
+      getObject: (n: string) => byName.get(n),
+      getAllObjects: () => [...byName.values()],
+    },
+    registerHook(event: string, handler: any, opts?: any) {
+      (hooks[event] ??= []).push({ handler, opts });
+    },
+    unregisterHooksByPackage(packageId: string) {
+      let removed = 0;
+      for (const [event, entries] of Object.entries(hooks)) {
+        const kept = entries.filter((e) => e.opts?.packageId !== packageId);
+        removed += entries.length - kept.length;
+        hooks[event] = kept;
+      }
+      return removed;
+    },
+    async trigger(event: string, ctx: any) {
+      for (const { handler } of hooks[event] ?? []) await handler(ctx);
+    },
+    async find(o: string, opts?: any) {
+      const rows = tables[o] ?? [];
+      const offset = opts?.offset ?? 0;
+      return rows.slice(offset, offset + (opts?.limit ?? rows.length));
+    },
+    async insert(o: string, data: Row) {
+      const ctx = { object: o, event: 'beforeInsert', input: { data } };
+      await engine.trigger('beforeInsert', ctx);
+      (tables[o] ??= []).push({ ...ctx.input.data });
+      return ctx.input.data;
+    },
+    async update(o: string, data: Row) {
+      const ctx = { object: o, event: 'beforeUpdate', input: { id: data.id, data } };
+      await engine.trigger('beforeUpdate', ctx);
+      const t = tables[o] ?? [];
+      const i = t.findIndex((r) => r.id === data.id);
+      if (i >= 0) t[i] = { ...t[i], ...ctx.input.data };
+      return t[i];
+    },
+    _hooks: hooks,
+  };
+  return engine;
+}
+
+describe('bindSearchCompanionHooks', () => {
+  let engine: ReturnType<typeof makeEngine>;
+
+  beforeEach(() => {
+    engine = makeEngine([contactSchema, plainSchema]);
+    bindSearchCompanionHooks(engine as any);
+  });
+
+  it('binds beforeInsert + beforeUpdate globally and is idempotent (rebind-safe)', () => {
+    bindSearchCompanionHooks(engine as any); // rebind
+    expect(engine._hooks.beforeInsert).toHaveLength(1);
+    expect(engine._hooks.beforeUpdate).toHaveLength(1);
+    expect(engine._hooks.beforeInsert[0].opts.packageId).toBe(PINYIN_SEARCH_HOOK_PACKAGE);
+    expect(engine._hooks.beforeInsert[0].opts.object).toBeUndefined(); // global
+  });
+
+  it('stamps __search on insert when the name field carries CJK', async () => {
+    const row = await engine.insert('crm_contact', { id: 'c1', name: '张伟' });
+    expect(row.__search).toBe('zhangwei zw');
+  });
+
+  it('leaves __search null for latin names (source column already matches)', async () => {
+    const row = await engine.insert('crm_contact', { id: 'c2', name: 'Ada Lovelace' });
+    expect(row.__search).toBe(null);
+  });
+
+  it('recomputes on update ONLY when the source field is in the patch', async () => {
+    await engine.insert('crm_contact', { id: 'c3', name: '张伟' });
+    // email-only patch: no recompute, no companion key added
+    const patch: Row = { id: 'c3', email: 'zw@example.com' };
+    await engine.update('crm_contact', patch);
+    expect('__search' in patch).toBe(false);
+    // name patch: recompute
+    const updated = await engine.update('crm_contact', { id: 'c3', name: '王芳' });
+    expect(updated.__search).toBe('wangfang wf');
+  });
+
+  it('clears the companion when a CJK name is renamed to latin (no stale recall)', async () => {
+    await engine.insert('crm_contact', { id: 'c4', name: '张伟' });
+    const updated = await engine.update('crm_contact', { id: 'c4', name: 'Victor Zhang' });
+    expect(updated.__search).toBe(null);
+  });
+
+  it('ignores objects without a provisioned companion column', async () => {
+    const row = await engine.insert('crm_note', { id: 'n1', title: '会议纪要' });
+    expect('__search' in row).toBe(false);
+  });
+});
+
+describe('backfillSearchCompanion / rebuildSearchCompanion', () => {
+  it('fills rows missing a blob, in pages, and skips rows that need none', async () => {
+    const engine = makeEngine([contactSchema]);
+    engine._tables.crm_contact = [
+      { id: 'a', name: '张伟', __search: null },            // hook-bypassing write → fill
+      { id: 'b', name: 'Ada', __search: null },              // latin → skip
+      { id: 'c', name: '王芳', __search: 'wangfang wf' },    // already filled → skip
+      { id: 'd', name: '李雷', __search: null },             // fill (second page)
+    ];
+    const result = await backfillSearchCompanion(engine as any, undefined, { batchSize: 2 });
+    expect(result).toEqual({ objects: 1, scanned: 4, updated: 2 });
+    const rows = engine._tables.crm_contact;
+    expect(rows.find((r) => r.id === 'a')!.__search).toBe('zhangwei zw');
+    expect(rows.find((r) => r.id === 'b')!.__search).toBe(null);
+    expect(rows.find((r) => r.id === 'd')!.__search).toBe('lilei ll');
+  });
+
+  it('is idempotent — a second pass updates nothing', async () => {
+    const engine = makeEngine([contactSchema]);
+    engine._tables.crm_contact = [{ id: 'a', name: '张伟', __search: null }];
+    await backfillSearchCompanion(engine as any);
+    const second = await backfillSearchCompanion(engine as any);
+    expect(second.updated).toBe(0);
+  });
+
+  it('rebuild recomputes everything, clearing stale blobs (reconcile entry)', async () => {
+    const engine = makeEngine([contactSchema]);
+    engine._tables.crm_contact = [
+      { id: 'a', name: 'Renamed To Latin', __search: 'zhangwei zw' }, // stale → cleared
+      { id: 'b', name: '王芳', __search: 'wrongblob' },               // wrong → recomputed
+    ];
+    const result = await rebuildSearchCompanion(engine as any);
+    expect(result.updated).toBe(2);
+    expect(engine._tables.crm_contact[0].__search).toBe(null);
+    expect(engine._tables.crm_contact[1].__search).toBe('wangfang wf');
+  });
+});

package/src/companion-projection.ts

@@ -0,0 +1,214 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * `__search` companion-column projection (#2486).
+ *
+ * The column itself is DECLARED at object compile time by the SchemaRegistry
+ * (`provisionSearchCompanion`, gated on `OS_SEARCH_PINYIN_ENABLED`); this
+ * module only FILLS the value — the `plugin-sharing` primary-BU projection
+ * pattern (column on the object, plugin maintains it via hooks).
+ *
+ * Write path: global `beforeInsert`/`beforeUpdate` hooks stamp
+ * `data.__search` whenever a companion source field (the object's
+ * display/name field) is present in the write — i.e. only when the source
+ * actually changed, avoiding write amplification. Writes that bypass hooks
+ * (bulk import, direct migration) leave the companion empty; the boot
+ * backfill and the `rebuildSearchCompanion` reconcile entry cover that.
+ */
+
+import {
+  SEARCH_COMPANION_FIELD,
+  resolveSearchCompanionSources,
+  containsCJK,
+} from '@objectstack/objectql';
+import { computeSearchCompanionValue } from './pinyin.js';
+
+const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
+
+export const PINYIN_SEARCH_HOOK_PACKAGE = 'plugin-pinyin-search:companion';
+
+interface MinimalEngine {
+  registerHook(
+    event: string,
+    handler: (ctx: any) => any | Promise<any>,
+    options?: { object?: string | string[]; priority?: number; packageId?: string },
+  ): void;
+  unregisterHooksByPackage(packageId: string): number;
+  find(object: string, query?: any, options?: any): Promise<any[]>;
+  update(object: string, data: any, options?: any): Promise<any>;
+  registry?: {
+    getObject(name: string): any;
+    getAllObjects?(packageId?: string): any[];
+  };
+}
+
+interface MinimalLogger {
+  info?: (msg: any, ...rest: any[]) => void;
+  warn?: (msg: any, ...rest: any[]) => void;
+  debug?: (msg: any, ...rest: any[]) => void;
+}
+
+/**
+ * Stamp `data.__search` on a before-save hook context when a companion source
+ * field is part of the write. Recomputes from the NEW value; a non-CJK new
+ * value clears the companion (null) so stale pinyin never recalls a renamed
+ * record. Never throws — a normalization failure must not fail the write.
+ */
+async function stampCompanion(engine: MinimalEngine, ctx: any, logger?: MinimalLogger): Promise<void> {
+  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; // source unchanged → no recompute (no write amplification)
+
+  try {
+    data[SEARCH_COMPANION_FIELD] = await computeSearchCompanionValue(sources.map((s) => data[s]));
+  } catch (err: any) {
+    logger?.warn?.('[pinyin-search] companion normalization failed — write proceeds without it', {
+      object,
+      error: err?.message,
+    });
+  }
+}
+
+/**
+ * Bind the global before-save hooks that keep `__search` in step. Idempotent
+ * (unbinds the package first). Hooks are global (no object filter) with a
+ * cheap early-out: objects without a provisioned companion column return
+ * immediately. They run for system-context writes too — the projection must
+ * stay correct regardless of who writes (seeds, imports, admin UI).
+ */
+export function bindSearchCompanionHooks(engine: MinimalEngine, logger?: MinimalLogger): void {
+  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: any) => 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)');
+}
+
+export interface CompanionBackfillOptions {
+  /** Rows fetched per page during the scan. Default 1000. */
+  batchSize?: number;
+  /** Restrict to one object (reconcile entry); default: every provisioned object. */
+  object?: string;
+  /**
+   * Recompute EVERY row's companion, not just missing ones — the periodic
+   * reconcile/rebuild mode. Default false (backfill: only rows whose
+   * companion is empty but whose source has CJK content).
+   */
+  force?: boolean;
+}
+
+export interface CompanionBackfillResult {
+  objects: number;
+  scanned: number;
+  updated: number;
+}
+
+/**
+ * Backfill / reconcile the companion column.
+ *
+ * Denormalized-on-write columns go stale when writes bypass hooks (bulk
+ * import, direct migration) and are empty for rows that predate the switch
+ * being enabled. This scans every object that carries the companion column
+ * (paged, system context) and fills the gaps; with `force: true` it
+ * recomputes unconditionally (the periodic reconcile / rebuild entry).
+ * Idempotent; per-row failures are skipped so one bad row never aborts the
+ * pass.
+ */
+export async function backfillSearchCompanion(
+  engine: MinimalEngine,
+  logger?: MinimalLogger,
+  options?: CompanionBackfillOptions,
+): Promise<CompanionBackfillResult> {
+  const batchSize = Math.max(1, options?.batchSize ?? 1000);
+  const all = options?.object
+    ? [engine.registry?.getObject?.(options.object)].filter(Boolean)
+    : engine.registry?.getAllObjects?.() ?? [];
+
+  const result: CompanionBackfillResult = { 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: any[] = [];
+      try {
+        rows = await engine.find(schema.name, {
+          fields: ['id', ...sources, SEARCH_COMPANION_FIELD],
+          limit: batchSize,
+          offset,
+          context: SYSTEM_CTX,
+        });
+      } catch (err: any) {
+        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) => containsCJK(row[s]));
+        // Backfill mode: touch only rows missing a blob they should have.
+        // Force mode: recompute everything (also clears stale blobs).
+        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: any) {
+          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;
+}
+
+/**
+ * Periodic reconcile / rebuild entry: recompute the companion for every row
+ * (optionally one object). Alias for `backfillSearchCompanion` with
+ * `force: true` — exposed under its own name so operators/jobs have an
+ * explicit "rebuild the pinyin index" handle.
+ */
+export function rebuildSearchCompanion(
+  engine: MinimalEngine,
+  logger?: MinimalLogger,
+  options?: Omit<CompanionBackfillOptions, 'force'>,
+): Promise<CompanionBackfillResult> {
+  return backfillSearchCompanion(engine, logger, { ...options, force: true });
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { PinyinSearchPlugin } from './pinyin-search-plugin.js';
+export type { PinyinSearchPluginOptions } from './pinyin-search-plugin.js';
+export {
+  bindSearchCompanionHooks,
+  backfillSearchCompanion,
+  rebuildSearchCompanion,
+  PINYIN_SEARCH_HOOK_PACKAGE,
+} from './companion-projection.js';
+export type {
+  CompanionBackfillOptions,
+  CompanionBackfillResult,
+} from './companion-projection.js';
+export { computeSearchCompanionValue } from './pinyin.js';

package/src/pinyin-search-plugin.ts

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * PinyinSearchPlugin (#2486) — pinyin recall for `$search`.
+ *
+ * Pure hook plugin: the `__search` companion column is declared at object
+ * compile time by the SchemaRegistry (gated on the SAME
+ * `OS_SEARCH_PINYIN_ENABLED` decision point), the engine ORs it into the
+ * `$search` filter, and this plugin fills the value:
+ *
+ *   - before-save hooks: recompute full pinyin + initials of the
+ *     display/name field when it changes;
+ *   - boot backfill (`kernel:bootstrapped`): fill rows that predate the
+ *     switch or arrived via hook-bypassing writes;
+ *   - `rebuildSearchCompanion` (exported): explicit reconcile/rebuild entry.
+ *
+ * When the flag is off the plugin is inert: no hooks, no backfill, and
+ * `pinyin-pro` is never imported.
+ */
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import { resolveSearchPinyinEnabled } from '@objectstack/types';
+import {
+  bindSearchCompanionHooks,
+  backfillSearchCompanion,
+} from './companion-projection.js';
+
+export interface PinyinSearchPluginOptions {
+  /**
+   * Force-enable/disable regardless of `OS_SEARCH_PINYIN_ENABLED` (tests /
+   * embedders). Default: `resolveSearchPinyinEnabled()`.
+   */
+  enabled?: boolean;
+  /** Skip the boot backfill (default: run it once per boot). */
+  backfill?: boolean;
+}
+
+export class PinyinSearchPlugin implements Plugin {
+  name = 'com.objectstack.plugin.pinyin-search';
+  version = '1.0.0';
+  type = 'standard';
+  dependencies = ['com.objectstack.engine.objectql'];
+
+  private readonly options: PinyinSearchPluginOptions;
+
+  constructor(options: PinyinSearchPluginOptions = {}) {
+    this.options = options;
+  }
+
+  private get enabled(): boolean {
+    return this.options.enabled ?? resolveSearchPinyinEnabled();
+  }
+
+  async init(_ctx: PluginContext): Promise<void> {
+    // Nothing to register: the companion column is provisioned by the
+    // SchemaRegistry's compile-time seam, not injected at runtime.
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    if (!this.enabled) {
+      ctx.logger.debug?.('PinyinSearchPlugin: OS_SEARCH_PINYIN_ENABLED is off — inert');
+      return;
+    }
+
+    ctx.hook('kernel:ready', async () => {
+      const engine = this.resolveEngine(ctx);
+      if (!engine) {
+        ctx.logger.warn('PinyinSearchPlugin: no ObjectQL engine — companion hooks NOT bound');
+        return;
+      }
+      try {
+        bindSearchCompanionHooks(engine, ctx.logger as any);
+      } catch (err: any) {
+        ctx.logger.warn('PinyinSearchPlugin: companion hooks not bound', { error: err?.message });
+      }
+    });
+
+    // Backfill AFTER boot settles (`kernel:bootstrapped` fires once every
+    // `kernel:ready` hook — including seed loading — has completed), so
+    // seeded rows written before/around hook binding are reconciled too.
+    if (this.options.backfill !== false) {
+      ctx.hook('kernel:bootstrapped', async () => {
+        const engine = this.resolveEngine(ctx);
+        if (!engine) return;
+        try {
+          await backfillSearchCompanion(engine, ctx.logger as any);
+        } catch (err: any) {
+          ctx.logger.warn('PinyinSearchPlugin: companion backfill failed', { error: err?.message });
+        }
+      });
+    }
+  }
+
+  private resolveEngine(ctx: PluginContext): any {
+    try {
+      return ctx.getService<any>('objectql');
+    } catch {
+      try {
+        return ctx.getService<any>('data');
+      } catch {
+        return null;
+      }
+    }
+  }
+}

package/src/pinyin.test.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { computeSearchCompanionValue } from './pinyin.js';
+
+describe('computeSearchCompanionValue (#2486)', () => {
+  it('stores full pinyin + initials in one blob ("张伟" → "zhangwei zw")', async () => {
+    expect(await computeSearchCompanionValue(['张伟'])).toBe('zhangwei zw');
+  });
+
+  it('recalls every documented input shape as a substring of the blob', async () => {
+    const blob = (await computeSearchCompanionValue(['张伟']))!;
+    for (const typed of ['zhang', 'wei', 'zhangwei', 'zw']) {
+      expect(blob.includes(typed)).toBe(true);
+    }
+  });
+
+  it('handles multi-word and mixed CJK/latin values', async () => {
+    const blob = (await computeSearchCompanionValue(['上海分公司']))!;
+    expect(blob).toBe('shanghaifengongsi shfgs');
+
+    const mixed = (await computeSearchCompanionValue(['张伟2号']))!;
+    expect(mixed.includes('zhangwei2hao')).toBe(true);
+  });
+
+  it('returns null for non-CJK / empty / non-string values (companion cleared)', async () => {
+    expect(await computeSearchCompanionValue(['Zhang Wei'])).toBe(null);
+    expect(await computeSearchCompanionValue([''])).toBe(null);
+    expect(await computeSearchCompanionValue([null, undefined, 42])).toBe(null);
+    expect(await computeSearchCompanionValue([])).toBe(null);
+  });
+
+  it('deduplicates when initials equal the full form (single-char name)', async () => {
+    const blob = (await computeSearchCompanionValue(['张']))!;
+    expect(blob).toBe('zhang z');
+    // no duplicated tokens
+    expect(new Set(blob.split(' ')).size).toBe(blob.split(' ').length);
+  });
+});

package/src/pinyin.ts

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pinyin normalization for the `__search` companion column (#2486).
+ *
+ * One normalized blob per record — full pinyin AND initials in the same
+ * column — so a single `$contains` recalls every latin input shape:
+ *
+ *   "张伟"  →  "zhangwei zw"
+ *     `zhang` / `wei` / `zhangwei`  → substring of the full form
+ *     `zw`                          → substring of the initials form
+ *
+ * `pinyin-pro` is loaded lazily on first use: non-Chinese deployments (flag
+ * off → hooks never bound) never import it and pay zero cost.
+ *
+ * Polyphones: pinyin-pro's default heuristics are accepted (issue #2486
+ * "待定" — surname polyphone dictionaries are a P2 follow-up).
+ */
+
+import { containsCJK } from '@objectstack/objectql';
+
+type PinyinFn = (text: string, options?: Record<string, unknown>) => string | string[];
+
+let _pinyin: Promise<PinyinFn> | null = null;
+
+/** Lazy-load `pinyin-pro` (cached module-wide). */
+function loadPinyin(): Promise<PinyinFn> {
+  _pinyin ??= import('pinyin-pro').then((m: any) => (m.pinyin ?? m.default?.pinyin) as PinyinFn);
+  return _pinyin;
+}
+
+/** Lowercase and strip everything that is not a latin letter or digit. */
+function squash(syllables: string | string[]): string {
+  const joined = Array.isArray(syllables) ? syllables.join('') : String(syllables ?? '');
+  return joined.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+
+/**
+ * Compute the companion value for the given source-field values.
+ *
+ * Returns the normalized blob (`"<full-pinyin> <initials>"`, deduplicated)
+ * when at least one value contains CJK characters, else `null` — a `null`
+ * companion means "nothing pinyin-searchable here" and clears any stale blob
+ * when a name is edited away from CJK. Non-CJK values need no companion:
+ * their source column already matches latin input directly.
+ */
+export async function computeSearchCompanionValue(values: ReadonlyArray<unknown>): Promise<string | null> {
+  const cjkValues = values.filter((v): v is string => containsCJK(v));
+  if (cjkValues.length === 0) return null;
+
+  const pinyin = await loadPinyin();
+  const parts: string[] = [];
+  for (const value of cjkValues) {
+    // `nonZh: 'consecutive'` keeps latin/digit runs intact inside mixed
+    // values ("张伟2号" → "zhangwei2hao"), so mixed names stay one token.
+    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(' ');
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}