@yrest/cli 0.8.1 → 0.10.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 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: Luis
-    email: luis@test.com
+    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,80 @@ 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/storage/parseSchema.ts
+function parseSchema(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 [field, value] of Object.entries(fields)) {
+      const def = normaliseFieldDef(value);
+      if (def) result[collection][field] = def;
+    }
+  }
+  return result;
+}
+function normaliseFieldDef(value) {
+  if (value === "required") return { required: true };
+  if (value === "optional") return { required: false };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value;
+  const def = {};
+  if (v["required"] === true || v["required"] === false) def.required = v["required"];
+  if (typeof v["type"] === "string" && ["string", "integer", "number", "boolean", "object", "array"].includes(v["type"]))
+    def.type = v["type"];
+  if (typeof v["format"] === "string") def.format = v["format"];
+  if (Array.isArray(v["enum"])) def.enum = v["enum"];
+  if (typeof v["description"] === "string") def.description = v["description"];
+  if (v["default"] !== void 0) def.default = v["default"];
+  return def;
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -125,10 +607,12 @@ function deepCopyData(source) {
 function createYrestStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
-  const relations = raw["_rel"] ?? {};
+  const RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
+  const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const schema = parseSchema(raw["_schema"]);
   const data = Object.fromEntries(
-    Object.entries(raw).filter(([key]) => key !== "_rel" && key !== "_routes")
+    Object.entries(raw).filter(([key]) => !RESERVED.has(key))
   );
   let snapshot = {
     data: deepCopyData(data),
@@ -142,6 +626,9 @@ function createYrestStorage(filePath) {
     getRelations() {
       return relations;
     },
+    getSchema() {
+      return schema;
+    },
     getRoutes() {
       return routes;
     },
@@ -162,9 +649,9 @@ 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")
+        Object.entries(fresh).filter(([key]) => !RESERVED.has(key))
       );
       for (const key of Object.keys(data)) delete data[key];
       Object.assign(data, freshData);
@@ -247,16 +734,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",
@@ -285,7 +763,7 @@ function endpointRow(method, path, desc) {
 }
 function resourceAccordion(name, base, isOpen) {
   const p = `${base}/${name}`;
-  const singular = name.endsWith("s") ? name.slice(0, -1) : name;
+  const singular2 = name.endsWith("s") ? name.slice(0, -1) : name;
   const rows = [
     endpointRow(
       "GET",
@@ -295,20 +773,20 @@ function resourceAccordion(name, base, isOpen) {
     endpointRow(
       "POST",
       p,
-      `Create a new ${singular}. Auto-assigns <code>id</code> if not provided.`
+      `Create a new ${singular2}. Auto-assigns <code>id</code> if not provided.`
     ),
-    endpointRow("GET", `${p}/:id`, `Get a single ${singular} by id.`),
+    endpointRow("GET", `${p}/:id`, `Get a single ${singular2} by id.`),
     endpointRow(
       "PUT",
       `${p}/:id`,
-      `Fully replace a ${singular}. Original <code>id</code> is always preserved.`
+      `Fully replace a ${singular2}. Original <code>id</code> is always preserved.`
     ),
     endpointRow(
       "PATCH",
       `${p}/:id`,
-      `Partially update a ${singular} \u2014 only provided fields change.`
+      `Partially update a ${singular2} \u2014 only provided fields change.`
     ),
-    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular} and return it as confirmation.`)
+    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular2} and return it as confirmation.`)
   ].join("");
   return `
   <details class="resource-card" ${isOpen ? "open" : ""}>
@@ -321,12 +799,145 @@ 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 singular2 = 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 ${singular2} 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];
   if (firstCol) {
     const p = `${host}${base}/${firstCol}`;
-    const singular = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
+    const singular2 = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
     examples.push(
       `# List all ${firstCol}
 curl ${p}`,
@@ -334,52 +945,53 @@ curl ${p}`,
 curl "${p}?name=value"`,
       `# Sort and paginate
 curl "${p}?_sort=id&_order=desc&_page=1&_limit=5"`,
-      `# Get single ${singular}
+      `# Get single ${singular2}
 curl ${p}/1`,
-      `# Create ${singular}
+      `# Create ${singular2}
 curl -X POST ${p} \\
   -H "Content-Type: application/json" \\
   -d '{"name":"example"}'`,
-      `# Partially update ${singular}
+      `# Partially update ${singular2}
 curl -X PATCH ${p}/1 \\
   -H "Content-Type: application/json" \\
   -d '{"name":"updated"}'`,
-      `# Delete ${singular}
+      `# Delete ${singular2}
 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(
@@ -405,9 +1017,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 = [];
@@ -421,105 +1045,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);
-      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);
-  }).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">
@@ -667,10 +1192,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>
@@ -870,10 +1395,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;
       }
     }
