@yrest/cli 0.13.0 → 0.14.0

package/README.md

@@ -8,14 +8,17 @@
 [![npm downloads](https://img.shields.io/npm/dw/@yrest/cli)](https://www.npmjs.com/package/@yrest/cli)
 [![license](https://img.shields.io/npm/l/@yrest/cli)](LICENSE)
 [![CI](https://github.com/aggiovato/yRest/actions/workflows/ci.yml/badge.svg)](https://github.com/aggiovato/yRest/actions)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/cca9b352-b564-4027-a05d-af26728c8ac3/deploy-status)](https://app.netlify.com/projects/cca9b352-b564-4027-a05d-af26728c8ac3/deploys)
 [![Node](https://img.shields.io/node/v/@yrest/cli)](https://www.npmjs.com/package/@yrest/cli)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.typescriptlang.org/)
-[![Socket](https://badge.socket.dev/npm/package/@yrest/cli/0.13.0)](https://socket.dev/npm/package/@yrest/cli)
+[![Socket](https://badge.socket.dev/npm/package/@yrest/cli/0.14.0)](https://socket.dev/npm/package/@yrest/cli)
 
 YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a `db.yml` file.
 
 > Think `json-server`, but powered by YAML — with relations, filters, pagination, nested routes, snapshots and custom handlers.
 
+**[📖 Full documentation](https://yrest-docs.netlify.app)** — Getting Started, CLI reference, YAML format, relations, custom routes, SSE streams, playground and more.
+
 ```yaml
 # db.yml
 users:
@@ -62,7 +65,7 @@ A YAML-first alternative to json-server for frontend development.
 | Pageable mode (envelope response)                   |  ✅   |     ❌      |
 | Custom static routes (`_routes`)                    |  ✅   |     ❌      |
 | Template variables in responses                     |  ✅   |     ❌      |
-| Handler functions (JS logic)                        |  ✅   |     ❌      |
+| Handler functions (JS / TS logic)                   |  ✅   |     ❌      |
 | Conditional scenarios (`scenarios:`)                |  ✅   |     ❌      |
 | Snapshot endpoints                                  |  ✅   |     ❌      |
 | Config file                                         |  ✅   |     ⚠️      |
@@ -70,7 +73,7 @@ A YAML-first alternative to json-server for frontend development.
 | Watch mode                                          |  ✅   |     ✅      |
 | Readonly mode                                       |  ✅   |     ❌      |
 | Atomic writes                                       |  ✅   |     ✅      |
-| TypeScript types                                    |  ✅   |     ❌      |
+| TypeScript types + codegen (`yrest types`)          |  ✅   |     ❌      |
 | Programmatic API for test frameworks                |  ✅   |     ❌      |
 | OpenAPI 3.0 spec (`GET /_openapi`, `yrest openapi`) |  ✅   |     ❌      |
 | Field annotations (`_schema`)                       |  ✅   |     ❌      |
@@ -169,6 +172,104 @@ The spec is also available live at `GET /_openapi` (YAML) and `GET /_openapi.jso
 
 ---
 
+### `types`
+
+Generates TypeScript interfaces from a `db.yml` file — one per collection, plus a `CollectionName` union and a `Collections` map.
+
+```bash
+npx @yrest/cli types db.yml                                   # prints to stdout
+npx @yrest/cli types db.yml --output db.types.ts              # writes a file
+npx @yrest/cli types db.yml --output db.types.ts --watch      # regenerates on every change
+```
+
+| Flag              | Default    | Description                                               |
+| ----------------- | ---------- | --------------------------------------------------------- |
+| `--output <file>` | _(stdout)_ | Write to a file instead of printing to stdout             |
+| `--watch`         | `false`    | Regenerate on every change of the file (needs `--output`) |
+
+Given this `db.yml`:
+
+```yaml
+_schema:
+  users:
+    email:
+      _required: true
+      _format: email
+    role:
+      _enum: [admin, editor]
+_rel:
+  posts:
+    userId: users
+users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+    role: admin
+  - id: 2
+    name: Luis
+    address: { city: Lima }
+posts:
+  - id: 1
+    title: Hello
+    userId: 1
+```
+
+`yrest types db.yml` prints:
+
+```ts
+// Auto-generated by yrest types — do not edit manually.
+// Source: db.yml
+
+/** Item of the `users` collection. */
+export interface User {
+  id: number;
+  name: string;
+  /**
+   * @format email
+   */
+  email: string;
+  role?: "admin" | "editor";
+  address?: { city: string };
+}
+
+/** Item of the `posts` collection. */
+export interface Post {
+  id: number;
+  title: string;
+  /** FK → users.id */
+  userId: number;
+}
+
+/** Union of all collection names in the source file. */
+export type CollectionName = "users" | "posts";
+
+/** Maps each collection name to its item array type. */
+export interface Collections {
+  users: User[];
+  posts: Post[];
+}
+```
+
+**How types are derived:**
+
+- Interface names are the collection name in singular PascalCase (`users` → `User`, `post_tags` → `PostTag`, `categories` → `Category`). If two names collide, the plural form is kept.
+- Types are inferred from **every** item. A field present on all items is required; a field missing on any item is optional (`?`).
+- Different types across items become a union (`number | string`); `null` values add `| null`. Nested objects are merged into one inline shape and array elements are pooled (`{ k?: string; v?: number }[]`).
+- `_schema` overrides the inference: `_type` (`integer` → `number`), `_required` (or the `required` / `optional` shorthand), `_enum` (literal union), `_nullable` and `_items`. `_description`, `_format` and `_deprecated` are emitted as JSDoc. Fields declared only in `_schema` are included.
+- `many2one` / `one2one` foreign keys from `_rel` are annotated with `FK → target.id`.
+
+The command only reads the file: `__uuid_gen` / `__fk` directives are **not** resolved and `db.yml` is never rewritten (unresolved directive values are typed as `string`).
+
+The generator is also available programmatically:
+
+```ts
+import { generateTypes } from "@yrest/cli";
+
+const source = generateTypes({ data: { users: [{ id: 1, name: "Ana" }] } });
+```
+
+---
+
 ### `serve`
 
 Starts the mock server.
@@ -193,7 +294,7 @@ npx @yrest/cli serve db.yml --handlers yrest.handlers.js
 | `--delay <ms>`      | `0`         | Add a fixed delay to all responses (simulates network latency)          |
 | `--pageable [n]`    | `false`     | Wrap GET collection responses in `{ data, pagination }`. Optional limit |
 | `--snapshot`        | `false`     | Save initial state snapshot and expose `/_snapshot` endpoints           |
-| `--handlers <file>` | _(none)_    | Path to a JS file exporting handler functions for custom routes         |
+| `--handlers <file>` | _(none)_    | Path to a JS or TS file exporting handler functions for custom routes   |
 | `--id-strategy`     | `increment` | Id generation for new items: `increment` (auto-int) or `uuid`           |
 
 All flags can also be set in `yrest.config.yml` (see below). CLI flags always take priority over the config file.
@@ -903,41 +1004,57 @@ _routes:
 
 ### Handler functions
 
-For routes that need real logic (conditional responses, stateful mocks, request inspection), reference a JavaScript function via the `handler:` field:
+For routes that need real logic (conditional responses, stateful mocks, request inspection), point a `_routes` entry at a function with `_handler`:
 
 ```yaml
 _routes:
-  - method: POST
-    path: /login
-    handler: login
-    response: # optional fallback if handler throws
-      status: 200
-      body: { token: fake }
+  - _method: POST
+    _path: /login
+    _handler: login
 
-  - method: GET
-    path: /auth/me
-    handler: getCurrentUser
+  - _method: GET
+    _path: /auth/me
+    _handler: getCurrentUser
 ```
 
-Create a `yrest.handlers.js` file in the same directory as `db.yml`:
+Export the functions from a handlers file — JavaScript (`.js`, `.mjs`, `.cjs`) or TypeScript (`.ts`, `.mts`):
 
-```js
-// yrest.handlers.js
-export async function login(req) {
-  const { email, password } = req.body ?? {};
-  if (password !== "secret") return { status: 401, body: { error: "Invalid credentials" } };
-  return { status: 200, body: { token: `tok-${email}` } };
-}
+```ts
+// yrest.handlers.ts
+import { defineHandler } from "@yrest/cli";
+import type { User } from "./db.types"; // generated with `yrest types`
+
+export const login = defineHandler((req, { collection }) => {
+  const { email, password } = (req.body ?? {}) as { email?: string; password?: string };
+  const user = collection<User>("users").findWhere((u) => u.email === email)[0];
+  if (!user || password !== "secret") {
+    return { status: 401, body: { error: "Invalid credentials" } };
+  }
+  return { body: { token: `tok-${user.id}` } };
+});
 
-export async function getCurrentUser(req) {
-  return { status: 200, body: { id: 1, name: "Ana", role: "admin" } };
-}
+export const getCurrentUser = defineHandler(() => ({
+  body: { id: 1, name: "Ana", role: "admin" },
+}));
 ```
 
-Pass the file to the server with `--handlers`:
+Pass the file to the server with `--handlers` (or `handlers:` in `yrest.config.yml`):
 
 ```bash
-npx @yrest/cli serve db.yml --handlers yrest.handlers.js
+npx @yrest/cli serve db.yml --handlers yrest.handlers.ts
+```
+
+TypeScript handler files are loaded by Node's built-in type stripping (Node ≥ 22.18). On older versions load [`tsx`](https://tsx.is) into Node (`NODE_OPTIONS="--import tsx" npx @yrest/cli serve …`) or compile the file to `.js`. With type stripping, type-only imports must use `import type`.
+
+In plain JavaScript the same functions work without `defineHandler`:
+
+```js
+// yrest.handlers.js
+export async function login(req, ctx) {
+  const { email } = req.body ?? {};
+  const user = ctx.collection("users").findWhere((u) => u.email === email)[0];
+  return user ? { body: { token: `tok-${user.id}` } } : { status: 401 };
+}
 ```
 
 **Handler signature:**
@@ -956,10 +1073,24 @@ type HandlerResponse = {
   headers?: Record<string, string>;
 };
 
-type Handler = (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>;
+type HandlerContext = {
+  // Typed CRUD access to the live data — the same handle as server.collection()
+  collection<T>(name: string): CollectionHandle<T>;
+};
+
+type Handler = (
+  req: HandlerRequest,
+  ctx: HandlerContext
+) => HandlerResponse | Promise<HandlerResponse>;
 ```
 
-If a named handler is not found in the file, the server returns `501`. If the handler throws, it returns `500`. If a `response:` block is defined alongside `handler:`, it is used as fallback only when the handler itself throws.
+`defineHandler` (and `defineSseHandler` for [SSE streams](#sse-streams)) are identity wrappers exported by `@yrest/cli`: they only add types.
+
+**`ctx.collection(name)`** reads and writes the same data the REST routes serve: a record a handler creates is returned by `GET /users` straight away and persisted to `db.yml` like a `POST`. See [Typed collection access](#typed-collection-access) for every method. It throws if the collection does not exist.
+
+**Errors:** if a named handler is not exported by the file, the route answers `501`; if the handler throws, it answers `500` with the error message.
+
+**Scaffolding:** `yrest handler <name>` adds a stub to the handlers file (`handlers:` in `yrest.config.yml`, or `yrest.handlers.js`). For a `.ts` / `.mts` file the stub uses `defineHandler`. Add `--register --method POST --path /login` to also write the `_routes` entry to `db.yml`.
 
 ### SSE streams
 
@@ -1009,6 +1140,41 @@ _events:
       filter: "{{query.filter}}" # from query string
 ```
 
+**Handler-driven streams** — for streams that depend on state (a chat, a job queue), let a function drive the stream with `_handler` instead of `_events`:
+
+```yaml
+_routes:
+  - _method: SSE
+    _path: /events/chat
+    _sse:
+      _handler: chatStream
+  - _method: POST
+    _path: /chat/messages
+    _handler: postMessage
+```
+
+```ts
+// yrest.handlers.ts
+import { EventEmitter } from "node:events";
+import { defineHandler, defineSseHandler } from "@yrest/cli";
+
+const bus = new EventEmitter();
+
+export const chatStream = defineSseHandler((req, raw) => {
+  const send = (msg: unknown) => raw.write(`event: message\ndata: ${JSON.stringify(msg)}\n\n`);
+  bus.on("message", send);
+  raw.on("close", () => bus.off("message", send)); // client disconnected
+});
+
+export const postMessage = defineHandler((req, { collection }) => {
+  const message = collection("messages").create(req.body as { text: string });
+  bus.emit("message", message);
+  return { status: 201, body: message };
+});
+```
+
+The SSE handler receives `(req, raw, ctx)`, where `raw` is the Node.js `ServerResponse`. yRest sends the SSE headers and the keep-alive comments; the handler writes frames and calls `raw.end()` when it is done. A handler missing from the handlers file answers `501`; one that throws sends an `event: error` frame and the stream is closed.
+
 **Consuming from the browser:**
 
 ```js
@@ -1207,16 +1373,47 @@ import { createYrestServer, yrest } from "@yrest/cli";
 | `delay`    | `number`          | `0`         | Fixed delay in ms added to every response              |
 | `pageable` | `boolean\|number` | `false`     | Wrap GET responses in `{ data, pagination }` envelope  |
 | `snapshot` | `boolean`         | `false`     | Enable snapshot endpoints (`/_snapshot`)               |
-| `handlers` | `string`          | —           | Path to a JS file exporting handler functions          |
+| `handlers` | `string`          | —           | Path to a JS or TS file exporting handler functions    |
 
 **Returned handle:**
 
-| Member    | Description                                              |
-| --------- | -------------------------------------------------------- |
-| `start()` | Starts the server and begins listening                   |
-| `stop()`  | Gracefully closes the server                             |
-| `port`    | The actual port after `start()` (useful when `port: 0`)  |
-| `url`     | Base URL after `start()` (e.g. `http://localhost:49821`) |
+| Member                | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `start()`             | Starts the server and begins listening                           |
+| `stop()`              | Gracefully closes the server                                     |
+| `port`                | The actual port after `start()` (useful when `port: 0`)          |
+| `url`                 | Base URL after `start()` (e.g. `http://localhost:49821`)         |
+| `collection<T>(name)` | Typed CRUD handle for a collection — see below (after `start()`) |
+
+### Typed collection access
+
+`server.collection<T>(name)` returns a typed handle over the running data. Use it to seed or inspect state in a test without going through HTTP. Combine it with [`yrest types`](#types) to get the item types:
+
+```ts
+import { createYrestServer } from "@yrest/cli";
+import type { User } from "./db.types"; // npx @yrest/cli types db.yml -o db.types.ts
+
+const server = createYrestServer({ file: "./tests/db.yml", port: 0 });
+await server.start();
+
+const users = server.collection<User>("users");
+users.create({ name: "Ana", email: "ana@test.com" }); // id assigned by the server
+
+const res = await fetch(`${server.url}/users`);
+expect(await res.json()).toHaveLength(users.count());
+```
+
+| Method              | Returns          | Description                                                     |
+| ------------------- | ---------------- | --------------------------------------------------------------- |
+| `findAll()`         | `T[]`            | Every item, in stored order                                     |
+| `findById(id)`      | `T \| undefined` | Item by id — `1` and `"1"` both match                           |
+| `findWhere(fn)`     | `T[]`            | Items for which the predicate returns `true`                    |
+| `count()`           | `number`         | Number of items                                                 |
+| `create(data)`      | `T`              | Adds an item; the id is generated with the server's id strategy |
+| `update(id, patch)` | `T \| undefined` | Merges `patch` into the item (the id cannot change)             |
+| `delete(id)`        | `T \| undefined` | Removes the item and returns it                                 |
+
+Changes are visible to HTTP clients immediately and are persisted to `db.yml` exactly like REST writes (in-memory for inline data). Returned items are copies: changing one does not change the stored data — use `update()`. `collection()` throws for an unknown collection, and before `start()`. The same handle is available to handlers as [`ctx.collection`](#handler-functions).
 
 ### `yrest` tagged template literal
 
@@ -1350,7 +1547,8 @@ const server = createYrestServer({
 | Auto-embedding (`nested: true` in `_rel`)          | ✅     |
 | SSE stream routes (`_method: SSE`)                 | ✅     |
 | WebSocket mock channels (`_method: WS`)            | 🔜     |
-| TypeScript handlers + typed collections            | 🔜     |
+| TypeScript codegen (`yrest types db.yml`)          | ✅     |
+| TypeScript handlers + typed collections            | ✅     |
 
 ---