@flattype/models 1.5.0 → 1.7.0

package/README.md

@@ -19,6 +19,8 @@
   <a href="https://www.npmjs.com/package/@flattype/react"><img src="https://img.shields.io/npm/v/@flattype/react?label=%40flattype%2Freact&color=8b6cff" alt="npm @flattype/react"></a>
   <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://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">
@@ -33,6 +35,8 @@
   <a href="#react"><b>React</b></a> ·
   <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="#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>
@@ -41,10 +45,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 71 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 and Angular in real apps, and the size comparison with JSON and TOON">
+      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">
   </a>
   <br>
-  <sub>▶ <a href="https://github.com/karammm/flattype/blob/main/docs/assets/flattype-intro.mp4">Watch the 71-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 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>
 </p>
 
 ---
@@ -103,7 +107,7 @@ app.use(flatExpress()); // server: res.json() answers in Flat Notation when the
 const users = await flatFetch("/api/users", { model: User, list: true }); // client: User[]
 ```
 
-And in React, Vue or Angular:
+And in React, Vue, Angular, Svelte or Solid:
 
 ```tsx
 import { useFlat } from "@flattype/react"; // or "@flattype/vue": the same API, with refs
@@ -112,6 +116,10 @@ const { data: users, loading, error } = useFlat("/api/users", { model: User, lis
 
 // Angular: signals on top of HttpClient
 users = flatResource(() => "/api/users", { model: User, list: true }); // users.value(): User[] | undefined
+
+// Svelte: a store, $users.data; Solid: a resource
+const users = flatStore("/api/users", { model: User, list: true });
+const [users] = createFlatResource(() => "/api/users", { model: User, list: true });
 ```
 
 ## Why FlatType
@@ -133,9 +141,11 @@ users = flatResource(() => "/api/users", { model: User, list: true }); // users.
 | [`@flattype/react`](https://github.com/karammm/flattype/blob/main/packages/react) | `useFlat`, `useFlatSuspense`, `useFlatStream`, `useModel`, `FlatProvider` | +1.4 KB |
 | [`@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/shared`](https://github.com/karammm/flattype/blob/main/packages/shared) | Shared TypeScript types | types only |
 
-Svelte bindings, Claude helpers and a CLI are planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
+A CLI with code generation is planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
 ## The format
 
@@ -381,6 +391,108 @@ export class UsersComponent {
 
 Angular 19+ (built with partial compilation, so it works with every later version). A runnable Angular 22 app with Playwright tests in three browsers is in [`examples/angular-app`](https://github.com/karammm/flattype/blob/main/examples/angular-app).
 
+## Svelte and Solid
+
+```bash
+npm install @flattype/svelte @flattype/models
+```
+
+**Svelte** (3, 4 and 5). The stores follow the Svelte store contract, so `$store` just works:
+
+```svelte
+<script lang="ts">
+  import { createFlat } from "@flattype/svelte";
+  import { derived, writable } from "svelte/store";
+
+  const api = createFlat({ baseURL: "/api", headers: () => ({ authorization: `Bearer ${token}` }) });
+
+  const users = api.store("/users", { model: User, list: true });            // $users.data: User[] | undefined
+  const id = writable(1);
+  const user = api.store(derived(id, (i) => `/users/${i}`), { model: User }); // the URL can be a store
+  const events = api.streamStore("/export", { model: Row, table: "rows" });   // rows while downloading
+</script>
+
+{#each $users.data ?? [] as u (u.id)}<li>{u.fullName}</li>{/each}
+<p>{$events.done ? "Done" : `Loading… ${$events.rows.length}`}</p>
+```
+
+**Solid** (`@flattype/svelte/solid`):
+
+```tsx
+import { createFlatResource, createFlatStream } from "@flattype/svelte/solid";
+
+const [user, { refetch }] = createFlatResource(() => `/users/${props.id}`, { baseURL: "/api", model: User });
+const events = createFlatStream(() => "/api/export", { model: Row, table: "rows" });
+
+<Suspense fallback={<Spinner />}>
+  <Show when={user()}>{(u) => <h2>{u().fullName}</h2>}</Show>
+</Suspense>;
+```
+
+| API | What it does |
+| --- | --- |
+| `flatStore(url, options)` | A store of `{ data, error, loading }` plus `refetch()`. Lazy: it fetches on the first subscriber and aborts when the last one leaves. A URL store change aborts the old request |
+| `flatStreamStore(url, options)` | A store of `{ rows, done, error }` plus `restart()`. One update per network chunk |
+| `modelStore(source, Model)` | Maps another store's value to a model |
+| `createFlatResource(() => url, options)` | A Solid resource, for `<Suspense>` and `<ErrorBoundary>`. Aborts on change and on cleanup |
+| `createFlatStream(() => url, options)` | `rows`, `done` and `error` accessors plus `restart()` |
+
+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`).
+
 ## Benchmarks
 
 `pnpm compare` on the fixtures in [`fixtures/`](https://github.com/karammm/flattype/blob/main/fixtures/index.mjs) (Node 24, Apple Silicon):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flattype/models",
-  "version": "1.5.0",
+  "version": "1.7.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.5.0",
-    "@flattype/shared": "1.5.0"
+    "@flattype/core": "1.7.0",
+    "@flattype/shared": "1.7.0"
   },
   "publishConfig": {
     "access": "public"