npm - @edium/halifax - Versions diffs - 2.0.0 → 2.1.0 - Mend

@edium/halifax 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -3,6 +3,20 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [2.1.0]
+### Added
+- **Configurable response envelope.** A new `envelope` option wraps every success response body
+  under a single key (e.g. `envelope: 'data'` → `{ "data": <body> }`). Set it API-wide on
+  `createExpressCrudRouter`/`registerCrudApi` options, or per resource on `ResourceDefinition`
+  (the per-resource setting wins, including an explicit `null`/`''` to opt a single resource out
+  of an API-wide envelope). The wrap is uniform across list, single, create/update/upsert, and
+  the delete confirmation; **error responses are never enveloped**, keeping one stable error
+  contract. Applied at the response boundary (after the cache), so cached payloads are
+  envelope-agnostic. Eases adopting Halifax behind clients that expect a legacy `{ data: ... }`
+  shape. Defaults to off — fully backward compatible.
 ## [2.0.0]
 A breaking release with two themes: **permissive, minimal-by-default resource definitions**

package/README_AUTOCRUD.md CHANGED Viewed

@@ -141,6 +141,39 @@ always pulled all rows:
 { defaultLimit: 0, maxLimit: 0 } // no pagination — return everything
 ```
+## Response Envelope
+By default every success response is sent **bare** — a list is `{ count, results }`, a single
+record is the object itself, a delete is `{ deleted: true }`. To wrap every success body under a
+single key (handy when adopting Halifax behind a client that expects a legacy `{ data: ... }`
+shape), set `envelope` — API-wide or per resource:
+```ts
+// API-wide: every resource's success body is wrapped under "data"
+createExpressCrudRouter(resources, { authStrategy, envelope: 'data' })
+// Per resource (wins over the API-wide setting):
+{ routePrefix: 'posts', repository, envelope: 'data' }
+```
+The wrap is **uniform** — it nests the entire body, it does not reshape it:
+| Endpoint        | Bare (default)            | `envelope: 'data'`                    |
+| --------------- | ------------------------- | ------------------------------------- |
+| List / query    | `{ count, results }`      | `{ data: { count, results } }`        |
+| Read / create   | `{ id, ... }`             | `{ data: { id, ... } }`               |
+| Delete one      | `{ deleted: true }`       | `{ data: { deleted: true } }`         |
+Notes:
+- **Errors are never enveloped** — they always use the `{ errors: [...] }` shape (see below), so
+  clients have one stable error contract regardless of the success envelope.
+- **Precedence** — an explicit per-resource `envelope` always wins, including `null` or `''`,
+  which opts a single resource out of an API-wide envelope. Omit it to inherit the API default.
+- `null`, `undefined`, and `''` all mean "no envelope" (an empty key is rejected as meaningless).
+- The envelope is applied at the response boundary, after the read-through cache, so cached
+  payloads are envelope-agnostic.
 ## Query-String Filtering and Pagination
 ```

package/dist/core/crudRouter.d.ts CHANGED Viewed

