@flattype/models 1.4.1 → 1.6.0

package/README.md

@@ -18,6 +18,8 @@
   <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://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">
@@ -31,6 +33,8 @@
   <a href="#http"><b>HTTP</b></a> ·
   <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>
@@ -39,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 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">
+      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 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>
+  <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>
 
 ---
@@ -101,12 +105,19 @@ 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 or Vue:
+And in React, Vue, Angular, Svelte or Solid:
 
 ```tsx
 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
+
+// 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
@@ -126,10 +137,12 @@ 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/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 |
 
-Angular and 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
 
@@ -333,6 +346,96 @@ const { rows, done } = useFlatStream("/export", { model: Row, table: "rows" });
 
 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).
 
+## Angular
+
+```bash
+npm install @flattype/angular @flattype/models
+```
+
+```ts
+// main.ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideHttpClient(withInterceptors([flatInterceptor])), // every HttpClient call can read Flat Notation
+    provideFlatType({ baseURL: "/api" }),
+  ],
+});
+```
+
+```ts
+@Component({
+  imports: [FlatModelPipe],
+  template: `
+    @for (u of users.value()?.data; track u.id) { <li>{{ u.fullName }}</li> }
+    <p>{{ (raw() | flatModel: Address)?.city }}</p>
+    <p>{{ events.done() ? "Done" : "Loading… " + events.rows().length }}</p>
+  `,
+})
+export class UsersComponent {
+  page = signal(1);
+  users = flatResource(() => `/users?page=${this.page()}`, { model: UsersPage }); // refetches when page changes
+  events = flatStream(() => "/export", { model: Row, table: "rows" });           // rows while downloading
+  raw = toSignal(inject(HttpClient).get("/api/address"));                        // plain HttpClient works too
+}
+```
+
+| API | What it does |
+| --- | --- |
+| `flatInterceptor` | Adds `Accept: text/x-flat, application/json` and decodes either format, error bodies included. Skip a request with `FLAT_TYPE_SKIP` in its `HttpContext` |
+| `flatResource(() => url, options)` | `value`, `error` and `isLoading` signals plus `reload()`. Runs on HttpClient and cancels the old request when the URL changes |
+| `flatStream(() => url, options)` | `rows`, `done` and `error` signals plus `restart()`. Uses `fetch`, because HttpClient can't stream |
+| `flatModel` pipe, `mapModel` / `mapModelList` | Model mapping in templates and in RxJS pipelines |
+
+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):
@@ -364,7 +467,7 @@ pnpm build && pnpm typecheck && pnpm test
 pnpm bench        # encode/decode vs JSON
 pnpm compare      # size and parse time vs JSON and TOON
 pnpm check:size   # bundle budgets
-pnpm video        # re-render docs/assets/flattype-intro.{mp4,gif} (needs ffmpeg)
+pnpm video        # re-render docs/assets/flattype-intro.{mp4,gif} (needs ffmpeg and the Angular example built)
 ```
 
 This is a pnpm + Turborepo monorepo built with tsup and tested with Vitest and fast-check. Releases use Changesets, and all `@flattype/*` packages share one version number. Every release follows the checklist in [ROADMAP.md](https://github.com/karammm/flattype/blob/main/ROADMAP.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flattype/models",
-  "version": "1.4.1",
+  "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.4.1",
-    "@flattype/shared": "1.4.1"
+    "@flattype/core": "1.6.0",
+    "@flattype/shared": "1.6.0"
   },
   "publishConfig": {
     "access": "public"