@yrest/cli 0.5.3 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aggiovato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -56,6 +56,7 @@ A YAML-first alternative to json-server for frontend development.
 | Custom static routes (`_routes`)             |  ✅   |     ❌      |
 | Template variables in responses              |  ✅   |     ❌      |
 | Handler functions (JS logic)                 |  ✅   |     ❌      |
+| Conditional scenarios (`scenarios:`)         |  ✅   |     ❌      |
 | Snapshot endpoints                           |  ✅   |     ❌      |
 | Config file                                  |  ✅   |     ⚠️      |
 | API overview page (`/_about`)                |  ✅   |     ❌      |
@@ -63,6 +64,7 @@ A YAML-first alternative to json-server for frontend development.
 | Readonly mode                                |  ✅   |     ❌      |
 | Atomic writes                                |  ✅   |     ✅      |
 | TypeScript types                             |  ✅   |     ❌      |
+| Programmatic API for test frameworks         |  ✅   |     ❌      |
 
 ---
 
@@ -496,6 +498,103 @@ Available variables:
 
 When a field contains only a single `{{variable}}` placeholder, the resolved value preserves its original type (number, boolean, object). When embedded in a larger string it is stringified.
 
+### Conditional scenarios
+
+Define multiple conditional response variants for a custom route. Scenarios are evaluated in declaration order — the first matching `when:` wins. If none match, the `otherwise:` block is used (if defined), otherwise the static `response:` block.
+
+```yaml
+_routes:
+  - method: POST
+    path: /login
+    scenarios:
+      - when:
+          body.email: ana@test.com
+          body.password: secret
+        response:
+          status: 200
+          body:
+            token: tok-ana
+      - when:
+          body.email: admin@test.com
+          body.password: admin
+        response:
+          status: 200
+          body:
+            token: tok-admin
+            role: admin
+    otherwise:
+      status: 401
+      body:
+        error: Invalid credentials
+```
+
+**`when:` as an object** — all entries must match (AND semantics):
+
+```yaml
+when:
+  body.email: ana@test.com
+  body.password: secret
+```
+
+**`when:` as an array of objects** — any group satisfying all its conditions matches (OR of ANDs):
+
+```yaml
+when:
+  - body.role: admin
+  - body.role: superadmin
+```
+
+Condition keys use dot-notation to address request data:
+
+| Prefix      | Example             | Resolves to                |
+| ----------- | ------------------- | -------------------------- |
+| `body.X`    | `body.email`        | `req.body.email`           |
+| `params.X`  | `params.id`         | `req.params.id`            |
+| `query.X`   | `query.page`        | `req.query.page`           |
+| `headers.X` | `headers.x-api-key` | `req.headers["x-api-key"]` |
+
+Field operator suffixes (`_ne`, `_like`, `_start`, `_regex`, `_gte`, `_lte`) work on condition keys exactly as they do on query params:
+
+```yaml
+scenarios:
+  - when:
+      body.name_like: ana # name contains "ana" (case-insensitive)
+      body.age_gte: "18" # age >= 18
+    response:
+      status: 200
+      body: { ok: true }
+```
+
+Template variables (`{{}}`) are supported in both scenario and `otherwise` response bodies:
+
+```yaml
+scenarios:
+  - when:
+      body.email: ana@test.com
+    response:
+      status: 200
+      body:
+        message: "Welcome {{body.email}}"
+otherwise:
+  status: 401
+  body:
+    error: "Unknown user: {{body.email}}"
+```
+
+### Per-route delay
+
+Add a fixed delay (ms) to a specific route without affecting the rest of the server. Takes priority over the global `--delay` option for that route:
+
+```yaml
+_routes:
+  - method: GET
+    path: /slow-endpoint
+    delay: 800
+    response:
+      status: 200
+      body: { data: loaded }
+```
+
 ### Handler functions
 
 For routes that need real logic (conditional responses, stateful mocks, request inspection), reference a JavaScript function via the `handler:` field:
