@yrest/cli 0.11.2 → 0.13.0

package/dist/cli/index.mjs

@@ -88,6 +88,7 @@ categories:
 // src/cli/commands/templates/relational.ts
 var relationalTemplate = `# yrest relational sample \u2014 blog
 # Demonstrates: many2one, one2one and many2many relationships
+# Also shows __uuid_gen and __fk directives for UUID-based IDs
 # Run: npx @yrest/cli serve db.yml
 # Docs: GET http://localhost:3070/_about
 
@@ -112,33 +113,36 @@ _rel:
       _type: one2one
       _target: users
 
+# __uuid_gen:alias generates a UUID and registers it under that alias.
+# __fk.collection:alias resolves to the UUID registered in that collection.
+# yRest rewrites this file on first run, replacing all directives with real values.
 users:
-  - id: 1
+  - id: __uuid_gen:ana
     name: Ana Garc\xEDa
     email: ana@example.com
     role: author
-  - id: 2
+  - id: __uuid_gen:luis
     name: Luis Mart\xEDnez
     email: luis@example.com
     role: author
-  - id: 3
+  - id: __uuid_gen:sara
     name: Sara L\xF3pez
     email: sara@example.com
     role: reader
 
 profiles:
-  - id: 1
-    userId: 1
+  - id: __uuid_gen
+    userId: __fk.users:ana
     bio: Full-stack developer and open-source enthusiast
     avatar: https://i.pravatar.cc/150?img=1
     website: https://ana.dev
-  - id: 2
-    userId: 2
+  - id: __uuid_gen
+    userId: __fk.users:luis
     bio: Backend engineer, coffee addict
     avatar: https://i.pravatar.cc/150?img=2
     website: https://luisdev.io
-  - id: 3
-    userId: 3
+  - id: __uuid_gen
+    userId: __fk.users:sara
     bio: Designer turned frontend developer
     avatar: https://i.pravatar.cc/150?img=3
     website: null
@@ -161,75 +165,75 @@ tags:
     color: "#ef4444"
 
 posts:
-  - id: 1
+  - id: __uuid_gen:post-ts
     title: Getting started with TypeScript
     slug: getting-started-typescript
     body: TypeScript adds static typing to JavaScript, catching errors at compile time...
-    userId: 1
+    userId: __fk.users:ana
     published: true
     views: 1420
     createdAt: "2024-11-01"
-  - id: 2
+  - id: __uuid_gen:post-fastify
     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
+    userId: __fk.users:ana
     published: true
     views: 980
     createdAt: "2024-11-15"
-  - id: 3
+  - id: __uuid_gen:post-testing
     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
+    userId: __fk.users:luis
     published: true
     views: 640
     createdAt: "2024-12-03"
-  - id: 4
+  - id: __uuid_gen:post-yaml
     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
+    userId: __fk.users:luis
     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 }
+  - { id: 1, postId: __fk.posts:post-ts,      tagId: 1 }
+  - { id: 2, postId: __fk.posts:post-ts,      tagId: 2 }
+  - { id: 3, postId: __fk.posts:post-fastify, tagId: 2 }
+  - { id: 4, postId: __fk.posts:post-fastify, tagId: 4 }
+  - { id: 5, postId: __fk.posts:post-testing, tagId: 3 }
+  - { id: 6, postId: __fk.posts:post-testing, tagId: 1 }
+  - { id: 7, postId: __fk.posts:post-yaml,    tagId: 5 }
+  - { id: 8, postId: __fk.posts:post-yaml,    tagId: 2 }
 
 comments:
   - id: 1
     body: Great introduction! This helped me a lot.
-    postId: 1
-    userId: 3
+    postId: __fk.posts:post-ts
+    userId: __fk.users:sara
     likes: 5
   - id: 2
     body: Could you cover generics in a follow-up post?
-    postId: 1
-    userId: 2
+    postId: __fk.posts:post-ts
+    userId: __fk.users:luis
     likes: 3
   - id: 3
     body: Fastify is indeed much faster than Express in my benchmarks.
-    postId: 2
-    userId: 3
+    postId: __fk.posts:post-fastify
+    userId: __fk.users:sara
     likes: 8
   - id: 4
     body: Do you have a GitHub repo with these examples?
-    postId: 2
-    userId: 1
+    postId: __fk.posts:post-fastify
+    userId: __fk.users:ana
     likes: 1
   - id: 5
     body: E2E tests are underrated. Solid post!
-    postId: 3
-    userId: 1
+    postId: __fk.posts:post-testing
+    userId: __fk.users:ana
     likes: 4
 
 # Try these queries:
@@ -519,7 +523,7 @@ import { join as join2, resolve as resolve3 } from "path";
 // src/storage/yrestStorage.ts
 import { readFileSync, writeFileSync as writeFileSync2, renameSync } from "fs";
 import { resolve as resolve2, dirname } from "path";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { parse, stringify } from "yaml";
 
 // src/storage/parseRelations.ts
@@ -637,6 +641,8 @@ function normaliseRoute(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
   const v = raw;
   const method = v["_method"];
+  if (typeof method === "string" && method.toUpperCase() === "SSE") return null;
+  if ("_sse" in v) return null;
   const path = v["_path"];
   if (typeof method !== "string" || typeof path !== "string") return null;
   const route = { method, path };
@@ -676,6 +682,43 @@ function normaliseScenario(raw) {
   return { when, response };
 }
 
+// src/storage/parseSseRoutes.ts
+function parseSseRoutes(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(normaliseSseRoute).filter((r) => r !== null);
+}
+function normaliseSseRoute(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const v = raw;
+  const method = typeof v["_method"] === "string" ? v["_method"].toUpperCase() : null;
+  const path = v["_path"];
+  const sse = v["_sse"];
+  if (method !== "SSE") return null;
+  if (typeof path !== "string" || !sse || typeof sse !== "object" || Array.isArray(sse)) {
+    return null;
+  }
+  const s = sse;
+  const rawEvents = s["_events"];
+  if (!Array.isArray(rawEvents)) return null;
+  const events = rawEvents.map(normaliseEvent).filter((e) => e !== null);
+  if (!events.length) return null;
+  return {
+    path,
+    interval: typeof s["_interval"] === "number" ? s["_interval"] : 1e3,
+    loop: s["_loop"] !== false,
+    repeat: typeof s["_repeat"] === "number" ? s["_repeat"] : void 0,
+    events
+  };
+}
+function normaliseEvent(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const v = raw;
+  if (!("_data" in v)) return null;
+  const event = { data: v["_data"] };
+  if (typeof v["_event"] === "string") event.event = v["_event"];
+  return event;
+}
+
 // src/storage/parseSchema.ts
 function parseSchema(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
@@ -752,6 +795,51 @@ function hasDataBlock(raw) {
   return d !== null && d !== void 0 && typeof d === "object" && !Array.isArray(d);
 }
 
+// src/storage/resolveDirectives.ts
+import { randomUUID } from "crypto";
+var UUID_GEN_RE = /^__uuid_gen(?::([a-zA-Z0-9_-]+))?$/;
+var FK_RE = /^__fk\.([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)$/;
+function resolveDirectives(data) {
+  const registry = /* @__PURE__ */ new Map();
+  let modified = false;
+  for (const [collection, items] of Object.entries(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = UUID_GEN_RE.exec(value);
+        if (!m) continue;
+        const uuid = randomUUID();
+        item[field] = uuid;
+        modified = true;
+        const alias = m[1];
+        if (alias) {
+          if (!registry.has(collection)) registry.set(collection, /* @__PURE__ */ new Map());
+          registry.get(collection).set(alias, uuid);
+        }
+      }
+    }
+  }
+  for (const items of Object.values(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = FK_RE.exec(value);
+        if (!m) continue;
+        const col = m[1];
+        const alias = m[2];
+        const uuid = registry.get(col)?.get(alias);
+        if (uuid !== void 0) {
+          item[field] = uuid;
+          modified = true;
+        } else {
+          console.warn(`yrest: cannot resolve __fk.${col}:${alias} \u2014 alias not registered`);
+        }
+      }
+    }
+  }
+  return modified;
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -819,15 +907,17 @@ function createYrestStorage(filePath) {
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
   const relations = parseRelations(raw["_rel"]);
   const routes = parseRoutes(raw["_routes"]);
+  const sseRoutes = parseSseRoutes(raw["_routes"]);
   const schema = parseSchema(raw["_schema"]);
   const dataBlock = hasDataBlock(raw);
   const data = parseData(raw);
+  const directivesModified = resolveDirectives(data);
   let snapshot = {
     data: deepCopyData(data),
     relations: { ...relations },
     savedAt: /* @__PURE__ */ new Date()
   };
-  return {
+  const storage = {
     getData() {
       return data;
     },
@@ -840,6 +930,9 @@ function createYrestStorage(filePath) {
     getRoutes() {
       return routes;
     },
+    getSseRoutes() {
+      return sseRoutes;
+    },
     getCollection(name) {
       return data[name];
     },
@@ -855,7 +948,7 @@ function createYrestStorage(filePath) {
       } else {
         Object.assign(payload, data);
       }
-      const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID()}.tmp`);
+      const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID2()}.tmp`);
       writeFileSync2(tmp, stringify(payload), "utf8");
       renameSync(tmp, absPath);
     },
@@ -867,6 +960,7 @@ function createYrestStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+      if (resolveDirectives(data)) storage.persist();
     },
     getSnapshot() {
       return snapshot;
@@ -887,6 +981,8 @@ function createYrestStorage(filePath) {
       this.persist();
     }
   };
+  if (directivesModified) storage.persist();
+  return storage;
 }
 
 // src/server/createServer.ts
@@ -899,7 +995,7 @@ import { dirname as dirname2, join } from "path";
 import { fileURLToPath } from "url";
 
 // src/utils/interpolate.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 function getPath(obj, path) {
   return path.split(".").reduce((acc, key) => {
     if (acc != null && typeof acc === "object") return acc[key];
@@ -908,7 +1004,7 @@ function getPath(obj, path) {
 }
 function resolveVar(path, ctx) {
   if (path === "now") return (/* @__PURE__ */ new Date()).toISOString();
-  if (path === "uuid") return randomUUID2();
+  if (path === "uuid") return randomUUID3();
   if (path === "body") return ctx.body;
   if (path.startsWith("body.")) return getPath(ctx.body, path.slice(5));
   if (path.startsWith("params.")) return ctx.params[path.slice(7)] ?? "";
@@ -951,6 +1047,8 @@ var METHOD_COLOR = {
   PUT: "#d29922",
   PATCH: "#a371f7",
   DELETE: "#f85149",
+  SSE: "#0ea5e9",
+  WS: "#8b5cf6",
   fn: "#f0883e"
 };
 function escapeHtml(str) {
@@ -1142,6 +1240,30 @@ function handlersAccordion(handlers, routes, base) {
     </tbody></table>
   </details>`;
 }
