@kubun/graphql 0.17.0 → 0.17.2

package/lib/context.d.ts

@@ -3,7 +3,7 @@ import type { AggregateHaving, AggregateSpec, AggregateValues, DocumentData, Doc
 import type { SearchDocumentResult, SearchDocumentsParams, StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
 import type { Tracer } from '@sozai/otel';
 import type { GraphQLResolveInfo } from 'graphql';
-import type { Connection, Edge } from 'graphql-relay';
+import type { Connection, Edge } from './relay.js';
 import type { AllConnectionArguments, ModelAccessDefaults, UpdateMutationInput } from './types.js';
 /**
  * Event data for document save notifications used by subscriptions.
@@ -90,7 +90,7 @@ export type AggregateScope = {
 };
 /**
  * Connection value returned by {@link QueryContext.resolveConnection}. Extends
- * the graphql-relay connection (edges/pageInfo are untouched) with the query
+ * the Relay connection (edges/pageInfo are untouched) with the query
  * scope so the `aggregates` field can resolve consistently with the page.
  */
 export type ScopedConnection = Connection<DocumentNode> & {
@@ -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/relay.d.ts

@@ -0,0 +1,93 @@
+import { type GraphQLFieldConfig, type GraphQLFieldConfigArgumentMap, type GraphQLFieldExtensions, type GraphQLFieldResolver, type GraphQLInputFieldConfig, GraphQLInterfaceType, type GraphQLNamedOutputType, GraphQLNonNull, GraphQLObjectType, type GraphQLResolveInfo, type GraphQLTypeResolver, type ThunkObjMap } from 'graphql';
+/**
+ * Internal reimplementation of the small slice of `graphql-relay` this package
+ * uses (connection args/types, `Node` interface, and Relay-style mutations).
+ * The emitted GraphQL types are byte-identical to `graphql-relay@0.10`, which
+ * the schema snapshot tests verify.
+ */
+/** A type alias for cursors in this implementation. */
+export type ConnectionCursor = string;
+/** A type describing the arguments a connection field receives in GraphQL. */
+export type ConnectionArguments = {
+    before?: ConnectionCursor | null;
+    after?: ConnectionCursor | null;
+    first?: number | null;
+    last?: number | null;
+};
+/** A type designed to be exposed as a `Connection` over GraphQL. */
+export type Connection<T> = {
+    edges: Array<Edge<T>>;
+    pageInfo: PageInfo;
+};
+/** A type designed to be exposed as an `Edge` over GraphQL. */
+export type Edge<T> = {
+    node: T;
+    cursor: ConnectionCursor;
+};
+/** A type designed to be exposed as `PageInfo` over GraphQL. */
+export type PageInfo = {
+    startCursor: ConnectionCursor | null;
+    endCursor: ConnectionCursor | null;
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+};
+/**
+ * Args to include on a field whose return type is a connection type with
+ * forward pagination.
+ */
+export declare const forwardConnectionArgs: GraphQLFieldConfigArgumentMap;
+/**
+ * Args to include on a field whose return type is a connection type with
+ * backward pagination.
+ */
+export declare const backwardConnectionArgs: GraphQLFieldConfigArgumentMap;
+/**
+ * Args to include on a field whose return type is a connection type with
+ * bidirectional pagination.
+ */
+export declare const connectionArgs: GraphQLFieldConfigArgumentMap;
+export type ConnectionConfig = {
+    name?: string;
+    nodeType: GraphQLNamedOutputType | GraphQLNonNull<GraphQLNamedOutputType>;
+    resolveNode?: GraphQLFieldResolver<any, any>;
+    resolveCursor?: GraphQLFieldResolver<any, any>;
+    edgeFields?: ThunkObjMap<GraphQLFieldConfig<any, any>>;
+    connectionFields?: ThunkObjMap<GraphQLFieldConfig<any, any>>;
+};
+export type GraphQLConnectionDefinitions = {
+    edgeType: GraphQLObjectType;
+    connectionType: GraphQLObjectType;
+};
+/**
+ * Returns a GraphQLObjectType for a connection with the given name, and whose
+ * nodes are of the specified type.
+ */
+export declare function connectionDefinitions(config: ConnectionConfig): GraphQLConnectionDefinitions;
+export type GraphQLNodeDefinitions<TContext> = {
+    nodeInterface: GraphQLInterfaceType;
+    nodeField: GraphQLFieldConfig<unknown, TContext>;
+    nodesField: GraphQLFieldConfig<unknown, TContext>;
+};
+/**
+ * Given a function to map from an ID to an underlying object, and a function to
+ * map from an underlying object to its concrete GraphQLObjectType, constructs a
+ * `Node` interface plus `node`/`nodes` root field configs.
+ */
+export declare function nodeDefinitions<TContext>(fetchById: (id: string, context: TContext, info: GraphQLResolveInfo) => unknown, typeResolver?: GraphQLTypeResolver<unknown, TContext>): GraphQLNodeDefinitions<TContext>;
+type MutationFn<TInput, TOutput, TContext> = (object: TInput, ctx: TContext, info: GraphQLResolveInfo) => TOutput;
+export type MutationConfig<TInput = any, TOutput = unknown, TContext = unknown> = {
+    name: string;
+    description?: string;
+    deprecationReason?: string;
+    extensions?: GraphQLFieldExtensions<unknown, unknown>;
+    inputFields: ThunkObjMap<GraphQLInputFieldConfig>;
+    outputFields: ThunkObjMap<GraphQLFieldConfig<TOutput, TContext>>;
+    mutateAndGetPayload: MutationFn<TInput, Promise<TOutput> | TOutput, TContext>;
+};
+/**
+ * Returns a GraphQLFieldConfig for the mutation described by the provided
+ * config, wiring the Relay `clientMutationId` round-trip through a generated
+ * `${name}Input`/`${name}Payload` pair.
+ */
+export declare function mutationWithClientMutationId<TInput = any, TOutput = unknown, TContext = unknown>(config: MutationConfig<TInput, TOutput, TContext>): GraphQLFieldConfig<unknown, TContext>;
+export {};

package/lib/relay.js

@@ -0,0 +1,197 @@
+import { GraphQLBoolean, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLString, getNamedType, resolveObjMapThunk } from 'graphql';
+/**
+ * Args to include on a field whose return type is a connection type with
+ * forward pagination.
+ */ export const forwardConnectionArgs = Object.freeze({
+    after: {
+        type: GraphQLString,
+        description: 'Returns the items in the list that come after the specified cursor.'
+    },
+    first: {
+        type: GraphQLInt,
+        description: 'Returns the first n items from the list.'
+    }
+});
+/**
+ * Args to include on a field whose return type is a connection type with
+ * backward pagination.
+ */ export const backwardConnectionArgs = Object.freeze({
+    before: {
+        type: GraphQLString,
+        description: 'Returns the items in the list that come before the specified cursor.'
+    },
+    last: {
+        type: GraphQLInt,
+        description: 'Returns the last n items from the list.'
+    }
+});
+/**
+ * Args to include on a field whose return type is a connection type with
+ * bidirectional pagination.
+ */ export const connectionArgs = {
+    ...forwardConnectionArgs,
+    ...backwardConnectionArgs
+};
+/** The common page info type shared by every connection. */ const pageInfoType = new GraphQLObjectType({
+    name: 'PageInfo',
+    description: 'Information about pagination in a connection.',
+    fields: ()=>({
+            hasNextPage: {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                description: 'When paginating forwards, are there more items?'
+            },
+            hasPreviousPage: {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                description: 'When paginating backwards, are there more items?'
+            },
+            startCursor: {
+                type: GraphQLString,
+                description: 'When paginating backwards, the cursor to continue.'
+            },
+            endCursor: {
+                type: GraphQLString,
+                description: 'When paginating forwards, the cursor to continue.'
+            }
+        })
+});
+/**
+ * Returns a GraphQLObjectType for a connection with the given name, and whose
+ * nodes are of the specified type.
+ */ export function connectionDefinitions(config) {
+    const { nodeType } = config;
+    const name = config.name ?? getNamedType(nodeType).name;
+    const edgeType = new GraphQLObjectType({
+        name: `${name}Edge`,
+        description: 'An edge in a connection.',
+        fields: ()=>({
+                node: {
+                    type: nodeType,
+                    resolve: config.resolveNode,
+                    description: 'The item at the end of the edge'
+                },
+                cursor: {
+                    type: new GraphQLNonNull(GraphQLString),
+                    resolve: config.resolveCursor,
+                    description: 'A cursor for use in pagination'
+                },
+                ...resolveObjMapThunk(config.edgeFields ?? {})
+            })
+    });
+    const connectionType = new GraphQLObjectType({
+        name: `${name}Connection`,
+        description: 'A connection to a list of items.',
+        fields: ()=>({
+                pageInfo: {
+                    type: new GraphQLNonNull(pageInfoType),
+                    description: 'Information to aid in pagination.'
+                },
+                edges: {
+                    type: new GraphQLList(edgeType),
+                    description: 'A list of edges.'
+                },
+                ...resolveObjMapThunk(config.connectionFields ?? {})
+            })
+    });
+    return {
+        edgeType,
+        connectionType
+    };
+}
+/**
+ * Given a function to map from an ID to an underlying object, and a function to
+ * map from an underlying object to its concrete GraphQLObjectType, constructs a
+ * `Node` interface plus `node`/`nodes` root field configs.
+ */ export function nodeDefinitions(fetchById, typeResolver) {
+    const nodeInterface = new GraphQLInterfaceType({
+        name: 'Node',
+        description: 'An object with an ID',
+        fields: ()=>({
+                id: {
+                    type: new GraphQLNonNull(GraphQLID),
+                    description: 'The id of the object.'
+                }
+            }),
+        resolveType: typeResolver
+    });
+    const nodeField = {
+        description: 'Fetches an object given its ID',
+        type: nodeInterface,
+        args: {
+            id: {
+                type: new GraphQLNonNull(GraphQLID),
+                description: 'The ID of an object'
+            }
+        },
+        resolve: (_obj, { id }, context, info)=>fetchById(id, context, info)
+    };
+    const nodesField = {
+        description: 'Fetches objects given their IDs',
+        type: new GraphQLNonNull(new GraphQLList(nodeInterface)),
+        args: {
+            ids: {
+                type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLID))),
+                description: 'The IDs of objects'
+            }
+        },
+        resolve: (_obj, { ids }, context, info)=>ids.map((id)=>fetchById(id, context, info))
+    };
+    return {
+        nodeInterface,
+        nodeField,
+        nodesField
+    };
+}
+function isPromiseLike(value) {
+    return typeof value?.then === 'function';
+}
+/**
+ * Returns a GraphQLFieldConfig for the mutation described by the provided
+ * config, wiring the Relay `clientMutationId` round-trip through a generated
+ * `${name}Input`/`${name}Payload` pair.
+ */ export function mutationWithClientMutationId(config) {
+    const { name, inputFields, outputFields, mutateAndGetPayload } = config;
+    const outputType = new GraphQLObjectType({
+        name: `${name}Payload`,
+        fields: ()=>({
+                ...resolveObjMapThunk(outputFields),
+                clientMutationId: {
+                    type: GraphQLString
+                }
+            })
+    });
+    const inputType = new GraphQLInputObjectType({
+        name: `${name}Input`,
+        fields: ()=>({
+                ...resolveObjMapThunk(inputFields),
+                clientMutationId: {
+                    type: GraphQLString
+                }
+            })
+    });
+    return {
+        type: outputType,
+        description: config.description,
+        deprecationReason: config.deprecationReason,
+        extensions: config.extensions,
+        args: {
+            input: {
+                type: new GraphQLNonNull(inputType)
+            }
+        },
+        resolve: (_source, { input }, context, info)=>{
+            const { clientMutationId } = input;
+            const injectClientMutationId = (data)=>{
+                if (typeof data === 'object' && data !== null) {
+                    ;
+                    data.clientMutationId = clientMutationId;
+                }
+                return data;
+            };
+            const payload = mutateAndGetPayload(input, context, info);
+            if (isPromiseLike(payload)) {
+                return payload.then((value)=>injectClientMutationId(value));
+            }
+            return injectClientMutationId(payload);
+        }
+    };
+}