@@ -902,10 +1428,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;
         }
       }
@@ -914,10 +1454,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;
   });
@@ -957,7 +1544,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
@@ -989,7 +1581,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
@@ -1094,7 +1691,7 @@ var CustomRouteCommand = class {
         url,
         handler: async (req, reply) => {
           if (route.delay && route.delay > 0) {
-            await new Promise((resolve5) => setTimeout(resolve5, route.delay));
+            await new Promise((resolve6) => setTimeout(resolve6, route.delay));
           }
           if (route.error) {
             const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
@@ -1170,7 +1767,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
@@ -1213,31 +1815,432 @@ 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/openapi/inferSchema.ts
+function buildCollectionSchema(items, fieldDefs = {}) {
+  const sample = items.slice(0, 10);
+  const inferredTypes = /* @__PURE__ */ new Map();
+  for (const item of sample) {
+    for (const [key, value] of Object.entries(item)) {
+      if (!inferredTypes.has(key)) {
+        inferredTypes.set(key, jsToOpenApiType(value));
+      }
+    }
+  }
+  const allFields = /* @__PURE__ */ new Set([...inferredTypes.keys(), ...Object.keys(fieldDefs)]);
+  const properties = {};
+  const required = [];
+  for (const field of allFields) {
+    const def = fieldDefs[field];
+    const inferred = inferredTypes.get(field) ?? "string";
+    const prop = {
+      type: def?.type ?? inferred
+    };
+    if (def?.format) prop.format = def.format;
+    if (def?.description) prop.description = def.description;
+    if (def?.enum) prop.enum = def.enum;
+    if (def?.default !== void 0) prop.default = def.default;
+    properties[field] = prop;
+    if (def?.required === true) required.push(field);
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+function jsToOpenApiType(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/buildPaths.ts
+var COLLECTION_QUERY_PARAMS = [
+  { name: "_page", in: "query", schema: { type: "integer" }, description: "Page number (1-based)" },
+  { name: "_limit", in: "query", schema: { type: "integer" }, description: "Items per page" },
+  { name: "_sort", in: "query", schema: { type: "string" }, description: "Field name to sort by" },
+  {
+    name: "_order",
+    in: "query",
+    schema: { type: "string", enum: ["asc", "desc"] },
+    description: "Sort direction"
+  },
+  {
+    name: "_q",
+    in: "query",
+    schema: { type: "string" },
+    description: "Full-text search across all scalar fields (case-insensitive)"
+  },
+  {
+    name: "_expand",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed related parent object inline (e.g. ?_expand=user)"
+  },
+  {
+    name: "_embed",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed child collection into each item (e.g. ?_embed=posts)"
+  },
+  {
+    name: "_fields",
+    in: "query",
+    schema: { type: "string" },
+    description: "Comma-separated field projection (e.g. ?_fields=id,name)"
+  }
+];
+var ID_PATH_PARAM = {
+  name: "id",
+  in: "path",
+  required: true,
+  schema: { type: "string" },
+  description: "Item id"
+};
+function toOpenApiPath(fastifyPath) {
+  return fastifyPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+}
+function extractPathParams(fastifyPath) {
+  const matches = fastifyPath.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g) ?? [];
+  return matches.map((m) => ({
+    name: m.slice(1),
+    in: "path",
+    required: true,
+    schema: { type: "string" }
+  }));
+}
+function singular(name) {
+  return name.endsWith("s") ? name.slice(0, -1) : name;
+}
+function schemaRef(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+function jsonContent(schema) {
+  return { "application/json": { schema } };
+}
+function ok(schema, description = "OK") {
+  return { description, content: jsonContent(schema) };
+}
+function buildCrudPaths(collection, base, schemaName) {
+  const ref = schemaRef(schemaName);
+  const tag = collection;
+  const sing = singular(collection);
+  const collPath = `${base}/${collection}`;
+  const itemPath = `${base}/${collection}/{id}`;
+  return {
+    [collPath]: {
+      get: {
+        summary: `List ${collection}`,
+        tags: [tag],
+        parameters: COLLECTION_QUERY_PARAMS,
+        responses: {
+          "200": {
+            description: "OK",
+            content: jsonContent({ type: "array", items: ref }),
+            headers: {
+              "X-Total-Count": {
+                description: "Total items (when using ?_page / ?_limit)",
+                schema: { type: "integer" }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        summary: `Create ${sing}`,
+        tags: [tag],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "201": ok(ref, "Created") }
+      }
+    },
+    [itemPath]: {
+      get: {
+        summary: `Get ${sing}`,
+        tags: [tag],
+        parameters: [
+          ID_PATH_PARAM,
+          ...COLLECTION_QUERY_PARAMS.filter(
+            (p) => ["_expand", "_embed", "_fields"].includes(p.name)
+          )
+        ],
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      put: {
+        summary: `Replace ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      patch: {
+        summary: `Update ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: false, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      delete: {
+        summary: `Delete ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        responses: { "200": ok(ref, "Deleted item returned"), "404": { description: "Not found" } }
+      }
+    }
+  };
+}
+function buildRelationPaths(relations, base) {
+  const paths = {};
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type === "many2many") {
+        const forwardPath = `${base}/${source}/{id}/${key}`;
+        const inversePath = `${base}/${def.target}/{id}/${source}`;
+        paths[forwardPath] = {
+          get: {
+            summary: `List ${def.target} linked to ${singular(source)} via ${def.through}`,
+            tags: [source],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(source)} not found` }
+            }
+          }
+        };
+        paths[inversePath] = {
+          get: {
+            summary: `List ${source} linked to ${singular(def.target)} via ${def.through} (inverse)`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(def.target)} not found` }
+            }
+          }
+        };
+      } else {
+        const parentSing = singular(def.target);
+        const collPath = `${base}/${def.target}/{id}/${source}`;
+        const isOne2One = def.type === "one2one";
+        const responseSchema = isOne2One ? { type: "object" } : { type: "array", items: { type: "object" } };
+        paths[collPath] = {
+          get: {
+            summary: isOne2One ? `Get ${singular(source)} belonging to ${parentSing}` : `List ${source} belonging to ${parentSing}`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": { description: "OK", content: jsonContent(responseSchema) },
+              "404": { description: `${parentSing} not found` }
+            }
+          }
+        };
+        if (!isOne2One) {
+          const itemPath = `${base}/${def.target}/{id}/${source}/{childId}`;
+          paths[itemPath] = {
+            get: {
+              summary: `Get single ${singular(source)} scoped to ${parentSing}`,
+              tags: [def.target],
+              parameters: [
+                ID_PATH_PARAM,
+                { name: "childId", in: "path", required: true, schema: { type: "string" } }
+              ],
+              responses: {
+                "200": { description: "OK", content: jsonContent({ type: "object" }) },
+                "404": { description: "Not found" }
+              }
+            }
+          };
+        }
+      }
+    }
+  }
+  return paths;
+}
+function buildCustomRoutePaths(routes, base) {
+  const paths = {};
+  for (const route of routes) {
+    const openApiPath = toOpenApiPath(`${base}${route.path}`);
+    const method = route.method.toLowerCase();
+    const pathParams = extractPathParams(route.path);
+    const responses = {};
+    if (route.error) {
+      responses[String(route.error)] = { description: `Forced error ${route.error}` };
+    } else {
+      const statuses = /* @__PURE__ */ new Set();
+      for (const s of route.scenarios ?? []) statuses.add(s.response.status ?? 200);
+      if (route.otherwise) statuses.add(route.otherwise.status ?? 200);
+      if (route.response) statuses.add(route.response.status ?? 200);
+      if (statuses.size === 0) statuses.add(200);
+      for (const status of statuses) {
+        const bodySource = (route.scenarios ?? []).find((s) => (s.response.status ?? 200) === status)?.response.body ?? (route.otherwise?.status ?? 200) === status ? route.otherwise?.body : route.response?.body;
+        responses[String(status)] = {
+          description: status < 400 ? "OK" : "Error",
+          ...bodySource != null ? { content: jsonContent(inferResponseSchema(bodySource)) } : {}
+        };
       }
     }
+    const desc = route.handler ? `Handler: ${route.handler}()` : route.scenarios?.length ? `Conditional scenarios (${route.scenarios.length})` : "Custom static route";
+    const operation = {
+      summary: `${route.method.toUpperCase()} ${route.path}`,
+      description: desc,
+      tags: ["custom"],
+      ...pathParams.length > 0 ? { parameters: pathParams } : {},
+      responses
+    };
+    if (!paths[openApiPath]) paths[openApiPath] = {};
+    paths[openApiPath][method] = operation;
+  }
+  return paths;
+}
+function inferResponseSchema(body) {
+  if (body === null || body === void 0) return {};
+  if (typeof body !== "object" || Array.isArray(body)) return { type: "object" };
+  const properties = {};
+  for (const [key, value] of Object.entries(body)) {
+    properties[key] = { type: jsToOpenApiType2(value) };
+  }
+  return { type: "object", properties };
+}
+function jsToOpenApiType2(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/generateOpenApi.ts
+function generateOpenApi(storage, options, title = "yRest API") {
+  const collections = Object.keys(storage.getData());
+  const relations = storage.getRelations();
+  const schemaBlock = storage.getSchema();
+  const customRoutes = storage.getRoutes();
+  const base = options.base ?? "";
+  const schemas = {};
+  for (const collection of collections) {
+    const items = storage.getCollection(collection) ?? [];
+    const fieldDefs = schemaBlock[collection] ?? {};
+    const schemaName = toSchemaName(collection);
+    schemas[schemaName] = buildCollectionSchema(items, fieldDefs);
+  }
+  const paths = {};
+  for (const collection of collections) {
+    const schemaName = toSchemaName(collection);
+    Object.assign(paths, buildCrudPaths(collection, base, schemaName));
+  }
+  Object.assign(paths, buildRelationPaths(relations, base));
+  Object.assign(paths, buildCustomRoutePaths(customRoutes, base));
+  return {
+    openapi: "3.0.3",
+    info: {
+      title,
+      version: "1.0.0",
+      description: "Generated by yRest from db.yml"
+    },
+    servers: [
+      {
+        url: `http://${options.host}:${options.port}${base}`,
+        description: "yRest mock server"
+      }
+    ],
+    paths,
+    components: { schemas }
+  };
+}
+function toSchemaName(collection) {
+  const withoutS = collection.endsWith("s") ? collection.slice(0, -1) : collection;
+  return withoutS.charAt(0).toUpperCase() + withoutS.slice(1);
+}
+
+// src/router/routes/openapi.routes.ts
+import { stringify as stringify2 } from "yaml";
+var OpenApiRouteCommand = class {
+  constructor(storage, options) {
+    this.storage = storage;
+    this.options = options;
+  }
+  storage;
+  options;
+  register(server) {
+    server.get("/_openapi", (_req, reply) => {
+      const doc = generateOpenApi(this.storage, this.options);
+      reply.header("Content-Type", "text/yaml; charset=utf-8");
+      return reply.send(stringify2(doc, { lineWidth: 0, aliasDuplicateObjects: false }));
+    });
+    server.get("/_openapi.json", (_req, reply) => {
+      return reply.send(generateOpenApi(this.storage, this.options));
+    });
   }
 };
 
@@ -1321,6 +2324,7 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   }
   const commands = [
     new AboutRouteCommand(storage, options, handlers),
+    new OpenApiRouteCommand(storage, options),
     ...options.snapshot ? [new SnapshotRouteCommand(storage)] : [],
     new CustomRouteCommand(storage, options.base, handlers),
     ...buildResourceRouteCommands(storage, options)
@@ -1565,7 +2569,7 @@ function registerServe(program2) {
 // src/cli/commands/handler.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, appendFileSync, writeFileSync as writeFileSync3 } from "fs";
 import { join as join3, resolve as resolve4, basename } from "path";
-import { parse as parse3, stringify as stringify2 } from "yaml";
+import { parse as parse3, stringify as stringify3 } from "yaml";
 var HANDLERS_FILE_HEADER = `// yrest handlers \u2014 loaded via "handlers:" in yrest.config.yml
 // Handler signature: (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>
 // See https://github.com/aggiovato/yaml-rest for full documentation
@@ -1627,7 +2631,7 @@ function registerHandler(program2) {
       const alreadyRegistered = routes.some((r) => r["handler"] === name);
       if (!alreadyRegistered) {
         routes.push({ method: flags.method.toUpperCase(), path: flags.path, handler: name });
-        writeFileSync3(dbPath, stringify2(raw), "utf8");
+        writeFileSync3(dbPath, stringify3(raw), "utf8");
         console.log(`  Added _routes entry to ${basename(dbPath)}`);
       } else {
         console.log(`  Handler "${name}" already in _routes \u2014 skipped`);
@@ -1650,6 +2654,33 @@ function registerHandler(program2) {
   });
 }
 
+// src/cli/commands/openapi.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+import { resolve as resolve5 } from "path";
+import { stringify as stringify4 } from "yaml";
+function registerOpenApi(program2) {
+  program2.command("openapi <file>").description("Generate an OpenAPI 3.0 spec from a db.yml file").option("-o, --output <file>", "Output file (default: openapi.yaml / openapi.json)").option("--format <fmt>", "Output format: yaml (default) or json", "yaml").option("--stdout", "Print to stdout instead of writing a file").option("--base <base>", "Base path prefix applied to all routes", "").option("--port <port>", "Server port shown in the servers block", "3070").option("--host <host>", "Server host shown in the servers block", "localhost").option("--title <title>", "API title for the info block", "yRest API").action((file, opts) => {
+    const storage = createYrestStorage(resolve5(file));
+    const options = yrestOptionsSchema.parse({
+      file,
+      base: opts["base"] || void 0,
+      port: Number(opts["port"]) || 3070,
+      host: opts["host"] || "localhost"
+    });
+    const doc = generateOpenApi(storage, options, opts["title"]);
+    const isJson = opts["format"] === "json";
+    const output = isJson ? JSON.stringify(doc, null, 2) : stringify4(doc, { lineWidth: 0, aliasDuplicateObjects: false });
+    if (opts["stdout"]) {
+      process.stdout.write(output);
+      return;
+    }
+    const defaultFile = isJson ? "openapi.json" : "openapi.yaml";
+    const outFile = resolve5(opts["output"] ?? defaultFile);
+    writeFileSync4(outFile, output, "utf8");
+    console.log(`\u2713  OpenAPI spec written to ${outFile}`);
+  });
+}
+
 // src/cli/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../../package.json");
@@ -1657,4 +2688,5 @@ program.name("yrest").description("Zero-config REST API mock server powered by a
 registerInit(program);
 registerServe(program);
 registerHandler(program);
+registerOpenApi(program);
 program.parse();