@aggiovato/yrest 0.2.0 → 0.2.1

package/README.md

@@ -19,7 +19,7 @@ npx @aggiovato/yrest serve db.yml
 ## Quick start
 
 ```bash
-# Create a sample db.yml in the current directory
+# Create a sample db.yml and yrest.config.yml in the current directory
 npx @aggiovato/yrest init
 
 # Start the server
@@ -34,11 +34,15 @@ Resources (base: /):
   /posts
 ```
 
+Open `http://localhost:3070/_about` in your browser for a live overview of all generated endpoints.
+
+---
+
 ## Commands
 
 ### `init`
 
-Creates a sample `db.yml` in the current directory.
+Creates a sample `db.yml` and a `yrest.config.yml` template in the current directory.
 
 ```bash
 npx @aggiovato/yrest init                            # basic sample (default)
@@ -57,22 +61,53 @@ npx @aggiovato/yrest init --sample relational --file api.yml
 - `basic` — two independent collections: `users` and `products`
 - `relational` — three collections with `_rel` relationships: `users`, `posts` and `comments`
 
+---
+
 ### `serve`
 
 Starts the mock server.
 
 ```bash
 npx @aggiovato/yrest serve db.yml
-npx @aggiovato/yrest serve db.yml --port 3001
-npx @aggiovato/yrest serve db.yml --host 0.0.0.0
-npx @aggiovato/yrest serve db.yml --base /api
+npx @aggiovato/yrest serve db.yml --port 3001 --host 0.0.0.0
+npx @aggiovato/yrest serve db.yml --base /api --watch
+npx @aggiovato/yrest serve db.yml --readonly --delay 300
+npx @aggiovato/yrest serve db.yml --pageable 20
+```
+
+| Flag             | Default     | Description                                                             |
+| ---------------- | ----------- | ----------------------------------------------------------------------- |
+| `--port`         | `3070`      | Port to listen on                                                       |
+| `--host`         | `localhost` | Host to bind                                                            |
+| `--base`         | _(none)_    | Prefix for all routes (e.g. `/api`)                                     |
+| `--watch`        | `false`     | Reload `db.yml` automatically when it changes on disk                   |
+| `--readonly`     | `false`     | Reject all write operations (POST, PUT, PATCH, DELETE) with `405`       |
+| `--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 |
+
+All flags can also be set in `yrest.config.yml` (see below). CLI flags always take priority over the config file.
+
+---
+
+## Configuration file
+
+`yrest init` creates a `yrest.config.yml` alongside `db.yml`. Options defined here apply every time you run `serve` without needing to type flags:
+
+```yaml
+# yrest.config.yml
+file: db.yml
+port: 3070
+host: localhost
+# base: /api
+# watch: false
+# readonly: false
+# delay: 0
+# pageable: false   # true (limit 10), or a number (custom limit)
 ```
 
-| Flag     | Default     | Description           |
-| -------- | ----------- | --------------------- |
-| `--port` | `3070`      | Port to listen on     |
-| `--host` | `localhost` | Host to bind          |
-| `--base` | _(none)_    | Prefix for all routes |
+**Priority order** (highest wins): CLI flags → `yrest.config.yml` → schema defaults.
+
+---
 
 ## Database format
 
@@ -93,6 +128,8 @@ posts:
 
 Each top-level key becomes a resource with full CRUD endpoints.
 
+---
+
 ## Generated endpoints
 
 For each resource in `db.yml`:
@@ -108,13 +145,15 @@ DELETE  /users/:id      Delete
 
 With `--base /api` all routes are prefixed: `/api/users`, `/api/users/:id`, etc.
 
+---
+
 ## Query params
 
 All query params can be combined freely.
 
 ### Filtering
 
-Return only items that match a field value:
+Return only items that match one or more field values:
 
 ```txt
 GET /users?name=Ana
@@ -128,28 +167,78 @@ Comparison is case-sensitive and converts types to string (`?id=1` matches numer
 ```txt
 GET /users?_sort=name              # ascending (default)
 GET /users?_sort=name&_order=desc  # descending
-GET /users?_sort=id&_order=asc
 ```
 
 String fields are compared case-insensitively. Items missing the sort field are pushed to the end.
 
 ### Pagination
 
+**Without `--pageable`** (default):
+
 ```txt
 GET /users?_page=1&_limit=10   # page 1, 10 items per page
 GET /users?_limit=5            # first 5 items