package/lib/schema.d.ts

@@ -1,11 +1,11 @@
 import { AttachmentID, DocumentModelID } from '@kubun/id';
 import type { AggregateHaving, AggregateSpec, ArrayModel, DocumentData, DocumentModel, DocumentModelSchema, DocumentModelsRecord, DocumentNode, GroupedAggregateOrderTerm, ObjectModel, OrderByDirection as OrderByDirectionValue, ReferencesRecordModel, ScalarModel, StringCustomModel, StringEnumModel, StringFormatModel, StringModel, TypeModel } from '@kubun/protocol';
-import { type FieldNode, GraphQLEnumType, type GraphQLFieldConfig, type GraphQLFieldConfigMap, type GraphQLFieldResolver, GraphQLInputObjectType, type GraphQLInputType, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, type GraphQLOutputType, type GraphQLResolveInfo, type GraphQLScalarType, GraphQLSchema, type SelectionNode } from 'graphql';
+import { type FieldNode, GraphQLEnumType, type GraphQLFieldConfig, type GraphQLFieldConfigMap, type GraphQLFieldResolver, GraphQLInputObjectType, type GraphQLInputType, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, type GraphQLNullableInputType, type GraphQLNullableOutputType, GraphQLObjectType, type GraphQLOutputType, type GraphQLResolveInfo, type GraphQLScalarType, GraphQLSchema, type SelectionNode } from 'graphql';
 import type { Context } from './context.js';
 export declare function toDocumentModelID(id: DocumentModelID | string): DocumentModelID;
 export declare function getGlobalID(id: DocumentModelID | string, globalID: DocumentModelID | string): DocumentModelID;
