@aggiovato/yrest 0.2.2 → 0.4.0

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();
     }
   };
 }
@@ -47,11 +75,92 @@ function createYamlStorage(filePath) {
 import Fastify from "fastify";
 import cors from "@fastify/cors";
 
-// src/services/resourceService.ts
+// src/utils/params.ts
 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 firstParam(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : value;
+}
+
+// src/services/query.service.ts
+var OPERATORS = ["_gte", "_lte", "_ne", "_like", "_start", "_regex"];
+function applyOperator(itemValue, op, filterValue) {
+  const strItem = String(itemValue);
+  const numItem = Number(itemValue);
+  const numFilter = Number(filterValue);
+  const numeric = !isNaN(numItem) && !isNaN(numFilter) && filterValue.trim() !== "";
+  switch (op) {
+    case "_gte":
+      return numeric ? numItem >= numFilter : strItem >= filterValue;
+    case "_lte":
+      return numeric ? numItem <= numFilter : strItem <= filterValue;
+    case "_ne":
+      return strItem !== filterValue;
+    case "_like":
+      return strItem.toLowerCase().includes(filterValue.toLowerCase());
+    case "_start":
+      return strItem.toLowerCase().startsWith(filterValue.toLowerCase());
+    case "_regex": {
+      try {
+        return new RegExp(filterValue, "i").test(strItem);
+      } catch {
+        return false;
+      }
+    }
+  }
+}
+function filterByQuery(items, query) {
+  const filters = Object.entries(query).filter(([key]) => !key.startsWith("_"));
+  if (filters.length === 0) return items;
+  return items.filter(
+    (item) => filters.every(([key, value]) => {
+      const op = OPERATORS.find((o) => key.endsWith(o));
+      if (op) {
+        const field = key.slice(0, -op.length);
+        if (item[field] === void 0) return false;
+        const filterVal = Array.isArray(value) ? value[0] : value;
+        return applyOperator(item[field], op, filterVal);
+      }
+      if (item[key] === void 0) return false;
+      const itemStr = String(item[key]);
+      return Array.isArray(value) ? value.includes(itemStr) : itemStr === value;
+    })
+  );
+}
+function fullTextSearch(items, term) {
+  const lower = term.toLowerCase();
+  return items.filter(
+    (item) => Object.values(item).some((val) => {
+      if (val === null || val === void 0 || typeof val === "object") return false;
+      return String(val).toLowerCase().includes(lower);
+    })
+  );
+}
+function sortBy(items, field, order) {
+  const direction = order === "desc" ? -1 : 1;
+  return [...items].sort((a, b) => {
+    const av = a[field];
+    const bv = b[field];
+    if (av === void 0) return 1;
+    if (bv === void 0) return -1;
+    if (typeof av === "number" && typeof bv === "number") return (av - bv) * direction;
+    return String(av).localeCompare(String(bv), void 0, { sensitivity: "base" }) * direction;
+  });
+}
+function projectFields(input, fields) {
+  if (fields.length === 0) return input;
+  const project = (item) => Object.fromEntries(fields.filter((f) => f in item).map((f) => [f, item[f]]));
+  return Array.isArray(input) ? input.map(project) : project(input);
+}
+function paginate(items, page, limit) {
+  const start = (page - 1) * limit;
+  return items.slice(start, start + limit);
+}
+
+// src/services/resource.service.ts
 function findById(items, id) {
   return items.find((i) => String(i["id"]) === id);
 }
@@ -88,36 +197,17 @@ function patchItem(storage, resource, id, body) {
   storage.persist();
   return updated;
 }
-function firstParam(value) {
-  if (value === void 0) return void 0;
-  return Array.isArray(value) ? value[0] : value;
-}
-function filterByQuery(items, query) {
-  const filters = Object.entries(query).filter(([key]) => !key.startsWith("_"));
-  if (filters.length === 0) return items;
-  return items.filter(
-    (item) => filters.every(([key, value]) => {
-      if (item[key] === void 0) return false;
-      const itemStr = String(item[key]);
-      return Array.isArray(value) ? value.includes(itemStr) : itemStr === value;
-    })
-  );
-}
-function sortBy(items, field, order) {
-  const direction = order === "desc" ? -1 : 1;
-  return [...items].sort((a, b) => {
-    const av = a[field];
-    const bv = b[field];
-    if (av === void 0) return 1;
-    if (bv === void 0) return -1;
-    if (typeof av === "number" && typeof bv === "number") return (av - bv) * direction;
-    return String(av).localeCompare(String(bv), void 0, { sensitivity: "base" }) * direction;
-  });
-}
-function paginate(items, page, limit) {
-  const start = (page - 1) * limit;
-  return items.slice(start, start + limit);
+function deleteItem(storage, resource, id) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const [deleted] = collection.splice(idx, 1);
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return deleted;
 }
+
+// src/services/expand.service.ts
 function expandItems(input, query, resource, storage) {
   const isArray = Array.isArray(input);
   const items = isArray ? input : [input];
@@ -150,14 +240,35 @@ function expandItems(input, query, resource, storage) {
   });
   return isArray ? expanded : expanded[0];
 }
