@amritk/mjst 0.5.1 → 0.7.0

package/README.md

@@ -44,9 +44,43 @@ The package ships a `mjst` bin that runs under Node ≥ 20 (or Bun), so you can
 ### CLI
 
 ```bash
-npx mjst --schema ./schema.json --outDir ./generated
+npx mjst --schema ./schema.json --out-dir ./generated
 ```
 
+> [!NOTE]
+> Every flag accepts both kebab-case and camelCase, so `--out-dir` and `--outDir` are equivalent.
+
+### Single file
+
+Pass `--out-file` instead of `--out-dir` to concatenate every generated definition into one
+self-contained file. This is currently supported together with `--types-only`:
+
+```bash
+npx mjst --schema ./schema.json --out-file ./generated/schema.ts --types-only
+```
+
+### Recursive — a whole folder of schemas
+
+Point `--schema-dir` at a directory of JSON Schemas and mjst generates parsers for every
+`*.json` file it finds, mirroring the directory layout under `--out-dir`:
+
+```bash
+npx mjst --schema-dir ./schemas --out-dir ./generated
+```
+
+```
+schemas/                  generated/
+  user.json        ─▶       user/
+  api/                        document.ts, index.ts
+    order.json     ─▶       api/order/
+                              document.ts, index.ts
+                            _helpers/        ← shared runtime helpers (embedded mode)
+```
+
+Each schema lands in its own subdirectory so generated files never collide, and in embedded
+mode the runtime helpers are emitted **once** into `outDir/_helpers/` — every nested parser
+imports from that single shared location. `--build` compiles the whole tree in place.
+
 ### Config file
 
 ```bash
@@ -63,16 +97,20 @@ npx mjst --config ./mjst.config.json
 <!-- config-table-start -->
 | | Property | CLI Flag | Type | Required | Default | Description |
 |:---:|:---|:---|:---:|:---:|:---:|:---|
-| 📄 | `schema` | `--schema <path>` | `string` | ✅ | — | Path to the schema to process. With the default 'json' input this is a JSON Schema file that is read and parsed. With any other input format it is a JS/TS module that exports a schema, which is loaded and converted to JSON Schema via the matching adapter. |
+| 📄 | `schema` | `--schema <path>` | `string` | — | — | Path to the schema to process. With the default 'json' input this is a JSON Schema file that is read and parsed. With any other input format it is a JS/TS module that exports a schema, which is loaded and converted to JSON Schema via the matching adapter. Either 'schema' or 'schemaDir' is required. |
+| 🗂️ | `schemaDir` | `--schema-dir <dir>` | `string` | — | — | Path to a directory of JSON Schema files. When set, the CLI walks the directory recursively, generates parsers for every '*.json' schema it finds, and mirrors the directory layout under outDir (each schema lands in its own subdirectory). The runtime helpers are emitted once into a shared outDir/_helpers/ that every nested parser imports from. Mutually exclusive with 'schema'; when both are present 'schemaDir' wins. Only JSON Schema input is supported in this mode. |
 | 🔌 | `input` | `--input <format>` | `string` | — | `"json"` | Source format of the schema. 'json' (default) reads a JSON Schema file directly. Any other format loads 'schema' as a module and converts it to JSON Schema with the matching adapter. Supported: 'typebox', 'zod' (zod v4+), 'valibot' (with @valibot/to-json-schema), and 'effect' — each requires the corresponding library installed in your project. |
 | 📦 | `export` | `--export <name>` | `string` | — | — | Which export of the schema module to use when 'input' is not 'json'. Defaults to the default export, or the sole named export when the module has exactly one. |
-| 📁 | `outDir` | `--outDir <dir>` | `string` | ✅ | — | Output directory for generated TypeScript files. The directory is created automatically if it does not exist. Subdirectories are created as needed when a generated file includes a nested path. |
+| 📁 | `outDir` | `--out-dir <dir>` | `string` | — | — | Output directory for generated TypeScript files. The directory is created automatically if it does not exist. Subdirectories are created as needed when a generated file includes a nested path. Mutually exclusive with 'outFile'. |
+| 📄 | `outFile` | `--out-file <file>` | `string` | — | — | Output everything to a single TypeScript file instead of a directory. Every generated definition is concatenated into one self-contained file and the cross-file imports are dropped. Mutually exclusive with 'outDir'. Currently supported only together with 'typesOnly'. |
 | 🏷️ | `typesOnly` | `--types-only` | `boolean` | — | `false` | Generate only TypeScript type definitions without parser functions. Useful when you only need the type shapes and do not need runtime validation. |
 | 🔨 | `build` | `--build` | `boolean` | — | `false` | Compile the generated TypeScript files to .js and .d.ts output. A temporary tsconfig is written to the output directory, tsc is invoked, and the intermediate .ts source files are removed when compilation succeeds. |
 | ⚠️ | `logWarnings` | `--log-warnings` | `boolean` | — | `false` | Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime. |
 | 🚫 | `strict` | `--strict` | `boolean` | — | `false` | Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. Unknown extra keys are still allowed. |
+| 🔒 | `readonly` | `--readonly` | `boolean` | — | `false` | Emit every property, array, and record in the generated type definitions as readonly, producing deeply immutable types. Affects type definitions only; the generated parsers still build and return plain objects. |
 | 🧰 | `helpers` | `--helpers <mode>` | `string` | — | — | Controls how generated parsers reference their runtime helpers. 'package' emits imports from @amritk/helpers (requires it to be installed in the consumer project). 'embedded' ships the helper source under outDir/_helpers/ so the output is self-contained. When omitted, the CLI auto-detects: it picks 'package' if @amritk/helpers resolves from outDir, otherwise 'embedded'. |
-| ⚙️ | `config` | `--config <path>` | `string` | — | — | Path to a JSON config file. Keys match the option names in this schema (schema, outDir, typesOnly, build, logWarnings, strict, helpers). CLI flags take precedence over config file values. |
+| 🏷️ | `typeSuffix` | `--type-suffix <suffix>` | `string` | — | `""` | Suffix appended to every generated type name derived from a $ref (e.g. 'Object' turns Contact into ContactObject). Defaults to no suffix. The root type name is used verbatim and is unaffected. |
+| ⚙️ | `config` | `--config <path>` | `string` | — | — | Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, outDir, outFile, typesOnly, build, logWarnings, strict, readonly, helpers, typeSuffix). CLI flags take precedence over config file values. |
 <!-- config-table-end -->
 
 ---

package/dist/cli-config.d.ts

@@ -5,7 +5,15 @@ import type { SourceFormat } from '@amritk/adapters/source-format';
  */
 export type CliConfig = {
     /** Path to the schema to process — a JSON Schema file, or a JS/TS module when `input` is set. */
-    readonly schema: string;
+    readonly schema?: string;
+    /**
+     * Path to a directory of JSON Schema files. When set, the CLI walks the directory
+     * recursively, generates parsers for every `*.json` schema it finds, and mirrors the
+     * directory layout under `outDir`. A single shared `_helpers/` directory is emitted at
+     * the root of `outDir` (in embedded mode) and every nested parser imports from it.
+     * Mutually exclusive with `schema`; when both are present `schemaDir` wins.
+     */
+    readonly schemaDir?: string;
     /**
      * The source format of the schema. Defaults to `'json'` (a plain JSON Schema file).
      * Any other format loads `schema` as a module and converts it via the matching adapter.
@@ -16,8 +24,13 @@ export type CliConfig = {
      * Defaults to the default export, or the sole named export when there is exactly one.
      */
     readonly export?: string;
-    /** Output directory for generated TypeScript files. */
-    readonly outDir: string;
+    /** Output directory for generated TypeScript files. Mutually exclusive with `outFile`. */
+    readonly outDir?: string;
+    /**
+     * Output everything to a single TypeScript file instead of a directory of files.
+     * Mutually exclusive with `outDir`. Currently supported only with `typesOnly`.
+     */
+    readonly outFile?: string;
     /**
      * When true, only generate TypeScript type definitions without parser functions.
      * Useful when you only need the type shapes and do not need runtime validation.
@@ -49,4 +62,15 @@ export type CliConfig = {
      * resolves from outDir, otherwise falls back to `'embedded'`.
      */
     readonly helpers?: 'package' | 'embedded';
+    /**
+     * When true, every property, array, and record in the generated type
+     * definitions is emitted as `readonly`, producing deeply immutable types.
+     */
+    readonly readonly?: boolean;
+    /**
+     * Suffix appended to every generated type name derived from a `$ref`
+     * (e.g. `'Object'` turns `Contact` into `ContactObject`). Defaults to `''`
+     * (no suffix). The root type name is used verbatim and is unaffected.
+     */
+    readonly typeSuffix?: string;
 };