@aggiovato/yrest 0.2.2 → 0.3.0

package/dist/cli/index.js

@@ -23,8 +23,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// node_modules/tsup/assets/cjs_shims.js
+var 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;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
 // src/cli/index.ts
 var import_commander = require("commander");
+var import_module = require("module");
 
 // src/cli/commands/init.ts
 var import_node_fs = require("fs");
@@ -101,6 +106,7 @@ host: localhost     # Host to bind
 # readonly: false   # Block write operations (POST, PUT, PATCH, DELETE)
 # delay: 0          # Simulated network latency in milliseconds
 # pageable: false   # Wrap GET collections in { data, pagination }. Use true (limit 10) or a number
+# snapshot: false   # Save initial db state and expose /_snapshot endpoints (GET / POST save / POST reset)
 `;
 function registerInit(program2) {
   program2.command("init").description("Create a sample db.yml and yrest.config.yml in the current directory").option("-f, --file <name>", "Output filename", "db.yml").option("-s, --sample <name>", `Sample data to use (${SAMPLES.join(", ")})`, "basic").action((flags) => {
@@ -133,6 +139,11 @@ var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var import_node_crypto = require("crypto");
 var import_yaml = require("yaml");
+function deepCopyData(source) {
+  return Object.fromEntries(
+    Object.entries(source).map(([k, v]) => [k, v.map((item) => ({ ...item }))])
+  );
+}
 function createYamlStorage(filePath) {
   const absPath = (0, import_node_path2.resolve)(filePath);
   const raw = (0, import_yaml.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
@@ -140,6 +151,11 @@ function createYamlStorage(filePath) {
   const data = Object.fromEntries(
     Object.entries(raw).filter(([key]) => key !== "_rel")
   );
+  let snapshot = {
+    data: deepCopyData(data),
+    relations: { ...relations },
+    savedAt: /* @__PURE__ */ new Date()
+  };
   return {
     getData() {
       return data;
@@ -169,6 +185,24 @@ function createYamlStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    saveSnapshot() {
+      snapshot = {
+        data: deepCopyData(data),
+        relations: { ...relations },
+        savedAt: /* @__PURE__ */ new Date()
+      };
+    },
+    resetToSnapshot() {
+      const snap = deepCopyData(snapshot.data);
+      for (const key of Object.keys(data)) delete data[key];
+      Object.assign(data, snap);
+      for (const key of Object.keys(relations)) delete relations[key];
+      Object.assign(relations, { ...snapshot.relations });
+      this.persist();
     }
   };
 }
@@ -334,6 +368,9 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
     return expandItems(result, req.query, resource, storage);
   });
   server.post(base, (req, reply) => {
+    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(storage, resource, req.body);
     return reply.status(201).send(expandItems(item, req.query, resource, storage));
   });
@@ -347,11 +384,17 @@ var registerItemRoutes = (server, storage, resource, base) => {
     return expandItems(item, req.query, resource, storage);
   });
   server.put(`${base}/:id`, (req, reply) => {
+    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 = replaceItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
   });
   server.patch(`${base}/:id`, (req, reply) => {
+    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 = patchItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
@@ -367,7 +410,9 @@ var registerItemRoutes = (server, storage, resource, base) => {
 var registerNestedRoutes = (server, storage, relations, base) => {
   for (const [child, fields] of Object.entries(relations)) {
     for (const [field, parent] of Object.entries(fields)) {
-      server.get(`${base}/${parent}/:id/${child}`, (req, reply) => {
+      const collectionPath = `${base}/${parent}/:id/${child}`;
+      const itemPath = `${base}/${parent}/:id/${child}/:childId`;
+      server.get(collectionPath, (req, reply) => {
         const parentCollection = storage.getCollection(parent) ?? [];
         const parentItem = findById(parentCollection, req.params.id);
         if (!parentItem) return reply.status(404).send({ error: "Not found" });
@@ -376,6 +421,16 @@ var registerNestedRoutes = (server, storage, relations, base) => {
         );
         return children;
       });
+      server.get(itemPath, (req, reply) => {
+        const parentCollection = storage.getCollection(parent) ?? [];
+        const parentItem = findById(parentCollection, req.params.id);
+        if (!parentItem) return reply.status(404).send({ error: "Not found" });
+        const childItem = (storage.getCollection(child) ?? []).find(
+          (item) => String(item[field]) === req.params.id && String(item["id"]) === req.params.childId
+        );
+        if (!childItem) return reply.status(404).send({ error: "Not found" });
+        return childItem;
+      });
     }
   }
 };
@@ -500,6 +555,14 @@ curl ${host}${base}/${parent}/1/${child}`);
     examples.push(`# Pageable envelope
 curl "${host}${base}/${firstCol}?_page=2"`);
   }
+  if (options.snapshot) {
+    examples.push(
+      `# Snapshot endpoints
+curl ${host}/_snapshot
+curl -X POST ${host}/_snapshot/save
+curl -X POST ${host}/_snapshot/reset`
+    );
+  }
   const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
   return `<pre>${highlighted}</pre>`;
 }
