@flattype/models 1.6.0 → 1.8.0

package/README.md

@@ -20,6 +20,8 @@
   <a href="https://www.npmjs.com/package/@flattype/vue"><img src="https://img.shields.io/npm/v/@flattype/vue?label=%40flattype%2Fvue&color=8b6cff" alt="npm @flattype/vue"></a>
   <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">
@@ -35,6 +37,8 @@
   <a href="#vue"><b>Vue</b></a> ·
   <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>
@@ -43,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>
 
 ---
@@ -140,9 +144,11 @@ const [users] = createFlatResource(() => "/api/users", { model: User, list: true
 | [`@flattype/vue`](https://github.com/karammm/flattype/blob/main/packages/vue) | The same composables for Vue 3, with reactive URLs, plus the `createFlat()` plugin | +1.2 KB |
 | [`@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 |
 
-Claude helpers and a CLI are 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
 
@@ -436,6 +442,112 @@ const events = createFlatStream(() => "/api/export", { model: Row, table: "rows"
 
 The stores also work in Solid, or anywhere else, through the store contract: `from(flatStore(...))`. Runnable apps with Playwright tests in three browsers are in [`examples/svelte-app`](https://github.com/karammm/flattype/blob/main/examples/svelte-app) and [`examples/solid-app`](https://github.com/karammm/flattype/blob/main/examples/solid-app).
 
+## Claude and LLMs
+
+```bash
+npm install @flattype/ai
+```
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { countTokens, fromModelOutput, outputInstructions, toPrompt } from "@flattype/ai";
+
+const client = new Anthropic();
+
+// 1. Data in: Flat Notation inside <data> tags, with a one-line legend the model reads once.
+const response = await client.beta.messages.create({
+  model: "claude-opus-5-5",
+  max_tokens: 16000,
+  betas: ["server-side-fallback-2026-07-01"],
+  fallbacks: "default", // if a safety classifier declines, retry on the recommended fallback model
+  messages: [{
+    role: "user",
+    content: `${toPrompt(orders, { name: "orders" })}\n\nTotal spent per customer?\n\n${outputInstructions([{ customer: "Alice", spent: 120 }])}`,
+  }],
+});
+
+// 2. Data out: tolerant of tags, fences, prose and JSON, then validated into typed models.
+const reply = response.content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+const totals = fromModelOutput(reply, { model: Total, list: true }); // Total[]
+
+// 3. Measure it with Claude's own tokenizer (count_tokens is free).
+const { json, flat, saved } = await countTokens(client, orders);
+```
+
+**Tool results** shrink too, which matters most for agents that call tools over and over:
+
+```ts
+import { claudeToolResult, toolResult } from "@flattype/ai";
+
+// MCP server (@modelcontextprotocol/sdk): returns a CallToolResult with Flat Notation text
+server.registerTool("list_orders", { description: "…" }, async () => toolResult(await db.orders()));
+
+// Claude API tool loop: a tool_result block for the next user message
+messages.push({ role: "user", content: [claudeToolResult(toolUse.id, await runTool(toolUse))] });
+```
+
+| API | What it does |
+| --- | --- |
+| `toPrompt(data, { name, legend })` | `<data format="flat-notation">` plus a one-line legend. The block is still valid Flat Notation; put the legend in your system prompt once with `legend: false` |
+| `outputInstructions(example)` | Asks the model to answer in Flat Notation and shows the exact shape you expect |
+| `fromModelOutput(reply, { model, list })` | Finds the data (last `<data>` block, code fence, or the text itself), skips prose lines, and accepts JSON too |
+| `countTokens(client, data, { model })` | `{ json, flat, saved }` in real Claude tokens, minus per-message overhead. Takes any client with `messages.countTokens` |
+| `toolResult(data, { structured })` / `claudeToolResult(id, data)` | MCP `CallToolResult` and Claude API `tool_result` blocks |
+
+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.6.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.6.0",
-    "@flattype/shared": "1.6.0"
+    "@flattype/core": "1.8.0",
+    "@flattype/shared": "1.8.0"
   },
   "publishConfig": {
     "access": "public"