ts-procedures 8.3.0 → 8.5.0

package/build/codegen/targets/ts/shared-models.test.js

@@ -0,0 +1,354 @@
+import { describe, it, expect, vi } from 'vitest';
+import { runPipeline } from '../../pipeline.js';
+import { makeApiRoute, makeEnvelope } from '../../__fixtures__/make-envelope.js';
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+/** A reusable `$id`-bearing schema — appears verbatim in multiple routes/scopes. */
+const messageModel = {
+    $id: 'urn:msg',
+    title: 'Message',
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        body: { type: 'string' },
+    },
+    required: ['id', 'body'],
+};
+/**
+ * The same `urn:msg` model appears as a nested property in two scopes
+ * (`messages`, `threads`), and once as the WHOLE response body of a route
+ * (top-level `$id`).
+ */
+function modelEnvelope() {
+    return makeEnvelope([
+        makeApiRoute({
+            name: 'GetMessage',
+            scope: 'messages',
+            fullPath: '/messages/:id',
+            jsonSchema: {
+                req: {
+                    pathParams: {
+                        type: 'object',
+                        properties: { id: { type: 'string' } },
+                        required: ['id'],
+                    },
+                },
+                // Whole response body IS the model (top-level $id) → `Response = Message`.
+                res: { body: { ...messageModel } },
+            },
+        }),
+        makeApiRoute({
+            name: 'ListMessages',
+            scope: 'messages',
+            fullPath: '/messages',
+            jsonSchema: {
+                res: {
+                    body: {
+                        type: 'object',
+                        properties: {
+                            // Model nested inside an array → referenced, not inlined.
+                            items: { type: 'array', items: { ...messageModel } },
+                        },
+                        required: ['items'],
+                    },
+                },
+            },
+        }),
+        makeApiRoute({
+            name: 'GetThread',
+            scope: 'threads',
+            fullPath: '/threads/:id',
+            jsonSchema: {
+                res: {
+                    body: {
+                        type: 'object',
+                        properties: {
+                            // Same model in a SECOND scope.
+                            latest: { ...messageModel },
+                        },
+                        required: ['latest'],
+                    },
+                },
+            },
+        }),
+    ]);
+}
+/** Identical to {@link modelEnvelope} but with every `$id`/`title` stripped. */
+function noModelEnvelope() {
+    return makeEnvelope([
+        makeApiRoute({
+            name: 'GetMessage',
+            scope: 'messages',
+            fullPath: '/messages/:id',
+            jsonSchema: {
+                req: {
+                    pathParams: {
+                        type: 'object',
+                        properties: { id: { type: 'string' } },
+                        required: ['id'],
+                    },
+                },
+                res: {
+                    body: {
+                        type: 'object',
+                        properties: { id: { type: 'string' }, body: { type: 'string' } },
+                        required: ['id', 'body'],
+                    },
+                },
+            },
+        }),
+    ]);
+}
+function findFile(files, suffix) {
+    return files.find((f) => f.path.endsWith(suffix));
+}
+const countMatches = (haystack, re) => (haystack.match(re) ?? []).length;
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('shared models (TS target, ajsc x-named-type)', () => {
+    it('shareModels:true emits _models.ts with exactly one Message type; scopes reference it', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+        });
+        const modelsFile = findFile(files, '_models.ts');
+        expect(modelsFile).toBeDefined();
+        expect(countMatches(modelsFile.code, /export type Message =/g)).toBe(1);
+        // Both scopes that use the model import it and reference Message by name.
+        const messages = findFile(files, 'messages.ts');
+        const threads = findFile(files, 'threads.ts');
+        for (const scope of [messages, threads]) {
+            expect(scope.code).toContain("from './_models'");
+            expect(scope.code).toContain('Message');
+            // No inlined model object literal — the body shape lives only in _models.ts.
+            expect(scope.code).not.toMatch(/body:\s*string;[^}]*}\s*\)/);
+        }
+    });
+    it('a route whose entire response IS the model emits `Response = Message`', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+        });
+        const messages = findFile(files, 'messages.ts');
+        // GetMessage's response body IS the whole model (top-level $id) → the Body
+        // alias is exactly `Message`, the single token replacing the whole schema.
+        expect(messages.code).toMatch(/export type Body = Message\b/);
+        // And the nested-array case references the same model inside Array<…>.
+        expect(messages.code).toMatch(/Array<Message>/);
+    });
+    it('shareModels:false emits NO _models.ts and inlines as before', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: false,
+            namespaceTypes: true,
+        });
+        expect(findFile(files, '_models.ts')).toBeUndefined();
+        const messages = findFile(files, 'messages.ts');
+        // The model is inlined: its properties appear in the scope, no _models import.
+        expect(messages.code).not.toContain("from './_models'");
+        expect(messages.code).toContain('body');
+    });
+    it('regression: a no-$id envelope produces byte-identical scope output for true vs false', async () => {
+        const on = await runPipeline({
+            envelope: noModelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+        });
+        const off = await runPipeline({
+            envelope: noModelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: false,
+            namespaceTypes: true,
+        });
+        // No models exist, so neither run emits _models.ts.
+        expect(findFile(on, '_models.ts')).toBeUndefined();
+        expect(findFile(off, '_models.ts')).toBeUndefined();
+        const onScope = findFile(on, 'messages.ts');
+        const offScope = findFile(off, 'messages.ts');
+        expect(onScope.code).toBe(offScope.code);
+    });
+    it('sharedTypesImport re-exports the model and skips generating its body', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } },
+        });
+        const modelsFile = findFile(files, '_models.ts');
+        expect(modelsFile.code).toContain("export { Message } from '@shared/schemas'");
+        // No generated body when the model is externally imported.
+        expect(modelsFile.code).not.toMatch(/export type Message =/);
+        // Scopes still import Message from ./_models (the single hub).
+        const messages = findFile(files, 'messages.ts');
+        expect(messages.code).toContain("from './_models'");
+        expect(messages.code).toContain('Message');
+    });
+    it('flat mode (namespaceTypes:false) imports Message from ./_models', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: false,
+        });
+        const messages = findFile(files, 'messages.ts');
+        expect(messages.code).toContain("import type { Message } from './_models'");
+    });
+    it('sharedModelsModule re-exports every $id model from the convention module', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+            sharedModelsModule: '@app/schemas',
+        });
+        const modelsFile = findFile(files, '_models.ts');
+        // Re-exported, not generated.
+        expect(modelsFile.code).toContain("export { Message } from '@app/schemas'");
+        expect(countMatches(modelsFile.code, /export type Message =/g)).toBe(0);
+        // Scopes still import the shared name from ./_models.
+        expect(findFile(files, 'messages.ts').code).toContain("from './_models'");
+    });
+    it('explicit sharedTypesImport overrides the sharedModelsModule convention per $id', async () => {
+        const files = await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+            sharedModelsModule: '@app/schemas',
+            sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Message' } },
+        });
+        expect(findFile(files, '_models.ts').code).toContain("export { Message } from '@override/pkg'");
+    });
+    it('emits a neutral summary of the re-exported / generated split via the injected logger', async () => {
+        const lines = [];
+        await runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+            logger: (m) => lines.push(m),
+        });
+        expect(lines.join('\n')).toContain('Shared models: 1 total — 0 re-exported, 1 generated locally.');
+    });
+    it('does not emit a summary when there are no $id-bearing models', async () => {
+        const lines = [];
+        await runPipeline({
+            envelope: noModelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+            logger: (m) => lines.push(m),
+        });
+        expect(lines.join('\n')).not.toContain('Shared models:');
+    });
+    it('stays silent (no console output) when no logger is injected', async () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
+        try {
+            await runPipeline({
+                envelope: modelEnvelope(),
+                outDir: 'out',
+                dryRun: true,
+                shareModels: true,
+                namespaceTypes: true,
+                selfContained: false,
+            });
+            expect(log.mock.calls.flat().join('\n')).not.toContain('Shared models:');
+        }
+        finally {
+            log.mockRestore();
+        }
+    });
+    it('strictSharedModels throws listing the offending $id and derived name', async () => {
+        await expect(runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+            strictSharedModels: true,
+        })).rejects.toThrow(/--strict-shared-models[\s\S]*urn:msg[\s\S]*Message/);
+    });
+    it('strictSharedModels passes once every model is covered by the convention', async () => {
+        await expect(runPipeline({
+            envelope: modelEnvelope(),
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+            strictSharedModels: true,
+            sharedModelsModule: '@app/schemas',
+        })).resolves.toBeDefined();
+    });
+    it('fails loudly when a shared model name collides with a property-derived sub-type', async () => {
+        // `latest` references the Message model; a sibling property literally named
+        // `message` would make ajsc extract a structural sub-type ALSO named
+        // `Message`. ajsc silently merges the two (the model reference resolves to
+        // the unrelated structural type), so codegen must reject this rather than
+        // emit a silently-wrong type. See assertNoModelNameCollision in emit-scope.
+        const collision = makeEnvelope([
+            makeApiRoute({
+                name: 'GetThread',
+                scope: 'chat',
+                fullPath: '/thread',
+                jsonSchema: {
+                    res: {
+                        body: {
+                            type: 'object',
+                            required: ['latest', 'message'],
+                            properties: {
+                                latest: {
+                                    type: 'object',
+                                    $id: 'urn:msg',
+                                    title: 'Message',
+                                    required: ['id'],
+                                    properties: { id: { type: 'string' } },
+                                },
+                                message: {
+                                    type: 'object',
+                                    required: ['unread'],
+                                    properties: { unread: { type: 'boolean' } },
+                                },
+                            },
+                        },
+                    },
+                },
+            }),
+        ]);
+        await expect(runPipeline({
+            envelope: collision,
+            outDir: 'out',
+            dryRun: true,
+            shareModels: true,
+            namespaceTypes: true,
+            selfContained: false,
+        })).rejects.toThrow(/shared model 'Message' collides/);
+    });
+});
+//# sourceMappingURL=shared-models.test.js.map

