@yrest/cli 0.5.3 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+import { z } from 'zod';
 import * as fastify from 'fastify';
 import * as http from 'http';
-import { z } from 'zod';
 
 /** A single REST resource item. Field names and value types are user-defined in the YAML file. */
 type Resource = Record<string, unknown>;
@@ -21,19 +21,72 @@ type Data = Record<string, Resource[]>;
  * // GET /users/1/posts → returns posts where userId === "1"
  */
 type Relations = Record<string, Record<string, string>>;
+/**
+ * A static response block shared by {@link CustomRoute} and {@link Scenario}.
+ */
+type RouteResponse = {
+    /** HTTP status code. Defaults to `200` if omitted. */
+    status?: number;
+    /** Response body. Any YAML-serialisable value (object, array, string, number, null). */
+    body?: unknown;
+    /** Additional response headers to set alongside `Content-Type`. */
+    headers?: Record<string, string>;
+};
+/**
+ * A conditional response variant for a custom route.
+ *
+ * Evaluated in declaration order — the first scenario whose `when` conditions match wins.
+ * If none match, the route falls back to `otherwise:` (if defined) or `response:`.
+ *
+ * **`when` as an object** — all entries must match (AND):
+ * ```yaml
+ * when: { body.email: ana@test.com, body.password: secret }
+ * ```
+ *
+ * **`when` as an array** — any group must match (OR of ANDs):
+ * ```yaml
+ * when:
+ *   - { body.role: admin }
+ *   - { body.role: superadmin }
+ * ```
+ *
+ * Condition keys use dot-notation (`body.X`, `params.X`, `query.X`, `headers.X`).
+ * Field operator suffixes are supported: `_ne`, `_like`, `_start`, `_regex`, `_gte`, `_lte`.
+ * Response bodies support `{{}}` template variables (same as static routes).
+ */
+type Scenario = {
+    /**
+     * Condition(s) to evaluate against the request.
+     * - Object → all entries AND
+     * - Array of objects → any group OR (each group is AND internally)
+     */
+    when: Record<string, unknown> | Record<string, unknown>[];
+    /** Response to return when the conditions match. Supports `{{}}` template variables. */
+    response: RouteResponse;
+};
 /**
  * A single custom route declared under `_routes` in the YAML file.
  *
- * Custom routes are registered before resource routes and take priority over them.
- * They always return a static, pre-defined response regardless of the request body or params.
+ * Resolution priority per request:
+ * 1. `handler` function (if defined and found in the handlers file)
+ * 2. First matching `scenario` (evaluated in declaration order)
+ * 3. `otherwise` block (explicit fallback when scenarios are defined but none matched)
+ * 4. Static `response` block (final fallback)
  *
  * @example
  * // _routes:
  * //   - method: POST
  * //     path: /login
- * //     response:
- * //       status: 200
- * //       body: { token: abc123 }
+ * //     scenarios:
+ * //       - when: { body.password: secret }
+ * //         response: { status: 200, body: { token: real-tok } }
+ * //       - when:
+ * //           - { body.role: admin }
+ * //           - { body.role: superadmin }
+ * //         response: { status: 200, body: { token: admin-tok } }
+ * //     otherwise:
+ * //       status: 401
+ * //       body: { error: Invalid credentials }
  */
 type CustomRoute = {
     /** HTTP method (case-insensitive: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). */
@@ -42,19 +95,23 @@ type CustomRoute = {
     path: string;
     /**
      * Name of an exported function in the handlers file (`handlers:` in config).
-     * When set, the function is called on every request and its return value is used as the response.
-     * Takes priority over `response:`. Falls back to `response:` if the name is not found.
+     * Takes priority over `scenarios` and `response`. Falls back to `response` if not found.
      */
     handler?: string;
-    /** Static or template response. Used when `handler` is absent or not found in the handlers file. */
-    response?: {
-        /** HTTP status code. Defaults to `200` if omitted. */
-        status?: number;
-        /** Response body. Any YAML-serialisable value (object, array, string, number, null). */
-        body?: unknown;
-        /** Additional response headers to set alongside `Content-Type`. */
-        headers?: Record<string, string>;
-    };
+    /** Conditional response variants. Evaluated in order — first match wins. */
+    scenarios?: Scenario[];
+    /**
+     * Explicit fallback response when `scenarios` are defined but none matched.
+     * Takes priority over `response` when present. Supports `{{}}` template variables.
+     */
+    otherwise?: RouteResponse;
+    /** Static or template response. Final fallback when no handler, scenario, or otherwise applies. */
+    response?: RouteResponse;
+    /**
+     * Per-route response delay in milliseconds. Overrides the global `--delay` option for this route.
+     * Applied before any response is sent, regardless of which path resolved the response.
+     */
+    delay?: number;
 };
 /**
  * In-memory store backed by a YAML file.
@@ -63,7 +120,7 @@ type CustomRoute = {
  * flushed to disk by calling {@link persist}. Use {@link reload} to pull in
  * changes made to the file externally (e.g. in watch mode).
  */
-interface YamlStorage {
+interface YrestStorage {
     /** Returns the full in-memory dataset (all collections). */
     getData(): Data;
     /** Returns the relational mappings declared under `_rel`. */
@@ -130,16 +187,27 @@ interface YamlStorage {
 }
 
 /**
- * Creates a {@link YamlStorage} instance backed by the given YAML file.
+ * Tagged template literal that parses inline YAML into a yRest {@link Data} object.
  *
- * The file is read and parsed eagerly on construction. The `_rel` key is
- * extracted as relational metadata; `_routes` as custom route declarations;
- * all other top-level keys become collections.
+ * Strips common leading indentation automatically, so the template can be
+ * indented naturally inside the calling function without affecting YAML parsing.
  *
- * @param filePath - Relative or absolute path to the YAML database file.
- * @throws {Error} If the file cannot be read or its YAML is invalid.
+ * Supports interpolated values — they are stringified and inserted inline.
+ *
+ * @throws {Error} If the template is not valid YAML or does not resolve to a plain object.
+ *
+ * @example
+ * const data = yrest`
+ *   users:
+ *     - id: 1
+ *       name: Ana
+ *   posts:
+ *     - id: 1
+ *       title: First post
+ *       userId: 1
+ * `;
  */
-declare function createYamlStorage(filePath: string): YamlStorage;
+declare function yrest(strings: TemplateStringsArray, ...values: unknown[]): Data;
 
 /**
  * Zod schema for all server runtime options.
@@ -147,7 +215,7 @@ declare function createYamlStorage(filePath: string): YamlStorage;
  * Validates and normalises options from three sources in ascending priority:
  * schema defaults → `yrest.config.yml` → explicit CLI flags.
  */
-declare const serverOptionsSchema: z.ZodObject<{
+declare const yrestOptionsSchema: z.ZodObject<{
     /** Path to the YAML database file. Must be a non-empty string. */
     file: z.ZodString;
     /** TCP port the server listens on. Accepts string input and coerces to number. */
@@ -211,9 +279,9 @@ declare const serverOptionsSchema: z.ZodObject<{
 }>;
 /**
  * Resolved server configuration after Zod validation and transformation.
- * Inferred from {@link serverOptionsSchema}.
+ * Inferred from {@link yrestOptionsSchema}.
  */
-type ServerOptions = z.infer<typeof serverOptionsSchema>;
+type YrestOptions = z.infer<typeof yrestOptionsSchema>;
 
 /** Incoming request data passed to every handler function. */
 type HandlerRequest = {
@@ -252,6 +320,113 @@ type HandlerMap = Map<string, Handler>;
  * @param options - Validated server options.
  * @param handlers - Map of named handler functions loaded from yrest.handlers.js.
  */
-declare function createServer(storage: YamlStorage, options: ServerOptions, handlers?: HandlerMap): Promise<fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>>;
+declare function createServer(storage: YrestStorage, options: YrestOptions, handlers?: HandlerMap): Promise<fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>>;
+
+/** Handle returned by {@link createYrestServerFromStorage} and {@link createYrestServer}. */
+interface YrestServer {
+    /** Starts the server and begins listening on the configured port. */
+    start(): Promise<void>;
+    /** Gracefully closes the server. */
+    stop(): Promise<void>;
+    /** The port the server is listening on. Only valid after `start()`. */
+    readonly port: number;
+    /** The base URL of the server (e.g. `http://localhost:3070`). Only valid after `start()`. */
+    readonly url: string;
+}
+/**
+ * Creates a {@link YrestServer} from an already-initialised storage and parsed options.
+ *
+ * This is the shared Fastify lifecycle owner used by both the CLI (`serve` command)
+ * and the programmatic API (`createYrestServer`). It is the only place where
+ * `createServer → listen → close` lives.
+ *
+ * Each consumer is responsible for building storage and resolving options before
+ * calling this function:
+ * - CLI (`serve.ts`): Zod parsing, config-file merging, `process.exit` error handling
+ * - Programmatic API (`createYrestServer`): raw → parsed options conversion, inline data support
+ *
+ * @param storage  - Initialised storage instance (file-based or in-memory).
+ * @param options  - Fully resolved and validated server options.
+ * @param handlers - Pre-loaded handler map. Defaults to an empty map.
+ */
+declare function createYrestServerFromStorage(storage: YrestStorage, options: YrestOptions, handlers?: HandlerMap): YrestServer;
+
+/** Base options shared between file-based and data-based server instances. */
+type YrestServerBaseOptions = {
+    /** TCP port to listen on. Defaults to `3070`. Use `0` to get a random available port. */
+    port?: number;
+    /** Host to bind. Defaults to `"localhost"`. */
+    host?: string;
+    /** URL prefix prepended to every route (e.g. `"/api"`). */
+    base?: string;
+    /** Reject all mutating requests (POST, PUT, PATCH, DELETE) with `405`. */
+    readonly?: boolean;
+    /** Milliseconds to delay every response. */
+    delay?: number;
+    /** Wrap GET collection responses in `{ data, pagination }`. Pass `true` (limit 10) or a number. */
+    pageable?: boolean | number;
+    /** Save a snapshot at startup and expose `/_snapshot` endpoints. */
+    snapshot?: boolean;
+    /** Path to a JS file exporting handler functions for custom `_routes` entries. */
+    handlers?: string;
+};
+/**
+ * Options for {@link createYrestServer}.
+ * Either `file` (path to a `db.yml`) or `data` (inline object, e.g. from `yrest\`...\``) is required.
+ */
+type YrestServerOptions = YrestServerBaseOptions & ({
+    file: string;
+    data?: never;
+} | {
+    data: Data;
+    file?: never;
+});
+/**
+ * Creates a yRest server instance for programmatic use.
+ *
+ * Accepts either a `file` path to a `db.yml` or an inline `data` object
+ * (typically produced by the {@link yrest} tagged template literal).
+ *
+ * The server is not started until you call `start()`.
+ *
+ * @example — file-based (e.g. in Playwright globalSetup)
+ * ```ts
+ * const server = createYrestServer({ file: "./tests/db.yml", readonly: true });
+ * await server.start();
+ * // → http://localhost:3070
+ * await server.stop();
+ * ```
+ *
+ * @example — inline data (e.g. in Vitest)
+ * ```ts
+ * import { createYrestServer, yrest } from "@yrest/cli";
+ *
+ * const server = createYrestServer({
+ *   data: yrest`
+ *     users:
+ *       - id: 1
+ *         name: Ana
+ *   `,
+ *   port: 0,
+ *   readonly: true,
+ * });
+ *
+ * beforeAll(() => server.start());
+ * afterAll(() => server.stop());
+ * ```
+ */
+declare function createYrestServer(options: YrestServerOptions): YrestServer;
+
+/**
+ * Creates a {@link YrestStorage} instance backed by the given YAML file.
+ *
+ * The file is read and parsed eagerly on construction. The `_rel` key is
+ * extracted as relational metadata; `_routes` as custom route declarations;
+ * all other top-level keys become collections.
+ *
+ * @param filePath - Relative or absolute path to the YAML database file.
+ * @throws {Error} If the file cannot be read or its YAML is invalid.
+ */
+declare function createYrestStorage(filePath: string): YrestStorage;
 
-export { type CustomRoute, type Data, type Handler, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type ServerOptions, type YamlStorage, createServer, createYamlStorage, serverOptionsSchema };
+export { type CustomRoute, type Data, type Handler, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type YrestOptions, type YrestServer, type YrestServerBaseOptions, type YrestServerOptions, type YrestStorage, createServer, createYrestServer, createYrestServerFromStorage, createYrestStorage, yrest, yrestOptionsSchema };