@yrest/cli 0.8.0 → 0.9.0

package/dist/cli/index.mjs

@@ -9,62 +9,470 @@ import { existsSync, writeFileSync } from "fs";
 import { resolve } from "path";
 
 // src/cli/commands/templates/basic.ts
-var basicTemplate = `users:
+var basicTemplate = `# yrest basic sample
+# Run: npx @yrest/cli serve db.yml
+# Docs: GET http://localhost:3070/_about
+
+users:
   - id: 1
-    name: Ana
-    email: ana@test.com
+    name: Ana Garc\xEDa
+    email: ana@example.com
+    role: admin
+    active: true
   - id: 2
-    name: Luis
-    email: luis@test.com
+    name: Luis Mart\xEDnez
+    email: luis@example.com
+    role: editor
+    active: true
+  - id: 3
+    name: Sara L\xF3pez
+    email: sara@example.com
+    role: user
+    active: true
+  - id: 4
+    name: Diego Ruiz
+    email: diego@example.com
+    role: user
+    active: false
 
 products:
   - id: 1
-    name: Laptop
-    price: 999
+    name: Laptop Pro 15
+    price: 1299.99
+    stock: 15
+    category: electronics
+    featured: true
+  - id: 2
+    name: Wireless Mouse
+    price: 39.99
+    stock: 80
+    category: accessories
+    featured: false
+  - id: 3
+    name: Mechanical Keyboard
+    price: 129.99
+    stock: 45
+    category: accessories
+    featured: true
+  - id: 4
+    name: 4K Monitor 27"
+    price: 549.99
+    stock: 20
+    category: electronics
+    featured: true
+  - id: 5
+    name: USB-C Hub 7-in-1
+    price: 49.99
+    stock: 100
+    category: accessories
+    featured: false
+
+categories:
+  - id: 1
+    name: Electronics
+    slug: electronics
+    description: Laptops, monitors and computing gear
   - id: 2
