ajsc 5.2.3 → 7.0.0

package/README.md

@@ -1,198 +1,306 @@
-# ajsc - Another JSON Schema Parser
+# ajsc — Another JSON Schema Converter
 
-**ajsc** is an npm package that transforms JSON Schema definitions into an intermediate representation (IR) called `IRNode`. This intermediate form is designed to be consumed by language-specific converters—such as the built-in [TypeScript converter](#typescriptconverter)—or by any custom converter you create for languages like Kotlin or Swift. This library streamlines the process of converting API JSON Schema definitions into strong-typed code representations, ensuring consistency between your API contracts and client implementations.
+**ajsc** transforms JSON Schema documents into idiomatic, language-native code for **TypeScript**, **Kotlin**, and **Swift**. It exposes a small function-style API for typical codegen pipelines, plus class-based converters for advanced extension.
 
----
+```bash
+npm install ajsc
+```
 
-## Features
+```ts
+import { emitTypescript, emitKotlin, emitSwift } from "ajsc";
 
-- **Comprehensive Schema Parsing:**  
-  Convert JSON Schema types including strings, numbers, booleans, nulls, literals, enums, unions, intersections, arrays, and objects into a unified IR.
+const schema = {
+  title: "User",
+  type: "object",
+  properties: {
+    id:    { type: "integer" },
+    name:  { type: "string" },
+    email: { type: "string", format: "email" },
+  },
+  required: ["id", "name"],
+};
 
-- **Intermediate Representation (`IRNode`):**  
-  The `IRNode` provides a standard structure that captures type, constraints, and path information. This representation is ideal for further transformation into various target languages.
+const ts = emitTypescript(schema);
+const kt = emitKotlin(schema);
+const sw = emitSwift(schema);
+```
 
-- **Plugin-Based Architecture:**  
-  Use the provided language plugin (currently, a [TypeScript converter](#typescriptconverter)) or write your own converter to support additional languages such as Kotlin or Swift.
+Each emit function returns the same shape:
 
-- **$defs and References Handling:**  
-  Resolve JSON Schema definitions (`$defs`) and references (`$ref`) seamlessly, ensuring reusable schema components are properly processed.
+```ts
+interface EmitResult {
+  code: string;                   // declarations only — no `import` lines
+  rootTypeName: string;           // top-level emitted type ("User")
+  extractedTypeNames: string[];   // additional types emitted (nested objects, enums, variants)
+  imports: string[];              // language-native module/symbol paths to import
+}
+```
 
-- **Unique Signature Tracking:**  
-  For objects and arrays, the library tracks unique signatures to avoid duplicate type definitions when converting to code.
+`code` contains type declarations only. Consumers assemble the final source file by combining `imports` with `code`.
 
 ---
 
-## Installation
+## Output examples
 
-Install **ajsc** via npm:
+### TypeScript
 
-```bash
-npm install ajsc
+```ts
+import { emitTypescript } from "ajsc";
+
+const { code } = emitTypescript({
+  title: "User", type: "object",
+  properties: { id: { type: "integer" }, name: { type: "string" } },
+  required: ["id", "name"],
+});
+
+// code:
+// export type User = { id: number; name: string; };
 ```
 
-## Usage
+### Kotlin (default: kotlinx-serialization)
+
+```ts
+import { emitKotlin } from "ajsc";
+
+const { code, imports } = emitKotlin({
+  title: "User", type: "object",
+  properties: { id: { type: "integer" }, name: { type: "string" } },
+  required: ["id", "name"],
+});
+
+// imports: ["kotlinx.serialization.Serializable"]
+// code:
+// @Serializable
+// data class User(
+//   val id: Long,
+//   val name: String,
+// )
+```
 
-### Basic Conversion to IRNode
+Pass `serializer: "none"` for plain types with no annotations.
 
-The primary function of ajsc is to convert a JSON Schema into an IRNode. Here’s an example of converting a simple JSON Schema that defines a string type:
+### Swift (default: Codable)
 
-```javascript
-import { JSONSchemaConverter } from "ajsc";
+```ts
+import { emitSwift } from "ajsc";
 
-const schema = { type: "string" };
-const converter = new JSONSchemaConverter(schema);
+const { code, imports } = emitSwift({
+  title: "User", type: "object",
+  properties: { id: { type: "integer" }, name: { type: "string" } },
+  required: ["id", "name"],
+});
 
-console.log(converter.irNode);
-// Output:
-// {
-//   type: "string",
-//   constraints: {},
-//   path: "",
+// imports: []
+// code:
+// public struct User: Codable {
+//   public let id: Int64
+//   public let name: String
 // }
 ```
 
-Converting Complex Schemas
-You can also convert more complex schemas including objects, arrays, unions, intersections, and even schemas with $defs:
-
-```javascript
-import { JSONSchemaConverter } from "ajsc";
-
-const complexSchema = {
-  $defs: {
-    Person: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        age: { type: "number" },
-      },
-      required: ["name"],
-    },
-  },
-  type: "object",
-  properties: {
-    person: { $ref: "#/$defs/Person" },
-  },
-};
+Pass `serializer: "none"` to drop `Codable` conformance.
+
+### Assembling a final file
 
-const converter = new JSONSchemaConverter(complexSchema);
-console.log(converter.irNode);
+```ts
+const { code, imports } = emitKotlin(schema);
+const file = [...imports.map((i) => `import ${i}`), "", code].join("\n");
 ```
 
-## API Reference
+Swift `imports` are module names (`["Foundation"]`); Kotlin `imports` are fully-qualified symbol paths. TypeScript `imports` is always empty.
+
+---
+
+## Package layout
+
+| Subpath          | Exports                                                                                                |
+|------------------|--------------------------------------------------------------------------------------------------------|
+| `ajsc`           | `emitTypescript`, `emitKotlin`, `emitSwift`, `EmitResult`, plus the converter classes (re-exported)    |
+| `ajsc/typescript`| `TypescriptConverter`, `TypescriptBaseConverter`, related types                                        |
+| `ajsc/kotlin`    | `KotlinConverter`, `KotlinBaseConverter`, `sanitizeKotlinIdentifier`, `KOTLIN_RESERVED`                |
+| `ajsc/swift`     | `SwiftConverter`, `SwiftBaseConverter`, `sanitizeSwiftIdentifier`, `SWIFT_RESERVED`                    |
+| `ajsc/converter` | `BaseConverter`, `Emitter`, `walkIR`, `LanguageProfile`, `BaseConverterOpts`, `RefTypeEntry`, etc.     |
+| `ajsc/ir`        | `JSONSchemaConverter` (JSON Schema → IRNode tree)                                                      |
+| `ajsc/types`     | `IRNode`, `ILanguageConverter`, signature types                                                        |
+| `ajsc/utils`     | `PathUtils`, `toPascalCase`                                                                            |
+
+The root (`ajsc`) is the typical entry point. Subpaths are for advanced use — extending a converter, accessing the IR layer, building a custom language target.
+
+---
+
+## Function-style vs class-style
 
-### JSONSchemaConverter
+```ts
+// Function-style — recommended for most consumers.
+import { emitKotlin } from "ajsc";
+const result = emitKotlin(schema, opts);
 
-- Constructor:
-  `new JSONSchemaConverter(schema: object)`
-- Properties:
-  - irNode: The resulting intermediate representation of the JSON Schema.
-- Supported Schema Types:
-  - Primitive Types: string, number, boolean, null
-  - Literals: Using the const keyword.
-  - Enums: Using the enum property.
-  - Unions: When type is an array (e.g., ["string", "number"]).
-  - Intersections: Using allOf to combine multiple schemas.
-  - Arrays: With type: "array" and an items schema.
-  - Objects: With type: "object" and a properties definition.
-  - $defs and $ref: For defining and referencing reusable schema parts.
+// Class-style — for subclassing or accessing converter internals.
+import { KotlinConverter } from "ajsc/kotlin";
+const converter = new KotlinConverter(schema, opts);
+console.log(converter.code, converter.imports);
+```
 
-### TypescriptConverter
+Both produce identical output; the function form just bundles `code`, `rootTypeName`, `extractedTypeNames`, `imports` into a single return value. For codegen pipelines, the function form is usually nicer — it avoids the `new` and gives a stable result shape.
 
-The package includes a TypeScript language plugin that converts the IRNode into TypeScript type definitions.
+---
 
-- Constructor:
-  `new TypescriptConverter(schema: object, options?: TypescriptConverterOpts)`
-- Properties:
-  - code: A string containing the generated TypeScript code.
+## Options
 
-#### Options
+All three converters accept `BaseConverterOpts` plus language-specific options.
+
+### Shared options (`BaseConverterOpts`)
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `inlineTypes` | `boolean` | `false` | If true, object types are inlined instead of extracted as named type aliases. |
-| `depluralize` | `boolean` | `true` | Singularize array item type names. Handles irregular plurals (e.g. `entries` → `Entry`, `people` → `Person`). |
-| `arrayItemNaming` | `string \| false` | `false` | Controls the postfix for array item type names. `false` = no postfix, `string` = custom postfix (e.g. `"Item"` → `ContactItem`). |
-| `enumStyle` | `"union" \| "enum"` | `"union"` | `"union"` emits `"a" \| "b"`, `"enum"` emits `export enum`. Only applies when `inlineTypes` is false and all values are strings. |
-| `uncountableWords` | `string[]` | `undefined` | Additional words that should not be singularized (built-in: `"data"`, `"metadata"`). |
+| `rootTypeName` | `string` | `schema.title \|\| "Root"` | Override the top-level type name. |
+| `arrayItemNaming` | `string \| false` | `false` | Postfix for array-item type names. `false` = property name, `"Item"` = `ContactsItem`. |
+| `depluralize` | `boolean` | `true` | Singularize array-item path segments (`entries` → `Entry`). |
+| `uncountableWords` | `string[]` | `[]` | Words to skip when singularizing. Built-ins: `data`, `metadata`. |
+| `unsupportedUnions` | `"throw" \| "fallback"` | `"throw"` | What to do with untagged unions: throw with a path-bearing error, or emit a language fallback type (`JsonElement` / `AnyCodable` / `any`). |
 
-#### Usage Examples
+### TypeScript (`TypescriptConverterOpts`)
 
-Default behavior — array item types are automatically singularized:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `inlineTypes` | `boolean` | `false` | If true, nested object types are inlined rather than extracted to named aliases. |
+| `enumStyle` | `"union" \| "enum"` | `"union"` | `"union"` emits `"a" \| "b" \| "c"`; `"enum"` emits `export enum Status { ... }`. |
+| `jsdoc` | `boolean` | `false` | Emit JSDoc comments from JSON Schema `description` and `title`. Requires `inlineTypes: false`. |
 
-```javascript
-import { TypescriptConverter } from "ajsc";
+### Kotlin (`KotlinConverterOpts`)
 
-const schema = {
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    age: { type: "number" },
-    contacts: {
-      type: "array",
-      items: {
-        type: "object",
-        properties: {
-          email: { type: "string" },
-        },
-        required: ["email"],
-      },
-    },
-    profile: {
-      type: "object",
-      properties: {
-        email: { type: "string" },
-      },
-      required: ["email"],
-    },
-  },
-  required: ["name", "age"],
-};
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serializer` | `"kotlinx" \| "none"` | `"kotlinx"` | Emit `@Serializable`/`@SerialName`/`@Contextual` annotations and matching imports. `"none"` emits plain types. |
+| `packageName` | `string` | `undefined` | If set, emit `package <name>` at the top of the output. |
 
-const tsConverter = new TypescriptConverter(schema);
-console.log(tsConverter.code);
+### Swift (`SwiftConverterOpts`)
 
-// Output:
-// export type Contact = { email: string; };
-// export type Profile = { email: string; };
-//
-// export type Root = { name: string; age: number; contacts?: Array<Contact>; profile?: Profile; };
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serializer` | `"codable" \| "none"` | `"codable"` | Emit `: Codable` conformance, `CodingKeys` enums, and discriminated-union `init(from:)`/`encode(to:)` plumbing. `"none"` emits plain types. |
+| `accessLevel` | `"public" \| "internal"` | `"public"` | Access modifier on emitted types and members. |
+
+---
+
+## Type mapping
+
+### TypeScript
+
+JSON Schema → idiomatic TS. `string` → `string`, `integer` → `number`, etc. Discriminated `oneOf`/`anyOf` → tagged union types. `$ref: "#"` → direct self-reference.
+
+### Kotlin (target: JVM)
+
+| JSON Schema | Kotlin | Notes |
+|-------------|--------|-------|
+| `string` | `String` | |
+| `string, format: date-time` | `java.time.Instant` | `@Contextual` under kotlinx |
+| `string, format: date` / `time` | `java.time.LocalDate` / `LocalTime` | `@Contextual` under kotlinx |
+| `string, format: uuid` | `java.util.UUID` | `@Contextual` under kotlinx |
+| `string, format: uri` | `java.net.URI` | `@Contextual` under kotlinx |
+| `string, format: email` / `hostname` / `ipv4` / `ipv6` | `String` + KDoc note | |
+| `integer` | `Long` | `format: int32` → `Int` |
+| `number` | `Double` | |
+| `boolean` | `Boolean` | |
+| `array` | `List<T>` | |
+| `object` | `data class` | `@Serializable` under kotlinx |
+| `enum` (string) | `enum class` | `@Serializable` under kotlinx |
+| `oneOf` w/ discriminator | `sealed interface` | `@JsonClassDiscriminator` under kotlinx |
+| Tuple length 2 / 3 | `Pair<A,B>` / `Triple<A,B,C>` | length > 3 throws |
+
+### Swift
+
+| JSON Schema | Swift | Notes |
+|-------------|-------|-------|
+| `string` | `String` | |
+| `string, format: date-time` | `Foundation.Date` | requires `JSONDecoder.dateDecodingStrategy = .iso8601` |
+| `string, format: uuid` | `Foundation.UUID` | |
+| `string, format: uri` | `Foundation.URL` | |
+| `string, format: email` etc. | `String` + `///` doc note | |
+| `integer` | `Int64` | `format: int32` → `Int32` |
+| `number` | `Double` | |
+| `boolean` | `Bool` | |
+| `array` | `[T]` | |
+| `object` | `struct` | `: Codable` by default |
+| `enum` (string) | `enum: String, Codable` | raw-value enum |
+| `oneOf` w/ discriminator | `enum` w/ associated values | hand-rolled `init(from:)`/`encode(to:)` |
+| Tuple (homogeneous) | `[T]` | |
+| Tuple (heterogeneous, codable) | throws | use `serializer: "none"` for native tuples |
+
+Schema-level `default` values are emitted inline for primitive types in Kotlin/Swift (`val foo: String = "x"`, `let foo: Int64 = 0`).
+
+---
+
+## Working with the IR directly
 
-Inline types (no extracted type aliases):
+If you need the intermediate representation (e.g., to write a custom emitter), use `JSONSchemaConverter`:
 
-```javascript
-const tsConverter = new TypescriptConverter(schema, { inlineTypes: true });
-console.log(tsConverter.code);
+```ts
+import { JSONSchemaConverter } from "ajsc/ir";
 
-// Output:
-// { name: string; age: number; contacts?: Array<{ email: string; }>; profile?: { email: string; }; }
+const ir = new JSONSchemaConverter({ type: "string" }).irNode;
+// { type: "string", path: "", constraints: {} }
 ```
 
-Enum style:
+`IRNode` shape is documented in `ajsc/types`.
 
-```javascript
-const enumSchema = {
-  type: "object",
-  properties: {
-    status: { type: "string", enum: ["active", "inactive", "pending"] },
-  },
-};
+## Building a custom language emitter
+
+To target a new language, extend `BaseConverter`:
 
-const tsConverter = new TypescriptConverter(enumSchema, { enumStyle: "enum" });
-console.log(tsConverter.code);
+```ts
+import { BaseConverter, type LanguageProfile } from "ajsc/converter";
 
-// Output:
-// export enum Status { Active = "active", Inactive = "inactive", Pending = "pending" }
-//
-// export type Root = { status?: Status; };
+class DartConverter extends BaseConverter {
+  protected readonly languageProfile: LanguageProfile = {
+    language: "dart",
+    // ... per-language overrides
+  };
+  // ... implement generateObjectType and the emission orchestration
+}
 ```
 
-Custom uncountable words:
+See `docs/architecture/README.md` for the layered design — `BaseConverter`, the `LanguageProfile` pattern, and the per-language helper module conventions used by Kotlin and Swift.
 
-```javascript
-const tsConverter = new TypescriptConverter(schema, {
-  uncountableWords: ["criteria", "alumni"],
-});
-// "criteria" array items will produce type "Criteria", not "Criterium"
+---
+
+## Migrating from v6 to v7
+
+### Breaking changes
+
+These are output changes for existing consumers. They're behavioral fixes, not regressions, but if you've been depending on the older shapes you'll see diffs:
+
+- **`$ref: "#"` recursion** in TypeScript now emits direct self-reference (`Array<Tree>`) rather than a buggy `Child` extraction with `Array<any>` recursion.
+- **`anyOf` merge** preserves the parent's `required` flag. A required schema field that gets anyOf-merged is now non-optional in output (`actor: Actor` instead of `actor?: Actor`).
+- **`oneOf` variant naming** in TypeScript now uses discriminator-derived names (`WrapperOuter`, `ScalarOuter`) rather than path-collision suffix names (`Outer`, `OuterType`). Kotlin and Swift always used the discriminator-derived form; this brings TS into alignment.
+- **`format: int32`** is now honored: emits `Int` (Kotlin) and `Int32` (Swift) where previously these always emitted `Long`/`Int64`. `format: int64` and unset format both still emit `Long`/`Int64`.
+- **Schema-level `default`** is now emitted in Kotlin and Swift property declarations for primitive defaults (`val foo: String = "x"`). TS output is unchanged.
+- **Swift acronym preservation**: enum case names for all-uppercase tokens (`US`, `URL`, `ID`) are no longer lowerCamelCased (`uS`/`uRL`/`iD`). They're preserved as-is.
+- **`./converter` extension API** has been heavily refactored. If you subclassed `BaseConverter` to override hook methods, see the new `LanguageProfile` pattern in `docs/architecture/README.md`. Most legacy hook overrides should migrate to a single `protected readonly languageProfile` field.
+
+### New features
+
+- **Kotlin and Swift converters.** First-class language targets, not just IR.
+- **Top-level emit functions.** `emitTypescript`, `emitKotlin`, `emitSwift` from `"ajsc"`.
+- **`./converter` subpath** for downstream extension authors.
+- **Root subpath restored.** `import { TypescriptConverter } from "ajsc"` works again (was subpath-only in v6).
+
+### Migrating v5 → v7
+
+If you're still on v5, the v6 → v7 changes apply on top of these:
+
+```diff
+- import { TypescriptConverter, JSONSchemaConverter } from "ajsc";
++ import { TypescriptConverter } from "ajsc";              // root entry restored
++ import { JSONSchemaConverter } from "ajsc/ir";           // moved to subpath in v6
 ```
+
+---
+
+## Architecture
+
+For contributors and downstream extension authors, see [`docs/architecture/README.md`](./docs/architecture/README.md) — the data flow, layered class hierarchy, `LanguageProfile` pattern, per-language module structure, and the steps to add a new language target.
+
+## License
+
+MIT