@contractkit/plugin-typescript 0.28.2 → 0.30.0

package/src/ts-render.ts

@@ -1,7 +1,9 @@
 import type { ContractTypeNode, FieldNode, ScalarTypeNode } from '@contractkit/core';
 
+/** Declaration emitted into generated files that reference the `json` scalar. */
 export const JSON_VALUE_TYPE_DECL = 'export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };';
 
+/** Quote a property name unless it is already a valid bare TypeScript identifier. */
 export function quoteKey(name: string): string {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `'${name}'`;
 }
@@ -31,12 +33,25 @@ export function headerNameToProperty(name: string): string {
 
 // ─── TypeScript type rendering ────────────────────────────────────────────
 
-export function renderTsType(type: ContractTypeNode): string {
+/**
+ * Which runtime the emitted types describe. A few scalars have no single correct TypeScript
+ * type: `binary` is a `Blob` in a fetch-based client but a `Buffer` on a Node server. Everything
+ * else renders identically for both targets. Defaults to `'client'`.
+ */
+export type TsRenderTarget = 'client' | 'server';
+
+/**
+ * Render a contract type as a plain TypeScript type expression. Model refs render as their bare
+ * name; use `renderInputTsType` / `renderOutputTsType` to substitute Input/Output variants.
+ *
+ * @param target Runtime the type describes; only `binary` differs (`Buffer` vs `Blob`).
+ */
+export function renderTsType(type: ContractTypeNode, target: TsRenderTarget = 'client'): string {
     switch (type.kind) {
         case 'scalar':
-            return renderTsScalar(type.name);
+            return renderTsScalar(type.name, target);
         case 'array': {
-            const inner = renderTsType(type.item);
+            const inner = renderTsType(type.item, target);
             const needsParens =
                 type.item.kind === 'union' ||
                 type.item.kind === 'discriminatedUnion' ||
@@ -45,31 +60,31 @@ export function renderTsType(type: ContractTypeNode): string {
             return needsParens ? `(${inner})[]` : `${inner}[]`;
         }
         case 'tuple':
-            return `[${type.items.map(renderTsType).join(', ')}]`;
+            return `[${type.items.map(i => renderTsType(i, target)).join(', ')}]`;
         case 'record':
-            return `Record<${renderTsType(type.key)}, ${renderTsType(type.value)}>`;
+            return `Record<${renderTsType(type.key, target)}, ${renderTsType(type.value, target)}>`;
         case 'enum':
             return type.values.map(v => `'${escapeSingleQuoted(v)}'`).join(' | ');
         case 'literal':
             return typeof type.value === 'string' ? `'${escapeSingleQuoted(type.value)}'` : String(type.value);
         case 'union':
-            return type.members.map(renderTsType).join(' | ');
+            return type.members.map(m => renderTsType(m, target)).join(' | ');
         case 'discriminatedUnion':
-            return type.members.map(renderTsType).join(' | ');
+            return type.members.map(m => renderTsType(m, target)).join(' | ');
         case 'intersection':
-            return type.members.map(renderTsType).join(' & ');
+            return type.members.map(m => renderTsType(m, target)).join(' & ');
         case 'ref':
             return type.name;
         case 'lazy':
-            return renderTsType(type.inner);
+            return renderTsType(type.inner, target);
         case 'inlineObject':
-            return renderTsInlineObject(type.fields);
+            return renderTsInlineObject(type.fields, target);
         default:
             return 'unknown';
     }
 }
 
-function renderTsScalar(name: ScalarTypeNode['name']): string {
+function renderTsScalar(name: ScalarTypeNode['name'], target: TsRenderTarget): string {
     switch (name) {
         case 'string':
         case 'email':
@@ -96,7 +111,8 @@ function renderTsScalar(name: ScalarTypeNode['name']): string {
         case 'object':
             return 'Record<string, unknown>';
         case 'binary':
-            return 'Blob';
+            // Node servers hand the handler a Buffer (matching `_ZodBinary`); fetch clients get a Blob.
+            return target === 'server' ? 'Buffer' : 'Blob';
         case 'json':
             return 'JsonValue';
         default: {
@@ -106,10 +122,10 @@ function renderTsScalar(name: ScalarTypeNode['name']): string {
     }
 }
 
-function renderTsInlineObject(fields: FieldNode[]): string {
+function renderTsInlineObject(fields: FieldNode[], target: TsRenderTarget): string {
     const entries = fields.map(f => {
         const opt = f.optional ? '?' : '';
-        return `${quoteKey(f.name)}${opt}: ${renderTsType(f.type)}`;
+        return `${quoteKey(f.name)}${opt}: ${renderTsType(f.type, target)}`;
     });
     return `{ ${entries.join('; ')} }`;
 }
@@ -118,14 +134,16 @@ function renderTsInlineObject(fields: FieldNode[]): string {
  * Like renderTsType, but substitutes model refs with their Input variant
  * when the model has visibility modifiers. Used for request-side types
  * (body, params, query, headers).
+ *
+ * @param target Runtime the type describes; only `binary` differs (`Buffer` vs `Blob`).
  */
-export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<string>): string {
-    if (!modelsWithInput || modelsWithInput.size === 0) return renderTsType(type);
+export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<string>, target: TsRenderTarget = 'client'): string {
+    if (!modelsWithInput || modelsWithInput.size === 0) return renderTsType(type, target);
     switch (type.kind) {
         case 'ref':
             return modelsWithInput.has(type.name) ? `${type.name}Input` : type.name;
         case 'array': {
-            const inner = renderInputTsType(type.item, modelsWithInput);
+            const inner = renderInputTsType(type.item, modelsWithInput, target);
             const needsParens =
                 type.item.kind === 'union' ||
                 type.item.kind === 'discriminatedUnion' ||
@@ -134,17 +152,17 @@ export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<
             return needsParens ? `(${inner})[]` : `${inner}[]`;
         }
         case 'intersection':
-            return type.members.map(m => renderInputTsType(m, modelsWithInput)).join(' & ');
+            return type.members.map(m => renderInputTsType(m, modelsWithInput, target)).join(' & ');
         case 'union':
-            return type.members.map(m => renderInputTsType(m, modelsWithInput)).join(' | ');
+            return type.members.map(m => renderInputTsType(m, modelsWithInput, target)).join(' | ');
         case 'discriminatedUnion':
-            return type.members.map(m => renderInputTsType(m, modelsWithInput)).join(' | ');
+            return type.members.map(m => renderInputTsType(m, modelsWithInput, target)).join(' | ');
         case 'inlineObject':
-            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderInputTsType(f.type, modelsWithInput)}`).join('; ')} }`;
+            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderInputTsType(f.type, modelsWithInput, target)}`).join('; ')} }`;
         case 'lazy':
-            return renderInputTsType(type.inner, modelsWithInput);
+            return renderInputTsType(type.inner, modelsWithInput, target);
         default:
-            return renderTsType(type);
+            return renderTsType(type, target);
     }
 }
 
@@ -153,14 +171,16 @@ export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<
  * (post-transform wire shape) when the model has format(output=...) or
  * transitively references one. Used for response-side types in routers
  * and SDK return types.
+ *
+ * @param target Runtime the type describes; only `binary` differs (`Buffer` vs `Blob`).
  */
-export function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Set<string>): string {
-    if (!modelsWithOutput || modelsWithOutput.size === 0) return renderTsType(type);
+export function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Set<string>, target: TsRenderTarget = 'client'): string {
+    if (!modelsWithOutput || modelsWithOutput.size === 0) return renderTsType(type, target);
     switch (type.kind) {
         case 'ref':
             return modelsWithOutput.has(type.name) ? `${type.name}Output` : type.name;
         case 'array': {
-            const inner = renderOutputTsType(type.item, modelsWithOutput);
+            const inner = renderOutputTsType(type.item, modelsWithOutput, target);
             const needsParens =
                 type.item.kind === 'union' ||
                 type.item.kind === 'discriminatedUnion' ||
@@ -169,16 +189,16 @@ export function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Se
             return needsParens ? `(${inner})[]` : `${inner}[]`;
         }
         case 'intersection':
-            return type.members.map(m => renderOutputTsType(m, modelsWithOutput)).join(' & ');
+            return type.members.map(m => renderOutputTsType(m, modelsWithOutput, target)).join(' & ');
         case 'union':
-            return type.members.map(m => renderOutputTsType(m, modelsWithOutput)).join(' | ');
+            return type.members.map(m => renderOutputTsType(m, modelsWithOutput, target)).join(' | ');
         case 'discriminatedUnion':
-            return type.members.map(m => renderOutputTsType(m, modelsWithOutput)).join(' | ');
+            return type.members.map(m => renderOutputTsType(m, modelsWithOutput, target)).join(' | ');
         case 'inlineObject':
-            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderOutputTsType(f.type, modelsWithOutput)}`).join('; ')} }`;
+            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderOutputTsType(f.type, modelsWithOutput, target)}`).join('; ')} }`;
         case 'lazy':
-            return renderOutputTsType(type.inner, modelsWithOutput);
+            return renderOutputTsType(type.inner, modelsWithOutput, target);
         default:
-            return renderTsType(type);
+            return renderTsType(type, target);
     }
 }

package/tests/codegen-operation.test.ts

@@ -101,6 +101,66 @@ describe('generateOperation', () => {
             const output = generateOp(root);
             expect(output).not.toContain('luxon');
         });
+
+        // Every conditional import must be justified by a reference in the generated body —
+        // an unused import trips `noUnusedLocals` and lint in the consuming project.
+        it('imports bodyParserMiddleware only when an operation has a request body', () => {
+            const withBody = generateOp(opRoot([opRoute('/users', [opOperation('post', { request: opRequest('CreateUser') })])]));
+            expect(withBody).toContain('bodyParserMiddleware');
+
+            const withoutBody = generateOp(opRoot([opRoute('/users', [opOperation('get')])]));
+            expect(withoutBody).not.toContain('bodyParserMiddleware');
+        });
+
+        it('omits MultipartBody when a multipart body shares its shape with the other MIME types', () => {
+            // Structurally equal bodies collapse to a single parseAndValidate call, so nothing
+            // references MultipartBody even though the operation does declare multipart.
+            const root = opRoot([
+                opRoute('/upload', [
+                    opOperation('post', {
+                        request: opMultiRequest([
+                            ['multipart/form-data', 'UploadForm'],
+                            ['application/json', 'UploadForm'],
+                        ]),
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).not.toContain('MultipartBody');
+        });
+
+        it('imports MultipartBody when the multipart body is handled on its own', () => {
+            const root = opRoot([opRoute('/upload', [opOperation('post', { request: opMultiRequest([['multipart/form-data', 'UploadForm']]) })])]);
+            expect(generateOp(root)).toContain("import { MultipartBody } from '@maroonedsoftware/multipart';");
+        });
+
+        it('leaves no import unreferenced in the generated body', () => {
+            const root = opRoot([
+                opRoute(
+                    '/users/{id}',
+                    [
+                        opOperation('get', { security: SECURITY_NONE }),
+                        opOperation('post', { request: opRequest('CreateUser'), signature: 'webhookKey' }),
+                    ],
+                    [opParam('id', scalarType('uuid'))],
+                ),
+            ]);
+            const output = generateOp(root);
+            const importLines = output.split('\n').filter(l => l.startsWith('import '));
+            expect(importLines.length).toBeGreaterThan(0);
+
+            const bodyText = output
+                .split('\n')
+                .filter(l => !l.startsWith('import '))
+                .join('\n');
+            for (const line of importLines) {
+                const named = line.match(/^import \{([^}]*)\}/);
+                if (!named) continue;
+                for (const symbol of named[1]!.split(',').map(s => s.trim().replace(/^type /, ''))) {
+                    expect(bodyText, `${symbol} is imported but never used`).toMatch(new RegExp(`\\b${symbol}\\b`));
+                }
+            }
+        });
     });
 
     // ─── Handler signature ─────────────────────────────────────────
@@ -658,6 +718,77 @@ describe('generateOperation', () => {
             const output = generateOp(root, { modelsWithOutput: new Set(['AuthToken']) });
             expect(output).toContain('result: AuthTokenOutput[]');
         });
+
+        // Scalar response bodies used to emit the .ck scalar name verbatim (`result: binary`),
+        // which only happened to compile for `string`.
+        describe('scalar response bodies map to the server-side TypeScript type', () => {
+            const cases: Array<[string, string]> = [
+                ['binary', 'Buffer'],
+                ['int', 'number'],
+                ['number', 'number'],
+                ['bigint', 'bigint'],
+                ['boolean', 'boolean'],
+                ['string', 'string'],
+                ['uuid', 'string'],
+                ['email', 'string'],
+                ['url', 'string'],
+                ['datetime', 'DateTime'],
+                ['date', 'DateTime'],
+                ['time', 'DateTime'],
+                ['duration', 'Duration'],
+                ['interval', 'string'],
+                ['json', '_JsonValue'],
+                ['object', 'Record<string, unknown>'],
+                ['unknown', 'unknown'],
+                ['null', 'null'],
+            ];
+
+            for (const [scalar, tsType] of cases) {
+                it(`renders ${scalar} as ${tsType}`, () => {
+                    const root = opRoot([
+                        opRoute('/x', [
+                            opOperation('get', {
+                                responses: [opResponse(200, scalarType(scalar as never), 'application/octet-stream')],
+                            }),
+                        ]),
+                    ]);
+                    expect(generateOp(root)).toContain(`const result: ${tsType} = await service.list();`);
+                });
+            }
+
+            it('renders an array of binary as Buffer[]', () => {
+                const root = opRoot([
+                    opRoute('/x', [opOperation('get', { responses: [opResponse(200, arrayType(scalarType('binary')), 'application/json')] })]),
+                ]);
+                expect(generateOp(root)).toContain('const result: Buffer[] = await service.list();');
+            });
+        });
+
+        describe('luxon imports cover every scalar that references a luxon class', () => {
+            it('imports Duration for a duration response body', () => {
+                const root = opRoot([opRoute('/x', [opOperation('get', { responses: [opResponse(200, scalarType('duration'), 'application/json')] })])]);
+                expect(generateOp(root)).toContain("import { Duration } from 'luxon';");
+            });
+
+            it('imports Interval and emits the _ZodInterval helper for an interval body', () => {
+                const root = opRoot([opRoute('/x', [opOperation('get', { responses: [opResponse(200, scalarType('interval'), 'application/json')] })])]);
+                const output = generateOp(root);
+                expect(output).toContain("import { Interval } from 'luxon';");
+                expect(output).toContain('const _ZodInterval =');
+            });
+
+            it('imports DateTime and Duration together when both are used', () => {
+                const root = opRoot([
+                    opRoute('/x', [
+                        opOperation('post', {
+                            request: opRequest(scalarType('datetime')),
+                            responses: [opResponse(200, scalarType('duration'), 'application/json')],
+                        }),
+                    ]),
+                ]);
+                expect(generateOp(root)).toContain("import { DateTime, Duration } from 'luxon';");
+            });
+        });
     });
 
     // ─── Service inference ────────────────────────────────────────
@@ -903,7 +1034,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
             expect(out).not.toContain('requireSignature');
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy }`);
+            expect(out).toContain(`import { ServerKitRouter, requirePolicy }`);
         });
     });
 
@@ -914,7 +1045,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             const op = opOperation('get');
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy }`);
+            expect(out).toContain(`import { ServerKitRouter, requirePolicy }`);
             expect(out).toContain(`requirePolicy()`);
         });
 