-    name: Phone
-    price: 499
+    name: Accessories
+    slug: accessories
+    description: Peripherals and add-ons
+
+# Try these queries:
+#   GET /users?role=admin
+#   GET /products?featured=true&_sort=price&_order=asc
+#   GET /products?price_lte=100
+#   GET /users?_q=garcia
+#   GET /products?_fields=id,name,price&_page=1&_limit=3
 `;
 
 // src/cli/commands/templates/relational.ts
-var relationalTemplate = `_rel:
+var relationalTemplate = `# yrest relational sample \u2014 blog
+# Demonstrates: many2one, one2one and many2many relationships
+# Run: npx @yrest/cli serve db.yml
+# Docs: GET http://localhost:3070/_about
+
+_rel:
+  # many2one \u2014 posts and comments belong to a user
   posts:
     userId: users
+    # many2many \u2014 posts can have multiple tags via the post_tags pivot
+    tags:
+      type: many2many
+      target: tags
+      through: post_tags
+      foreignKey: postId
+      otherKey: tagId
   comments:
     postId: posts
+    userId: users
+
+  # one2one \u2014 each user has exactly one profile
+  profiles:
+    userId:
+      type: one2one
+      target: users
 
 users:
   - id: 1
-    name: Ana
-    email: ana@test.com
+    name: Ana Garc\xEDa
+    email: ana@example.com
+    role: author
   - id: 2
-    name: Luis
-    email: luis@test.com
+    name: Luis Mart\xEDnez
+    email: luis@example.com
+    role: author
+  - id: 3
+    name: Sara L\xF3pez
+    email: sara@example.com
+    role: reader
+
+profiles:
+  - id: 1
+    userId: 1
+    bio: Full-stack developer and open-source enthusiast
+    avatar: https://i.pravatar.cc/150?img=1
+    website: https://ana.dev
+  - id: 2
+    userId: 2
+    bio: Backend engineer, coffee addict
+    avatar: https://i.pravatar.cc/150?img=2
+    website: https://luisdev.io
+  - id: 3
+    userId: 3
+    bio: Designer turned frontend developer
+    avatar: https://i.pravatar.cc/150?img=3
+    website: null
+
+tags:
+  - id: 1
+    name: typescript
+    color: "#3178c6"
+  - id: 2
+    name: api
+    color: "#10b981"
+  - id: 3
+    name: testing
+    color: "#f59e0b"
+  - id: 4
+    name: devtools
+    color: "#8b5cf6"
+  - id: 5
+    name: yaml
+    color: "#ef4444"
 
 posts:
   - id: 1
-    title: First post
-    body: Content of the first post
+    title: Getting started with TypeScript
+    slug: getting-started-typescript
+    body: TypeScript adds static typing to JavaScript, catching errors at compile time...
     userId: 1
+    published: true
+    views: 1420
+    createdAt: "2024-11-01"
   - id: 2
-    title: Second post
-    body: Content of the second post
+    title: Building REST APIs with Fastify
+    slug: rest-apis-fastify
+    body: Fastify is the fastest Node.js web framework, perfect for building APIs...
     userId: 1
+    published: true
+    views: 980
+    createdAt: "2024-11-15"
+  - id: 3
+    title: Testing strategies for modern apps
+    slug: testing-strategies-modern
+    body: A solid test strategy covers unit, integration and end-to-end scenarios...
+    userId: 2
+    published: true
+    views: 640
+    createdAt: "2024-12-03"
+  - id: 4
+    title: YAML as a database format
+    slug: yaml-database-format
+    body: YAML is human-readable and expressive enough for mock data during development...
+    userId: 2
+    published: false
+    views: 0
+    createdAt: "2025-01-10"
+
+# pivot table for posts \u2194 tags (many2many)
+post_tags:
+  - { id: 1, postId: 1, tagId: 1 }
+  - { id: 2, postId: 1, tagId: 2 }
+  - { id: 3, postId: 2, tagId: 2 }
+  - { id: 4, postId: 2, tagId: 4 }
+  - { id: 5, postId: 3, tagId: 3 }
+  - { id: 6, postId: 3, tagId: 1 }
+  - { id: 7, postId: 4, tagId: 5 }
+  - { id: 8, postId: 4, tagId: 2 }
 
 comments:
   - id: 1
-    body: Great post!
+    body: Great introduction! This helped me a lot.
     postId: 1
+    userId: 3
+    likes: 5
   - id: 2
-    body: Thanks for sharing
+    body: Could you cover generics in a follow-up post?
     postId: 1
+    userId: 2
+    likes: 3
+  - id: 3
+    body: Fastify is indeed much faster than Express in my benchmarks.
+    postId: 2
+    userId: 3
+    likes: 8
+  - id: 4
+    body: Do you have a GitHub repo with these examples?
+    postId: 2
+    userId: 1
+    likes: 1
+  - id: 5
+    body: E2E tests are underrated. Solid post!
+    postId: 3
+    userId: 1
+    likes: 4
+
+# Try these queries:
+#   GET /posts?published=true&_sort=views&_order=desc
+#   GET /posts/1?_expand=user          \u2192 embeds author object
+#   GET /users/1?_embed=posts          \u2192 embeds posts array
+#   GET /users/1/profiles              \u2192 one2one nested route
+#   GET /posts/1/tags                  \u2192 many2many nested route
+#   GET /posts/1?_embed=tags           \u2192 many2many via ?_embed
+#   GET /users/1?_embed=profiles       \u2192 one2one via ?_embed (returns object, not array)
+`;
+
+// src/cli/commands/templates/ecommerce.ts
+var ecommerceTemplate = `# yrest ecommerce sample
+# Demonstrates: many2one, many2many, _routes with scenarios, template vars and delay
+# Run: npx @yrest/cli serve db.yml
+# Docs: GET http://localhost:3070/_about
+
+_rel:
+  # many2one
+  orders:
+    userId: users
+  order_items:
+    orderId: orders
+    productId: products
+
+  # many2many \u2014 products belong to multiple categories via pivot
+  products:
+    categories:
+      type: many2many
+      target: categories
+      through: product_categories
+      foreignKey: productId
+      otherKey: categoryId
+
+_routes:
+  # Login with conditional scenarios
+  - method: POST
+    path: /auth/login
+    scenarios:
+      - when:
+          body.email: admin@example.com
+          body.password: secret
+        response:
+          status: 200
+          body:
+            token: tok-admin-abc123
+            role: admin
+            userId: 1
+      - when:
+          body.email: user@example.com
+          body.password: secret
+        response:
+          status: 200
+          body:
+            token: tok-user-xyz789
+            role: user
+            userId: 2
+    otherwise:
+      status: 401
+      body:
+        error: Invalid credentials
+
+  # Logout \u2014 always 204
+  - method: POST
+    path: /auth/logout
+    response:
+      status: 204
+
+  # Static featured products list
+  - method: GET
+    path: /store/featured
+    response:
+      status: 200
+      body:
+        - id: 1
+          name: Laptop Pro 15
+          price: 1299.99
+          badge: Best Seller
+        - id: 4
+          name: 4K Monitor 27"
+          price: 549.99
+          badge: New Arrival
+        - id: 3
+          name: Mechanical Keyboard
+          price: 129.99
+          badge: On Sale
+
+  # Template variables \u2014 echoes the requested product id
+  - method: GET
+    path: /products/:id/summary
+    response:
+      status: 200
+      body:
+        productId: "{{params.id}}"
+        requestedAt: "{{now}}"
+        source: mock
+
+  # Cancel order with simulated latency and template vars
+  - method: POST
+    path: /orders/:id/cancel
+    delay: 500
+    response:
+      status: 200
+      body:
+        orderId: "{{params.id}}"
+        status: cancelled
+        cancelledAt: "{{now}}"
+
+  # Simulate a service outage for testing error handling
+  - method: GET
+    path: /store/inventory/sync
+    error: 503
+    errorBody:
+      message: Inventory service temporarily unavailable
+      retryAfter: 30
+
+users:
+  - id: 1
+    name: Ana Garc\xEDa
+    email: admin@example.com
+    role: admin
+    active: true
+  - id: 2
+    name: Luis Mart\xEDnez
+    email: user@example.com
+    role: user
+    active: true
+  - id: 3
+    name: Sara L\xF3pez
+    email: sara@example.com
+    role: user
+    active: true
+  - id: 4
+    name: Diego Ruiz
+    email: diego@example.com
+    role: user
+    active: false
+
+categories:
+  - id: 1
+    name: Laptops
+    slug: laptops
+  - id: 2
+    name: Peripherals
+    slug: peripherals
+  - id: 3
+    name: Monitors
+    slug: monitors
+  - id: 4
+    name: Accessories
+    slug: accessories
+
+products:
+  - id: 1
+    name: Laptop Pro 15
+    description: High-performance laptop for developers
+    price: 1299.99
+    stock: 15
+    sku: LAP-001
+    active: true
+  - id: 2
+    name: Wireless Mouse
+    description: Ergonomic wireless mouse with USB-C receiver
+    price: 39.99
+    stock: 80
+    sku: MOU-001
+    active: true
+  - id: 3
+    name: Mechanical Keyboard
+    description: Tactile switches, full RGB, TKL layout
+    price: 129.99
+    stock: 45
+    sku: KEY-001
+    active: true
+  - id: 4
+    name: 4K Monitor 27"
+    description: IPS panel, 144Hz, HDR400
+    price: 549.99
+    stock: 20
+    sku: MON-001
+    active: true
+  - id: 5
+    name: USB-C Hub 7-in-1
+    description: HDMI, SD card and USB-A ports
+    price: 49.99
+    stock: 100
+    sku: HUB-001
+    active: true
+
+# pivot table for products \u2194 categories (many2many)
+product_categories:
+  - { id: 1, productId: 1, categoryId: 1 }
+  - { id: 2, productId: 2, categoryId: 2 }
+  - { id: 3, productId: 2, categoryId: 4 }
+  - { id: 4, productId: 3, categoryId: 2 }
+  - { id: 5, productId: 3, categoryId: 4 }
+  - { id: 6, productId: 4, categoryId: 3 }
+  - { id: 7, productId: 5, categoryId: 4 }
+
+orders:
+  - id: 1
+    userId: 2
+    status: delivered
+    total: 1339.98
+    createdAt: "2024-12-10"
+  - id: 2
+    userId: 3
+    status: processing
+    total: 179.98
+    createdAt: "2025-01-15"
+  - id: 3
+    userId: 2
+    status: pending
+    total: 549.99
+    createdAt: "2025-02-01"
+
+order_items:
+  - { id: 1, orderId: 1, productId: 1, quantity: 1, unitPrice: 1299.99 }
+  - { id: 2, orderId: 1, productId: 2, quantity: 1, unitPrice:   39.99 }
+  - { id: 3, orderId: 2, productId: 3, quantity: 1, unitPrice:  129.99 }
+  - { id: 4, orderId: 2, productId: 2, quantity: 1, unitPrice:   39.99 }
+  - { id: 5, orderId: 3, productId: 4, quantity: 1, unitPrice:  549.99 }
+
+# Try these queries:
+#   POST /auth/login       { "email": "admin@example.com", "password": "secret" }
+#   GET  /store/featured
+#   GET  /products/1/summary
+#   GET  /products/1/categories              \u2192 many2many nested route
+#   GET  /products/1?_embed=categories       \u2192 many2many via ?_embed
+#   GET  /users/2?_embed=orders              \u2192 many2one ?_embed
+#   GET  /users/2/orders                     \u2192 nested route
+#   GET  /orders/1?_embed=order_items        \u2192 nested items
+#   POST /orders/1/cancel                    \u2192 delayed response with template vars
+#   GET  /store/inventory/sync               \u2192 forced 503 error
 `;
 
 // src/cli/commands/templates/index.ts
