@kubun/store-graph 0.13.1 → 0.13.2

package/lib/api.js

@@ -2,6 +2,7 @@ import { DocumentID, DocumentModelID } from '@kubun/id';
 import { serializeCursor } from './cursor.js';
 import { isMissingTableError, ModelNotDeployedError } from './errors.js';
 import { aggregateFieldName, applyAggregateSelections, applyDocumentFilter, applyDocumentOrderBy, applyGroupBySelections, applyPagination, groupKeyAlias, knownFieldColumn } from './query-builder.js';
+import { resolveSearchableFields, SearchNotEnabledError } from './search.js';
 // --- Helper functions ---
 // SQL numeric results round-trip as strings on some adapters (Postgres `numeric`/`sum`),
 // so normalise to a JS number, treating NULL/empty as null.
@@ -342,6 +343,31 @@ export function createGraphStore(db, adapter) {
             effectiveOwners: owners
         };
     }
+    // --- Write-path search index maintenance ---
+    //
+    // Runs inline in the caller's write transaction (`db` here IS that
+    // transaction), so the FTS entry commits atomically with the document row.
+    // Gated on the `kubun_graph_search_models` registry: a model with no row is
+    // not searchable, so these are a no-op for it.
+    async function indexFieldsFor(model) {
+        const row = await db.selectFrom('kubun_graph_search_models').select('fields').where('model_id', '=', model).executeTakeFirst();
+        return row ? row.fields : null;
+    }
+    async function reindexDocument(model, documentID, data) {
+        const fields = await indexFieldsFor(model);
+        if (fields == null) return;
+        const fieldValues = {};
+        for (const field of fields){
+            const value = extractFieldValue(data, field);
+            if (value != null) fieldValues[field] = String(value);
+        }
+        await adapter.updateSearchEntry(db, model, documentID, fieldValues, fields);
+    }
+    async function unindexDocument(model, documentID) {
+        const fields = await indexFieldsFor(model);
+        if (fields == null) return;
+        await adapter.removeSearchEntry(db, model, documentID);
+    }
     const api = {
         // --- Document operations ---
         async getDocument (id) {
@@ -420,14 +446,23 @@ export function createGraphStore(db, adapter) {
                 data: adapter.encodeJSON(params.data),
                 unique: adapter.encodeBinary(params.unique)
             }).returningAll().executeTakeFirstOrThrow(()=>new Error(`createDocument failed to return row for ${id}`));
+            if (params.data) {
+                await reindexDocument(model, id, params.data);
+            }
             return documentNodeFromTable(adapter, doc);
         },
         async saveDocument (params) {
             const id = params.id.toString();
-            const doc = await db.updateTable(`k_${params.id.model.toString()}`).set({
+            const model = params.id.model.toString();
+            const doc = await db.updateTable(`k_${model}`).set({
                 data: params.data ? adapter.encodeJSON(params.data) : null,
                 updated_at: adapter.encodeTimestamp(new Date())
             }).where('id', '=', id).returningAll().executeTakeFirstOrThrow(()=>new Error(`saveDocument: document not found for id=${id}`));
+            if (params.data) {
+                await reindexDocument(model, id, params.data);
+            } else {
+                await unindexDocument(model, id);
+            }
             return documentNodeFromTable(adapter, doc);
         },
         async queryDocuments (params) {
@@ -795,6 +830,65 @@ export function createGraphStore(db, adapter) {
                         added.add(id);
                     }));
                 }
