[xban1x]

Requested by Urban · project thread

Summary

Adds a lazySchemas option (--lazySchemas, requires tsNamespaces) that builds each model schema on first access instead of at import.

With tsNamespaces, importing a models module today constructs every Zod schema of the namespace, even when the importer needs one of them. On large APIs that is a measurable share of frontend cold start (the TOS frontend spends tens of milliseconds per details route constructing schemas it never reads). With lazySchemas: true the generator emits:

const once = <T>(create: () => T) => {
  let value: T | undefined;
  return () => (value ??= create());
};

const CategorySchema = once(() => z.object({ id: z.int().nullable(), name: z.string().nullable() }).partial());
const PetSchema = once(() => z.object({ id: z.int().nullish(), category: CategorySchema().nullish() }));

export const PetModels = {
  /** JSDoc kept per member */
  get CategorySchema() {
    return CategorySchema();
  },
  get PetSchema() {
    return PetSchema();
  },
};
export declare namespace PetModels {
  export type Category = z.infer<typeof PetModels.CategorySchema>;
  export type Pet = z.infer<typeof PetModels.PetSchema>;
}

• PetModels.PetSchema is a regular Zod schema (.extend, .shape, .pick work) and the same instance on every access.
• PetModels.Pet keeps resolving as a type through the merged declare namespace; circular schemas keep their explicit type and z.ZodObject<z.ZodRawShape> & z.ZodType<...> annotation.
• Enum constants (PetModels.Status) are lazy getters too.
• modelsInCommon proxies forward to the common namespace through getters.
• Sibling references inside a schema become factory calls (CategorySchema()); member accesses, object keys, string and .regex(/…/) literals are left alone.
• compileSchemas still wraps non-circular factories in z.compile(...).

Changes

• Option plumbing: options.ts, options.const.ts, generate.command.ts, resolveConfig.ts (throws lazySchemas requires tsNamespaces), native/src/config.rs.
• TypeScript generator: generateModels.ts (renderLazyModels, lazy proxy) and generate.lazy.utils.ts (sibling-call rewriter, once helper lines).
• Native renderer: render.rs (render_lazy_common_models, render_lazy_schema_parts, call_lazy_schema_references, lazy render_proxy branch). Output is byte-identical to the TypeScript generator.
• Parity matrix: lazySchemas is a 7th layout key (128 layouts, 56 invalid, 72 runtime-checked).
• Tests: shape, compile, proxy, TS/native agreement and a runtime import test (enum, regex, circular, identity) in generateModels.test.ts; config validation in resolveConfig.test.ts.
• README: new "Lazy schemas" section, option listed under the generate command and in generation modes.

Test plan

• bun run build:native
• bun run test:ts (1327 passed)
• bun run test:native (1327 passed)
• bun run typecheck, bun run lint:check, bun run format
• Generated lazy output for the petstore fixture typechecks with tsc --strict and runs under bun (circular parse, enum access, .extend, shared identity)

---

Generated by Claude Code