@@ -694,6 +793,139 @@ const session = await fetch("http://localhost:3070/login", {
 // → { token: "tok-ana@test.com" }
 ```
 
+## Programmatic API
+
+Use yRest directly inside your test suite — no CLI, no separate process to manage.
+
+Install as a dev dependency:
+
+```bash
+npm install -D @yrest/cli
+```
+
+### `createYrestServer`
+
+Creates a server instance that you control with `start()` and `stop()`. Accepts either inline YAML data or a path to a `db.yml` file.
+
+```ts
+import { createYrestServer, yrest } from "@yrest/cli";
+```
+
+**Options:**
+
+| Option     | Type              | Default     | Description                                            |
+| ---------- | ----------------- | ----------- | ------------------------------------------------------ |
+| `data`     | `Data`            | —           | Inline data object (use with `yrest\`...\``)           |
+| `file`     | `string`          | —           | Path to a `db.yml` file (`data` or `file` is required) |
+| `port`     | `number`          | `3070`      | TCP port. Use `0` to get a random available port       |
+| `host`     | `string`          | `localhost` | Host to bind                                           |
+| `base`     | `string`          | —           | URL prefix for all routes (e.g. `"/api"`)              |
+| `readonly` | `boolean`         | `false`     | Reject all write operations with `405`                 |
+| `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          |
+
+**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`) |
+
+### `yrest` tagged template literal
+
+Parses inline YAML into a data object. Strips common leading indentation automatically, so you can indent naturally inside your test files. Supports interpolated values.
+
+```ts
+const data = yrest`
+  users:
+    - id: 1
+      name: Ana
+  posts:
+    - id: 1
+      title: First post
+      userId: 1
+`;
+```
+
+### Vitest example
+
+```ts
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createYrestServer, yrest } from "@yrest/cli";
+
+const server = createYrestServer({
+  data: yrest`
+    users:
+      - id: 1
+        name: Ana
+      - id: 2
+        name: Luis
+  `,
+  port: 0, // random port — no conflicts between parallel tests
+  readonly: true,
+});
+
+beforeAll(() => server.start());
+afterAll(() => server.stop());
+
+describe("users API", () => {
+  it("returns all users", async () => {
+    const res = await fetch(`${server.url}/users`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toHaveLength(2);
+  });
+
+  it("returns a single user", async () => {
+    const res = await fetch(`${server.url}/users/1`);
+    expect(await res.json()).toMatchObject({ name: "Ana" });
+  });
+});
+```
+
+### Playwright example
+
+```ts
+// tests/api.spec.ts
+import { test, expect, beforeAll, afterAll } from "@playwright/test";
+import { createYrestServer, yrest } from "@yrest/cli";
+
+const server = createYrestServer({
+  data: yrest`
+    users:
+      - id: 1
+        name: Ana
+  `,
+  port: 0,
+  readonly: true,
+});
+
+beforeAll(() => server.start());
+afterAll(() => server.stop());
+
+test("lists users", async () => {
+  const res = await fetch(`${server.url}/users`);
+  expect(await res.json()).toHaveLength(1);
+});
+```
+
+### File-based example
+
+When your test data is too large for inline YAML, point to a file:
+
+```ts
+const server = createYrestServer({
+  file: "./tests/fixtures/db.yml",
+  port: 0,
+  readonly: true,
+});
+```
+
+---
+
 ## Use in package.json scripts
 
 ```json
@@ -708,6 +940,29 @@ const session = await fetch("http://localhost:3070/login", {
 
 ---
 
+## Roadmap
+
+| Feature                                            | Status |
+| -------------------------------------------------- | ------ |
+| Full CRUD from `db.yml`                            | ✅     |
+| Field filters, operators, full-text search         | ✅     |
+| Relations, `_expand`, `_embed`, nested routes      | ✅     |
+| Pagination, sorting, field projection              | ✅     |
+| Watch, readonly, delay, snapshot modes             | ✅     |
+| Custom routes (`_routes`) with static responses    | ✅     |
+| Template variables in responses (`{{params.id}}`)  | ✅     |
+| Handler functions (`yrest.handlers.js`)            | ✅     |
+| Visual panel (`/_panel`)                           | 🔜     |
+| Programmatic API for Vitest / Playwright           | ✅     |
+| Docker image                                       | 🔜     |
+| OpenAPI export (`yrest openapi db.yml`)            | 🔜     |
+| VS Code extension with YAML snippets               | 🔜     |
+| Request validation with JSON Schema                | 🔜     |
+| Conditional scenarios (`scenarios:`, `otherwise:`) | ✅     |
+| Per-route delay (`delay:`)                         | ✅     |
+
+---
+
 ## Contributing
 
 ### Prerequisites

package/dist/cli/index.js

@@ -135,7 +135,7 @@ function registerInit(program2) {
 var import_node_fs5 = require("fs");
 var import_node_path3 = require("path");
 
-// src/storage/yamlStorage.ts
+// src/storage/yrestStorage.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var import_node_crypto = require("crypto");
@@ -148,8 +148,8 @@ function deepCopyData(source) {
   );
 }
 
-// src/storage/yamlStorage.ts
-function createYamlStorage(filePath) {
+// src/storage/yrestStorage.ts
+function createYrestStorage(filePath) {
   const absPath = (0, import_node_path2.resolve)(filePath);
   const raw = (0, import_yaml.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
   const relations = raw["_rel"] ?? {};
@@ -469,16 +469,33 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     <table><tbody>
       ${customRoutes.map((r) => {
     const fullPath = `${base}${r.path}`;
+    const tags = [];
+    if (r.delay && r.delay > 0) {
+      tags.push(`<span style="color:#fb923c;font-size:11px">delay\xB7${r.delay}ms</span>`);
+    }
+    if (r.scenarios?.length) {
+      const hasOr = r.scenarios.some((s) => Array.isArray(s.when));
+      tags.push(
+        `<span style="color:#a371f7;font-size:11px">scenarios\xB7${r.scenarios.length}${hasOr ? " (OR)" : ""}</span>`
+      );
+    }
+    if (r.otherwise) {
+      tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
+    }
     let desc;
     if (r.handler) {
       const found = handlers.has(r.handler);
       desc = found ? `Handler \u2014 <code>${r.handler}()</code>` : `Handler \u2014 <code>${r.handler}()</code> <span style="color:#f85149">(not loaded)</span>`;
+    } else if (r.scenarios?.length) {
+      const hasTemplateInScenarios = r.scenarios.some((s) => s.response.body != null && hasTemplates(s.response.body)) || r.otherwise?.body != null && hasTemplates(r.otherwise.body);
+      desc = hasTemplateInScenarios ? `Scenarios \u2014 <code>{{\u2026}}</code>` : `Scenarios`;
     } else if (r.response?.body != null && hasTemplates(r.response.body)) {
-      desc = `Dynamic body \u2014 <code>{{\u2026}}</code>`;
+      desc = `Dynamic \u2014 <code>{{\u2026}}</code>`;
     } else {
       const status = r.response?.status ?? 200;
-      desc = `Static \u2014 <code>${status}</code>${r.response?.headers ? ` + custom headers` : ""}`;
+      desc = `Static \u2014 <code>${status}</code>${r.response?.headers ? ` + headers` : ""}`;
     }
+    if (tags.length) desc += `&ensp;${tags.join("&ensp;")}`;
     return endpointRow(r.method?.toUpperCase() ?? "GET", fullPath, desc);
   }).join("")}
     </tbody></table>
@@ -630,7 +647,7 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
 
   <div class="banner">
     <div class="banner-inner">
-      <h1><span class="y">y</span><span class="rest">rest</span></h1>
+      <h1><span class="y">y</span><span class="rest">Rest</span></h1>
       <p>Zero-config REST API mock server</p>
       <div class="banner-meta">
         <span>URL <strong>${host}</strong></span>
@@ -682,7 +699,7 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     ${collections.length ? `<h2>Examples</h2><div class="card">${examplesBlock(collections, relations, base, host, options, customRoutes[0])}</div>` : ""}
 
     <footer>
-      Powered by <a href="https://github.com/aggiovato/yaml-rest" target="_blank">@aggiovato/yrest</a> &nbsp;\xB7&nbsp; <a href="/_about">/_about</a>
+      Powered by <a href="https://github.com/aggiovato/yRest" target="_blank">@yrest/cli</a> &nbsp;\xB7&nbsp; <a href="/_about">/_about</a>
     </footer>
 
   </div>
@@ -987,7 +1004,63 @@ var CollectionRouteCommand = class {
   }
 };
 
+// src/utils/conditions.ts
+function resolveRequestPath(dotPath, req) {
+  const [root, ...rest] = dotPath.split(".");
+  let value;
+  switch (root) {
+    case "body":
+      value = req.body;
+      break;
+    case "params":
+      value = req.params;
+      break;
+    case "query":
+      value = req.query;
+      break;
+    case "headers":
+      value = req.headers;
+      break;
+    default:
+      return void 0;
+  }
+  for (const key of rest) {
+    if (value != null && typeof value === "object") {
+      value = value[key];
+    } else {
+      return void 0;
+    }
+  }
+  return value;
+}
+function matchConditionGroup(group, req) {
+  return Object.entries(group).every(([key, expected]) => {
+    const op = OPERATORS.find((o) => key.endsWith(o));
+    if (op) {
+      const path = key.slice(0, -op.length);
+      const value2 = resolveRequestPath(path, req);
+      if (value2 === void 0) return false;
+      return applyOperator(value2, op, String(expected));
+    }
+    const value = resolveRequestPath(key, req);
+    return String(value) === String(expected);
+  });
+}
+function matchWhen(when, req) {
+  if (Array.isArray(when)) {
+    return when.some((group) => matchConditionGroup(group, req));
+  }
+  return matchConditionGroup(when, req);
+}
+function findMatchingScenario(scenarios, req) {
+  return scenarios.find((s) => matchWhen(s.when, req));
+}
+
 // src/router/routes/custom.routes.ts
+function resolveBody(body, ctx) {
+  if (body != null && hasTemplates(body)) return interpolate(body, ctx);
+  return body ?? null;
+}
 var CustomRouteCommand = class {
   constructor(storage, base, handlers = /* @__PURE__ */ new Map()) {
     this.storage = storage;
@@ -1012,6 +1085,9 @@ var CustomRouteCommand = class {
         method,
         url,
         handler: async (req, reply) => {
+          if (route.delay && route.delay > 0) {
+            await new Promise((resolve5) => setTimeout(resolve5, route.delay));
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1021,13 +1097,13 @@ var CustomRouteCommand = class {
               return reply.status(501).send({ error: `Handler "${handlerName}" is not defined in the handlers file` });
             }
             try {
-              const ctx = {
+              const ctx2 = {
                 params: req.params,
                 query: req.query,
                 body: req.body,
                 headers: req.headers
               };
-              const result = await fn(ctx);
+              const result = await fn(ctx2);
               const resStatus = result.status ?? 200;
               for (const [k, v] of Object.entries(result.headers ?? {})) {
                 reply.header(k, v);
@@ -1039,12 +1115,24 @@ var CustomRouteCommand = class {
               return reply.status(500).send({ error: `Handler "${handlerName}" threw an error: ${msg}` });
             }
           }
-          const body = dynamic ? interpolate(rawBody, {
+          const ctx = {
             params: req.params,
             query: req.query,
             body: req.body,
             headers: req.headers
-          }) : rawBody;
+          };
+          if (route.scenarios?.length) {
+            const matched = findMatchingScenario(route.scenarios, ctx);
+            const active = matched?.response ?? route.otherwise;
+            if (active) {
+              const aStatus = active.status ?? 200;
+              const aBody = resolveBody(active.body, ctx);
+              for (const [k, v] of Object.entries(active.headers ?? {})) reply.header(k, v);
+              if (!active.body && aStatus === 204) return reply.status(aStatus).send();
+              return reply.status(aStatus).send(aBody);
+            }
+          }
+          const body = dynamic ? interpolate(rawBody, ctx) : rawBody;
           if (body === null && status === 204) return reply.status(status).send();
           return reply.status(status).send(body);
         }
@@ -1231,9 +1319,37 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   return server;
 }
 
+// src/server/yrestServer.ts
+function createYrestServerFromStorage(storage, options, handlers = /* @__PURE__ */ new Map()) {
+  let _port = 0;
+  let _started = false;
+  let _fastify = null;
+  return {
+    async start() {
+      if (_started) return;
+      _fastify = await createServer(storage, options, handlers);
+      await _fastify.listen({ port: options.port, host: options.host });
+      const address = _fastify.addresses()[0];
+      _port = typeof address === "object" && "port" in address ? address.port : options.port;
+      _started = true;
+    },
+    async stop() {
+      if (!_started || !_fastify) return;
+      await _fastify.close();
+      _started = false;
+    },
+    get port() {
+      return _port;
+    },
+    get url() {
+      return `http://${options.host}:${_port}${options.base}`;
+    }
+  };
+}
+
 // src/config/loadOptions.ts
 var import_zod = require("zod");
