@kubun/graphql 0.17.1 → 0.17.2

package/lib/context.d.ts

@@ -216,6 +216,13 @@ export type SetMutationParams = {
      * viewer) owns. Omitted means owner = signer (the ops-level owner).
      */
     owner?: string;
+    /**
+     * Fetch-order token for a merge-policy-aware SET, forwarded to the engine's
+     * outcome-bearing seam. A model that declares a `providerMergePolicy` rejects
+     * a tokenless write; ordinary models ignore it. Optional, so non-connector
+     * callers stay source-compatible.
+     */
+    sourceFetchHLC?: string;
 };
 export type UpdateMutationParams = {
     input: UpdateMutationInput;
@@ -249,6 +256,19 @@ export type SetDocumentAccessOverrideParams = {
 export type MutationContext = {
     executeCreateMutation(params: CreateMutationParams): Promise<DocumentNode>;
     executeSetMutation(params: SetMutationParams): Promise<DocumentNode>;
+    /**
+     * Outcome-bearing SET, present only on the engine's signing context. The
+     * client and service graph contexts do not implement it, so a consumer that
+     * needs the merge outcome asserts presence with a runtime null check and
+     * fails closed (throws) when it is absent, rather than mis-committing through
+     * the plain SET seam. `document` is null when a gate dropped the projection.
+     */
+    executeSetMutationWithOutcome?(params: SetMutationParams): Promise<{
+        document: DocumentNode | null;
+        outcome?: 'applied' | 'dominated' | 'nonconforming';
+        candidateDigest?: string;
+        winnerDigest?: string;
+    }>;
     executeUpdateMutation(params: UpdateMutationParams): Promise<DocumentNode>;
     executeRemoveMutation(params: RemoveMutationParams): Promise<void>;
     executeSetModelAccessDefaults(params: SetModelAccessDefaultsParams): Promise<ModelAccessDefaults>;

package/lib/schema.d.ts

@@ -94,6 +94,7 @@ export declare class SchemaBuilder {
     _relationsTo: Record<string, RelationFields>;
     _extensionSDL: string | undefined;
     _extensionResolvers: ExtensionResolvers | undefined;
+    _skippedTypeExtensions: Set<string>;
     _stubExtensionResolvers: boolean;
     _pluginNodeResolvers: Record<string, {
         resolve: (localID: string, ctx: Context) => Promise<unknown> | unknown;

package/lib/schema.js

@@ -35,6 +35,8 @@ import { getUniqueDocValue, validateAccessIdentifiers } from './utils.js';
     // Object types: return empty object — sub-fields use their own stub resolvers
     return {};
 }
+// Marks an extension of a model type that applies only when the graph has it.
+const IF_TYPE_EXISTS = 'ifTypeExists';
 const STRING_FORMATS = {
     date: GraphQLString,
     time: GraphQLString,
@@ -388,6 +390,9 @@ export class SchemaBuilder {
     _relationsTo = {};
     _extensionSDL;
     _extensionResolvers;
+    // Types whose `@ifTypeExists` extension was left out: their `typeFields`
+    // are skipped rather than rejected.
+    _skippedTypeExtensions = new Set();
     _stubExtensionResolvers;
     _pluginNodeResolvers = {};
     _subscriptions = {};
@@ -968,10 +973,14 @@ export class SchemaBuilder {
         // Apply SDL extensions
         if (this._extensionSDL != null) {
             const typesBefore = new Set(Object.keys(schema.getTypeMap()));
-            schema = extendSchema(schema, parseGraphQL(this._extensionSDL));
+            const fieldsBefore = new Map();
+            for (const [typeName, type] of Object.entries(schema.getTypeMap())){
+                if (isObjectType(type)) fieldsBefore.set(typeName, new Set(Object.keys(type.getFields())));
+            }
+            schema = extendSchema(schema, this.#applicableExtensions(schema, this._extensionSDL));
             // Stub extension resolvers for client-side pre-execution
             if (this._stubExtensionResolvers) {
-                this.#stubExtensionFields(schema, typesBefore);
+                this.#stubExtensionFields(schema, typesBefore, fieldsBefore);
             }
         }
         // Attach resolvers to extended fields
@@ -980,6 +989,35 @@ export class SchemaBuilder {
         }
         return schema;
     }
+    /**
+   * The extension SDL to apply. `extend type T @ifTypeExists { ... }` extends
+   * `T` only when the schema built from the models has it — a plugin can add
+   * fields to model types a graph may or may not include — and is otherwise
+   * left out, along with the `typeFields` given for `T`. The directive is a
+   * build instruction only and never reaches the schema.
+   */ #applicableExtensions(schema, sdl) {
+        const document = parseGraphQL(sdl);
+        const definitions = [];
+        for (const definition of document.definitions){
+            const conditional = definition.kind === Kind.OBJECT_TYPE_EXTENSION && definition.directives?.some((directive)=>directive.name.value === IF_TYPE_EXISTS);
+            if (!conditional) {
+                definitions.push(definition);
+                continue;
+            }
+            if (schema.getType(definition.name.value) == null) {
+                this._skippedTypeExtensions.add(definition.name.value);
+                continue;
+            }
+            definitions.push({
+                ...definition,
+                directives: definition.directives?.filter((directive)=>directive.name.value !== IF_TYPE_EXISTS)
+            });
+        }
+        return {
+            ...document,
+            definitions
+        };
+    }
     #attachExtensionResolvers(schema, resolvers) {
         const queryType = schema.getQueryType();
         if (queryType != null && resolvers.queryFields != null) {
@@ -1014,6 +1052,7 @@ export class SchemaBuilder {
         }
         if (resolvers.typeFields != null) {
             for (const [typeName, fieldResolvers] of Object.entries(resolvers.typeFields)){
+                if (this._skippedTypeExtensions.has(typeName)) continue;
                 const type = schema.getType(typeName);
                 if (type == null) {
                     throw new Error(`Extension resolver references type "${typeName}" which does not exist in the schema`);
@@ -1036,7 +1075,7 @@ export class SchemaBuilder {
             }
         }
     }
-    #stubExtensionFields(schema, typesBefore) {
+    #stubExtensionFields(schema, typesBefore, fieldsBefore) {
         // Stub root Query/Mutation fields added by extension SDL
         for (const rootType of [
             schema.getQueryType(),
@@ -1050,15 +1089,22 @@ export class SchemaBuilder {
                 }
             }
         }
-        // Stub fields on types added by extension SDL
+        // Stub fields on types added by extension SDL, and fields an extension
+        // added to an existing type
         for (const [typeName, type] of Object.entries(schema.getTypeMap())){
-            if (typesBefore.has(typeName)) continue;
             if (!isObjectType(type)) continue;
+            const existing = typesBefore.has(typeName) ? fieldsBefore.get(typeName) ?? null : null;
+            if (typesBefore.has(typeName) && existing == null) continue;
             const fields = type.getFields();
             for (const field of Object.values(fields)){
+                if (existing?.has(field.name) === true) continue;
                 if (field.resolve == null) {
                     const fieldType = field.type;
-                    field.resolve = (source)=>source[field.name] ?? createDefaultValue(fieldType);
+                    // A nullable field added to an existing type (a model's) stubs as
+                    // null: a made-up value, such as an enum's first member, would read
+                    // as a real one.
+                    const stubsNull = existing != null && !isNonNullType(fieldType);
+                    field.resolve = (source)=>source[field.name] ?? (stubsNull ? null : createDefaultValue(fieldType));
                 }
             }
         }
@@ -1162,12 +1208,15 @@ export class SchemaBuilder {
         }, (node)=>{
             if (typeof node === 'string') return 'AccountNode';
             if (node instanceof AttachmentID) return 'AttachmentNode';
-            if (node != null && typeof node === 'object' && 'model' in node) {
-                return this._aliases[node.model];
-            }
+            // An explicit type (set on a plugin node above) wins over the document
+            // heuristic, so a plugin node whose source has a `model` key is not
+            // taken for a document.
             if (node != null && typeof node === 'object' && '__typename' in node) {
                 return node.__typename;
             }
+            if (node != null && typeof node === 'object' && 'model' in node) {
+                return this._aliases[node.model];
+            }
             throw new Error('Unknown node type');
         });
         const accountObject = new GraphQLObjectType({

package/lib/types.d.ts

@@ -1,30 +1,6 @@
-import type { DocumentData, DocumentFilter, DocumentOrderBy } from '@kubun/protocol';
+import type { DocumentData, DocumentFilter, DocumentOrderBy, PatchOperation } from '@kubun/protocol';
 import type { ConnectionArguments } from './relay.js';
-export type PatchAddOperation = {
-    op: 'add';
-    path: string;
-    value: unknown;
-};
-export type PatchRemoveOperation = {
-    op: 'remove';
-    path: string;
-};
-export type PatchReplaceOperation = {
-    op: 'replace';
-    path: string;
-    value: unknown;
-};
-export type PatchMoveOperation = {
-    op: 'move';
-    from: string;
-    path: string;
-};
-export type PatchCopyOperation = {
-    op: 'copy';
-    from: string;
-    path: string;
-};
-export type PatchOperation = PatchAddOperation | PatchCopyOperation | PatchMoveOperation | PatchRemoveOperation | PatchReplaceOperation;
+export type { PatchAddOperation, PatchCopyOperation, PatchMoveOperation, PatchOperation, PatchRemoveOperation, PatchReplaceOperation, } from '@kubun/protocol';
 export type AllConnectionArguments = ConnectionArguments & {
     filter?: DocumentFilter;
     orderBy?: DocumentOrderBy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/graphql",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -18,7 +18,7 @@
     "@kubun/hlc": "^0.17.0",
     "@kubun/id": "^0.17.0",
     "@kubun/logger": "^0.17.0",
-    "@kubun/protocol": "^0.17.0",
+    "@kubun/protocol": "^0.17.1",
     "@sozai/async": "^0.2.1",
     "@sozai/codec": "^0.4.0",
     "@sozai/event": "^0.1.3",
@@ -34,7 +34,7 @@
     "@kubun/db": "^0.17.0",
     "@kubun/db-better-sqlite": "^0.17.0",
     "@kubun/scalars": "^0.17.0",
-    "@kubun/store-graph": "^0.17.0",
+    "@kubun/store-graph": "^0.17.1",
     "@kubun/test-utils": "^0.0.0"
   },
   "publishConfig": {