@flattype/models 1.4.1 → 1.5.0

package/README.md

@@ -18,6 +18,7 @@
   <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://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 +32,7 @@
   <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="#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 +41,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 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">
   </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 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>
 </p>
 
 ---
@@ -101,12 +103,15 @@ 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 or Angular:
 
 ```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
 ```
 
 ## Why FlatType
@@ -126,10 +131,11 @@ 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/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).
+Svelte bindings, Claude helpers and a CLI are planned. See the [roadmap](https://github.com/karammm/flattype/blob/main/ROADMAP.md).
 
 ## The format
 
@@ -333,6 +339,48 @@ 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).
+
 ## Benchmarks
 
 `pnpm compare` on the fixtures in [`fixtures/`](https://github.com/karammm/flattype/blob/main/fixtures/index.mjs) (Node 24, Apple Silicon):
@@ -364,7 +412,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.5.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.5.0",
+    "@flattype/shared": "1.5.0"
   },
   "publishConfig": {
     "access": "public"