@edium/halifax 1.0.0 → 2.1.0

package/dist/core/crudRouter.js

@@ -1,6 +1,5 @@
 import { AllowAllAuthStrategy } from '../auth/AuthStrategy.js';
-import { QueryBuilder } from '../classes/QueryBuilder.js';
-import { BadRequestError } from '../errors/BadRequestError.js';
+import { createCachingRepository, InMemoryCacheStore } from '../core/cache/index.js';
 import { HttpError } from '../errors/HttpError.js';
 import { MethodNotAllowedError } from '../errors/MethodNotAllowedError.js';
 import { NotAcceptableError } from '../errors/NotAcceptableError.js';
@@ -10,41 +9,122 @@ import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js'
 import { UnsupportedMediaTypeError } from '../errors/UnsupportedMediaTypeError.js';
 import { defaultCrudPermissions } from '../core/types.js';
 import { parseListOptions } from '../core/queryString.js';
-import { validateAdvancedQuery, validateId, isValidUuid } from '../core/validation.js';
+import { validateAdvancedQuery, validateId, isValidUuid, isValidObjectId } from '../core/validation.js';
 import { ServerError } from '../errors/ServerError.js';
 import { AuthorizationError } from '../errors/AuthorizationError.js';
 /**
  * Parses and validates a raw `:id` route parameter.
  * @param raw - The raw string value from `req.params.id`.
- * @returns A parsed integer for numeric IDs, or the original string for UUIDs.
- * @throws {@link BadRequestError} when the value is not a valid integer or UUID.
+ * @returns A parsed integer for numeric IDs, or the original string for UUID / ObjectId keys.
+ * @throws {@link BadRequestError} when the value is not a valid integer, UUID, or ObjectId.
  */
 function parseId(raw) {
     validateId(raw);
-    if (typeof raw === 'string' && isValidUuid(raw))
+    // UUID and Mongo ObjectId keys are passed through as strings; only numeric ids are parsed.
+    if (typeof raw === 'string' && (isValidUuid(raw) || isValidObjectId(raw)))
         return raw;
     return typeof raw === 'string' ? parseInt(raw, 10) : raw;
 }
 /**
  * Strips non-writable fields from a request body and rejects unknown fields with a 422.
- * Only fields explicitly marked `writable: true` are allowed through; fields with
- * `writable: false` or `writable` unset are silently dropped.
- * @param resource - The resource definition that defines writable fields.
+ * Operates on a {@link normalizeResource | normalized} resource, whose fields carry explicit
+ * `writable` booleans (permissive by default; the primary key protected). Fields with
+ * `writable: false` are silently dropped.
+ * @param resource - The normalized resource definition.
  * @param data - The raw request body key-value map.
- * @returns A new object containing only explicitly writable fields.
+ * @returns A new object containing only writable fields.
  * @throws {@link UnprocessableEntityError} when the body contains keys not defined on the resource.
  */
 function filterWritableFields(resource, data) {
-    const knownFields = new Set(resource.fields.map((f) => f.name));
+    const fields = resource.fields ?? [];
+    const knownFields = new Set(fields.map((f) => f.name));
     const unknownFields = Object.keys(data).filter((key) => !knownFields.has(key));
     if (unknownFields.length) {
         throw new UnprocessableEntityError(`Unknown field(s): ${unknownFields.join(', ')}.`);
     }
     return Object.fromEntries(Object.entries(data).filter(([key]) => {
-        const field = resource.fields.find((f) => f.name === key);
-        return field?.writable === true;
+        const field = fields.find((f) => f.name === key);
+        return field?.writable !== false;
     }));
 }
