@flattype/models 1.7.0 → 1.8.0

package/README.md

@@ -21,6 +21,7 @@
   <a href="https://www.npmjs.com/package/@flattype/angular"><img src="https://img.shields.io/npm/v/@flattype/angular?label=%40flattype%2Fangular&color=8b6cff" alt="npm @flattype/angular"></a>
   <a href="https://www.npmjs.com/package/@flattype/svelte"><img src="https://img.shields.io/npm/v/@flattype/svelte?label=%40flattype%2Fsvelte&color=8b6cff" alt="npm @flattype/svelte"></a>
   <a href="https://www.npmjs.com/package/@flattype/ai"><img src="https://img.shields.io/npm/v/@flattype/ai?label=%40flattype%2Fai&color=8b6cff" alt="npm @flattype/ai"></a>
+  <a href="https://www.npmjs.com/package/@flattype/cli"><img src="https://img.shields.io/npm/v/@flattype/cli?label=%40flattype%2Fcli&color=8b6cff" alt="npm @flattype/cli"></a>
   <a href="https://github.com/karammm/flattype/actions/workflows/ci.yml"><img src="https://github.com/karammm/flattype/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/core-3.7_KB_min%2Bgz-2fd4b2" alt="3.7 KB min+gz">
   <img src="https://img.shields.io/badge/dependencies-0-2fd4b2" alt="No third-party dependencies">
@@ -37,6 +38,7 @@
   <a href="#angular"><b>Angular</b></a> ·
   <a href="#svelte-and-solid"><b>Svelte &amp; Solid</b></a> ·
   <a href="#claude-and-llms"><b>Claude &amp; LLMs</b></a> ·
+  <a href="#cli"><b>CLI</b></a> ·
   <a href="#benchmarks"><b>Benchmarks</b></a> ·
   <a href="https://github.com/karammm/flattype/blob/main/CHANGELOG.md"><b>Changelog</b></a> ·
   <a href="https://github.com/karammm/flattype/blob/main/ROADMAP.md"><b>Roadmap</b></a>
@@ -45,10 +47,10 @@
 <p align="center">
   <a href="https://github.com/karammm/flattype/blob/main/docs/assets/flattype-intro.mp4">
     <img src="https://raw.githubusercontent.com/karammm/flattype/main/docs/assets/flattype-intro.gif" width="820"
-      alt="FlatType.js in 77 seconds: an API response encoded to Flat Notation, how tables and dot paths keep it small, typed models mapped from snake_case JSON, an Express server answering in Flat Notation or JSON, React, Vue, Angular and Svelte in real apps, and the size comparison with JSON and TOON">
+      alt="FlatType.js in 84 seconds: an API response encoded to Flat Notation, how tables and dot paths keep it small, typed models mapped from snake_case JSON, an Express server answering in Flat Notation or JSON, React, Vue, Angular and Svelte in real apps, the CLI generating models from OpenAPI, and the size comparison with JSON and TOON">
   </a>
   <br>
-  <sub>▶ <a href="https://github.com/karammm/flattype/blob/main/docs/assets/flattype-intro.mp4">Watch the 77-second intro in full quality</a>. Every result shown is real output, generated by <a href="https://github.com/karammm/flattype/blob/main/scripts/video/record.mjs"><code>scripts/video/record.mjs</code></a>.</sub>
+  <sub>▶ <a href="https://github.com/karammm/flattype/blob/main/docs/assets/flattype-intro.mp4">Watch the 84-second intro in full quality</a>. Every result shown is real output, generated by <a href="https://github.com/karammm/flattype/blob/main/scripts/video/record.mjs"><code>scripts/video/record.mjs</code></a>.</sub>
 </p>
 
 ---