-GET /users?_page=2&_limit=5    # items 6–10
 ```
 
-When pagination is active, the response includes an `X-Total-Count` header with the total number of items before pagination (after any active filter).
+When `_page` or `_limit` are used, the response includes an `X-Total-Count` header with the total number of items before pagination.
+
+**With `--pageable`** (or `pageable: true` in config):
+
+Every GET collection response is automatically wrapped in a `{ data, pagination }` envelope:
+
+```bash
+npx @aggiovato/yrest serve db.yml --pageable      # default limit: 10
+npx @aggiovato/yrest serve db.yml --pageable 20   # custom limit: 20
+```
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "Ana" },
+    { "id": 2, "name": "Luis" }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "totalItems": 23,
+    "totalPages": 3,
+    "isFirst": true,
+    "isLast": false,
+    "hasNext": true,
+    "hasPrev": false
+  }
+}
+```
+
+The `?_page` and `?_limit` query params still work in pageable mode to navigate pages.
+
+### Relation embedding (`?_expand`)
+
+Embed a related parent object directly into the response using the `_rel` block (see [Relational data](#relational-data)):
+
+```txt
+GET /posts?_expand=user           # embed user object in each post
+GET /posts/1?_expand=user         # embed in a single item
+```
+
+Both syntaxes are supported:
+
+```txt
+?_expand=author,category          # comma-separated
+?_expand=author&_expand=category  # repeated param
+```
+
+Unresolvable keys are silently ignored. Works on all operations: GET, POST, PUT, PATCH, DELETE.
 
 ### Combined example
 
 ```txt
-GET /users?role=admin&_sort=name&_order=asc&_page=1&_limit=5
+GET /posts?userId=1&_sort=title&_order=asc&_page=1&_limit=5&_expand=user
 ```
 
-Returns the first 5 admin users sorted alphabetically by name.
+Returns the first 5 posts by user 1, sorted alphabetically by title, with the user object embedded.
+
+---
 
 ## Relational data
 
@@ -170,12 +259,66 @@ posts:
     userId: 1
 ```
 
-This enables nested routes:
+This enables:
+
+**Nested routes:**
 
 ```txt
 GET /users/1/posts    # all posts where userId === 1
 ```
 
+**Relation embedding with `?_expand`:**
+
+```txt
+GET /posts/1?_expand=user   →  { id: 1, title: "First post", userId: 1, user: { id: 1, name: "Ana" } }
+```
+
+---
+
+## Server modes
+
+### Watch mode
+
+Automatically reloads `db.yml` when it changes on disk — useful when you edit the file manually while the server is running:
+
+```bash
+npx @aggiovato/yrest serve db.yml --watch
+```
+
+> **Note:** Watch mode reloads data in existing collections. Adding or removing entire collections requires a server restart.
+
+### Readonly mode
+
+Rejects all write operations with `405 Method Not Allowed`:
+
+```bash
+npx @aggiovato/yrest serve db.yml --readonly
+```
+
+Useful to expose a stable read-only snapshot for demos or CI environments.
+
+### Delay mode
+
+Adds a fixed delay (in milliseconds) to every response to simulate real network latency:
+
+```bash
+npx @aggiovato/yrest serve db.yml --delay 500   # 500ms on every response
+```
+
+---
+
+## API overview page
+
+Every running server exposes `GET /_about` — a self-contained HTML page listing all generated endpoints, active modes, query param reference and ready-to-run `curl` examples derived from your actual `db.yml`:
+
+```bash
+open http://localhost:3070/_about
+```
+
+The page reflects the live state of the server, so it updates automatically in watch mode.
+
+---
+
 ## HTTP responses
 
 | Status | When                                   |
@@ -183,9 +326,12 @@ GET /users/1/posts    # all posts where userId === 1
 | `200`  | Successful GET, PUT, PATCH, DELETE     |
 | `201`  | Successful POST                        |
 | `404`  | Resource or id not found               |
+| `405`  | Write operation in readonly mode       |
 | `500`  | Error reading or writing the YAML file |
 
-DELETE returns the deleted item (useful for debugging).
+DELETE returns the deleted item as confirmation.
+
+---
 
 ## ID generation
 
@@ -199,15 +345,21 @@ All write operations (POST, PUT, PATCH, DELETE) are saved back to `db.yml` immed
 
 CORS is enabled by default, so you can call the API from any frontend running on a different port without extra configuration.
 
+---
+
 ## Frontend usage
 
 ```ts
-// List
+// List all
 const users = await fetch("http://localhost:3070/users").then((r) => r.json());
 
 // Filter + sort + paginate
 const res = await fetch("http://localhost:3070/users?role=admin&_sort=name&_page=1&_limit=10");
 
+// Embed related object
+const post = await fetch("http://localhost:3070/posts/1?_expand=user").then((r) => r.json());
+// → { id: 1, title: "...", userId: 1, user: { id: 1, name: "Ana" } }
+
 // Create
 await fetch("http://localhost:3070/users", {
   method: "POST",
@@ -231,7 +383,8 @@ await fetch("http://localhost:3070/users/1", { method: "DELETE" });
 ```json
 {
   "scripts": {
-    "mock": "yrest serve db.yml"
+    "mock": "yrest serve db.yml",
+    "mock:watch": "yrest serve db.yml --watch"
   }
 }
 ```
@@ -251,14 +404,17 @@ Run `task --list` to see all available commands.
 
 #### Development
 
-| Command           | What it does                                                                    |
-| ----------------- | ------------------------------------------------------------------------------- |
-| `task test`       | Runs the full test suite once                                                   |
-| `task test:watch` | Runs tests in watch mode — reruns on every file change                          |
-| `task build`      | Compiles TypeScript to `dist/` via tsup                                         |
-| `task dev`        | Builds once, then starts watch-build + server from `dist/` in parallel          |
-| `task serve:dist` | Builds and starts the server from the local `dist/`                             |
-| `task serve:npx`  | Starts the version currently published on npm (useful to compare against local) |
+| Command                 | What it does                                                           |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `task test`             | Runs the full test suite once                                          |
+| `task test:watch`       | Runs tests in watch mode — reruns on every file change                 |
+| `task build`            | Compiles TypeScript to `dist/` via tsup                                |
+| `task dev`              | Builds once, then starts watch-build + server from `dist/` in parallel |
+| `task serve:dist`       | Builds and starts the server from the local `dist/`                    |
+| `task serve:dist:watch` | Builds and starts the server with `--watch` (reloads db.yml on change) |
+| `task serve:npx`        | Starts the published npm version (useful to compare against local)     |
+| `task serve:npx:watch`  | Starts the published npm version with `--watch`                        |
+| `task preflight`        | Full pre-push check: format, lint, typecheck and tests in order        |
 
 #### Release
 
@@ -280,14 +436,12 @@ task dev          # keep this running in another terminal
 
 `test:watch` reruns the suite on every save so you catch regressions immediately. `dev` rebuilds and serves so you can call the endpoints manually while you work.
 
-**Before committing:**
+**Before pushing:**
 
 ```bash
-task test         # confirm everything passes
+task preflight    # format + lint + typecheck + tests in one command
 ```
 
-The test suite covers all routes, filters, sorting, pagination and CRUD operations. Do not commit with failing tests.
-
 **Good practices:**
 
 - Write tests for every new feature or bug fix before opening a PR.
@@ -300,8 +454,8 @@ The test suite covers all routes, filters, sorting, pagination and CRUD operatio
 Releases are fully automated via GitHub Actions once a version tag is pushed:
 
 ```bash
-# 1. Make sure all tests pass
-task test
+# 1. Make sure everything is clean
+task preflight
 
 # 2. Bump the version (choose one)
 task release:patch   # bug fixes
@@ -312,10 +466,10 @@ task release:major   # breaking changes
 git push && git push --tags
 ```
 
-Step 3 triggers two GitHub Actions pipelines automatically (no manual action needed after the push):
+Step 3 triggers two GitHub Actions pipelines automatically:
 
 - **CI** — runs on every push to `main` and on every PR. Executes typecheck + tests on Node 20 and Node 22.
-- **Publish** — runs only when a `v*` tag is pushed. Runs tests + build and publishes to npm using Trusted Publishing (no tokens stored as secrets).
+- **Publish** — runs only when a `v*` tag is pushed. Runs tests + build and publishes to npm using Trusted Publishing (OIDC — no tokens stored as secrets).
 
 ### CI/CD pipelines
 
@@ -324,15 +478,15 @@ push to main / PR open
         │
         ▼
     [CI workflow]
-    ├── Node 20: typecheck + tests
-    └── Node 22: typecheck + tests
+    ├── Node 20: lint + format check + typecheck + tests
+    └── Node 22: lint + format check + typecheck + tests
 
 push tag v*
         │
         ▼
     [Publish workflow]
     ├── tests + build  (via prepublishOnly)
-    └── npm publish --provenance  (via Trusted Publishing / OIDC)
+    └── npm publish --provenance  (via Trusted Publishing / OIDC, Node 24)
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aggiovato/yrest",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Zero-config REST API mock server powered by a YAML file",
   "keywords": [
     "yaml",