@gabrielbryk/json-schema-to-zod 2.13.0 → 2.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 2.14.0
+
+### Minor Changes
+
+- ff1858d: Add naming customization hooks to jsonSchemaToZod output for schema and type exports.
+
 ## 2.13.0
 
 ### Minor Changes

package/README.md

@@ -92,6 +92,21 @@ export const mySchema = z.object({ hello: z.string().optional() });
 export type MySchema = z.infer<typeof mySchema>;
 ```
 
+#### Naming customization
+
+Use the `naming` option to control schema const names and exported type names (root + lifted refs).
+
+```typescript
+const moduleWithCustomNaming = jsonSchemaToZod(myObject, {
+  name: "Workflow",
+  typeExports: true,
+  naming: {
+    schemaName: (base) => base,
+    typeName: (base) => `${base}Type`,
+  },
+});
+```
+
 #### Example with `$refs` resolved and output formatted
 
 ```typescript

package/dist/core/analyzeSchema.js

@@ -1,23 +1,38 @@
 import { parseSchema } from "../parsers/parseSchema.js";
 import { detectCycles, computeScc } from "../utils/cycles.js";
 import { buildRefRegistry } from "../utils/buildRefRegistry.js";
+import { resolveSchemaName } from "../utils/schemaNaming.js";
 export const analyzeSchema = (schema, options = {}) => {
-    const { name, type, ...rest } = options;
+    const { name, type, naming, ...rest } = options;
     if (type && !name) {
         throw new Error("Option `type` requires `name` to be set");
     }
+    const nameContext = { isRoot: true, isLifted: false };
+    const rootBaseName = name;
+    let resolvedName = name;
+    const usedNames = new Set();
+    const usedBaseNames = new Set();
+    if (name && naming) {
+        resolvedName = resolveSchemaName(name, naming, nameContext, usedNames);
+        usedBaseNames.add(name);
+    }
+    if (resolvedName) {
+        usedNames.add(resolvedName);
+    }
     const normalized = {
-        name,
+        name: resolvedName,
         type,
+        naming,
         module: "esm",
         ...rest,
         exportRefs: rest.exportRefs ?? true,
         withMeta: rest.withMeta ?? true,
     };
     const refNameByPointer = new Map();
-    const usedNames = new Set();
-    if (name) {
-        usedNames.add(name);
+    const refBaseNameByPointer = new Map();
+    const baseNameBySchema = new Map();
+    if (naming && resolvedName && rootBaseName) {
+        baseNameBySchema.set(resolvedName, rootBaseName);
     }
     const declarations = new Map();
     const dependencies = new Map();
@@ -37,13 +52,17 @@ export const analyzeSchema = (schema, options = {}) => {
         dependencies,
         inProgress: new Set(),
         refNameByPointer,
+        refBaseNameByPointer,
+        baseNameBySchema,
         usedNames,
+        usedBaseNames,
         root: schema,
-        currentSchemaName: name,
+        currentSchemaName: resolvedName,
         refRegistry,
         rootBaseUri,
         ...rest,
         withMeta: normalized.withMeta,
+        naming,
     };
     parseSchema(schema, pass1);
     const names = Array.from(declarations.keys());
@@ -71,6 +90,9 @@ export const analyzeSchema = (schema, options = {}) => {
         definitions: {}, // Legacy support
         dependencies,
         refNameByPointer,
+        refBaseNameByPointer,
+        baseNameBySchema,
+        rootBaseName,
         usedNames,
         cycleRefNames,
         cycleComponentByName: componentByName,

package/dist/core/emitZod.js

@@ -2,6 +2,7 @@ import { parseSchema } from "../parsers/parseSchema.js";
 import { expandJsdocs } from "../utils/jsdocs.js";
 import { inferTypeFromExpression } from "../utils/schemaRepresentation.js";
 import { EsmEmitter } from "../utils/esmEmitter.js";
+import { resolveTypeName } from "../utils/schemaNaming.js";
 /**
  * Split a z.object({...}).method1().method2() expression into base and method chain.
  * This is needed for Rule 2: Don't chain methods on recursive types.
@@ -148,8 +149,8 @@ const orderDeclarations = (entries, dependencies) => {
     return ordered.map((name) => [name, repByName.get(name)]);
 };
 export const emitZod = (analysis) => {
-    const { schema, options, refNameByPointer, cycleRefNames, cycleComponentByName } = analysis;
-    const { name, type, noImport, exportRefs, typeExports, withMeta, ...rest } = options;
+    const { schema, options, refNameByPointer, cycleRefNames, cycleComponentByName, baseNameBySchema, rootBaseName, } = analysis;
+    const { name, type, naming, noImport, exportRefs, typeExports, withMeta, ...rest } = options;
     const declarations = new Map();
     const dependencies = new Map();
     // Fresh name registry for the emission pass.
@@ -175,6 +176,7 @@ export const emitZod = (analysis) => {
         rootBaseUri: analysis.rootBaseUri,
         ...rest,
         withMeta,
+        naming,
     });
     const jsdocs = rest.withJsdocs && typeof schema === "object" && schema !== null && "description" in schema
         ? expandJsdocs(typeof schema.description === "string"
@@ -182,6 +184,13 @@ export const emitZod = (analysis) => {
             : "")
         : "";
     const emitter = new EsmEmitter();
+    const usedTypeNames = new Set();
+    const resolveDeclarationTypeName = (schemaName) => {
+        if (!naming)
+            return schemaName;
+        const baseName = baseNameBySchema.get(schemaName) ?? schemaName;
+        return resolveTypeName(baseName, naming, { isRoot: false, isLifted: true }, usedTypeNames);
+    };
     if (!noImport) {
         emitter.addNamedImport("z", "zod");
     }
@@ -236,10 +245,14 @@ export const emitZod = (analysis) => {
                     });
                     // Export type for this declaration if typeExports is enabled
                     if (typeExports && exportRefs) {
+                        const typeName = resolveDeclarationTypeName(refName);
                         emitter.addTypeExport({
-                            name: refName,
+                            name: typeName ?? refName,
                             type: `z.infer<typeof ${refName}>`,
                         });
+                        if (typeName) {
+                            usedTypeNames.add(typeName);
+                        }
                     }
                     continue;
                 }
@@ -252,10 +265,14 @@ export const emitZod = (analysis) => {
             });
             // Export type for this declaration if typeExports is enabled
             if (typeExports && exportRefs) {
+                const typeName = resolveDeclarationTypeName(refName);
                 emitter.addTypeExport({
-                    name: refName,
+                    name: typeName ?? refName,
                     type: `z.infer<typeof ${refName}>`,
                 });
+                if (typeName) {
+                    usedTypeNames.add(typeName);
+                }
             }
         }
     }
@@ -275,11 +292,18 @@ export const emitZod = (analysis) => {
     }
     // Export type for root schema if type option is set, or if typeExports is enabled
     if (name && (type || typeExports)) {
-        const typeName = typeof type === "string" ? type : `${name[0].toUpperCase()}${name.substring(1)}`;
-        emitter.addTypeExport({
-            name: typeName,
-            type: `z.infer<typeof ${name}>`,
-        });
+        const rootTypeName = typeof type === "string"
+            ? type
+            : naming && rootBaseName
+                ? resolveTypeName(rootBaseName, naming, { isRoot: true, isLifted: false }, usedTypeNames)
+                : `${name[0].toUpperCase()}${name.substring(1)}`;
+        if (rootTypeName) {
+            emitter.addTypeExport({
+                name: rootTypeName,
+                type: `z.infer<typeof ${name}>`,
+            });
+            usedTypeNames.add(rootTypeName);
+        }
     }
     return emitter.render();
 };

package/dist/index.js

@@ -33,6 +33,7 @@ export * from "./utils/namingService.js";
 export * from "./utils/omit.js";
 export * from "./utils/resolveRef.js";
 export * from "./utils/resolveUri.js";
+export * from "./utils/schemaNaming.js";
 export * from "./utils/schemaRepresentation.js";
 export * from "./utils/withMessage.js";
 export * from "./zodToJsonSchema.js";

package/dist/parsers/parseSchema.js

@@ -18,6 +18,7 @@ import { parseNullable } from "./parseNullable.js";
 import { anyOrUnknown } from "../utils/anyOrUnknown.js";
 import { resolveUri } from "../utils/resolveUri.js";
 import { resolveRef } from "../utils/resolveRef.js";
+import { ensureUnique, resolveSchemaName, sanitizeIdentifier } from "../utils/schemaNaming.js";
 export const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockMeta) => {
     // Ensure ref bookkeeping exists so $ref declarations and getter-based recursion work
     refs.root = refs.root ?? schema;
@@ -253,10 +254,20 @@ const getOrCreateRefName = (pointer, path, refs) => {
     if (refs.refNameByPointer?.has(pointer)) {
         return refs.refNameByPointer.get(pointer);
     }
-    const preferred = buildNameFromPath(path, refs.usedNames);
-    refs.refNameByPointer?.set(pointer, preferred);
-    refs.usedNames?.add(preferred);
-    return preferred;
+    if (!refs.naming) {
+        const preferred = buildNameFromPath(path, refs.usedNames);
+        refs.refNameByPointer?.set(pointer, preferred);
+        refs.usedNames?.add(preferred);
+        return preferred;
+    }
+    const baseName = buildBaseNameFromPath(path, refs.usedBaseNames);
+    const schemaName = resolveSchemaName(baseName, refs.naming, { isRoot: false, isLifted: true }, refs.usedNames);
+    refs.refNameByPointer?.set(pointer, schemaName);
+    refs.refBaseNameByPointer?.set(pointer, baseName);
+    refs.baseNameBySchema?.set(schemaName, baseName);
+    refs.usedNames?.add(schemaName);
+    refs.usedBaseNames?.add(baseName);
+    return schemaName;
 };
 const buildNameFromPath = (path, used) => {
     const filtered = path
@@ -289,19 +300,36 @@ const buildNameFromPath = (path, used) => {
         finalName += "Schema";
     }
     const sanitized = sanitizeIdentifier(finalName);
-    if (!used || !used.has(sanitized))
-        return sanitized;
-    let counter = 2;
-    let candidate = `${sanitized}${counter}`;
-    while (used.has(candidate)) {
-        counter += 1;
-        candidate = `${sanitized}${counter}`;
-    }
-    return candidate;
+    return ensureUnique(sanitized, used);
 };
-const sanitizeIdentifier = (value) => {
-    const cleaned = value.replace(/^[^a-zA-Z_$]+/, "").replace(/[^a-zA-Z0-9_$]/g, "");
-    return cleaned || "Ref";
+const buildBaseNameFromPath = (path, used) => {
+    const filtered = path
+        .map((segment, idx) => {
+        if (idx === 0 && (segment === "$defs" || segment === "definitions")) {
+            return undefined; // root-level defs prefix is redundant for naming
+        }
+        if (segment === "properties")
+            return undefined; // skip noisy properties segment
+        if (segment === "$defs" || segment === "definitions")
+            return "Defs";
+        return segment;
+    })
+        .filter((segment) => segment !== undefined);
+    const base = filtered.length
+        ? filtered
+            .map((segment) => typeof segment === "number"
+            ? `Ref${segment}`
+            : segment
+                .toString()
+                .replace(/[^a-zA-Z0-9_$]/g, " ")
+                .split(" ")
+                .filter(Boolean)
+                .map(capitalize)
+                .join(""))
+            .join("")
+        : "Ref";
+    const sanitized = sanitizeIdentifier(base);
+    return ensureUnique(sanitized, used);
 };
 const capitalize = (value) => value.length ? value[0].toUpperCase() + value.slice(1) : value;
 const addDefaults = (schema, parsed) => {

package/dist/types/Types.d.ts

@@ -73,6 +73,16 @@ export type JsonSchemaObject = {
 } & Record<string, unknown>;
 export type ParserSelector = (schema: JsonSchemaObject, refs: Refs) => SchemaRepresentation;
 export type ParserOverride = (schema: JsonSchemaObject, refs: Refs) => string | void;
+export type NamingContext = {
+    isRoot: boolean;
+    isLifted: boolean;
+};
+export type NamingOptions = {
+    /** Customize the const name for schemas. Defaults to appending "Schema". */
+    schemaName?: (baseName: string, ctx: NamingContext) => string;
+    /** Customize the type name for schemas. Defaults to baseName when naming is enabled. */
+    typeName?: (baseName: string, ctx: NamingContext) => string | undefined;
+};
 export type Options = {
     name?: string;
     withoutDefaults?: boolean;
@@ -80,6 +90,8 @@ export type Options = {
     withJsdocs?: boolean;
     /** Use .meta() instead of .describe() - includes id, title, description */
     withMeta?: boolean;
+    /** Customize schema and type naming for root and lifted schemas. */
+    naming?: NamingOptions;
     parserOverride?: ParserOverride;
     depth?: number;
     type?: boolean | string;
@@ -184,7 +196,10 @@ export type Refs = Options & {
     dependencies?: Map<string, Set<string>>;
     inProgress?: Set<string>;
     refNameByPointer?: Map<string, string>;
+    refBaseNameByPointer?: Map<string, string>;
+    baseNameBySchema?: Map<string, string>;
     usedNames?: Set<string>;
+    usedBaseNames?: Set<string>;
     currentSchemaName?: string;
     cycleRefNames?: Set<string>;
     cycleComponentByName?: Map<string, number>;

package/dist/types/core/analyzeSchema.d.ts

@@ -8,6 +8,9 @@ export type AnalysisResult = {
     schema: JsonSchema;
     options: NormalizedOptions;
     refNameByPointer: Map<string, string>;
+    refBaseNameByPointer: Map<string, string>;
+    baseNameBySchema: Map<string, string>;
+    rootBaseName?: string;
     usedNames: Set<string>;
     declarations: Map<string, SchemaRepresentation>;
     dependencies: Map<string, Set<string>>;

package/dist/types/index.d.ts

@@ -33,6 +33,7 @@ export * from "./utils/namingService.js";
 export * from "./utils/omit.js";
 export * from "./utils/resolveRef.js";
 export * from "./utils/resolveUri.js";
+export * from "./utils/schemaNaming.js";
 export * from "./utils/schemaRepresentation.js";
 export * from "./utils/withMessage.js";
 export * from "./zodToJsonSchema.js";

package/dist/types/utils/schemaNaming.d.ts

@@ -0,0 +1,6 @@
+import { NamingContext, NamingOptions } from "../Types.js";
+export declare const defaultSchemaName: (baseName: string) => string;
+export declare const sanitizeIdentifier: (value: string) => string;
+export declare const ensureUnique: (candidate: string, used?: Set<string>) => string;
+export declare const resolveSchemaName: (baseName: string, naming: NamingOptions, ctx: NamingContext, used?: Set<string>) => string;
+export declare const resolveTypeName: (baseName: string, naming: NamingOptions, ctx: NamingContext, used?: Set<string>) => string | undefined;

package/dist/utils/schemaNaming.js

@@ -0,0 +1,31 @@
+export const defaultSchemaName = (baseName) => `${baseName}Schema`;
+export const sanitizeIdentifier = (value) => {
+    const cleaned = value.replace(/^[^a-zA-Z_$]+/, "").replace(/[^a-zA-Z0-9_$]/g, "");
+    return cleaned || "Ref";
+};
+export const ensureUnique = (candidate, used) => {
+    if (!used)
+        return candidate;
+    if (!used.has(candidate))
+        return candidate;
+    let counter = 2;
+    let unique = `${candidate}${counter}`;
+    while (used.has(unique)) {
+        counter += 1;
+        unique = `${candidate}${counter}`;
+    }
+    return unique;
+};
+export const resolveSchemaName = (baseName, naming, ctx, used) => {
+    const schemaNameFn = naming.schemaName ?? defaultSchemaName;
+    const candidate = sanitizeIdentifier(schemaNameFn(baseName, ctx));
+    return ensureUnique(candidate, used);
+};
+export const resolveTypeName = (baseName, naming, ctx, used) => {
+    const typeNameFn = naming.typeName ?? ((name) => name);
+    const candidate = typeNameFn(baseName, ctx);
+    if (!candidate)
+        return undefined;
+    const sanitized = sanitizeIdentifier(candidate);
+    return ensureUnique(sanitized, used);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gabrielbryk/json-schema-to-zod",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Converts JSON schema objects or files into Zod schemas",
   "type": "module",
   "types": "./dist/types/index.d.ts",