-var serverOptionsSchema = import_zod.z.object({
+var yrestOptionsSchema = import_zod.z.object({
   /** Path to the YAML database file. Must be a non-empty string. */
   file: import_zod.z.string().min(1),
   /** TCP port the server listens on. Accepts string input and coerces to number. */
@@ -1324,18 +1440,18 @@ function registerServe(program2) {
       ...cmd.args.length > 0 ? { file } : {},
       ...cliOverrides
     };
-    const options = serverOptionsSchema.parse(merged);
+    const options = yrestOptionsSchema.parse(merged);
     let storage;
     try {
-      storage = createYamlStorage(options.file);
+      storage = createYrestStorage(options.file);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`Error: cannot load "${options.file}" \u2014 ${msg}`);
       process.exit(1);
     }
     const handlers = options.handlers ? await loadHandlers((0, import_node_path3.resolve)(options.handlers)) : /* @__PURE__ */ new Map();
-    const server = await createServer(storage, options, handlers);
-    await server.listen({ port: options.port, host: options.host });
+    const yrestServer = createYrestServerFromStorage(storage, options, handlers);
+    await yrestServer.start();
     const collections = Object.keys(storage.getData());
     const customRoutes = storage.getRoutes();
     const base = options.base || "/";
@@ -1355,7 +1471,7 @@ function registerServe(program2) {
     };
     console.log(
       `
-  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${options.port}`)}
+  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${yrestServer.port}`)}
 `
     );
     console.log(`  ${b("Collections")} ${dim(`(base: ${base})`)}:`);