@@ -514,6 +577,7 @@ function generateAboutHtml(storage, options) {
   if (options.delay > 0) modes.push(badge(`delay \xB7 ${options.delay}ms`, "#fb923c", "#fb923c18"));
   if (options.pageable.enabled)
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
+  if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -533,6 +597,18 @@ function generateAboutHtml(storage, options) {
     </summary>
     <table><tbody>${nestedRows.join("")}</tbody></table>
   </details>` : "";
+  const snapshotAccordion = options.snapshot ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">/_snapshot</span>
+      <span class="route-count">3 routes</span>
+    </summary>
+    <table><tbody>
+      ${endpointRow("GET", "/_snapshot", "Returns metadata of the current snapshot: <code>savedAt</code> and item counts per collection.")}
+      ${endpointRow("POST", "/_snapshot/save", "Replaces the stored snapshot with the current database state.")}
+      ${endpointRow("POST", "/_snapshot/reset", "Restores the database to the last saved snapshot and persists to disk.")}
+    </tbody></table>
+  </details>` : "";
   const paginationDesc = options.pageable.enabled ? `Pageable mode active \u2014 default limit <code>${options.pageable.limit}</code>. Response wrapped in <code>{ data, pagination }</code>.` : `Returns the requested slice. <code>X-Total-Count</code> header reflects the total before pagination.`;
   return `<!DOCTYPE html>
 <html lang="en">
@@ -681,6 +757,7 @@ function generateAboutHtml(storage, options) {
     <div class="endpoints-grid">
       ${accordions}
       ${nestedAccordion}
+      ${snapshotAccordion}
     </div>
 
     <h2>Query Parameters</h2>
@@ -715,11 +792,51 @@ function registerAboutRoute(server, storage, options) {
   });
 }
 
+// src/router/routes/snapshot.routes.ts
+function registerSnapshotRoutes(server, storage) {
+  server.get("/_snapshot", (_req, reply) => {
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/save", (_req, reply) => {
+    storage.saveSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Snapshot saved",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/reset", (_req, reply) => {
+    storage.resetToSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Database restored to snapshot",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+}
+
 // src/server/createServer.ts
 var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 async function createServer(storage, options) {
   const server = (0, import_fastify.default)();
   await server.register(import_cors.default);
+  server.setErrorHandler((err, _req, reply) => {
+    const status = err.statusCode ?? 500;
+    const message = status < 500 ? err.message || "Request error" : "Internal server error";
+    reply.status(status).send({ error: message });
+  });
   if (options.readonly) {
     server.addHook("onRequest", (_req, reply, done) => {
       if (MUTATING_METHODS.has(_req.method)) {
@@ -734,6 +851,7 @@ async function createServer(storage, options) {
     });
   }
   registerAboutRoute(server, storage, options);
+  if (options.snapshot) registerSnapshotRoutes(server, storage);
   registerResourceRoutes(server, storage, options);
   return server;
 }
@@ -754,6 +872,11 @@ var serverOptionsSchema = import_zod.z.object({
   base: import_zod.z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v),
   /** When `true`, the server reloads the YAML file automatically on disk changes. */
   watch: import_zod.z.boolean().default(false),
+  /**
+   * When `true`, saves a snapshot of the initial database state on startup.
+   * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+   */
+  snapshot: import_zod.z.boolean().default(false),
   /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
   readonly: import_zod.z.boolean().default(false),
   /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
@@ -786,6 +909,9 @@ function registerServe(program2) {
   ).option(
     "--pageable [limit]",
     "Wrap GET collection responses in { data, pagination } envelope. Optionally set default page size (default: 10)"
+  ).option(
+    "--snapshot",
+    "Save a snapshot of the initial database state and expose /_snapshot endpoints"
   ).action(async (file, flags, cmd) => {
     const fileConfig = loadConfigFile((0, import_node_path3.join)(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
@@ -798,7 +924,14 @@ function registerServe(program2) {
       ...cliOverrides
     };
     const options = serverOptionsSchema.parse(merged);
-    const storage = createYamlStorage(options.file);
+    let storage;
+    try {
+      storage = createYamlStorage(options.file);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`Error: cannot load "${options.file}" \u2014 ${msg}`);
+      process.exit(1);
+    }
     const server = await createServer(storage, options);
     await server.listen({ port: options.port, host: options.host });
     const collections = Object.keys(storage.getData());
@@ -811,6 +944,8 @@ yrest running at http://${options.host}:${options.port}`);
       console.log(
         `[pageable] responses wrapped in { data, pagination } (limit: ${options.pageable.limit})`
       );
+    if (options.snapshot)
+      console.log("[snapshot] /_snapshot endpoints enabled \u2014 GET / POST save / POST reset");
     console.log(`
 Resources (base: ${baseLabel}):`);
     for (const name of collections) {
@@ -827,8 +962,9 @@ Resources (base: ${baseLabel}):`);
           try {
             storage.reload();
             console.log(`[watch] reloaded ${options.file}`);
-          } catch {
-            console.error(`[watch] failed to reload ${options.file} \u2014 check YAML syntax`);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[watch] failed to reload ${options.file} \u2014 ${msg}`);
           }
         }, 100);
       });
