@yrest/cli 0.6.0 → 0.7.0

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`)                |  ✅   |     ❌      |
@@ -497,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:
@@ -844,23 +942,24 @@ const server = createYrestServer({
 
 ## 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                             | 🔜     |
+| 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:`)                         | ✅     |
 
 ---
 

package/dist/cli/index.js

@@ -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);
         }

package/dist/cli/index.mjs

@@ -442,16 +442,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>
@@ -603,7 +620,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>
@@ -655,7 +672,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>
@@ -960,7 +977,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;
@@ -985,6 +1058,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);
           }
@@ -994,13 +1070,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);
@@ -1012,12 +1088,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);
         }

package/dist/index.d.mts

@@ -21,19 +21,72 @@ type Data = Record<string, Resource[]>;
  * // GET /users/1/posts → returns posts where userId === "1"
  */
 type Relations = Record<string, Record<string, string>>;
+/**
+ * A static response block shared by {@link CustomRoute} and {@link Scenario}.
+ */
+type RouteResponse = {
+    /** HTTP status code. Defaults to `200` if omitted. */
+    status?: number;
+    /** Response body. Any YAML-serialisable value (object, array, string, number, null). */
+    body?: unknown;
+    /** Additional response headers to set alongside `Content-Type`. */
+    headers?: Record<string, string>;
+};
+/**
+ * A conditional response variant for a custom route.
+ *
+ * Evaluated in declaration order — the first scenario whose `when` conditions match wins.
+ * If none match, the route falls back to `otherwise:` (if defined) or `response:`.
+ *
+ * **`when` as an object** — all entries must match (AND):
+ * ```yaml
+ * when: { body.email: ana@test.com, body.password: secret }
+ * ```
+ *
+ * **`when` as an array** — any group must match (OR of ANDs):
+ * ```yaml
+ * when:
+ *   - { body.role: admin }
+ *   - { body.role: superadmin }
+ * ```
+ *
+ * Condition keys use dot-notation (`body.X`, `params.X`, `query.X`, `headers.X`).
+ * Field operator suffixes are supported: `_ne`, `_like`, `_start`, `_regex`, `_gte`, `_lte`.
+ * Response bodies support `{{}}` template variables (same as static routes).
+ */
+type Scenario = {
+    /**
+     * Condition(s) to evaluate against the request.
+     * - Object → all entries AND
+     * - Array of objects → any group OR (each group is AND internally)
+     */
+    when: Record<string, unknown> | Record<string, unknown>[];
+    /** Response to return when the conditions match. Supports `{{}}` template variables. */
+    response: RouteResponse;
+};
 /**
  * A single custom route declared under `_routes` in the YAML file.
  *
- * Custom routes are registered before resource routes and take priority over them.
- * They always return a static, pre-defined response regardless of the request body or params.
+ * Resolution priority per request:
+ * 1. `handler` function (if defined and found in the handlers file)
+ * 2. First matching `scenario` (evaluated in declaration order)
+ * 3. `otherwise` block (explicit fallback when scenarios are defined but none matched)
+ * 4. Static `response` block (final fallback)
  *
  * @example
  * // _routes:
  * //   - method: POST
  * //     path: /login
- * //     response:
- * //       status: 200
- * //       body: { token: abc123 }
+ * //     scenarios:
+ * //       - when: { body.password: secret }
+ * //         response: { status: 200, body: { token: real-tok } }
+ * //       - when:
+ * //           - { body.role: admin }
+ * //           - { body.role: superadmin }
+ * //         response: { status: 200, body: { token: admin-tok } }
+ * //     otherwise:
+ * //       status: 401
+ * //       body: { error: Invalid credentials }
  */
 type CustomRoute = {
     /** HTTP method (case-insensitive: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). */
@@ -42,19 +95,23 @@ type CustomRoute = {
     path: string;
     /**
      * Name of an exported function in the handlers file (`handlers:` in config).
-     * When set, the function is called on every request and its return value is used as the response.
-     * Takes priority over `response:`. Falls back to `response:` if the name is not found.
+     * Takes priority over `scenarios` and `response`. Falls back to `response` if not found.
      */
     handler?: string;
-    /** Static or template response. Used when `handler` is absent or not found in the handlers file. */
-    response?: {
-        /** HTTP status code. Defaults to `200` if omitted. */
-        status?: number;
-        /** Response body. Any YAML-serialisable value (object, array, string, number, null). */
-        body?: unknown;
-        /** Additional response headers to set alongside `Content-Type`. */
-        headers?: Record<string, string>;
-    };
+    /** Conditional response variants. Evaluated in order — first match wins. */
+    scenarios?: Scenario[];
+    /**
+     * Explicit fallback response when `scenarios` are defined but none matched.
+     * Takes priority over `response` when present. Supports `{{}}` template variables.
+     */
+    otherwise?: RouteResponse;
+    /** Static or template response. Final fallback when no handler, scenario, or otherwise applies. */
+    response?: RouteResponse;
+    /**
+     * Per-route response delay in milliseconds. Overrides the global `--delay` option for this route.
+     * Applied before any response is sent, regardless of which path resolved the response.
+     */
+    delay?: number;
 };
 /**
  * In-memory store backed by a YAML file.

package/dist/index.d.ts

@@ -21,19 +21,72 @@ type Data = Record<string, Resource[]>;
  * // GET /users/1/posts → returns posts where userId === "1"
  */
 type Relations = Record<string, Record<string, string>>;
+/**
+ * A static response block shared by {@link CustomRoute} and {@link Scenario}.
+ */
+type RouteResponse = {
+    /** HTTP status code. Defaults to `200` if omitted. */
+    status?: number;
+    /** Response body. Any YAML-serialisable value (object, array, string, number, null). */
+    body?: unknown;
+    /** Additional response headers to set alongside `Content-Type`. */
+    headers?: Record<string, string>;
+};
+/**
+ * A conditional response variant for a custom route.
+ *
+ * Evaluated in declaration order — the first scenario whose `when` conditions match wins.
+ * If none match, the route falls back to `otherwise:` (if defined) or `response:`.
+ *
+ * **`when` as an object** — all entries must match (AND):
+ * ```yaml
+ * when: { body.email: ana@test.com, body.password: secret }
+ * ```
+ *
+ * **`when` as an array** — any group must match (OR of ANDs):
+ * ```yaml
+ * when:
+ *   - { body.role: admin }
+ *   - { body.role: superadmin }
+ * ```
+ *
+ * Condition keys use dot-notation (`body.X`, `params.X`, `query.X`, `headers.X`).
+ * Field operator suffixes are supported: `_ne`, `_like`, `_start`, `_regex`, `_gte`, `_lte`.
+ * Response bodies support `{{}}` template variables (same as static routes).
+ */
+type Scenario = {
+    /**
+     * Condition(s) to evaluate against the request.
+     * - Object → all entries AND
+     * - Array of objects → any group OR (each group is AND internally)
+     */
+    when: Record<string, unknown> | Record<string, unknown>[];
+    /** Response to return when the conditions match. Supports `{{}}` template variables. */
+    response: RouteResponse;
+};
 /**
  * A single custom route declared under `_routes` in the YAML file.
  *
- * Custom routes are registered before resource routes and take priority over them.
- * They always return a static, pre-defined response regardless of the request body or params.
+ * Resolution priority per request:
+ * 1. `handler` function (if defined and found in the handlers file)
+ * 2. First matching `scenario` (evaluated in declaration order)
+ * 3. `otherwise` block (explicit fallback when scenarios are defined but none matched)
+ * 4. Static `response` block (final fallback)
  *
  * @example
  * // _routes:
  * //   - method: POST
  * //     path: /login
- * //     response:
- * //       status: 200
- * //       body: { token: abc123 }
+ * //     scenarios:
+ * //       - when: { body.password: secret }
+ * //         response: { status: 200, body: { token: real-tok } }
+ * //       - when:
+ * //           - { body.role: admin }
+ * //           - { body.role: superadmin }
+ * //         response: { status: 200, body: { token: admin-tok } }
+ * //     otherwise:
+ * //       status: 401
+ * //       body: { error: Invalid credentials }
  */
 type CustomRoute = {
     /** HTTP method (case-insensitive: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). */
@@ -42,19 +95,23 @@ type CustomRoute = {
     path: string;
     /**
      * Name of an exported function in the handlers file (`handlers:` in config).
-     * When set, the function is called on every request and its return value is used as the response.
-     * Takes priority over `response:`. Falls back to `response:` if the name is not found.
+     * Takes priority over `scenarios` and `response`. Falls back to `response` if not found.
      */
     handler?: string;
-    /** Static or template response. Used when `handler` is absent or not found in the handlers file. */
-    response?: {
-        /** HTTP status code. Defaults to `200` if omitted. */
-        status?: number;
-        /** Response body. Any YAML-serialisable value (object, array, string, number, null). */
-        body?: unknown;
-        /** Additional response headers to set alongside `Content-Type`. */
-        headers?: Record<string, string>;
-    };
+    /** Conditional response variants. Evaluated in order — first match wins. */
+    scenarios?: Scenario[];
+    /**
+     * Explicit fallback response when `scenarios` are defined but none matched.
+     * Takes priority over `response` when present. Supports `{{}}` template variables.
+     */
+    otherwise?: RouteResponse;
+    /** Static or template response. Final fallback when no handler, scenario, or otherwise applies. */
+    response?: RouteResponse;
+    /**
+     * Per-route response delay in milliseconds. Overrides the global `--delay` option for this route.
+     * Applied before any response is sent, regardless of which path resolved the response.
+     */
+    delay?: number;
 };
 /**
  * In-memory store backed by a YAML file.

package/dist/index.js

@@ -485,16 +485,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>
@@ -646,7 +663,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>
@@ -698,7 +715,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>
@@ -1012,6 +1029,65 @@ var CollectionRouteCommand = class {
 
 // src/router/routes/custom.routes.ts
 init_cjs_shims();
+
+// src/utils/conditions.ts
+init_cjs_shims();
+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;
@@ -1036,6 +1112,9 @@ var CustomRouteCommand = class {
         method,
         url,
         handler: async (req, reply) => {
+          if (route.delay && route.delay > 0) {
+            await new Promise((resolve3) => setTimeout(resolve3, route.delay));
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1045,13 +1124,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);
@@ -1063,12 +1142,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);
         }

package/dist/index.mjs

@@ -454,16 +454,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>
@@ -615,7 +632,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>
@@ -667,7 +684,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>
@@ -981,6 +998,65 @@ var CollectionRouteCommand = class {
 
 // src/router/routes/custom.routes.ts
 init_esm_shims();
+
+// src/utils/conditions.ts
+init_esm_shims();
+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 path2 = key.slice(0, -op.length);
+      const value2 = resolveRequestPath(path2, 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;
@@ -1005,6 +1081,9 @@ var CustomRouteCommand = class {
         method,
         url,
         handler: async (req, reply) => {
+          if (route.delay && route.delay > 0) {
+            await new Promise((resolve3) => setTimeout(resolve3, route.delay));
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1014,13 +1093,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);
@@ -1032,12 +1111,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);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yrest/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a db.yml file.",
   "keywords": [
     "yrest",