@yrest/cli 0.5.3

package/dist/index.d.mts

@@ -0,0 +1,257 @@
+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>;
+/**
+ * The full in-memory database.
+ * Keys are collection names (e.g. `"users"`); values are arrays of {@link Resource} items.
+ */
+type Data = Record<string, Resource[]>;
+/**
+ * Relational mappings declared under `_rel` in the YAML file.
+ *
+ * - Outer key: child collection name.
+ * - Inner key: foreign key field on the child.
+ * - Inner value: parent collection name.
+ *
+ * @example
+ * // Given: _rel: { posts: { userId: users } }
+ * // GET /users/1/posts → returns posts where userId === "1"
+ */
+type Relations = Record<string, Record<string, string>>;
+/**
+ * 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.
+ *
+ * @example
+ * // _routes:
+ * //   - method: POST
+ * //     path: /login
+ * //     response:
+ * //       status: 200
+ * //       body: { token: abc123 }
+ */
+type CustomRoute = {
+    /** HTTP method (case-insensitive: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). */
+    method: string;
+    /** URL path. May include Fastify path params (e.g. `/users/:id`). Must start with `/`. */
+    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.
+     */
+    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>;
+    };
+};
+/**
+ * In-memory store backed by a YAML file.
+ *
+ * All reads operate on a live in-memory snapshot. Writes must be explicitly
+ * 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 {
+    /** Returns the full in-memory dataset (all collections). */
+    getData(): Data;
+    /** Returns the relational mappings declared under `_rel`. */
+    getRelations(): Relations;
+    /**
+     * Returns the items in a named collection, or `undefined` if it does not exist.
+     *
+     * @param name - Collection name as declared in the YAML file (e.g. `"users"`).
+     */
+    getCollection(name: string): Resource[] | undefined;
+    /**
+     * Replaces the items of a named collection in memory.
+     * Call {@link persist} afterwards to flush the change to disk.
+     *
+     * @param name  - Collection name.
+     * @param items - New array of items to store.
+     */
+    setCollection(name: string, items: Resource[]): void;
+    /**
+     * Atomically writes the current in-memory state to the YAML file.
+     *
+     * Uses a write-to-temp-then-rename strategy so a crash during the write
+     * never leaves the file in a partially written state.
+     *
+     * @throws {Error} If the filesystem write or rename fails.
+     */
+    persist(): void;
+    /**
+     * Reloads the YAML file from disk and updates the in-memory state in place.
+     *
+     * Mutates the existing `data` and `relations` objects rather than replacing them,
+     * so any code holding a reference to the storage instance sees the updated values
+     * without needing to re-fetch.
+     *
+     * @throws {Error} If the file cannot be read or the YAML is malformed.
+     */
+    reload(): void;
+    /**
+     * Returns the custom routes declared under `_routes` in the YAML file.
+     * Returns an empty array if no `_routes` block is present.
+     */
+    getRoutes(): CustomRoute[];
+    /**
+     * Returns the saved snapshot: a frozen copy of `data` and `relations` taken
+     * at the last call to {@link saveSnapshot} (or at construction time).
+     */
+    getSnapshot(): {
+        data: Data;
+        relations: Relations;
+        savedAt: Date;
+    };
+    /**
+     * Replaces the stored snapshot with a deep copy of the current in-memory state.
+     * Future calls to {@link resetToSnapshot} will restore to this point.
+     */
+    saveSnapshot(): void;
+    /**
+     * Restores the in-memory state to the last saved snapshot and persists to disk.
+     * Mutates `data` and `relations` in place so existing references stay valid.
+     *
+     * @throws {Error} If the filesystem write fails.
+     */
+    resetToSnapshot(): void;
+}
+
+/**
+ * Creates a {@link YamlStorage} 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 createYamlStorage(filePath: string): YamlStorage;
+
+/**
+ * Zod schema for all server runtime options.
+ *
+ * Validates and normalises options from three sources in ascending priority:
+ * schema defaults → `yrest.config.yml` → explicit CLI flags.
+ */
+declare const serverOptionsSchema: 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. */
+    port: z.ZodDefault<z.ZodNumber>;
+    /** Hostname or IP address to bind. */
+    host: z.ZodDefault<z.ZodString>;
+    /**
+     * URL prefix prepended to every route (e.g. `/api`).
+     * A leading slash is added automatically if omitted.
+     */
+    base: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    /** When `true`, the server reloads the YAML file automatically on disk changes. */
+    watch: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * When `true`, saves a snapshot of the initial database state on startup.
+     * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+     */
+    snapshot: z.ZodDefault<z.ZodBoolean>;
+    /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
+    readonly: z.ZodDefault<z.ZodBoolean>;
+    /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
+    delay: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Path to a JavaScript file exporting handler functions for custom routes.
+     * When set, functions are loaded at startup and referenced by name via `handler:` in `_routes`.
+     */
+    handlers: z.ZodOptional<z.ZodString>;
+    /**
+     * Wraps GET collection responses in a `{ data, pagination }` envelope.
+     * Accepts `true` (default limit 10), `false` (disabled), or a positive integer (custom limit).
+     */
+    pageable: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodNumber]>>, {
+        enabled: boolean;
+        limit: number;
+    }, number | boolean | undefined>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    port: number;
+    host: string;
+    base: string;
+    watch: boolean;
+    snapshot: boolean;
+    readonly: boolean;
+    delay: number;
+    pageable: {
+        enabled: boolean;
+        limit: number;
+    };
+    handlers?: string | undefined;
+}, {
+    file: string;
+    port?: number | undefined;
+    host?: string | undefined;
+    base?: string | undefined;
+    watch?: boolean | undefined;
+    snapshot?: boolean | undefined;
+    readonly?: boolean | undefined;
+    delay?: number | undefined;
+    handlers?: string | undefined;
+    pageable?: number | boolean | undefined;
+}>;
+/**
+ * Resolved server configuration after Zod validation and transformation.
+ * Inferred from {@link serverOptionsSchema}.
+ */
+type ServerOptions = z.infer<typeof serverOptionsSchema>;
+
+/** Incoming request data passed to every handler function. */
+type HandlerRequest = {
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body: unknown;
+    headers: Record<string, string | string[]>;
+};
+/** Value returned by a handler function to describe the HTTP response. */
+type HandlerResponse = {
+    /** HTTP status code. Defaults to `200` if omitted. */
+    status?: number;
+    /** Response body. Any JSON-serialisable value. */
+    body?: unknown;
+    /** Additional response headers to set on the reply. */
+    headers?: Record<string, string>;
+};
+/** A function that handles a custom route request and returns a response descriptor. */
+type Handler = (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>;
+/** Map of exported function name → handler function. */
+type HandlerMap = Map<string, Handler>;
+
+/**
+ * Creates and configures a Fastify instance wired to the given YAML storage.
+ *
+ * Registers, in order:
+ * 1. CORS (all origins, permissive defaults).
+ * 2. Readonly guard hook — rejects mutating requests with 405 when enabled.
+ * 3. Delay hook — defers `onSend` by N ms when enabled.
+ * 4. All route commands: about, snapshot (optional), custom routes, resource routes.
+ *
+ * The server is returned before `listen()` is called so tests can inject
+ * requests without binding a real port.
+ *
+ * @param storage - Initialised YAML storage instance.
+ * @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>>;
+
+export { type CustomRoute, type Data, type Handler, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type ServerOptions, type YamlStorage, createServer, createYamlStorage, serverOptionsSchema };

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+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>;
+/**
+ * The full in-memory database.
+ * Keys are collection names (e.g. `"users"`); values are arrays of {@link Resource} items.
+ */
+type Data = Record<string, Resource[]>;
+/**
+ * Relational mappings declared under `_rel` in the YAML file.
+ *
+ * - Outer key: child collection name.
+ * - Inner key: foreign key field on the child.
+ * - Inner value: parent collection name.
+ *
+ * @example
+ * // Given: _rel: { posts: { userId: users } }
+ * // GET /users/1/posts → returns posts where userId === "1"
+ */
+type Relations = Record<string, Record<string, string>>;
+/**
+ * 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.
+ *
+ * @example
+ * // _routes:
+ * //   - method: POST
+ * //     path: /login
+ * //     response:
+ * //       status: 200
+ * //       body: { token: abc123 }
+ */
+type CustomRoute = {
+    /** HTTP method (case-insensitive: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). */
+    method: string;
+    /** URL path. May include Fastify path params (e.g. `/users/:id`). Must start with `/`. */
+    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.
+     */
+    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>;
+    };
+};
+/**
+ * In-memory store backed by a YAML file.
+ *
+ * All reads operate on a live in-memory snapshot. Writes must be explicitly
+ * 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 {
+    /** Returns the full in-memory dataset (all collections). */
+    getData(): Data;
+    /** Returns the relational mappings declared under `_rel`. */
+    getRelations(): Relations;
+    /**
+     * Returns the items in a named collection, or `undefined` if it does not exist.
+     *
+     * @param name - Collection name as declared in the YAML file (e.g. `"users"`).
+     */
+    getCollection(name: string): Resource[] | undefined;
+    /**
+     * Replaces the items of a named collection in memory.
+     * Call {@link persist} afterwards to flush the change to disk.
+     *
+     * @param name  - Collection name.
+     * @param items - New array of items to store.
+     */
+    setCollection(name: string, items: Resource[]): void;
+    /**
+     * Atomically writes the current in-memory state to the YAML file.
+     *
+     * Uses a write-to-temp-then-rename strategy so a crash during the write
+     * never leaves the file in a partially written state.
+     *
+     * @throws {Error} If the filesystem write or rename fails.
+     */
+    persist(): void;
+    /**
+     * Reloads the YAML file from disk and updates the in-memory state in place.
+     *
+     * Mutates the existing `data` and `relations` objects rather than replacing them,
+     * so any code holding a reference to the storage instance sees the updated values
+     * without needing to re-fetch.
+     *
+     * @throws {Error} If the file cannot be read or the YAML is malformed.
+     */
+    reload(): void;
+    /**
+     * Returns the custom routes declared under `_routes` in the YAML file.
+     * Returns an empty array if no `_routes` block is present.
+     */
+    getRoutes(): CustomRoute[];
+    /**
+     * Returns the saved snapshot: a frozen copy of `data` and `relations` taken
+     * at the last call to {@link saveSnapshot} (or at construction time).
+     */
+    getSnapshot(): {
+        data: Data;
+        relations: Relations;
+        savedAt: Date;
+    };
+    /**
+     * Replaces the stored snapshot with a deep copy of the current in-memory state.
+     * Future calls to {@link resetToSnapshot} will restore to this point.
+     */
+    saveSnapshot(): void;
+    /**
+     * Restores the in-memory state to the last saved snapshot and persists to disk.
+     * Mutates `data` and `relations` in place so existing references stay valid.
+     *
+     * @throws {Error} If the filesystem write fails.
+     */
+    resetToSnapshot(): void;
+}
+
+/**
+ * Creates a {@link YamlStorage} 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 createYamlStorage(filePath: string): YamlStorage;
+
+/**
+ * Zod schema for all server runtime options.
+ *
+ * Validates and normalises options from three sources in ascending priority:
+ * schema defaults → `yrest.config.yml` → explicit CLI flags.
+ */
+declare const serverOptionsSchema: 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. */
+    port: z.ZodDefault<z.ZodNumber>;
+    /** Hostname or IP address to bind. */
+    host: z.ZodDefault<z.ZodString>;
+    /**
+     * URL prefix prepended to every route (e.g. `/api`).
+     * A leading slash is added automatically if omitted.
+     */
+    base: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    /** When `true`, the server reloads the YAML file automatically on disk changes. */
+    watch: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * When `true`, saves a snapshot of the initial database state on startup.
+     * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+     */
+    snapshot: z.ZodDefault<z.ZodBoolean>;
+    /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
+    readonly: z.ZodDefault<z.ZodBoolean>;
+    /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
+    delay: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Path to a JavaScript file exporting handler functions for custom routes.
+     * When set, functions are loaded at startup and referenced by name via `handler:` in `_routes`.
+     */
+    handlers: z.ZodOptional<z.ZodString>;
+    /**
+     * Wraps GET collection responses in a `{ data, pagination }` envelope.
+     * Accepts `true` (default limit 10), `false` (disabled), or a positive integer (custom limit).
+     */
+    pageable: z.ZodEffects<z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodNumber]>>, {
+        enabled: boolean;
+        limit: number;
+    }, number | boolean | undefined>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    port: number;
+    host: string;
+    base: string;
+    watch: boolean;
+    snapshot: boolean;
+    readonly: boolean;
+    delay: number;
+    pageable: {
+        enabled: boolean;
+        limit: number;
+    };
+    handlers?: string | undefined;
+}, {
+    file: string;
+    port?: number | undefined;
+    host?: string | undefined;
+    base?: string | undefined;
+    watch?: boolean | undefined;
+    snapshot?: boolean | undefined;
+    readonly?: boolean | undefined;
+    delay?: number | undefined;
+    handlers?: string | undefined;
+    pageable?: number | boolean | undefined;
+}>;
+/**
+ * Resolved server configuration after Zod validation and transformation.
+ * Inferred from {@link serverOptionsSchema}.
+ */
+type ServerOptions = z.infer<typeof serverOptionsSchema>;
+
+/** Incoming request data passed to every handler function. */
+type HandlerRequest = {
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body: unknown;
+    headers: Record<string, string | string[]>;
+};
+/** Value returned by a handler function to describe the HTTP response. */
+type HandlerResponse = {
+    /** HTTP status code. Defaults to `200` if omitted. */
+    status?: number;
+    /** Response body. Any JSON-serialisable value. */
+    body?: unknown;
+    /** Additional response headers to set on the reply. */
+    headers?: Record<string, string>;
+};
+/** A function that handles a custom route request and returns a response descriptor. */
+type Handler = (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>;
+/** Map of exported function name → handler function. */
+type HandlerMap = Map<string, Handler>;
+
+/**
+ * Creates and configures a Fastify instance wired to the given YAML storage.
+ *
+ * Registers, in order:
+ * 1. CORS (all origins, permissive defaults).
+ * 2. Readonly guard hook — rejects mutating requests with 405 when enabled.
+ * 3. Delay hook — defers `onSend` by N ms when enabled.
+ * 4. All route commands: about, snapshot (optional), custom routes, resource routes.
+ *
+ * The server is returned before `listen()` is called so tests can inject
+ * requests without binding a real port.
+ *
+ * @param storage - Initialised YAML storage instance.
+ * @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>>;
+
+export { type CustomRoute, type Data, type Handler, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type ServerOptions, type YamlStorage, createServer, createYamlStorage, serverOptionsSchema };