@nage-api/compat 1.0.0-beta.2

package/dist/legacy/envelope.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The legacy response body, rebuilt (PLAN.md §23.1).
+ *
+ * §23.1 asks for "the old `Result`/`Created` helpers and the old envelope behind
+ * a flag" so a controller can be ported before its clients are. That needs a
+ * definition of the old body, and this repository does not contain one:
+ * `nest-core-v2` is not a dependency here and `src/core/core.responses.ts` is
+ * not readable from it. What is below is **reconstructed** from the two call
+ * sites PLAN.md quotes — `Result(res, { data, message })` (§4.1) and
+ * `Result(res, { records: rows, offset, limit, count })` (§22, and the
+ * before/after pair in `docs/migration.md`) — plus §16.1's observation that the
+ * old envelope carried `timestamp` on 200s and not on errors.
+ *
+ * So the default builder spreads the payload and stamps a timestamp, which is
+ * the only behaviour both quoted call sites agree on. Anything more specific
+ * would be invention. `legacyBody` is the seam: diff the output against your own
+ * `core.responses.ts` and, where it differs, pass your own builder rather than
+ * patching this one.
+ *
+ * One thing is deliberately **not** reproduced: the legacy `ErrorResponse`
+ * echoed `error.message || error` straight to the client (§5.2), which is how
+ * SQL text and upstream bodies reached callers. `legacyErrorBody` takes an
+ * already-sanitised `ErrorPayload`, so the shape comes back and the leak does
+ * not.
+ */
+import type { ErrorPayload } from '@nage-api/contracts';
+/** What the handler (or the `Result` caller) produced, plus the clock. */
+export interface LegacyBodyInput {
+    readonly payload: unknown;
+    /** ISO-8601; injected rather than read so a test can assert an exact body. */
+    readonly timestamp: string;
+}
+export type LegacyBodyBuilder = (input: LegacyBodyInput) => unknown;
+/** The legacy list body: counters beside the records, not under `meta`. */
+export interface LegacyListBody {
+    readonly records: readonly unknown[];
+    readonly offset: number;
+    readonly limit: number;
+    readonly count: number;
+    readonly timestamp: string;
+}
+/**
+ * Reconstructed legacy success body.
+ *
+ * A page is flattened back out: `records` and the three counters return to the
+ * top level, undoing the `meta.pagination` nesting §16.1 introduced. That is the
+ * whole point of the shim — the service can already return `Paginated<T>` while
+ * the client still reads the fields where it always read them.
+ */
+export declare const defaultLegacyBody: LegacyBodyBuilder;
+/**
+ * Reconstructed legacy error body.
+ *
+ * `code` is carried through even though the legacy body had no such field: a
+ * client that ignores it is unaffected, and one that starts reading it is
+ * already migrating. Nothing else is added, because an error body that grows
+ * during a migration is a body two systems disagree about.
+ */
+export declare function legacyErrorBody(error: ErrorPayload, options?: {
+    readonly timestamp?: string;
+}): Record<string, unknown>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/legacy/envelope.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * The legacy response body, rebuilt (PLAN.md §23.1).
+ *
+ * §23.1 asks for "the old `Result`/`Created` helpers and the old envelope behind
+ * a flag" so a controller can be ported before its clients are. That needs a
+ * definition of the old body, and this repository does not contain one:
+ * `nest-core-v2` is not a dependency here and `src/core/core.responses.ts` is
+ * not readable from it. What is below is **reconstructed** from the two call
+ * sites PLAN.md quotes — `Result(res, { data, message })` (§4.1) and
+ * `Result(res, { records: rows, offset, limit, count })` (§22, and the
+ * before/after pair in `docs/migration.md`) — plus §16.1's observation that the
+ * old envelope carried `timestamp` on 200s and not on errors.
+ *
+ * So the default builder spreads the payload and stamps a timestamp, which is
+ * the only behaviour both quoted call sites agree on. Anything more specific
+ * would be invention. `legacyBody` is the seam: diff the output against your own
+ * `core.responses.ts` and, where it differs, pass your own builder rather than
+ * patching this one.
+ *
+ * One thing is deliberately **not** reproduced: the legacy `ErrorResponse`
+ * echoed `error.message || error` straight to the client (§5.2), which is how
+ * SQL text and upstream bodies reached callers. `legacyErrorBody` takes an
+ * already-sanitised `ErrorPayload`, so the shape comes back and the leak does
+ * not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLegacyBody = void 0;
+exports.legacyErrorBody = legacyErrorBody;
+/** True for a `{ records, pagination }` page, the shape a ported service returns. */
+function isPage(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    if (!Array.isArray(candidate.records))
+        return false;
+    if (candidate.pagination === null || typeof candidate.pagination !== 'object')
+        return false;
+    return typeof candidate.pagination.limit === 'number';
+}
+/** A plain object, as opposed to an array, a date, a class instance or null. */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Reconstructed legacy success body.
+ *
+ * A page is flattened back out: `records` and the three counters return to the
+ * top level, undoing the `meta.pagination` nesting §16.1 introduced. That is the
+ * whole point of the shim — the service can already return `Paginated<T>` while
+ * the client still reads the fields where it always read them.
+ */
+const defaultLegacyBody = ({ payload, timestamp }) => {
+    if (isPage(payload)) {
+        const { offset, limit, count } = payload.pagination;
+        return { records: payload.records, offset, limit, count, timestamp };
+    }
+    // Spread only a plain object. Spreading an array loses it to numeric keys, and
+    // spreading a class instance drops everything on its prototype — both of which
+    // silently produce `{ timestamp }` and nothing else.
+    if (isPlainObject(payload))
+        return { ...payload, timestamp };
+    return { data: payload ?? null, timestamp };
+};
+exports.defaultLegacyBody = defaultLegacyBody;
+/**
+ * Reconstructed legacy error body.
+ *
+ * `code` is carried through even though the legacy body had no such field: a
+ * client that ignores it is unaffected, and one that starts reading it is
+ * already migrating. Nothing else is added, because an error body that grows
+ * during a migration is a body two systems disagree about.
+ */
+function legacyErrorBody(error, options = {}) {
+    return {
+        success: false,
+        message: error.message,
+        code: error.code,
+        ...(error.details === undefined ? {} : { details: error.details }),
+        ...(options.timestamp === undefined ? {} : { timestamp: options.timestamp }),
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/legacy/legacy-envelope.decorator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Opt one route (or one controller) back onto the legacy response body.
+ *
+ * The flag §23.1 asks for is per-route rather than per-application, and that is
+ * a deliberate limit rather than a shortcut. `NageCoreModule` registers
+ * `ResponseInterceptor` unconditionally, so a global "serve the old envelope"
+ * switch would have to win a race with it that is decided by module import
+ * order — a correctness property no reader can see at the call site. Riding on
+ * `@NoEnvelope()` instead makes the core interceptor stand down for exactly the
+ * routes this one handles, whatever order the modules were imported in.
+ *
+ * It also matches how §23.3 phase 5 says to migrate: controller by controller.
+ */
+/** Read by `LegacyEnvelopeInterceptor`; not part of the public contract. */
+export declare const LEGACY_ENVELOPE_METADATA = "nage:compat:legacy-envelope";
+export declare const LegacyEnvelope: () => MethodDecorator & ClassDecorator;
+//# sourceMappingURL=legacy-envelope.decorator.d.ts.map

package/dist/legacy/legacy-envelope.decorator.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Opt one route (or one controller) back onto the legacy response body.
+ *
+ * The flag §23.1 asks for is per-route rather than per-application, and that is
+ * a deliberate limit rather than a shortcut. `NageCoreModule` registers
+ * `ResponseInterceptor` unconditionally, so a global "serve the old envelope"
+ * switch would have to win a race with it that is decided by module import
+ * order — a correctness property no reader can see at the call site. Riding on
+ * `@NoEnvelope()` instead makes the core interceptor stand down for exactly the
+ * routes this one handles, whatever order the modules were imported in.
+ *
+ * It also matches how §23.3 phase 5 says to migrate: controller by controller.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegacyEnvelope = exports.LEGACY_ENVELOPE_METADATA = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nage-api/core");
+/** Read by `LegacyEnvelopeInterceptor`; not part of the public contract. */
+exports.LEGACY_ENVELOPE_METADATA = 'nage:compat:legacy-envelope';
+const LegacyEnvelope = () => (0, common_1.applyDecorators)((0, core_1.NoEnvelope)(), (0, common_1.SetMetadata)(exports.LEGACY_ENVELOPE_METADATA, true));
+exports.LegacyEnvelope = LegacyEnvelope;
+//# sourceMappingURL=legacy-envelope.decorator.js.map

package/dist/legacy/legacy-envelope.interceptor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Serves the legacy body for routes marked `@LegacyEnvelope()` (PLAN.md §23.1).
+ *
+ * The controller has already been ported — it returns data and never touches
+ * `res` — while its clients still read `records`/`offset`/`limit`/`count` at the
+ * top level. This maps one to the other, so the two halves of a migration can
+ * ship weeks apart.
+ *
+ * Errors are **not** remapped. `AllExceptionsFilter` is global and this package
+ * does not replace it, so a failing legacy route answers with the new
+ * `{ success: false, error, meta }` shape. Restoring the old error body would
+ * mean a second filter with its own copy of the status mapping, and the old
+ * shape is the one that leaked (§5.2). See the README.
+ */
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Observable } from 'rxjs';
+import { type CompatOptions } from './options.js';
+export declare class LegacyEnvelopeInterceptor implements NestInterceptor {
+    #private;
+    private readonly reflector;
+    constructor(reflector: Reflector, options?: CompatOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=legacy-envelope.interceptor.d.ts.map

package/dist/legacy/legacy-envelope.interceptor.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Serves the legacy body for routes marked `@LegacyEnvelope()` (PLAN.md §23.1).
+ *
+ * The controller has already been ported — it returns data and never touches
+ * `res` — while its clients still read `records`/`offset`/`limit`/`count` at the
+ * top level. This maps one to the other, so the two halves of a migration can
+ * ship weeks apart.
+ *
+ * Errors are **not** remapped. `AllExceptionsFilter` is global and this package
+ * does not replace it, so a failing legacy route answers with the new
+ * `{ success: false, error, meta }` shape. Restoring the old error body would
+ * mean a second filter with its own copy of the status mapping, and the old
+ * shape is the one that leaked (§5.2). See the README.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegacyEnvelopeInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const operators_1 = require("rxjs/operators");
+const envelope_js_1 = require("./envelope.js");
+const legacy_envelope_decorator_js_1 = require("./legacy-envelope.decorator.js");
+const options_js_1 = require("./options.js");
+let LegacyEnvelopeInterceptor = class LegacyEnvelopeInterceptor {
+    reflector;
+    #options;
+    constructor(reflector, options) {
+        this.reflector = reflector;
+        this.#options = options ?? {};
+    }
+    intercept(context, next) {
+        if (context.getType() !== 'http')
+            return next.handle();
+        const legacy = this.reflector.getAllAndOverride(legacy_envelope_decorator_js_1.LEGACY_ENVELOPE_METADATA, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (legacy !== true)
+            return next.handle();
+        const build = this.#options.body ?? envelope_js_1.defaultLegacyBody;
+        const now = this.#options.now ?? (() => new Date());
+        return next
+            .handle()
+            .pipe((0, operators_1.map)((payload) => build({ payload, timestamp: now().toISOString() })));
+    }
+};
+exports.LegacyEnvelopeInterceptor = LegacyEnvelopeInterceptor;
+exports.LegacyEnvelopeInterceptor = LegacyEnvelopeInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(core_1.Reflector)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(options_js_1.NAGE_COMPAT_OPTIONS)),
+    __metadata("design:paramtypes", [core_1.Reflector, Object])
+], LegacyEnvelopeInterceptor);
+//# sourceMappingURL=legacy-envelope.interceptor.js.map

package/dist/legacy/options.d.ts

@@ -0,0 +1,14 @@
+/** Wiring for the legacy shim; see `envelope.ts` for why `body` is a seam. */
+import type { LegacyBodyBuilder } from './envelope.js';
+export interface CompatOptions {
+    /**
+     * Builds the legacy body. The default is reconstructed from PLAN.md's quoted
+     * call sites; supply your own once you have diffed it against the
+     * `core.responses.ts` your application actually shipped.
+     */
+    readonly body?: LegacyBodyBuilder;
+    /** Injected so a test can assert an exact body; defaults to now. */
+    readonly now?: () => Date;
+}
+export declare const NAGE_COMPAT_OPTIONS: import("@nage-api/core").Token<CompatOptions>;
+//# sourceMappingURL=options.d.ts.map

package/dist/legacy/options.js

@@ -0,0 +1,7 @@
+"use strict";
+/** Wiring for the legacy shim; see `envelope.ts` for why `body` is a seam. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_COMPAT_OPTIONS = void 0;
+const core_1 = require("@nage-api/core");
+exports.NAGE_COMPAT_OPTIONS = (0, core_1.createToken)('NAGE_COMPAT_OPTIONS');
+//# sourceMappingURL=options.js.map

package/dist/legacy/responses.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The legacy manual response builders (PLAN.md §23.1).
+ *
+ * These exist for exactly one job: letting a controller that still declares
+ * `@Res() res: Response` compile and behave inside a `@nage-api` application, so its
+ * import can be repointed in one commit and the `@Res()` removal happens in
+ * another. They are the first step of §23.3 phase 5, not a destination — a route
+ * that writes the response itself is invisible to `ResponseInterceptor` and to
+ * `AllExceptionsFilter`, which is the defect §16.1 replaced.
+ *
+ * The response argument is typed as `LegacyResponse` rather than Express's
+ * `Response`. Two reasons: this package should not pull Express into an
+ * application that runs Fastify, and a two-method interface is a thing a test can
+ * pass without a server.
+ */
+import type { ErrorPayload } from '@nage-api/contracts';
+import { type LegacyBodyBuilder } from './envelope.js';
+/** The part of an HTTP response object these helpers touch. */
+export interface LegacyResponse {
+    status(code: number): LegacyResponse;
+    json(body: unknown): unknown;
+}
+export interface LegacyResponseOptions {
+    /** Override when your `core.responses.ts` built a different body. */
+    readonly body?: LegacyBodyBuilder;
+    /** Injected so a test can assert an exact body; defaults to now. */
+    readonly now?: () => Date;
+}
+/**
+ * `Result(res, payload)` — 200 with the legacy body.
+ *
+ * Returns whatever `res.json` returns so `return Result(res, x)` keeps working
+ * unchanged; the value is Nest's, not ours, and is ignored in `@Res()` mode.
+ */
+export declare function Result(res: LegacyResponse, payload: unknown, options?: LegacyResponseOptions): unknown;
+/** `Created(res, payload)` — the same body at 201. */
+export declare function Created(res: LegacyResponse, payload: unknown, options?: LegacyResponseOptions): unknown;
+/**
+ * `ErrorResponse(res, error)` — the legacy error shape from a *safe* payload.
+ *
+ * The legacy helper of this name took the caught error and echoed
+ * `error.message || error`, which is how SQL text and upstream response bodies
+ * reached clients (§5.2). This one takes an `ErrorPayload` — the sanitised
+ * `{ code, message, details? }` the exception filter produces — so the call site
+ * has to have decided what is safe to say before it can call this at all.
+ */
+export declare function ErrorResponse(res: LegacyResponse, error: ErrorPayload, status: number, options?: LegacyResponseOptions): unknown;
+//# sourceMappingURL=responses.d.ts.map

package/dist/legacy/responses.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * The legacy manual response builders (PLAN.md §23.1).
+ *
+ * These exist for exactly one job: letting a controller that still declares
+ * `@Res() res: Response` compile and behave inside a `@nage-api` application, so its
+ * import can be repointed in one commit and the `@Res()` removal happens in
+ * another. They are the first step of §23.3 phase 5, not a destination — a route
+ * that writes the response itself is invisible to `ResponseInterceptor` and to
+ * `AllExceptionsFilter`, which is the defect §16.1 replaced.
+ *
+ * The response argument is typed as `LegacyResponse` rather than Express's
+ * `Response`. Two reasons: this package should not pull Express into an
+ * application that runs Fastify, and a two-method interface is a thing a test can
+ * pass without a server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Result = Result;
+exports.Created = Created;
+exports.ErrorResponse = ErrorResponse;
+const envelope_js_1 = require("./envelope.js");
+function stamp(options) {
+    return (options.now?.() ?? new Date()).toISOString();
+}
+/**
+ * `Result(res, payload)` — 200 with the legacy body.
+ *
+ * Returns whatever `res.json` returns so `return Result(res, x)` keeps working
+ * unchanged; the value is Nest's, not ours, and is ignored in `@Res()` mode.
+ */
+function Result(res, payload, options = {}) {
+    const build = options.body ?? envelope_js_1.defaultLegacyBody;
+    return res.status(200).json(build({ payload, timestamp: stamp(options) }));
+}
+/** `Created(res, payload)` — the same body at 201. */
+function Created(res, payload, options = {}) {
+    const build = options.body ?? envelope_js_1.defaultLegacyBody;
+    return res.status(201).json(build({ payload, timestamp: stamp(options) }));
+}
+/**
+ * `ErrorResponse(res, error)` — the legacy error shape from a *safe* payload.
+ *
+ * The legacy helper of this name took the caught error and echoed
+ * `error.message || error`, which is how SQL text and upstream response bodies
+ * reached clients (§5.2). This one takes an `ErrorPayload` — the sanitised
+ * `{ code, message, details? }` the exception filter produces — so the call site
+ * has to have decided what is safe to say before it can call this at all.
+ */
+function ErrorResponse(res, error, status, options = {}) {
+    return res.status(status).json((0, envelope_js_1.legacyErrorBody)(error, { timestamp: stamp(options) }));
+}
+//# sourceMappingURL=responses.js.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nage-api/compat",
+  "version": "1.0.0-beta.2",
+  "description": "Legacy envelope shim and migration codemods for moving a nest-core-v2 app onto @nage-api",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nage-codemod": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}