@yrest/cli 0.11.1 → 0.12.0

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 {};
@@ -690,6 +729,7 @@ function parseSchema(raw) {
   }
   return result;
 }
+var VALID_TYPES = /* @__PURE__ */ new Set(["string", "integer", "number", "boolean", "object", "array"]);
 function normaliseFieldDef(value) {
   if (value === "required") return { required: true };
   if (value === "optional") return { required: false };
@@ -697,15 +737,60 @@ function normaliseFieldDef(value) {
   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"]))
+  if (typeof v["_type"] === "string" && VALID_TYPES.has(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"];
+  if (v["_example"] !== void 0) def.example = v["_example"];
+  if (v["_nullable"] === true || v["_nullable"] === false) def.nullable = v["_nullable"];
+  if (typeof v["_minLength"] === "number") def.minLength = v["_minLength"];
+  if (typeof v["_maxLength"] === "number") def.maxLength = v["_maxLength"];
+  if (typeof v["_pattern"] === "string") def.pattern = v["_pattern"];
+  if (typeof v["_minimum"] === "number") def.minimum = v["_minimum"];
+  if (typeof v["_maximum"] === "number") def.maximum = v["_maximum"];
+  if (typeof v["_exclusiveMinimum"] === "number") def.exclusiveMinimum = v["_exclusiveMinimum"];
+  if (typeof v["_exclusiveMaximum"] === "number") def.exclusiveMaximum = v["_exclusiveMaximum"];
+  if (typeof v["_multipleOf"] === "number") def.multipleOf = v["_multipleOf"];
+  if (typeof v["_minItems"] === "number") def.minItems = v["_minItems"];
+  if (typeof v["_maxItems"] === "number") def.maxItems = v["_maxItems"];
+  if (v["_uniqueItems"] === true || v["_uniqueItems"] === false)
+    def.uniqueItems = v["_uniqueItems"];
+  if (v["_items"] && typeof v["_items"] === "object" && !Array.isArray(v["_items"])) {
+    const items = v["_items"];
+    const itemsDef = {};
+    if (typeof items["_type"] === "string" && VALID_TYPES.has(items["_type"]))
+      itemsDef.type = items["_type"];
+    if (typeof items["_format"] === "string") itemsDef.format = items["_format"];
+    if (Array.isArray(items["_enum"])) itemsDef.enum = items["_enum"];
+    def.items = itemsDef;
+  }
+  if (v["_deprecated"] === true || v["_deprecated"] === false)
+    def.deprecated = v["_deprecated"];
+  if (v["_readOnly"] === true || v["_readOnly"] === false) def.readOnly = v["_readOnly"];
+  if (v["_writeOnly"] === true || v["_writeOnly"] === false)
+    def.writeOnly = v["_writeOnly"];
   return def;
 }
 
+// src/storage/parseData.ts
+var RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema", "_data"]);
+function parseData(raw) {
+  const block = raw["_data"];
+  const fromBlock = block && typeof block === "object" && !Array.isArray(block) ? Object.fromEntries(
+    Object.entries(block).filter(([, v]) => Array.isArray(v))
+  ) : {};
+  const fromRoot = Object.fromEntries(
+    Object.entries(raw).filter(([key, val]) => !RESERVED.has(key) && Array.isArray(val))
+  );
+  return { ...fromBlock, ...fromRoot };
+}
+function hasDataBlock(raw) {
+  const d = raw["_data"];
+  return d !== null && d !== void 0 && typeof d === "object" && !Array.isArray(d);
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -771,13 +856,12 @@ function serializeScenario(s) {
 function createYrestStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
-  const RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
   const routes = parseRoutes(raw["_routes"]);
+  const sseRoutes = parseSseRoutes(raw["_routes"]);
   const schema = parseSchema(raw["_schema"]);
-  const data = Object.fromEntries(
-    Object.entries(raw).filter(([key]) => !RESERVED.has(key))
-  );
+  const dataBlock = hasDataBlock(raw);
+  const data = parseData(raw);
   let snapshot = {
     data: deepCopyData(data),
     relations: { ...relations },
@@ -796,6 +880,9 @@ function createYrestStorage(filePath) {
     getRoutes() {
       return routes;
     },
+    getSseRoutes() {
+      return sseRoutes;
+    },
     getCollection(name) {
       return data[name];
     },
@@ -806,7 +893,11 @@ function createYrestStorage(filePath) {
       const payload = {};
       if (Object.keys(relations).length > 0) payload._rel = serializeRelations(relations);
       if (routes.length > 0) payload._routes = serializeRoutes(routes);
-      Object.assign(payload, data);
+      if (dataBlock) {
+        payload._data = data;
+      } else {
+        Object.assign(payload, data);
+      }
       const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID()}.tmp`);
       writeFileSync2(tmp, stringify(payload), "utf8");
       renameSync(tmp, absPath);
@@ -814,9 +905,7 @@ function createYrestStorage(filePath) {
     reload() {
       const fresh = parse(readFileSync(absPath, "utf8")) ?? {};
       const freshRelations = parseRelations(fresh["_rel"]);
-      const freshData = Object.fromEntries(
-        Object.entries(fresh).filter(([key]) => !RESERVED.has(key))
-      );
+      const freshData = parseData(fresh);
       for (const key of Object.keys(data)) delete data[key];
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
@@ -905,6 +994,8 @@ var METHOD_COLOR = {
   PUT: "#d29922",
   PATCH: "#a371f7",
   DELETE: "#f85149",
+  SSE: "#0ea5e9",
+  WS: "#8b5cf6",
   fn: "#f0883e"
 };
 function escapeHtml(str) {
@@ -1096,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];
@@ -1766,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`)}`;
@@ -1949,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>
@@ -2376,15 +2493,19 @@ function resolveRequestPath(dotPath, req) {
   const [root, ...rest] = dotPath.split(".");
   let value;
   switch (root) {
+    case "_body":
     case "body":
       value = req.body;
       break;
+    case "_params":
     case "params":
       value = req.params;
       break;
+    case "_query":
     case "query":
       value = req.query;
       break;
+    case "_headers":
     case "headers":
       value = req.headers;
       break;
@@ -2676,6 +2797,23 @@ function buildCollectionSchema(items, fieldDefs = {}) {
     if (def?.description) prop.description = def.description;
     if (def?.enum) prop.enum = def.enum;
     if (def?.default !== void 0) prop.default = def.default;
+    if (def?.example !== void 0) prop.example = def.example;
+    if (def?.nullable) prop.nullable = def.nullable;
+    if (def?.minLength !== void 0) prop.minLength = def.minLength;
+    if (def?.maxLength !== void 0) prop.maxLength = def.maxLength;
+    if (def?.pattern) prop.pattern = def.pattern;
+    if (def?.minimum !== void 0) prop.minimum = def.minimum;
+    if (def?.maximum !== void 0) prop.maximum = def.maximum;
+    if (def?.exclusiveMinimum !== void 0) prop.exclusiveMinimum = def.exclusiveMinimum;
+    if (def?.exclusiveMaximum !== void 0) prop.exclusiveMaximum = def.exclusiveMaximum;
+    if (def?.multipleOf !== void 0) prop.multipleOf = def.multipleOf;
+    if (def?.items) prop.items = def.items;
+    if (def?.minItems !== void 0) prop.minItems = def.minItems;
+    if (def?.maxItems !== void 0) prop.maxItems = def.maxItems;
+    if (def?.uniqueItems !== void 0) prop.uniqueItems = def.uniqueItems;
+    if (def?.deprecated) prop.deprecated = def.deprecated;
+    if (def?.readOnly) prop.readOnly = def.readOnly;
+    if (def?.writeOnly) prop.writeOnly = def.writeOnly;
     properties[field] = prop;
     if (def?.required === true) required.push(field);
   }
@@ -3058,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 = [];
@@ -3099,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)
   ];
@@ -3218,6 +3430,14 @@ async function loadHandlers(filePath) {
 }
 
 // src/cli/commands/serve.ts
+function buildServeOptions(file, fileConfig, cliOverrides, fileArgIsExplicit = false) {
+  return yrestOptionsSchema.parse({
+    file,
+    ...fileConfig,
+    ...fileArgIsExplicit ? { file } : {},
+    ...cliOverrides
+  });
+}
 function registerServe(program2) {
   program2.command("serve").description("Start the mock server using a YAML file as database").argument("[file]", "Path to the YAML database file", "db.yml").option("-p, --port <number>", "Port to listen on", "3070").option("-H, --host <host>", "Host to bind", "localhost").option("-b, --base <path>", "Base path prefix for all routes", "").option("-w, --watch", "Reload db.yml automatically when it changes on disk").option("-r, --readonly", "Reject all write operations (POST, PUT, PATCH, DELETE) with 405").option(
     "-d, --delay <ms>",
@@ -3241,13 +3461,7 @@ function registerServe(program2) {
     const cliOverrides = Object.fromEntries(
       Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
     );
-    const merged = {
-      file,
-      ...fileConfig,
-      ...cmd.args.length > 0 ? { file } : {},
-      ...cliOverrides
-    };
-    const options = yrestOptionsSchema.parse(merged);
+    const options = buildServeOptions(file, fileConfig, cliOverrides, cmd.args.length > 0);
     let storage;
     try {
       storage = createYrestStorage(options.file);

package/dist/index.d.mts

@@ -10,21 +10,87 @@ type Resource = Record<string, unknown>;
  * All properties are optional — omit what you don't need. Fields not mentioned
  * in `_schema` are inferred from the collection data and treated as optional.
  *
+ * In the YAML file every property uses the `_` prefix convention:
+ * `_type`, `_required`, `_format`, `_enum`, `_description`, `_default`, etc.
+ *
  * Shorthand: `fieldName: required` normalises to `{ required: true }`.
+ *
+ * @example
+ * ```yaml
+ * _schema:
+ *   users:
+ *     name:
+ *       _type: string
+ *       _required: true
+ *       _minLength: 2
+ *       _maxLength: 100
+ *     email:
+ *       _type: string
+ *       _required: true
+ *       _format: email
+ *     age:
+ *       _type: integer
+ *       _minimum: 0
+ *       _maximum: 120
+ *       _nullable: true
+ *     role:
+ *       _type: string
+ *       _enum: [admin, editor, viewer]
+ *       _default: viewer
+ *     tags:
+ *       _type: array
+ *       _items:
+ *         _type: string
+ *       _uniqueItems: true
+ * ```
  */
 type FieldDef = {
-    /** If `true`, the field is listed in the OpenAPI `required` array and (Phase B) validated on POST/PUT. */
+    /** If `true`, the field is listed in the OpenAPI `required` array. */
     required?: boolean;
     /** Explicit type override. If absent, inferred from the data. */
     type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
-    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`). */
+    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`, `binary`). */
     format?: string;
-    /** Restricts the field to a fixed set of values. */
+    /** Restricts the field to a fixed set of allowed values. */
     enum?: unknown[];
     /** Human-readable description included in the OpenAPI spec. */
     description?: string;
     /** Default value included in the OpenAPI spec. */
     default?: unknown;
+    /** Example value included in the OpenAPI spec. */
+    example?: unknown;
+    /** If `true`, the field may be `null` in addition to its declared type. */
+    nullable?: boolean;
+    /** Minimum string length (inclusive). Applies when `type` is `string`. */
+    minLength?: number;
+    /** Maximum string length (inclusive). Applies when `type` is `string`. */
+    maxLength?: number;
+    /** Regex pattern the string value must match. Applies when `type` is `string`. */
+    pattern?: string;
+    /** Minimum numeric value (inclusive). Applies when `type` is `number` or `integer`. */
+    minimum?: number;
+    /** Maximum numeric value (inclusive). Applies when `type` is `number` or `integer`. */
+    maximum?: number;
+    /** Exclusive lower bound. Applies when `type` is `number` or `integer`. */
+    exclusiveMinimum?: number;
+    /** Exclusive upper bound. Applies when `type` is `number` or `integer`. */
+    exclusiveMaximum?: number;
+    /** Value must be a multiple of this number. */
+    multipleOf?: number;
+    /** Schema descriptor for the items of an array field. */
+    items?: Pick<FieldDef, "type" | "format" | "enum">;
+    /** Minimum number of items in the array. */
+    minItems?: number;
+    /** Maximum number of items in the array. */
+    maxItems?: number;
+    /** If `true`, all array items must be unique. */
+    uniqueItems?: boolean;
+    /** If `true`, marks the field as deprecated in the OpenAPI spec. */
+    deprecated?: boolean;
+    /** If `true`, the field is only returned in responses (excluded from request bodies). */
+    readOnly?: boolean;
+    /** If `true`, the field is only accepted in request bodies (excluded from responses). */
+    writeOnly?: boolean;
 };
 /**
  * Field-level schema declarations for one or more collections, parsed from `_schema` in the YAML.
@@ -218,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.
  *
@@ -270,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

@@ -10,21 +10,87 @@ type Resource = Record<string, unknown>;
  * All properties are optional — omit what you don't need. Fields not mentioned
  * in `_schema` are inferred from the collection data and treated as optional.
  *
+ * In the YAML file every property uses the `_` prefix convention:
+ * `_type`, `_required`, `_format`, `_enum`, `_description`, `_default`, etc.
+ *
  * Shorthand: `fieldName: required` normalises to `{ required: true }`.
+ *
+ * @example
+ * ```yaml
+ * _schema:
+ *   users:
+ *     name:
+ *       _type: string
+ *       _required: true
+ *       _minLength: 2
+ *       _maxLength: 100
+ *     email:
+ *       _type: string
+ *       _required: true
+ *       _format: email
+ *     age:
+ *       _type: integer
+ *       _minimum: 0
+ *       _maximum: 120
+ *       _nullable: true
+ *     role:
+ *       _type: string
+ *       _enum: [admin, editor, viewer]
+ *       _default: viewer
+ *     tags:
+ *       _type: array
+ *       _items:
+ *         _type: string
+ *       _uniqueItems: true
+ * ```
  */
 type FieldDef = {
-    /** If `true`, the field is listed in the OpenAPI `required` array and (Phase B) validated on POST/PUT. */
+    /** If `true`, the field is listed in the OpenAPI `required` array. */
     required?: boolean;
     /** Explicit type override. If absent, inferred from the data. */
     type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
-    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`). */
+    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`, `binary`). */
     format?: string;
-    /** Restricts the field to a fixed set of values. */
+    /** Restricts the field to a fixed set of allowed values. */
     enum?: unknown[];
     /** Human-readable description included in the OpenAPI spec. */
     description?: string;
     /** Default value included in the OpenAPI spec. */
     default?: unknown;
+    /** Example value included in the OpenAPI spec. */
+    example?: unknown;
+    /** If `true`, the field may be `null` in addition to its declared type. */
+    nullable?: boolean;
+    /** Minimum string length (inclusive). Applies when `type` is `string`. */
+    minLength?: number;
+    /** Maximum string length (inclusive). Applies when `type` is `string`. */
+    maxLength?: number;
+    /** Regex pattern the string value must match. Applies when `type` is `string`. */
+    pattern?: string;
+    /** Minimum numeric value (inclusive). Applies when `type` is `number` or `integer`. */
+    minimum?: number;
+    /** Maximum numeric value (inclusive). Applies when `type` is `number` or `integer`. */
+    maximum?: number;
+    /** Exclusive lower bound. Applies when `type` is `number` or `integer`. */
+    exclusiveMinimum?: number;
+    /** Exclusive upper bound. Applies when `type` is `number` or `integer`. */
+    exclusiveMaximum?: number;
+    /** Value must be a multiple of this number. */
+    multipleOf?: number;
+    /** Schema descriptor for the items of an array field. */
+    items?: Pick<FieldDef, "type" | "format" | "enum">;
+    /** Minimum number of items in the array. */
+    minItems?: number;
+    /** Maximum number of items in the array. */
+    maxItems?: number;
+    /** If `true`, all array items must be unique. */
+    uniqueItems?: boolean;
+    /** If `true`, marks the field as deprecated in the OpenAPI spec. */
+    deprecated?: boolean;
+    /** If `true`, the field is only returned in responses (excluded from request bodies). */
+    readOnly?: boolean;
+    /** If `true`, the field is only accepted in request bodies (excluded from responses). */
+    writeOnly?: boolean;
 };
 /**
  * Field-level schema declarations for one or more collections, parsed from `_schema` in the YAML.
@@ -218,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.
  *
@@ -270,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).