@supalive/codegen 1.8.0 → 1.9.0

package/README.md

@@ -85,6 +85,154 @@ const { files } = generate({ entry: "src/server/procedures.ts" });
 `extractClient` (build the intermediate representation) and `emit` (turn the IR
 into files) are also exported for advanced use.
 
+## Return type overrides
+
+By default the codegen infers everything from TypeScript types: `number` →
+`double`, `bigint` → `BigInt`, `Date` → `DateTime`, etc. The `returns` property
+on procedure configs lets you override specific fields for the generated client
+without changing your handler's return type.
+
+Model naming uses the `.modelName()` Zod extension method — no extra imports
+needed (it patches all Zod types when you import from `@supalive/core/procedure`).
+
+### Default (no `returns`)
+
+Everything inferred from the handler's TS return type:
+
+```ts
+const listCards = query({
+  args: z.object({ limit: z.number().int().default(20) }),
+  handler: async (_ctx, _input): Promise<{ items: { id: string; name: string }[] }> => ({
+    items: [],
+  }),
+});
+// → ListCardsResult { items: List<ListCardsItem> }
+```
+
+### `.modelName("Name")` — rename a model
+
+Give a generated model a custom name instead of the auto-derived one:
+
+```ts
+const listCards = query({
+  args: z.object({ limit: z.number().int().default(20) }),
+  returns: z.array(
+    z.object({ id: z.string(), name: z.string() }).modelName("CardItem")
+  ),
+  handler: async (_ctx, _input) => [] as { id: string; name: string }[],
+});
+// → result type: List<CardItem>  (not List<ListCardsResultItem>)
+```
+
+`.modelName("Foo")` on any Zod schema tells the codegen to rename the
+model to `Foo`. Combine with field-level overrides like `z.number().int()` to
+also patch the TS-inferred types.
+
+### Partial field overrides (implicit)
+
+Only the fields you list in the `returns` schema are overridden; the rest stay
+inferred from TS. No `partial()` wrapper needed:
+
+```ts
+const storeCards = query({
+  args: z.object({}),
+  returns: z.object({
+    total: z.number().int(),           // override: number → int
+    // 'cards' is NOT listed → stays inferred from TS
+  }),
+  handler: async (_ctx, _input): Promise<{
+    cards: { id: string; name: string; balance: number }[];
+    total: number;
+  }> => ({ cards: [], total: 0 }),
+});
+// → StoreCardsResult { cards: List<...>, total: int }
+```
+
+### Combining `.modelName()` + `.int()`
+
+The most common pattern: rename nested models and patch numeric types while
+keeping the parent result inferred from TS:
+
+```ts
+const storeCards = query({
+  args: z.object({}),
+  returns: z.object({
+    value: z.array(
+      z.object({
+        balanceCents: z.number().int(),  // double → int
+      }).modelName("StoreCardItem")
+    ),
+  }),
+  handler: async (ctx, input) => {
+    const cards = await ctx.db.query(GiftCardSchema).select().get();
+    return {
+      cursor: "...",
+      value: cards,
+    };
+  },
+});
+// → StoreCardsResult { cursor: String, value: List<StoreCardItem> }
+//   StoreCardItem { id, balanceCents: int, ... }
+```
+
+### Procedure-level list return with model naming
+
+When a procedure returns a bare list (not wrapped in an object), use
+`z.array()` at the top level of `returns`:
+
+```ts
+const cardLedger = query({
+  args: z.object({ cardId: z.string() }),
+  returns: z.array(
+    z.object({
+      amountCents: z.number().int(),
+      balanceAfterCents: z.number().int(),
+    }).modelName("CardLedgerItem")
+  ),
+  handler: async (ctx, { cardId }) =>
+    ctx.db.query(CardTransactionSchema).select()
+      .where((f) => f.eq("cardId", cardId)).get(),
+});
+// → result type: List<CardLedgerItem>
+//   CardLedgerItem { ..., amountCents: int, balanceAfterCents: int, ... }
+```
+
+### Nested model overrides
+
+Override fields inside a list element's model by nesting `.modelName()` +
+field overrides:
+
+```ts
+const nestedOverride = query({
+  args: z.object({}),
+  returns: z.object({
+    items: z.array(
+      z.object({
+        id: z.string(),
+        balance: z.number().int(),  // override int
+        name: z.string(),
+      }).modelName("NestedItem")
+    ),
+  }),
+  handler: async (_ctx, _input) => ({
+    items: [] as { id: string; balance: number; name: string }[],
+  }),
+});
+// → NestedItem { id: String, balance: int, name: String }
+```
+
+### Summary of helpers
+
+| Helper | Purpose | Example |
+| --- | --- | --- |
+| `.modelName("Name")` | Rename a model in generated output | `z.object({ ... }).modelName("CardItem")` |
+| `z.number().int()` | Patch a field's type from `double` to `int` | `z.object({ balance: z.number().int() })` |
+| `z.bigint()` | Patch a field's type to `BigInt` | `z.object({ revision: z.bigint() })` |
+
+All `returns` helpers are purely for codegen — they have no effect at runtime.
+The Zod schemas are not used for runtime validation of the handler's return
+value.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as generateToDisk, r as readEntryConfig } from "./src-BRGy8CeY.js";
+import { n as generateToDisk, r as readEntryConfig } from "./src-C8EGEwt7.js";
 import path from "node:path";
 //#region src/cli.ts
 function parseArgs(argv) {

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as emit, c as loadSchemaEnums, i as resolveConfig, n as generateToDisk, o as extractClient, r as readEntryConfig, s as SchemaEnumRegistry, t as generate } from "./src-BRGy8CeY.js";
+import { a as emit, c as loadSchemaEnums, i as resolveConfig, n as generateToDisk, o as extractClient, r as readEntryConfig, s as SchemaEnumRegistry, t as generate } from "./src-C8EGEwt7.js";
 export { SchemaEnumRegistry, emit, extractClient, generate, generateToDisk, loadSchemaEnums, readEntryConfig, resolveConfig };