+function sseRoutesAccordion(routes, base) {
+  if (!routes.length) return "";
+  const rows = routes.map((r) => {
+    const tags = [
+      `<span style="color:#0ea5e9;font-size:11px">interval\xB7${r.interval}ms</span>`,
+      `<span style="color:var(--text-muted);font-size:11px">${r.events.length} event${r.events.length !== 1 ? "s" : ""}</span>`
+    ];
+    if (!r.loop) tags.push(`<span style="color:var(--text-muted);font-size:11px">no\xB7loop</span>`);
+    if (r.repeat !== void 0)
+      tags.push(`<span style="color:var(--text-muted);font-size:11px">repeat\xB7${r.repeat}\xD7</span>`);
+    const desc = `SSE stream&ensp;${tags.join("&ensp;")}`;
+    return endpointRow("SSE", `${base}${r.path}`, desc);
+  });
+  return `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">SSE streams</span>
+      <span class="route-count">${routes.length} stream${routes.length !== 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];
@@ -1812,6 +1934,7 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
   const collections = Object.keys(storage.getData());
   const relations = storage.getRelations();
   const customRoutes = storage.getRoutes();
+  const sseRoutes = storage.getSseRoutes();
   const base = options.base;
   const host = `http://${options.host}:${options.port}`;
   const swaggerUrl = `https://petstore.swagger.io/?url=${encodeURIComponent(`${host}/_openapi.json`)}`;
@@ -1995,6 +2118,7 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
           ${accordions}
           ${nestedRoutesAccordion(relations, base)}
           ${options.snapshot ? snapshotAccordion() : ""}
+          ${sseRoutesAccordion(sseRoutes, base)}
           ${customRoutesAccordion(customRoutes, base, handlers)}
           ${handlersAccordion(handlers, customRoutes, base)}
         </div>
@@ -3125,6 +3249,79 @@ var SnapshotRouteCommand = class {
   }
 };
 