package/build/codegen/targets/ts/shared-models.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-models.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/ts/shared-models.test.ts"],"names":[],"mappings":"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"}

package/build/doc-envelope.d.ts

@@ -0,0 +1,13 @@
+import type { DocEnvelope } from './implementations/types.js';
+export type DocEnvelopeSource = DocEnvelope | {
+    toDocEnvelope(): DocEnvelope;
+} | {
+    toJSON(): DocEnvelope;
+};
+/**
+ * Serializes a doc envelope to disk as pretty JSON so codegen can run offline
+ * via `--file <path>` without a running server. Accepts a plain `DocEnvelope`,
+ * a builder exposing `toDocEnvelope()`, or a `DocRegistry` exposing `toJSON()`.
+ * Parent directories are created as needed.
+ */
+export declare function writeDocEnvelope(source: DocEnvelopeSource, path: string): Promise<void>;

package/build/doc-envelope.js

@@ -0,0 +1,23 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+function coerceToEnvelope(source) {
+    if (typeof source.toDocEnvelope === 'function') {
+        return source.toDocEnvelope();
+    }
+    if (typeof source.toJSON === 'function') {
+        return source.toJSON();
+    }
+    return source;
+}
+/**
+ * Serializes a doc envelope to disk as pretty JSON so codegen can run offline
+ * via `--file <path>` without a running server. Accepts a plain `DocEnvelope`,
+ * a builder exposing `toDocEnvelope()`, or a `DocRegistry` exposing `toJSON()`.
+ * Parent directories are created as needed.
+ */
+export async function writeDocEnvelope(source, path) {
+    const envelope = coerceToEnvelope(source);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(envelope, null, 2), 'utf8');
+}
+//# sourceMappingURL=doc-envelope.js.map