@@ -948,7 +1079,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             const op = opOperation('get', { security: SECURITY_NONE });
             const root = opRoot([opRoute('/health', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware }`);
+            expect(out).toContain(`import { ServerKitRouter } from`);
             expect(out).not.toContain('requirePolicy');
         });
 

package/tests/codegen-plain-types.test.ts

@@ -98,6 +98,54 @@ describe('generatePlainTypes', () => {
             expect(output).toContain('o: Record<string, unknown>;');
             expect(output).toContain('bin: Blob;');
         });
+
+        // `binary` is the one scalar with no runtime-independent TypeScript type: a fetch client
+        // sees a Blob, a Koa handler sees the Buffer that _ZodBinary validates.
+        describe('binary follows the render target', () => {
+            const ctx = (target: 'client' | 'server') => ({
+                modelOutPaths: new Map<string, string>(),
+                currentOutPath: 'out.ts',
+                target,
+            });
+
+            it('renders Buffer for the server target', () => {
+                const root = contractRoot([model('M', [field('bin', scalarType('binary'))])]);
+                expect(generatePlainTypes(root, ctx('server'))).toContain('bin: Buffer;');
+            });
+
+            it('renders Blob for the client target', () => {
+                const root = contractRoot([model('M', [field('bin', scalarType('binary'))])]);
+                expect(generatePlainTypes(root, ctx('client'))).toContain('bin: Blob;');
+            });
+
+            it('defaults to the client target when unset', () => {
+                const root = contractRoot([model('M', [field('bin', scalarType('binary'))])]);
+                expect(generatePlainTypes(root)).toContain('bin: Blob;');
+            });
+
+            it('applies to nested and compound positions', () => {
+                const root = contractRoot([
+                    model('M', [
+                        field('list', arrayType(scalarType('binary'))),
+                        field('nested', inlineObjectType([field('bin', scalarType('binary'))])),
+                        field('map', recordType(scalarType('string'), scalarType('binary'))),
+                    ]),
+                ]);
+                const output = generatePlainTypes(root, ctx('server'));
+                expect(output).toContain('list: Buffer[];');
+                expect(output).toContain('nested: { bin: Buffer };');
+                expect(output).toContain('map: Record<string, Buffer>;');
+            });
+
+            it('applies to type aliases and their Input variants', () => {
+                const root = contractRoot([
+                    model('Blob1', [field('bin', scalarType('binary')), field('secret', scalarType('binary'), { visibility: 'readonly' })]),
+                ]);
+                const output = generatePlainTypes(root, { ...ctx('server'), modelsWithInput: new Set(['Blob1']) });
+                expect(output).toContain('bin: Buffer;');
+                expect(output).not.toContain('Blob;');
+            });
+        });
     });
 
     // ─── Compound types ───────────────────────────────────────────

package/tests/codegen-server.test.ts

@@ -120,6 +120,43 @@ describe('createTypescriptPlugin (server)', () => {
             expect(typeContent).not.toContain('z.');
             expect(typeContent).toContain('export interface User');
         });
+
+        it('renders binary as Buffer in server plain types', async () => {
+            const plugin = createTypescriptPlugin({ server: { output: { types: 'src/types/{filename}.ts' } } }, '/project');
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('Upload', [field('data', scalarType('binary'))])], '/project/contracts/uploads.ck')];
+            await plugin.generateTargets!(inputs([], contractRoots as any), ctx);
+            const typeContent = [...ctx.emitted.values()][0]!;
+            expect(typeContent).toContain('data: Buffer;');
+            expect(typeContent).not.toContain('Blob');
+        });
+
+        it('renders binary as Blob in SDK plain types', async () => {
+            const plugin = createTypescriptPlugin({ sdk: { output: { types: 'src/types/{filename}.ts' } } }, '/project');
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('Upload', [field('data', scalarType('binary'))])], '/project/contracts/uploads.ck')];
+            await plugin.generateTargets!(inputs([], contractRoots as any), ctx);
+            const typeContent = [...ctx.emitted.values()].find(c => c.includes('interface Upload'))!;
+            expect(typeContent).toContain('data: Blob;');
+        });
+
+        it('honors types.target on the standalone types sub-generator', async () => {
+            const contractRoots = [contractRoot([model('Upload', [field('data', scalarType('binary'))])], '/project/contracts/uploads.ck')];
+
+            const serverCtx = makeCtx('/project');
+            await createTypescriptPlugin({ types: { output: 'src/{filename}.types.ts', target: 'server' } }, '/project').generateTargets!(
+                inputs([], contractRoots as any),
+                serverCtx,
+            );
+            expect([...serverCtx.emitted.values()][0]!).toContain('data: Buffer;');
+
+            const defaultCtx = makeCtx('/project');
+            await createTypescriptPlugin({ types: { output: 'src/{filename}.types.ts' } }, '/project').generateTargets!(
+                inputs([], contractRoots as any),
+                defaultCtx,
+            );
+            expect([...defaultCtx.emitted.values()][0]!).toContain('data: Blob;');
+        });
     });
 
     describe('generated content', () => {