-export declare function toList(type: GraphQLInputType): GraphQLList<GraphQLNonNull<GraphQLInputType>>;
-export declare function toOuputList(type: GraphQLOutputType): GraphQLList<GraphQLNonNull<GraphQLOutputType>>;
+export declare function toList(type: GraphQLNullableInputType): GraphQLList<GraphQLNonNull<GraphQLNullableInputType>>;
+export declare function toOuputList(type: GraphQLNullableOutputType): GraphQLList<GraphQLNonNull<GraphQLNullableOutputType>>;
 export declare const PatchOperation: GraphQLInputObjectType;
 export type GraphQLNodeDefinitions = {
     nodeInterface: GraphQLInterfaceType;
@@ -94,23 +94,24 @@ 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;
     }>;
     _subscriptions: GraphQLFieldConfigMap<unknown, Context>;
-    _types: Record<string, GraphQLOutputType>;
+    _types: Record<string, GraphQLNullableOutputType>;
     constructor(params: SchemaBuilderParams);
     _resolveModelIdentifier(identifier: string): string;
     _resolveModelIDsToInclude(): Set<string>;
     getModelIDs(id: string | null): Array<string>;
     build(): GraphQLSchema;
     _getDefinitions(): SharedDefinitions;
-    _getReference(path: string, parentName?: string): GraphQLOutputType;
+    _getReference(path: string, parentName?: string): GraphQLNullableOutputType;
     _getReferenceSchema(id: string): TypeModel;
     _getInputObject(key: string): GraphQLInputObjectType;
     _getType(key: string): GraphQLOutputType;