+// src/router/routes/sse.routes.ts
+var SSERouteCommand = class {
+  constructor(storage, base) {
+    this.storage = storage;
+    this.base = base;
+  }
+  storage;
+  base;
+  register(server) {
+    for (const route of this.storage.getSseRoutes()) {
+      const url = `${this.base}${route.path}`;
+      server.route({
+        method: "GET",
+        url,
+        handler: async (req, reply) => {
+          reply.hijack();
+          const raw = reply.raw;
+          raw.setHeader("Content-Type", "text/event-stream");
+          raw.setHeader("Cache-Control", "no-cache");
+          raw.setHeader("Connection", "keep-alive");
+          raw.setHeader("Access-Control-Allow-Origin", "*");
+          raw.flushHeaders();
+          let alive = true;
+          req.raw.on("close", () => {
+            alive = false;
+          });
+          const keepAlive = setInterval(() => {
+            if (alive) raw.write(": ping\n\n");
+          }, 15e3);
+          let frameIndex = 0;
+          let cycleCount = 0;
+          function sendNext() {
+            if (!alive) {
+              clearInterval(keepAlive);
+              return;
+            }
+            const ev = route.events[frameIndex];
+            const ctx = {
+              params: req.params,
+              query: req.query,
+              body: null,
+              headers: req.headers
+            };
+            const data = hasTemplates(ev.data) ? interpolate(ev.data, ctx) : ev.data;
+            let chunk = "";
+            if (ev.event) chunk += `event: ${ev.event}
+`;
+            chunk += `data: ${JSON.stringify(data)}
+
+`;
+            raw.write(chunk);
+            frameIndex++;
+            if (frameIndex >= route.events.length) {
+              frameIndex = 0;
+              cycleCount++;
+              const done = !route.loop || route.repeat !== void 0 && cycleCount >= route.repeat;
+              if (done) {
+                clearInterval(keepAlive);
+                raw.end();
+                return;
+              }
+            }
+            if (alive) {
+              setTimeout(sendNext, route.interval);
+            }
+          }
+          sendNext();
+        }
+      });
+    }
+  }
+};
+
 // src/router/resource.router.ts
 function buildResourceRouteCommands(storage, options) {
   const commands = [];
@@ -3166,6 +3363,7 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
     new AboutRouteCommand(storage, options, handlers),
     new OpenApiRouteCommand(storage, options),
     ...options.snapshot ? [new SnapshotRouteCommand(storage)] : [],
+    new SSERouteCommand(storage, options.base),
     new CustomRouteCommand(storage, options.base, handlers),
     ...buildResourceRouteCommands(storage, options)
   ];
