@flattype/models 1.2.0 → 1.3.0

package/README.md

@@ -16,6 +16,7 @@
   <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.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">
@@ -27,6 +28,7 @@
   <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>
@@ -35,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 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">
+      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 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>
+  <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>
 
 ---
@@ -97,6 +99,14 @@ 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:
+
+```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.
@@ -113,9 +123,10 @@ const users = await flatFetch("/api/users", { model: User, list: true }); // cli
 | [`@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, 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
 
@@ -242,6 +253,46 @@ for await (const { path, index, value } of streamRows("/api/export")) {  // rows
 
 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.2.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/shared": "1.2.0",
-    "@flattype/core": "1.2.0"
+    "@flattype/core": "1.3.0",
+    "@flattype/shared": "1.3.0"
   },
   "publishConfig": {
     "access": "public"