+                // Search indices: for every model named in the search config, create the
+                // `fts_<model>` index (once) and record its denormalized registry row (the
+                // single source of truth the write path and read guard consult) TOGETHER,
+                // only when the index does not already exist. The registry's `fields` must
+                // always equal the live FTS table's columns — the write path inserts
+                // `INSERT INTO fts_<model> (document_id, <fields...>)` using the registry
+                // list, so a registry row naming a column the table lacks turns every
+                // subsequent write into a "no such column" failure that rolls back the
+                // whole write transaction. Once an index exists, the write path
+                // (`createDocument`/`saveDocument`) keeps its entries in sync inline, so a
+                // re-deploy over an existing index is a pure no-op: it must not re-derive
+                // rows it already has, and it must not touch the registry (a re-deploy that
+                // changes a model's field set is unsupported — the table's columns are
+                // frozen at first creation — but it must never break writes by drifting the
+                // registry ahead of the table). Existence is checked via Kysely's
+                // dialect-agnostic introspection rather than an adapter/dialect string check
+                // (the adapter's `dialect` is a Kysely `Dialect` object, not a string).
+                const searchConfig = params.search ?? {};
+                const searchModelIDs = Object.keys(params.record).filter((id)=>id in searchConfig);
+                let existingFTSTables;
+                if (searchModelIDs.length > 0) {
+                    const tables = await trx.introspection.getTables();
+                    existingFTSTables = new Set(tables.map((t)=>t.name));
+                }
+                for (const [modelID, model] of Object.entries(params.record)){
+                    if (!(modelID in searchConfig)) {
+                        continue;
+                    }
+                    const fields = resolveSearchableFields(model.fieldsMeta, searchConfig[modelID]?.fields);
+                    if (fields.length === 0) {
+                        continue;
+                    }
+                    if (existingFTSTables?.has(`fts_${modelID}`)) {
+                        continue;
+                    }
+                    await trx.insertInto('kubun_graph_search_models').values({
+                        model_id: modelID,
+                        fields: adapter.encodeJSON(fields)
+                    }).onConflict((oc)=>oc.column('model_id').doUpdateSet((eb)=>({
+                                fields: eb.ref('excluded.fields')
+                            }))).execute();
+                    await adapter.createSearchIndex(trx, {
+                        modelID,
+                        fields
+                    });
+                    const rows = await trx.selectFrom(`k_${modelID}`).selectAll().where('data', 'is not', null).execute();
+                    for (const row of rows){
+                        const node = documentNodeFromTable(adapter, row);
+                        const data = node.data ?? {};
+                        const fieldValues = {};
+                        for (const field of fields){
+                            const value = extractFieldValue(data, field);
+                            if (value != null) {
+                                fieldValues[field] = String(value);
+                            }
+                        }
+                        await adapter.updateSearchEntry(trx, modelID, node.id, fieldValues, fields);
+                    }
+                }
                 for (const [clusterID, cluster] of Object.entries(params.clusters ?? {})){
                     const entries = Object.entries(cluster.models).map(([modelID, index])=>({
                             model_id: modelID,
@@ -884,6 +978,17 @@ export function createGraphStore(db, adapter) {
             await adapter.removeSearchEntry(db, modelID, documentID);
         },
         async searchDocuments (params) {
+            // Guard against querying a model with no `kubun_graph_search_models`
+            // registry row: without this, a missing `fts_<model>` table surfaces
+            // as a raw adapter error (e.g. "no such table") instead of a clean,
+            // named one.
+            const configured = await db.selectFrom('kubun_graph_search_models').select('model_id').where('model_id', 'in', params.modelIDs).execute();
+            const configuredSet = new Set(configured.map((row)=>row.model_id));
+            for (const modelID of params.modelIDs){
+                if (!configuredSet.has(modelID)) {
+                    throw new SearchNotEnabledError(modelID);
+                }
+            }
             const allResults = [];
             for (const modelID of params.modelIDs){
                 const hits = await adapter.searchIndex(db, {

package/lib/index.d.ts

@@ -4,6 +4,7 @@ export type { GraphStoreAPI, StoredAccessDefaultRow, StoredAccessRule } from './
 export { createGraphStore } from './api.js';
 export { graphStoreDefinition } from './definition.js';
 export { ModelNotDeployedError } from './errors.js';
+export { resolveSearchableFields, SearchNotEnabledError } from './search.js';
 export declare const GRAPH_STORE: "graph";
 export declare function getGraphStore(provider: StoreProvider): Promise<GraphStoreAPI>;
 export type { AccessLevel, AccessPermissions, AddDocumentModelParams, Catalog, ClusterDefinitionRow, ClusterModel, ConnectionArguments, CreateDocumentParams, CreateGraphParams, CursorDocument, Document, DocumentData, DocumentModelRow, DocumentParams, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertDocument, InsertDocumentModel, InsertDocumentModelInterface, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, PaginatedResult, PaginationParams, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchConfig, SearchDocumentResult, SearchDocumentsParams, UpdateDocument, UpdateDocumentModel, ViewerReadAccess, } from './tables.js';

package/lib/index.js

@@ -1,6 +1,7 @@
 export { createGraphStore } from './api.js';
 export { graphStoreDefinition } from './definition.js';
 export { ModelNotDeployedError } from './errors.js';
+export { resolveSearchableFields, SearchNotEnabledError } from './search.js';
 export const GRAPH_STORE = 'graph';
 export function getGraphStore(provider) {
     return provider.getStore(GRAPH_STORE);

package/lib/migrations.js

@@ -24,6 +24,11 @@
             ]).execute();
             // Graph models
             await db.schema.createTable('kubun_graph_models').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('aliases', t.json, (col)=>col.defaultTo('{}').notNull()).addColumn('search', t.json).addColumn('extension_sdl', t.text).addColumn('plugin_config', t.json).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
+            // Search models registry: denormalized per-model FTS field list, written at
+            // deploy alongside the `fts_<model>` index. The write path and read guard read
+            // this table to learn which models are searchable and on which fields. `fields`
+            // mirrors the JSON column type used by `kubun_graph_models.search`.
+            await db.schema.createTable('kubun_graph_search_models').ifNotExists().addColumn('model_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('fields', t.json, (col)=>col.notNull()).execute();
             // Graph document model links (junction: graph-model ↔ document-model)
             await db.schema.createTable('kubun_graph_document_model_links').ifNotExists().addColumn('graph_model_id', t.text, (col)=>col.notNull().references('kubun_graph_models.id')).addColumn('document_model_id', t.text, (col)=>col.notNull().references('kubun_graph_document_models.id')).addUniqueConstraint('kubun_graph_document_model_links_pkey', [
                 'graph_model_id',
@@ -80,6 +85,7 @@
             }
         },
         async down (db) {
+            await db.schema.dropTable('kubun_graph_search_models').ifExists().execute();
             await db.schema.dropTable('kubun_graph_catalogs').ifExists().execute();
             await db.schema.dropTable('kubun_graph_clusters').ifExists().execute();
             await db.schema.dropTable('kubun_graph_cluster_models').ifExists().execute();

package/lib/search.d.ts

@@ -0,0 +1,10 @@
+import type { DocumentFieldsMeta } from '@kubun/protocol';
+/**
+ * The field list to index for a model: an explicit `search` config's `fields`
+ * when present and non-empty, otherwise the model's field-level `searchable`
+ * flags (in declaration order). Empty when neither applies.
+ */
+export declare function resolveSearchableFields(fieldsMeta: DocumentFieldsMeta | null | undefined, explicit?: Array<string>): Array<string>;
+export declare class SearchNotEnabledError extends Error {
+    constructor(modelID: string);
+}

package/lib/search.js

@@ -0,0 +1,19 @@
+/**
+ * The field list to index for a model: an explicit `search` config's `fields`
+ * when present and non-empty, otherwise the model's field-level `searchable`
+ * flags (in declaration order). Empty when neither applies.
+ */ export function resolveSearchableFields(fieldsMeta, explicit) {
+    if (explicit != null && explicit.length > 0) {
+        return explicit;
+    }
+    if (fieldsMeta == null) {
+        return [];
+    }
+    return Object.entries(fieldsMeta).filter(([, meta])=>meta?.searchable === true).map(([field])=>field);
+}
+export class SearchNotEnabledError extends Error {
+    constructor(modelID){
+        super(`Model ${modelID} does not have search enabled`);
+        this.name = 'SearchNotEnabledError';
+    }
+}

package/lib/tables.d.ts

@@ -55,6 +55,12 @@ export type GraphModelTable = {
 export type GraphModel = Selectable<GraphModelTable>;
 export type InsertGraphModel = Insertable<GraphModelTable>;
 export type UpdateGraphModel = Updateable<GraphModelTable>;
+export type SearchModelTable = {
+    model_id: string;
+    fields: JSONValueColumn<Array<string>>;
+};
+export type SearchModelRow = Selectable<SearchModelTable>;
+export type InsertSearchModel = Insertable<SearchModelTable>;
 export type GraphDocumentModelTable = {
     graph_model_id: string;
     document_model_id: string;
@@ -148,6 +154,7 @@ export type GraphTables = {
     kubun_graph_document_model_links: GraphDocumentModelTable;
     kubun_graph_models: GraphModelTable;
     kubun_graph_mutation_log: MutationLogTable;
+    kubun_graph_search_models: SearchModelTable;
     kubun_graph_user_model_access_defaults: UserModelAccessDefaultTable;
     [key: `k_${string}`]: DocumentTable;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-graph",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -17,15 +17,15 @@
   "dependencies": {
     "@sozai/codec": "^0.4.0",
     "kysely": "^0.29.5",
-    "@kubun/db-adapter": "^0.13.0",
     "@kubun/id": "^0.13.0",
-    "@kubun/protocol": "^0.13.1",
-    "@kubun/db": "^0.13.0"
+    "@kubun/db-adapter": "^0.13.1",
+    "@kubun/db": "^0.13.0",
+    "@kubun/protocol": "^0.13.1"
   },
   "devDependencies": {
     "@testcontainers/postgresql": "^12.1.0",
-    "@kubun/db-better-sqlite": "^0.13.0",
-    "@kubun/db-postgres": "^0.13.0"
+    "@kubun/db-postgres": "^0.13.0",
+    "@kubun/db-better-sqlite": "^0.13.0"
   },
   "publishConfig": {
     "access": "public"