@kubun/store-graph 0.16.0 → 0.17.1

package/lib/api.d.ts

@@ -1,8 +1,36 @@
 import type { Adapter } from '@kubun/db-adapter';
 import { DocumentID, DocumentModelID } from '@kubun/id';
-import type { AggregateDocumentsParams, AggregateValues, DocumentModel, DocumentNode, GroupedAggregateDocumentsParams, GroupedAggregateValue } from '@kubun/protocol';
+import type { AggregateDocumentsParams, AggregateValues, DocumentFieldsMeta, DocumentModel, DocumentModelSchema, DocumentNode, GroupedAggregateDocumentsParams, GroupedAggregateValue } from '@kubun/protocol';
 import type { Kysely } from 'kysely';
-import type { AccessLevel, Catalog, ClusterDefinitionRow, ClusterModel, CreateDocumentParams, CreateGraphParams, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchDocumentResult, SearchDocumentsParams } from './tables.js';
+import type { AccessLevel, Catalog, ClusterDefinitionRow, ClusterModel, CreateDocumentParams, CreateGraphParams, DocumentModelRow, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchDocumentResult, SearchDocumentsParams } from './tables.js';
+export declare function documentModelFromTable(row: DocumentModelRow): DocumentModel;
+export declare function documentModelToTable(adapter: Adapter, id: string, model: DocumentModel): {
+    id: string;
+    version: "1.0";
+    name: string;
+    behavior: "unique" | "default" | "interface";
+    unique_fields: string[] | null;
+    interfaces: Array<string>;
+    schema: DocumentModelSchema;
+    fields_meta: DocumentFieldsMeta;
+    provider_merge_policy: {
+        group: Array<string>;
+    } | null;
+};
+/**
+ * Reads a document's `field_values` cell on the given transaction and
+ * delegates the merge-policy liveness comparison to `@kubun/mutation`'s pure
+ * `winnerStateDigestOf`. Returns the winning live `$setFetch` digest, the
+ * constant deleted-state digest when the delete side wins, or `null` when the
+ * document (or its fetch-order registers) is absent.
+ *
+ * Because graph and connector tables share one DB connection (the KubunDB
+ * coordinator), a caller with its own transaction over a wider `DB` type
+ * passes it here cast to `Kysely<GraphTables>` (the same pattern
+ * `addDocumentModel` above already relies on) so the read joins that
+ * transaction rather than opening a second connection.
+ */
+export declare function readWinnerStateDigest(tx: Kysely<GraphTables>, documentID: string): Promise<string | null>;
 /**
  * Persisted access rule shape as stored in `user_model_access_defaults`.
  */

package/lib/api.js

@@ -1,4 +1,5 @@
 import { DocumentID, DocumentModelID } from '@kubun/id';
+import { winnerStateDigestOf } from '@kubun/mutation';
 import { serializeCursor } from './cursor.js';
 import { isMissingTableError, ModelNotDeployedError } from './errors.js';
 import { aggregateFieldName, applyAggregateSelections, applyDocumentFilter, applyDocumentOrderBy, applyGroupBySelections, applyPagination, groupKeyAlias, knownFieldColumn } from './query-builder.js';
@@ -254,21 +255,22 @@ function compareGroups(a, b, orderBy) {
     }
     return 0;
 }