@@ -839,7 +975,9 @@ Resources (base: ${baseLabel}):`);
 }
 
 // src/cli/index.ts
-import_commander.program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version("0.1.0");
+var require2 = (0, import_module.createRequire)(importMetaUrl);
+var { version } = require2("../../package.json");
+import_commander.program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version(version);
 registerInit(import_commander.program);
 registerServe(import_commander.program);
 import_commander.program.parse();

package/dist/cli/index.mjs

@@ -2,6 +2,7 @@
 
 // src/cli/index.ts
 import { program } from "commander";
+import { createRequire } from "module";
 
 // src/cli/commands/init.ts
 import { existsSync, writeFileSync } from "fs";
@@ -78,6 +79,7 @@ host: localhost     # Host to bind
 # readonly: false   # Block write operations (POST, PUT, PATCH, DELETE)
 # delay: 0          # Simulated network latency in milliseconds
 # pageable: false   # Wrap GET collections in { data, pagination }. Use true (limit 10) or a number
+# snapshot: false   # Save initial db state and expose /_snapshot endpoints (GET / POST save / POST reset)
 `;
 function registerInit(program2) {
   program2.command("init").description("Create a sample db.yml and yrest.config.yml in the current directory").option("-f, --file <name>", "Output filename", "db.yml").option("-s, --sample <name>", `Sample data to use (${SAMPLES.join(", ")})`, "basic").action((flags) => {
@@ -110,6 +112,11 @@ import { readFileSync, writeFileSync as writeFileSync2, renameSync } from "fs";
 import { resolve as resolve2, dirname } from "path";
 import { randomUUID } from "crypto";
 import { parse, stringify } from "yaml";
+function deepCopyData(source) {
+  return Object.fromEntries(
+    Object.entries(source).map(([k, v]) => [k, v.map((item) => ({ ...item }))])
+  );
+}
 function createYamlStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
@@ -117,6 +124,11 @@ function createYamlStorage(filePath) {
   const data = Object.fromEntries(
     Object.entries(raw).filter(([key]) => key !== "_rel")
   );
+  let snapshot = {
+    data: deepCopyData(data),
+    relations: { ...relations },
+    savedAt: /* @__PURE__ */ new Date()
+  };
   return {
     getData() {
       return data;
@@ -146,6 +158,24 @@ function createYamlStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    saveSnapshot() {
+      snapshot = {
+        data: deepCopyData(data),
+        relations: { ...relations },
+        savedAt: /* @__PURE__ */ new Date()
+      };
+    },
+    resetToSnapshot() {
+      const snap = deepCopyData(snapshot.data);
+      for (const key of Object.keys(data)) delete data[key];
+      Object.assign(data, snap);
+      for (const key of Object.keys(relations)) delete relations[key];
+      Object.assign(relations, { ...snapshot.relations });
+      this.persist();
     }
   };
 }
@@ -311,6 +341,9 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
     return expandItems(result, req.query, resource, storage);
   });
   server.post(base, (req, reply) => {
+    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(storage, resource, req.body);
     return reply.status(201).send(expandItems(item, req.query, resource, storage));
   });
@@ -324,11 +357,17 @@ var registerItemRoutes = (server, storage, resource, base) => {
     return expandItems(item, req.query, resource, storage);
   });
   server.put(`${base}/:id`, (req, reply) => {
+    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 = replaceItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
   });
   server.patch(`${base}/:id`, (req, reply) => {
+    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 = patchItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
@@ -344,7 +383,9 @@ var registerItemRoutes = (server, storage, resource, base) => {
 var registerNestedRoutes = (server, storage, relations, base) => {
   for (const [child, fields] of Object.entries(relations)) {
     for (const [field, parent] of Object.entries(fields)) {
-      server.get(`${base}/${parent}/:id/${child}`, (req, reply) => {
+      const collectionPath = `${base}/${parent}/:id/${child}`;
+      const itemPath = `${base}/${parent}/:id/${child}/:childId`;
+      server.get(collectionPath, (req, reply) => {
         const parentCollection = storage.getCollection(parent) ?? [];
         const parentItem = findById(parentCollection, req.params.id);
         if (!parentItem) return reply.status(404).send({ error: "Not found" });
@@ -353,6 +394,16 @@ var registerNestedRoutes = (server, storage, relations, base) => {
         );
         return children;
       });
+      server.get(itemPath, (req, reply) => {
+        const parentCollection = storage.getCollection(parent) ?? [];
+        const parentItem = findById(parentCollection, req.params.id);
+        if (!parentItem) return reply.status(404).send({ error: "Not found" });
+        const childItem = (storage.getCollection(child) ?? []).find(
+          (item) => String(item[field]) === req.params.id && String(item["id"]) === req.params.childId
+        );
+        if (!childItem) return reply.status(404).send({ error: "Not found" });
+        return childItem;
+      });
     }
   }
 };
@@ -477,6 +528,14 @@ curl ${host}${base}/${parent}/1/${child}`);
     examples.push(`# Pageable envelope
 curl "${host}${base}/${firstCol}?_page=2"`);
   }
+  if (options.snapshot) {
+    examples.push(
+      `# Snapshot endpoints
+curl ${host}/_snapshot
+curl -X POST ${host}/_snapshot/save
+curl -X POST ${host}/_snapshot/reset`
+    );
+  }
   const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
   return `<pre>${highlighted}</pre>`;
 }
@@ -491,6 +550,7 @@ function generateAboutHtml(storage, options) {
   if (options.delay > 0) modes.push(badge(`delay \xB7 ${options.delay}ms`, "#fb923c", "#fb923c18"));
   if (options.pageable.enabled)
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
+  if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -510,6 +570,18 @@ function generateAboutHtml(storage, options) {
     </summary>
     <table><tbody>${nestedRows.join("")}</tbody></table>
   </details>` : "";
+  const snapshotAccordion = options.snapshot ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">/_snapshot</span>
+      <span class="route-count">3 routes</span>
+    </summary>
+    <table><tbody>
+      ${endpointRow("GET", "/_snapshot", "Returns metadata of the current snapshot: <code>savedAt</code> and item counts per collection.")}
+      ${endpointRow("POST", "/_snapshot/save", "Replaces the stored snapshot with the current database state.")}
+      ${endpointRow("POST", "/_snapshot/reset", "Restores the database to the last saved snapshot and persists to disk.")}
+    </tbody></table>
+  </details>` : "";
   const paginationDesc = options.pageable.enabled ? `Pageable mode active \u2014 default limit <code>${options.pageable.limit}</code>. Response wrapped in <code>{ data, pagination }</code>.` : `Returns the requested slice. <code>X-Total-Count</code> header reflects the total before pagination.`;
   return `<!DOCTYPE html>
 <html lang="en">
@@ -658,6 +730,7 @@ function generateAboutHtml(storage, options) {
     <div class="endpoints-grid">
       ${accordions}
       ${nestedAccordion}
+      ${snapshotAccordion}
     </div>
 
     <h2>Query Parameters</h2>
@@ -692,11 +765,51 @@ function registerAboutRoute(server, storage, options) {
   });
 }
 
+// src/router/routes/snapshot.routes.ts
+function registerSnapshotRoutes(server, storage) {
+  server.get("/_snapshot", (_req, reply) => {
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/save", (_req, reply) => {
+    storage.saveSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Snapshot saved",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/reset", (_req, reply) => {
+    storage.resetToSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Database restored to snapshot",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+}
+
 // src/server/createServer.ts
 var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 async function createServer(storage, options) {
   const server = Fastify();
   await server.register(cors);
+  server.setErrorHandler((err, _req, reply) => {
+    const status = err.statusCode ?? 500;
+    const message = status < 500 ? err.message || "Request error" : "Internal server error";
+    reply.status(status).send({ error: message });
+  });
   if (options.readonly) {
     server.addHook("onRequest", (_req, reply, done) => {
       if (MUTATING_METHODS.has(_req.method)) {
@@ -711,6 +824,7 @@ async function createServer(storage, options) {
     });
   }
   registerAboutRoute(server, storage, options);
+  if (options.snapshot) registerSnapshotRoutes(server, storage);
   registerResourceRoutes(server, storage, options);
   return server;
 }
@@ -731,6 +845,11 @@ var serverOptionsSchema = z.object({
   base: z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v),
   /** When `true`, the server reloads the YAML file automatically on disk changes. */
   watch: z.boolean().default(false),
+  /**
+   * When `true`, saves a snapshot of the initial database state on startup.
+   * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+   */
+  snapshot: z.boolean().default(false),
   /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
   readonly: z.boolean().default(false),
   /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
@@ -763,6 +882,9 @@ function registerServe(program2) {
   ).option(
     "--pageable [limit]",
     "Wrap GET collection responses in { data, pagination } envelope. Optionally set default page size (default: 10)"
+  ).option(
+    "--snapshot",
+    "Save a snapshot of the initial database state and expose /_snapshot endpoints"
   ).action(async (file, flags, cmd) => {
     const fileConfig = loadConfigFile(join(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
@@ -775,7 +897,14 @@ function registerServe(program2) {
       ...cliOverrides
     };
     const options = serverOptionsSchema.parse(merged);
-    const storage = createYamlStorage(options.file);
+    let storage;
+    try {
+      storage = createYamlStorage(options.file);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`Error: cannot load "${options.file}" \u2014 ${msg}`);
+      process.exit(1);
+    }
     const server = await createServer(storage, options);
     await server.listen({ port: options.port, host: options.host });
     const collections = Object.keys(storage.getData());
@@ -788,6 +917,8 @@ yrest running at http://${options.host}:${options.port}`);
       console.log(
         `[pageable] responses wrapped in { data, pagination } (limit: ${options.pageable.limit})`
       );
+    if (options.snapshot)
+      console.log("[snapshot] /_snapshot endpoints enabled \u2014 GET / POST save / POST reset");
     console.log(`
 Resources (base: ${baseLabel}):`);
     for (const name of collections) {
@@ -804,8 +935,9 @@ Resources (base: ${baseLabel}):`);
           try {
             storage.reload();
             console.log(`[watch] reloaded ${options.file}`);
-          } catch {
-            console.error(`[watch] failed to reload ${options.file} \u2014 check YAML syntax`);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[watch] failed to reload ${options.file} \u2014 ${msg}`);
           }
         }, 100);
       });
@@ -816,7 +948,9 @@ Resources (base: ${baseLabel}):`);
 }
 
 // src/cli/index.ts
-program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version("0.1.0");
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../../package.json");
+program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version(version);
 registerInit(program);
 registerServe(program);
 program.parse();

package/dist/index.d.mts

@@ -67,16 +67,28 @@ interface YamlStorage {
      * @throws {Error} If the file cannot be read or the YAML is malformed.
      */
     reload(): void;
+    /**
+     * Returns the saved snapshot: a frozen copy of `data` and `relations` taken
+     * at the last call to {@link saveSnapshot} (or at construction time).
+     */
+    getSnapshot(): {
+        data: Data;
+        relations: Relations;
+        savedAt: Date;
+    };
+    /**
+     * Replaces the stored snapshot with a deep copy of the current in-memory state.
+     * Future calls to {@link resetToSnapshot} will restore to this point.
+     */
+    saveSnapshot(): void;
+    /**
+     * Restores the in-memory state to the last saved snapshot and persists to disk.
+     * Mutates `data` and `relations` in place so existing references stay valid.
+     *
+     * @throws {Error} If the filesystem write fails.
+     */
+    resetToSnapshot(): void;
 }
-/**
- * Creates a {@link YamlStorage} instance backed by the given YAML file.
- *
- * The file is read and parsed eagerly on construction. The `_rel` key is
- * extracted as relational metadata; all other top-level keys become collections.
- *
- * @param filePath - Relative or absolute path to the YAML database file.
- * @throws {Error} If the file cannot be read or its YAML is invalid.
- */
 declare function createYamlStorage(filePath: string): YamlStorage;
 
 /**
@@ -99,6 +111,11 @@ declare const serverOptionsSchema: z.ZodObject<{
     base: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
     /** When `true`, the server reloads the YAML file automatically on disk changes. */
     watch: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * When `true`, saves a snapshot of the initial database state on startup.
+     * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+     */
+    snapshot: z.ZodDefault<z.ZodBoolean>;
     /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
     readonly: z.ZodDefault<z.ZodBoolean>;
     /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
@@ -117,6 +134,7 @@ declare const serverOptionsSchema: z.ZodObject<{
     host: string;
     base: string;
     watch: boolean;
+    snapshot: boolean;
     readonly: boolean;
     delay: number;
     pageable: {
@@ -129,6 +147,7 @@ declare const serverOptionsSchema: z.ZodObject<{
     host?: string | undefined;
     base?: string | undefined;
     watch?: boolean | undefined;
+    snapshot?: boolean | undefined;
     readonly?: boolean | undefined;
     delay?: number | undefined;
     pageable?: number | boolean | undefined;

package/dist/index.d.ts

@@ -67,16 +67,28 @@ interface YamlStorage {
      * @throws {Error} If the file cannot be read or the YAML is malformed.
      */
     reload(): void;
+    /**
+     * Returns the saved snapshot: a frozen copy of `data` and `relations` taken
+     * at the last call to {@link saveSnapshot} (or at construction time).
+     */
+    getSnapshot(): {
+        data: Data;
+        relations: Relations;
+        savedAt: Date;
+    };
+    /**
+     * Replaces the stored snapshot with a deep copy of the current in-memory state.
+     * Future calls to {@link resetToSnapshot} will restore to this point.
+     */
+    saveSnapshot(): void;
+    /**
+     * Restores the in-memory state to the last saved snapshot and persists to disk.
+     * Mutates `data` and `relations` in place so existing references stay valid.
+     *
+     * @throws {Error} If the filesystem write fails.
+     */
+    resetToSnapshot(): void;
 }
-/**
- * Creates a {@link YamlStorage} instance backed by the given YAML file.
- *
- * The file is read and parsed eagerly on construction. The `_rel` key is
- * extracted as relational metadata; all other top-level keys become collections.
- *
- * @param filePath - Relative or absolute path to the YAML database file.
- * @throws {Error} If the file cannot be read or its YAML is invalid.
- */
 declare function createYamlStorage(filePath: string): YamlStorage;
 
 /**
@@ -99,6 +111,11 @@ declare const serverOptionsSchema: z.ZodObject<{
     base: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
     /** When `true`, the server reloads the YAML file automatically on disk changes. */
     watch: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * When `true`, saves a snapshot of the initial database state on startup.
+     * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+     */
+    snapshot: z.ZodDefault<z.ZodBoolean>;
     /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
     readonly: z.ZodDefault<z.ZodBoolean>;
     /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
@@ -117,6 +134,7 @@ declare const serverOptionsSchema: z.ZodObject<{
     host: string;
     base: string;
     watch: boolean;
+    snapshot: boolean;
     readonly: boolean;
     delay: number;
     pageable: {
@@ -129,6 +147,7 @@ declare const serverOptionsSchema: z.ZodObject<{
     host?: string | undefined;
     base?: string | undefined;
     watch?: boolean | undefined;
+    snapshot?: boolean | undefined;
     readonly?: boolean | undefined;
     delay?: number | undefined;
     pageable?: number | boolean | undefined;

package/dist/index.js

@@ -41,6 +41,11 @@ var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_crypto = require("crypto");
 var import_yaml = require("yaml");
+function deepCopyData(source) {
+  return Object.fromEntries(
+    Object.entries(source).map(([k, v]) => [k, v.map((item) => ({ ...item }))])
+  );
+}
 function createYamlStorage(filePath) {
   const absPath = (0, import_node_path.resolve)(filePath);
   const raw = (0, import_yaml.parse)((0, import_node_fs.readFileSync)(absPath, "utf8")) ?? {};
@@ -48,6 +53,11 @@ function createYamlStorage(filePath) {
   const data = Object.fromEntries(
     Object.entries(raw).filter(([key]) => key !== "_rel")
   );
+  let snapshot = {
+    data: deepCopyData(data),
+    relations: { ...relations },
+    savedAt: /* @__PURE__ */ new Date()
+  };
   return {
     getData() {
       return data;
@@ -77,6 +87,24 @@ function createYamlStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    saveSnapshot() {
+      snapshot = {
+        data: deepCopyData(data),
+        relations: { ...relations },
+        savedAt: /* @__PURE__ */ new Date()
+      };
+    },
+    resetToSnapshot() {
+      const snap = deepCopyData(snapshot.data);
+      for (const key of Object.keys(data)) delete data[key];
+      Object.assign(data, snap);
+      for (const key of Object.keys(relations)) delete relations[key];
+      Object.assign(relations, { ...snapshot.relations });
+      this.persist();
     }
   };
 }
@@ -242,6 +270,9 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
     return expandItems(result, req.query, resource, storage);
   });
   server.post(base, (req, reply) => {
+    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(storage, resource, req.body);
     return reply.status(201).send(expandItems(item, req.query, resource, storage));
   });
@@ -255,11 +286,17 @@ var registerItemRoutes = (server, storage, resource, base) => {
     return expandItems(item, req.query, resource, storage);
   });
   server.put(`${base}/:id`, (req, reply) => {
+    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 = replaceItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
   });
   server.patch(`${base}/:id`, (req, reply) => {
+    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 = patchItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
@@ -275,7 +312,9 @@ var registerItemRoutes = (server, storage, resource, base) => {
 var registerNestedRoutes = (server, storage, relations, base) => {
   for (const [child, fields] of Object.entries(relations)) {
     for (const [field, parent] of Object.entries(fields)) {
-      server.get(`${base}/${parent}/:id/${child}`, (req, reply) => {
+      const collectionPath = `${base}/${parent}/:id/${child}`;
+      const itemPath = `${base}/${parent}/:id/${child}/:childId`;
+      server.get(collectionPath, (req, reply) => {
         const parentCollection = storage.getCollection(parent) ?? [];
         const parentItem = findById(parentCollection, req.params.id);
         if (!parentItem) return reply.status(404).send({ error: "Not found" });
@@ -284,6 +323,16 @@ var registerNestedRoutes = (server, storage, relations, base) => {
         );
         return children;
       });
+      server.get(itemPath, (req, reply) => {
+        const parentCollection = storage.getCollection(parent) ?? [];
+        const parentItem = findById(parentCollection, req.params.id);
+        if (!parentItem) return reply.status(404).send({ error: "Not found" });
+        const childItem = (storage.getCollection(child) ?? []).find(
+          (item) => String(item[field]) === req.params.id && String(item["id"]) === req.params.childId
+        );
+        if (!childItem) return reply.status(404).send({ error: "Not found" });
+        return childItem;
+      });
     }
   }
 };
@@ -408,6 +457,14 @@ curl ${host}${base}/${parent}/1/${child}`);
     examples.push(`# Pageable envelope
 curl "${host}${base}/${firstCol}?_page=2"`);
   }
+  if (options.snapshot) {
+    examples.push(
+      `# Snapshot endpoints
+curl ${host}/_snapshot
+curl -X POST ${host}/_snapshot/save
+curl -X POST ${host}/_snapshot/reset`
+    );
+  }
   const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
   return `<pre>${highlighted}</pre>`;
 }
@@ -422,6 +479,7 @@ function generateAboutHtml(storage, options) {
   if (options.delay > 0) modes.push(badge(`delay \xB7 ${options.delay}ms`, "#fb923c", "#fb923c18"));
   if (options.pageable.enabled)
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
+  if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -441,6 +499,18 @@ function generateAboutHtml(storage, options) {
     </summary>
     <table><tbody>${nestedRows.join("")}</tbody></table>
   </details>` : "";
+  const snapshotAccordion = options.snapshot ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">/_snapshot</span>
+      <span class="route-count">3 routes</span>
+    </summary>
+    <table><tbody>
+      ${endpointRow("GET", "/_snapshot", "Returns metadata of the current snapshot: <code>savedAt</code> and item counts per collection.")}
+      ${endpointRow("POST", "/_snapshot/save", "Replaces the stored snapshot with the current database state.")}
+      ${endpointRow("POST", "/_snapshot/reset", "Restores the database to the last saved snapshot and persists to disk.")}
+    </tbody></table>
+  </details>` : "";
   const paginationDesc = options.pageable.enabled ? `Pageable mode active \u2014 default limit <code>${options.pageable.limit}</code>. Response wrapped in <code>{ data, pagination }</code>.` : `Returns the requested slice. <code>X-Total-Count</code> header reflects the total before pagination.`;
   return `<!DOCTYPE html>
 <html lang="en">
@@ -589,6 +659,7 @@ function generateAboutHtml(storage, options) {
     <div class="endpoints-grid">
       ${accordions}
       ${nestedAccordion}
+      ${snapshotAccordion}
     </div>
 
     <h2>Query Parameters</h2>
@@ -623,11 +694,51 @@ function registerAboutRoute(server, storage, options) {
   });
 }
 
+// src/router/routes/snapshot.routes.ts
+function registerSnapshotRoutes(server, storage) {
+  server.get("/_snapshot", (_req, reply) => {
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/save", (_req, reply) => {
+    storage.saveSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Snapshot saved",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/reset", (_req, reply) => {
+    storage.resetToSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Database restored to snapshot",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+}
+
 // src/server/createServer.ts
 var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 async function createServer(storage, options) {
   const server = (0, import_fastify.default)();
   await server.register(import_cors.default);
+  server.setErrorHandler((err, _req, reply) => {
+    const status = err.statusCode ?? 500;
+    const message = status < 500 ? err.message || "Request error" : "Internal server error";
+    reply.status(status).send({ error: message });
+  });
   if (options.readonly) {
     server.addHook("onRequest", (_req, reply, done) => {
       if (MUTATING_METHODS.has(_req.method)) {
@@ -642,6 +753,7 @@ async function createServer(storage, options) {
     });
   }
   registerAboutRoute(server, storage, options);
+  if (options.snapshot) registerSnapshotRoutes(server, storage);
   registerResourceRoutes(server, storage, options);
   return server;
 }
@@ -662,6 +774,11 @@ var serverOptionsSchema = import_zod.z.object({
   base: import_zod.z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v),
   /** When `true`, the server reloads the YAML file automatically on disk changes. */
   watch: import_zod.z.boolean().default(false),
+  /**
+   * When `true`, saves a snapshot of the initial database state on startup.
+   * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+   */
+  snapshot: import_zod.z.boolean().default(false),
   /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
   readonly: import_zod.z.boolean().default(false),
   /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */

package/dist/index.mjs

@@ -3,6 +3,11 @@ import { readFileSync, writeFileSync, renameSync } from "fs";
 import { resolve, dirname } from "path";
 import { randomUUID } from "crypto";
 import { parse, stringify } from "yaml";
+function deepCopyData(source) {
+  return Object.fromEntries(
+    Object.entries(source).map(([k, v]) => [k, v.map((item) => ({ ...item }))])
+  );
+}
 function createYamlStorage(filePath) {
   const absPath = resolve(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
@@ -10,6 +15,11 @@ function createYamlStorage(filePath) {
   const data = Object.fromEntries(
     Object.entries(raw).filter(([key]) => key !== "_rel")
   );
+  let snapshot = {
+    data: deepCopyData(data),
+    relations: { ...relations },
+    savedAt: /* @__PURE__ */ new Date()
+  };
   return {
     getData() {
       return data;
@@ -39,6 +49,24 @@ function createYamlStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    saveSnapshot() {
+      snapshot = {
+        data: deepCopyData(data),
+        relations: { ...relations },
+        savedAt: /* @__PURE__ */ new Date()
+      };
+    },
+    resetToSnapshot() {
+      const snap = deepCopyData(snapshot.data);
+      for (const key of Object.keys(data)) delete data[key];
+      Object.assign(data, snap);
+      for (const key of Object.keys(relations)) delete relations[key];
+      Object.assign(relations, { ...snapshot.relations });
+      this.persist();
     }
   };
 }
@@ -204,6 +232,9 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
     return expandItems(result, req.query, resource, storage);
   });
   server.post(base, (req, reply) => {
+    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(storage, resource, req.body);
     return reply.status(201).send(expandItems(item, req.query, resource, storage));
   });
@@ -217,11 +248,17 @@ var registerItemRoutes = (server, storage, resource, base) => {
     return expandItems(item, req.query, resource, storage);
   });
   server.put(`${base}/:id`, (req, reply) => {
+    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 = replaceItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
   });
   server.patch(`${base}/:id`, (req, reply) => {
+    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 = patchItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
     return expandItems(item, req.query, resource, storage);
@@ -237,7 +274,9 @@ var registerItemRoutes = (server, storage, resource, base) => {
 var registerNestedRoutes = (server, storage, relations, base) => {
   for (const [child, fields] of Object.entries(relations)) {
     for (const [field, parent] of Object.entries(fields)) {
-      server.get(`${base}/${parent}/:id/${child}`, (req, reply) => {
+      const collectionPath = `${base}/${parent}/:id/${child}`;
+      const itemPath = `${base}/${parent}/:id/${child}/:childId`;
+      server.get(collectionPath, (req, reply) => {
         const parentCollection = storage.getCollection(parent) ?? [];
         const parentItem = findById(parentCollection, req.params.id);
         if (!parentItem) return reply.status(404).send({ error: "Not found" });
@@ -246,6 +285,16 @@ var registerNestedRoutes = (server, storage, relations, base) => {
         );
         return children;
       });
+      server.get(itemPath, (req, reply) => {
+        const parentCollection = storage.getCollection(parent) ?? [];
+        const parentItem = findById(parentCollection, req.params.id);
+        if (!parentItem) return reply.status(404).send({ error: "Not found" });
+        const childItem = (storage.getCollection(child) ?? []).find(
+          (item) => String(item[field]) === req.params.id && String(item["id"]) === req.params.childId
+        );
+        if (!childItem) return reply.status(404).send({ error: "Not found" });
+        return childItem;
+      });
     }
   }
 };
@@ -370,6 +419,14 @@ curl ${host}${base}/${parent}/1/${child}`);
     examples.push(`# Pageable envelope
 curl "${host}${base}/${firstCol}?_page=2"`);
   }
+  if (options.snapshot) {
+    examples.push(
+      `# Snapshot endpoints
+curl ${host}/_snapshot
+curl -X POST ${host}/_snapshot/save
+curl -X POST ${host}/_snapshot/reset`
+    );
+  }
   const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
   return `<pre>${highlighted}</pre>`;
 }
@@ -384,6 +441,7 @@ function generateAboutHtml(storage, options) {
   if (options.delay > 0) modes.push(badge(`delay \xB7 ${options.delay}ms`, "#fb923c", "#fb923c18"));
   if (options.pageable.enabled)
     modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
+  if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const nestedRows = [];
   for (const [child, fields] of Object.entries(relations)) {
@@ -403,6 +461,18 @@ function generateAboutHtml(storage, options) {
     </summary>
     <table><tbody>${nestedRows.join("")}</tbody></table>
   </details>` : "";
+  const snapshotAccordion = options.snapshot ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">/_snapshot</span>
+      <span class="route-count">3 routes</span>
+    </summary>
+    <table><tbody>
+      ${endpointRow("GET", "/_snapshot", "Returns metadata of the current snapshot: <code>savedAt</code> and item counts per collection.")}
+      ${endpointRow("POST", "/_snapshot/save", "Replaces the stored snapshot with the current database state.")}
+      ${endpointRow("POST", "/_snapshot/reset", "Restores the database to the last saved snapshot and persists to disk.")}
+    </tbody></table>
+  </details>` : "";
   const paginationDesc = options.pageable.enabled ? `Pageable mode active \u2014 default limit <code>${options.pageable.limit}</code>. Response wrapped in <code>{ data, pagination }</code>.` : `Returns the requested slice. <code>X-Total-Count</code> header reflects the total before pagination.`;
   return `<!DOCTYPE html>
 <html lang="en">
@@ -551,6 +621,7 @@ function generateAboutHtml(storage, options) {
     <div class="endpoints-grid">
       ${accordions}
       ${nestedAccordion}
+      ${snapshotAccordion}
     </div>
 
     <h2>Query Parameters</h2>
@@ -585,11 +656,51 @@ function registerAboutRoute(server, storage, options) {
   });
 }
 
+// src/router/routes/snapshot.routes.ts
+function registerSnapshotRoutes(server, storage) {
+  server.get("/_snapshot", (_req, reply) => {
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/save", (_req, reply) => {
+    storage.saveSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Snapshot saved",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+  server.post("/_snapshot/reset", (_req, reply) => {
+    storage.resetToSnapshot();
+    const { data, savedAt } = storage.getSnapshot();
+    return reply.send({
+      message: "Database restored to snapshot",
+      savedAt: savedAt.toISOString(),
+      collections: Object.fromEntries(
+        Object.entries(data).map(([name, items]) => [name, items.length])
+      )
+    });
+  });
+}
+
 // src/server/createServer.ts
 var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 async function createServer(storage, options) {
   const server = Fastify();
   await server.register(cors);
+  server.setErrorHandler((err, _req, reply) => {
+    const status = err.statusCode ?? 500;
+    const message = status < 500 ? err.message || "Request error" : "Internal server error";
+    reply.status(status).send({ error: message });
+  });
   if (options.readonly) {
     server.addHook("onRequest", (_req, reply, done) => {
       if (MUTATING_METHODS.has(_req.method)) {
@@ -604,6 +715,7 @@ async function createServer(storage, options) {
     });
   }
   registerAboutRoute(server, storage, options);
+  if (options.snapshot) registerSnapshotRoutes(server, storage);
   registerResourceRoutes(server, storage, options);
   return server;
 }
@@ -624,6 +736,11 @@ var serverOptionsSchema = z.object({
   base: z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v),
   /** When `true`, the server reloads the YAML file automatically on disk changes. */
   watch: z.boolean().default(false),
+  /**
+   * When `true`, saves a snapshot of the initial database state on startup.
+   * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+   */
+  snapshot: z.boolean().default(false),
   /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
   readonly: z.boolean().default(false),
   /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */

package/package.json

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