-function deleteItem(storage, resource, id) {
-  const collection = storage.getCollection(resource) ?? [];
-  const idx = findIndexById(collection, id);
-  if (idx === -1) return void 0;
-  const [deleted] = collection.splice(idx, 1);
-  storage.setCollection(resource, collection);
-  storage.persist();
-  return deleted;
+function embedItems(input, query, resource, storage) {
+  const isArray = Array.isArray(input);
+  const items = isArray ? input : [input];
+  const embedParam = query["_embed"];
+  if (!embedParam) return isArray ? items : input;
+  const keys = (Array.isArray(embedParam) ? embedParam : [embedParam]).flatMap((v) => v.split(",")).map((k) => k.trim()).filter(Boolean);
+  const relations = storage.getRelations();
+  const embeds = /* @__PURE__ */ new Map();
+  for (const embedKey of keys) {
+    outer: for (const [childCollection, fields] of Object.entries(relations)) {
+      for (const [fkField, parentCollection] of Object.entries(fields)) {
+        if (parentCollection === resource && childCollection === embedKey) {
+          embeds.set(embedKey, { childCollection, fkField });
+          break outer;
+        }
+      }
+    }
+  }
+  if (embeds.size === 0) return isArray ? items : input;
+  const result = items.map((item) => {
+    const out = { ...item };
+    for (const [embedKey, { childCollection, fkField }] of embeds) {
+      out[embedKey] = (storage.getCollection(childCollection) ?? []).filter(
+        (child) => String(child[fkField]) === String(item["id"])
+      );
+    }
+    return out;
+  });
+  return isArray ? result : result[0];
 }
 
 // src/router/routes/collection.routes.ts
@@ -165,9 +276,12 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
   server.get(base, (req, reply) => {
     const collection = storage.getCollection(resource) ?? [];
     const filtered = filterByQuery(collection, req.query);
+    const searchTerm = firstParam(req.query["_q"]);
+    const searched = searchTerm ? fullTextSearch(filtered, searchTerm) : filtered;
+    const fields = (firstParam(req.query["_fields"]) ?? "").split(",").map((f) => f.trim()).filter(Boolean);
     const sortField = firstParam(req.query["_sort"]);
     const sortOrder = firstParam(req.query["_order"]) === "desc" ? "desc" : "asc";
-    const sorted = sortField ? sortBy(filtered, sortField, sortOrder) : filtered;
+    const sorted = sortField ? sortBy(searched, sortField, sortOrder) : searched;
     if (options.pageable.enabled) {
       const defaultLimit = options.pageable.limit;
       const page = Math.max(1, parseInt(firstParam(req.query["_page"]) ?? "1", 10) || 1);
@@ -177,7 +291,15 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
       );
       const totalItems = sorted.length;
       const totalPages = Math.ceil(totalItems / limit) || 1;
-      const data = expandItems(paginate(sorted, page, limit), req.query, resource, storage);
+      const data = projectFields(
+        embedItems(
+          expandItems(paginate(sorted, page, limit), req.query, resource, storage),
+          req.query,
+          resource,
+          storage
+        ),
+        fields
+      );
       const pagination = {
         page,
         limit,
@@ -201,9 +323,15 @@ var registerCollectionRoutes = (server, storage, resource, base, options) => {
       reply.header("X-Total-Count", String(sorted.length));
       result = paginate(sorted, page, limit);
     }
-    return expandItems(result, req.query, resource, storage);
+    return projectFields(
+      embedItems(expandItems(result, req.query, resource, storage), req.query, resource, storage),
+      fields
+    );
   });
   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));
   });
