@flattype/models 1.1.0 → 1.2.0

package/README.md

@@ -15,8 +15,9 @@
 <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://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 +26,7 @@
   <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="#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 +35,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 52 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, 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 52-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 +46,7 @@
 ## Quick start
 
 ```bash
-npm install @flattype/core @flattype/models
+npm install @flattype/core @flattype/models @flattype/http
 ```
 
 ```ts
@@ -85,23 +87,35 @@ 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[]
+```
+
 ## 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/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).
+React, 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 +207,41 @@ 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.
+
 ## 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.2.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/shared": "1.2.0",
+    "@flattype/core": "1.2.0"
   },
   "publishConfig": {
     "access": "public"