@flattype/models 1.7.0 → 1.9.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://github.com/karammm/flattype">
+  <a href="https://karammm.github.io/flattype/docs/">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/karammm/flattype/main/docs/assets/logo-dark.svg">
       <img src="https://raw.githubusercontent.com/karammm/flattype/main/docs/assets/logo-light.svg" alt="FlatType.js" width="300">
@@ -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">
@@ -28,6 +29,8 @@
 </p>
 
 <p align="center">
+  <a href="https://karammm.github.io/flattype/docs/"><b>Documentation</b></a> ·
+  <a href="https://karammm.github.io/flattype/"><b>Playground</b></a> ·
   <a href="#quick-start"><b>Quick start</b></a> ·
   <a href="#the-format"><b>Format</b></a> ·
   <a href="#typed-models"><b>Models</b></a> ·
@@ -37,6 +40,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 +49,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 +147,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).
+Everything is documented at [karammm.github.io/flattype/docs](https://karammm.github.io/flattype/docs/), and you can try the format on your own data in the [playground](https://karammm.github.io/flattype/). See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
 ## The format
 
@@ -493,6 +498,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):
@@ -510,7 +567,7 @@ See [`examples/ai-claude`](https://github.com/karammm/flattype/blob/main/example
 | **FlatType `decode`** | **0.73 ms** |
 | TOON `decode` | 5.9 ms |
 
-Some honest notes on these numbers:
+Numbers measured on every docs build are on the [benchmarks page](https://karammm.github.io/flattype/docs/guide/benchmarks). Some honest notes on them:
 
 - **The savings come from lists.** A single small object is about the same size as JSON.
 - **Gzip already removes most of JSON's repeated keys,** so gzipped network sizes come out close. FlatType makes the biggest difference where text isn't compressed: LLM prompts and tool results, logs, caches and local storage.
@@ -524,11 +581,19 @@ pnpm build && pnpm typecheck && pnpm test
 pnpm bench        # encode/decode vs JSON
 pnpm compare      # size and parse time vs JSON and TOON
 pnpm check:size   # bundle budgets
+pnpm --filter @flattype/core test:perf                        # linear-time checks on hostile input
+FUZZ_RUNS=50000 pnpm --filter @flattype/core exec vitest run  # deep fuzzing, as in CI
+pnpm --filter @flattype/docs dev                              # docs site (VitePress)
+pnpm --filter @flattype/playground dev                        # playground
 pnpm video        # re-render docs/assets/flattype-intro.{mp4,gif} (needs ffmpeg and the Angular example built)
 ```
 
 This is a pnpm + Turborepo monorepo built with tsup and tested with Vitest and fast-check. Releases use Changesets, and all `@flattype/*` packages share one version number. Every release follows the checklist in [ROADMAP.md](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
+## Security
+
+The decoder is prototype-safe, runs in linear time on hostile input, and only ever throws `FlatDecodeError`. Deep fuzzing and timing tests check this on every push, as described on the [security page](https://karammm.github.io/flattype/docs/guide/security). Please report vulnerabilities privately, following [SECURITY.md](https://github.com/karammm/flattype/blob/main/SECURITY.md).
+
 ## Contributing
 
 Issues and pull requests are welcome. If you have a payload that FlatType handles badly, please [open an issue](https://github.com/karammm/flattype/issues) with a sample; it becomes a test fixture.

package/dist/index.cjs

@@ -55,7 +55,7 @@ var ModelError = class extends Error {
 // src/model.ts
 var PRIMITIVES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "date", "any"]);
 var FAIL = /* @__PURE__ */ Symbol("fail");
-var NUMERIC = /^\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*$/;
+var NUMERIC = /^\s*[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?\s*$/;
 var ISO_DATE = /^\d{4}-\d{2}-\d{2}/;
 function isModel(v) {
   return typeof v === "object" && v !== null && v.__model === true;
@@ -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

@@ -23,7 +23,7 @@ var ModelError = class extends Error {
 // src/model.ts
 var PRIMITIVES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "date", "any"]);
 var FAIL = /* @__PURE__ */ Symbol("fail");
-var NUMERIC = /^\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*$/;
+var NUMERIC = /^\s*[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?\s*$/;
 var ISO_DATE = /^\d{4}-\d{2}-\d{2}/;
 function isModel(v) {
   return typeof v === "object" && v !== null && v.__model === true;
@@ -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.9.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.9.0",
+    "@flattype/shared": "1.9.0"
   },
   "publishConfig": {
     "access": "public"
@@ -55,6 +55,7 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist .turbo",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:perf": "vitest run --config vitest.perf.config.ts"
   }
 }