package/build/doc-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-envelope.js","sourceRoot":"","sources":["../src/doc-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAQnC,SAAS,gBAAgB,CAAC,MAAyB;IACjD,IAAI,OAAQ,MAAsC,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;QAChF,OAAQ,MAA2C,CAAC,aAAa,EAAE,CAAA;IACrE,CAAC;IACD,IAAI,OAAQ,MAA+B,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAClE,OAAQ,MAAoC,CAAC,MAAM,EAAE,CAAA;IACvD,CAAC;IACD,OAAO,MAAqB,CAAA;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAyB,EAAE,IAAY;IAC5E,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAA;IACzC,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AAClE,CAAC"}

package/build/doc-envelope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/doc-envelope.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { readFile, rm, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeDocEnvelope } from './doc-envelope.js';
+const envelope = { basePath: '', headers: [], errors: [], routes: [] };
+describe('writeDocEnvelope', () => {
+    let dir;
+    afterEach(async () => { if (dir)
+        await rm(dir, { recursive: true, force: true }); });
+    it('writes a plain DocEnvelope as pretty JSON', async () => {
+        dir = await mkdtemp(join(tmpdir(), 'tsp-'));
+        const out = join(dir, 'nested', 'docs.json');
+        await writeDocEnvelope(envelope, out);
+        const parsed = JSON.parse(await readFile(out, 'utf8'));
+        expect(parsed).toEqual(envelope);
+    });
+    it('accepts a builder-like object with toDocEnvelope()', async () => {
+        dir = await mkdtemp(join(tmpdir(), 'tsp-'));
+        const out = join(dir, 'docs.json');
+        await writeDocEnvelope({ toDocEnvelope: () => envelope }, out);
+        expect(JSON.parse(await readFile(out, 'utf8'))).toEqual(envelope);
+    });
+    it('accepts a DocRegistry-like object (toJSON)', async () => {
+        dir = await mkdtemp(join(tmpdir(), 'tsp-'));
+        const out = join(dir, 'docs.json');
+        await writeDocEnvelope({ toJSON: () => envelope }, out);
+        expect(JSON.parse(await readFile(out, 'utf8'))).toEqual(envelope);
+    });
+});
+//# sourceMappingURL=doc-envelope.test.js.map