+/**
+ * Derives a human-readable resource name from a route prefix when none is given:
+ * de-kebabs/de-snakes and title-cases each word (`'blog-posts'` → `'Blog Posts'`).
+ * @param routePrefix - The resource's URL path segment.
+ * @returns A title-cased display name.
+ */
+function deriveResourceName(routePrefix) {
+    return (routePrefix
+        .split(/[-_/\s]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ') || routePrefix);
+}
+/**
+ * Resolves the effective field list for a resource. When the repository exposes a field
+ * schema it forms the base, and the resource's own `fields` are merged over it **by name**
+ * as sparse overrides (entries with no matching base field are added). When the repository
+ * exposes no schema, the resource's `fields` are the authoritative list.
+ *
+ * Every resolved field gets explicit, permissive defaults — `filterable`/`sortable`/
+ * `selectable`/`writable` default to `true` — except the primary key, which is non-writable
+ * unless a field entry explicitly sets `writable: true`.
+ *
+ * @param resource - The raw resource definition.
+ * @param idField - The repository's primary-key field name (protected from writes).
+ * @returns The fully-resolved field list.
+ * @throws {@link ServerError} when neither the repository nor the resource provides any fields.
+ */
+function resolveFields(resource, idField) {
+    const byName = new Map();
+    for (const field of resource.repository?.fields ?? [])
+        byName.set(field.name, { ...field });
+    for (const override of resource.fields ?? [])
+        byName.set(override.name, { ...byName.get(override.name), ...override });
+    const merged = [...byName.values()];
+    if (merged.length === 0) {
+        throw new ServerError(`Resource '${resource.name ?? resource.routePrefix}' has no fields. Provide 'fields', ` +
+            `or construct its repository with a model so the schema can be derived.`);
+    }
+    return merged.map((field) => ({
+        name: field.name,
+        filterable: field.filterable !== false,
+        sortable: field.sortable !== false,
+        selectable: field.selectable !== false,
+        // Permissive by default — but the primary key is protected: writable only when opted in.
+        writable: field.name === idField ? field.writable === true : field.writable !== false
+    }));
+}
+/**
+ * Merges the repository's relation schema with the resource's own relations, by name.
+ * @param resource - The raw resource definition.
+ * @returns The resolved relation list (may be empty).
+ */
+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 (derived from `routePrefix` when
+ * omitted), and `fields`/`relations` resolved from the repository schema + the resource's
+ * own (override) entries. Every downstream router stage operates on this normalized form,
+ * so defaults live in exactly one place.
+ * @param resource - The raw resource definition supplied by the caller.
+ * @returns A normalized resource with guaranteed `name` and resolved `fields`/`relations`.
+ */
+function normalizeResource(resource) {
+    const idField = resource.repository?.idField ?? 'id';
+    return {
+        ...resource,
+        name: resource.name ?? deriveResourceName(resource.routePrefix),
+        fields: resolveFields(resource, idField),
+        relations: resolveRelations(resource)
+    };
+}
 /** Maps HTTP status codes to machine-readable error code strings. */
 const statusCodeMap = {
     400: 'BAD_REQUEST',
@@ -77,35 +157,6 @@ export function normalizeError(error) {
     }
     return { status: 500, code: 'INTERNAL_ERROR', message: 'Internal server error' };
 }
-/**
- * Validates that all identifier-shaped values in a preview query are safe SQL identifiers.
- * Field names and the table name are interpolated directly into SQL strings (not parameterized),
- * so they must match `[a-zA-Z_][a-zA-Z0-9_.]*` to prevent unexpected SQL fragments.
- * @param query - The query AST to inspect.
- * @throws {@link BadRequestError} when any identifier contains disallowed characters.
- */
-function assertSafePreviewIdentifiers(query) {
-    const safe = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
-    const check = (value, label) => {
-        if (!safe.test(value))
-            throw new BadRequestError(`Invalid ${label}: '${value}'.`);
-    };
-    if (query.tableName)
-        check(query.tableName, 'table name');
-    for (const f of query.fields ?? [])
-        check(f, 'field name');
-    for (const s of query.orderBy ?? [])
-        check(s.field, 'sort field');
-    const checkFilters = (filters) => {
-        for (const f of filters) {
-            if (f.field)
-                check(f.field, 'filter field');
-            if (f.children?.length)
-                checkFilters(f.children);
-        }
-    };
-    checkFilters(query.where ?? []);
-}
 /**
  * Serialises a caught error and writes it as a JSON `{ errors: [...] }` response.
  * @param error - The caught value to serialise.
@@ -118,12 +169,35 @@ async function sendError(error, res) {
         item['details'] = details;
     await res.status(status).json({ errors: [item] });
 }
+/**
+ * Resolves the effective envelope key: a non-empty string enables wrapping; `null`, `undefined`,
+ * and `''` all mean "no envelope" (an empty key would produce a meaningless `{ "": body }`).
+ * @param value - The per-resource or API-wide envelope setting.
+ * @returns The envelope key, or `null` when responses should be sent bare.
+ */
+function normalizeEnvelope(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Writes a success body as JSON, wrapping it under `envelope` when one is configured.
+ * The single seam through which every success response is serialised, so the envelope is
+ * applied consistently and exactly once. Applied at the response boundary (after the cache),
+ * so cached payloads stay envelope-agnostic.
+ * @param res - The response object to write to.
+ * @param status - HTTP status code to send.
+ * @param body - The success payload (wrapped under `envelope` when set).
+ * @param envelope - Resolved envelope key, or `null` to send the body bare.
+ */
+function writeSuccess(res, status, body, envelope) {
+    return res.status(status).json(envelope ? { [envelope]: body } : body);
+}
 /**
  * Runs the auth strategy for `action` and throws {@link AuthorizationError} when not allowed.
  * @param req - The incoming HTTP request.
  * @param resource - The resource being accessed (used to look up required permissions).
  * @param action - The CRUD action being performed.
  * @param authStrategy - The active auth strategy.
+ * @returns The resolved {@link AuthContext} (so callers can derive the tenant scope from it).
  */
 async function authorizeRequest(req, resource, action, authStrategy) {
     const auth = await authStrategy.authenticate(req);
@@ -138,7 +212,7 @@ async function authorizeRequest(req, resource, action, authStrategy) {
         });
         if (!allowed)
             throw new AuthorizationError();
-        return;
+        return auth;
     }
     if (requiredPermissions.length) {
         const permissions = new Set(auth.permissions ?? []);
@@ -147,7 +221,28 @@ async function authorizeRequest(req, resource, action, authStrategy) {
         if (!allowed)
             throw new AuthorizationError();
     }
+    return auth;
 }
+/**
+ * Determines the column a resource is tenant-scoped on, applying this precedence:
+ * explicit `resource.tenant` (or `false` to opt out) → auto-detect the API's default
+ * tenant field when the resource actually has it → otherwise unscoped (global).
+ * @param resource - The resource being inspected.
+ * @param tenant - The API-wide tenant options, or `undefined` when tenancy is off.
+ * @returns The tenant field name, or `null` when the resource is not scoped.
+ */
+function effectiveTenantField(resource, tenant) {
+    if (!tenant)
+        return null;
+    if (resource.tenant === false)
+        return null;
+    if (resource.tenant && resource.tenant.field)
+        return resource.tenant.field;
+    const fallback = tenant.field ?? 'tenantId';
+    return (resource.fields ?? []).some((f) => f.name === fallback) ? fallback : null;
+}
+/** Matches a safe SQL identifier — tenant fields are interpolated into SQL on bulk paths. */
+const safeIdentifier = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 /**
  * Reads a single header value by name (case-insensitive).
  * @param req - The incoming HTTP request.
@@ -159,6 +254,22 @@ function getHeaderValue(req, name) {
     const value = Array.isArray(raw) ? raw[0] : raw;
     return typeof value === 'string' ? value : undefined;
 }
+/**
+ * Decides whether the request asks to bypass (bust) the cache. For the standard
+ * `Cache-Control` header this means a `no-cache`/`no-store` directive; for any custom
+ * bust header, mere presence (with a non-empty value) triggers a refresh.
+ * @param req - The incoming HTTP request.
+ * @param header - The configured bust header name.
+ * @returns `true` when the cache should be force-refreshed for this request.
+ */
+function wantsCacheBust(req, header) {
+    const value = getHeaderValue(req, header);
+    if (!value)
+        return false;
+    if (header.toLowerCase() === 'cache-control')
+        return /no-cache|no-store/i.test(value);
+    return true;
+}
 /**
  * Throws {@link UnsupportedMediaTypeError} when a body-carrying request uses a non-JSON Content-Type.
  * @param req - The incoming HTTP request to check.
@@ -209,141 +320,201 @@ function wrap(handler) {
  * Registers all CRUD routes for every resource on the given HTTP server.
  *
  * Routes are controlled by `resource.permissions` merged with {@link defaultCrudPermissions}.
- * A global query-builder preview endpoint is also registered at `previewQueryBuilderPath`.
  *
  * @param server - The HTTP server adapter to register routes on (e.g. {@link ExpressHttpServer}).
  * @param resources - Resource definitions to wire up as CRUD endpoints.
- * @param options - Auth strategy, query-builder path overrides, and preview path overrides.
+ * @param options - Auth strategy and query-builder path overrides.
  */
 export function registerCrudApi(server, resources, options = {}) {
     const authStrategy = options.authStrategy ?? new AllowAllAuthStrategy();
-    const queryBuilderPath = options.queryBuilderPath ?? 'query-builder';
-    const previewPath = options.previewQueryBuilderPath ?? '/query-builder/preview';
-    resources.forEach((resource) => {
-        const repository = resource.repository;
+    const queryBuilderPath = options.queryBuilderPath ?? 'query';
+    // One shared cache store for the whole API (created lazily only if any resource caches),
+    // so version-based invalidation is consistent across requests and resources.
+    const cacheStore = options.cache?.store ?? new InMemoryCacheStore();
+    const bustHeader = options.cache?.bustHeader ?? 'cache-control';
+    resources.forEach((rawResource) => {
+        const repository = rawResource.repository;
         if (!repository)
-            throw new ServerError(`Resource '${resource.name}' does not define a repository.`);
+            throw new ServerError(`Resource '${rawResource.name ?? rawResource.routePrefix}' does not define a repository.`);
+        // Resolve name + field/relation schema once, here, so every downstream stage (validation,
+        // write-filtering, tenant auto-detection, cache namespace) works off a single source of
+        // truth with all defaults already applied.
+        const resource = normalizeResource(rawResource);
+        // Resolve the response envelope once: an explicit per-resource setting wins over the
+        // API-wide default — including an explicit `null`/`''`, which opts this resource out.
+        const envelope = normalizeEnvelope(resource.envelope !== undefined ? resource.envelope : options.envelope);
+        // Resolve tenancy once at registration and fail closed on misconfiguration, so a
+        // scoped resource can never be silently served unscoped at request time.
+        const tenantField = effectiveTenantField(resource, options.tenant);
+        if (tenantField) {
+            if (!safeIdentifier.test(tenantField))
+                throw new ServerError(`Resource '${resource.name}' has an unsafe tenant field name '${tenantField}'.`);
+            if (!repository.withScope)
+                throw new ServerError(`Resource '${resource.name}' is tenant-scoped on '${tenantField}' but its repository ` +
+                    `does not implement withScope(). Refusing to serve it unscoped.`);
+        }
+        // Effective cache TTL: an explicit `cache: false` disables; otherwise per-resource config
+        // wins over the API-wide default. `0` means "never expire" (so `undefined` = no caching).
+        const cacheTtl = resource.cache === false
+            ? undefined
+            : (resource.cache?.ttlSeconds ?? options.cache?.ttlSeconds);
+        const cachingEnabled = cacheTtl !== undefined;
+        /**
+         * Wraps a repository in the read-through cache when caching is enabled for this resource.
+         * The namespace embeds the resource name and tenant key, so one tenant can never read
+         * another's cached rows. `bust` (from the cache-bust header) force-refreshes this request.
+         * @param repo - The (possibly tenant-scoped) repository for this request.
+         * @param scopeKey - Stable key for the current tenant scope (or `'global'`).
+         * @param bust - Whether the caller requested a cache-busting refresh.
+         * @returns The repository, cache-wrapped when caching is enabled.
+         */
+        const withCache = (repo, scopeKey, bust) => cachingEnabled
+            ? createCachingRepository(repo, {
+                store: cacheStore,
+                ttlSeconds: cacheTtl,
+                namespace: `${resource.name}:${scopeKey}`,
+                bust
+            })
+            : repo;
+        /**
+         * Returns the repository to use for this request: the tenant-scoped clone when the
+         * resource is scoped, or the bare repository otherwise — wrapped in the read-through
+         * cache when enabled. Throws 403 in strict mode (the default) when a scoped resource
+         * cannot resolve a tenant for the caller.
+         */
+        const resolveRepo = async (req, auth) => {
+            const bust = cachingEnabled && wantsCacheBust(req, bustHeader);
+            if (!tenantField || !options.tenant)
+                return withCache(repository, 'global', bust);
+            const value = await options.tenant.resolveId({ auth, req, resource });
+            if (value === undefined || value === null || value === '') {
+                if (options.tenant.strict !== false)
+                    throw new AuthorizationError('No tenant is associated with this request.');
+                return withCache(repository, 'global', bust);
+            }
+            return withCache(repository.withScope({ field: tenantField, value }), String(value), bust);
+        };
         const permissions = { ...defaultCrudPermissions, ...resource.permissions };
         const basePath = `/${resource.routePrefix}`;
         if (permissions.allowCreate) {
             server.registerRoute('POST', basePath, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'create', authStrategy);
+                const auth = await authorizeRequest(req, resource, 'create', authStrategy);
+                const repo = await resolveRepo(req, auth);
                 const idempotencyKey = getHeaderValue(req, 'idempotency-key');
                 const createOptions = idempotencyKey ? { idempotencyKey } : undefined;
                 const items = (Array.isArray(req.body) ? req.body : [req.body]).map((item) => filterWritableFields(resource, item));
                 if (items.length === 1) {
-                    const result = await repository.createOne(items[0], createOptions);
-                    await res.status(201).json(result);
+                    const result = await repo.createOne(items[0], createOptions);
+                    await writeSuccess(res, 201, result, envelope);
                     return;
                 }
-                const results = await repository.createMany(items, createOptions);
-                await res.status(201).json(results);
+                const results = await repo.createMany(items, createOptions);
+                await writeSuccess(res, 201, results, envelope);
             }));
         }
         if (permissions.allowReadMany) {
             server.registerRoute('GET', basePath, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'readMany', authStrategy);
+                const auth = await authorizeRequest(req, resource, 'readMany', authStrategy);
+                const repo = await resolveRepo(req, auth);
                 const listOptions = parseListOptions(req.query, resource);
-                const results = await repository.getMany(listOptions);
-                await res.status(200).json(results);
+                const results = await repo.getMany(listOptions);
+                await writeSuccess(res, 200, results, envelope);
             }));
         }
         if (permissions.allowReadManyWithQueryBuilder) {
             server.registerRoute('POST', `${basePath}/${queryBuilderPath}`, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'readManyWithQueryBuilder', authStrategy);
-                if (!repository.executeQueryBuilder)
+                const auth = await authorizeRequest(req, resource, 'readManyWithQueryBuilder', authStrategy);
+                const repo = await resolveRepo(req, auth);
+                if (!repo.executeQuery)
                     throw new NotImplementedError('This resource does not support the query builder.');
                 const body = (req.body ?? {});
-                const query = {
-                    ...body,
-                    tableName: resource.tableName
-                };
+                const query = { ...body };
                 validateAdvancedQuery(resource, query);
-                const results = await repository.executeQueryBuilder(query);
-                await res.status(200).json(results);
+                const results = await repo.executeQuery(query);
+                await writeSuccess(res, 200, results, envelope);
             }));
         }
         if (permissions.allowReadOne) {
             server.registerRoute('GET', `${basePath}/:id`, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'readOne', authStrategy);
+                const auth = await authorizeRequest(req, resource, 'readOne', authStrategy);
+                const repo = await resolveRepo(req, auth);
                 const id = parseId(req.params['id']);
                 const listOptions = parseListOptions(req.query, resource);
-                const result = await repository.getOne(id, {
+                const result = await repo.getOne(id, {
                     fields: listOptions.fields,
                     include: listOptions.include
                 });
                 if (!result)
                     throw new NotFoundError();
-                await res.status(200).json(result);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowUpdateOne) {
             server.registerRoute('PATCH', `${basePath}/:id`, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'updateOne', authStrategy);
+                const auth = await authorizeRequest(req, resource, 'updateOne', authStrategy);
+                const repo = await resolveRepo(req, auth);
                 const id = parseId(req.params['id']);
                 const body = filterWritableFields(resource, req.body);
-                const result = await repository.updateOne(id, body);
+                const result = await repo.updateOne(id, body);
                 if (!result)
                     throw new NotFoundError();
-                await res.status(200).json(result);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowUpdateMany) {
             server.registerRoute('PATCH', basePath, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'updateMany', authStrategy);
-                if (!repository.updateMany)
+                const auth = await authorizeRequest(req, resource, 'updateMany', authStrategy);
+                const repo = await resolveRepo(req, auth);
+                if (!repo.updateMany)
                     throw new NotImplementedError('This resource does not support updateMany.');
                 const { update, ...queryBody } = (req.body ?? {});
                 const filteredUpdate = filterWritableFields(resource, (update ?? {}));
                 if (!Object.keys(filteredUpdate).length)
                     throw new UnprocessableEntityError('updateMany requires at least one writable field in the update payload.');
-                const query = {
-                    ...queryBody,
-                    tableName: resource.tableName
-                };
+                const query = { ...queryBody };
                 validateAdvancedQuery(resource, query);
                 if (!query.where?.length)
                     throw new UnprocessableEntityError('updateMany requires at least one WHERE filter to prevent unintended bulk updates.');
-                const result = await repository.updateMany(query, filteredUpdate);
-                await res.status(200).json(result);
+                const result = await repo.updateMany(query, filteredUpdate);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowUpsertOne) {
             server.registerRoute('PUT', `${basePath}/:id`, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'upsertOne', authStrategy);
-                if (!repository.upsertOne)
+                const auth = await authorizeRequest(req, resource, 'upsertOne', authStrategy);
+                const repo = await resolveRepo(req, auth);
+                if (!repo.upsertOne)
                     throw new NotImplementedError('This resource does not support upsert.');
                 const id = parseId(req.params['id']);
                 const body = filterWritableFields(resource, req.body);
-                const result = await repository.upsertOne(id, body);
-                await res.status(200).json(result);
+                const result = await repo.upsertOne(id, body);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowDeleteOne) {
             server.registerRoute('DELETE', `${basePath}/:id`, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'deleteOne', authStrategy);
+                const auth = await authorizeRequest(req, resource, 'deleteOne', authStrategy);
+                const repo = await resolveRepo(req, auth);
                 const id = parseId(req.params['id']);
-                const deleted = await repository.deleteOne(id);
+                const deleted = await repo.deleteOne(id);
                 if (!deleted)
                     throw new NotFoundError();
-                await res.status(200).json({ deleted: true });
+                await writeSuccess(res, 200, { deleted: true }, envelope);
             }));
         }
         if (permissions.allowDeleteMany) {
             server.registerRoute('DELETE', basePath, wrap(async (req, res) => {
-                await authorizeRequest(req, resource, 'deleteMany', authStrategy);
-                if (!repository.deleteMany)
+                const auth = await authorizeRequest(req, resource, 'deleteMany', authStrategy);
+                const repo = await resolveRepo(req, auth);
+                if (!repo.deleteMany)
                     throw new NotImplementedError('This resource does not support deleteMany.');
                 const body = (req.body ?? {});
-                const query = {
-                    ...body,
-                    tableName: resource.tableName
-                };
+                const query = { ...body };
                 validateAdvancedQuery(resource, query);
                 if (!query.where?.length)
                     throw new UnprocessableEntityError('deleteMany requires at least one WHERE filter to prevent unintended bulk deletes.');
-                const result = await repository.deleteMany(query);
-                await res.status(200).json(result);
+                const result = await repo.deleteMany(query);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         // 405 fallbacks — only registered when at least one method exists for the path
@@ -378,14 +549,4 @@ export function registerCrudApi(server, resources, options = {}) {
             });
         }
     });
