@flattype/models 1.1.0 → 1.3.0

package/README.md

@@ -15,8 +15,10 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@flattype/core"><img src="https://img.shields.io/npm/v/@flattype/core?label=%40flattype%2Fcore&color=8b6cff" alt="npm @flattype/core"></a>
   <a href="https://www.npmjs.com/package/@flattype/models"><img src="https://img.shields.io/npm/v/@flattype/models?label=%40flattype%2Fmodels&color=8b6cff" alt="npm @flattype/models"></a>
+  <a href="https://www.npmjs.com/package/@flattype/http"><img src="https://img.shields.io/npm/v/@flattype/http?label=%40flattype%2Fhttp&color=8b6cff" alt="npm @flattype/http"></a>
+  <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://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.5_KB_min%2Bgz-2fd4b2" alt="3.5 KB min+gz">
+  <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">
   <a href="https://github.com/karammm/flattype/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
 </p>
@@ -25,6 +27,8 @@
   <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> ·
+  <a href="#http"><b>HTTP</b></a> ·
+  <a href="#react"><b>React</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>
@@ -33,10 +37,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 42 seconds: an API response encoded to Flat Notation, how tables and dot paths keep it small, typed models mapped from snake_case JSON, and the size comparison with JSON and TOON">
+      alt="FlatType.js in 62 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 hooks in a real app, 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 42-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 62-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>
 
 ---
@@ -44,7 +48,7 @@
 ## Quick start
 
 ```bash
-npm install @flattype/core @flattype/models
+npm install @flattype/core @flattype/models @flattype/http
 ```
 
 ```ts
@@ -85,23 +89,44 @@ type User = Infer<typeof User>; // { id: number; fullName: string; createdAt: Da
 const users = User.parseList(await res.json()); // full_name → fullName, ISO string → Date
 ```
 
+Or let both ends speak Flat Notation, with JSON for every other client:
+
+```ts
+import { flatExpress, flatFetch } from "@flattype/http";
+
+app.use(flatExpress()); // server: res.json() answers in Flat Notation when the client asks
+
+const users = await flatFetch("/api/users", { model: User, list: true }); // client: User[]
+```
+
+And in React:
+
+```tsx
+import { useFlat } from "@flattype/react";
+
+const { data: users, loading, error } = useFlat("/api/users", { model: User, list: true }); // User[] | undefined
+```
+
 ## Why FlatType
 
 - **About half the size on list payloads.** A list of 1,000 users is 45% smaller than minified JSON and 50% smaller than TOON, because keys are written once and nested fields are flattened into the table header.
 - **Made for LLM context.** You pay for every character you send to Claude or another model. Flat Notation is plain `key: value` text that both models and people read easily, and `decode(text, { strict: false })` recovers data from model replies.
 - **Typed models without boilerplate.** Declare the fields you want and get full TypeScript types. snake_case keys, numeric strings, ISO dates, defaults and nullable fields are handled for you, and every problem is reported with its path.
+- **Drop-in for your API.** One middleware for Express, Fastify, Hono or any fetch-API server. Clients that ask get Flat Notation, everyone else still gets JSON, and big lists can be streamed row by row.
 - **Lossless.** `decode(encode(x))` always equals `JSON.parse(JSON.stringify(x))`. Thousands of random values check this on every test run.
-- **Small and safe.** The core is 3.5 KB min+gz, with no third-party dependencies. It's ESM + CJS with full types, works in the browser and Node 18+, and guards against `__proto__` pollution.
+- **Small and safe.** The core is 3.7 KB min+gz, with no third-party dependencies. It's ESM + CJS with full types, works in the browser and Node 18+, and guards against `__proto__` pollution.
 
 ## Packages
 
 | Package | What it does | Size (min+gz) |
 | --- | --- | ---: |
