@edium/halifax 2.2.2 → 2.3.0

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';
@@ -13,6 +14,7 @@ const statusCodeMap = {
     404: 'NOT_FOUND',
     405: 'METHOD_NOT_ALLOWED',
     406: 'NOT_ACCEPTABLE',
+    409: 'CONFLICT',
     415: 'UNSUPPORTED_MEDIA_TYPE',
     422: 'UNPROCESSABLE_ENTITY',
     501: 'NOT_IMPLEMENTED'
@@ -62,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.
@@ -95,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;
@@ -125,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,4 +1,4 @@
-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) => {
@@ -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/query.js

@@ -1,6 +1,6 @@
 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) => {
@@ -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,5 +1,5 @@
 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) => {
@@ -10,9 +10,7 @@ export function registerReadMany(server, basePath, ctx) {
         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,4 +1,4 @@
-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) {
@@ -10,11 +10,8 @@ export function registerReadOne(server, basePath, ctx) {
         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,7 +1,7 @@
 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) => {
@@ -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/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/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/errors/ConflictError.d.ts

@@ -0,0 +1,5 @@
+import { HttpError } from './HttpError.js';
+/** Thrown when a write conflicts with an existing record — e.g. a duplicate unique field (HTTP 409). */
+export declare class ConflictError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}

package/dist/errors/ConflictError.js

@@ -0,0 +1,8 @@
+import { HttpError } from './HttpError.js';
+/** Thrown when a write conflicts with an existing record — e.g. a duplicate unique field (HTTP 409). */
+export class ConflictError extends HttpError {
+    constructor(message = 'Conflict', details) {
+        super(message, 409, details);
+        this.name = 'ConflictError';
+    }
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './core/types.js';
 export * from './core/validation.js';
 export * from '@edium/halifax-types';
 export * from './errors/AuthenticationError.js';
+export * from './errors/ConflictError.js';
 export * from './errors/AuthorizationError.js';
 export * from './errors/BadRequestError.js';
 export * from './errors/HttpError.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './core/types.js';
 export * from './core/validation.js';
 export * from '@edium/halifax-types';
 export * from './errors/AuthenticationError.js';
+export * from './errors/ConflictError.js';
 export * from './errors/AuthorizationError.js';
 export * from './errors/BadRequestError.js';
 export * from './errors/HttpError.js';

package/dist/openapi/specGenerator.js

@@ -1,5 +1,5 @@
 import { defaultCrudPermissions } from '../core/types.js';
-import { mergeFieldDefinitions } from '../core/fields.js';
+import { mergeFieldDefinitions, mergeRelationDefinitions, normalizeEnvelope } from '../core/fields.js';
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 // Exhaustive map from every FieldType to its JSON Schema type string.
 // Adding a new FieldType causes a compile error here until the map is updated — no switch to edit.
@@ -21,9 +21,6 @@ function toPascalCase(routePrefix) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join('');
 }
-function normalizeEnvelope(value) {
-    return typeof value === 'string' && value.length > 0 ? value : null;
-}
 function mergeFields(resource) {
     const idField = resource.repository?.idField ?? 'id';
     return mergeFieldDefinitions(resource).map((f) => ({
@@ -31,14 +28,6 @@ function mergeFields(resource) {
         writable: f.name === idField ? f.writable === true : f.writable !== false
     }));
 }
-function mergeRelations(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()];
-}
 // Wraps a schema under an envelope key if one is active.
 function withEnvelope(schema, envelope) {
     if (!envelope)
@@ -202,7 +191,7 @@ const sharedSchemas = {
             '    { "field": "published", "comparison": "=", "value": true },',
             '    { "field": "createdAt", "comparison": ">=", "value": "2024-01-01T00:00:00Z" }',
             '  ],',
-            '  "orderBy": [{ "field": "createdAt", "direction": "desc" }],',
+            '  "orderBy": [{ "field": "createdAt", "order": "DESC" }],',
             '  "limit": 20,',
             '  "offset": 0,',
             '  "fields": ["id", "title", "createdAt"],',
@@ -228,10 +217,10 @@ const sharedSchemas = {
                 description: 'Sort order. Multiple entries produce multi-column sorting.',
                 items: {
                     type: 'object',
-                    required: ['field', 'direction'],
+                    required: ['field', 'order'],
                     properties: {
                         field: { type: 'string', description: 'Field name to sort by (must be sortable).' },
-                        direction: { type: 'string', enum: ['asc', 'desc'] }
+                        order: { type: 'string', enum: ['ASC', 'DESC'] }
                     }
                 }
             },
@@ -240,7 +229,11 @@ const sharedSchemas = {
                 items: { type: 'string' },
                 description: 'Relation names to eagerly load (if the resource supports includes).'
             },
-            distinct: { type: 'boolean', description: 'When `true`, de-duplicates results.' }
+            distinct: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Field names to de-duplicate results on (maps to SQL DISTINCT ON these columns).'
+            }
         }
     }
 };
