@edium/halifax 2.2.3 → 2.4.0

package/dist/core/fields.d.ts

@@ -1,4 +1,4 @@
-import type { FieldDefinition, ResourceDefinition } from '../core/types.js';
+import type { FieldDefinition, RelationDefinition, ResourceDefinition } from '../core/types.js';
 /**
  * Merges a resource's field schema: repository fields are the base, and
  * `resource.fields` entries are applied as sparse overrides (by name).
@@ -6,3 +6,13 @@ import type { FieldDefinition, ResourceDefinition } from '../core/types.js';
  * the flags they care about on top of this.
  */
 export declare function mergeFieldDefinitions(resource: ResourceDefinition): FieldDefinition[];
+/**
+ * Merges a resource's relation schema: repository relations are the base, and
+ * `resource.relations` entries are applied as sparse overrides (by name).
+ */
+export declare function mergeRelationDefinitions(resource: ResourceDefinition): RelationDefinition[];
+/**
+ * Resolves the effective envelope key. A non-empty string enables wrapping;
+ * `null`, `undefined`, and `''` all mean "no envelope".
+ */
+export declare function normalizeEnvelope(value: string | null | undefined): string | null;

package/dist/core/fields.js

@@ -12,3 +12,22 @@ export function mergeFieldDefinitions(resource) {
         byName.set(f.name, { ...byName.get(f.name), ...f });
     return [...byName.values()];
 }
+/**
+ * Merges a resource's relation schema: repository relations are the base, and
+ * `resource.relations` entries are applied as sparse overrides (by name).
+ */
+export function mergeRelationDefinitions(resource) {
+    const byName = new Map();
+    for (const r of resource.repository?.relations ?? [])
+        byName.set(r.name, r);
+    for (const r of resource.relations ?? [])
+        byName.set(r.name, r);
+    return [...byName.values()];
+}
+/**
+ * Resolves the effective envelope key. A non-empty string enables wrapping;
+ * `null`, `undefined`, and `''` all mean "no envelope".
+ */
+export function normalizeEnvelope(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}

package/dist/core/handlerUtils.d.ts