-    server.registerRoute('POST', previewPath, wrap(async (req, res) => {
-        await authStrategy.authenticate(req);
-        const query = req.body;
-        assertSafePreviewIdentifiers(query);
-        await res.status(200).json({
-            count: QueryBuilder.buildCountQuery(query),
-            select: QueryBuilder.buildSelectQuery(query)
-        });
-    }));
 }
-//# sourceMappingURL=crudRouter.js.map

package/dist/core/queryString.d.ts

@@ -1,13 +1,13 @@
-import type { ListOptions, ResourceDefinition } from '../core/types.js';
+import { type ListOptions, type ResourceDefinition } from '../core/types.js';
 /**
  * Parses and validates the raw query-string from a GET request into typed {@link ListOptions}.
  *
  * Validates field names, sort fields, includes, and filter keys against the resource schema.
- * Applies `defaultLimit` and `maxLimit` from the resource definition when set.
+ * Applies the resource's `defaultLimit`/`maxLimit`, falling back to the framework page
+ * defaults so the result set is always bounded.
  *
  * @param query - The raw query-string object from the HTTP request.
  * @param resource - The resource definition used for field and relation validation.
  * @returns Typed list options ready to pass to `repository.getMany()`.
  */
 export declare function parseListOptions(query: Record<string, unknown>, resource: ResourceDefinition): ListOptions;