-var SAMPLES = ["basic", "relational"];
+var SAMPLES = ["basic", "relational", "ecommerce"];
 var templates = {
   basic: basicTemplate,
-  relational: relationalTemplate
+  relational: relationalTemplate,
+  ecommerce: ecommerceTemplate
 };
 
 // src/cli/commands/init.ts
@@ -114,6 +522,50 @@ import { resolve as resolve2, dirname } from "path";
 import { randomUUID } from "crypto";
 import { parse, stringify } from "yaml";
 
+// src/storage/parseRelations.ts
+function parseRelations(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result = {};
+  for (const [collection, fields] of Object.entries(raw)) {
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) continue;
+    result[collection] = {};
+    for (const [key, value] of Object.entries(fields)) {
+      const def = normaliseRelationDef(key, value);
+      if (def) result[collection][key] = def;
+    }
+  }
+  return result;
+}
+function normaliseRelationDef(key, value) {
+  if (typeof value === "string") {
+    return { type: "many2one", target: value };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value;
+  const type = v["type"];
+  const nested = v["nested"] === true ? true : void 0;
+  if (type === "many2one" || type === void 0) {
+    const target = v["target"];
+    if (typeof target !== "string") return null;
+    return nested ? { type: "many2one", target, nested } : { type: "many2one", target };
+  }
+  if (type === "one2one") {
+    const target = v["target"];
+    if (typeof target !== "string") return null;
+    return nested ? { type: "one2one", target, nested } : { type: "one2one", target };
+  }
+  if (type === "many2many") {
+    const target = typeof v["target"] === "string" ? v["target"] : key;
+    const through = v["through"];
+    const foreignKey = v["foreignKey"];
+    const otherKey = v["otherKey"];
+    if (typeof through !== "string" || typeof foreignKey !== "string" || typeof otherKey !== "string")
+      return null;
+    return nested ? { type: "many2many", target, through, foreignKey, otherKey, nested } : { type: "many2many", target, through, foreignKey, otherKey };
+  }
+  return null;
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -125,7 +577,7 @@ function deepCopyData(source) {
 function createYrestStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
-  const relations = raw["_rel"] ?? {};
+  const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
   const data = Object.fromEntries(
     Object.entries(raw).filter(([key]) => key !== "_rel" && key !== "_routes")
@@ -162,7 +614,7 @@ function createYrestStorage(filePath) {
     },
     reload() {
       const fresh = parse(readFileSync(absPath, "utf8")) ?? {};
-      const freshRelations = fresh["_rel"] ?? {};
+      const freshRelations = parseRelations(fresh["_rel"]);
       const freshData = Object.fromEntries(
         Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
       );
@@ -247,16 +699,7 @@ function hasTemplates(value) {
   return typeof value === "string" ? value.includes("{{") : JSON.stringify(value).includes("{{");
 }
 
-// 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 "";
-  }
-})();
+// src/router/templates/about.helpers.ts
 var METHOD_COLOR = {
   GET: "#3fb950",
   POST: "#58a6ff",
@@ -265,8 +708,11 @@ var METHOD_COLOR = {
   DELETE: "#f85149",
   fn: "#f0883e"
 };
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
 function badge(label, color, bg) {
-  return `<span class="badge" style="background:${bg};color:${color};border:1px solid ${color}40">${label}</span>`;
+  return `<span class="badge" style="background:${bg};color:${color};border:1px solid ${color}40">${escapeHtml(label)}</span>`;
 }
 function methodBadge(method) {
   const color = METHOD_COLOR[method] ?? "#7d8590";
@@ -276,7 +722,7 @@ function endpointRow(method, path, desc) {
   return `
     <tr>
       <td class="method-cell">${methodBadge(method)}</td>
-      <td class="path-cell"><code>${path}</code></td>
+      <td class="path-cell"><code>${escapeHtml(path)}</code></td>
       <td class="desc-cell">${desc}</td>
     </tr>`;
 }
@@ -310,7 +756,7 @@ function resourceAccordion(name, base, isOpen) {
   return `
   <details class="resource-card" ${isOpen ? "open" : ""}>
     <summary>
-      <span class="resource-name">/${name}</span>
+      <span class="resource-name">/${escapeHtml(name)}</span>
       <span class="route-count">6 routes</span>
     </summary>
     <table>
@@ -318,6 +764,139 @@ function resourceAccordion(name, base, isOpen) {
     </table>
   </details>`;
 }
+function nestedRoutesAccordion(relations, base) {
+  const rows = [];
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      const nestedBadge = def.nested ? ` ${badge("nested", "#facc15", "#facc1518")}` : "";
+      if (def.type === "many2many") {
+        const singular = source.endsWith("s") ? source.slice(0, -1) : source;
+        const m2mBadge = badge("many2many", "#818cf8", "#818cf818");
+        rows.push(
+          endpointRow(
+            "GET",
+            `${base}/${source}/:id/${key}`,
+            `List ${def.target} linked to a ${singular} via ${def.through}. ${m2mBadge}${nestedBadge}`
+          )
+        );
+        const targetSingular = def.target.endsWith("s") ? def.target.slice(0, -1) : def.target;
+        rows.push(
+          endpointRow(
+            "GET",
+            `${base}/${def.target}/:id/${source}`,
+            `List ${source} linked to a ${targetSingular} via ${def.through} (inverse). ${m2mBadge}`
+          )
+        );
+      } else {
+        const path = `${base}/${def.target}/:id/${source}`;
+        const parentSingular = def.target.endsWith("s") ? def.target.slice(0, -1) : def.target;
+        const typeBadge = def.type === "one2one" ? ` ${badge("one2one", "#34d399", "#34d39918")}` : "";
+        rows.push(
+          endpointRow(
+            "GET",
+            path,
+            `${def.type === "one2one" ? "Get" : "List"} ${source} belonging to a ${parentSingular}.${typeBadge}${nestedBadge}`
+          )
+        );
+      }
+    }
+  }
+  if (!rows.length) return "";
+  return `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">Nested routes</span>
+      <span class="route-count">${rows.length} route${rows.length !== 1 ? "s" : ""}</span>
+    </summary>
+    <table><tbody>${rows.join("")}</tbody></table>
+  </details>`;
+}
+function snapshotAccordion() {
+  return `
+  <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>`;
+}
+function customRoutesAccordion(routes, base, handlers) {
+  if (!routes.length) return "";
+  const rows = routes.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>`);
+    if (r.scenarios?.length) {
+      const hasOr = r.scenarios.some((s) => Array.isArray(s.when));
+      tags.push(
+        `<span style="color:#a371f7;font-size:11px">scenarios\xB7${r.scenarios.length}${hasOr ? " (OR)" : ""}</span>`
+      );
+    }
+    if (r.otherwise)
+      tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
+    let desc;
+    if (r.error) {
+      desc = `Error injection \u2014 <code>${r.error}</code>`;
+    } else if (r.handler) {
+      const found = handlers.has(r.handler);
+      const handlerName = escapeHtml(r.handler);
+      desc = found ? `Handler \u2014 <code>${handlerName}()</code>` : `Handler \u2014 <code>${handlerName}()</code> <span style="color:#f85149">(not loaded)</span>`;
+    } else if (r.scenarios?.length) {
+      const hasTemplateInScenarios = r.scenarios.some((s) => s.response.body != null && hasTemplates(s.response.body)) || r.otherwise?.body != null && hasTemplates(r.otherwise.body);
+      desc = hasTemplateInScenarios ? `Scenarios \u2014 <code>{{\u2026}}</code>` : `Scenarios`;
+    } else if (r.response?.body != null && hasTemplates(r.response.body)) {
+      desc = `Dynamic \u2014 <code>{{\u2026}}</code>`;
+    } else {
+      const status = r.response?.status ?? 200;
+      desc = `Static \u2014 <code>${status}</code>${r.response?.headers ? ` + headers` : ""}`;
+    }
+    if (tags.length) desc += `&ensp;${tags.join("&ensp;")}`;
+    return endpointRow(r.method?.toUpperCase() ?? "GET", fullPath, desc);
+  });
+  return `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">Custom routes</span>
+      <span class="route-count">${routes.length} route${routes.length !== 1 ? "s" : ""}</span>
+    </summary>
+    <table><tbody>
+      ${rows.join("")}
+    </tbody></table>
+  </details>`;
+}
+function handlersAccordion(handlers, routes, base) {
+  if (!handlers.size) return "";
+  const routesByHandler = /* @__PURE__ */ new Map();
+  for (const r of routes) {
+    if (r.handler) {
+      const list = routesByHandler.get(r.handler) ?? [];
+      list.push({ method: (r.method ?? "GET").toUpperCase(), path: `${base}${r.path}` });
+      routesByHandler.set(r.handler, list);
+    }
+  }
+  const rows = [...handlers.keys()].map((name) => {
+    const linked = routesByHandler.get(name);
+    const routeDesc = linked ? linked.map((r) => `<code>${r.method} ${r.path}</code>`).join(", ") : `<span style="color:var(--text-muted)">not referenced in _routes</span>`;
+    return endpointRow("fn", name + "()", routeDesc);
+  });
+  return `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">Handlers</span>
+      <span class="route-count">${handlers.size} function${handlers.size !== 1 ? "s" : ""}</span>
+    </summary>
+    <table><tbody>
+      ${rows.join("")}
+    </tbody></table>
+  </details>`;
+}
 function examplesBlock(collections, relations, base, host, options, firstCustomRoute) {
   const examples = [];
   const firstCol = collections[0];
@@ -348,35 +927,36 @@ curl -X DELETE ${p}/1`
   const firstRel = Object.entries(relations)[0];
   if (firstRel) {
     const [child, fields] = firstRel;
-    const fk = Object.keys(fields)[0];
-    const expandKey = fk.replace(/Id$/i, "");
-    examples.push(
-      `# Embed parent with ?_expand
-curl "${host}${base}/${child}/1?_expand=${expandKey}"`
-    );
-  }
-  const firstRelEntry = Object.entries(relations)[0];
-  if (firstRelEntry) {
-    const [child, fields] = firstRelEntry;
-    const parent = Object.values(fields)[0];
-    if (parent) {
-      examples.push(`# Nested resource
-curl ${host}${base}/${parent}/1/${child}`);
+    const firstField = Object.entries(fields)[0];
+    if (firstField) {
+      const [fk, def] = firstField;
+      if (def.type !== "many2many") {
+        const expandKey = fk.replace(/Id$/i, "");
+        examples.push(
+          `# Embed parent with ?_expand
+curl "${host}${base}/${child}/1?_expand=${expandKey}"`,
+          `# Nested resource
+curl ${host}${base}/${def.target}/1/${child}`
+        );
+      } else {
+        examples.push(`# Many-to-many embed
+curl "${host}${base}/${child}/1/${fk}"`);
+      }
     }
   }
   if (options.pageable.enabled && firstCol) {
     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"`
     );
   }
+  const firstParentRel = Object.entries(relations).find(
+    ([, fields]) => Object.values(fields).some((def) => def.type !== "many2many" && def.target === firstCol)
+  );
   if (firstParentRel && firstCol) {
     const [childName] = firstParentRel;
     examples.push(
@@ -394,7 +974,7 @@ curl -X POST ${host}/_snapshot/reset`
   }
   if (firstCustomRoute) {
     const method = firstCustomRoute.method?.toUpperCase() ?? "GET";
-    const fullPath = `${host}${base}${firstCustomRoute.path}`;
+    const fullPath = `${host}${base}${escapeHtml(firstCustomRoute.path ?? "")}`;
     const curlFlag = method === "GET" ? "" : `-X ${method} `;
     examples.push(`# Custom route
 curl ${curlFlag}${fullPath}`);
@@ -402,9 +982,21 @@ curl ${curlFlag}${fullPath}`);
   const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
   return `<pre>${highlighted}</pre>`;
 }
+
+// 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 "";
+  }
+})();
 function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map()) {
   const collections = Object.keys(storage.getData());
   const relations = storage.getRelations();
+  const customRoutes = storage.getRoutes();
   const base = options.base;
   const host = `http://${options.host}:${options.port}`;
   const modes = [];
@@ -418,104 +1010,6 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
   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)) {
-    for (const [, parent] of Object.entries(fields)) {
-      const nestedPath = `${base}/${parent}/:id/${child}`;
-      const parentSingular = parent.endsWith("s") ? parent.slice(0, -1) : parent;
-      nestedRows.push(
-        endpointRow("GET", nestedPath, `List ${child} belonging to a ${parentSingular}.`)
-      );
-    }
-  }
-  const nestedAccordion = nestedRows.length ? `
-  <details class="resource-card nested-card">
-    <summary>
-      <span class="resource-name">Nested routes</span>
-      <span class="route-count">${nestedRows.length} route${nestedRows.length !== 1 ? "s" : ""}</span>
-    </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 customRoutes = storage.getRoutes();
-  const customRoutesAccordion = customRoutes.length ? `
-  <details class="resource-card nested-card">
-    <summary>
-      <span class="resource-name">Custom routes</span>
-      <span class="route-count">${customRoutes.length} route${customRoutes.length !== 1 ? "s" : ""}</span>
-    </summary>
-    <table><tbody>
-      ${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>`);
-    }
-    if (r.scenarios?.length) {
-      const hasOr = r.scenarios.some((s) => Array.isArray(s.when));
-      tags.push(
-        `<span style="color:#a371f7;font-size:11px">scenarios\xB7${r.scenarios.length}${hasOr ? " (OR)" : ""}</span>`
-      );
-    }
-    if (r.otherwise) {
-      tags.push(`<span style="color:var(--text-muted);font-size:11px">otherwise</span>`);
-    }
-    let desc;
-    if (r.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) {
-      const hasTemplateInScenarios = r.scenarios.some((s) => s.response.body != null && hasTemplates(s.response.body)) || r.otherwise?.body != null && hasTemplates(r.otherwise.body);
-      desc = hasTemplateInScenarios ? `Scenarios \u2014 <code>{{\u2026}}</code>` : `Scenarios`;
-    } else if (r.response?.body != null && hasTemplates(r.response.body)) {
-      desc = `Dynamic \u2014 <code>{{\u2026}}</code>`;
-    } else {
-      const status = r.response?.status ?? 200;
-      desc = `Static \u2014 <code>${status}</code>${r.response?.headers ? ` + headers` : ""}`;
-    }
-    if (tags.length) desc += `&ensp;${tags.join("&ensp;")}`;
-    return endpointRow(r.method?.toUpperCase() ?? "GET", fullPath, desc);
-  }).join("")}
-    </tbody></table>
-  </details>` : "";
-  const routesByHandler = /* @__PURE__ */ new Map();
-  for (const r of customRoutes) {
-    if (r.handler) {
-      const list = routesByHandler.get(r.handler) ?? [];
-      list.push({ method: (r.method ?? "GET").toUpperCase(), path: `${base}${r.path}` });
-      routesByHandler.set(r.handler, list);
-    }
-  }
-  const handlersAccordion = handlers.size > 0 ? `
-  <details class="resource-card nested-card">
-    <summary>
-      <span class="resource-name">Handlers</span>
-      <span class="route-count">${handlers.size} function${handlers.size !== 1 ? "s" : ""}</span>
-    </summary>
-    <table><tbody>
-      ${[...handlers.keys()].map((name) => {
-    const routes = routesByHandler.get(name);
-    const routeDesc = routes ? routes.map((r) => `<code>${r.method} ${r.path}</code>`).join(", ") : `<span style="color:var(--text-muted)">not referenced in _routes</span>`;
-    return endpointRow("fn", name + "()", routeDesc);
-  }).join("")}
-    </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">
@@ -663,10 +1157,10 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     <h2>Endpoints</h2>
     <div class="endpoints-grid">
       ${accordions}
-      ${nestedAccordion}
-      ${snapshotAccordion}
-      ${customRoutesAccordion}
-      ${handlersAccordion}
+      ${nestedRoutesAccordion(relations, base)}
+      ${options.snapshot ? snapshotAccordion() : ""}
+      ${customRoutesAccordion(customRoutes, base, handlers)}
+      ${handlersAccordion(handlers, customRoutes, base)}
     </div>
 
     <h2>Query Parameters</h2>
@@ -752,6 +1246,7 @@ function applyOperator(itemValue, op, filterValue) {
     case "_start":
       return strItem.toLowerCase().startsWith(filterValue.toLowerCase());
     case "_regex": {
+      if (filterValue.length > 200) return false;
       try {
         return new RegExp(filterValue, "i").test(strItem);
       } catch {
@@ -865,10 +1360,11 @@ function expandItems(input, query, resource, storage) {
   const resourceRelations = storage.getRelations()[resource] ?? {};
   const expansions = /* @__PURE__ */ new Map();
   for (const expandKey of keys) {
-    for (const [field, parentCollection] of Object.entries(resourceRelations)) {
+    for (const [field, def] of Object.entries(resourceRelations)) {
+      if (def.type === "many2many") continue;
       const derivedKey = field.replace(/Id$/i, "");
-      if (derivedKey === expandKey || parentCollection === expandKey || parentCollection === `${expandKey}s`) {
-        expansions.set(expandKey, { field, parentCollection });
+      if (derivedKey === expandKey || def.target === expandKey || def.target === `${expandKey}s`) {
+        expansions.set(expandKey, { field, parentCollection: def.target });
         break;
       }
     }
@@ -897,10 +1393,24 @@ function embedItems(input, query, resource, storage) {
   const relations = storage.getRelations();
   const embeds = /* @__PURE__ */ new Map();
   for (const embedKey of keys) {
+    const ownRelations = relations[resource] ?? {};
+    if (embedKey in ownRelations) {
+      const def = ownRelations[embedKey];
+      if (def.type === "many2many") {
+        embeds.set(embedKey, {
+          kind: "many2many",
+          target: def.target,
+          through: def.through,
+          foreignKey: def.foreignKey,
+          otherKey: def.otherKey
+        });
+        continue;
+      }
+    }
     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 });
+      for (const [fkField, def] of Object.entries(fields)) {
+        if ((def.type === "many2one" || def.type === "one2one") && def.target === resource && childCollection === embedKey) {
+          embeds.set(embedKey, { kind: def.type, childCollection, fkField });
           break outer;
         }
       }
@@ -909,10 +1419,57 @@ function embedItems(input, query, resource, storage) {
   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"])
-      );
+    for (const [embedKey, spec] of embeds) {
+      if (spec.kind === "many2many") {
+        const pivot = storage.getCollection(spec.through) ?? [];
+        const matchingIds = new Set(
+          pivot.filter((row) => String(row[spec.foreignKey]) === String(item["id"])).map((row) => String(row[spec.otherKey]))
+        );
+        out[embedKey] = (storage.getCollection(spec.target) ?? []).filter(
+          (t) => matchingIds.has(String(t["id"]))
+        );
+      } else if (spec.kind === "one2one") {
+        out[embedKey] = (storage.getCollection(spec.childCollection) ?? []).find(
+          (child) => String(child[spec.fkField]) === String(item["id"])
+        ) ?? null;
+      } else {
+        out[embedKey] = (storage.getCollection(spec.childCollection) ?? []).filter(
+          (child) => String(child[spec.fkField]) === String(item["id"])
+        );
+      }
+    }
+    return out;
+  });
+  return isArray ? result : result[0];
+}
+function applyNested(input, resource, storage) {
+  const isArray = Array.isArray(input);
+  const items = isArray ? input : [input];
+  const resourceRelations = storage.getRelations()[resource] ?? {};
+  const nestedDefs = Object.entries(resourceRelations).filter(([, def]) => def.nested === true);
+  if (nestedDefs.length === 0) return input;
+  const result = items.map((item) => {
+    const out = { ...item };
+    for (const [key, def] of nestedDefs) {
+      if (def.type === "many2many") {
+        const pivot = storage.getCollection(def.through) ?? [];
+        const matchingIds = new Set(
+          pivot.filter((row) => String(row[def.foreignKey]) === String(item["id"])).map((row) => String(row[def.otherKey]))
+        );
+        out[key] = (storage.getCollection(def.target) ?? []).filter(
+          (t) => matchingIds.has(String(t["id"]))
+        );
+      } else {
+        const foreignKeyValue = item[key];
+        if (foreignKeyValue === void 0) continue;
+        const parent = (storage.getCollection(def.target) ?? []).find(
+          (p) => String(p["id"]) === String(foreignKeyValue)
+        );
+        if (parent !== void 0) {
+          const embedKey = key.replace(/Id$/i, "");
+          out[embedKey] = parent;
+        }
+      }
     }
     return out;
   });
@@ -952,7 +1509,12 @@ var CollectionRouteCommand = class {
         const totalPages = Math.ceil(totalItems / limit) || 1;
         const data = projectFields(
           embedItems(
-            expandItems(paginate(sorted, page, limit), req.query, this.resource, this.storage),
+            expandItems(
+              applyNested(paginate(sorted, page, limit), this.resource, this.storage),
+              req.query,
+              this.resource,
+              this.storage
+            ),
             req.query,
             this.resource,
             this.storage
@@ -984,7 +1546,12 @@ var CollectionRouteCommand = class {
       }
       return projectFields(
         embedItems(
-          expandItems(result, req.query, this.resource, this.storage),
+          expandItems(
+            applyNested(result, this.resource, this.storage),
+            req.query,
+            this.resource,
+            this.storage
+          ),
           req.query,
           this.resource,
           this.storage
@@ -1165,7 +1732,12 @@ var ItemRouteCommand = class {
       const fields = (req.query["_fields"] ?? "").split(",").map((f) => f.trim()).filter(Boolean);
       return projectFields(
         embedItems(
-          expandItems(item, req.query, this.resource, this.storage),
+          expandItems(
+            applyNested(item, this.resource, this.storage),
+            req.query,
+            this.resource,
+            this.storage
+          ),
           req.query,
           this.resource,
           this.storage
@@ -1208,32 +1780,68 @@ var NestedRouteCommand = class {
   relations;
   base;
   register(server) {
-    for (const [child, fields] of Object.entries(this.relations)) {
-      for (const [field, parent] of Object.entries(fields)) {
-        const collectionPath = `${this.base}/${parent}/:id/${child}`;
-        const itemPath = `${this.base}/${parent}/:id/${child}/:childId`;
-        server.get(collectionPath, (req, reply) => {
-          const parentCollection = this.storage.getCollection(parent) ?? [];
-          const parentItem = findById(parentCollection, req.params.id);
-          if (!parentItem) return reply.status(404).send({ error: "Not found" });
-          const children = (this.storage.getCollection(child) ?? []).filter(
-            (item) => String(item[field]) === req.params.id
-          );
-          return children;
-        });
-        server.get(itemPath, (req, reply) => {
-          const parentCollection = this.storage.getCollection(parent) ?? [];
-          const parentItem = findById(parentCollection, req.params.id);
-          if (!parentItem) return reply.status(404).send({ error: "Not found" });
-          const childItem = (this.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;
-        });
+    for (const [source, fields] of Object.entries(this.relations)) {
+      for (const [key, def] of Object.entries(fields)) {
+        if (def.type === "many2many") {
+          this.registerMany2Many(server, source, key, def);
+        } else {
+          this.registerFkRelation(server, source, key, def.target, def.type);
+        }
       }
     }
   }
+  registerFkRelation(server, child, fkField, parent, type) {
+    const collectionPath = `${this.base}/${parent}/:id/${child}`;
+    const itemPath = `${this.base}/${parent}/:id/${child}/:childId`;
+    server.get(collectionPath, (req, reply) => {
+      const parentCollection = this.storage.getCollection(parent) ?? [];
+      const parentItem = findById(parentCollection, req.params.id);
+      if (!parentItem) return reply.status(404).send({ error: "Not found" });
+      const all = (this.storage.getCollection(child) ?? []).filter(
+        (item) => String(item[fkField]) === req.params.id
+      );
+      if (type === "one2one") return all[0] ?? reply.status(404).send({ error: "Not found" });
+      return all;
+    });
+    if (type === "many2one") {
+      server.get(itemPath, (req, reply) => {
+        const parentCollection = this.storage.getCollection(parent) ?? [];
+        const parentItem = findById(parentCollection, req.params.id);
+        if (!parentItem) return reply.status(404).send({ error: "Not found" });
+        const childItem = (this.storage.getCollection(child) ?? []).find(
+          (item) => String(item[fkField]) === req.params.id && String(item["id"]) === req.params.childId
+        );
+        if (!childItem) return reply.status(404).send({ error: "Not found" });
+        return childItem;
+      });
+    }
+  }
+  registerMany2Many(server, source, alias, def) {
+    server.get(`${this.base}/${source}/:id/${alias}`, (req, reply) => {
+      const sourceCollection = this.storage.getCollection(source) ?? [];
+      const sourceItem = findById(sourceCollection, req.params.id);
+      if (!sourceItem) return reply.status(404).send({ error: "Not found" });
+      const pivot = this.storage.getCollection(def.through) ?? [];
+      const matchingIds = new Set(
+        pivot.filter((row) => String(row[def.foreignKey]) === req.params.id).map((row) => String(row[def.otherKey]))
+      );
+      return (this.storage.getCollection(def.target) ?? []).filter(
+        (t) => matchingIds.has(String(t["id"]))
+      );
+    });
+    server.get(`${this.base}/${def.target}/:id/${source}`, (req, reply) => {
+      const targetCollection = this.storage.getCollection(def.target) ?? [];
+      const targetItem = findById(targetCollection, req.params.id);
+      if (!targetItem) return reply.status(404).send({ error: "Not found" });
+      const pivot = this.storage.getCollection(def.through) ?? [];
+      const matchingIds = new Set(
+        pivot.filter((row) => String(row[def.otherKey]) === req.params.id).map((row) => String(row[def.foreignKey]))
+      );
+      return (this.storage.getCollection(source) ?? []).filter(
+        (t) => matchingIds.has(String(t["id"]))
+      );
+    });
+  }
 };
 
 // src/router/routes/snapshot.routes.ts
@@ -1412,8 +2020,15 @@ function loadConfigFile(configPath) {
 
 // src/utils/handlers.ts
 import { existsSync as existsSync3 } from "fs";
+var ALLOWED_EXTENSIONS = [".js", ".mjs", ".cjs"];
 async function loadHandlers(filePath) {
   if (!existsSync3(filePath)) return /* @__PURE__ */ new Map();
+  if (!ALLOWED_EXTENSIONS.some((ext) => filePath.endsWith(ext))) {
+    console.error(
+      `  \x1B[31m[handlers] ${filePath} \u2014 only .js, .mjs and .cjs files are allowed\x1B[0m`
+    );
+    return /* @__PURE__ */ new Map();
+  }
   try {
     const mod = await import(filePath);
     const map = /* @__PURE__ */ new Map();