@@ -262,6 +255,7 @@ const badRequestError = errorRef('Bad Request — malformed query string, invali
 const notFoundError = errorRef('Not Found — the record with the given ID does not exist.');
 const unprocessableError = errorRef('Unprocessable Entity — request body contains unknown or non-writable fields.');
 const notImplementedError = errorRef('Not Implemented — the underlying repository does not support this operation.');
+const conflictError = errorRef('Conflict — the write was rejected because it would violate a unique constraint.');
 // ─── Main export ──────────────────────────────────────────────────────────────
 export function generateOpenApiSpec(resources, options = {}) {
     const globalEnvelope = normalizeEnvelope(options.envelope);
@@ -284,10 +278,17 @@ export function generateOpenApiSpec(resources, options = {}) {
                 : {})
         }
     };
+    // Note: resources here are the *raw* definitions as passed by the caller — they have NOT
+    // been through crudRouter's `normalizeResource()`. That means `mergeFields` and
+    // `mergeRelationDefinitions` below re-derive the same merged views that the router already
+    // computed at startup. This is intentional: the spec generator is a standalone function
+    // (called outside the router for static generation tooling), so it can't rely on the
+    // router's normalized state. If crudRouter ever caches normalized resources, pass them
+    // here instead to avoid the duplicate merge work.
     for (const resource of resources) {
         const permissions = { ...defaultCrudPermissions, ...resource.permissions };
         const fields = mergeFields(resource);
-        const relations = mergeRelations(resource);
+        const relations = mergeRelationDefinitions(resource);
         const idField = resource.repository?.idField ?? 'id';
         const schemaBase = toPascalCase(resource.routePrefix);
         const tag = resource.name ?? schemaBase;
@@ -458,6 +459,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                         content: { 'application/json': { schema: { oneOf: [singleResponse, arrayResponse] } } }
                     },
                     '400': badRequestError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     ...commonErrors,
                     ...writeErrors
@@ -500,10 +502,10 @@ export function generateOpenApiSpec(resources, options = {}) {
                         type: 'array',
                         items: {
                             type: 'object',
-                            required: ['field', 'direction'],
+                            required: ['field', 'order'],
                             properties: {
                                 field: { type: 'string' },
-                                direction: { type: 'string', enum: ['asc', 'desc'] }
+                                order: { type: 'string', enum: ['ASC', 'DESC'] }
                             }
                         }
                     }
@@ -538,6 +540,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                         }
                     },
                     '400': badRequestError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     '501': notImplementedError,
                     ...commonErrors,
@@ -697,6 +700,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                     },
                     '400': badRequestError,
                     '404': notFoundError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     ...commonErrors,
                     ...writeErrors
@@ -733,6 +737,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                         }
                     },
                     '400': badRequestError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     '501': notImplementedError,
                     ...commonErrors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edium/halifax",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Auto-generate type-safe REST CRUD APIs from your data models. Adapter-driven: Express/Fastify/HyperExpress, Prisma (PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, SQLite), JWT/API-key auth, multi-tenancy, a dynamic query builder, and pluggable Redis caching.",
   "author": "David LaTour <david@edium.com>",
   "homepage": "https://github.com/splayfee/halifax#readme",
@@ -166,7 +166,7 @@
   ],
   "dependencies": {
     "uuid": "^14.0.0",
-    "@edium/halifax-types": "2.2.2"
+    "@edium/halifax-types": "2.3.0"
   },
   "scripts": {
     "build": "rm -rf dist && tsc --build && tsc-alias",