@yrest/cli 0.11.2 → 0.12.0

package/README.md

@@ -10,7 +10,7 @@
 [![CI](https://github.com/aggiovato/yRest/actions/workflows/ci.yml/badge.svg)](https://github.com/aggiovato/yRest/actions)
 [![Node](https://img.shields.io/node/v/@yrest/cli)](https://www.npmjs.com/package/@yrest/cli)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.typescriptlang.org/)
-[![Socket](https://badge.socket.dev/npm/package/@yrest/cli/0.11.2)](https://socket.dev/npm/package/@yrest/cli)
+[![Socket](https://badge.socket.dev/npm/package/@yrest/cli/0.12.0)](https://socket.dev/npm/package/@yrest/cli)
 
 YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a `db.yml` file.
 
@@ -75,6 +75,7 @@ A YAML-first alternative to json-server for frontend development.
 | OpenAPI 3.0 spec (`GET /_openapi`, `yrest openapi`) |  ✅   |     ❌      |
 | Field annotations (`_schema`)                       |  ✅   |     ❌      |
 | Compact relation DSL (`m2o:target@fk[card]+nested`) |  ✅   |     ❌      |
+| SSE stream routes (`_method: SSE`)                  |  ✅   |     ❌      |
 
 ---
 
@@ -935,6 +936,76 @@ type Handler = (req: HandlerRequest) => HandlerResponse | Promise<HandlerRespons
 
 If a named handler is not found in the file, the server returns `501`. If the handler throws, it returns `500`. If a `response:` block is defined alongside `handler:`, it is used as fallback only when the handler itself throws.
 
+### SSE streams
+
+Mock Server-Sent Events streams by adding `_method: SSE` and an `_sse` block to a `_routes` entry. Clients connect with a regular `GET` request and receive a continuous stream of events until the connection is closed.
+
+```yaml
+_routes:
+  - _method: SSE
+    _path: /events/orders
+    _sse:
+      _interval: 1500 # ms between frames (default: 1000)
+      _loop: true # restart after last event (default: true)
+      _repeat: 3 # stop after N full cycles (omit = infinite)
+      _events:
+        - _event: update
+          _data:
+            orderId: 1
+            status: processing
+        - _event: update
+          _data:
+            orderId: 1
+            status: shipped
+        - _event: done
+          _data:
+            orderId: 1
+            status: delivered
+```
+
+**`_sse` options:**
+
+| Key         | Default | Description                                                                                          |
+| ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `_interval` | `1000`  | Milliseconds between frames                                                                          |
+| `_loop`     | `true`  | Restart the sequence after the last frame. Set to `false` to close after one cycle                   |
+| `_repeat`   | —       | Stop after N complete cycles and close the stream. Omit for infinite                                 |
+| `_events`   | —       | Ordered list of frames. Each entry needs `_data` (required) and optionally `_event` (SSE event name) |
+
+**Template variables** — resolved per frame at emit time, so each event gets a fresh value:
+
+```yaml
+_events:
+  - _event: tick
+    _data:
+      ts: "{{now}}" # ISO timestamp, unique per frame
+      id: "{{uuid}}" # random UUID v4
+      channel: "{{params.channel}}" # from URL params
+      filter: "{{query.filter}}" # from query string
+```
+
+**Consuming from the browser:**
+
+```js
+const es = new EventSource("http://localhost:3070/events/orders");
+
+es.addEventListener("update", (e) => console.log(JSON.parse(e.data)));
+es.addEventListener("done", (e) => {
+  console.log(JSON.parse(e.data));
+  es.close();
+});
+```
+
+**Consuming from the terminal:**
+
+```bash
+curl -N http://localhost:3070/events/orders
+```
+
+The `-N` flag disables curl's output buffering, which is required to see SSE frames as they arrive.
+
+A keep-alive comment (`: ping`) is sent every 15 s to prevent proxy timeouts. SSE routes are shown in `/_about` under their own **SSE streams** accordion with a sky-blue `SSE` badge.
+
 ---
 
 ## Server modes
@@ -1252,6 +1323,9 @@ const server = createYrestServer({
 | Explicit relation types (one2one, many2many)       | ✅     |
 | Bidirectional many2many nested routes              | ✅     |
 | Auto-embedding (`nested: true` in `_rel`)          | ✅     |
+| SSE stream routes (`_method: SSE`)                 | ✅     |
+| WebSocket mock channels (`_method: WS`)            | 🔜     |
+| TypeScript handlers + typed collections            | 🔜     |
 
 ---
 

package/dist/cli/index.js

@@ -664,6 +664,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 };
@@ -703,6 +705,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 {};
@@ -846,6 +885,7 @@ function createYrestStorage(filePath) {
   const raw = (0, import_yaml.parse)((0, import_node_fs2.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);
@@ -867,6 +907,9 @@ function createYrestStorage(filePath) {
     getRoutes() {
       return routes;
     },
+    getSseRoutes() {
+      return sseRoutes;
+    },
     getCollection(name) {
       return data[name];
     },
@@ -978,6 +1021,8 @@ var METHOD_COLOR = {
   PUT: "#d29922",
   PATCH: "#a371f7",
   DELETE: "#f85149",
+  SSE: "#0ea5e9",
+  WS: "#8b5cf6",
   fn: "#f0883e"
 };
 function escapeHtml(str) {
@@ -1169,6 +1214,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];
@@ -1839,6 +1908,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`)}`;
@@ -2022,6 +2092,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>
@@ -3152,6 +3223,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 = [];
@@ -3193,6 +3337,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)
   ];

package/dist/cli/index.mjs

@@ -637,6 +637,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 +678,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 {};
@@ -819,6 +858,7 @@ 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);
@@ -840,6 +880,9 @@ function createYrestStorage(filePath) {
     getRoutes() {
       return routes;
     },
+    getSseRoutes() {
+      return sseRoutes;
+    },
     getCollection(name) {
       return data[name];
     },
@@ -951,6 +994,8 @@ var METHOD_COLOR = {
   PUT: "#d29922",
   PATCH: "#a371f7",
   DELETE: "#f85149",
+  SSE: "#0ea5e9",
+  WS: "#8b5cf6",
   fn: "#f0883e"
 };
 function escapeHtml(str) {
@@ -1142,6 +1187,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 +1881,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 +2065,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 +3196,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 +3310,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)
   ];

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).

package/dist/index.js

@@ -153,6 +153,49 @@ var init_parseRelations = __esm({
   }
 });
 
+// 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;
+}
+var init_parseSseRoutes = __esm({
+  "src/storage/parseSseRoutes.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
 // src/storage/parseSchema.ts
 function parseSchema(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
@@ -241,6 +284,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 };
@@ -374,6 +419,7 @@ function createYrestStorage(filePath) {
   const raw = (0, import_yaml3.parse)((0, import_node_fs3.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);
@@ -395,6 +441,9 @@ function createYrestStorage(filePath) {
     getRoutes() {
       return routes;
     },
+    getSseRoutes() {
+      return sseRoutes;
+    },
     getCollection(name) {
       return data[name];
     },
@@ -454,6 +503,7 @@ var init_yrestStorage = __esm({
     import_yaml3 = require("yaml");
     init_parseRelations();
     init_parseRoutes();
+    init_parseSseRoutes();
     init_parseSchema();
     init_parseData();
     init_deepCopy();
@@ -519,6 +569,7 @@ function dedent(str) {
 init_cjs_shims();
 var import_node_path3 = require("path");
 init_parseRelations();
+init_parseSseRoutes();
 init_parseSchema();
 
 // src/utils/handlers.ts
@@ -630,6 +681,8 @@ var METHOD_COLOR = {
   PUT: "#d29922",
   PATCH: "#a371f7",
   DELETE: "#f85149",
+  SSE: "#0ea5e9",
+  WS: "#8b5cf6",
   fn: "#f0883e"
 };
 function escapeHtml(str) {
@@ -821,6 +874,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];
@@ -1493,6 +1570,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`)}`;
@@ -1676,6 +1754,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>
@@ -2828,6 +2907,80 @@ var SnapshotRouteCommand = class {
   }
 };
 
+// src/router/routes/sse.routes.ts
+init_cjs_shims();
+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 = [];
@@ -2869,6 +3022,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)
   ];
@@ -2950,6 +3104,7 @@ function createInMemoryStorage(data) {
   const RESERVED2 = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const sseRoutes = parseSseRoutes(raw["_routes"]);
   const schema = parseSchema(raw["_schema"]);
   const collections = Object.fromEntries(
     Object.entries(raw).filter(([k]) => !RESERVED2.has(k))
@@ -2964,6 +3119,7 @@ function createInMemoryStorage(data) {
     getRelations: () => relations,
     getSchema: () => schema,
     getRoutes: () => routes,
+    getSseRoutes: () => sseRoutes,
     getCollection: (name) => collections[name],
     setCollection: (name, items) => {
       collections[name] = items;

package/dist/index.mjs

@@ -130,6 +130,49 @@ var init_parseRelations = __esm({
   }
 });
 
+// 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 path2 = v["_path"];
+  const sse = v["_sse"];
+  if (method !== "SSE") return null;
+  if (typeof path2 !== "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: path2,
+    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;
+}
+var init_parseSseRoutes = __esm({
+  "src/storage/parseSseRoutes.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/storage/parseSchema.ts
 function parseSchema(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
@@ -218,6 +261,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 path2 = v["_path"];
   if (typeof method !== "string" || typeof path2 !== "string") return null;
   const route = { method, path: path2 };
@@ -355,6 +400,7 @@ function createYrestStorage(filePath) {
   const raw = parse2(readFileSync2(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);
@@ -376,6 +422,9 @@ function createYrestStorage(filePath) {
     getRoutes() {
       return routes;
     },
+    getSseRoutes() {
+      return sseRoutes;
+    },
     getCollection(name) {
       return data[name];
     },
@@ -430,6 +479,7 @@ var init_yrestStorage = __esm({
     init_esm_shims();
     init_parseRelations();
     init_parseRoutes();
+    init_parseSseRoutes();
     init_parseSchema();
     init_parseData();
     init_deepCopy();
@@ -484,6 +534,7 @@ function dedent(str) {
 // src/api/yrestServer.ts
 init_esm_shims();
 init_parseRelations();
+init_parseSseRoutes();
 init_parseSchema();
 import { resolve as resolve2 } from "path";
 
@@ -596,6 +647,8 @@ var METHOD_COLOR = {
   PUT: "#d29922",
   PATCH: "#a371f7",
   DELETE: "#f85149",
+  SSE: "#0ea5e9",
+  WS: "#8b5cf6",
   fn: "#f0883e"
 };
 function escapeHtml(str) {
@@ -787,6 +840,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];
@@ -1459,6 +1536,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`)}`;
@@ -1642,6 +1720,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>
@@ -2794,6 +2873,80 @@ var SnapshotRouteCommand = class {
   }
 };
 
+// src/router/routes/sse.routes.ts
+init_esm_shims();
+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 = [];
@@ -2835,6 +2988,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)
   ];
@@ -2916,6 +3070,7 @@ function createInMemoryStorage(data) {
   const RESERVED2 = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const sseRoutes = parseSseRoutes(raw["_routes"]);
   const schema = parseSchema(raw["_schema"]);
   const collections = Object.fromEntries(
     Object.entries(raw).filter(([k]) => !RESERVED2.has(k))
@@ -2930,6 +3085,7 @@ function createInMemoryStorage(data) {
     getRelations: () => relations,
     getSchema: () => schema,
     getRoutes: () => routes,
+    getSseRoutes: () => sseRoutes,
     getCollection: (name) => collections[name],
     setCollection: (name, items) => {
       collections[name] = items;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yrest/cli",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a db.yml file.",
   "keywords": [
     "yrest",