@dokebi/search 0.0.0-stage → 0.1.0

package/AI.md

@@ -0,0 +1,134 @@
+# AI guide — @dokebi/search
+
+Search in the lists of an application's own rows (posts, comments, members, log targets) that stays **bounded on a table that only grows**: @dokebi/db AI.md section 6.10, once. The words of each item are kept in a term table whose key ends in the display order, written **in the transaction of the text**; Korean and other languages that attach endings are found by the stem (word prefixes); one word is one index lookup whatever its frequency; several words are driven by the rarest, with a cap on the rows one call and one whole search examine, kept in a signed cursor. Answers are item ids in display order: your code reads its rows. PostgreSQL, MySQL 8, MariaDB 10.6+ through @dokebi/db (no MongoDB). Node >=24.0.0, core ^0.4.2, @dokebi/db ^0.4.1. Decision: [D-0170](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0170-search.md).
+
+## 1. Install and set up
+
+```sh
+npx dokebi add @dokebi/db --adapter pg          # the main connection, if the app has none yet
+npx dokebi add @dokebi/search                   # writes src/infra/search/indexes.ts, the migration and a cursor secret in dokebi.yaml
+npx dokebi-migrate up                           # creates dokebi_search_terms, dokebi_search_counts, dokebi_search_indexes
+```
+
+> `npx dokebi` is the @dokebi/cli installed in the project (`dokebi init` adds it to devDependencies). The npm package named `dokebi` is not this CLI, so never run `npx -y dokebi`. Without a local install use `npx -y @dokebi/cli …`.
+
+- **The tables live with your rows** (the dokebi-db connection `connection`, default `main`), so `index` shares the transaction that saves the text. At start the plugin derives its own pool of that connection (`pool.max`, default 4) for `find`, and checks the tables: without the migration the start fails with `TABLE_MISSING` (its fix: `npx dokebi-migrate up`).
+- **The cursor secret**: `dokebi add` writes a generated one into `secrets`; `npx dokebi config secret dokebi-search.secrets` makes one later. Without it the start fails with `SECRET_MISSING`. The variable of `secretsEnv` (default `DOKEBI_SEARCH_SECRETS`, comma-separated) wins over dokebi.yaml.
+- **The indexes** are `src/infra/search/indexes.ts` (yours; `dokebi add` writes an example):
+
+```ts snippet
+import { defineSearchIndexes } from '@dokebi/search';
+
+export default defineSearchIndexes({
+  posts: { fields: { title: {}, body: {}, author: { prefix: 0 } } },
+  members: { fields: { name: {}, nickname: {}, email: {} } },
+});
+```
+
+Index and field names are a-z then a-z, 0-9 or `_` (at most 40); at most 64 indexes of 32 fields. Per field: `prefix` (0–32, default 10) is the longest word prefix kept, so `도깨비` finds `도깨비가` and `도깨비를`, and `note` finds `notebook` <!-- docs-check: allow-hangul --> (0 keeps whole words only: a name list where a prefix would match too much); `minLength` (1–prefix, default 1) the shortest. A bad declaration fails the start (`INVALID_INDEXES`). The declaration's fingerprint is stored: after you change a field's rules the start warns `SEARCH_INDEX_CHANGED` and `status()` says `stale` until you indexed the rows again and called `markCurrent(index)`.
+
+## 2. Configuration `options.dokebi-search`
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `connection` | string | `main` | The dokebi-db connection of the database that holds your rows; `dokebi add` writes the migration into its folder |
+| `pool.max` | integer 0–64 | 4 | Connections of the pool derived from it for `find`; 0 uses the connection pool |
+| `examineLimit` | integer 100–100000 | 2000 | Most rows of the leading word one `find` of several words examines |
+| `searchLimit` | integer 100–10000000 | 50000 | Most rows one search of several words examines over all its pages; at least `examineLimit` |
+| `list.maxLimit` | integer 1–1000 | 100 | Most items one `find` returns (default page 20) |
+| `counts.slots` | integer 1–64 | 4 | Rows a word's item count is split into |
+| `counts.flushMs` | integer 100–60000 | 1000 | How often each worker adds its buffered word counts to the table |
+| `secrets` | array | — | Cursor signing secrets (32+ characters); the first signs, all verify |
+| `secretsEnv` | string | — | The environment variable that replaces `secrets` (default `DOKEBI_SEARCH_SECRETS`) |
+
+## 3. Index items
+
+```ts snippet
+import { dependency as searchDependency } from '@dokebi/search/dependency';
+
+const search = context.getDependency(searchDependency);
+// Saving a post: the row and its terms in one transaction.
+const client = await pool.connect();
+try {
+  await client.query('BEGIN');
+  const { rows } = await client.query(
+    'INSERT INTO posts (board_id, title, body, author_name, created_at) VALUES ($1, $2, $3, $4, $5) RETURNING id',
+    [board, title, body, authorName, Date.now()],
+  );
+  await search.index(client, 'posts', {
+    id: String(rows[0].id),
+    sortKey: createdAt,
+    scopes: ['', `board:${board}`],
+    fields: { title, body, author: authorName },
+  });
+  await client.query('COMMIT');
+} catch (error) {
+  await client.query('ROLLBACK');
+  throw error;
+} finally {
+  client.release();
+}
+```
+
+- **`index(tx, index, item)`** writes in the transaction of `tx` (the pg client of `BEGIN`…`COMMIT`, or the mysql2/mariadb connection of the transaction). `item` is the item's **whole** searchable text: `id` (1–128), `sortKey` (a safe integer: the display order, newest first — usually the creation time in ms), `scopes` (the filters a search is combined with, at most 32 of at most 64 characters; default `['']`, everything), `fields` (a text per declared field; absent or null has no terms; at most 1,000,000 characters). It reads the item's terms by the item index and writes only the difference; a new `sortKey` rewrites them. Call it in the transaction that changes the item's row, so that row's lock orders two writers of the same item.
+- **Scopes** are how a search is filtered without reading other rows: an item is indexed under each, so a board and its ancestor categories are `['', 'board:12', 'cat:3', 'cat:3/7']` and a search names one. Each scope adds the item's terms again: keep them few.
+- **`remove(tx, index, id)`** when the item is hidden or deleted → `{ removed }`. Items a viewer may not see must not be in the index (or in a scope that viewer searches): `find` answers ids, it does not check rights.
+- **`indexMany(tx, index, items)`**: a first fill or a re-index, in batches of a few hundred per transaction from a job; then `flush()` and `markCurrent(index)`.
+- **A display order that changes all the time** (views, likes) is not a `sortKey`: every change would rewrite every term row. Search in the index's order and rank a capped set of results yourself, saying so.
+- **Word counts** (which word is rarest) are a hint the plugin adds after the write, outside your transaction: each worker buffers them and writes them every `counts.flushMs`, at drain and on `flush()`. A common word's count is never a row every writer waits on, and a rolled-back write leaves its count changed: the counts may drift, the results never do.
+
+## 4. Search
+
+```ts snippet
+const page = await search.find('posts', {
+  field: 'body',
+  q: request.query.q,
+  scope: `board:${board}`,
+  limit: 20,
+  cursor: request.query.cursor,
+});
+const rows = await postsByIds(page.items.map((hit) => hit.id)); // keep the page's order
+return { rows, next: page.next, partial: page.partial, stopped: page.stopped };
+```
+
+- **`find(index, { field, q, scope?, limit?, cursor? })`** → `{ items: [{ id, sortKey }], next?, partial, stopped?, examined }`. Every word of `q` is required (AND), 1–8 words after normalisation (NFKC, lower case, split on anything that is not a letter, mark or digit). A word matches the words that start with it up to the field's `prefix`; a longer word matches whole words only. A word shorter than `minLength`, no word or more than 8 is `INVALID_QUERY` (400).
+- **One word** is one lookup in display order: a page reads `limit + 1` rows, whether the word is in three rows or in all of them.
+- **Several words**: the rarest leads in display order and every other word is a key lookup. One call examines at most `examineLimit` rows; when it reaches that before the page is full it answers what it found, `next` and `partial: true`. Never show an empty page on its own: follow `next` (show that the search continues) until there are matches or no `next`. A search that examined `searchLimit` rows over its pages ends with `stopped: 'SEARCH_TOO_BROAD'` and no `next`: show what was found and ask for a narrower word or scope.
+- **`next`** is signed (HMAC-SHA256 with `secrets`) and bound to its query: pass it back unchanged as `cursor` with the same `field`, `q` and `scope`; anything else is `INVALID_CURSOR` (400). The running total of a search is in it, so a client cannot reset it.
+- **No relevance ranking**: results are in the index's display order. `examined` is the number of term rows the call read; keep it as a test of your lists (@dokebi/db AI.md 6.10: measure all five kinds — a word nothing has, a rare one, one in most rows, two characters, two common words that rarely meet).
+- **`terms(index, field, text)`**: the terms a text gets (what can match); `words`, `terms` and `queryTerms` are exported as pure functions.
+
+## 5. Logs, health and describe
+
+debug ([D-0047](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0047-logging-and-no-silent-errors.md)): `SEARCH_SETUP` (connection, indexes, ready, ms), `SEARCH_SECRETS` (where the secrets came from and how many, never their values), `SEARCH_CONNECTED` (dialect, server version, pool, stale indexes), `SEARCH_STORE_FAILED` (operation, the full error; the caller gets `STORE_FAILED` with it as the cause), `SEARCH_TOO_BROAD`. info: `SEARCH_DB_RECOVERED`. warn: `SEARCH_DB_UNAVAILABLE`, `SEARCH_INDEX_CHANGED` (with its fix). error: `SEARCH_COUNTS_FAILED` (a count flush failed; kept for the next one; repeats counted once a minute). On a `startup: optional` connection whose database is down at start ([D-0127](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0127-optional-db-startup.md)) the app starts; calls answer `NOT_READY` (503) and reach the database again at most once a second. `dokebi describe` connects nothing: section `search` (connection, tables, indexes and fields, limits); calls answer `DESCRIBING`.
+
+## 6. Errors
+
+`SearchError` (`name`, `code`, `plugin: dokebi-search`, `fix`, `data`).
+
+<!-- docs-check: complete-error-codes SearchErrorCode -->
+| Code | When |
+|---|---|
+| `INVALID_OPTIONS` | options the schema refuses, `searchLimit` below `examineLimit`, bad secrets in the environment variable |
+| `INVALID_INDEXES` | the entry has no declaration, or a name or rule outside its rule |
+| `UNKNOWN_INDEX` | an index not declared |
+| `UNKNOWN_FIELD` | a field the index does not declare |
+| `INVALID_ITEM` | an item field outside its rule (`data.field`), a transaction client without `query` |
+| `INVALID_QUERY` | no word, more than 8, one shorter than `minLength`, a bad scope or limit (400) |
+| `INVALID_CURSOR` | a cursor this server did not sign, a changed one, or one of another query (400) |
+| `SECRET_MISSING` | no `secrets` in dokebi.yaml and the variable of `secretsEnv` is empty |
+| `UNKNOWN_CONNECTION` | `connection` is not a dokebi-db connection |
+| `UNSUPPORTED_RESOURCE` | the connection is not a pg, mysql2/promise or mariadb pool (MongoDB) |
+| `TABLE_MISSING` | the tables or their columns are missing at start (run the migration) |
+| `NOT_READY` | the database of an optional connection is down (503) |
+| `STORE_FAILED` | a statement failed (the driver error is the cause) |
+| `DESCRIBING` | a call during `dokebi describe` |
+
+## 7. Cautions
+
+- Index **in the transaction** that saves the text; an index written outside it can stay when the save fails.
+- Remove what a viewer may not see (`remove`, or a scope they never search), and still check rights on the rows you read by id.
+- A long word is cut to 64 characters; two words that share their first 64 match each other.
+- Changing `prefix` or `minLength` changes what the stored rows mean: index the rows again (`indexMany` in batches from a job), then `markCurrent`.
+- Exports: `createPlugin`, `dependency` (also `@dokebi/search/dependency`), `defineSearchIndexes`, `SearchError`, `options`, `words`, `terms`, `queryTerms`, `TERMS_TABLE`, `COUNTS_TABLE`, `INDEXES_TABLE`, types `SearchApi`, `SearchItem`, `SearchQuery`, `SearchAnswer`, `SearchHit`, `SearchIndexStatus`, `SearchIndexes`, `IndexesDeclaration`, `IndexDeclaration`, `FieldDeclaration`, `TermRules`, `SearchErrorCode`, `SearchOptions`.
+- Example: [examples/66-search](https://git.nyx-zone.com/dokebi/framework/-/blob/main/examples/66-search/README.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dokebi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @dokebi/search
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Search in the lists of an application's own rows that stays bounded on a growing table (@dokebi/db AI.md 6.10), on PostgreSQL, MySQL 8 and MariaDB 10.6+ through @dokebi/db. Version 0.1.0 (unpublished). AI agents start with [AI.md](AI.md); the design is [D-0170](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0170-search.md).
+
+- `search.index(tx, 'posts', { id, sortKey, scopes, fields })` writes the item's terms in the transaction that saves its text: every word and its prefixes, so a stem finds the words languages attach endings to.
+- `search.find('posts', { field, q, scope, cursor })`: one word is one index lookup in display order; several words are driven by the rarest, with a cap per call (`examineLimit`) and per search (`searchLimit`) kept in a signed cursor, and `stopped: 'SEARCH_TOO_BROAD'` at the end of a search that is too broad. Answers item ids; your code reads the rows.
+- Indexes come from `src/infra/search/indexes.ts` (`defineSearchIndexes`), which `npx dokebi add @dokebi/search` writes with the table migration and a cursor secret.
+
+MIT licensed.

package/dist/api.d.ts

@@ -0,0 +1,78 @@
+import type { SearchIndexes } from './indexes.js';
+/** One item of an index: its whole searchable text, the display order and the filters. */
+export interface SearchItem {
+    /** The application's id of the row (1–128 characters). */
+    readonly id: string;
+    /** The display order, newest first: a safe integer (usually the creation time in ms). */
+    readonly sortKey: number;
+    /**
+     * The filters a search is combined with (a board, each ancestor category), at most 32 of at
+     * most 64 characters; the item is indexed under each. Default `['']`: everything.
+     */
+    readonly scopes?: readonly string[];
+    /** The text of each declared field; a field left out or null has no terms. */
+    readonly fields: Readonly<Record<string, string | null | undefined>>;
+}
+export interface SearchQuery {
+    /** The declared field to search. */
+    readonly field: string;
+    /** The words, all required (1–8 after normalisation). */
+    readonly q: string;
+    /** One scope the items were indexed under; default `''` (everything). */
+    readonly scope?: string;
+    /** Items per page (default 20, at most list.maxLimit). */
+    readonly limit?: number;
+    /** The `next` of the previous answer of the same search. */
+    readonly cursor?: string;
+}
+export interface SearchHit {
+    readonly id: string;
+    readonly sortKey: number;
+}
+export interface SearchAnswer {
+    /** Matches in display order (sortKey, then id, descending). */
+    readonly items: readonly SearchHit[];
+    /** Present when more matches may follow: pass it back as `cursor`. */
+    readonly next?: string;
+    /**
+     * The request reached examineLimit before the page was full: the matches found so far, and
+     * `next` to go on. Follow `next` (showing that the search continues) rather than showing an
+     * empty page on its own.
+     */
+    readonly partial: boolean;
+    /** The search examined searchLimit rows over its pages and ended: ask for a narrower query. */
+    readonly stopped?: 'SEARCH_TOO_BROAD';
+    /** Rows of the term table this call examined. */
+    readonly examined: number;
+}
+export interface SearchIndexStatus {
+    readonly name: string;
+    readonly fingerprint: string;
+    /** The declaration changed since the rows were indexed: index them again, then markCurrent. */
+    readonly stale: boolean;
+}
+export interface SearchApi {
+    /** The declared indexes (src/infra/search/indexes.ts). */
+    readonly indexes: SearchIndexes;
+    /** The terms a text gets in a field (what a search can match), sorted. */
+    terms(index: string, field: string, text: string): readonly string[];
+    /** Writes the item's terms in the caller's transaction, replacing what it had. */
+    index(tx: unknown, index: string, item: SearchItem): Promise<void>;
+    /** `index` for several items, in one transaction (a first fill or a re-index in batches). */
+    indexMany(tx: unknown, index: string, items: readonly SearchItem[]): Promise<void>;
+    /** Removes the item's terms (hidden or deleted) in the caller's transaction. */
+    remove(tx: unknown, index: string, id: string): Promise<{
+        readonly removed: boolean;
+    }>;
+    /** One page of a search; bounded by examineLimit per call and searchLimit per search. */
+    find(index: string, query: SearchQuery): Promise<SearchAnswer>;
+    /**
+     * Writes the buffered word counts now (each worker does every counts.flushMs and at drain);
+     * a re-index job calls it when it finished. Never rejects: a failure is logged and retried.
+     */
+    flush(): Promise<void>;
+    /** Records the current declaration of an index as indexed (after a re-index finished). */
+    markCurrent(index: string): Promise<void>;
+    /** Per index: the fingerprint and whether it is stale. No I/O. */
+    status(): readonly SearchIndexStatus[];
+}

package/dist/api.js

@@ -0,0 +1 @@
+export {};

package/dist/cursor.d.ts

@@ -0,0 +1,19 @@
+export interface CursorState {
+    /** The query fingerprint (index, field, scope, terms). */
+    readonly query: string;
+    /** The leading word of a search of several words; absent for one word. */
+    readonly lead?: string;
+    readonly sortKey: number;
+    readonly id: string;
+    /** Rows of the leading word examined over every page so far. */
+    readonly examined: number;
+}
+/** The fingerprint of a query: a cursor of another query is refused. */
+export declare function queryFingerprint(index: string, field: string, scope: string, terms: readonly string[]): string;
+export declare class Cursors {
+    #private;
+    constructor(secrets: readonly string[]);
+    sign(state: CursorState): string;
+    /** The state of a cursor this server signed for `query`, or INVALID_CURSOR. */
+    open(cursor: unknown, query: string): CursorState;
+}

package/dist/cursor.js

@@ -0,0 +1,68 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { SearchError } from './errors.js';
+const MAX_CURSOR = 1024;
+/** The fingerprint of a query: a cursor of another query is refused. */
+export function queryFingerprint(index, field, scope, terms) {
+    return createHash('sha256')
+        .update(JSON.stringify([index, field, scope, [...terms].sort()]))
+        .digest('base64url')
+        .slice(0, 22);
+}
+export class Cursors {
+    #secrets;
+    constructor(secrets) {
+        this.#secrets = secrets.map((secret) => Buffer.from(secret, 'utf8'));
+    }
+    #mac(body, secret) {
+        return createHmac('sha256', secret).update(body).digest();
+    }
+    sign(state) {
+        const body = Buffer.from(JSON.stringify([state.query, state.lead ?? null, state.sortKey, state.id, state.examined]), 'utf8').toString('base64url');
+        const mac = this.#mac(body, this.#secrets[0]).toString('base64url');
+        return `${body}.${mac}`;
+    }
+    /** The state of a cursor this server signed for `query`, or INVALID_CURSOR. */
+    open(cursor, query) {
+        const refuse = (reason) => new SearchError('INVALID_CURSOR', `The search cursor is not valid: ${reason}`, {
+            data: { reason },
+        });
+        if (typeof cursor !== 'string' || cursor.length > MAX_CURSOR)
+            throw refuse('not a cursor');
+        const dot = cursor.indexOf('.');
+        if (dot < 1)
+            throw refuse('not a cursor');
+        const body = cursor.slice(0, dot);
+        const given = Buffer.from(cursor.slice(dot + 1), 'base64url');
+        const signed = this.#secrets.some((secret) => {
+            const expected = this.#mac(body, secret);
+            return given.length === expected.length && timingSafeEqual(given, expected);
+        });
+        if (!signed)
+            throw refuse('signature');
+        let fields;
+        try {
+            fields = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        }
+        catch (cause) {
+            // A signed body always parses; this is a cursor of a changed format, refused with its cause.
+            throw new SearchError('INVALID_CURSOR', 'The search cursor is not valid: body', { cause });
+        }
+        if (!Array.isArray(fields) || fields.length !== 5)
+            throw refuse('body');
+        const [owner, lead, sortKey, id, examined] = fields;
+        if (owner !== query)
+            throw refuse('another query');
+        if ((lead !== null && typeof lead !== 'string') ||
+            !Number.isSafeInteger(sortKey) ||
+            typeof id !== 'string' ||
+            !Number.isSafeInteger(examined))
+            throw refuse('body');
+        return {
+            query,
+            ...(typeof lead === 'string' ? { lead } : {}),
+            sortKey: sortKey,
+            id,
+            examined: examined,
+        };
+    }
+}

