@aggiovato/yrest 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -2,37 +2,158 @@ 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>;
-type DbData = Record<string, Resource[]>;
+/**
+ * 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>>;
 
+/**
+ * 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 {
-    getData(): DbData;
+    /** 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;
 }
+/**
+ * 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; 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`, 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>;
+    /**
+     * 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;
+    readonly: boolean;
+    delay: number;
+    pageable: {
+        enabled: boolean;
+        limit: number;
+    };
 }, {
     file: string;
     port?: number | undefined;
     host?: string | undefined;
     base?: string | undefined;
+    watch?: boolean | undefined;
+    readonly?: boolean | undefined;
+    delay?: number | undefined;
+    pageable?: number | boolean | undefined;
 }>;
+/**
+ * Resolved server configuration after Zod validation and transformation.
+ * Inferred from {@link serverOptionsSchema}.
+ */
 type ServerOptions = z.infer<typeof serverOptionsSchema>;
 
+/**
+ * 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 resource routes derived from the storage collections.
+ *
+ * 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.
+ */
 declare function createServer(storage: YamlStorage, options: ServerOptions): Promise<fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>>;
 
-export { type DbData, type Relations, type Resource, type ServerOptions, createServer, createYamlStorage, serverOptionsSchema };
+export { type Data, type Relations, type Resource, type ServerOptions, createServer, createYamlStorage, serverOptionsSchema };

package/dist/index.d.ts

@@ -2,37 +2,158 @@ 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>;
-type DbData = Record<string, Resource[]>;
+/**
+ * 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>>;
 
+/**
+ * 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 {
-    getData(): DbData;
+    /** 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;
 }
+/**
+ * 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; 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`, 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>;
+    /**
+     * 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;
+    readonly: boolean;
+    delay: number;
+    pageable: {
+        enabled: boolean;
+        limit: number;
+    };
 }, {
     file: string;
     port?: number | undefined;
     host?: string | undefined;
     base?: string | undefined;
+    watch?: boolean | undefined;
+    readonly?: boolean | undefined;
+    delay?: number | undefined;
+    pageable?: number | boolean | undefined;
 }>;
+/**
+ * Resolved server configuration after Zod validation and transformation.
+ * Inferred from {@link serverOptionsSchema}.
+ */
 type ServerOptions = z.infer<typeof serverOptionsSchema>;
 
+/**
+ * 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 resource routes derived from the storage collections.
+ *
+ * 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.
+ */
 declare function createServer(storage: YamlStorage, options: ServerOptions): Promise<fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>>;
 
-export { type DbData, type Relations, type Resource, type ServerOptions, createServer, createYamlStorage, serverOptionsSchema };
+export { type Data, type Relations, type Resource, type ServerOptions, createServer, createYamlStorage, serverOptionsSchema };