@@ -3311,11 +3509,18 @@ function registerServe(program2) {
     "--id-strategy <strategy>",
     "Id generation strategy for new items: increment (default) or uuid",
     "increment"
+  ).option(
+    "--uuid",
+    "Shorthand for --id-strategy uuid: assign UUID ids to new items created via POST"
   ).action(async (file, flags, cmd) => {
     const fileConfig = loadConfigFile(join2(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
       Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
     );
+    if (cliOverrides["uuid"] === true) {
+      cliOverrides["idStrategy"] = "uuid";
+      delete cliOverrides["uuid"];
+    }
     const options = buildServeOptions(file, fileConfig, cliOverrides, cmd.args.length > 0);
     let storage;
     try {

package/dist/index.d.mts

@@ -284,6 +284,42 @@ type CustomRoute = {
     /** Optional body to return alongside `error:`. Defaults to `{ error: "Forced error <status>" }`. */
     errorBody?: unknown;
 };
+/** A single event in an SSE stream declared under `_sse._events`. */
+type SseEvent = {
+    /** SSE event name emitted as `event: <name>`. Omit for unnamed events. */
+    event?: string;
+    /** Payload serialised as JSON in the `data:` line. Supports `{{}}` templates. */
+    data: unknown;
+};
+/**
+ * A Server-Sent Events stream route declared under `_routes` with an `_sse` block.
+ *
+ * @example
+ * ```yaml
+ * _routes:
+ *   - _method: GET
+ *     _path: /events/orders
+ *     _sse:
+ *       _interval: 1500
+ *       _loop: true
+ *       _repeat: 5
+ *       _events:
+ *         - _event: update
+ *           _data: { orderId: 1, status: processing }
+ * ```
+ */
+type SseRoute = {
+    /** URL path. May include Fastify path params (e.g. `/events/:id`). */
+    path: string;
+    /** Milliseconds between frames. Default: `1000`. */
+    interval: number;
+    /** Restart the sequence after the last event. Default: `true`. */
+    loop: boolean;
+    /** Stop after this many full cycles. Omit for infinite. */
+    repeat?: number;
+    /** Ordered list of events to emit. */
+    events: SseEvent[];
+};
 /**
  * In-memory store backed by a YAML file.
  *
@@ -336,6 +372,11 @@ interface YrestStorage {
      * Returns an empty array if no `_routes` block is present.
      */
     getRoutes(): CustomRoute[];
+    /**
+     * Returns the SSE stream routes declared under `_routes` (entries with an `_sse` block).
+     * Returns an empty array if none are present.
+     */
+    getSseRoutes(): SseRoute[];
     /**
      * Returns the saved snapshot: a frozen copy of `data` and `relations` taken
      * at the last call to {@link saveSnapshot} (or at construction time).

package/dist/index.d.ts

@@ -284,6 +284,42 @@ type CustomRoute = {
     /** Optional body to return alongside `error:`. Defaults to `{ error: "Forced error <status>" }`. */
     errorBody?: unknown;
 };
+/** A single event in an SSE stream declared under `_sse._events`. */
+type SseEvent = {
+    /** SSE event name emitted as `event: <name>`. Omit for unnamed events. */
+    event?: string;
+    /** Payload serialised as JSON in the `data:` line. Supports `{{}}` templates. */
+    data: unknown;
+};
+/**
+ * A Server-Sent Events stream route declared under `_routes` with an `_sse` block.
+ *
+ * @example
+ * ```yaml
+ * _routes:
+ *   - _method: GET
+ *     _path: /events/orders
+ *     _sse:
+ *       _interval: 1500
+ *       _loop: true
+ *       _repeat: 5
+ *       _events:
+ *         - _event: update
+ *           _data: { orderId: 1, status: processing }
+ * ```
+ */
+type SseRoute = {
+    /** URL path. May include Fastify path params (e.g. `/events/:id`). */
+    path: string;
+    /** Milliseconds between frames. Default: `1000`. */
+    interval: number;
+    /** Restart the sequence after the last event. Default: `true`. */
+    loop: boolean;
+    /** Stop after this many full cycles. Omit for infinite. */
+    repeat?: number;
+    /** Ordered list of events to emit. */
+    events: SseEvent[];
+};
 /**
  * In-memory store backed by a YAML file.
  *
@@ -336,6 +372,11 @@ interface YrestStorage {
      * Returns an empty array if no `_routes` block is present.
      */
     getRoutes(): CustomRoute[];
+    /**
+     * Returns the SSE stream routes declared under `_routes` (entries with an `_sse` block).
+     * Returns an empty array if none are present.
+     */
+    getSseRoutes(): SseRoute[];
     /**
      * Returns the saved snapshot: a frozen copy of `data` and `relations` taken
      * at the last call to {@link saveSnapshot} (or at construction time).