@edium/halifax 2.2.3 → 2.3.0

package/dist/auth/strategies/PassportStrategies.js

@@ -1,4 +1,5 @@
 import { AuthenticationError } from '../../errors/AuthenticationError.js';
+import { checkRequiredPermissions } from './types.js';
 /**
  * Extracts `userId`, `roles`, `permissions`, and `claims` from a raw Passport user payload.
  * @param user - The raw user object returned by Passport (typically a decoded JWT payload).
@@ -17,13 +18,6 @@ function defaultMapUser(user) {
         ctx.userId = userId;
     return ctx;
 }
-function checkPermissions(auth, requiredPermissions) {
-    if (!requiredPermissions.length)
-        return true;
-    const permissions = new Set(auth.permissions ?? []);
-    const roles = new Set(auth.roles ?? []);
-    return requiredPermissions.every((p) => permissions.has(p) || roles.has(p));
-}
 /** Delegates authentication to a caller-provided Passport authenticate wrapper. */
 export class PassportAuthStrategy {
     authenticateWithPassport;
@@ -85,7 +79,7 @@ export class PassportJwtStrategy {
      * @returns `true` when all required permissions are satisfied, `false` otherwise.
      */
     authorize(params) {
-        return checkPermissions(params.auth, params.requiredPermissions);
+        return checkRequiredPermissions(params.auth, params.requiredPermissions);
     }
     openApiScheme() {
         return { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' };
@@ -129,7 +123,7 @@ export class PassportSessionStrategy {
      * @returns `true` when all required permissions are satisfied, `false` otherwise.
      */
     authorize(params) {
-        return checkPermissions(params.auth, params.requiredPermissions);
+        return checkRequiredPermissions(params.auth, params.requiredPermissions);
     }
     openApiScheme() {
         return {

package/dist/auth/strategies/types.d.ts

@@ -45,6 +45,13 @@ export type SecurityScheme = {
     scheme: 'basic';
     description?: string;
 };
+/**
+ * Checks whether an auth context satisfies `requiredPermissions`.
+ * Semantics: **any single match** in `auth.permissions` OR `auth.roles` grants access
+ * (i.e. the list is an OR — "user must have at least one of these"). This mirrors
+ * the documented behaviour of `FieldDefinition.readRoles` / `writeRoles`.
+ */
+export declare function checkRequiredPermissions(auth: AuthContext, requiredPermissions: string[]): boolean;
 /** Contract for pluggable authentication and authorisation strategies. */
 export interface AuthStrategy {
     /**

package/dist/auth/strategies/types.js

@@ -1 +1,13 @@
-export {};
+/**
+ * Checks whether an auth context satisfies `requiredPermissions`.
+ * Semantics: **any single match** in `auth.permissions` OR `auth.roles` grants access
+ * (i.e. the list is an OR — "user must have at least one of these"). This mirrors
+ * the documented behaviour of `FieldDefinition.readRoles` / `writeRoles`.
+ */
+export function checkRequiredPermissions(auth, requiredPermissions) {
+    if (!requiredPermissions.length)
+        return true;
+    const permissions = new Set(auth.permissions ?? []);
+    const roles = new Set(auth.roles ?? []);
+    return requiredPermissions.some((p) => permissions.has(p) || roles.has(p));
+}

package/dist/core/cache/CacheStore.d.ts

@@ -22,4 +22,16 @@ export interface CacheStore {
      * @param key - Cache key to remove.
      */
     delete(key: string): Promise<void> | void;
+    /**
+     * Atomically increment an integer counter and return the new value.
+     * When the key does not exist, it is initialised to `0` before incrementing.
+     *
+     * Implementing this method is **strongly recommended** for multi-process stores
+     * (e.g. Redis) — without it, `createCachingRepository` falls back to a non-atomic
+     * read-then-write version-bump that can lose invalidations under concurrent writes.
+     *
+     * Single-process stores (`InMemoryCacheStore`) can implement this synchronously and
+     * are immune to the race regardless, but should still implement it for correctness.
+     */
+    increment?(key: string): Promise<number> | number;
 }

package/dist/core/cache/createCachingRepository.js

@@ -34,7 +34,16 @@ export function createCachingRepository(repo, options) {
         return typeof v === 'number' ? v : 0;
     };
     const bumpVersion = async () => {
-        await store.set(versionKey, (await readVersion()) + 1);
+        // Use store.increment when available (atomic on Redis via INCR; race-free on
+        // InMemoryCacheStore because Node.js is single-threaded). Fall back to a non-atomic
+        // read-then-write only when the store does not expose increment — acceptable for
+        // custom single-process stores where concurrent writes cannot interleave.
+        if (store.increment) {
+            await store.increment(versionKey);
+        }
+        else {
+            await store.set(versionKey, (await readVersion()) + 1);
+        }
     };
     const keyFor = async (op, payload) => `${namespace}:v${await readVersion()}:${op}:${stableStringify(payload)}`;
     const cachedRead = async (op, payload, run) => {

package/dist/core/cache/in-memory/InMemoryCacheStore.d.ts

@@ -5,15 +5,28 @@ import type { CacheStore } from '../CacheStore.js';
  * Suitable for single-process deployments and tests. For multi-instance deployments,
  * inject a shared store (e.g. `RedisCacheStore`) instead so cache and invalidation are
  * consistent across processes.
+ *
+ * Expired entries are lazily evicted on reads. To prevent unbounded accumulation under
+ * write-heavy workloads, a sweep of all expired entries runs automatically every
+ * `sweepEvery` writes (default: 200). Adjust via the constructor option.
  */
 export declare class InMemoryCacheStore implements CacheStore {
     private readonly now;
     private readonly map;
+    private setCount;
+    private readonly sweepEvery;
     /**
      * @param now - Clock function (ms epoch). Injectable for tests; defaults to `Date.now`.
+     * @param sweepEvery - Run a full expired-entry sweep every N `set` calls. Defaults to 200.
      */
-    constructor(now?: () => number);
+    constructor(now?: () => number, sweepEvery?: number);
     get(key: string): unknown;
     set(key: string, value: unknown, ttlSeconds?: number): void;
     delete(key: string): void;
+    /**
+     * Atomically increments an integer counter and returns the new value.
+     * Because Node.js is single-threaded this is race-free without a lock.
+     */
+    increment(key: string): number;
+    private purgeExpired;
 }

package/dist/core/cache/in-memory/InMemoryCacheStore.js

@@ -4,15 +4,23 @@
  * Suitable for single-process deployments and tests. For multi-instance deployments,
  * inject a shared store (e.g. `RedisCacheStore`) instead so cache and invalidation are
  * consistent across processes.
+ *
+ * Expired entries are lazily evicted on reads. To prevent unbounded accumulation under
+ * write-heavy workloads, a sweep of all expired entries runs automatically every
+ * `sweepEvery` writes (default: 200). Adjust via the constructor option.
  */
 export class InMemoryCacheStore {
     now;
     map = new Map();
+    setCount = 0;
+    sweepEvery;
     /**
      * @param now - Clock function (ms epoch). Injectable for tests; defaults to `Date.now`.
+     * @param sweepEvery - Run a full expired-entry sweep every N `set` calls. Defaults to 200.
      */
-    constructor(now = () => Date.now()) {
+    constructor(now = () => Date.now(), sweepEvery = 200) {
         this.now = now;
+        this.sweepEvery = sweepEvery;
     }
     get(key) {
         const entry = this.map.get(key);
@@ -27,8 +35,28 @@ export class InMemoryCacheStore {
     set(key, value, ttlSeconds) {
         const expiresAt = ttlSeconds && ttlSeconds > 0 ? this.now() + ttlSeconds * 1000 : null;
         this.map.set(key, { value, expiresAt });
+        if (++this.setCount % this.sweepEvery === 0)
+            this.purgeExpired();
     }
     delete(key) {
         this.map.delete(key);
     }
+    /**
+     * Atomically increments an integer counter and returns the new value.
+     * Because Node.js is single-threaded this is race-free without a lock.
+     */
+    increment(key) {
+        const entry = this.map.get(key);
+        const current = typeof entry?.value === 'number' ? entry.value : 0;
+        const next = current + 1;
+        this.map.set(key, { value: next, expiresAt: null });
+        return next;
+    }
+    purgeExpired() {
+        const now = this.now();
+        for (const [key, entry] of this.map) {
+            if (entry.expiresAt !== null && entry.expiresAt <= now)
+                this.map.delete(key);
+        }
+    }
 }

package/dist/core/cache/redis/RedisCacheStore.d.ts

@@ -25,4 +25,10 @@ export declare class RedisCacheStore implements CacheStore {
     get(key: string): Promise<unknown>;
     set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
     delete(key: string): Promise<void>;
+    /**
+     * Atomically increments the integer stored at `key` (using Redis `INCR`) and returns
+     * the new value. Falls back to a non-atomic get-then-set when the underlying client
+     * does not expose `incr` — this should not occur with standard Redis clients.
+     */
+    increment(key: string): Promise<number>;
 }

package/dist/core/cache/redis/RedisCacheStore.js

@@ -39,4 +39,18 @@ export class RedisCacheStore {
     async delete(key) {
         await this.client.del(this.prefix + key);
     }
+    /**
+     * Atomically increments the integer stored at `key` (using Redis `INCR`) and returns
+     * the new value. Falls back to a non-atomic get-then-set when the underlying client
+     * does not expose `incr` — this should not occur with standard Redis clients.
+     */
+    async increment(key) {
+        if (this.client.incr) {
+            return await this.client.incr(this.prefix + key);
+        }
+        const raw = await this.client.get(this.prefix + key);
+        const next = (raw !== null ? parseInt(raw, 10) : 0) + 1;
+        await this.client.set(this.prefix + key, String(next));
+        return next;
+    }
 }

package/dist/core/cache/redis/RedisLikeClient.d.ts

@@ -9,4 +9,6 @@ export interface RedisLikeClient {
         EX?: number;
     }): Promise<unknown>;
     del(key: string): Promise<unknown>;
+    /** Atomic integer increment — maps to Redis `INCR`. Optional but strongly recommended. */
+    incr?(key: string): Promise<number>;
 }

package/dist/core/crudRouter.js

@@ -6,7 +6,7 @@ import { ServerError } from '../errors/ServerError.js';
 import { AuthorizationError } from '../errors/AuthorizationError.js';
 import { MethodNotAllowedError } from '../errors/MethodNotAllowedError.js';
 import { normalizeError, sendError, wantsCacheBust } from '../core/handlerUtils.js';
-import { mergeFieldDefinitions } from '../core/fields.js';
+import { mergeFieldDefinitions, mergeRelationDefinitions, normalizeEnvelope } from '../core/fields.js';
 import { registerCreate } from '../core/handlers/create.js';
 import { registerReadMany } from '../core/handlers/readMany.js';
 import { registerReadOne } from '../core/handlers/readOne.js';
@@ -53,17 +53,6 @@ function resolveFields(resource, idField) {
         ...(field.writeRoles?.length ? { writeRoles: field.writeRoles } : {})
     }));
 }
-/**
- * Merges the repository's relation schema with the resource's own relations, by name.
- */
-function resolveRelations(resource) {
-    const byName = new Map();
-    for (const relation of resource.repository?.relations ?? [])
-        byName.set(relation.name, relation);
-    for (const relation of resource.relations ?? [])
-        byName.set(relation.name, relation);
-    return [...byName.values()];
-}
 /**
  * Produces a fully-resolved resource: `name` filled in, and `fields`/`relations` resolved
  * from the repository schema + the resource's own entries. Every downstream stage operates
@@ -75,16 +64,9 @@ function normalizeResource(resource) {
         ...resource,
         name: resource.name ?? deriveResourceName(resource.routePrefix),
         fields: resolveFields(resource, idField),
-        relations: resolveRelations(resource)
+        relations: mergeRelationDefinitions(resource)
     };
 }
-/**
- * Resolves the effective envelope key. A non-empty string enables wrapping; `null`, `undefined`,
- * and `''` all mean "no envelope".
- */
-function normalizeEnvelope(value) {
-    return typeof value === 'string' && value.length > 0 ? value : null;
-}
 /**
  * Determines the column a resource is tenant-scoped on, with this precedence:
  * explicit `resource.tenant` (or `false` to opt out) → auto-detect the API's default

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.
  */

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,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(', ')}.`);
     }