-| [`@flattype/core`](https://github.com/karammm/flattype/blob/main/packages/core) | `encode`, `decode`, `flatten`, `unflatten`, `stats` | 3.5 KB |
+| [`@flattype/core`](https://github.com/karammm/flattype/blob/main/packages/core) | `encode`, `decode`, `createDecoder`, `flatten`, `unflatten`, `stats` | 3.7 KB |
 | [`@flattype/models`](https://github.com/karammm/flattype/blob/main/packages/models) | `defineModel`, `infer`, `toSource`: typed models from JSON or Flat Notation | +3.2 KB |
+| [`@flattype/http`](https://github.com/karammm/flattype/blob/main/packages/http) | `flatFetch`, `createClient`, `flatAxios`, `streamRows`, and `flatExpress` / `flatFastify` / `flatHono` | +2.3 KB |
+| [`@flattype/react`](https://github.com/karammm/flattype/blob/main/packages/react) | `useFlat`, `useFlatSuspense`, `useFlatStream`, `useModel`, `FlatProvider` | +1.4 KB |
 | [`@flattype/shared`](https://github.com/karammm/flattype/blob/main/packages/shared) | Shared TypeScript types | types only |
 
-React, Vue, Angular and Svelte bindings, HTTP helpers, Claude helpers and a CLI are planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
+Vue, Angular and Svelte bindings, Claude helpers and a CLI are planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
 ## The format
 
@@ -193,6 +218,81 @@ export const UsersPage = defineModel({
 export type UsersPage = Infer<typeof UsersPage>;
 ```
 
+## HTTP
+
+`@flattype/http` adds Flat Notation to an existing API without breaking anyone. A response is re-encoded only when the request says `Accept: text/x-flat`, and `Vary: Accept` keeps caches correct.
+
+**Server**
+
+```ts
+import { flatExpress, flatFastify, flatHono, negotiate } from "@flattype/http";
+
+expressApp.use(flatExpress());                         // Express: res.json(...)
+await fastifyApp.register(flatFastify);                // Fastify: object replies
+honoApp.use(flatHono());                               // Hono: c.json(...)
+return negotiate(request, Response.json(data));        // Bun, Deno, Next.js route handlers, Workers
+```
+
+**Client**
+
+```ts
+import { createClient, flatAxios, flatFetch, streamRows } from "@flattype/http";
+
+const user = await flatFetch("/api/users/7", { model: User });          // typed, throws HttpError on 4xx/5xx
+
+const api = createClient({ baseURL: "https://api.example.com/v1", headers: { authorization } });
+const page = await api.get("/users", { query: { page: 2 } });
+await api.post("/users", { name: "Chen" });                              // JSON request body
+
+const axiosApi = flatAxios(axios.create({ baseURL: "/api" }));           // axios: response.data is decoded
+
+for await (const { path, index, value } of streamRows("/api/export")) {  // rows while still downloading
+  table.append(value);
+}
+```
+
+A JSON-only server works with every client helper: the response is just read as JSON.
+
+## React
+
+```bash
+npm install @flattype/react @flattype/models
+```
+
+```tsx
+import { FlatProvider, useFlat, useFlatStream, useFlatSuspense } from "@flattype/react";
+
+<FlatProvider baseURL="/api" headers={{ authorization: `Bearer ${token}` }}>
+  <App />
+</FlatProvider>;
+
+function Users() {
+  const { data, error, loading, refetch } = useFlat("/users", { model: User, list: true });
+  if (error) return <ErrorMessage error={error} />;   // HttpError, ModelError or a network error
+  if (!data) return <Spinner />;
+  return <UserList users={data} onRefresh={refetch} />; // data: User[]
+}
+
+function Profile({ id }: { id: number }) {
+  const { data: user } = useFlatSuspense(`/users/${id}`, { model: User }); // inside <Suspense>
+  return <h2>{user.fullName}</h2>;                                          // user: User, never undefined
+}
+
+function Export() {
+  const { rows, done } = useFlatStream("/export", { model: Row, table: "rows" });
+  return <Table rows={rows} footer={done ? "Done" : `Loading… ${rows.length}`} />; // rows appear while downloading
+}
+```
+
+| Hook | Returns | Notes |
+| --- | --- | --- |
+| `useFlat(url, options)` | `{ data, error, loading, refetch }` | A new URL aborts the old request. Old data stays while the next loads. `url: null` or `enabled: false` skips the request |
+| `useFlatSuspense(url, options)` | `{ data, refetch }` | Suspends, sends errors to an error boundary, and caches by URL (one request for many components) |
+| `useFlatStream(url, options)` | `{ rows, done, error, restart }` | One render per network chunk. `table` picks one table by path |
+| `useModel(data, Model, { list })` | the mapped value | Memoized. For data from props, stores or sockets |
+
+Works with React 18 and 19, in StrictMode and with any server. A JSON-only API works too. A runnable app with Playwright tests in three browsers is in [`examples/react-app`](https://github.com/karammm/flattype/blob/main/examples/react-app).
+
 ## 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.1.0",
+  "version": "1.3.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.1.0",
-    "@flattype/shared": "1.1.0"
+    "@flattype/core": "1.3.0",
+    "@flattype/shared": "1.3.0"
   },
   "publishConfig": {
     "access": "public"