@edium/halifax 2.2.2 → 2.3.0

package/dist/adapters/orm/prisma/PrismaAdapter.js

@@ -1,7 +1,9 @@
-import { NotImplementedError } from '../../../errors/NotImplementedError.js';
+import { ConflictError } from '../../../errors/ConflictError.js';
 import { NotFoundError } from '../../../errors/NotFoundError.js';
+import { NotImplementedError } from '../../../errors/NotImplementedError.js';
 import { ServerError } from '../../../errors/ServerError.js';
-import { astToPrismaWhere, astToPrismaOrderBy } from './astToPrisma.js';
+import { astToPrismaOrderBy, astToPrismaWhere } from './astToPrisma.js';
+import { toInclude, toOrderBy, toSelect } from './helpers.js';
 /** Returns true for Prisma's P2025 "record not found" error. */
 function isNotFoundError(error) {
     return (typeof error === 'object' &&
@@ -9,7 +11,26 @@ function isNotFoundError(error) {
         'code' in error &&
         error.code === 'P2025');
 }
-import { toSelect, toInclude, toOrderBy } from './helpers.js';
+/** Returns true for Prisma's P2002 unique constraint violation. */
+function isDuplicateError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'P2002');
+}
+/**
+ * Returns true for SQL Server's "IDENTITY_INSERT is set to OFF" error (code 544).
+ * MSSQL IDENTITY columns reject any explicit-value INSERT via the driver adapter rather
+ * than surfacing a P2002 duplicate — so this must be caught separately.
+ */
+function isIdentityInsertError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const cause = error.cause;
+    return (typeof cause === 'object' &&
+        cause !== null &&
+        cause.code === 544);
+}
 function prismaTypeToOpenApi(prismaType) {
     switch (prismaType) {
         case 'Int':
@@ -247,7 +268,14 @@ export class PrismaAdapter {
      * @throws ServerError if the Prisma delegate does not support the create method.
      */
     async createOne(data) {
-        return (await this.delegate.create({ data: this.stampTenant(data) }));
+        try {
+            return (await this.delegate.create({ data: this.stampTenant(data) }));
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     /**
      * Creates multiple records in the database using the provided array of data objects.
@@ -260,7 +288,14 @@ export class PrismaAdapter {
         if (!this.delegate.createMany || this.returnCreated) {
             return await Promise.all(data.map((item) => this.createOne(item)));
         }
-        await this.delegate.createMany({ data: data.map((item) => this.stampTenant(item)) });
+        try {
+            await this.delegate.createMany({ data: data.map((item) => this.stampTenant(item)) });
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
         return [];
     }
     /**
@@ -271,19 +306,24 @@ export class PrismaAdapter {
      * @throws ServerError if the Prisma delegate does not support the update method.
      */
     async updateOne(id, data) {
-        // When scoped, confirm the row belongs to the caller's tenant before touching it,
-        // and strip the tenant field from the payload so the row can't be moved tenants.
         if (this.scope) {
-            if (!this.delegate.findFirst) {
-                throw new ServerError('Prisma delegate does not support findFirst (required for tenant scoping).');
+            const scopedWhere = this.scopedWhere({ [this.idField]: id });
+            // Preferred path: delegate.updateMany lets us do a single atomic statement whose
+            // WHERE enforces the tenant boundary, eliminating the TOCTOU window.
+            if (this.delegate.updateMany && this.delegate.findFirst) {
+                const { count } = await this.delegate.updateMany({
+                    where: scopedWhere,
+                    data: this.stripTenant(data)
+                });
+                if (count === 0)
+                    return null;
+                return (await this.delegate.findFirst({ where: scopedWhere }));
             }
-            const owned = await this.delegate.findFirst({
-                where: this.scopedWhere({ [this.idField]: id }),
-                select: { [this.idField]: true }
-            });
-            if (!owned)
-                return null;
-            data = this.stripTenant(data);
+            // updateMany is unavailable — we cannot perform a single atomic scoped update.
+            // A two-step findFirst + unscoped update would introduce a TOCTOU window where a
+            // record could be transferred to another tenant between the check and the write.
+            // Refuse rather than risk a cross-tenant modification.
+            throw new ServerError('Prisma delegate does not support updateMany (required for safe tenant-scoped updateOne).');
         }
         try {
             return (await this.delegate.update({ where: { [this.idField]: id }, data }));
@@ -291,6 +331,8 @@ export class PrismaAdapter {
         catch (error) {
             if (isNotFoundError(error))
                 return null;
+            if (isDuplicateError(error))
+                throw new ConflictError();
             throw error;
         }
     }
@@ -331,33 +373,107 @@ export class PrismaAdapter {
      * @throws ServerError if the Prisma delegate does not support the required methods for upserting records.
      */
     async upsertOne(id, data) {
-        if (!this.delegate.upsert) {
-            throw new NotImplementedError('Prisma delegate does not support upsert.');
-        }
-        // When scoped, an upsert keyed on a unique id could otherwise overwrite a row owned
-        // by another tenant. Reject that case (hidden as "not found"), stamp the tenant on
-        // create, and forbid reassigning the tenant on update.
+        // Scoped upsert: do NOT use delegate.upsert with a bare id where-clause — Prisma's upsert
+        // would execute its `update` branch against any matching record regardless of tenant, giving
+        // a cross-tenant write if a race places another tenant's row at that id. Instead we decompose
+        // into a scoped findFirst + a scoped updateMany (create on miss) so the tenant constraint is
+        // enforced at every statement.
         if (this.scope) {
             if (!this.delegate.findFirst) {
                 throw new ServerError('Prisma delegate does not support findFirst (required for tenant scoping).');
             }
+            const scopedWhere = this.scopedWhere({ [this.idField]: id });
             const existing = (await this.delegate.findFirst({
-                where: { [this.idField]: id }
+                where: scopedWhere
             }));
+            // Defense-in-depth: even though scopedWhere already filters by tenant, verify the
+            // returned record actually belongs to this tenant before treating it as owned.
             if (existing && existing[this.scope.field] !== this.scope.value) {
                 throw new NotFoundError();
             }
+            if (existing) {
+                // Record exists for this tenant — update it atomically via updateMany(scopedWhere)
+                // so the tenant constraint is enforced in the same SQL statement as the write.
+                if (this.delegate.updateMany) {
+                    const { count } = await this.delegate.updateMany({
+                        where: scopedWhere,
+                        data: this.stripTenant(data)
+                    });
+                    if (count === 0) {
+                        // Deleted in the tiny window between findFirst and updateMany — treat as a
+                        // fresh create so the caller gets a record back (consistent with upsert semantics).
+                        try {
+                            return (await this.delegate.create({
+                                data: this.stampTenant({ ...data, [this.idField]: id })
+                            }));
+                        }
+                        catch (error) {
+                            if (isDuplicateError(error))
+                                throw new ConflictError();
+                            if (isIdentityInsertError(error)) {
+                                const anyMatch = await this.delegate.findFirst({ where: { [this.idField]: id } });
+                                if (anyMatch)
+                                    throw new ConflictError();
+                                return (await this.delegate.create({ data: this.stampTenant(data) }));
+                            }
+                            throw error;
+                        }
+                    }
+                    return (await this.delegate.findFirst({ where: scopedWhere }));
+                }
+                // Fallback when updateMany is unavailable (non-standard delegate). The update is still
+                // scoped via the earlier findFirst; the TOCTOU window here is only closeable with a
+                // transaction, which we cannot guarantee across providers.
+                try {
+                    return (await this.delegate.update({
+                        where: { [this.idField]: id },
+                        data: this.stripTenant(data)
+                    }));
+                }
+                catch (error) {
+                    if (isNotFoundError(error))
+                        throw new NotFoundError();
+                    if (isDuplicateError(error))
+                        throw new ConflictError();
+                    throw error;
+                }
+            }
+            // Record does not exist for this tenant — create it with the tenant stamped.
+            try {
+                return (await this.delegate.create({
+                    data: this.stampTenant({ ...data, [this.idField]: id })
+                }));
+            }
+            catch (error) {
+                if (isDuplicateError(error))
+                    throw new ConflictError();
+                if (isIdentityInsertError(error)) {
+                    // MSSQL IDENTITY columns reject any explicit-ID insert. Probe to distinguish a
+                    // cross-tenant ID collision (another tenant owns this ID → ConflictError) from a
+                    // genuinely new row (let the DB assign the ID instead).
+                    const anyMatch = await this.delegate.findFirst({ where: { [this.idField]: id } });
+                    if (anyMatch)
+                        throw new ConflictError();
+                    return (await this.delegate.create({ data: this.stampTenant(data) }));
+                }
+                throw error;
+            }
+        }
+        if (!this.delegate.upsert) {
+            throw new NotImplementedError('Prisma delegate does not support upsert.');
+        }
+        try {
             return (await this.delegate.upsert({
                 where: { [this.idField]: id },
-                create: this.stampTenant(data),
-                update: this.stripTenant(data)
+                create: data,
+                update: data
             }));
         }
-        return (await this.delegate.upsert({
-            where: { [this.idField]: id },
-            create: data,
-            update: data
-        }));
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     /**
      * Deletes a single record identified by its ID. If the record does not exist, it returns false.
@@ -378,15 +494,9 @@ export class PrismaAdapter {
                 });
                 return (result?.count ?? 0) > 0;
             }
-            if (!this.delegate.findFirst) {
-                throw new ServerError('Prisma delegate does not support deleteMany or findFirst (required for tenant scoping).');
-            }
-            const owned = await this.delegate.findFirst({
-                where: this.scopedWhere({ [this.idField]: id }),
-                select: { [this.idField]: true }
-            });
-            if (!owned)
-                return false;
+            // deleteMany is unavailable — we cannot do an atomic scoped delete. A two-step
+            // findFirst + unscoped delete would introduce a TOCTOU cross-tenant deletion risk.
+            throw new ServerError('Prisma delegate does not support deleteMany (required for safe tenant-scoped deleteOne).');
         }
         try {
             await this.delegate.delete({ where: { [this.idField]: id } });

package/dist/adapters/orm/prisma/astToPrisma.js

@@ -3,6 +3,12 @@ import { SqlComparison, SqlOperator, SqlOrder } from '@edium/halifax-types';
  * Splits a `LIKE` pattern into a Prisma string operator based on its `%` wildcards.
  * `%x%` → `contains`, `x%` → `startsWith`, `%x` → `endsWith`, and a wildcard-free value
  * collapses to `equals` (matching SQL `LIKE 'x'` semantics).
+ *
+ * **Known limitation:** interior wildcards (`'foo%bar'`) cannot be expressed with Prisma's
+ * string operators — they fall through to `equals`, which is an exact match, not a
+ * wildcard match. Prisma has no `matches`/`glob` operator without raw SQL. Use `CONTAINS`,
+ * `STARTS WITH`, or `ENDS WITH` comparisons instead of `LIKE` when possible.
+ *
  * @param value - The raw LIKE pattern.
  * @returns A Prisma string-filter object.
  */

package/dist/auth/strategies/JwtClaimsAuthStrategy.js

@@ -1,4 +1,5 @@
 import { AuthenticationError } from '../../errors/AuthenticationError.js';
+import { checkRequiredPermissions } from './types.js';
 /** Authenticates via a Bearer JWT and authorises using roles/permissions embedded in its claims. */
 export class JwtClaimsAuthStrategy {
     verifyToken;
@@ -31,14 +32,7 @@ export class JwtClaimsAuthStrategy {
      * @returns `true` when all required permissions are satisfied, `false` otherwise.
      */
     authorize(params) {
-        if (!params.requiredPermissions.length) {
-            return true;
-        }
-        const permissions = new Set(params.auth.permissions ?? []);
-        const roles = new Set(params.auth.roles ?? []);
-        return params.requiredPermissions.every((permission) => {
-            return permissions.has(permission) || roles.has(permission);
-        });
+        return checkRequiredPermissions(params.auth, params.requiredPermissions);
     }
     openApiScheme() {
         return { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' };

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