package/dist/{src-BRGy8CeY.js → src-C8EGEwt7.js}

@@ -39,6 +39,20 @@ function procedureDocText(prop) {
 			const doc = stmt ? jsDocText(stmt) : void 0;
 			if (doc) return doc;
 		}
+		for (const def of idNode.getDefinitionNodes()) if (Node.isImportSpecifier(def)) {
+			const sourceFile = def.getImportDeclaration().getModuleSpecifierSourceFile();
+			if (sourceFile) {
+				const exported = sourceFile.getExportedDeclarations().get(def.getName());
+				if (exported && exported.length > 0) {
+					const decl = exported[0];
+					if (Node.isVariableDeclaration(decl)) {
+						const stmt = decl.getVariableStatement();
+						const doc = stmt ? jsDocText(stmt) : void 0;
+						if (doc) return doc;
+					}
+				}
+			}
+		}
 	}
 }
 /** The trimmed description of a node's last JSDoc block, if any. */
@@ -66,6 +80,139 @@ function scanZodArgMeta(routerDecl) {
 	} catch {}
 	return result;
 }
+/** From a `query({ returns: ..., handler })` call, get the output schema. */
+function getOutputSchema(call) {
+	if (!Node.isCallExpression(call)) return void 0;
+	const arg = call.getArguments()[0];
+	if (!arg || !Node.isObjectLiteralExpression(arg)) return void 0;
+	const returnsProp = arg.getProperty("returns");
+	if (!returnsProp || !Node.isPropertyAssignment(returnsProp)) return void 0;
+	return returnsProp.getInitializer();
+}
+/**
+* Scan each procedure's `returns` Zod schema into a structured metadata tree.
+* Returns `Map<procName, OutputSchemaMeta>`.
+*/
+function scanZodOutputMeta(routerDecl) {
+	const result = /* @__PURE__ */ new Map();
+	try {
+		const proceduresObj = getProceduresObjectLiteral(routerDecl);
+		if (!proceduresObj) return result;
+		for (const prop of proceduresObj.getProperties()) {
+			const key = getPropertyKey(prop);
+			if (!key) continue;
+			const call = resolveProcedureCall(prop);
+			if (!call) continue;
+			const outputSchema = getOutputSchema(call);
+			if (!outputSchema) continue;
+			const meta = scanOutputSchemaNode(outputSchema);
+			if (meta) result.set(key, meta);
+		}
+	} catch {}
+	return result;
+}
+/**
+* Recursively scan a Zod schema expression, extracting field metadata and
+* `__genType` model names. Returns `null` if no metadata found.
+*/
+function scanOutputSchemaNode(node) {
+	if (!node) return null;
+	let resolved = node;
+	if (Node.isIdentifier(resolved)) {
+		const init = resolveIdentifierInit(resolved);
+		if (init) resolved = init;
+	}
+	let modelName;
+	let isObject = false;
+	let baseCallNode;
+	let arrayElementNode;
+	let cur = resolved;
+	while (cur && Node.isCallExpression(cur)) {
+		const expr = cur.getExpression();
+		if (Node.isPropertyAccessExpression(expr)) {
+			const method = expr.getName();
+			if (method === "meta") {
+				const metaArg = cur.getArguments()[0];
+				if (metaArg && Node.isObjectLiteralExpression(metaArg)) {
+					const genTypeProp = metaArg.getProperty("__genType");
+					if (genTypeProp && Node.isPropertyAssignment(genTypeProp)) {
+						const init = genTypeProp.getInitializer();
+						if (init && Node.isStringLiteral(init)) modelName = init.getLiteralValue();
+					}
+				}
+				cur = expr.getExpression();
+			} else if (method === "modelName") {
+				const nameArg = cur.getArguments()[0];
+				if (nameArg && Node.isStringLiteral(nameArg)) modelName = nameArg.getLiteralValue();
+				cur = expr.getExpression();
+			} else if (method === "array") {
+				arrayElementNode = cur.getArguments()[0];
+				cur = expr.getExpression();
+			} else if (/^(strict|loose)?[oO]bject$/.test(method)) {
+				isObject = true;
+				baseCallNode = cur;
+				break;
+			} else cur = expr.getExpression();
+		} else break;
+	}
+	if (!isObject && cur && Node.isCallExpression(cur)) {
+		const expr = cur.getExpression();
+		if (Node.isIdentifier(expr) || Node.isPropertyAccessExpression(expr)) {
+			const exprText = expr.getText();
+			if (/(^|\.)(strict|loose)?[oO]bject$/.test(exprText)) {
+				isObject = true;
+				baseCallNode = cur;
+			}
+		}
+	}
+	if (isObject && baseCallNode && Node.isCallExpression(baseCallNode)) {
+		const arg = baseCallNode.getArguments()[0];
+		if (!arg || !Node.isObjectLiteralExpression(arg)) return modelName ? {
+			fieldMeta: /* @__PURE__ */ new Map(),
+			modelName,
+			nested: /* @__PURE__ */ new Map()
+		} : null;
+		const fieldMeta = /* @__PURE__ */ new Map();
+		const nested = /* @__PURE__ */ new Map();
+		for (const prop of arg.getProperties()) {
+			if (!Node.isPropertyAssignment(prop)) continue;
+			const key = prop.getName();
+			const init = prop.getInitializer();
+			if (!init) continue;
+			const methods = topLevelZodMethods(init);
+			const meta = {};
+			if (methods.has("bigint")) meta.numeric = "bigint";
+			else if (methods.has("int")) meta.numeric = "int";
+			if (methods.has("default") || methods.has("catch") || methods.has("prefault")) meta.optional = true;
+			const description = topLevelZodDescription(init);
+			if (description) meta.description = description;
+			if (meta.numeric || meta.optional || meta.description) fieldMeta.set(key, meta);
+			const nestedMeta = scanOutputSchemaNode(init);
+			if (nestedMeta) nested.set(key, nestedMeta);
+		}
+		return {
+			fieldMeta,
+			modelName,
+			nested
+		};
+	}
+	if (arrayElementNode) {
+		const elementMeta = scanOutputSchemaNode(arrayElementNode);
+		if (elementMeta || modelName) return {
+			fieldMeta: /* @__PURE__ */ new Map(),
+			modelName,
+			nested: /* @__PURE__ */ new Map([["__element", elementMeta ?? {
+				fieldMeta: /* @__PURE__ */ new Map(),
+				nested: /* @__PURE__ */ new Map()
+			}]])
+		};
+	}
+	return modelName ? {
+		fieldMeta: /* @__PURE__ */ new Map(),
+		modelName,
+		nested: /* @__PURE__ */ new Map()
+	} : null;
+}
 function getProceduresObjectLiteral(routerDecl) {
 	let init;
 	if (Node.isVariableDeclaration(routerDecl)) init = routerDecl.getInitializer();
@@ -109,9 +256,6 @@ function followToCall(node, depth) {
 /**
 * Given an Identifier that may be an import binding, follow through the import
 * chain to the actual exported declaration's initializer node.
-*
-* Handles: `import { listItems } from "./procs.js"` → the exported VariableDeclaration
-*          `import { x } from "./reexport.js"` where that file re-exports → recursive follow
 */
 function followImport(id) {
 	const sourceFile = id.getSourceFile();
@@ -153,9 +297,6 @@ function followImport(id) {
 		}
 	}
 }
-/** Extract the initializer expression from a definition node, unwrapping any
-*  container nodes (VariableStatement, ExportNamedDeclaration, etc.) that
-*  ts-morph may return for cross-file imports. */
 function definitionInitializer(def) {
 	if (Node.isVariableDeclaration(def)) return def.getInitializer();
 	if (Node.isVariableStatement(def)) for (const d of def.getDeclarationList().getDeclarations()) {
@@ -167,7 +308,6 @@ function definitionInitializer(def) {
 		if (init) return init;
 	}
 }
-/** Resolve an Identifier to its initializer, following definitions across files. */
 function resolveIdentifierInit(id) {
 	if (!Node.isIdentifier(id)) return void 0;
 	for (const def of id.getDefinitionNodes()) {
@@ -212,11 +352,6 @@ function scanObjectSchema(schema) {
 	}
 	return map;
 }
-/**
-* Names of the methods called at the top level of a Zod field expression.
-* For `z.number().int().default(0)` → `{ number, int, default }`. Nested
-* schemas (inside an object argument) are not descended into.
-*/
 function topLevelZodMethods(node) {
 	const methods = /* @__PURE__ */ new Set();
 	let cur = node;
@@ -229,11 +364,6 @@ function topLevelZodMethods(node) {
 	}
 	return methods;
 }
-/**
-* The description string from a field's top-level `.describe("...")` or
-* `.meta({ description: "..." })`, walking the method chain (outermost first,
-* so the outermost description wins).
-*/
 function topLevelZodDescription(node) {
 	let cur = node;
 	while (cur && Node.isCallExpression(cur)) {
@@ -461,8 +591,9 @@ function extractClient(config, schemaEnums = SchemaEnumRegistry.empty()) {
 	if (!proceduresSym) throw new Error(`Export "${config.router}" does not look like a Supalive router (no "procedures" property).`);
 	const proceduresType = proceduresSym.getTypeAtLocation(routerDecl);
 	const argMeta = scanZodArgMeta(routerDecl);
+	const outputMeta = scanZodOutputMeta(routerDecl);
 	const procDocs = scanProcedureDocs(routerDecl);
-	const extractor = new Extractor(routerDecl, config, argMeta, project.getTypeChecker(), schemaEnums);
+	const extractor = new Extractor(routerDecl, config, argMeta, outputMeta, project.getTypeChecker(), schemaEnums);
 	const procedures = [];
 	for (const procSym of proceduresType.getProperties()) {
 		const name = procSym.getName();
@@ -486,6 +617,7 @@ var Extractor = class {
 	locationNode;
 	config;
 	argMeta;
+	outputMeta;
 	tc;
 	schemaEnums;
 	modelRegistry = /* @__PURE__ */ new Map();
@@ -495,10 +627,11 @@ var Extractor = class {
 	enumsFinalized = false;
 	nameCounts = /* @__PURE__ */ new Map();
 	visiting = /* @__PURE__ */ new Set();
-	constructor(locationNode, config, argMeta, tc, schemaEnums) {
+	constructor(locationNode, config, argMeta, outputMeta, tc, schemaEnums) {
 		this.locationNode = locationNode;
 		this.config = config;
 		this.argMeta = argMeta;
+		this.outputMeta = outputMeta;
 		this.tc = tc;
 		this.schemaEnums = schemaEnums;
 	}
@@ -512,31 +645,6 @@ var Extractor = class {
 			return;
 		}
 	}
-	/**
-	* Read an `@type` JSDoc tag from a property and parse it into a DartType.
-	*
-	* Supported formats:
-	*   - `/** @type StoreCardItem *​/` → model with that name
-	*   - `/** @type List<StoreCardItem> *​/` → list with model element
-	*   - `/** @type String *​/`, `/** @type int *​/`, etc. → primitive
-	*/
-	readTypeOverride(prop) {
-		try {
-			const decls = prop.getDeclarations();
-			if (!decls || decls.length === 0) return null;
-			const node = decls[0];
-			if (!Node.isJSDocable(node)) return null;
-			const jsDocs = node.getJsDocs();
-			if (jsDocs.length === 0) return null;
-			const typeTag = jsDocs[jsDocs.length - 1].getTags().find((t) => t.getTagName() === "type");
-			if (!typeTag) return null;
-			const raw = typeTag.compilerNode.typeExpression?.getText?.()?.trim();
-			if (!raw) return null;
-			return parseTypeOverride(raw);
-		} catch {
-			return null;
-		}
-	}
 	models() {
 		this.finalizeEnums();
 		return [...this.modelRegistry.values()];
@@ -570,6 +678,8 @@ var Extractor = class {
 		const ret = unwrapPromise(sig.getReturnType());
 		const { hasNull, hasUndefined } = splitNullish(ret);
 		const resultType = this.walk(ret, pascal(name) + "Result");
+		const outputSchemaMeta = this.outputMeta.get(name);
+		if (outputSchemaMeta) this.applyOutputMeta(resultType, outputSchemaMeta);
 		return {
 			name,
 			kind,
@@ -580,6 +690,41 @@ var Extractor = class {
 			resultNullable: hasNull || hasUndefined
 		};
 	}
+	/**
+	* Recursively apply output schema metadata to a DartType tree.
+	* Patches numeric types (int/bigint), renames models via __genType,
+	* and recurses into nested objects and lists.
+	*/
+	applyOutputMeta(dt, meta) {
+		if (meta.modelName && dt.kind === "model") {
+			const existing = this.modelRegistry.get(dt.name);
+			if (existing && !this.modelRegistry.has(meta.modelName)) {
+				const renamed = {
+					...existing,
+					name: meta.modelName
+				};
+				this.modelRegistry.set(meta.modelName, renamed);
+				this.modelRegistry.delete(dt.name);
+			}
+			dt.name = meta.modelName;
+		}
+		if (dt.kind === "model") {
+			const model = this.modelRegistry.get(dt.name);
+			if (model) for (const f of model.fields) {
+				const fMeta = meta.fieldMeta.get(f.jsonKey);
+				if (fMeta) {
+					if (fMeta.numeric && (f.type.kind === "double" || f.type.kind === "int")) f.type = { kind: fMeta.numeric };
+					if (fMeta.optional) f.optional = true;
+					if (fMeta.description && !f.doc) f.doc = fMeta.description;
+				}
+				const nestedMeta = meta.nested.get(f.jsonKey);
+				if (nestedMeta) this.applyOutputMeta(f.type, nestedMeta);
+			}
+		} else if (dt.kind === "list") {
+			const elMeta = meta.nested.get("__element");
+			if (elMeta) this.applyOutputMeta(dt.element, elMeta);
+		}
+	}
 	walk(type, hint) {
 		const { core } = splitNullish(type);
 		if (core.length === 0) return { kind: "dynamic" };
@@ -653,10 +798,8 @@ var Extractor = class {
 			const { core, hasNull, hasUndefined } = splitNullish(propType);
 			const optional = declaredOptional || hasUndefined;
 			const nullable = hasNull;
-			const typeOverride = this.readTypeOverride(prop);
 			let dartType;
-			if (typeOverride) dartType = typeOverride;
-			else if (core.length === 0) dartType = { kind: "dynamic" };
+			if (core.length === 0) dartType = { kind: "dynamic" };
 			else if (core.length === 1) {
 				const fieldHint = name.replace(/Result$/, "") + pascal(jsonKey);
 				dartType = this.walkSingle(core[0], fieldHint);
@@ -945,40 +1088,6 @@ function cleanStem(modelName) {
 	}
 	return singularizeWord(s);
 }
-const PRIMITIVE_MAP = {
-	string: "string",
-	int: "int",
-	double: "double",
-	bool: "bool",
-	bigint: "bigint",
-	bytes: "bytes",
-	datetime: "datetime",
-	dynamic: "dynamic"
-};
-/**
-* Parse an `@type` override value into a DartType.
-*
-* - `"StoreCardItem"` → `{ kind: "model", name: "StoreCardItem" }`
-* - `"List<StoreCardItem>"` → `{ kind: "list", element: { kind: "model", name: "StoreCardItem" } }`
-* - `"String"` → `{ kind: "string" }`
-* - `"int"` → `{ kind: "int" }`
-*/
-function parseTypeOverride(raw) {
-	const listMatch = raw.match(/^List<(.+)>$/);
-	if (listMatch) {
-		const innerType = parseTypeOverride(listMatch[1].trim());
-		return innerType ? {
-			kind: "list",
-			element: innerType
-		} : null;
-	}
-	const prim = PRIMITIVE_MAP[raw.toLowerCase()];
-	if (prim) return { kind: prim };
-	return {
-		kind: "model",
-		name: raw
-	};
-}
 /** The bare candidate name for a structural (non-schema) enum group. */
 function fallbackBase(g) {
 	return pascal(g.field ?? g.hint);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supalive/codegen",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Generate type-safe client code (Dart, and more) from a Supalive TypeScript router.",
   "author": "Rebaz Raouf",
   "license": "MIT",