@yrest/cli 0.7.0 → 0.8.0

package/README.md

@@ -1,4 +1,8 @@
-# yRest
+<div align="center">
+  <img src="assets/yRest-banner.png" alt="yRest" width="100%" />
+</div>
+
+<br/>
 
 [![npm version](https://img.shields.io/npm/v/@yrest/cli)](https://www.npmjs.com/package/@yrest/cli)
 [![npm downloads](https://img.shields.io/npm/dw/@yrest/cli)](https://www.npmjs.com/package/@yrest/cli)
@@ -6,6 +10,7 @@
 [![CI](https://github.com/aggiovato/yRest/actions/workflows/ci.yml/badge.svg)](https://github.com/aggiovato/yRest/actions)
 [![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.8.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.
 
@@ -157,6 +162,7 @@ npx @yrest/cli serve db.yml --handlers yrest.handlers.js
 | `--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         |
+| `--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.
 
@@ -178,6 +184,7 @@ host: localhost
 # pageable: false   # true (limit 10), or a number (custom limit)
 # snapshot: false
 # handlers: yrest.handlers.js
+# idStrategy: increment   # increment or uuid
 ```
 
 **Priority order** (highest wins): CLI flags → `yrest.config.yml` → schema defaults.
@@ -595,6 +602,36 @@ _routes:
       body: { data: loaded }
 ```
 
+### Error injection
+
+Force a custom route to always return a specific HTTP error, regardless of handlers, scenarios or the static response. Useful for simulating outages, payment failures or auth errors:
+
+```yaml
+_routes:
+  - method: GET
+    path: /payments
+    error: 503
+    errorBody:
+      message: Service temporarily unavailable
+      retryAfter: 30
+
+  - method: POST
+    path: /checkout
+    error: 402
+    errorBody:
+      error: Payment required
+
+  - method: GET
+    path: /slow-failure
+    delay: 400
+    error: 500
+```
+
+- `error` takes priority over `handler`, `scenarios` and `response` — the route always returns this status.
+- `errorBody` is optional. If omitted, the default body is `{ "error": "Forced error NNN" }`.
+- `delay` still applies before the error is returned.
+- Shown in `/_about` with a red `error·NNN` badge.
+
 ### Handler functions
 
 For routes that need real logic (conditional responses, stateful mocks, request inspection), reference a JavaScript function via the `handler:` field:
@@ -960,6 +997,8 @@ const server = createYrestServer({
 | Request validation with JSON Schema                | 🔜     |
 | Conditional scenarios (`scenarios:`, `otherwise:`) | ✅     |
 | Per-route delay (`delay:`)                         | ✅     |
+| Error injection (`error:` in `_routes`)            | ✅     |
+| Configurable ID strategy (`idStrategy`)            | ✅     |
 
 ---
 

package/dist/cli/index.js

@@ -132,8 +132,8 @@ function registerInit(program2) {
 }
 
 // src/cli/commands/serve.ts
-var import_node_fs5 = require("fs");
-var import_node_path3 = require("path");
+var import_node_fs6 = require("fs");
+var import_node_path4 = require("path");
 
 // src/storage/yrestStorage.ts
 var import_node_fs2 = require("fs");
@@ -223,6 +223,11 @@ function createYrestStorage(filePath) {
 var import_fastify = __toESM(require("fastify"));
 var import_cors = __toESM(require("@fastify/cors"));
 
+// src/router/templates/about.template.ts
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+var import_node_url = require("url");
+
 // src/utils/interpolate.ts
 var import_node_crypto2 = require("crypto");
 function getPath(obj, path) {
@@ -270,6 +275,15 @@ function hasTemplates(value) {
 }
 
 // src/router/templates/about.template.ts
+var _dir = (0, import_node_path3.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+var LOGO_SRC = (() => {
+  try {
+    const buf = (0, import_node_fs3.readFileSync)((0, import_node_path3.join)(_dir, "../../assets/logo-color.png"));
+    return `data:image/png;base64,${buf.toString("base64")}`;
+  } catch {
+    return "";
+  }
+})();
 var METHOD_COLOR = {
   GET: "#3fb950",
   POST: "#58a6ff",
@@ -428,6 +442,8 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
   if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   if (handlers.size > 0) modes.push(badge(`handlers \xB7 ${handlers.size}`, "#f0883e", "#f0883e18"));
+  if (options.idStrategy !== "increment")
+    modes.push(badge(`id \xB7 ${options.idStrategy}`, "#a371f7", "#a371f718"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -470,6 +486,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       ${customRoutes.map((r) => {
     const fullPath = `${base}${r.path}`;
     const tags = [];
+    if (r.error) {
+      tags.push(`<span style="color:#f85149;font-size:11px">error\xB7${r.error}</span>`);
+    }
     if (r.delay && r.delay > 0) {
       tags.push(`<span style="color:#fb923c;font-size:11px">delay\xB7${r.delay}ms</span>`);
     }
@@ -483,7 +502,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
     }
     let desc;
-    if (r.handler) {
+    if (r.error) {
+      desc = `Error injection \u2014 <code>${r.error}</code>`;
+    } else 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) {
@@ -647,7 +668,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>
+      ${LOGO_SRC ? `<img src="${LOGO_SRC}" alt="yRest" height="68" style="display:block;margin-bottom:0px" />` : `<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>
@@ -730,6 +751,10 @@ function nextId(items) {
   const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
 }
+function generateId(items, strategy) {
+  if (strategy === "uuid") return crypto.randomUUID();
+  return nextId(items);
+}
 function firstParam(value) {
   if (value === void 0) return void 0;
   return Array.isArray(value) ? value[0] : value;
@@ -817,10 +842,10 @@ function findById(items, id) {
 function findIndexById(items, id) {
   return items.findIndex((i) => String(i["id"]) === id);
 }
-function createItem(storage, resource, body) {
+function createItem(storage, resource, body, idStrategy = "increment") {
   const collection = storage.getCollection(resource) ?? [];
   const item = {
-    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    id: body["id"] !== void 0 ? body["id"] : generateId(collection, idStrategy),
     ...body
   };
   storage.setCollection(resource, [...collection, item]);
@@ -998,7 +1023,12 @@ var CollectionRouteCommand = class {
       if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
         return reply.status(400).send({ error: "Request body must be a JSON object" });
       }
-      const item = createItem(this.storage, this.resource, req.body);
+      const item = createItem(
+        this.storage,
+        this.resource,
+        req.body,
+        this.options.idStrategy
+      );
       return reply.status(201).send(expandItems(item, req.query, this.resource, this.storage));
     });
   }
@@ -1088,6 +1118,10 @@ var CustomRouteCommand = class {
           if (route.delay && route.delay > 0) {
             await new Promise((resolve5) => setTimeout(resolve5, route.delay));
           }
+          if (route.error) {
+            const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
+            return reply.status(route.error).send(body2);
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1384,22 +1418,29 @@ var yrestOptionsSchema = import_zod.z.object({
   pageable: import_zod.z.union([import_zod.z.boolean(), import_zod.z.coerce.number().int().positive()]).default(false).transform((v) => ({
     enabled: v !== false,
     limit: v === false || v === true ? 10 : v
-  }))
+  })),
+  /**
+   * Strategy used to generate `id` values for new items when no `id` is provided in the body.
+   *
+   * - `"increment"` (default) — next integer above the current max id in the collection.
+   * - `"uuid"` — a random UUID v4 string (`crypto.randomUUID()`).
+   */
+  idStrategy: import_zod.z.enum(["increment", "uuid"]).default("increment")
 });
 
 // src/config/loadConfigFile.ts
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 var import_yaml2 = require("yaml");
 function loadConfigFile(configPath) {
-  if (!(0, import_node_fs3.existsSync)(configPath)) return {};
-  const raw = (0, import_node_fs3.readFileSync)(configPath, "utf8");
+  if (!(0, import_node_fs4.existsSync)(configPath)) return {};
+  const raw = (0, import_node_fs4.readFileSync)(configPath, "utf8");
   return (0, import_yaml2.parse)(raw) ?? {};
 }
 
 // src/utils/handlers.ts
-var import_node_fs4 = require("fs");
+var import_node_fs5 = require("fs");
 async function loadHandlers(filePath) {
-  if (!(0, import_node_fs4.existsSync)(filePath)) return /* @__PURE__ */ new Map();
+  if (!(0, import_node_fs5.existsSync)(filePath)) return /* @__PURE__ */ new Map();
   try {
     const mod = await import(filePath);
     const map = /* @__PURE__ */ new Map();
@@ -1429,8 +1470,12 @@ function registerServe(program2) {
   ).option(
     "--handlers <file>",
     "Path to a JavaScript file exporting custom route handler functions"
+  ).option(
+    "--id-strategy <strategy>",
+    "Id generation strategy for new items: increment (default) or uuid",
+    "increment"
   ).action(async (file, flags, cmd) => {
-    const fileConfig = loadConfigFile((0, import_node_path3.join)(process.cwd(), "yrest.config.yml"));
+    const fileConfig = loadConfigFile((0, import_node_path4.join)(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
       Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
     );
@@ -1449,7 +1494,7 @@ function registerServe(program2) {
       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 handlers = options.handlers ? await loadHandlers((0, import_node_path4.resolve)(options.handlers)) : /* @__PURE__ */ new Map();
     const yrestServer = createYrestServerFromStorage(storage, options, handlers);
     await yrestServer.start();
     const collections = Object.keys(storage.getData());
@@ -1511,9 +1556,9 @@ function registerServe(program2) {
   ${dim(modes.map((m) => `[${m}]`).join("  "))}`);
     console.log("");
     if (options.watch) {
-      const absFile = (0, import_node_path3.resolve)(options.file);
+      const absFile = (0, import_node_path4.resolve)(options.file);
       let debounce;
-      (0, import_node_fs5.watchFile)(absFile, { interval: 300 }, (curr, prev) => {
+      (0, import_node_fs6.watchFile)(absFile, { interval: 300 }, (curr, prev) => {
         if (curr.mtimeMs === prev.mtimeMs) return;
         clearTimeout(debounce);
         debounce = setTimeout(() => {
@@ -1533,8 +1578,8 @@ function registerServe(program2) {
 }
 
 // src/cli/commands/handler.ts
-var import_node_fs6 = require("fs");
-var import_node_path4 = require("path");
+var import_node_fs7 = require("fs");
+var import_node_path5 = require("path");
 var import_yaml3 = require("yaml");
 var HANDLERS_FILE_HEADER = `// yrest handlers \u2014 loaded via "handlers:" in yrest.config.yml
 // Handler signature: (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>
@@ -1561,44 +1606,44 @@ function registerHandler(program2) {
     "--register",
     "Also add a _routes entry to db.yml linking this handler to method + path"
   ).action((name, flags) => {
-    const fileConfig = loadConfigFile((0, import_node_path4.join)(process.cwd(), "yrest.config.yml"));
-    const handlersPath = (0, import_node_path4.resolve)(
+    const fileConfig = loadConfigFile((0, import_node_path5.join)(process.cwd(), "yrest.config.yml"));
+    const handlersPath = (0, import_node_path5.resolve)(
       fileConfig.handlers ?? "yrest.handlers.js"
     );
-    const dbPath = (0, import_node_path4.resolve)(fileConfig.file ?? "db.yml");
-    if (!(0, import_node_fs6.existsSync)(handlersPath)) {
-      (0, import_node_fs6.writeFileSync)(
+    const dbPath = (0, import_node_path5.resolve)(fileConfig.file ?? "db.yml");
+    if (!(0, import_node_fs7.existsSync)(handlersPath)) {
+      (0, import_node_fs7.writeFileSync)(
         handlersPath,
         HANDLERS_FILE_HEADER + buildStub(name, flags.method, flags.path),
         "utf8"
       );
-      console.log(`  Created ${(0, import_node_path4.basename)(handlersPath)}`);
+      console.log(`  Created ${(0, import_node_path5.basename)(handlersPath)}`);
     } else {
-      const existing = (0, import_node_fs6.readFileSync)(handlersPath, "utf8");
+      const existing = (0, import_node_fs7.readFileSync)(handlersPath, "utf8");
       if (existing.includes(`function ${name}(`)) {
-        console.error(`  Error: handler "${name}" already exists in ${(0, import_node_path4.basename)(handlersPath)}`);
+        console.error(`  Error: handler "${name}" already exists in ${(0, import_node_path5.basename)(handlersPath)}`);
         process.exit(1);
       }
-      (0, import_node_fs6.appendFileSync)(handlersPath, buildStub(name, flags.method, flags.path), "utf8");
-      console.log(`  Added handler "${name}" to ${(0, import_node_path4.basename)(handlersPath)}`);
+      (0, import_node_fs7.appendFileSync)(handlersPath, buildStub(name, flags.method, flags.path), "utf8");
+      console.log(`  Added handler "${name}" to ${(0, import_node_path5.basename)(handlersPath)}`);
     }
     if (flags.register) {
       if (!flags.method || !flags.path) {
         console.error("  Error: --register requires --method and --path");
         process.exit(1);
       }
-      if (!(0, import_node_fs6.existsSync)(dbPath)) {
+      if (!(0, import_node_fs7.existsSync)(dbPath)) {
         console.error(`  Error: database file not found at ${dbPath}`);
         process.exit(1);
       }
-      const raw = (0, import_yaml3.parse)((0, import_node_fs6.readFileSync)(dbPath, "utf8")) ?? {};
+      const raw = (0, import_yaml3.parse)((0, import_node_fs7.readFileSync)(dbPath, "utf8")) ?? {};
       if (!Array.isArray(raw["_routes"])) raw["_routes"] = [];
       const routes = raw["_routes"];
       const alreadyRegistered = routes.some((r) => r["handler"] === name);
       if (!alreadyRegistered) {
         routes.push({ method: flags.method.toUpperCase(), path: flags.path, handler: name });
-        (0, import_node_fs6.writeFileSync)(dbPath, (0, import_yaml3.stringify)(raw), "utf8");
-        console.log(`  Added _routes entry to ${(0, import_node_path4.basename)(dbPath)}`);
+        (0, import_node_fs7.writeFileSync)(dbPath, (0, import_yaml3.stringify)(raw), "utf8");
+        console.log(`  Added _routes entry to ${(0, import_node_path5.basename)(dbPath)}`);
       } else {
         console.log(`  Handler "${name}" already in _routes \u2014 skipped`);
       }
@@ -1606,10 +1651,10 @@ function registerHandler(program2) {
     console.log(`
   Next steps:`);
     if (!fileConfig.handlers) {
-      console.log(`    1. Add  handlers: ${(0, import_node_path4.basename)(handlersPath)}  to yrest.config.yml`);
-      console.log(`    2. Implement the "${name}" function in ${(0, import_node_path4.basename)(handlersPath)}`);
+      console.log(`    1. Add  handlers: ${(0, import_node_path5.basename)(handlersPath)}  to yrest.config.yml`);
+      console.log(`    2. Implement the "${name}" function in ${(0, import_node_path5.basename)(handlersPath)}`);
     } else {
-      console.log(`    1. Implement the "${name}" function in ${(0, import_node_path4.basename)(handlersPath)}`);
+      console.log(`    1. Implement the "${name}" function in ${(0, import_node_path5.basename)(handlersPath)}`);
     }
     if (!flags.register) {
       console.log(

package/dist/cli/index.mjs

@@ -106,7 +106,7 @@ function registerInit(program2) {
 
 // src/cli/commands/serve.ts
 import { watchFile } from "fs";
-import { join, resolve as resolve3 } from "path";
+import { join as join2, resolve as resolve3 } from "path";
 
 // src/storage/yrestStorage.ts
 import { readFileSync, writeFileSync as writeFileSync2, renameSync } from "fs";
@@ -196,6 +196,11 @@ function createYrestStorage(filePath) {
 import Fastify from "fastify";
 import cors from "@fastify/cors";
 
+// src/router/templates/about.template.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, join } from "path";
+import { fileURLToPath } from "url";
+
 // src/utils/interpolate.ts
 import { randomUUID as randomUUID2 } from "crypto";
 function getPath(obj, path) {
@@ -243,6 +248,15 @@ function hasTemplates(value) {
 }
 
 // src/router/templates/about.template.ts
+var _dir = dirname2(fileURLToPath(import.meta.url));
+var LOGO_SRC = (() => {
+  try {
+    const buf = readFileSync2(join(_dir, "../../assets/logo-color.png"));
+    return `data:image/png;base64,${buf.toString("base64")}`;
+  } catch {
+    return "";
+  }
+})();
 var METHOD_COLOR = {
   GET: "#3fb950",
   POST: "#58a6ff",
@@ -401,6 +415,8 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
   if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   if (handlers.size > 0) modes.push(badge(`handlers \xB7 ${handlers.size}`, "#f0883e", "#f0883e18"));
+  if (options.idStrategy !== "increment")
+    modes.push(badge(`id \xB7 ${options.idStrategy}`, "#a371f7", "#a371f718"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -443,6 +459,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       ${customRoutes.map((r) => {
     const fullPath = `${base}${r.path}`;
     const tags = [];
+    if (r.error) {
+      tags.push(`<span style="color:#f85149;font-size:11px">error\xB7${r.error}</span>`);
+    }
     if (r.delay && r.delay > 0) {
       tags.push(`<span style="color:#fb923c;font-size:11px">delay\xB7${r.delay}ms</span>`);
     }
@@ -456,7 +475,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
     }
     let desc;
-    if (r.handler) {
+    if (r.error) {
+      desc = `Error injection \u2014 <code>${r.error}</code>`;
+    } else 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) {
@@ -620,7 +641,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>
+      ${LOGO_SRC ? `<img src="${LOGO_SRC}" alt="yRest" height="68" style="display:block;margin-bottom:0px" />` : `<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>
@@ -703,6 +724,10 @@ function nextId(items) {
   const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
 }
+function generateId(items, strategy) {
+  if (strategy === "uuid") return crypto.randomUUID();
+  return nextId(items);
+}
 function firstParam(value) {
   if (value === void 0) return void 0;
   return Array.isArray(value) ? value[0] : value;
@@ -790,10 +815,10 @@ function findById(items, id) {
 function findIndexById(items, id) {
   return items.findIndex((i) => String(i["id"]) === id);
 }
-function createItem(storage, resource, body) {
+function createItem(storage, resource, body, idStrategy = "increment") {
   const collection = storage.getCollection(resource) ?? [];
   const item = {
-    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    id: body["id"] !== void 0 ? body["id"] : generateId(collection, idStrategy),
     ...body
   };
   storage.setCollection(resource, [...collection, item]);
@@ -971,7 +996,12 @@ var CollectionRouteCommand = class {
       if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
         return reply.status(400).send({ error: "Request body must be a JSON object" });
       }
-      const item = createItem(this.storage, this.resource, req.body);
+      const item = createItem(
+        this.storage,
+        this.resource,
+        req.body,
+        this.options.idStrategy
+      );
       return reply.status(201).send(expandItems(item, req.query, this.resource, this.storage));
     });
   }
@@ -1061,6 +1091,10 @@ var CustomRouteCommand = class {
           if (route.delay && route.delay > 0) {
             await new Promise((resolve5) => setTimeout(resolve5, route.delay));
           }
+          if (route.error) {
+            const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
+            return reply.status(route.error).send(body2);
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1357,15 +1391,22 @@ var yrestOptionsSchema = z.object({
   pageable: z.union([z.boolean(), z.coerce.number().int().positive()]).default(false).transform((v) => ({
     enabled: v !== false,
     limit: v === false || v === true ? 10 : v
-  }))
+  })),
+  /**
+   * Strategy used to generate `id` values for new items when no `id` is provided in the body.
+   *
+   * - `"increment"` (default) — next integer above the current max id in the collection.
+   * - `"uuid"` — a random UUID v4 string (`crypto.randomUUID()`).
+   */
+  idStrategy: z.enum(["increment", "uuid"]).default("increment")
 });
 
 // src/config/loadConfigFile.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
 import { parse as parse2 } from "yaml";
 function loadConfigFile(configPath) {
   if (!existsSync2(configPath)) return {};
-  const raw = readFileSync2(configPath, "utf8");
+  const raw = readFileSync3(configPath, "utf8");
   return parse2(raw) ?? {};
 }
 
@@ -1402,8 +1443,12 @@ function registerServe(program2) {
   ).option(
     "--handlers <file>",
     "Path to a JavaScript file exporting custom route handler functions"
+  ).option(
+    "--id-strategy <strategy>",
+    "Id generation strategy for new items: increment (default) or uuid",
+    "increment"
   ).action(async (file, flags, cmd) => {
-    const fileConfig = loadConfigFile(join(process.cwd(), "yrest.config.yml"));
+    const fileConfig = loadConfigFile(join2(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
       Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
     );
@@ -1506,8 +1551,8 @@ function registerServe(program2) {
 }
 
 // src/cli/commands/handler.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3, appendFileSync, writeFileSync as writeFileSync3 } from "fs";
-import { join as join2, resolve as resolve4, basename } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4, appendFileSync, writeFileSync as writeFileSync3 } from "fs";
+import { join as join3, resolve as resolve4, basename } from "path";
 import { parse as parse3, stringify as stringify2 } from "yaml";
 var HANDLERS_FILE_HEADER = `// yrest handlers \u2014 loaded via "handlers:" in yrest.config.yml
 // Handler signature: (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>
@@ -1534,7 +1579,7 @@ function registerHandler(program2) {
     "--register",
     "Also add a _routes entry to db.yml linking this handler to method + path"
   ).action((name, flags) => {
-    const fileConfig = loadConfigFile(join2(process.cwd(), "yrest.config.yml"));
+    const fileConfig = loadConfigFile(join3(process.cwd(), "yrest.config.yml"));
     const handlersPath = resolve4(
       fileConfig.handlers ?? "yrest.handlers.js"
     );
@@ -1547,7 +1592,7 @@ function registerHandler(program2) {
       );
       console.log(`  Created ${basename(handlersPath)}`);
     } else {
-      const existing = readFileSync3(handlersPath, "utf8");
+      const existing = readFileSync4(handlersPath, "utf8");
       if (existing.includes(`function ${name}(`)) {
         console.error(`  Error: handler "${name}" already exists in ${basename(handlersPath)}`);
         process.exit(1);
@@ -1564,7 +1609,7 @@ function registerHandler(program2) {
         console.error(`  Error: database file not found at ${dbPath}`);
         process.exit(1);
       }
-      const raw = parse3(readFileSync3(dbPath, "utf8")) ?? {};
+      const raw = parse3(readFileSync4(dbPath, "utf8")) ?? {};
       if (!Array.isArray(raw["_routes"])) raw["_routes"] = [];
       const routes = raw["_routes"];
       const alreadyRegistered = routes.some((r) => r["handler"] === name);

package/dist/index.d.mts

@@ -112,6 +112,19 @@ type CustomRoute = {
      * Applied before any response is sent, regardless of which path resolved the response.
      */
     delay?: number;
+    /**
+     * Forces this route to always return the given HTTP status code as an error,
+     * bypassing handlers, scenarios and the static response entirely.
+     * Applied after `delay:` so slow-error scenarios still work.
+     *
+     * @example
+     * // Always return 503
+     * error: 503
+     * errorBody: { message: "Service unavailable" }
+     */
+    error?: number;
+    /** Optional body to return alongside `error:`. Defaults to `{ error: "Forced error <status>" }`. */
+    errorBody?: unknown;
 };
 /**
  * In-memory store backed by a YAML file.
@@ -251,6 +264,13 @@ declare const yrestOptionsSchema: z.ZodObject<{
         enabled: boolean;
         limit: number;
     }, number | boolean | undefined>;
+    /**
+     * Strategy used to generate `id` values for new items when no `id` is provided in the body.
+     *
+     * - `"increment"` (default) — next integer above the current max id in the collection.
+     * - `"uuid"` — a random UUID v4 string (`crypto.randomUUID()`).
+     */
+    idStrategy: z.ZodDefault<z.ZodEnum<["increment", "uuid"]>>;
 }, "strip", z.ZodTypeAny, {
     file: string;
     port: number;
@@ -264,6 +284,7 @@ declare const yrestOptionsSchema: z.ZodObject<{
         enabled: boolean;
         limit: number;
     };
+    idStrategy: "increment" | "uuid";
     handlers?: string | undefined;
 }, {
     file: string;
@@ -276,6 +297,7 @@ declare const yrestOptionsSchema: z.ZodObject<{
     delay?: number | undefined;
     handlers?: string | undefined;
     pageable?: number | boolean | undefined;
+    idStrategy?: "increment" | "uuid" | undefined;
 }>;
 /**
  * Resolved server configuration after Zod validation and transformation.

package/dist/index.d.ts

@@ -112,6 +112,19 @@ type CustomRoute = {
      * Applied before any response is sent, regardless of which path resolved the response.
      */
     delay?: number;
+    /**
+     * Forces this route to always return the given HTTP status code as an error,
+     * bypassing handlers, scenarios and the static response entirely.
+     * Applied after `delay:` so slow-error scenarios still work.
+     *
+     * @example
+     * // Always return 503
+     * error: 503
+     * errorBody: { message: "Service unavailable" }
+     */
+    error?: number;
+    /** Optional body to return alongside `error:`. Defaults to `{ error: "Forced error <status>" }`. */
+    errorBody?: unknown;
 };
 /**
  * In-memory store backed by a YAML file.
@@ -251,6 +264,13 @@ declare const yrestOptionsSchema: z.ZodObject<{
         enabled: boolean;
         limit: number;
     }, number | boolean | undefined>;
+    /**
+     * Strategy used to generate `id` values for new items when no `id` is provided in the body.
+     *
+     * - `"increment"` (default) — next integer above the current max id in the collection.
+     * - `"uuid"` — a random UUID v4 string (`crypto.randomUUID()`).
+     */
+    idStrategy: z.ZodDefault<z.ZodEnum<["increment", "uuid"]>>;
 }, "strip", z.ZodTypeAny, {
     file: string;
     port: number;
@@ -264,6 +284,7 @@ declare const yrestOptionsSchema: z.ZodObject<{
         enabled: boolean;
         limit: number;
     };
+    idStrategy: "increment" | "uuid";
     handlers?: string | undefined;
 }, {
     file: string;
@@ -276,6 +297,7 @@ declare const yrestOptionsSchema: z.ZodObject<{
     delay?: number | undefined;
     handlers?: string | undefined;
     pageable?: number | boolean | undefined;
+    idStrategy?: "increment" | "uuid" | undefined;
 }>;
 /**
  * Resolved server configuration after Zod validation and transformation.

package/dist/index.js

@@ -31,9 +31,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl, importMetaUrl;
 var init_cjs_shims = __esm({
   "node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
+    getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+    importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
   }
 });
 
@@ -56,8 +59,8 @@ __export(yrestStorage_exports, {
   createYrestStorage: () => createYrestStorage
 });
 function createYrestStorage(filePath) {
-  const absPath = (0, import_node_path.resolve)(filePath);
-  const raw = (0, import_yaml2.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
+  const absPath = (0, import_node_path2.resolve)(filePath);
+  const raw = (0, import_yaml2.parse)((0, import_node_fs3.readFileSync)(absPath, "utf8")) ?? {};
   const relations = raw["_rel"] ?? {};
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
   const data = Object.fromEntries(
@@ -89,12 +92,12 @@ function createYrestStorage(filePath) {
       if (Object.keys(relations).length > 0) payload._rel = relations;
       if (routes.length > 0) payload._routes = routes;
       Object.assign(payload, data);
-      const tmp = (0, import_node_path.resolve)((0, import_node_path.dirname)(absPath), `.yrest-${(0, import_node_crypto2.randomUUID)()}.tmp`);
-      (0, import_node_fs2.writeFileSync)(tmp, (0, import_yaml2.stringify)(payload), "utf8");
-      (0, import_node_fs2.renameSync)(tmp, absPath);
+      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto2.randomUUID)()}.tmp`);
+      (0, import_node_fs3.writeFileSync)(tmp, (0, import_yaml2.stringify)(payload), "utf8");
+      (0, import_node_fs3.renameSync)(tmp, absPath);
     },
     reload() {
-      const fresh = (0, import_yaml2.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
+      const fresh = (0, import_yaml2.parse)((0, import_node_fs3.readFileSync)(absPath, "utf8")) ?? {};
       const freshRelations = fresh["_rel"] ?? {};
       const freshData = Object.fromEntries(
         Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
@@ -124,13 +127,13 @@ function createYrestStorage(filePath) {
     }
   };
 }
-var import_node_fs2, import_node_path, import_node_crypto2, import_yaml2;
+var import_node_fs3, import_node_path2, import_node_crypto2, import_yaml2;
 var init_yrestStorage = __esm({
   "src/storage/yrestStorage.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_fs2 = require("fs");
-    import_node_path = require("path");
+    import_node_fs3 = require("fs");
+    import_node_path2 = require("path");
     import_node_crypto2 = require("crypto");
     import_yaml2 = require("yaml");
     init_deepCopy();
@@ -194,7 +197,7 @@ function dedent(str) {
 
 // src/api/yrestServer.ts
 init_cjs_shims();
-var import_node_path2 = require("path");
+var import_node_path3 = require("path");
 
 // src/utils/handlers.ts
 init_cjs_shims();
@@ -237,6 +240,9 @@ init_cjs_shims();
 
 // src/router/templates/about.template.ts
 init_cjs_shims();
+var import_node_fs2 = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
 
 // src/utils/interpolate.ts
 init_cjs_shims();
@@ -286,6 +292,15 @@ function hasTemplates(value) {
 }
 
 // src/router/templates/about.template.ts
+var _dir = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+var LOGO_SRC = (() => {
+  try {
+    const buf = (0, import_node_fs2.readFileSync)((0, import_node_path.join)(_dir, "../../assets/logo-color.png"));
+    return `data:image/png;base64,${buf.toString("base64")}`;
+  } catch {
+    return "";
+  }
+})();
 var METHOD_COLOR = {
   GET: "#3fb950",
   POST: "#58a6ff",
@@ -444,6 +459,8 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
   if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   if (handlers.size > 0) modes.push(badge(`handlers \xB7 ${handlers.size}`, "#f0883e", "#f0883e18"));
+  if (options.idStrategy !== "increment")
+    modes.push(badge(`id \xB7 ${options.idStrategy}`, "#a371f7", "#a371f718"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -486,6 +503,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       ${customRoutes.map((r) => {
     const fullPath = `${base}${r.path}`;
     const tags = [];
+    if (r.error) {
+      tags.push(`<span style="color:#f85149;font-size:11px">error\xB7${r.error}</span>`);
+    }
     if (r.delay && r.delay > 0) {
       tags.push(`<span style="color:#fb923c;font-size:11px">delay\xB7${r.delay}ms</span>`);
     }
@@ -499,7 +519,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
     }
     let desc;
-    if (r.handler) {
+    if (r.error) {
+      desc = `Error injection \u2014 <code>${r.error}</code>`;
+    } else 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) {
@@ -663,7 +685,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>
+      ${LOGO_SRC ? `<img src="${LOGO_SRC}" alt="yRest" height="68" style="display:block;margin-bottom:0px" />` : `<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>
@@ -750,6 +772,10 @@ function nextId(items) {
   const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
 }
+function generateId(items, strategy) {
+  if (strategy === "uuid") return crypto.randomUUID();
+  return nextId(items);
+}
 function firstParam(value) {
   if (value === void 0) return void 0;
   return Array.isArray(value) ? value[0] : value;
@@ -839,10 +865,10 @@ function findById(items, id) {
 function findIndexById(items, id) {
   return items.findIndex((i) => String(i["id"]) === id);
 }
-function createItem(storage, resource, body) {
+function createItem(storage, resource, body, idStrategy = "increment") {
   const collection = storage.getCollection(resource) ?? [];
   const item = {
-    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    id: body["id"] !== void 0 ? body["id"] : generateId(collection, idStrategy),
     ...body
   };
   storage.setCollection(resource, [...collection, item]);
@@ -1021,7 +1047,12 @@ var CollectionRouteCommand = class {
       if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
         return reply.status(400).send({ error: "Request body must be a JSON object" });
       }
-      const item = createItem(this.storage, this.resource, req.body);
+      const item = createItem(
+        this.storage,
+        this.resource,
+        req.body,
+        this.options.idStrategy
+      );
       return reply.status(201).send(expandItems(item, req.query, this.resource, this.storage));
     });
   }
@@ -1115,6 +1146,10 @@ var CustomRouteCommand = class {
           if (route.delay && route.delay > 0) {
             await new Promise((resolve3) => setTimeout(resolve3, route.delay));
           }
+          if (route.error) {
+            const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
+            return reply.status(route.error).send(body2);
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1385,7 +1420,7 @@ function createYrestServer(options) {
   return {
     async start() {
       const storage = "data" in options && options.data !== void 0 ? createInMemoryStorage(options.data) : (await Promise.resolve().then(() => (init_yrestStorage(), yrestStorage_exports))).createYrestStorage(resolvedOptions.file);
-      const handlers = resolvedOptions.handlers ? await loadHandlers((0, import_node_path2.resolve)(resolvedOptions.handlers)) : /* @__PURE__ */ new Map();
+      const handlers = resolvedOptions.handlers ? await loadHandlers((0, import_node_path3.resolve)(resolvedOptions.handlers)) : /* @__PURE__ */ new Map();
       _inner = createYrestServerFromStorage(storage, resolvedOptions, handlers);
       await _inner.start();
     },
@@ -1412,7 +1447,8 @@ function buildOptions(opts) {
     readonly: opts.readonly ?? false,
     delay: opts.delay ?? 0,
     handlers: opts.handlers,
-    pageable: typeof pageable === "number" ? { enabled: true, limit: pageable } : pageable ? { enabled: true, limit: 10 } : { enabled: false, limit: 10 }
+    pageable: typeof pageable === "number" ? { enabled: true, limit: pageable } : pageable ? { enabled: true, limit: 10 } : { enabled: false, limit: 10 },
+    idStrategy: "increment"
   };
 }
 function createInMemoryStorage(data) {
@@ -1496,7 +1532,14 @@ var yrestOptionsSchema = import_zod.z.object({
   pageable: import_zod.z.union([import_zod.z.boolean(), import_zod.z.coerce.number().int().positive()]).default(false).transform((v) => ({
     enabled: v !== false,
     limit: v === false || v === true ? 10 : v
-  }))
+  })),
+  /**
+   * Strategy used to generate `id` values for new items when no `id` is provided in the body.
+   *
+   * - `"increment"` (default) — next integer above the current max id in the collection.
+   * - `"uuid"` — a random UUID v4 string (`crypto.randomUUID()`).
+   */
+  idStrategy: import_zod.z.enum(["increment", "uuid"]).default("increment")
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -35,13 +35,13 @@ var yrestStorage_exports = {};
 __export(yrestStorage_exports, {
   createYrestStorage: () => createYrestStorage
 });
-import { readFileSync, writeFileSync, renameSync } from "fs";
-import { resolve, dirname } from "path";
+import { readFileSync as readFileSync2, writeFileSync, renameSync } from "fs";
+import { resolve, dirname as dirname2 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 import { parse as parse2, stringify } from "yaml";
 function createYrestStorage(filePath) {
   const absPath = resolve(filePath);
-  const raw = parse2(readFileSync(absPath, "utf8")) ?? {};
+  const raw = parse2(readFileSync2(absPath, "utf8")) ?? {};
   const relations = raw["_rel"] ?? {};
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
   const data = Object.fromEntries(
@@ -73,12 +73,12 @@ function createYrestStorage(filePath) {
       if (Object.keys(relations).length > 0) payload._rel = relations;
       if (routes.length > 0) payload._routes = routes;
       Object.assign(payload, data);
-      const tmp = resolve(dirname(absPath), `.yrest-${randomUUID2()}.tmp`);
+      const tmp = resolve(dirname2(absPath), `.yrest-${randomUUID2()}.tmp`);
       writeFileSync(tmp, stringify(payload), "utf8");
       renameSync(tmp, absPath);
     },
     reload() {
-      const fresh = parse2(readFileSync(absPath, "utf8")) ?? {};
+      const fresh = parse2(readFileSync2(absPath, "utf8")) ?? {};
       const freshRelations = fresh["_rel"] ?? {};
       const freshData = Object.fromEntries(
         Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
@@ -206,6 +206,9 @@ init_esm_shims();
 
 // src/router/templates/about.template.ts
 init_esm_shims();
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/utils/interpolate.ts
 init_esm_shims();
@@ -255,6 +258,15 @@ function hasTemplates(value) {
 }
 
 // src/router/templates/about.template.ts
+var _dir = dirname(fileURLToPath2(import.meta.url));
+var LOGO_SRC = (() => {
+  try {
+    const buf = readFileSync(join(_dir, "../../assets/logo-color.png"));
+    return `data:image/png;base64,${buf.toString("base64")}`;
+  } catch {
+    return "";
+  }
+})();
 var METHOD_COLOR = {
   GET: "#3fb950",
   POST: "#58a6ff",
@@ -413,6 +425,8 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
   if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   if (handlers.size > 0) modes.push(badge(`handlers \xB7 ${handlers.size}`, "#f0883e", "#f0883e18"));
+  if (options.idStrategy !== "increment")
+    modes.push(badge(`id \xB7 ${options.idStrategy}`, "#a371f7", "#a371f718"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -455,6 +469,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       ${customRoutes.map((r) => {
     const fullPath = `${base}${r.path}`;
     const tags = [];
+    if (r.error) {
+      tags.push(`<span style="color:#f85149;font-size:11px">error\xB7${r.error}</span>`);
+    }
     if (r.delay && r.delay > 0) {
       tags.push(`<span style="color:#fb923c;font-size:11px">delay\xB7${r.delay}ms</span>`);
     }
@@ -468,7 +485,9 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
     }
     let desc;
-    if (r.handler) {
+    if (r.error) {
+      desc = `Error injection \u2014 <code>${r.error}</code>`;
+    } else 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) {
@@ -632,7 +651,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>
+      ${LOGO_SRC ? `<img src="${LOGO_SRC}" alt="yRest" height="68" style="display:block;margin-bottom:0px" />` : `<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>
@@ -719,6 +738,10 @@ function nextId(items) {
   const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
 }
+function generateId(items, strategy) {
+  if (strategy === "uuid") return crypto.randomUUID();
+  return nextId(items);
+}
 function firstParam(value) {
   if (value === void 0) return void 0;
   return Array.isArray(value) ? value[0] : value;
@@ -808,10 +831,10 @@ function findById(items, id) {
 function findIndexById(items, id) {
   return items.findIndex((i) => String(i["id"]) === id);
 }
-function createItem(storage, resource, body) {
+function createItem(storage, resource, body, idStrategy = "increment") {
   const collection = storage.getCollection(resource) ?? [];
   const item = {
-    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    id: body["id"] !== void 0 ? body["id"] : generateId(collection, idStrategy),
     ...body
   };
   storage.setCollection(resource, [...collection, item]);
@@ -990,7 +1013,12 @@ var CollectionRouteCommand = class {
       if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
         return reply.status(400).send({ error: "Request body must be a JSON object" });
       }
-      const item = createItem(this.storage, this.resource, req.body);
+      const item = createItem(
+        this.storage,
+        this.resource,
+        req.body,
+        this.options.idStrategy
+      );
       return reply.status(201).send(expandItems(item, req.query, this.resource, this.storage));
     });
   }
@@ -1084,6 +1112,10 @@ var CustomRouteCommand = class {
           if (route.delay && route.delay > 0) {
             await new Promise((resolve3) => setTimeout(resolve3, route.delay));
           }
+          if (route.error) {
+            const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
+            return reply.status(route.error).send(body2);
+          }
           for (const [key, value] of Object.entries(headers)) {
             reply.header(key, value);
           }
@@ -1381,7 +1413,8 @@ function buildOptions(opts) {
     readonly: opts.readonly ?? false,
     delay: opts.delay ?? 0,
     handlers: opts.handlers,
-    pageable: typeof pageable === "number" ? { enabled: true, limit: pageable } : pageable ? { enabled: true, limit: 10 } : { enabled: false, limit: 10 }
+    pageable: typeof pageable === "number" ? { enabled: true, limit: pageable } : pageable ? { enabled: true, limit: 10 } : { enabled: false, limit: 10 },
+    idStrategy: "increment"
   };
 }
 function createInMemoryStorage(data) {
@@ -1465,7 +1498,14 @@ var yrestOptionsSchema = z.object({
   pageable: z.union([z.boolean(), z.coerce.number().int().positive()]).default(false).transform((v) => ({
     enabled: v !== false,
     limit: v === false || v === true ? 10 : v
-  }))
+  })),
+  /**
+   * Strategy used to generate `id` values for new items when no `id` is provided in the body.
+   *
+   * - `"increment"` (default) — next integer above the current max id in the collection.
+   * - `"uuid"` — a random UUID v4 string (`crypto.randomUUID()`).
+   */
+  idStrategy: z.enum(["increment", "uuid"]).default("increment")
 });
 export {
   createServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yrest/cli",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -52,7 +52,8 @@
     "yrest": "./dist/cli/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "assets"
   ],
   "scripts": {
     "build": "tsup",
@@ -64,7 +65,8 @@
     "lint:fix": "eslint src tests --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepublishOnly": "npm run test:run && npm run build"
+    "prepublishOnly": "npm run test:run && npm run build",
+    "version": "node scripts/update-version-badge.mjs && git add README.md"
   },
   "dependencies": {
     "@fastify/cors": "^10.0.0",
@@ -86,5 +88,10 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "socket": {
+    "allow": {
+      "filesystem": true
+    }
   }
 }