@flattype/models 1.5.0 → 1.6.0

package/README.md

@@ -19,6 +19,7 @@
   <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://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 +34,7 @@
   <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="#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 +43,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 +105,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 +114,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 +139,10 @@ 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/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).
+Claude helpers and a CLI are planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
 ## The format
 
@@ -381,6 +388,54 @@ 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).
+
 ## 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.6.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.6.0",
+    "@flattype/shared": "1.6.0"
   },
   "publishConfig": {
     "access": "public"