@amritk/generate-parsers 0.5.0 → 0.6.0

package/src/generators/build-schema.test.ts

@@ -34,9 +34,9 @@ describe('build-schema', () => {
     expect(filenames).toContain('contact.ts')
     expect(filenames).toContain('schema.ts')
     const schemaFile = result.find((file) => file.filename === 'schema.ts')
-    // The generated schema.ts should declare SchemaObject and parseSchemaObject from the user's $defs/schema
-    expect(schemaFile?.content).toContain('export type SchemaObject')
-    expect(schemaFile?.content).toContain('parseSchemaObject')
+    // The generated schema.ts should declare Schema and parseSchema from the user's $defs/schema
+    expect(schemaFile?.content).toContain('export type Schema')
+    expect(schemaFile?.content).toContain('parseSchema')
   })
 
   it('applies extensions to matching definitions during build', async () => {
@@ -193,8 +193,8 @@ describe('build-schema', () => {
     const result = await buildSchema(schema, 'Document', undefined, true)
     const documentFile = result.find((file) => file.filename === 'document.ts')
 
-    expect(documentFile?.content).toContain("import type { ContactObject } from './contact';")
-    expect(documentFile?.content).not.toContain('parseContactObject')
+    expect(documentFile?.content).toContain("import type { Contact } from './contact';")
+    expect(documentFile?.content).not.toContain('parseContact')
   })
 
   it('still generates files for all $ref definitions in types-only mode', async () => {
@@ -246,8 +246,8 @@ describe('build-schema', () => {
     const result = await buildSchema(schema, 'Document', undefined, true)
     const contactFile = result.find((file) => file.filename === 'contact.ts')
 
-    expect(contactFile?.content).toContain('export type ContactObject')
-    expect(contactFile?.content).not.toContain('export const parseContactObject')
+    expect(contactFile?.content).toContain('export type Contact')
+    expect(contactFile?.content).not.toContain('export const parseContact')
   })
 
   it('applies extensions correctly in types-only mode', async () => {
@@ -273,7 +273,7 @@ describe('build-schema', () => {
     // Extension property should still appear in the type
     expect(parameterFile?.content).toContain("'x-enabled'")
     // But no parser should be generated
-    expect(parameterFile?.content).not.toContain('parseParameterObject')
+    expect(parameterFile?.content).not.toContain('parseParameter')
   })
 
   it('warns and skips when a $ref cannot be resolved', async () => {
@@ -322,7 +322,7 @@ describe('build-schema', () => {
     // Own property should be present in the object literal
     expect(documentFile?.content).toContain('name?:')
     // allOf ref generates an intersection type with the referenced type
-    expect(documentFile?.content).toContain('TaggableObject')
+    expect(documentFile?.content).toContain('Taggable')
     // The taggable definition should generate its own file
     const filenames = result.map((f) => f.filename)
     expect(filenames).toContain('taggable.ts')
@@ -356,11 +356,11 @@ describe('build-schema', () => {
     const documentFile = result.find((file) => file.filename === 'document.ts')
     const filenames = result.map((f) => f.filename)
 
-    // ExamplesObject IS imported since allOf generates an intersection type
-    expect(documentFile?.content).toContain('ExamplesObject')
+    // Examples IS imported since allOf generates an intersection type
+    expect(documentFile?.content).toContain('Examples')
     // The examples definition generates its own file
     expect(filenames).toContain('examples.ts')
-    // ExampleItemObject is also resolved from additionalProperties
+    // ExampleItem is also resolved from additionalProperties
     expect(filenames).toContain('example-item.ts')
   })
 
@@ -435,7 +435,7 @@ describe('build-schema', () => {
     const filenames = result.map((f) => f.filename)
 
     // specification-extensions is now treated like any other allOf ref
-    expect(documentFile?.content).toContain('SpecificationExtensionsObject')
+    expect(documentFile?.content).toContain('SpecificationExtensions')
     // The specification-extensions definition generates its own file
     expect(filenames).toContain('specification-extensions.ts')
     // x-custom property is NOT inlined into document.ts — it's in specification-extensions.ts
@@ -546,7 +546,7 @@ describe('build-schema', () => {
     // Both files are generated independently — they map to different filenames now
     expect(filenames).toContain('parameter.ts')
     expect(filenames).toContain('parameter-or-reference.ts')
-    // The parameter.ts should contain the real ParameterObject type
+    // The parameter.ts should contain the real Parameter type
     const parameterFile = result.find((f) => f.filename === 'parameter.ts')
     expect(parameterFile?.content).toContain('name')
     expect(parameterFile?.content).toContain('in')
@@ -572,7 +572,7 @@ describe('build-schema', () => {
     expect(indexFile).toBeDefined()
     // Named type + parser + shape-validator exports for each file
     expect(indexFile?.content).toContain(
-      "export { type ContactObject, validateContactObjectShape, parseContactObject } from './contact';",
+      "export { type Contact, validateContactShape, parseContact } from './contact';",
     )
     expect(indexFile?.content).toContain(
       "export { type Document, validateDocumentShape, parseDocument } from './document';",
@@ -601,9 +601,9 @@ describe('build-schema', () => {
 
     expect(indexFile).toBeDefined()
     // Types-only: export type { ... } syntax, no parsers
-    expect(indexFile?.content).toContain("export type { ContactObject } from './contact';")
+    expect(indexFile?.content).toContain("export type { Contact } from './contact';")
     expect(indexFile?.content).toContain("export type { Document } from './document';")
-    expect(indexFile?.content).not.toContain('parseContactObject')
+    expect(indexFile?.content).not.toContain('parseContact')
     expect(indexFile?.content).not.toContain('parseDocument')
     // No wildcard exports
     expect(indexFile?.content).not.toContain('export *')

package/src/generators/build-schema.ts

@@ -96,6 +96,9 @@ const extractDynamicAnchorDefs = (schema: JSONSchema): string[] => {
  *   directory while the helper sources are emitted once at the output root.
  * @param readonly - When true, every property, array, and record in the generated type
  *   definitions is emitted as `readonly`.
+ * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
+ *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
+ *   is used verbatim and is not affected by this suffix.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -138,6 +141,7 @@ export const buildSchema = async (
   helpersMode: HelpersMode = 'package',
   helpersImportPrefix = './',
   readonly = false,
+  typeSuffix = '',
 ): Promise<GeneratedFile[]> => {
   // Upgrade draft-07 schemas to 2020-12 conventions before processing.
   // This renames `definitions` → `$defs` recursively so the rest of the
@@ -165,6 +169,7 @@ export const buildSchema = async (
     helpersMode,
     helpersImportPrefix,
     readonly,
+    typeSuffix,
     ...(logWarnings !== undefined ? { logWarnings } : {}),
     ...(strict !== undefined ? { strict } : {}),
   })
@@ -206,7 +211,7 @@ export const buildSchema = async (
 
     // Generate file for this ref, resolving any $dynamicRef to $ref first
     // and applying any matching extensions for this definition
-    const typeName = refToName(ref)
+    const typeName = refToName(ref, typeSuffix)
     const filename = refToFilename(ref)
     const processedSchema = resolveDynamicRefs(resolvedSchema as JSONSchema, dynamicRefMap)
     const extendedSchema = extensions ? applySchemaExtensions(processedSchema, filename, extensions) : processedSchema
@@ -217,6 +222,7 @@ export const buildSchema = async (
       helpersMode,
       helpersImportPrefix,
       readonly,
+      typeSuffix,
       ...(logWarnings !== undefined ? { logWarnings } : {}),
       ...(strict !== undefined ? { strict } : {}),
     })

package/src/generators/generate-files.test.ts

@@ -13,9 +13,7 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Document')
 
-    expect(result).toContain(
-      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
-    )
+    expect(result).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
   })
 
   it('calls imported parser for optional $ref property', () => {
@@ -29,7 +27,7 @@ describe('generate-files', () => {
     const { content: result } = generateFile(schema, 'Document')
 
     // With local variable caching, optional $ref properties use the cached variable
-    expect(result).toContain('_contact !== undefined && { contact: parseContactObject(_contact) }')
+    expect(result).toContain('_contact !== undefined && { contact: parseContact(_contact) }')
   })
 
   it('calls imported parser for required $ref property', () => {
@@ -44,7 +42,7 @@ describe('generate-files', () => {
     const { content: result } = generateFile(schema, 'Document')
 
     // With local variable caching, required $ref properties use the cached variable
-    expect(result).toContain('contact: parseContactObject(_contact),')
+    expect(result).toContain('contact: parseContact(_contact),')
   })
 
   it('generates combined imports for multiple $ref properties', () => {
@@ -58,12 +56,8 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Document')
 
-    expect(result).toContain(
-      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
-    )
-    expect(result).toContain(
-      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
-    )
+    expect(result).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
+    expect(result).toContain("import { type Server, parseServer, validateServerShape } from './server';")
   })
 
   it('generates correct parser name for multi-word $ref', () => {
@@ -77,9 +71,9 @@ describe('generate-files', () => {
     const { content: result } = generateFile(schema, 'Document')
 
     expect(result).toContain(
-      "import { type ExternalDocumentationObject, parseExternalDocumentationObject, validateExternalDocumentationObjectShape } from './external-documentation';",
+      "import { type ExternalDocumentation, parseExternalDocumentation, validateExternalDocumentationShape } from './external-documentation';",
     )
-    expect(result).toContain('parseExternalDocumentationObject(_externalDoc)')
+    expect(result).toContain('parseExternalDocumentation(_externalDoc)')
   })
 
   it('does not generate ref imports when no $ref properties exist', () => {
@@ -113,7 +107,7 @@ describe('generate-files', () => {
     // Non-ref property should have inline validation against the cached local
     expect(result).toContain('typeof _name === "string"')
     // Ref property should call imported parser using cached variable
-    expect(result).toContain('parseContactObject(_contact)')
+    expect(result).toContain('parseContact(_contact)')
   })
 
   it('generates a correct import for -or-reference style $ref names', () => {
@@ -128,9 +122,9 @@ describe('generate-files', () => {
     const { content: result } = generateFile(schema, 'Document')
 
     expect(result).toContain(
-      "import { type CallbacksOrReferenceObject, parseCallbacksOrReferenceObject, validateCallbacksOrReferenceObjectShape } from './callbacks-or-reference';",
+      "import { type CallbacksOrReference, parseCallbacksOrReference, validateCallbacksOrReferenceShape } from './callbacks-or-reference';",
     )
-    expect(result).toContain('parseCallbacksOrReferenceObject(_callbacks)')
+    expect(result).toContain('parseCallbacksOrReference(_callbacks)')
   })
 
   it('generates arrow function parser', () => {
@@ -160,11 +154,9 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Document')
 
-    expect(result).toContain(
-      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
-    )
+    expect(result).toContain("import { type Server, parseServer, validateServerShape } from './server';")
     // With local variable caching, array validators use the cached variable
-    expect(result).toContain('validateArray(_servers, parseServerObject)')
+    expect(result).toContain('validateArray(_servers, parseServer)')
   })
 
   it('maps array items through imported parser for required array with $ref items', () => {
@@ -182,14 +174,12 @@ describe('generate-files', () => {
     const { content: result } = generateFile(schema, 'Document')
 
     // Check for required imports
-    expect(result).toContain(
-      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
-    )
+    expect(result).toContain("import { type Server, parseServer, validateServerShape } from './server';")
     expect(result).toContain("import { validateArray } from '@amritk/helpers/validate-array';")
     expect(result).toContain("import { isObject } from '@amritk/helpers/is-object';")
 
     // Check for required array validation using cached variable
-    expect(result).toContain('servers: validateArray(_servers, parseServerObject),')
+    expect(result).toContain('servers: validateArray(_servers, parseServer),')
 
     // Should not use spread operator for required fields
     expect(result).not.toContain('...(_servers')
@@ -261,8 +251,8 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Document', { typesOnly: true })
 
-    expect(result).toContain("import type { ContactObject } from './contact';")
-    expect(result).not.toContain('parseContactObject')
+    expect(result).toContain("import type { Contact } from './contact';")
+    expect(result).not.toContain('parseContact')
   })
 
   it('does not include runtime helper imports in types-only mode', () => {
@@ -311,8 +301,8 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Document', { typesOnly: true })
 
-    expect(result).toContain("import type { ServerObject } from './server';")
-    expect(result).not.toContain('parseServerObject')
+    expect(result).toContain("import type { Server } from './server';")
+    expect(result).not.toContain('parseServer')
     expect(result).not.toContain('validateArray')
   })
 
@@ -324,8 +314,8 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Paths', { typesOnly: true })
 
-    expect(result).toContain("import type { PathItemObject } from './path-item';")
-    expect(result).not.toContain('parsePathItemObject')
+    expect(result).toContain("import type { PathItem } from './path-item';")
+    expect(result).not.toContain('parsePathItem')
     expect(result).not.toContain('validateRecord')
   })
 
@@ -336,10 +326,10 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Pet', { typesOnly: true })
 
-    expect(result).toContain("import type { CatObject } from './cat';")
-    expect(result).toContain("import type { DogObject } from './dog';")
-    expect(result).not.toContain('parseCatObject')
-    expect(result).not.toContain('parseDogObject')
+    expect(result).toContain("import type { Cat } from './cat';")
+    expect(result).toContain("import type { Dog } from './dog';")
+    expect(result).not.toContain('parseCat')
+    expect(result).not.toContain('parseDog')
   })
 
   it('generates type-only imports for anyOf $ref variants in types-only mode', () => {
@@ -354,10 +344,10 @@ describe('generate-files', () => {
 
     const { content: result } = generateFile(schema, 'Wrapper', { typesOnly: true })
 
-    expect(result).toContain("import type { StringValueObject } from './string-value';")
-    expect(result).toContain("import type { NumberValueObject } from './number-value';")
-    expect(result).not.toContain('parseStringValueObject')
-    expect(result).not.toContain('parseNumberValueObject')
+    expect(result).toContain("import type { StringValue } from './string-value';")
+    expect(result).toContain("import type { NumberValue } from './number-value';")
+    expect(result).not.toContain('parseStringValue')
+    expect(result).not.toContain('parseNumberValue')
   })
 
   it('does not change default behavior when typesOnly is false', () => {
@@ -372,16 +362,14 @@ describe('generate-files', () => {
     const { content: explicitFalseResult } = generateFile(schema, 'Document', { typesOnly: false })
 
     expect(defaultResult).toBe(explicitFalseResult)
-    expect(defaultResult).toContain(
-      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
-    )
+    expect(defaultResult).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
     expect(defaultResult).toContain('export const parseDocument')
   })
 
   it('does not generate a self-import for recursive schemas in types-only mode', () => {
-    // Mirrors the 3.2.0 encoding schema: EncodingObject has properties itemEncoding, prefixEncoding,
+    // Mirrors the 3.2.0 encoding schema: Encoding has properties itemEncoding, prefixEncoding,
     // and encoding that all $ref back to #/$defs/encoding. The generated encoding.ts must not
-    // import EncodingObject from itself.
+    // import Encoding from itself.
     const schema = {
       type: 'object',
       properties: {
@@ -401,14 +389,14 @@ describe('generate-files', () => {
       },
     }
 
-    const { content: result } = generateFile(schema, 'EncodingObject', {
+    const { content: result } = generateFile(schema, 'Encoding', {
       typesOnly: true,
       selfRef: '#/$defs/encoding',
     })
 
-    expect(result).not.toContain("import type { EncodingObject } from './encoding';")
-    expect(result).toContain("import type { HeaderOrReferenceObject } from './header-or-reference';")
-    expect(result).toContain('export type EncodingObject')
+    expect(result).not.toContain("import type { Encoding } from './encoding';")
+    expect(result).toContain("import type { HeaderOrReference } from './header-or-reference';")
+    expect(result).toContain('export type Encoding')
   })
 
   it('does not generate a self-import for recursive schemas in full parser mode', () => {
@@ -423,13 +411,38 @@ describe('generate-files', () => {
       },
     }
 
-    const { content: result } = generateFile(schema, 'EncodingObject', { selfRef: '#/$defs/encoding' })
+    const { content: result } = generateFile(schema, 'Encoding', { selfRef: '#/$defs/encoding' })
 
-    expect(result).not.toContain(
-      "import { type EncodingObject, parseEncodingObject, validateEncodingObjectShape } from './encoding';",
-    )
+    expect(result).not.toContain("import { type Encoding, parseEncoding, validateEncodingShape } from './encoding';")
     expect(result).toContain(
-      "import { type HeaderOrReferenceObject, parseHeaderOrReferenceObject, validateHeaderOrReferenceObjectShape } from './header-or-reference';",
+      "import { type HeaderOrReference, parseHeaderOrReference, validateHeaderOrReferenceShape } from './header-or-reference';",
     )
   })
+
+  describe('typeSuffix', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        contact: { $ref: '#/$defs/contact' },
+      },
+      required: ['contact'],
+    }
+
+    it('appends the suffix to ref-derived type, parser, and import names', () => {
+      const { content: result } = generateFile(schema, 'Document', { typeSuffix: 'Object' })
+
+      expect(result).toContain(
+        "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+      )
+      expect(result).toContain('contact: ContactObject;')
+      expect(result).toContain('contact: parseContactObject(_contact)')
+    })
+
+    it('emits no suffix by default', () => {
+      const { content: result } = generateFile(schema, 'Document')
+
+      expect(result).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
+      expect(result).not.toContain('ContactObject')
+    })
+  })
 })

package/src/generators/generate-files.ts

@@ -59,6 +59,11 @@ type GenerateFileOptions = {
    * definitions is emitted as `readonly`.
    */
   readonly readonly?: boolean
+  /**
+   * Suffix appended to every type/parser name derived from a `$ref`.
+   * Defaults to `''` (no suffix). Set to e.g. `'Object'` to emit `ContactObject`.
+   */
+  readonly typeSuffix?: string
 }
 
 /** Result of generating a single parser file. */
@@ -105,11 +110,12 @@ export const generateFile = (
   const selfRef = options?.selfRef
   const rootSchema = options?.rootSchema
   const helpersMode: HelpersMode = options?.helpersMode ?? 'package'
-  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false })
+  const typeSuffix = options?.typeSuffix ?? ''
+  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false, typeSuffix })
 
   if (typesOnly) {
     // In types-only mode, skip the parser function and use type-only imports
-    const imports = collectImports(schema, { typesOnly: true, selfRef, rootSchema })
+    const imports = collectImports(schema, { typesOnly: true, selfRef, rootSchema, typeSuffix })
     let result = ''
 
     if (imports.length > 0) {
@@ -125,13 +131,14 @@ export const generateFile = (
 
   const parserFunction = generateParserFunction(schema, typeName, {
     useRefImports: true,
+    typeSuffix,
     ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
     ...(options?.strict !== undefined ? { strict: options.strict } : {}),
   })
-  const shapeValidator = generateShapeValidator(schema, typeName, true)
+  const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix)
   const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`
   const helpers: CollectedHelpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix)
-  const imports = [...collectImports(schema, { selfRef, rootSchema }), ...helpers.imports]
+  const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix }), ...helpers.imports]
 
   // Build file output using string concatenation instead of array join for performance
   let result = ''