@@ -214,14 +342,24 @@ var registerItemRoutes = (server, storage, resource, base) => {
   server.get(`${base}/:id`, (req, reply) => {
     const item = findById(storage.getCollection(resource) ?? [], req.params.id);
     if (!item) return reply.status(404).send({ error: "Not found" });
-    return expandItems(item, req.query, resource, storage);
+    const fields = (req.query["_fields"] ?? "").split(",").map((f) => f.trim()).filter(Boolean);
+    return projectFields(
+      embedItems(expandItems(item, req.query, resource, storage), req.query, resource, storage),
+      fields
+    );
   });
   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 +375,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 +386,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 +520,30 @@ curl ${host}${base}/${parent}/1/${child}`);
     examples.push(`# Pageable envelope
 curl "${host}${base}/${firstCol}?_page=2"`);
   }
+  const firstParentRel = Object.entries(relations).find(
+    ([, fields]) => Object.values(fields).includes(firstCol ?? "")
+  );
+  if (firstCol) {
+    examples.push(
+      `# Project fields with ?_fields
+curl "${host}${base}/${firstCol}?_fields=id,name"`
+    );
+  }
+  if (firstParentRel && firstCol) {
+    const [childName] = firstParentRel;
+    examples.push(
+      `# Embed child collection with ?_embed
+curl "${host}${base}/${firstCol}/1?_embed=${childName}"`
+    );
+  }
+  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 +558,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 +578,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 +738,7 @@ function generateAboutHtml(storage, options) {
     <div class="endpoints-grid">
       ${accordions}
       ${nestedAccordion}
+      ${snapshotAccordion}
     </div>
 
     <h2>Query Parameters</h2>
@@ -559,9 +747,17 @@ function generateAboutHtml(storage, options) {
         <thead><tr><th>Param</th><th>Example</th><th>Description</th></tr></thead>
         <tbody>
           <tr><td><code>?field=value</code></td><td><code>?name=Ana&amp;role=admin</code></td><td>Filter by any field. Multiple params are ANDed.</td></tr>
+          <tr><td><code>?field_gte / _lte</code></td><td><code>?price_gte=10&amp;price_lte=50</code></td><td>Numeric or lexicographic range. Works with any comparable field.</td></tr>
+          <tr><td><code>?field_ne</code></td><td><code>?status_ne=inactive</code></td><td>Exclude items where the field equals the value.</td></tr>
+          <tr><td><code>?field_like</code></td><td><code>?name_like=ana</code></td><td>Case-insensitive substring match.</td></tr>
+          <tr><td><code>?field_start</code></td><td><code>?name_start=A</code></td><td>Case-insensitive prefix match.</td></tr>
+          <tr><td><code>?field_regex</code></td><td><code>?email_regex=gmail</code></td><td>Case-insensitive regular expression match.</td></tr>
+          <tr><td><code>?_q</code></td><td><code>?_q=ana</code></td><td>Full-text search across all scalar fields (case-insensitive substring).</td></tr>
           <tr><td><code>?_sort &amp; ?_order</code></td><td><code>?_sort=name&amp;_order=desc</code></td><td>Sort by field. <code>_order</code>: <code>asc</code> (default) or <code>desc</code>.</td></tr>
           <tr><td><code>?_page &amp; ?_limit</code></td><td><code>?_page=2&amp;_limit=10</code></td><td>${paginationDesc}</td></tr>
           <tr><td><code>?_expand</code></td><td><code>?_expand=user</code></td><td>Embed a related parent object inline. Requires <code>_rel</code> in the YAML file.</td></tr>
+          <tr><td><code>?_embed</code></td><td><code>?_embed=posts</code></td><td>Embed child collections into each parent item. Requires <code>_rel</code> in the YAML file.</td></tr>
+          <tr><td><code>?_fields</code></td><td><code>?_fields=id,name</code></td><td>Return only the specified fields. Applied last \u2014 can include embedded/expanded keys.</td></tr>
         </tbody>
       </table>
     </div>
@@ -585,11 +781,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 +840,7 @@ async function createServer(storage, options) {
     });
   }
   registerAboutRoute(server, storage, options);
+  if (options.snapshot) registerSnapshotRoutes(server, storage);
   registerResourceRoutes(server, storage, options);
   return server;
 }
@@ -624,6 +861,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.4.0",
   "description": "Zero-config REST API mock server powered by a YAML file",
   "keywords": [
     "yaml",