-//# sourceMappingURL=queryString.d.ts.map

package/dist/core/queryString.js

@@ -1,5 +1,6 @@
 import { SqlOrder } from '../enums/SqlOrder.js';
 import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '../core/types.js';
 import { isValidInt32, validateFields, validateIncludes, validateQueryString, validateSelectableFields, validateSortableFields } from '../core/validation.js';
 /**
  * Parses and validates a single integer query-string value.
@@ -34,7 +35,8 @@ function parseCsv(value) {
  * Parses and validates the raw query-string from a GET request into typed {@link ListOptions}.
  *
  * Validates field names, sort fields, includes, and filter keys against the resource schema.
- * Applies `defaultLimit` and `maxLimit` from the resource definition when set.
+ * Applies the resource's `defaultLimit`/`maxLimit`, falling back to the framework page
+ * defaults so the result set is always bounded.
  *
  * @param query - The raw query-string object from the HTTP request.
  * @param resource - The resource definition used for field and relation validation.
@@ -47,10 +49,18 @@ export function parseListOptions(query, resource) {
     let limit = parseInteger(query.limit, 'limit');
     const offset = parseInteger(query.offset, 'offset', 0);
     const order = parseCsv(query.order);
-    if (!limit && resource.defaultLimit)
-        limit = resource.defaultLimit;
-    if (limit && resource.maxLimit && limit > resource.maxLimit)
-        limit = resource.maxLimit;
+    // Page size is bounded by sensible defaults, but a resource can opt out with `0` (= no
+    // bound). `count` in the response always reflects the true total, so a capped page is never
+    // a silent drop. Precedence: an explicit `?limit=` wins; otherwise the resource/default
+    // `defaultLimit` applies; finally a non-zero `maxLimit` caps the result either way.
+    const cap = resource.maxLimit ?? MAX_PAGE_LIMIT;
+    if (limit === undefined) {
+        const fallback = resource.defaultLimit ?? DEFAULT_PAGE_LIMIT;
+        if (fallback !== 0)
+            limit = fallback;
+    }
+    if (cap !== 0 && (limit === undefined || limit > cap))
+        limit = cap;
     if (fields) {
         validateFields(resource, fields);
         validateSelectableFields(resource, fields);
@@ -66,7 +76,7 @@ export function parseListOptions(query, resource) {
         validateSortableFields(resource, orderFields);
     }
     const where = {};
-    const fieldNames = new Set(resource.fields.map((field) => field.name));
+    const fieldNames = new Set((resource.fields ?? []).map((field) => field.name));
     Object.entries(query).forEach(([key, value]) => {
         if (!fieldNames.has(key))
             return;
@@ -86,4 +96,3 @@ export function parseListOptions(query, resource) {
         })
     };
 }
-//# sourceMappingURL=queryString.js.map