@@ -41,6 +41,12 @@ export declare function filterWritableFields(resource: ResourceDefinition, data:
  * Fast-path returns the record unchanged when no fields carry read restrictions.
  */
 export declare function filterReadableFields(resource: ResourceDefinition, record: Record<string, unknown>, auth?: AuthContext): Record<string, unknown>;
+/**
+ * Returns a reusable filter function that strips read-restricted fields.
+ * Build this once per request (outside a `.map()` loop) so the fieldMap and
+ * userRoles Set are not reconstructed for every record in a bulk response.
+ */
+export declare function makeReadableFieldFilter(resource: ResourceDefinition, auth?: AuthContext): (record: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Runs the auth strategy for `action` and throws {@link AuthorizationError} when not allowed.
  */
@@ -66,5 +72,5 @@ export interface RouteHandlerContext {
     authStrategy: AuthStrategy;
     envelope: string | null;
     hooks: CrudHooks<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>> | undefined;
-    resolveRepo: (req: HttpRequest, auth: AuthContext) => Promise<Repository>;
+    resolveRepo: (req: HttpRequest, auth: AuthContext, action: CrudAction) => Promise<Repository>;
 }

package/dist/core/handlerUtils.js

@@ -1,3 +1,4 @@
+import { checkRequiredPermissions } from '../auth/strategies/types.js';
 import { HttpError } from '../errors/HttpError.js';
 import { NotAcceptableError } from '../errors/NotAcceptableError.js';
 import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
@@ -63,9 +64,9 @@ export function writeSuccess(res, status, body, envelope) {
  */
 export function parseId(raw) {
     validateId(raw);
-    if (typeof raw === 'string' && (isValidUuid(raw) || isValidObjectId(raw)))
+    if (isValidUuid(raw) || isValidObjectId(raw))
         return raw;
-    return typeof raw === 'string' ? parseInt(raw, 10) : raw;
+    return parseInt(raw, 10);
 }
 /**
  * Strips non-writable fields from a request body and rejects unknown fields with a 422.
@@ -96,12 +97,20 @@ export function filterWritableFields(resource, data, auth) {
  * Fast-path returns the record unchanged when no fields carry read restrictions.
  */
 export function filterReadableFields(resource, record, auth) {
+    return makeReadableFieldFilter(resource, auth)(record);
+}
+/**
+ * Returns a reusable filter function that strips read-restricted fields.
+ * Build this once per request (outside a `.map()` loop) so the fieldMap and
+ * userRoles Set are not reconstructed for every record in a bulk response.
+ */
+export function makeReadableFieldFilter(resource, auth) {
     const fields = resource.fields ?? [];
     if (!fields.some((f) => (f.readRoles?.length ?? 0) > 0))
-        return record;
+        return (r) => r;
     const fieldMap = new Map(fields.map((f) => [f.name, f]));
     const userRoles = new Set([...(auth?.roles ?? []), ...(auth?.permissions ?? [])]);
-    return Object.fromEntries(Object.entries(record).filter(([key]) => {
+    return (record) => Object.fromEntries(Object.entries(record).filter(([key]) => {
         const field = fieldMap.get(key);
         if (!field?.readRoles?.length)
             return true;
@@ -126,13 +135,8 @@ export async function authorizeRequest(req, resource, action, authStrategy) {
             throw new AuthorizationError();
         return auth;
     }
-    if (requiredPermissions.length) {
-        const permissions = new Set(auth.permissions ?? []);
-        const roles = new Set(auth.roles ?? []);
-        const allowed = requiredPermissions.some((permission) => permissions.has(permission) || roles.has(permission));
-        if (!allowed)
-            throw new AuthorizationError();
-    }
+    if (!checkRequiredPermissions(auth, requiredPermissions))
+        throw new AuthorizationError();
     return auth;
 }
 /**

package/dist/core/handlers/create.js

@@ -1,9 +1,9 @@
-import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, getHeaderValue, wrap, writeSuccess } from '../../core/handlerUtils.js';
+import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, getHeaderValue, makeReadableFieldFilter, wrap, writeSuccess } from '../../core/handlerUtils.js';
 export function registerCreate(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('POST', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'create', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'create');
         const idempotencyKey = getHeaderValue(req, 'idempotency-key');
         const createOptions = idempotencyKey ? { idempotencyKey } : undefined;
         const hookCtx = { auth, resource, req };
@@ -21,6 +21,7 @@ export function registerCreate(server, basePath, ctx) {
         const results = hooks?.afterCreate
             ? await Promise.all(rawResults.map((r) => applyHook(hooks.afterCreate, r, hookCtx)))
             : rawResults;
-        await writeSuccess(res, 201, results.map((r) => filterReadableFields(resource, r, auth)), envelope);
+        const filterRecord = makeReadableFieldFilter(resource, auth);
+        await writeSuccess(res, 201, results.map(filterRecord), envelope);
     }));
 }

package/dist/core/handlers/deleteMany.js

@@ -6,7 +6,7 @@ export function registerDeleteMany(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('DELETE', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'deleteMany', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'deleteMany');
         if (!repo.deleteMany)
             throw new NotImplementedError('This resource does not support deleteMany.');
         const hookCtx = { auth, resource, req };

package/dist/core/handlers/deleteOne.js

@@ -4,7 +4,7 @@ export function registerDeleteOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('DELETE', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'deleteOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'deleteOne');
         const id = parseId(req.params['id']);
         const hookCtx = { auth, resource, req };
         if (hooks?.beforeDeleteOne)

package/dist/core/handlers/query.js

@@ -1,11 +1,11 @@
 import { validateAdvancedQuery } from '../../core/validation.js';
 import { NotImplementedError } from '../../errors/NotImplementedError.js';
-import { applyHook, authorizeRequest, filterReadableFields, wrap, writeSuccess } from '../../core/handlerUtils.js';
+import { applyHook, authorizeRequest, makeReadableFieldFilter, wrap, writeSuccess } from '../../core/handlerUtils.js';
 export function registerQuery(server, basePath, queryBuilderPath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('POST', `${basePath}/${queryBuilderPath}`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'readManyWithQueryBuilder', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'readManyWithQueryBuilder');
         if (!repo.executeQuery)
             throw new NotImplementedError('This resource does not support the query builder.');
         const hookCtx = { auth, resource, req };
@@ -15,9 +15,7 @@ export function registerQuery(server, basePath, queryBuilderPath, ctx) {
         validateAdvancedQuery(resource, query);
         const rawResult = await repo.executeQuery(query);
         const result = await applyHook(hooks?.afterQuery, rawResult, hookCtx);
-        await writeSuccess(res, 200, {
-            ...result,
-            results: result.results.map((r) => filterReadableFields(resource, r, auth))
-        }, envelope);
+        const filterRecord = makeReadableFieldFilter(resource, auth);
+        await writeSuccess(res, 200, { ...result, results: result.results.map(filterRecord) }, envelope);
     }));
 }

package/dist/core/handlers/readMany.js

@@ -1,18 +1,16 @@
 import { parseListOptions } from '../../core/queryString.js';
-import { applyHook, authorizeRequest, filterReadableFields, wrap, writeSuccess } from '../../core/handlerUtils.js';
+import { applyHook, authorizeRequest, makeReadableFieldFilter, wrap, writeSuccess } from '../../core/handlerUtils.js';
 export function registerReadMany(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('GET', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'readMany', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'readMany');
         const hookCtx = { auth, resource, req };
         const parsedOptions = parseListOptions(req.query, resource);
         const listOptions = await applyHook(hooks?.beforeReadMany, parsedOptions, hookCtx);
         const rawResult = await repo.getMany(listOptions);
         const result = await applyHook(hooks?.afterReadMany, rawResult, hookCtx);
-        await writeSuccess(res, 200, {
-            ...result,
-            results: result.results.map((r) => filterReadableFields(resource, r, auth))
-        }, envelope);
+        const filterRecord = makeReadableFieldFilter(resource, auth);
+        await writeSuccess(res, 200, { ...result, results: result.results.map(filterRecord) }, envelope);
     }));
 }

package/dist/core/handlers/readOne.js

@@ -1,20 +1,17 @@
-import { parseListOptions } from '../../core/queryString.js';
+import { parseGetOneOptions } from '../../core/queryString.js';
 import { NotFoundError } from '../../errors/NotFoundError.js';
 import { applyHook, authorizeRequest, filterReadableFields, parseId, wrap, writeSuccess } from '../../core/handlerUtils.js';
 export function registerReadOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('GET', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'readOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'readOne');
         const id = parseId(req.params['id']);
         const hookCtx = { auth, resource, req };
         if (hooks?.beforeReadOne)
             await hooks.beforeReadOne(id, hookCtx);
-        const listOptions = parseListOptions(req.query, resource);
-        const rawResult = await repo.getOne(id, {
-            fields: listOptions.fields,
-            include: listOptions.include
-        });
+        const { fields, include } = parseGetOneOptions(req.query, resource);
+        const rawResult = await repo.getOne(id, { fields, include });
         if (!rawResult)
             throw new NotFoundError();
         const result = await applyHook(hooks?.afterReadOne, rawResult, hookCtx);

package/dist/core/handlers/updateMany.js

@@ -1,12 +1,12 @@
 import { validateAdvancedQuery } from '../../core/validation.js';
 import { NotImplementedError } from '../../errors/NotImplementedError.js';
 import { UnprocessableEntityError } from '../../errors/UnprocessableEntityError.js';
-import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, wrap, writeSuccess } from '../../core/handlerUtils.js';
+import { applyHook, authorizeRequest, filterWritableFields, makeReadableFieldFilter, wrap, writeSuccess } from '../../core/handlerUtils.js';
 export function registerUpdateMany(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('PATCH', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'updateMany', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'updateMany');
         if (!repo.updateMany)
             throw new NotImplementedError('This resource does not support updateMany.');
         const hookCtx = { auth, resource, req };
@@ -22,12 +22,11 @@ export function registerUpdateMany(server, basePath, ctx) {
             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);
         await writeSuccess(res, 200, {
             ...result,
             ...(result.results
-                ? {
-                    results: result.results.map((r) => filterReadableFields(resource, r, auth))
-                }
+                ? { results: result.results.map((r) => filterRecord(r)) }
                 : {})
         }, envelope);
     }));

package/dist/core/handlers/updateOne.js

@@ -4,7 +4,7 @@ export function registerUpdateOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('PATCH', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'updateOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'updateOne');
         const id = parseId(req.params['id']);
         const hookCtx = { auth, resource, req };
         const rawBody = filterWritableFields(resource, (req.body ?? {}), auth);

package/dist/core/handlers/upsertOne.js

@@ -4,7 +4,7 @@ export function registerUpsertOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('PUT', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'upsertOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'upsertOne');
         if (!repo.upsertOne)
             throw new NotImplementedError('This resource does not support upsert.');
         const id = parseId(req.params['id']);

package/dist/core/queryString.d.ts

@@ -1,4 +1,14 @@
 import { type ListOptions, type ResourceDefinition } from '../core/types.js';
+/**
+ * Parses and validates the query-string for a single-record GET (`GET /resource/:id`).
+ * Only `?fields=` and `?include=` are meaningful for that endpoint — this avoids the wasted
+ * work and silent-discard behaviour of calling the full `parseListOptions` on a by-ID route.
+ *
+ * @param query - The raw query-string object from the HTTP request.
+ * @param resource - The resource definition used for field and relation validation.
+ * @returns Typed projection options ready to pass to `repository.getOne()`.
+ */
+export declare function parseGetOneOptions(query: Record<string, unknown>, resource: ResourceDefinition): Pick<ListOptions, 'fields' | 'include'>;
 /**
  * Parses and validates the raw query-string from a GET request into typed {@link ListOptions}.
  *

package/dist/core/queryString.js

@@ -31,6 +31,29 @@ function parseCsv(value) {
         .map((item) => item.trim())
         .filter(Boolean);
 }
+/**
+ * Parses and validates the query-string for a single-record GET (`GET /resource/:id`).
+ * Only `?fields=` and `?include=` are meaningful for that endpoint — this avoids the wasted
+ * work and silent-discard behaviour of calling the full `parseListOptions` on a by-ID route.
+ *
+ * @param query - The raw query-string object from the HTTP request.
+ * @param resource - The resource definition used for field and relation validation.
+ * @returns Typed projection options ready to pass to `repository.getOne()`.
+ */
+export function parseGetOneOptions(query, resource) {
+    const fields = parseCsv(query.fields);
+    const include = parseCsv(query.include);
+    if (fields) {
+        validateFields(resource, fields);
+        validateSelectableFields(resource, fields);
+    }
+    if (include)
+        validateIncludes(resource, include);
+    if (fields && include) {
+        throw new UnprocessableEntityError('Cannot use both ?fields= and ?include= in the same request.');
+    }
+    return { fields, include };
+}
 /**
  * Parses and validates the raw query-string from a GET request into typed {@link ListOptions}.
  *

package/dist/core/types.d.ts

@@ -389,6 +389,28 @@ export interface ResourceDefinition<TRecord = unknown, TCreate = Partial<TRecord
      * `false` to explicitly disable caching for this resource even when a default is configured.
      */
     cache?: ResourceCacheConfig | false;
+    /**
+     * Controls whether this resource is exposed through the GraphQL endpoint.
+     * Set to `false` to exclude this resource from the generated GraphQL schema entirely.
+     * Defaults to `true` when GraphQL is enabled on the API.
+     */
+    graphql?: boolean;
+    /**
+     * Roles or permission slugs whose holders may bypass tenant scoping for **read** operations
+     * on this resource, allowing them to see records across all tenants. Any single match in
+     * `auth.roles` or `auth.permissions` grants the bypass.
+     *
+     * Bypass callers receive all records on reads. To narrow to a single tenant they use the
+     * standard filter mechanism (`?companyId=42` on REST, `filter: { companyId: 42 }` in
+     * GraphQL) — the tenant field is just another filterable column from their perspective.
+     *
+     * Write operations (create / update / delete) are **never** bypassed — tenant value on writes
+     * always comes from `resolveId` (the auth token), not from the bypass path.
+     *
+     * Overrides {@link TenantOptions.bypassRoles} for this resource. Set to `[]` to disable
+     * bypass on this resource even when a global `bypassRoles` is configured.
+     */
+    bypassTenantRoles?: string[];
     /**
      * Wrap every success response body for this resource under a single key
      * (e.g. `'data'` →

package/dist/core/validation.js

@@ -58,9 +58,7 @@ export function validateId(value) {
  * @returns Array of field name strings.
  */
 export function getFieldNames(resource) {
-    return (resource.fields ?? []).map((field) => {
-        return field.name;
-    });
+    return (resource.fields ?? []).map((f) => f.name);
 }
 /**
  * Throws {@link UnprocessableEntityError} when any of `fields` are not defined on the resource.
@@ -82,10 +80,8 @@ export function validateFields(resource, fields = []) {
  * @param fields - Field names to check for selectability.
  */
 export function validateSelectableFields(resource, fields) {
-    const nonSelectable = fields.filter((name) => {
-        const field = resource.fields?.find((f) => f.name === name);
-        return field?.selectable === false;
-    });
+    const fieldMap = new Map((resource.fields ?? []).map((f) => [f.name, f]));
+    const nonSelectable = fields.filter((name) => fieldMap.get(name)?.selectable === false);
     if (nonSelectable.length) {
         throw new UnprocessableEntityError(`Field(s) not selectable: ${nonSelectable.join(', ')}.`);
     }
@@ -96,10 +92,8 @@ export function validateSelectableFields(resource, fields) {
  * @param fields - Field names to check for sortability.
  */
 export function validateSortableFields(resource, fields) {
-    const nonSortable = fields.filter((name) => {
-        const field = resource.fields?.find((f) => f.name === name);
-        return field?.sortable === false;
-    });
+    const fieldMap = new Map((resource.fields ?? []).map((f) => [f.name, f]));
+    const nonSortable = fields.filter((name) => fieldMap.get(name)?.sortable === false);
     if (nonSortable.length) {
         throw new UnprocessableEntityError(`Field(s) not sortable: ${nonSortable.join(', ')}.`);
     }

package/dist/graphql/graphiql.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates an HTML page that renders the GraphiQL IDE, loading assets from unpkg.com CDN.
+ * The GraphQL endpoint URL is embedded so GraphiQL points at the correct server path.
+ */
+export declare function generateGraphiQLHtml(graphqlPath: string, title: string): string;

package/dist/graphql/graphiql.js

@@ -0,0 +1,29 @@
+/**
+ * Generates an HTML page that renders the GraphiQL IDE, loading assets from unpkg.com CDN.
+ * The GraphQL endpoint URL is embedded so GraphiQL points at the correct server path.
+ */
+export function generateGraphiQLHtml(graphqlPath, title) {
+    const escapedPath = JSON.stringify(graphqlPath);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${title}</title>
+  <link href="https://unpkg.com/graphiql/graphiql.min.css" rel="stylesheet" />
+  <style>body { margin: 0; }</style>
+</head>
+<body>
+  <div id="graphiql" style="height:100vh;"></div>
+  <script crossorigin src="https://unpkg.com/react/umd/react.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
+  <script src="https://unpkg.com/graphiql/graphiql.min.js" type="application/javascript"></script>
+  <script>
+    var fetcher = GraphiQL.createFetcher({ url: ${escapedPath} });
+    ReactDOM.createRoot(document.getElementById('graphiql')).render(
+      React.createElement(GraphiQL, { fetcher: fetcher })
+    );
+  </script>
+</body>
+</html>`;
+}

package/dist/graphql/index.d.ts

@@ -0,0 +1,4 @@
+export type { GraphQLOptions, GraphQLResourceContext, GraphQLResolverContext } from './types.js';
+export { buildGraphQLSchema } from './schema.js';
+export { registerGraphqlRoute } from './registerGraphqlRoute.js';
+export { generateGraphiQLHtml } from './graphiql.js';

package/dist/graphql/index.js

@@ -0,0 +1,3 @@
+export { buildGraphQLSchema } from './schema.js';
+export { registerGraphqlRoute } from './registerGraphqlRoute.js';
+export { generateGraphiQLHtml } from './graphiql.js';

package/dist/graphql/registerGraphqlRoute.d.ts

@@ -0,0 +1,10 @@
+import type { GraphQLOptions, GraphQLResourceContext } from './types.js';
+import type { AuthStrategy } from '../auth/strategies/types.js';
+import type { HttpServer } from '../core/types.js';
+/**
+ * Registers the `POST /graphql` execution endpoint and optionally the `GET /graphql`
+ * GraphiQL IDE page on the given HTTP server.
+ *
+ * The schema is built once at registration time from the provided resource contexts.
+ */
+export declare function registerGraphqlRoute(server: HttpServer, contexts: GraphQLResourceContext[], options: GraphQLOptions, authStrategy: AuthStrategy): void;

package/dist/graphql/registerGraphqlRoute.js

@@ -0,0 +1,79 @@
+import { graphql, parse, validate } from 'graphql';
+import { buildGraphQLSchema } from './schema.js';
+import { generateGraphiQLHtml } from './graphiql.js';
+import { sendError } from '../core/handlerUtils.js';
+/**
+ * Registers the `POST /graphql` execution endpoint and optionally the `GET /graphql`
+ * GraphiQL IDE page on the given HTTP server.
+ *
+ * The schema is built once at registration time from the provided resource contexts.
+ */
+export function registerGraphqlRoute(server, contexts, options, authStrategy) {
+    if (options.enabled === false)
+        return;
+    const path = options.path ?? '/graphql';
+    const graphiqlEnabled = options.graphiql !== false;
+    const requireAuth = options.requireAuth === true;
+    const title = options.title ?? 'Halifax GraphQL';
+    const schema = buildGraphQLSchema(contexts);
+    const graphiqlHtml = graphiqlEnabled ? generateGraphiQLHtml(path, title) : null;
+    // ─── POST /graphql — execution endpoint ─────────────────────────────────
+    server.registerRoute('POST', path, async (req, res) => {
+        try {
+            if (requireAuth)
+                await authStrategy.authenticate(req);
+            const body = (req.body ?? {});
+            const source = body.query ?? '';
+            if (!source.trim()) {
+                await res.status(400).json({
+                    errors: [{ message: 'GraphQL request must include a query.' }]
+                });
+                return;
+            }
+            // Parse and validate before executing so syntax errors surface cleanly.
+            let document;
+            try {
+                document = parse(source);
+            }
+            catch (syntaxError) {
+                await res.status(400).json({
+                    errors: [
+                        { message: syntaxError instanceof Error ? syntaxError.message : 'Syntax error.' }
+                    ]
+                });
+                return;
+            }
+            const validationErrors = validate(schema, document);
+            if (validationErrors.length) {
+                await res.status(400).json({ errors: validationErrors.map((e) => ({ message: e.message })) });
+                return;
+            }
+            const result = await graphql({
+                schema,
+                source,
+                variableValues: body.variables,
+                operationName: body.operationName,
+                contextValue: { req }
+            });
+            res.setHeader?.('Content-Type', 'application/json');
+            await res.status(200).json(result);
+        }
+        catch (error) {
+            await sendError(error, res);
+        }
+    });
+    // ─── GET /graphql — GraphiQL IDE ─────────────────────────────────────────
+    if (graphiqlEnabled && graphiqlHtml) {
+        server.registerRoute('GET', path, async (req, res) => {
+            try {
+                if (requireAuth)
+                    await authStrategy.authenticate(req);
+                res.setHeader?.('Content-Type', 'text/html; charset=utf-8');
+                res.send?.(graphiqlHtml);
+            }
+            catch (error) {
+                await sendError(error, res);
+            }
+        });
+    }
+}

package/dist/graphql/scalars.d.ts

@@ -0,0 +1,6 @@
+import { GraphQLScalarType } from 'graphql';
+/**
+ * Custom `JSON` scalar that accepts any JSON-serializable value.
+ * Used for filter `value1`/`value2` fields in QueryFilterInput and for `object` field types.
+ */
+export declare const GraphQLJSON: GraphQLScalarType<unknown, unknown>;

package/dist/graphql/scalars.js

@@ -0,0 +1,32 @@
+import { GraphQLScalarType, Kind } from 'graphql';
+function parseLiteralToValue(ast) {
+    switch (ast.kind) {
+        case Kind.STRING:
+            return ast.value;
+        case Kind.BOOLEAN:
+            return ast.value;
+        case Kind.INT:
+            return parseInt(ast.value, 10);
+        case Kind.FLOAT:
+            return parseFloat(ast.value);
+        case Kind.NULL:
+            return null;
+        case Kind.LIST:
+            return ast.values.map(parseLiteralToValue);
+        case Kind.OBJECT:
+            return Object.fromEntries(ast.fields.map((f) => [f.name.value, parseLiteralToValue(f.value)]));
+        default:
+            return null;
+    }
+}
+/**
+ * Custom `JSON` scalar that accepts any JSON-serializable value.
+ * Used for filter `value1`/`value2` fields in QueryFilterInput and for `object` field types.
+ */
+export const GraphQLJSON = new GraphQLScalarType({
+    name: 'JSON',
+    description: 'Arbitrary JSON value (string, number, boolean, null, array, or object).',
+    serialize: (value) => value,
+    parseValue: (value) => value,
+    parseLiteral: parseLiteralToValue
+});

package/dist/graphql/schema.d.ts

@@ -0,0 +1,3 @@
+import { GraphQLSchema } from 'graphql';
+import type { GraphQLResourceContext } from './types.js';
+export declare function buildGraphQLSchema(contexts: GraphQLResourceContext[]): GraphQLSchema;