@dokebi/search 0.0.0-stage → 0.1.1

package/dist/install.js

@@ -0,0 +1,56 @@
+// Install lifecycle module (`dokebi.installModule`). It runs isolated in the CLI, so it imports
+// nothing and only reads the plain options it is given. Invalid options are left to the schema.
+const DB_PROVIDER = 'dokebi-db';
+/** dokebi-db connection names (the same rule as its options). */
+const CONNECTION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MIGRATION_SOURCE = 'templates/migrations/dokebi_search.ts';
+const DEFAULT_CONNECTION = 'main';
+/** The cursor signing secrets: `dokebi add` writes a generated one into dokebi.yaml. */
+const SECRETS_OPTION = 'secrets';
+/** The user-owned index declaration (D-0170 §2), the plugin's entry. */
+const ENTRY = Object.freeze({
+    source: 'templates/indexes.ts',
+    target: 'src/infra/search/indexes.ts',
+});
+function name(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    return typeof value === 'string' && CONNECTION.test(value) ? value : undefined;
+}
+/** UTC yyyyMMddHHmmss, the @dokebi/migrate file name prefix. */
+function stamp(now) {
+    return now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+}
+/**
+ * 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 function planInstall(context) {
+    const connection = name(context.options.connection, DEFAULT_CONNECTION);
+    const secrets = Array.isArray(context.planKeys) && context.planKeys.includes('configSecrets')
+        ? { configSecrets: [{ path: [SECRETS_OPTION] }] }
+        : {};
+    return {
+        requires: [DB_PROVIDER],
+        entry: ENTRY,
+        ...secrets,
+        ...(connection === undefined
+            ? {}
+            : {
+                files: [
+                    {
+                        source: MIGRATION_SOURCE,
+                        target: `src/infra/db/migrations/${connection}/${stamp(new Date())}_dokebi_search.ts`,
+                    },
+                ],
+            }),
+    };
+}
+export function planUpgrade() {
+    return { requires: [DB_PROVIDER], entry: ENTRY };
+}
+export function check() {
+    return { requires: [DB_PROVIDER], diagnostics: [] };
+}

package/dist/options.d.ts

@@ -0,0 +1,23 @@
+import { type OptionsOf } from '@dokebi/core';
+/** dokebi-db connection names (the same rule as its options). */
+export declare const CONNECTION_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$";
+export declare const MIN_SECRET_LENGTH = 32;
+export declare const DEFAULT_SECRETS_ENV = "DOKEBI_SEARCH_SECRETS";
+export declare const options: import("@dokebi/core").OptionsDeclaration<{
+    readonly connection: string;
+    readonly counts: {
+        readonly flushMs: number;
+        readonly slots: number;
+    };
+    readonly examineLimit: number;
+    readonly list: {
+        readonly maxLimit: number;
+    };
+    readonly pool: {
+        readonly max: number;
+    };
+    readonly searchLimit: number;
+    readonly secrets?: readonly string[];
+    readonly secretsEnv?: string;
+}>;
+export type SearchOptions = OptionsOf<typeof options>;

package/dist/options.js

@@ -0,0 +1,73 @@
+import { defineOptions, option as o } from '@dokebi/core';
+/*
+ * dokebi-search options (D-0170). options.schema.json is generated from this declaration at build
+ * time (D-0063 §3). The limits are rows of the term table a search reads (@dokebi/db AI.md 6.10).
+ */
+/** dokebi-db connection names (the same rule as its options). */
+export const CONNECTION_PATTERN = '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$';
+export const MIN_SECRET_LENGTH = 32;
+export const DEFAULT_SECRETS_ENV = 'DOKEBI_SEARCH_SECRETS';
+const ENV_NAME = '^[A-Za-z_][A-Za-z0-9_]{0,127}$';
+/** A settings object whose fields all have defaults (the parser fills them). */
+const EMPTY = {};
+export const options = defineOptions({
+    connection: o.string({
+        pattern: CONNECTION_PATTERN,
+        default: 'main',
+        description: "The dokebi-db connection of the database that holds the application's rows (the terms share their transaction); dokebi add writes the table migration into its migrations folder.",
+    }),
+    pool: o.object({
+        max: o.integer({
+            minimum: 0,
+            maximum: 64,
+            default: 4,
+            description: 'Connections of the pool derived from the connection for find, so searches never take the request pool. 0 uses the connection pool.',
+        }),
+    }, { default: EMPTY }),
+    examineLimit: o.integer({
+        minimum: 100,
+        maximum: 100_000,
+        default: 2000,
+        description: 'Most rows of the leading word one find call examines when a search has several words; reached before the page is full, it answers the matches found with next and partial: true.',
+    }),
+    searchLimit: o.integer({
+        minimum: 100,
+        maximum: 10_000_000,
+        default: 50_000,
+        description: 'Most rows one search of several words examines over all its pages (kept in the signed cursor); reached, it ends with stopped: SEARCH_TOO_BROAD. At least examineLimit.',
+    }),
+    list: o.object({
+        maxLimit: o.integer({
+            minimum: 1,
+            maximum: 1000,
+            default: 100,
+            description: 'Most items one find call returns.',
+        }),
+    }, { default: EMPTY }),
+    counts: o.object({
+        slots: o.integer({
+            minimum: 1,
+            maximum: 64,
+            default: 4,
+            description: "Rows a word's item count is split into (a flush adds to one at random, a read sums them), so the workers' flushes of common words do not wait on one row.",
+        }),
+        flushMs: o.integer({
+            minimum: 100,
+            maximum: 60_000,
+            default: 1000,
+            description: "How often each worker adds its buffered word counts to the table, outside every transaction (the counts only choose a search's leading word); also at drain and when 2000 words are buffered.",
+        }),
+    }, { default: EMPTY }),
+    secrets: o.array(o.string({ minLength: MIN_SECRET_LENGTH, maxLength: 512, secret: true }), {
+        minItems: 1,
+        maxItems: 8,
+        uniqueItems: true,
+        description: 'Cursor signing secrets (32+ characters); the first signs, all verify. dokebi add writes a generated one (npx dokebi config secret dokebi-search.secrets makes one later); keep dokebi.yaml out of version control',
+    }),
+    secretsEnv: o.string({
+        pattern: ENV_NAME,
+        // The name of an environment variable, never a secret itself.
+        plain: true,
+        description: `Environment variable that, when set and not empty, replaces secrets (comma-separated, the first signs): an optional production override (default ${DEFAULT_SECRETS_ENV})`,
+    }),
+});

package/dist/plugin.d.ts

@@ -0,0 +1,6 @@
+import { type Describer } from '@dokebi/core';
+import type { SearchApi } from './api.js';
+/** The `core:describe` point (core 0.4.2), declared by name. */
+export declare const describePoint: import("@dokebi/core").ContributionPoint<Describer>;
+/** Factory input: `{ app, options?, entry }`: `entry` is the module of src/infra/search/indexes.ts. */
+export declare const createPlugin: import("@dokebi/core").PluginFactory<SearchApi>;