-    _getReferenceInput(path: string, isPartial: boolean, parentName?: string): GraphQLInputType;
+    _getReferenceInput(path: string, isPartial: boolean, parentName?: string): GraphQLNullableInputType;
     _buildSharedDefinitions(): SharedDefinitions;
     _buildDocument(id: string): GraphQLObjectType<DocumentNode, Context> | GraphQLInterfaceType;
     /**
@@ -191,9 +192,9 @@ export declare class SchemaBuilder {
     _buildObjectFilterInput(id: string, schema: DocumentModelSchema | ObjectModel, parentName?: string, isDocument?: boolean): GraphQLInputObjectType;
     _buildObjectOrderByInput(id: string, schema: DocumentModelSchema | ObjectModel, parentName?: string, isDocument?: boolean): GraphQLInputObjectType;
     _buildSetInputObjectType(id: string, withFields: Array<string>, relationField?: string): GraphQLInputObjectType;
-    _buildReference(id: string, schema: TypeModel, parentName?: string): GraphQLOutputType;
+    _buildReference(id: string, schema: TypeModel, parentName?: string): GraphQLNullableOutputType;
     _buildScalar(id: string, schema: ScalarModel, parentName?: string): GraphQLScalarType;
-    _buildArray(schema: ArrayModel, parentName?: string): GraphQLList<GraphQLNonNull<GraphQLOutputType>>;
+    _buildArray(schema: ArrayModel, parentName?: string): GraphQLList<GraphQLNonNull<GraphQLNullableOutputType>>;
     _buildObject(id: string, schema: ObjectModel, parentName?: string): GraphQLObjectType;
     _buildObjectFields(id: string, schema: DocumentModelSchema | ObjectModel, parentName?: string): GraphQLFieldConfigMap<Record<string, unknown>, Context>;
     _buildNestedAttachmentField(key: string, fieldRef: string): GraphQLFieldConfig<Record<string, unknown>, Context> | null;

package/lib/schema.js

@@ -2,9 +2,9 @@ import { AttachmentID, DocumentID, DocumentModelID, decodeID, PluginNodeID } fro
 import { REFERENCE_PREFIX } from '@kubun/protocol';
 import { pascalCase } from 'change-case';
 import { extendSchema, GraphQLBoolean, GraphQLEnumType, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, isEnumType, isListType, isNonNullType, isObjectType, isScalarType, Kind, parse as parseGraphQL } from 'graphql';
-import { connectionArgs, connectionDefinitions, mutationWithClientMutationId, nodeDefinitions } from 'graphql-relay';
 import { GraphQLDateTimeISO, GraphQLDID, GraphQLDuration, GraphQLEmailAddress, GraphQLJSON, GraphQLJSONObject } from 'graphql-scalars';
 import { GraphQLAttachmentID, GraphQLCredentialEntryID, GraphQLDocID } from './identifiers.js';
+import { connectionArgs, connectionDefinitions, mutationWithClientMutationId, nodeDefinitions } from './relay.js';
 import { GraphQLURL } from './scalars.js';
 import { decodeSearchCursor, encodeSearchCursor } from './search-cursor.js';
 import { getUniqueDocValue, validateAccessIdentifiers } from './utils.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 = {};
@@ -561,7 +566,7 @@ export class SchemaBuilder {
             };
         }
         // Add top-level search query across all models
-        // Get the PageInfo type from an existing connection (shared by graphql-relay)
+        // Get the PageInfo type from an existing connection (shared across all connections)
         const firstModelID = [
             ...this._includedModelIDs
         ][0];
@@ -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 { ConnectionArguments } from 'graphql-relay';
-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;
+import type { DocumentData, DocumentFilter, DocumentOrderBy, PatchOperation } from '@kubun/protocol';
+import type { ConnectionArguments } from './relay.js';
+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.0",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -18,14 +18,13 @@
     "@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",
     "@sozai/otel": "^0.3.2",
     "change-case": "^5.4.4",
-    "graphql": "^16.14.2",
-    "graphql-relay": "^0.10.2",
+    "graphql": "^17.0.2",
     "graphql-scalars": "^2.0.0",
     "multiformats": "^14.0.5"
   },
@@ -35,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": {