@@ -48,6 +48,13 @@ export interface CrudApiOptions {
     tenant?: TenantOptions;
     /** Path segment for the query-builder POST route (default: `'query'`). */
     queryBuilderPath?: string;
+    /**
+     * Wrap every success response body under a single key (e.g. `'data'` → `{ "data": <body> }`)
+     * for all resources. Per-resource {@link ResourceDefinition.envelope} takes precedence.
+     * Error responses are never enveloped. Omit (or set `null`/`''`) for bare bodies — the
+     * default, and backward compatible.
+     */
+    envelope?: string | null;
     /**
      * API-wide read-through caching. Provide a `store` (defaults to an in-process
      * {@link InMemoryCacheStore}) and/or a default `ttlSeconds` applied to every resource that

package/dist/core/crudRouter.js CHANGED Viewed

@@ -169,6 +169,28 @@ 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.
@@ -318,6 +340,9 @@ export function registerCrudApi(server, resources, options = {}) {
         // 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);
@@ -380,11 +405,11 @@ export function registerCrudApi(server, resources, options = {}) {
                 const items = (Array.isArray(req.body) ? req.body : [req.body]).map((item) => filterWritableFields(resource, item));
                 if (items.length === 1) {
                     const result = await repo.createOne(items[0], createOptions);
-                    await res.status(201).json(result);
+                    await writeSuccess(res, 201, result, envelope);
                     return;
                 }
                 const results = await repo.createMany(items, createOptions);
-                await res.status(201).json(results);
+                await writeSuccess(res, 201, results, envelope);
             }));
         }
         if (permissions.allowReadMany) {
@@ -393,7 +418,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 const repo = await resolveRepo(req, auth);
                 const listOptions = parseListOptions(req.query, resource);
                 const results = await repo.getMany(listOptions);
-                await res.status(200).json(results);
+                await writeSuccess(res, 200, results, envelope);
             }));
         }
         if (permissions.allowReadManyWithQueryBuilder) {
@@ -406,7 +431,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 const query = { ...body };
                 validateAdvancedQuery(resource, query);
                 const results = await repo.executeQuery(query);
-                await res.status(200).json(results);
+                await writeSuccess(res, 200, results, envelope);
             }));
         }
         if (permissions.allowReadOne) {
@@ -421,7 +446,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 });
                 if (!result)
                     throw new NotFoundError();
-                await res.status(200).json(result);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowUpdateOne) {
@@ -433,7 +458,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 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) {
@@ -451,7 +476,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 if (!query.where?.length)
                     throw new UnprocessableEntityError('updateMany requires at least one WHERE filter to prevent unintended bulk updates.');
                 const result = await repo.updateMany(query, filteredUpdate);
-                await res.status(200).json(result);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowUpsertOne) {
@@ -463,7 +488,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 const id = parseId(req.params['id']);
                 const body = filterWritableFields(resource, req.body);
                 const result = await repo.upsertOne(id, body);
-                await res.status(200).json(result);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         if (permissions.allowDeleteOne) {
@@ -474,7 +499,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 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) {
@@ -489,7 +514,7 @@ export function registerCrudApi(server, resources, options = {}) {
                 if (!query.where?.length)
                     throw new UnprocessableEntityError('deleteMany requires at least one WHERE filter to prevent unintended bulk deletes.');
                 const result = await repo.deleteMany(query);
-                await res.status(200).json(result);
+                await writeSuccess(res, 200, result, envelope);
             }));
         }
         // 405 fallbacks — only registered when at least one method exists for the path

package/dist/core/types.d.ts CHANGED Viewed

@@ -380,6 +380,16 @@ export interface ResourceDefinition<TRecord = unknown, TCreate = Partial<TRecord
      * `false` to explicitly disable caching for this resource even when a default is configured.
      */
     cache?: ResourceCacheConfig | false;
+    /**
+     * Wrap every success response body for this resource under a single key
+     * (e.g. `'data'` →
+     * `{ "data": <body> }`). Applies uniformly to all success payloads — list
+     * (`{ data: { count, results } }`), single object, create/update/upsert, and the
+     * `{ deleted: true }` confirmation. Error responses are never enveloped.
+     * Overrides the API-wide {@link CrudApiOptions.envelope}. Omit (or set `null`/`''`) for
+     * a bare body — the default, and backward compatible.
+     */
+    envelope?: string | null;
 }
 /** Per-resource read-through cache configuration. */
 export interface ResourceCacheConfig {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@edium/halifax",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Auto-generate type-safe REST CRUD APIs from your data models. Adapter-driven: Express/Fastify/HyperExpress, Prisma (PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, SQLite), JWT/API-key auth, multi-tenancy, a dynamic query builder, and pluggable Redis caching.",
   "author": "David LaTour <david@edium.com>",
   "homepage": "https://github.com/splayfee/halifax#readme",