@edium/halifax 2.2.3 → 2.4.0

package/dist/graphql/schema.js

@@ -0,0 +1,635 @@
+import { GraphQLSchema, GraphQLObjectType, GraphQLInputObjectType, GraphQLEnumType, GraphQLList, GraphQLNonNull, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLID, GraphQLError } from 'graphql';
+import { GraphQLJSON } from './scalars.js';
+import { defaultCrudPermissions, DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '../core/types.js';
+import { SqlOrder } from '@edium/halifax-types';
+import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, makeReadableFieldFilter, parseId } from '../core/handlerUtils.js';
+import { validateAdvancedQuery, validateIncludes } from '../core/validation.js';
+import { NotFoundError } from '../errors/NotFoundError.js';
+import { NotImplementedError } from '../errors/NotImplementedError.js';
+import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
+import { HttpError } from '../errors/HttpError.js';
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function toPascalCase(str) {
+    return str
+        .split(/[-_/\s]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+}
+const httpStatusToGqlCode = {
+    400: 'BAD_REQUEST',
+    401: 'UNAUTHORIZED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    409: 'CONFLICT',
+    415: 'UNSUPPORTED_MEDIA_TYPE',
+    422: 'UNPROCESSABLE_ENTITY',
+    500: 'INTERNAL_ERROR',
+    501: 'NOT_IMPLEMENTED'
+};
+function toGraphQLError(error) {
+    if (error instanceof GraphQLError)
+        throw error;
+    if (error instanceof HttpError) {
+        throw new GraphQLError(error.message, {
+            extensions: {
+                code: httpStatusToGqlCode[error.status] ?? 'INTERNAL_ERROR',
+                status: error.status,
+                ...(error.details !== undefined ? { details: error.details } : {})
+            }
+        });
+    }
+    throw new GraphQLError('Internal server error', {
+        extensions: { code: 'INTERNAL_ERROR', status: 500 }
+    });
+}
+function fieldTypeToOutputGQL(type, isId) {
+    if (isId)
+        return GraphQLID;
+    switch (type) {
+        case 'integer':
+            return GraphQLInt;
+        case 'number':
+            return GraphQLFloat;
+        case 'boolean':
+            return GraphQLBoolean;
+        case 'object':
+            return GraphQLJSON;
+        case 'string':
+        default:
+            return GraphQLString;
+    }
+}
+function fieldTypeToInputGQL(type, isId) {
+    if (isId)
+        return GraphQLID;
+    switch (type) {
+        case 'integer':
+            return GraphQLInt;
+        case 'number':
+            return GraphQLFloat;
+        case 'boolean':
+            return GraphQLBoolean;
+        case 'object':
+            return GraphQLJSON;
+        case 'string':
+        default:
+            return GraphQLString;
+    }
+}
+function applyPageLimits(resource, requestedLimit) {
+    let limit = requestedLimit;
+    const cap = resource.maxLimit ?? MAX_PAGE_LIMIT;
+    if (limit === undefined) {
+        const fallback = resource.defaultLimit ?? DEFAULT_PAGE_LIMIT;
+        if (fallback !== 0)
+            limit = fallback;
+    }
+    if (cap !== 0 && (limit === undefined || limit > cap))
+        limit = cap;
+    return limit;
+}
+// ─── Shared singleton types (built once, reused across all resources) ─────────
+const SortDirectionEnum = new GraphQLEnumType({
+    name: 'SortDirection',
+    description: 'Sort direction for orderBy arguments.',
+    values: {
+        asc: { value: 'asc', description: 'Ascending order.' },
+        desc: { value: 'desc', description: 'Descending order.' }
+    }
+});
+const OrderByInput = new GraphQLInputObjectType({
+    name: 'OrderByInput',
+    description: 'A sort expression pairing a field name with a direction.',
+    fields: {
+        field: { type: new GraphQLNonNull(GraphQLString), description: 'Field name to sort by.' },
+        direction: { type: new GraphQLNonNull(SortDirectionEnum), description: 'Sort direction.' }
+    }
+});
+// Recursive input — must use a thunk to satisfy GraphQL's circular-ref requirement.
+const QueryFilterInput = new GraphQLInputObjectType({
+    name: 'QueryFilterInput',
+    description: 'A single filter condition (leaf) or a group of nested conditions. ' +
+        'Leaf: set field, comparison, and value1. ' +
+        'Group: set operator and children.',
+    fields: () => ({
+        field: { type: GraphQLString, description: 'Field name to filter on (leaf nodes only).' },
+        comparison: {
+            type: GraphQLString,
+            description: 'Comparison operator: =, <>, <, >, <=, >=, IN, NOT IN, BETWEEN, NOT BETWEEN, ' +
+                'LIKE, NOT LIKE, IS NULL, IS NOT NULL, CONTAINS, STARTS WITH, ENDS WITH.'
+        },
+        value1: {
+            type: GraphQLJSON,
+            description: 'Primary filter value (scalar or array for IN/BETWEEN operators).'
+        },
+        value2: {
+            type: GraphQLJSON,
+            description: 'Secondary value for BETWEEN / NOT BETWEEN operators.'
+        },
+        operator: {
+            type: GraphQLString,
+            description: 'Logical combinator for the flat where array: AND or OR. Required on all but the last element.'
+        },
+        children: {
+            type: new GraphQLList(QueryFilterInput),
+            description: 'Nested filter conditions combined with the operator.'
+        }
+    })
+});
+// ─── Main schema builder ──────────────────────────────────────────────────────
+export function buildGraphQLSchema(contexts) {
+    const queryFields = {};
+    const mutationFields = {};
+    for (const { resource, authStrategy, hooks, resolveRepo } of contexts) {
+        if (resource.graphql === false)
+            continue;
+        const permissions = { ...defaultCrudPermissions, ...resource.permissions };
+        const idField = resource.repository?.idField ?? 'id';
+        const typeName = toPascalCase(resource.routePrefix);
+        const allFields = resource.fields ?? [];
+        const selectableFields = allFields.filter((f) => f.selectable !== false);
+        const writableFields = allFields.filter((f) => f.name !== idField && f.writable !== false);
+        const filterableFields = allFields.filter((f) => f.filterable !== false);
+        // ─── Per-resource GraphQL types ─────────────────────────────────────────
+        const OutputType = new GraphQLObjectType({
+            name: typeName,
+            description: `A ${resource.name ?? typeName} record.`,
+            fields: () => {
+                const gqlFields = {};
+                for (const f of selectableFields) {
+                    gqlFields[f.name] = { type: fieldTypeToOutputGQL(f.type, f.name === idField) };
+                }
+                return gqlFields;
+            }
+        });
+        const ListResultType = new GraphQLObjectType({
+            name: `${typeName}ListResult`,
+            description: `Paginated list of ${typeName} records.`,
+            fields: {
+                count: {
+                    type: new GraphQLNonNull(GraphQLInt),
+                    description: 'Total matching records (before pagination).'
+                },
+                results: {
+                    type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(OutputType))),
+                    description: 'Records for the current page.'
+                }
+            }
+        });
+        const CreateInputType = new GraphQLInputObjectType({
+            name: `${typeName}CreateInput`,
+            description: `Fields required to create a ${typeName}.`,
+            fields: () => {
+                const gqlFields = {};
+                for (const f of writableFields) {
+                    gqlFields[f.name] = { type: fieldTypeToInputGQL(f.type, false) };
+                }
+                return gqlFields;
+            }
+        });
+        const UpdateInputType = new GraphQLInputObjectType({
+            name: `${typeName}UpdateInput`,
+            description: `Fields to patch on a ${typeName}. All fields are optional.`,
+            fields: () => {
+                const gqlFields = {};
+                for (const f of writableFields) {
+                    gqlFields[f.name] = { type: fieldTypeToInputGQL(f.type, false) };
+                }
+                return gqlFields;
+            }
+        });
+        const FilterInputType = new GraphQLInputObjectType({
+            name: `${typeName}FilterInput`,
+            description: `Simple equality filter for listing ${typeName} records.`,
+            fields: () => {
+                const gqlFields = {};
+                for (const f of filterableFields) {
+                    gqlFields[f.name] = { type: fieldTypeToInputGQL(f.type, f.name === idField) };
+                }
+                return gqlFields;
+            }
+        });
+        const UpdateManyResultType = new GraphQLObjectType({
+            name: `${typeName}UpdateManyResult`,
+            fields: {
+                updated: {
+                    type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLID))),
+                    description: 'IDs of updated records.'
+                },
+                results: {
+                    type: new GraphQLList(OutputType),
+                    description: 'Updated records (when the repository supports returning them).'
+                }
+            }
+        });
+        const DeleteManyResultType = new GraphQLObjectType({
+            name: `${typeName}DeleteManyResult`,
+            fields: {
+                deleted: {
+                    type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLID))),
+                    description: 'IDs of deleted records.'
+                }
+            }
+        });
+        // ─── Query: get (readOne) ──────────────────────────────────────────────
+        if (permissions.allowReadOne) {
+            queryFields[`get${typeName}`] = {
+                type: OutputType,
+                description: `Fetch a single ${typeName} by ID.`,
+                args: {
+                    id: { type: new GraphQLNonNull(GraphQLID), description: 'Record ID.' }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'readOne', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'readOne');
+                        const id = parseId(args.id);
+                        const hookCtx = { auth, resource, req: context.req };
+                        if (hooks?.beforeReadOne)
+                            await hooks.beforeReadOne(id, hookCtx);
+                        const rawResult = await repo.getOne(id);
+                        if (!rawResult)
+                            throw new NotFoundError();
+                        const result = await applyHook(hooks?.afterReadOne, rawResult, hookCtx);
+                        return filterReadableFields(resource, result, auth);
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Query: list (readMany) ────────────────────────────────────────────
+        if (permissions.allowReadMany) {
+            queryFields[`list${typeName}`] = {
+                type: new GraphQLNonNull(ListResultType),
+                description: `Fetch a paginated list of ${typeName} records. ` +
+                    `For advanced filtering use \`query${typeName}\`.`,
+                args: {
+                    filter: {
+                        type: FilterInputType,
+                        description: 'Per-field equality filters.'
+                    },
+                    limit: { type: GraphQLInt, description: 'Maximum records to return.' },
+                    offset: { type: GraphQLInt, description: 'Records to skip.' },
+                    orderBy: {
+                        type: new GraphQLList(new GraphQLNonNull(OrderByInput)),
+                        description: 'Sort order.'
+                    },
+                    include: {
+                        type: new GraphQLList(new GraphQLNonNull(GraphQLString)),
+                        description: 'Relation names to eagerly load.'
+                    }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'readMany', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'readMany');
+                        const hookCtx = { auth, resource, req: context.req };
+                        if (args.include?.length)
+                            validateIncludes(resource, args.include);
+                        const where = {};
+                        if (args.filter) {
+                            for (const [key, val] of Object.entries(args.filter)) {
+                                if (val !== undefined && val !== null)
+                                    where[key] = val;
+                            }
+                        }
+                        const listOptions = {
+                            where,
+                            limit: applyPageLimits(resource, args.limit),
+                            offset: args.offset,
+                            orderBy: args.orderBy?.map((o) => ({
+                                field: o.field,
+                                direction: o.direction
+                            })),
+                            include: args.include
+                        };
+                        const processedOptions = await applyHook(hooks?.beforeReadMany, listOptions, hookCtx);
+                        const rawResult = await repo.getMany(processedOptions);
+                        const result = await applyHook(hooks?.afterReadMany, rawResult, hookCtx);
+                        const filterRecord = makeReadableFieldFilter(resource, auth);
+                        return { count: result.count, results: result.results.map(filterRecord) };
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Query: query (executeQuery / readManyWithQueryBuilder) ───────────
+        if (permissions.allowReadManyWithQueryBuilder) {
+            queryFields[`query${typeName}`] = {
+                type: new GraphQLNonNull(ListResultType),
+                description: `Advanced query for ${typeName} with full filter expressions, sorting, and pagination. ` +
+                    `Mirrors the REST \`POST /${resource.routePrefix}/query\` endpoint.`,
+                args: {
+                    where: {
+                        type: new GraphQLList(new GraphQLNonNull(QueryFilterInput)),
+                        description: 'Filter conditions. Supports all operators (=, IN, LIKE, BETWEEN, …).'
+                    },
+                    fields: {
+                        type: new GraphQLList(new GraphQLNonNull(GraphQLString)),
+                        description: 'Field names to include. Omit for all selectable fields.'
+                    },
+                    distinct: {
+                        type: new GraphQLList(new GraphQLNonNull(GraphQLString)),
+                        description: 'Fields to de-duplicate on (SQL DISTINCT ON).'
+                    },
+                    limit: { type: GraphQLInt, description: 'Maximum records to return.' },
+                    offset: { type: GraphQLInt, description: 'Records to skip.' },
+                    orderBy: {
+                        type: new GraphQLList(new GraphQLNonNull(OrderByInput)),
+                        description: 'Sort order.'
+                    },
+                    include: {
+                        type: new GraphQLList(new GraphQLNonNull(GraphQLString)),
+                        description: 'Relation names to eagerly load.'
+                    }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'readManyWithQueryBuilder', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'readManyWithQueryBuilder');
+                        if (!repo.executeQuery)
+                            throw new NotImplementedError('This resource does not support the query builder.');
+                        const hookCtx = { auth, resource, req: context.req };
+                        const queryOrderBy = args.orderBy?.map((o) => ({
+                            field: o.field,
+                            order: (o.direction.toUpperCase() === 'DESC' ? SqlOrder.DESC : SqlOrder.ASC)
+                        }));
+                        const query = {
+                            ...(args.where !== undefined
+                                ? { where: args.where }
+                                : {}),
+                            ...(args.fields !== undefined ? { fields: args.fields } : {}),
+                            ...(args.distinct !== undefined ? { distinct: args.distinct } : {}),
+                            ...(args.limit !== undefined ? { limit: args.limit } : {}),
+                            ...(args.offset !== undefined ? { offset: args.offset } : {}),
+                            ...(queryOrderBy !== undefined ? { orderBy: queryOrderBy } : {}),
+                            ...(args.include !== undefined ? { include: args.include } : {})
+                        };
+                        const processedQuery = await applyHook(hooks?.beforeQuery, query, hookCtx);
+                        validateAdvancedQuery(resource, processedQuery);
+                        const rawResult = await repo.executeQuery(processedQuery);
+                        const result = await applyHook(hooks?.afterQuery, rawResult, hookCtx);
+                        const filterRecord = makeReadableFieldFilter(resource, auth);
+                        return {
+                            count: result.count ?? result.results.length,
+                            results: result.results.map(filterRecord)
+                        };
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Mutation: create (createOne) ─────────────────────────────────────
+        if (permissions.allowCreate) {
+            mutationFields[`create${typeName}`] = {
+                type: new GraphQLNonNull(OutputType),
+                description: `Create a single ${typeName} record.`,
+                args: {
+                    input: { type: new GraphQLNonNull(CreateInputType) }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'create', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'create');
+                        const hookCtx = { auth, resource, req: context.req };
+                        const filtered = filterWritableFields(resource, args.input, auth);
+                        const data = await applyHook(hooks?.beforeCreate, filtered, hookCtx);
+                        const rawResult = await repo.createOne(data);
+                        const result = await applyHook(hooks?.afterCreate, rawResult, hookCtx);
+                        return filterReadableFields(resource, result, auth);
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+            mutationFields[`createMany${typeName}`] = {
+                type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(OutputType))),
+                description: `Create multiple ${typeName} records.`,
+                args: {
+                    input: {
+                        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(CreateInputType)))
+                    }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'create', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'create');
+                        const hookCtx = { auth, resource, req: context.req };
+                        const rawItems = args.input.map((item) => filterWritableFields(resource, item, auth));
+                        const items = hooks?.beforeCreate
+                            ? await Promise.all(rawItems.map((d) => applyHook(hooks.beforeCreate, d, hookCtx)))
+                            : rawItems;
+                        const rawResults = await repo.createMany(items);
+                        const results = hooks?.afterCreate
+                            ? await Promise.all(rawResults.map((r) => applyHook(hooks.afterCreate, r, hookCtx)))
+                            : rawResults;
+                        const filterRecord = makeReadableFieldFilter(resource, auth);
+                        return results.map(filterRecord);
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Mutation: update (updateOne) ─────────────────────────────────────
+        if (permissions.allowUpdateOne) {
+            mutationFields[`update${typeName}`] = {
+                type: OutputType,
+                description: `Partially update a single ${typeName} by ID.`,
+                args: {
+                    id: { type: new GraphQLNonNull(GraphQLID) },
+                    input: { type: new GraphQLNonNull(UpdateInputType) }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'updateOne', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'updateOne');
+                        const id = parseId(args.id);
+                        const hookCtx = { auth, resource, req: context.req };
+                        const rawBody = filterWritableFields(resource, args.input, auth);
+                        const body = hooks?.beforeUpdateOne
+                            ? ((await hooks.beforeUpdateOne(id, rawBody, hookCtx)) ?? rawBody)
+                            : rawBody;
+                        const rawResult = await repo.updateOne(id, body);
+                        if (!rawResult)
+                            throw new NotFoundError();
+                        const result = await applyHook(hooks?.afterUpdateOne, rawResult, hookCtx);
+                        return filterReadableFields(resource, result, auth);
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Mutation: updateMany ──────────────────────────────────────────────
+        if (permissions.allowUpdateMany) {
+            mutationFields[`updateMany${typeName}`] = {
+                type: new GraphQLNonNull(UpdateManyResultType),
+                description: `Bulk-update ${typeName} records matching the given filter.`,
+                args: {
+                    where: {
+                        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(QueryFilterInput))),
+                        description: 'At least one filter is required to prevent accidental full-table updates.'
+                    },
+                    update: {
+                        type: new GraphQLNonNull(UpdateInputType),
+                        description: 'Fields to apply to every matched record.'
+                    }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'updateMany', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'updateMany');
+                        if (!repo.updateMany)
+                            throw new NotImplementedError('This resource does not support updateMany.');
+                        const hookCtx = { auth, resource, req: context.req };
+                        const filteredUpdate = filterWritableFields(resource, args.update, auth);
+                        if (!Object.keys(filteredUpdate).length)
+                            throw new UnprocessableEntityError('updateMany requires at least one writable field in the update payload.');
+                        const query = {
+                            where: args.where
+                        };
+                        validateAdvancedQuery(resource, query);
+                        if (!query.where?.length)
+                            throw new UnprocessableEntityError('updateMany requires at least one WHERE filter to prevent unintended bulk updates.');
+                        if (hooks?.beforeUpdateMany)
+                            await hooks.beforeUpdateMany(query, filteredUpdate, hookCtx);
+                        const rawResult = await repo.updateMany(query, filteredUpdate);
+                        const result = await applyHook(hooks?.afterUpdateMany, rawResult, hookCtx);
+                        const filterRecord = makeReadableFieldFilter(resource, auth);
+                        return {
+                            updated: result.updated,
+                            ...(result.results
+                                ? { results: result.results.map((r) => filterRecord(r)) }
+                                : {})
+                        };
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Mutation: upsert (upsertOne) ─────────────────────────────────────
+        if (permissions.allowUpsertOne) {
+            mutationFields[`upsert${typeName}`] = {
+                type: new GraphQLNonNull(OutputType),
+                description: `Create or replace a ${typeName} at the given ID.`,
+                args: {
+                    id: { type: new GraphQLNonNull(GraphQLID) },
+                    input: { type: new GraphQLNonNull(CreateInputType) }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'upsertOne', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'upsertOne');
+                        if (!repo.upsertOne)
+                            throw new NotImplementedError('This resource does not support upsert.');
+                        const id = parseId(args.id);
+                        const hookCtx = { auth, resource, req: context.req };
+                        const rawBody = filterWritableFields(resource, args.input, auth);
+                        const body = hooks?.beforeUpsertOne
+                            ? ((await hooks.beforeUpsertOne(id, rawBody, hookCtx)) ?? rawBody)
+                            : rawBody;
+                        const rawResult = await repo.upsertOne(id, body);
+                        const result = await applyHook(hooks?.afterUpsertOne, rawResult, hookCtx);
+                        return filterReadableFields(resource, result, auth);
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Mutation: delete (deleteOne) ─────────────────────────────────────
+        if (permissions.allowDeleteOne) {
+            mutationFields[`delete${typeName}`] = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                description: `Delete a single ${typeName} by ID. Returns true when deleted.`,
+                args: {
+                    id: { type: new GraphQLNonNull(GraphQLID) }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'deleteOne', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'deleteOne');
+                        const id = parseId(args.id);
+                        const hookCtx = { auth, resource, req: context.req };
+                        if (hooks?.beforeDeleteOne)
+                            await hooks.beforeDeleteOne(id, hookCtx);
+                        const deleted = await repo.deleteOne(id);
+                        if (!deleted)
+                            throw new NotFoundError();
+                        if (hooks?.afterDeleteOne)
+                            await hooks.afterDeleteOne(id, hookCtx);
+                        return true;
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+        // ─── Mutation: deleteMany ──────────────────────────────────────────────
+        if (permissions.allowDeleteMany) {
+            mutationFields[`deleteMany${typeName}`] = {
+                type: new GraphQLNonNull(DeleteManyResultType),
+                description: `Bulk-delete ${typeName} records matching the given filter.`,
+                args: {
+                    where: {
+                        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(QueryFilterInput))),
+                        description: 'At least one filter is required to prevent accidental full-table deletes.'
+                    }
+                },
+                async resolve(_parent, args, context) {
+                    try {
+                        const auth = await authorizeRequest(context.req, resource, 'deleteMany', authStrategy);
+                        const repo = await resolveRepo(context.req, auth, 'deleteMany');
+                        if (!repo.deleteMany)
+                            throw new NotImplementedError('This resource does not support deleteMany.');
+                        const hookCtx = { auth, resource, req: context.req };
+                        const query = {
+                            where: args.where
+                        };
+                        validateAdvancedQuery(resource, query);
+                        if (!query.where?.length)
+                            throw new UnprocessableEntityError('deleteMany requires at least one WHERE filter to prevent unintended bulk deletes.');
+                        if (hooks?.beforeDeleteMany)
+                            await hooks.beforeDeleteMany(query, hookCtx);
+                        const rawResult = await repo.deleteMany(query);
+                        const result = await applyHook(hooks?.afterDeleteMany, rawResult, hookCtx);
+                        return { deleted: result.deleted };
+                    }
+                    catch (e) {
+                        toGraphQLError(e);
+                    }
+                }
+            };
+        }
+    }
+    // Require at least one query field — GraphQL schema must have a Query root type.
+    if (!Object.keys(queryFields).length) {
+        queryFields['_empty'] = {
+            type: GraphQLString,
+            description: 'Placeholder — no resources are GraphQL-enabled.',
+            resolve: () => 'No GraphQL-enabled resources are registered.'
+        };
+    }
+    const hasMutations = Object.keys(mutationFields).length > 0;
+    return new GraphQLSchema({
+        query: new GraphQLObjectType({ name: 'Query', fields: queryFields }),
+        ...(hasMutations
+            ? { mutation: new GraphQLObjectType({ name: 'Mutation', fields: mutationFields }) }
+            : {})
+    });
+}

package/dist/graphql/types.d.ts

@@ -0,0 +1,48 @@
+import type { AuthContext } from '../auth/AuthStrategy.js';
+import type { AuthStrategy } from '../auth/strategies/types.js';
+import type { CrudHooks } from '../core/hooks.js';
+import type { CrudAction, HttpRequest, Repository, ResourceDefinition } from '../core/types.js';
+/** Configuration for the Halifax GraphQL endpoint. */
+export interface GraphQLOptions {
+    /**
+     * Must be explicitly set to `true` to enable the GraphQL endpoint.
+     * GraphQL is **disabled by default** — the peer dependency (`graphql`) is optional
+     * and will not be imported until you opt in.
+     */
+    enabled?: boolean;
+    /**
+     * Path for the `POST /graphql` endpoint.
+     * Defaults to `'/graphql'`.
+     */
+    path?: string;
+    /**
+     * When `true`, serve GraphiQL IDE at `GET <path>`.
+     * Defaults to `true`.
+     */
+    graphiql?: boolean;
+    /**
+     * When `true`, the GraphQL endpoint requires authentication before executing any operation,
+     * including introspection. Unauthenticated callers receive 401.
+     * Defaults to `false`.
+     */
+    requireAuth?: boolean;
+    /** Title shown in the GraphiQL browser tab. Defaults to `'Halifax GraphQL'`. */
+    title?: string;
+}
+/** Internal per-resource context threaded into the schema builder and resolvers. */
+export interface GraphQLResourceContext {
+    resource: ResourceDefinition;
+    authStrategy: AuthStrategy;
+    hooks: CrudHooks<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>> | undefined;
+    resolveRepo: (req: HttpRequest, auth: AuthContext, action: CrudAction) => Promise<Repository>;
+}
+/** GraphQL resolver context — the `contextValue` passed to every field resolver. */
+export interface GraphQLResolverContext {
+    req: HttpRequest;
+}
+/** Standard GraphQL-over-HTTP request body. */
+export interface GraphQLRequestBody {
+    query?: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}