@flattype/models 1.3.0 → 1.4.1

package/README.md

@@ -17,6 +17,7 @@
   <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://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://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">
@@ -29,6 +30,7 @@
   <a href="#typed-models"><b>Models</b></a> ·
   <a href="#http"><b>HTTP</b></a> ·
   <a href="#react"><b>React</b></a> ·
+  <a href="#vue"><b>Vue</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>
@@ -37,10 +39,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 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">
+      alt="FlatType.js in 66 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 and Vue composables 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 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>
+  <sub>▶ <a href="https://github.com/karammm/flattype/blob/main/docs/assets/flattype-intro.mp4">Watch the 66-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>
 
 ---
@@ -99,10 +101,10 @@ 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:
+And in React or Vue:
 
 ```tsx
-import { useFlat } from "@flattype/react";
+import { useFlat } from "@flattype/react"; // or "@flattype/vue": the same API, with refs
 
 const { data: users, loading, error } = useFlat("/api/users", { model: User, list: true }); // User[] | undefined
 ```
@@ -124,9 +126,10 @@ const { data: users, loading, error } = useFlat("/api/users", { model: User, lis
 | [`@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/vue`](https://github.com/karammm/flattype/blob/main/packages/vue) | The same composables for Vue 3, with reactive URLs, plus the `createFlat()` plugin | +1.1 KB |
 | [`@flattype/shared`](https://github.com/karammm/flattype/blob/main/packages/shared) | Shared TypeScript types | types only |
 
-Vue, Angular and Svelte bindings, Claude helpers and a CLI are planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
+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
 
@@ -293,6 +296,43 @@ function Export() {
 
 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).
 
+## Vue
+
+```bash
+npm install @flattype/vue @flattype/models
+```
+
+```ts
+// main.ts
+app.use(createFlat({ baseURL: "/api", headers: () => ({ authorization: `Bearer ${token.value}` }) }));
+```
+
+```vue
+<script setup lang="ts">
+import { useFlat, useFlatStream, useFlatSuspense } from "@flattype/vue";
+
+const props = defineProps<{ id: number }>();
+
+// The URL can be a ref or a getter: changing it aborts the old request and loads the new one.
+const { data: user, error, loading, refetch } = useFlat(() => `/users/${props.id}`, { model: User }); // Ref<User | undefined>
+
+// Inside <Suspense>, `await` the first response so `data` is always set.
+const { data: me } = await useFlatSuspense("/me", { model: User });                                  // Ref<User>
+
+// Big lists render while they download.
+const { rows, done } = useFlatStream("/export", { model: Row, table: "rows" });
+</script>
+```
+
+| Composable | Returns | Notes |
+| --- | --- | --- |
+| `useFlat(url, options)` | `{ data, error, loading, refetch }` refs | `url` and `enabled` can be refs or getters. Aborts on change and on unmount |
+| `useFlatSuspense(url, options)` | `Promise<{ data, error, loading, refetch }>` | For `async setup()` in `<Suspense>`. The first error goes to `onErrorCaptured` |
+| `useFlatStream(url, options)` | `{ rows, done, error, restart }` refs | One update per network chunk. `table` picks one table by path |
+| `useModel(source, Model, { list })` | a computed ref | For props, Pinia stores and sockets |
+
+Vue 3.3+. A runnable app with Playwright tests in three browsers is in [`examples/vue-app`](https://github.com/karammm/flattype/blob/main/examples/vue-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.3.0",
+  "version": "1.4.1",
   "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.3.0",
-    "@flattype/shared": "1.3.0"
+    "@flattype/core": "1.4.1",
+    "@flattype/shared": "1.4.1"
   },
   "publishConfig": {
     "access": "public"