@@ -143,9 +145,10 @@ const [users] = createFlatResource(() => "/api/users", { model: User, list: true
 | [`@flattype/angular`](https://github.com/karammm/flattype/blob/main/packages/angular) | `flatInterceptor` for HttpClient, the signal-based `flatResource` / `flatStream`, the `flatModel` pipe | +1.8 KB |
 | [`@flattype/svelte`](https://github.com/karammm/flattype/blob/main/packages/svelte) | Svelte stores (`flatStore`, `flatStreamStore`, `modelStore`), and `/solid` with `createFlatResource` / `createFlatStream` | +1.1 KB / +0.9 KB |
 | [`@flattype/ai`](https://github.com/karammm/flattype/blob/main/packages/ai) | `toPrompt`, `fromModelOutput`, `countTokens`, and MCP / Claude tool results | +1.3 KB |
+| [`@flattype/cli`](https://github.com/karammm/flattype/blob/main/packages/cli) | The `flattype` command: `encode`, `decode`, `stats`, and `gen` (models from samples or OpenAPI) | Node tool |
 | [`@flattype/shared`](https://github.com/karammm/flattype/blob/main/packages/shared) | Shared TypeScript types | types only |
 
-A CLI with code generation is planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
+Docs, a playground and published benchmarks are next on the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md). See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
 ## The format
 
@@ -493,6 +496,58 @@ messages.push({ role: "user", content: [claudeToolResult(toolUse.id, await runTo
 
 See [`examples/ai-claude`](https://github.com/karammm/flattype/blob/main/examples/ai-claude) for a token report, a full Claude round trip, and a runnable MCP server (`claude mcp add flattype-orders -- node mcp-server.mjs`).
 
+## CLI
+
+```bash
+npx @flattype/cli --help        # or: npm install -D @flattype/cli, then use `flattype …`
+```
+
+```bash
+# Convert, in pipes or files
+curl -s https://api.example.com/users | npx @flattype/cli encode
+npx @flattype/cli decode users.flat -o users.json
+
+# Compare sizes
+npx @flattype/cli stats users.json
+#                 bytes      gzip
+# JSON           169545     12890
+# Flat            93606     12568
+# saved             45%        2%
+
+# Generate typed models from an OpenAPI spec (3.0, 3.1 or Swagger 2; JSON or YAML)…
+npx @flattype/cli gen --openapi openapi.yaml -o src/models.ts
+
+# …or from a real response
+curl -s https://api.example.com/users > users.json && npx @flattype/cli gen --sample users.json --name UsersPage
+```
+
+For an OpenAPI schema like
+
+```yaml
+Customer:
+  type: object
+  required: [id, full_name, created_at]
+  properties:
+    id: { type: integer }
+    full_name: { type: string }
+    created_at: { type: string, format: date-time }
+    address: { $ref: "#/components/schemas/Address" }
+```
+
+`flattype gen --openapi` writes:
+
+```ts
+export const Customer = defineModel({
+  id: "integer",
+  fullName: "string",
+  createdAt: "date",
+  address: { type: Address, optional: true },
+}, { keys: "snake" });
+export type Customer = Infer<typeof Customer>;
+```
+
+It handles `$ref` between schemas, `allOf`, `required` (other fields become optional), `nullable` and `type: [..., "null"]`, `date` and `date-time` formats, enums and inline objects. A recursive reference becomes `"any"`, and the CLI warns you. Exit code 1 means bad input, 2 means a usage error. From code, use `fromOpenAPI(spec)` together with `toSource(models)`.
+
 ## Benchmarks
 
 `pnpm compare` on the fixtures in [`fixtures/`](https://github.com/karammm/flattype/blob/main/fixtures/index.mjs) (Node 24, Apple Silicon):

package/dist/index.cjs

@@ -321,8 +321,10 @@ function singular(s) {
   if (/[^s]s$/.test(s)) return s.slice(0, -1);
   return s;
 }
-function toSource(model, name) {
+function toSource(modelOrModels, name) {
+  const roots = isModel(modelOrModels) ? [[name ?? "Model", modelOrModels]] : Object.entries(modelOrModels);
   const names = /* @__PURE__ */ new Map();
+  const emitted = /* @__PURE__ */ new Set();
   const used = /* @__PURE__ */ new Set();
   const blocks = [];
   const unique = (base) => {
@@ -332,10 +334,13 @@ function toSource(model, name) {
     return n;
   };
   const emit = (m, want) => {
-    const known = names.get(m);
-    if (known) return known;
-    const id = unique(want);
-    names.set(m, id);
+    let id = names.get(m);
+    if (id && emitted.has(m)) return id;
+    if (!id) {
+      id = unique(want);
+      names.set(m, id);
+    }
+    emitted.add(m);
     const lines = [];
     for (const [field, spec] of Object.entries(m.shape)) {
       const key = IDENT.test(field) ? field : JSON.stringify(field);
@@ -363,7 +368,8 @@ export type ${id} = Infer<typeof ${id}>;`);
     if (o.from !== void 0) parts.push(`from: ${JSON.stringify(o.from)}`);
     return `{ ${parts.join(", ")} }`;
   };
-  emit(model, pascal(name));
+  for (const [n, m] of roots) if (!names.has(m)) names.set(m, unique(pascal(n)));
+  for (const [, m] of roots) emit(m, names.get(m));
   return `import { defineModel, type Infer } from "@flattype/models";
 
 ${blocks.join("\n\n")}

package/dist/index.d.cts

@@ -109,8 +109,12 @@ declare function defineModel<const S extends Shape>(shape: S, options?: ModelOpt
 declare function infer(sample: unknown, options?: {
     keys?: KeyStyle;
 }): Model<Record<string, unknown>>;
-/** Prints TypeScript source for a model and the models nested in it. */
+/**
+ * Prints TypeScript source for a model and the models nested in it, or for several named models at once
+ * (`toSource({ User, Order })`), where a model used by another is referenced by its name, not repeated.
+ */
 declare function toSource(model: Model<unknown>, name: string): string;
+declare function toSource(models: Record<string, Model<unknown>>): string;
 
 /** `createdAt` → `created_at`, `userID` → `user_id`. */
 declare function toSnake(s: string): string;

package/dist/index.d.ts

@@ -109,8 +109,12 @@ declare function defineModel<const S extends Shape>(shape: S, options?: ModelOpt
 declare function infer(sample: unknown, options?: {
     keys?: KeyStyle;
 }): Model<Record<string, unknown>>;
-/** Prints TypeScript source for a model and the models nested in it. */
+/**
+ * Prints TypeScript source for a model and the models nested in it, or for several named models at once
+ * (`toSource({ User, Order })`), where a model used by another is referenced by its name, not repeated.
+ */
 declare function toSource(model: Model<unknown>, name: string): string;
+declare function toSource(models: Record<string, Model<unknown>>): string;
 
 /** `createdAt` → `created_at`, `userID` → `user_id`. */
 declare function toSnake(s: string): string;

package/dist/index.js

@@ -289,8 +289,10 @@ function singular(s) {
   if (/[^s]s$/.test(s)) return s.slice(0, -1);
   return s;
 }
-function toSource(model, name) {
+function toSource(modelOrModels, name) {
+  const roots = isModel(modelOrModels) ? [[name ?? "Model", modelOrModels]] : Object.entries(modelOrModels);
   const names = /* @__PURE__ */ new Map();
+  const emitted = /* @__PURE__ */ new Set();
   const used = /* @__PURE__ */ new Set();
   const blocks = [];
   const unique = (base) => {
@@ -300,10 +302,13 @@ function toSource(model, name) {
     return n;
   };
   const emit = (m, want) => {
-    const known = names.get(m);
-    if (known) return known;
-    const id = unique(want);
-    names.set(m, id);
+    let id = names.get(m);
+    if (id && emitted.has(m)) return id;
+    if (!id) {
+      id = unique(want);
+      names.set(m, id);
+    }
+    emitted.add(m);
     const lines = [];
     for (const [field, spec] of Object.entries(m.shape)) {
       const key = IDENT.test(field) ? field : JSON.stringify(field);
@@ -331,7 +336,8 @@ export type ${id} = Infer<typeof ${id}>;`);
     if (o.from !== void 0) parts.push(`from: ${JSON.stringify(o.from)}`);
     return `{ ${parts.join(", ")} }`;
   };
-  emit(model, pascal(name));
+  for (const [n, m] of roots) if (!names.has(m)) names.set(m, unique(pascal(n)));
+  for (const [, m] of roots) emit(m, names.get(m));
   return `import { defineModel, type Infer } from "@flattype/models";
 
 ${blocks.join("\n\n")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flattype/models",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Typed models for API data: key mapping, coercion and defaults, from JSON or Flat Notation.",
   "license": "MIT",
   "type": "module",
@@ -33,8 +33,8 @@
     "flattype"
   ],
   "dependencies": {
-    "@flattype/core": "1.7.0",
-    "@flattype/shared": "1.7.0"
+    "@flattype/core": "1.8.0",
+    "@flattype/shared": "1.8.0"
   },
   "publishConfig": {
     "access": "public"