-function documentModelFromTable(row) {
+export function documentModelFromTable(row) {
     const model = {
         version: row.version,
         name: row.name,
         behavior: row.behavior,
         interfaces: row.interfaces,
         schema: row.schema,
-        fieldsMeta: row.fields_meta
+        fieldsMeta: row.fields_meta,
+        providerMergePolicy: row.provider_merge_policy ?? undefined
     };
     if (model.behavior === 'unique') {
         model.uniqueFields = row.unique_fields;
     }
     return model;
 }
-function documentModelToTable(adapter, id, model) {
+export function documentModelToTable(adapter, id, model) {
     return {
         id,
         version: model.version,
@@ -277,7 +279,8 @@ function documentModelToTable(adapter, id, model) {
         unique_fields: model.behavior === 'unique' ? adapter.encodeJSON(model.uniqueFields) : null,
         interfaces: adapter.encodeJSON(model.interfaces),
         schema: adapter.encodeJSON(model.schema),
-        fields_meta: adapter.encodeJSON(model.fieldsMeta)
+        fields_meta: adapter.encodeJSON(model.fieldsMeta),
+        provider_merge_policy: model.providerMergePolicy ? adapter.encodeJSON(model.providerMergePolicy) : null
     };
 }
 function documentNodeFromTable(adapter, doc) {
@@ -322,6 +325,29 @@ async function addDocumentModel(transaction, adapter, params) {
         document_model_id: id
     }).onConflict((oc)=>oc.doNothing()).execute();
 }
+// --- Cross-plan export: tx-scoped merge-policy winner read ---
+/**
+ * Reads a document's `field_values` cell on the given transaction and
+ * delegates the merge-policy liveness comparison to `@kubun/mutation`'s pure
+ * `winnerStateDigestOf`. Returns the winning live `$setFetch` digest, the
+ * constant deleted-state digest when the delete side wins, or `null` when the
+ * document (or its fetch-order registers) is absent.
+ *
+ * Because graph and connector tables share one DB connection (the KubunDB
+ * coordinator), a caller with its own transaction over a wider `DB` type
+ * passes it here cast to `Kysely<GraphTables>` (the same pattern
+ * `addDocumentModel` above already relies on) so the read joins that
+ * transaction rather than opening a second connection.
+ */ export async function readWinnerStateDigest(tx, documentID) {
+    const modelID = DocumentID.fromString(documentID).model.toString();
+    const row = await tx.selectFrom(`k_${modelID}`).select('field_values').where('id', '=', documentID).executeTakeFirst();
+    if (row?.field_values == null) {
+        return null;
+    }
+    // ParseJSONResultsPlugin may have already parsed the value.
+    const fieldValues = typeof row.field_values === 'string' ? JSON.parse(row.field_values) : row.field_values;
+    return winnerStateDigestOf(fieldValues);
+}
 // --- Factory function ---
 export function createGraphStore(db, adapter) {
     const coerce = adapter.coerceFilterValue.bind(adapter);
@@ -443,7 +469,9 @@ export function createGraphStore(db, adapter) {
                 id,
                 owner: params.owner,
                 model,
-                data: adapter.encodeJSON(params.data),
+                // Null data (a first-seen tombstone establishing a dead row) persists
+                // as SQL null, not the JSON string "null" — mirrors `saveDocument`.
+                data: params.data ? adapter.encodeJSON(params.data) : null,
                 unique: adapter.encodeBinary(params.unique)
             }).returningAll().executeTakeFirstOrThrow(()=>new Error(`createDocument failed to return row for ${id}`));
             if (params.data) {

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import type { StoreProvider } from '@kubun/db';
 import type { GraphStoreAPI } from './api.js';
 export type { GraphStoreAPI, StoredAccessDefaultRow, StoredAccessRule } from './api.js';
-export { createGraphStore } from './api.js';
+export { createGraphStore, readWinnerStateDigest } from './api.js';
 export { graphStoreDefinition } from './definition.js';
 export { ModelNotDeployedError } from './errors.js';
 export { resolveSearchableFields, SearchNotEnabledError } from './search.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { createGraphStore } from './api.js';
+export { createGraphStore, readWinnerStateDigest } from './api.js';
 export { graphStoreDefinition } from './definition.js';
 export { ModelNotDeployedError } from './errors.js';
 export { resolveSearchableFields, SearchNotEnabledError } from './search.js';

package/lib/migrations.js

@@ -16,7 +16,7 @@
     const init = {
         async up (db) {
             // Document models
-            await db.schema.createTable('kubun_graph_document_models').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('version', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('behavior', t.text, (col)=>col.notNull()).addColumn('unique_fields', t.json).addColumn('interfaces', t.json, (col)=>col.notNull()).addColumn('schema', t.json, (col)=>col.notNull()).addColumn('fields_meta', t.json, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            await db.schema.createTable('kubun_graph_document_models').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('version', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('behavior', t.text, (col)=>col.notNull()).addColumn('unique_fields', t.json).addColumn('interfaces', t.json, (col)=>col.notNull()).addColumn('schema', t.json, (col)=>col.notNull()).addColumn('fields_meta', t.json, (col)=>col.notNull()).addColumn('provider_merge_policy', t.json).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
             // Document model interfaces
             await db.schema.createTable('kubun_graph_document_model_interfaces').ifNotExists().addColumn('interface_id', t.text, (col)=>col.notNull().references('kubun_graph_document_models.id')).addColumn('implementation_id', t.text, (col)=>col.notNull().references('kubun_graph_document_models.id')).addUniqueConstraint('kubun_graph_document_model_interfaces_pkey', [
                 'interface_id',

package/lib/query-builder.js

@@ -75,7 +75,9 @@ function getOrderByFieldEntry(field) {
     const keys = [];
     let current = field;
     do {
-        const [key, value] = Object.entries(current)[0];
+        const entry = Object.entries(current)[0];
+        if (entry == null) break;
+        const [key, value] = entry;
         keys.push(key);
         if (typeof value === 'string') {
             return {
@@ -181,11 +183,15 @@ function buildKeysetPredicate(eb, orderBy, values, nullKeys, id, forward, coerce
     const idCmp = forward ? '>' : '<';
     const clauses = [];
     for(let level = 0; level < fields.length; level += 1){
+        const advanceField = fields[level];
+        if (advanceField == null) continue;
         const conjuncts = [];
         for(let prior = 0; prior < level; prior += 1){
-            conjuncts.push(equalTerm(eb, fields[prior]));
+            const priorField = fields[prior];
+            if (priorField == null) continue;
+            conjuncts.push(equalTerm(eb, priorField));
         }
-        conjuncts.push(advanceTerm(eb, fields[level]));
+        conjuncts.push(advanceTerm(eb, advanceField));
         clauses.push(eb.and(conjuncts));
     }
     const tieBreak = [];
@@ -232,10 +238,11 @@ function applyBackwardPagination(queryBuilder, limit, before, orderBy, coerce) {
 }
 export function applyDocumentFilter(eb, filter, adapter, path = [], coerce) {
     const entries = Object.entries(filter);
-    if (entries.length !== 1) {
+    const entry = entries[0];
+    if (entries.length !== 1 || entry == null) {
         throw new Error('Invalid document filter');
     }
-    const [type, value] = entries[0];
+    const [type, value] = entry;
     switch(type){
         case 'where':
             return applyObjectFilter(eb, value, adapter, path, coerce);
@@ -273,11 +280,12 @@ export function escapeLikePattern(value) {
 }
 export function applyValueFilter(eb, keys, filter, adapter, coerce) {
     const entries = Object.entries(filter);
-    if (entries.length !== 1) {
+    const entry = entries[0];
+    if (entries.length !== 1 || entry == null) {
         throw new Error('Invalid value filter');
     }
     const fieldName = getKeyPath(eb, keys);
-    const [type, value] = entries[0];
+    const [type, value] = entry;
     const c = coerce ?? ((v)=>v);
     switch(type){
         case 'isNull':
@@ -365,10 +373,11 @@ export function knownFieldColumn(keys) {
 }
 function applyOrderByField(query, adapter, orderBy, isReverse, path = []) {
     const entries = Object.entries(orderBy);
-    if (entries.length !== 1) {
+    const entry = entries[0];
+    if (entries.length !== 1 || entry == null) {
         throw new Error('Invalid order by field');
     }
-    const [key, value] = entries[0];
+    const [key, value] = entry;
     const keys = [
         ...path,
         key

package/lib/tables.d.ts

@@ -27,6 +27,9 @@ export type DocumentModelTable = {
     interfaces: JSONValueColumn<Array<string>>;
     schema: JSONValueColumn<DocumentModelSchema>;
     fields_meta: JSONValueColumn<DocumentFieldsMeta>;
+    provider_merge_policy: JSONValueColumn<{
+        group: Array<string>;
+    }> | null;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-graph",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,16 +15,17 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db": "^0.16.0",
-    "@kubun/db-adapter": "^0.16.0",
-    "@kubun/id": "^0.16.0",
-    "@kubun/protocol": "^0.16.0",
+    "@kubun/db": "^0.17.0",
+    "@kubun/db-adapter": "^0.17.0",
+    "@kubun/id": "^0.17.0",
+    "@kubun/mutation": "^0.17.1",
+    "@kubun/protocol": "^0.17.1",
     "@sozai/codec": "^0.4.0",
-    "kysely": "^0.29.5"
+    "kysely": "^0.29.6"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.16.0",
-    "@kubun/db-postgres": "^0.16.0",
+    "@kubun/db-better-sqlite": "^0.17.0",
+    "@kubun/db-postgres": "^0.17.1",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {
@@ -33,8 +34,8 @@
   "scripts": {
     "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
-    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:js": "del 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
     "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",