@contractkit/plugin-typescript 0.33.3 → 0.34.1

package/src/codegen-plain-types.ts

@@ -1,4 +1,3 @@
-import { relative, dirname } from 'node:path';
 import type { ContractRootNode, ModelNode, FieldNode } from '@contractkit/core';
 import { computeModelsWithOutput, collectExternalOutputRefs } from '@contractkit/core';
 import type { ContractCodegenContext } from './codegen-contract.js';
@@ -10,10 +9,10 @@ import {
     resolveImportPath,
     rootNeedsScalar,
 } from './codegen-contract.js';
-import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJsDocLines, JSON_VALUE_TYPE_DECL } from './ts-render.js';
+import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJsDocLines, sourceLink, JSON_VALUE_TYPE_DECL } from './ts-render.js';
 import type { TsRenderTarget } from './ts-render.js';
 import { DECIMAL_IMPORT, DECIMAL_CONFIG_LINE } from './decimal-runtime.js';
-import { renderReviveFunctions, reviveFnName, DECIMAL_COERCE_DECL } from './codegen-revive.js';
+import { renderReviveFunctions, reviveFnName, coerceDeclsFor } from './codegen-revive.js';
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
@@ -52,6 +51,14 @@ export function generatePlainTypes(root: ContractRootNode, context?: ContractCod
     const needsDecimal = rootNeedsScalar(root, 'decimal') || (context?.emitRevivers && context.modelsWithDecimal ? root.models.some(m => context.modelsWithDecimal!.has(m.name)) : false);
     if (needsDecimal) lines.push(DECIMAL_IMPORT);
 
+    // Likewise for the temporal scalars: `renderTsScalar` maps them to Luxon classes, which are a
+    // real runtime dependency of anyone holding one. `interval` is not among them — it renders as
+    // a string, since `_ZodInterval` transforms back to ISO on output.
+    const luxonImports: string[] = [];
+    if (rootNeedsScalar(root, 'date') || rootNeedsScalar(root, 'time') || rootNeedsScalar(root, 'datetime')) luxonImports.push('DateTime');
+    if (rootNeedsScalar(root, 'duration')) luxonImports.push('Duration');
+    if (luxonImports.length > 0) lines.push(`import { ${luxonImports.join(', ')} } from 'luxon';`);
+
     // Type-only imports for external references. A cross-file model carrying a decimal also
     // contributes its reviver, which is a value and so needs a second, non-type import.
     for (const ref of allExternalRefs) {
@@ -99,10 +106,11 @@ export function generatePlainTypes(root: ContractRootNode, context?: ContractCod
         lines.push(DECIMAL_CONFIG_LINE);
     }
 
-    // Same rule as in `generateContract`: the helper is emitted only if the revivers actually
+    // Same rule as in `generateContract`: a helper is emitted only if the revivers actually
     // reference it, so the two cannot drift and trip `noUnusedLocals`.
-    if (bodyLines.some(l => l.includes('__dec('))) {
-        lines.push(...DECIMAL_COERCE_DECL);
+    const coerceDecls = coerceDeclsFor(bodyLines);
+    if (coerceDecls.length > 0) {
+        lines.push(...coerceDecls);
         lines.push('');
     }
     lines.push(...bodyLines);
@@ -174,8 +182,7 @@ function generateComments(model: ModelNode, outPath?: string): string[] {
         for (const l of escapeJsDocLines(model.description)) lines.push(` * ${l}`);
     }
 
-    const relPath = outPath ? relative(dirname(outPath), model.loc.file) : model.loc.file;
-    lines.push(` * generated from [${model.name}](file://./${relPath}#L${model.loc.line})`);
+    lines.push(` * generated from ${sourceLink(model.name, outPath, model.loc.file, model.loc.line)}`);
     lines.push(' */');
     return lines;
 }

package/src/codegen-revive.ts

@@ -1,4 +1,4 @@
-import type { ContractTypeNode, FieldNode, ModelNode } from '@contractkit/core';
+import type { ContractTypeNode, FieldNode, ModelNode, ScalarTypeNode } from '@contractkit/core';
 
 /**
  * Emitters for the `reviveX` functions that rehydrate `decimal` fields in an SDK response.
@@ -19,27 +19,98 @@ import type { ContractTypeNode, FieldNode, ModelNode } from '@contractkit/core';
  */
 
 export interface ReviveCodegenOptions {
-    /** Models that carry a decimal, directly or transitively. Only these get a reviver. */
+    /** Models that carry a revivable scalar, directly or transitively. Only these get a reviver. */
     modelsWithDecimal: Set<string>;
+    /**
+     * Which scalars need rehydrating from their wire form. Defaults to `decimal`, the only scalar
+     * whose runtime type currently differs from what `JSON.parse` produces.
+     *
+     * A set rather than a boolean because the question a reviver asks is not "does this reach a
+     * decimal" but "which conversion does this leaf need" — and the answer becomes plural as soon
+     * as a second scalar joins.
+     */
+    revivableScalars?: ReadonlySet<ScalarTypeNode['name']>;
     /** Models with an `Output` variant, which need a second reviver keyed by the output casing. */
     modelsWithOutput?: Set<string>;
     /** Every model in scope, for resolving discriminated-union members to their literal tag. */
     modelMap?: Map<string, ModelNode>;
 }
 
-/** The per-file coercion helper. Emitted once in any file that declares a reviver. */
-export const DECIMAL_COERCE_DECL = [
-    `const __dec = (v: unknown, path: string): Decimal => {`,
-    `    if (typeof v !== 'string') {`,
-    `        throw new TypeError(\`ContractKit: expected a decimal string at '\${path}', received \${typeof v} — decimals must be sent as quoted JSON strings.\`);`,
-    `    }`,
-    `    try {`,
-    `        return new Decimal(v);`,
-    `    } catch {`,
-    `        throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid decimal.\`);`,
-    `    }`,
-    `};`,
-];
+/**
+ * The per-file coercion helpers, keyed by the call prefix that identifies them in emitted text.
+ *
+ * A file gets only the helpers its revivers actually call, decided by scanning the emitted lines
+ * — the same text-derived idiom the reviver and type imports use, and for the same reason: a
+ * predicate computed separately can drift and leave an unused local behind.
+ *
+ * Each one takes the raw JSON value and throws a `TypeError` naming the path rather than
+ * returning something invalid, because a silently wrong `DateTime` surfaces much further from
+ * the cause than a throw at the boundary does.
+ */
+export const COERCE_DECLS: Record<string, string[]> = {
+    '__dec(': [
+        `const __dec = (v: unknown, path: string): Decimal => {`,
+        `    if (typeof v !== 'string') {`,
+        `        throw new TypeError(\`ContractKit: expected a decimal string at '\${path}', received \${typeof v} — decimals must be sent as quoted JSON strings.\`);`,
+        `    }`,
+        `    try {`,
+        `        return new Decimal(v);`,
+        `    } catch {`,
+        `        throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid decimal.\`);`,
+        `    }`,
+        `};`,
+    ],
+    '__dt(': [
+        `const __dt = (v: unknown, path: string): DateTime => {`,
+        `    if (typeof v !== 'string') {`,
+        `        throw new TypeError(\`ContractKit: expected an ISO 8601 string at '\${path}', received \${typeof v}.\`);`,
+        `    }`,
+        `    const d = DateTime.fromISO(v);`,
+        `    if (!d.isValid) throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid ISO 8601 datetime.\`);`,
+        `    return d;`,
+        `};`,
+    ],
+    '__dtf(': [
+        `const __dtf = (v: unknown, path: string, fmt: string): DateTime => {`,
+        `    if (typeof v !== 'string') {`,
+        `        throw new TypeError(\`ContractKit: expected a string at '\${path}' in format \${fmt}, received \${typeof v}.\`);`,
+        `    }`,
+        `    const d = DateTime.fromFormat(v, fmt);`,
+        `    if (!d.isValid) throw new TypeError(\`ContractKit: '\${v}' at '\${path}' does not match format \${fmt}.\`);`,
+        `    return d;`,
+        `};`,
+    ],
+    '__dur(': [
+        `const __dur = (v: unknown, path: string): Duration => {`,
+        `    if (typeof v !== 'string') {`,
+        `        throw new TypeError(\`ContractKit: expected an ISO 8601 duration string at '\${path}', received \${typeof v}.\`);`,
+        `    }`,
+        `    const d = Duration.fromISO(v);`,
+        `    if (!d.isValid) throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid ISO 8601 duration.\`);`,
+        `    return d;`,
+        `};`,
+    ],
+};
+
+/** Back-compat alias: the decimal helper alone, which several call sites still name directly. */
+export const DECIMAL_COERCE_DECL = COERCE_DECLS['__dec(']!;
+
+/** The helper declarations `lines` actually calls, in a stable order. */
+export function coerceDeclsFor(lines: string[]): string[] {
+    const haystack = lines.join('\n');
+    return Object.entries(COERCE_DECLS)
+        .filter(([prefix]) => haystack.includes(prefix))
+        .flatMap(([, decl]) => decl);
+}
+
+/** Luxon classes referenced by the helpers `lines` calls, for the importing file to bring in. */
+export function coerceLuxonImports(lines: string[]): string[] {
+    const haystack = lines.join('\n');
+    const needed = new Set<string>();
+    if (haystack.includes('__dt(') || haystack.includes('__dtf(')) needed.add('DateTime');
+    if (haystack.includes('__dur(')) needed.add('Duration');
+    return [...needed].sort();
+}
 
 /** `reviveInvoice` / `reviveInvoiceOutput`. */
 export function reviveFnName(model: string, variant: 'base' | 'output' = 'base'): string {
@@ -52,11 +123,27 @@ function applyCase(name: string, caseTransform: 'camel' | 'snake' | 'pascal' | u
     return name.charAt(0).toUpperCase() + name.slice(1);
 }
 
-/** Whether a type reaches a decimal, following refs through `modelsWithDecimal`. */
+/**
+ * Scalars whose runtime type differs from what `JSON.parse` produces, and which a reviver
+ * therefore has to rehydrate. The default of {@link ReviveCodegenOptions.revivableScalars}.
+ *
+ * `interval` is excluded: `_ZodInterval` ends in `.transform(v => v.toISO()!)`, so its inferred
+ * output type is already `string` and there is nothing to revive it to. Covering it means making
+ * that round-trip idempotent first, which the router's `isRevalidatable` also depends on.
+ */
+export const DEFAULT_REVIVABLE_SCALARS: ReadonlySet<ScalarTypeNode['name']> = new Set([
+    'decimal',
+    'date',
+    'time',
+    'datetime',
+    'duration',
+]);
+
+/** Whether a type reaches a revivable scalar, following refs through `modelsWithDecimal`. */
 export function typeReachesDecimal(type: ContractTypeNode, opts: ReviveCodegenOptions): boolean {
     switch (type.kind) {
         case 'scalar':
-            return type.name === 'decimal';
+            return (opts.revivableScalars ?? DEFAULT_REVIVABLE_SCALARS).has(type.name);
         case 'ref':
             return opts.modelsWithDecimal.has(type.name);
         case 'array':
@@ -66,6 +153,10 @@ export function typeReachesDecimal(type: ContractTypeNode, opts: ReviveCodegenOp
         case 'tuple':
             return type.items.some(t => typeReachesDecimal(t, opts));
         case 'record':
+            // Value only, deliberately unlike `typeHasScalar` in core, which also checks the key.
+            // That one answers "is this scalar mentioned", which decides imports; this one answers
+            // "is there a value to rehydrate", and a JSON object key is always a string — there is
+            // nothing at a key position for a reviver to convert.
             return typeReachesDecimal(type.value, opts);
         case 'union':
         case 'discriminatedUnion':
@@ -78,6 +169,35 @@ export function typeReachesDecimal(type: ContractTypeNode, opts: ReviveCodegenOp
     }
 }
 
+/**
+ * The statement that rehydrates one scalar leaf, or nothing when the scalar needs no conversion.
+ *
+ * `date` and `time` carry their format on the node, and the reviver has to parse with the same
+ * format the schema validates against — which is why the helper takes it as an argument rather
+ * than baking one in. Defaults match `renderTsScalar`'s.
+ *
+ * `interval` is deliberately absent. `_ZodInterval` ends in `.transform(v => v.toISO()!)`, so its
+ * inferred output is a string and there is nothing to revive it to; covering it means making that
+ * round-trip idempotent first, which `isRevalidatable` in the router also depends on.
+ */
+function scalarCoercion(type: ScalarTypeNode, slot: string, path: string, opts: ReviveCodegenOptions): string[] {
+    if (!(opts.revivableScalars ?? DEFAULT_REVIVABLE_SCALARS).has(type.name)) return [];
+    switch (type.name) {
+        case 'decimal':
+            return [`${slot} = __dec(${slot}, '${path}');`];
+        case 'datetime':
+            return [`${slot} = __dt(${slot}, '${path}');`];
+        case 'duration':
+            return [`${slot} = __dur(${slot}, '${path}');`];
+        case 'date':
+            return [`${slot} = __dtf(${slot}, '${path}', '${type.format ?? 'yyyy-MM-dd'}');`];
+        case 'time':
+            return [`${slot} = __dtf(${slot}, '${path}', '${type.format ?? 'HH:mm:ss'}');`];
+        default:
+            return [];
+    }
+}
+
 /** Fresh local names, so nested loops in one function body cannot collide. */
 class Scope {
     private n = 0;
@@ -95,7 +215,7 @@ class Scope {
 function emit(slot: string, type: ContractTypeNode, path: string, opts: ReviveCodegenOptions, scope: Scope, variant: 'base' | 'output'): string[] {
     switch (type.kind) {
         case 'scalar':
-            return type.name === 'decimal' ? [`${slot} = __dec(${slot}, '${path}');`] : [];
+            return scalarCoercion(type, slot, path, opts);
 
         case 'ref':
             return opts.modelsWithDecimal.has(type.name) ? [`${reviveRefName(type.name, opts, variant)}(${slot} as never);`] : [];
@@ -278,7 +398,7 @@ function renderOne(model: ModelNode, opts: ReviveCodegenOptions, variant: 'base'
         const body = emit('__v[0]', model.type, model.name, opts, scope, variant);
         if (body.length === 0) return [];
         return [
-            `/** Rehydrates every \`decimal\` in a ${typeName} from its wire string. Mutates and returns \`raw\`. */`,
+            `/** Rehydrates every wire-encoded scalar in a ${typeName} into its runtime type. Mutates and returns \`raw\`. */`,
             `export function ${fnName}(raw: ${typeName}): ${typeName} {`,
             `    const __v = [raw] as unknown[];`,
             ...body.map(l => `    ${l}`),
@@ -294,7 +414,7 @@ function renderOne(model: ModelNode, opts: ReviveCodegenOptions, variant: 'base'
     if (body.length === 0) return [];
 
     return [
-        `/** Rehydrates every \`decimal\` in a ${typeName} from its wire string. Mutates and returns \`raw\`. */`,
+        `/** Rehydrates every wire-encoded scalar in a ${typeName} into its runtime type. Mutates and returns \`raw\`. */`,
         `export function ${fnName}(raw: ${typeName}): ${typeName} {`,
         `    const ${obj} = raw as unknown as Record<string, unknown>;`,
         ...body.map(l => `    ${l}`),