package/build/doc-envelope.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-envelope.test.js","sourceRoot":"","sources":["../src/doc-envelope.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAGpD,MAAM,QAAQ,GAAgB,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;AAEnF,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,IAAI,GAAW,CAAA;IACf,SAAS,CAAC,KAAK,IAAI,EAAE,GAAG,IAAI,GAAG;QAAE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA,CAAC,CAAC,CAAC,CAAA;IAEnF,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAA;QAC5C,MAAM,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;QAClC,MAAM,gBAAgB,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAA;QAC9D,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;QAClC,MAAM,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAA;QACvD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/exports.d.ts

@@ -7,3 +7,5 @@ export * from './schema/resolve-schema-lib.js';
 export * from './schema/types.js';
 export type { HttpReturn } from './create-http.js';
 export type { TCreateHttpConfig } from './types.js';
+export { writeDocEnvelope, type DocEnvelopeSource } from './doc-envelope.js';
+export type { DocEnvelope } from './implementations/types.js';

package/build/exports.js

@@ -5,4 +5,5 @@ export * from './schema/extract-json-schema.js';
 export * from './schema/parser.js';
 export * from './schema/resolve-schema-lib.js';
 export * from './schema/types.js';
+export { writeDocEnvelope } from './doc-envelope.js';
 //# sourceMappingURL=exports.js.map

package/build/exports.js.map

@@ -1 +1 @@
-{"version":3,"file":"exports.js","sourceRoot":"","sources":["../src/exports.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,oBAAoB,CAAA;AAClC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"exports.js","sourceRoot":"","sources":["../src/exports.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,oBAAoB,CAAA;AAClC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,mBAAmB,CAAA;AAGjC,OAAO,EAAE,gBAAgB,EAA0B,MAAM,mBAAmB,CAAA"}