package/dist/dependency.d.ts

@@ -0,0 +1,4 @@
+import type { SearchApi } from './api.js';
+export declare const provider: import("@dokebi/core").ProviderDescriptor<SearchApi>;
+/** Required: created from @dokebi/search when no `dokebi-search` plugin is registered. */
+export declare const dependency: import("@dokebi/core").PluginDependency<SearchApi>;

package/dist/dependency.js

@@ -0,0 +1,13 @@
+import { defineProvider } from '@dokebi/core';
+/*
+ * The one place dokebi-search states its name, package and range (D-0063 §6). A module that
+ * indexes or searches lists `dependency` from '@dokebi/search/dependency'.
+ */
+export const provider = defineProvider({
+    name: 'dokebi-search',
+    version: '^0.1.0',
+    packageName: '@dokebi/search',
+    load: () => import('./index.js'),
+});
+/** Required: created from @dokebi/search when no `dokebi-search` plugin is registered. */
+export const dependency = provider.dependency;

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+import { DokebiError, type DokebiErrorOptions } from '@dokebi/core';
+export type SearchErrorCode = 'INVALID_OPTIONS' | 'INVALID_INDEXES' | 'UNKNOWN_INDEX' | 'UNKNOWN_FIELD' | 'INVALID_ITEM' | 'INVALID_QUERY' | 'INVALID_CURSOR' | 'SECRET_MISSING' | 'UNKNOWN_CONNECTION' | 'UNSUPPORTED_RESOURCE' | 'TABLE_MISSING' | 'NOT_READY' | 'STORE_FAILED' | 'DESCRIBING';
+/** Errors of @dokebi/search (D-0063): a DokebiError with `plugin: 'dokebi-search'`. */
+export declare class SearchError extends DokebiError<SearchErrorCode> {
+    constructor(code: SearchErrorCode, message: string, options?: DokebiErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,58 @@
+import { DokebiError } from '@dokebi/core';
+/** Repair advice (D-0063): `fix` for the developer or AI, `hint` for whoever got the error. */
+const ADVICE = {
+    INVALID_OPTIONS: {
+        fix: 'Correct options.dokebi-search in dokebi.yaml; options.schema.json of @dokebi/search lists the fields (searchLimit is at least examineLimit).',
+    },
+    INVALID_INDEXES: {
+        fix: 'Export default defineSearchIndexes({ <index>: { fields: { <field>: { prefix?, minLength? } } } }) from src/infra/search/indexes.ts (npx dokebi add @dokebi/search writes it); names are a-z then a-z, 0-9 or _, at most 40 characters.',
+    },
+    UNKNOWN_INDEX: {
+        fix: 'Use an index of src/infra/search/indexes.ts, or declare it there.',
+    },
+    UNKNOWN_FIELD: {
+        fix: 'Use a field the index declares in src/infra/search/indexes.ts, or declare it there (then index the rows again).',
+    },
+    INVALID_ITEM: {
+        fix: 'Pass { id (1-128 characters), sortKey (a safe integer), scopes? (up to 32 strings of at most 64 characters), fields: { <declared field>: string } } and the transaction client.',
+    },
+    INVALID_QUERY: {
+        fix: 'Search with 1 to 8 words (letters or digits), each at least the field minLength, a limit within list.maxLimit and a scope of at most 64 characters.',
+        hint: 'Type at least one word to search for.',
+    },
+    INVALID_CURSOR: {
+        fix: 'Pass back the next value of the previous answer of the same search unchanged; a cursor of another query or a changed one is refused.',
+        hint: 'Start the search again.',
+    },
+    SECRET_MISSING: {
+        fix: 'Run npx dokebi config secret dokebi-search.secrets (npx dokebi add @dokebi/search does this on install), or set the environment variable of secretsEnv (default DOKEBI_SEARCH_SECRETS).',
+    },
+    UNKNOWN_CONNECTION: {
+        fix: 'Set options.dokebi-search.connection to a dokebi-db connection (default main), or add that connection.',
+    },
+    UNSUPPORTED_RESOURCE: {
+        fix: 'Use a pg, mysql2/promise or mariadb pool (the @dokebi/db templates); MongoDB is not supported in version 1 (D-0170).',
+    },
+    TABLE_MISSING: {
+        fix: 'Run npx dokebi-migrate up: the migration npx dokebi add @dokebi/search wrote creates dokebi_search_terms, dokebi_search_counts and dokebi_search_indexes.',
+    },
+    NOT_READY: {
+        hint: 'Search is not available right now; try again shortly.',
+    },
+    STORE_FAILED: {
+        hint: 'The search could not be run; try again shortly.',
+    },
+};
+/** Errors of @dokebi/search (D-0063): a DokebiError with `plugin: 'dokebi-search'`. */
+export class SearchError extends DokebiError {
+    constructor(code, message, options = {}) {
+        super(code, message, {
+            ...ADVICE[code],
+            ...(code === 'NOT_READY' ? { status: 503 } : {}),
+            ...(code === 'INVALID_QUERY' || code === 'INVALID_CURSOR' ? { status: 400 } : {}),
+            ...options,
+            plugin: 'dokebi-search',
+        });
+        this.name = 'SearchError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { SearchAnswer, SearchApi, SearchHit, SearchIndexStatus, SearchItem, SearchQuery, } from './api.js';
+export { dependency } from './dependency.js';
+export { SearchError, type SearchErrorCode } from './errors.js';
+export { defineSearchIndexes, type FieldDeclaration, type IndexDeclaration, type IndexesDeclaration, type SearchIndexes, } from './indexes.js';
+export { options, type SearchOptions } from './options.js';
+export { createPlugin } from './plugin.js';
+export { COUNTS_TABLE, INDEXES_TABLE, TERMS_TABLE } from './store.js';
+export { queryTerms, type TermRules, terms, words } from './terms.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { dependency } from './dependency.js';
+export { SearchError } from './errors.js';
+export { defineSearchIndexes, } from './indexes.js';
+export { options } from './options.js';
+export { createPlugin } from './plugin.js';
+export { COUNTS_TABLE, INDEXES_TABLE, TERMS_TABLE } from './store.js';
+export { queryTerms, terms, words } from './terms.js';

package/dist/indexes.d.ts

@@ -0,0 +1,27 @@
+import { type TermRules } from './terms.js';
+export interface FieldDeclaration {
+    /** The longest word prefix indexed (default 10); 0 indexes whole words only. */
+    readonly prefix?: number;
+    /** The shortest prefix indexed (default 1, at most prefix). */
+    readonly minLength?: number;
+}
+export interface IndexDeclaration {
+    readonly fields: Readonly<Record<string, FieldDeclaration>>;
+}
+export type IndexesDeclaration = Readonly<Record<string, IndexDeclaration>>;
+export interface SearchIndexes {
+    /** The declared index names, in declaration order. */
+    readonly names: readonly string[];
+    /** The fields of an index, or undefined for an unknown index. */
+    fields(index: string): readonly string[] | undefined;
+    /** The term rules of a field, or undefined for an unknown index or field. */
+    rules(index: string, field: string): TermRules | undefined;
+    /** The fingerprint of an index (32 hex characters). */
+    fingerprint(index: string): string | undefined;
+}
+export declare const NAME: RegExp;
+export declare const DEFAULT_PREFIX = 10;
+/** Checks the declaration once and returns the indexes the plugin and the application use. */
+export declare function defineSearchIndexes(declaration: IndexesDeclaration): SearchIndexes;
+/** The indexes of the entry module (`export default defineSearchIndexes(…)`), or themselves. */
+export declare function indexesOf(entry: unknown): SearchIndexes;

package/dist/indexes.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { SearchError } from './errors.js';
+import { MAX_PREFIX, TERMS_VERSION } from './terms.js';
+export const NAME = /^[a-z][a-z0-9_]{0,39}$/;
+const MAX_INDEXES = 64;
+const MAX_FIELDS = 32;
+export const DEFAULT_PREFIX = 10;
+const BRAND = Symbol.for('dokebi.search.indexes');
+function invalid(message) {
+    return new SearchError('INVALID_INDEXES', message);
+}
+function plain(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function integer(value, fallback, low, high, at) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < low || value > high)
+        throw invalid(`${at} is an integer from ${low} to ${high}`);
+    return value;
+}
+/** Checks the declaration once and returns the indexes the plugin and the application use. */
+export function defineSearchIndexes(declaration) {
+    if (!plain(declaration))
+        throw invalid('The declaration is an object of indexes');
+    const names = Object.keys(declaration);
+    if (!names.length)
+        throw invalid('The declaration has no index');
+    if (names.length > MAX_INDEXES)
+        throw invalid(`More than ${MAX_INDEXES} indexes`);
+    const rules = new Map();
+    const prints = new Map();
+    for (const index of names) {
+        if (!NAME.test(index))
+            throw invalid(`Index name ${JSON.stringify(index)} is not a-z, 0-9, _`);
+        const entry = declaration[index];
+        if (!plain(entry) || !plain(entry.fields))
+            throw invalid(`Index ${index} has no fields object`);
+        const fields = Object.keys(entry.fields);
+        if (!fields.length)
+            throw invalid(`Index ${index} has no field`);
+        if (fields.length > MAX_FIELDS)
+            throw invalid(`Index ${index} has more than ${MAX_FIELDS} fields`);
+        const map = new Map();
+        for (const field of fields) {
+            if (!NAME.test(field))
+                throw invalid(`Field name ${JSON.stringify(field)} of ${index} is not a-z, 0-9, _`);
+            const given = entry.fields[field];
+            if (given !== undefined && !plain(given))
+                throw invalid(`Field ${index}.${field} is an object of rules`);
+            const unknown = Object.keys(given ?? {}).filter((key) => key !== 'prefix' && key !== 'minLength');
+            if (unknown.length)
+                throw invalid(`Field ${index}.${field} has unknown rules: ${unknown}`);
+            const prefix = integer(given?.prefix, DEFAULT_PREFIX, 0, MAX_PREFIX, `${index}.${field}.prefix`);
+            const minLength = integer(given?.minLength, 1, 1, Math.max(1, prefix), `${index}.${field}.minLength`);
+            map.set(field, Object.freeze({ prefix, minLength }));
+        }
+        rules.set(index, map);
+        const shape = [...map].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        prints.set(index, createHash('sha256')
+            .update(JSON.stringify({ version: TERMS_VERSION, fields: shape }))
+            .digest('hex')
+            .slice(0, 32));
+    }
+    const api = {
+        names: Object.freeze([...names]),
+        fields: (index) => {
+            const map = typeof index === 'string' ? rules.get(index) : undefined;
+            return map ? Object.freeze([...map.keys()]) : undefined;
+        },
+        rules: (index, field) => typeof index === 'string' && typeof field === 'string'
+            ? rules.get(index)?.get(field)
+            : undefined,
+        fingerprint: (index) => prints.get(index),
+    };
+    Object.defineProperty(api, BRAND, { value: true });
+    return Object.freeze(api);
+}
+/** The indexes of the entry module (`export default defineSearchIndexes(…)`), or themselves. */
+export function indexesOf(entry) {
+    const candidate = entry !== null && typeof entry === 'object' && !(BRAND in entry)
+        ? entry.default
+        : entry;
+    if (candidate !== null && typeof candidate === 'object' && BRAND in candidate)
+        return candidate;
+    throw new SearchError('INVALID_INDEXES', 'The search entry has no indexes: src/infra/search/indexes.ts exports default defineSearchIndexes({ … })');
+}

package/dist/install.d.ts

@@ -0,0 +1,37 @@
+interface InstallContext {
+    readonly options: Readonly<Record<string, unknown>>;
+    /** The keys this CLI accepts in a planInstall result (CLI 0.4.3 and later). */
+    readonly planKeys?: readonly string[];
+}
+/**
+ * The index declaration (src/infra/search/indexes.ts), the table migration in the migrations
+ * folder of `connection` (default main, the database of the application's rows) and a generated
+ * cursor secret in dokebi.yaml (a CLI without `configSecrets` leaves it to
+ * `npx dokebi config secret dokebi-search.secrets`, which the start asks for).
+ */
+export declare function planInstall(context: InstallContext): {
+    requires: string[];
+    entry: {
+        source: string;
+        target: string;
+    };
+    files?: {
+        source: string;
+        target: string;
+    }[];
+    configSecrets?: {
+        path: string[];
+    }[];
+};
+export declare function planUpgrade(): {
+    requires: string[];
+    entry: {
+        source: string;
+        target: string;
+    };
+};
+export declare function check(): {
+    requires: string[];
+    diagnostics: [];
+};
+export {};