@yrest/cli 0.5.3 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aggiovato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -63,6 +63,7 @@ A YAML-first alternative to json-server for frontend development.
 | Readonly mode                                |  ✅   |     ❌      |
 | Atomic writes                                |  ✅   |     ✅      |
 | TypeScript types                             |  ✅   |     ❌      |
+| Programmatic API for test frameworks         |  ✅   |     ❌      |
 
 ---
 
@@ -694,6 +695,139 @@ const session = await fetch("http://localhost:3070/login", {
 // → { token: "tok-ana@test.com" }
 ```
 
+## Programmatic API
+
+Use yRest directly inside your test suite — no CLI, no separate process to manage.
+
+Install as a dev dependency:
+
+```bash
+npm install -D @yrest/cli
+```
+
+### `createYrestServer`
+
+Creates a server instance that you control with `start()` and `stop()`. Accepts either inline YAML data or a path to a `db.yml` file.
+
+```ts
+import { createYrestServer, yrest } from "@yrest/cli";
+```
+
+**Options:**
+
+| Option     | Type              | Default     | Description                                            |
+| ---------- | ----------------- | ----------- | ------------------------------------------------------ |
+| `data`     | `Data`            | —           | Inline data object (use with `yrest\`...\``)           |
+| `file`     | `string`          | —           | Path to a `db.yml` file (`data` or `file` is required) |
+| `port`     | `number`          | `3070`      | TCP port. Use `0` to get a random available port       |
+| `host`     | `string`          | `localhost` | Host to bind                                           |
+| `base`     | `string`          | —           | URL prefix for all routes (e.g. `"/api"`)              |
+| `readonly` | `boolean`         | `false`     | Reject all write operations with `405`                 |
+| `delay`    | `number`          | `0`         | Fixed delay in ms added to every response              |
+| `pageable` | `boolean\|number` | `false`     | Wrap GET responses in `{ data, pagination }` envelope  |
+| `snapshot` | `boolean`         | `false`     | Enable snapshot endpoints (`/_snapshot`)               |
+| `handlers` | `string`          | —           | Path to a JS file exporting handler functions          |
+
+**Returned handle:**
+
+| Member    | Description                                              |
+| --------- | -------------------------------------------------------- |
+| `start()` | Starts the server and begins listening                   |
+| `stop()`  | Gracefully closes the server                             |
+| `port`    | The actual port after `start()` (useful when `port: 0`)  |
+| `url`     | Base URL after `start()` (e.g. `http://localhost:49821`) |
+
+### `yrest` tagged template literal
+
+Parses inline YAML into a data object. Strips common leading indentation automatically, so you can indent naturally inside your test files. Supports interpolated values.
+
+```ts
+const data = yrest`
+  users:
+    - id: 1
+      name: Ana
+  posts:
+    - id: 1
+      title: First post
+      userId: 1
+`;
+```
+
+### Vitest example
+
+```ts
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createYrestServer, yrest } from "@yrest/cli";
+
+const server = createYrestServer({
+  data: yrest`
+    users:
+      - id: 1
+        name: Ana
+      - id: 2
+        name: Luis
+  `,
+  port: 0, // random port — no conflicts between parallel tests
+  readonly: true,
+});
+
+beforeAll(() => server.start());
+afterAll(() => server.stop());
+
+describe("users API", () => {
+  it("returns all users", async () => {
+    const res = await fetch(`${server.url}/users`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toHaveLength(2);
+  });
+
+  it("returns a single user", async () => {
+    const res = await fetch(`${server.url}/users/1`);
+    expect(await res.json()).toMatchObject({ name: "Ana" });
+  });
+});
+```
+
+### Playwright example
+
+```ts
+// tests/api.spec.ts
+import { test, expect, beforeAll, afterAll } from "@playwright/test";
+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());
+
+test("lists users", async () => {
+  const res = await fetch(`${server.url}/users`);
+  expect(await res.json()).toHaveLength(1);
+});
+```
+
+### File-based example
+
+When your test data is too large for inline YAML, point to a file:
+
+```ts
+const server = createYrestServer({
+  file: "./tests/fixtures/db.yml",
+  port: 0,
+  readonly: true,
+});
+```
+
+---
+
 ## Use in package.json scripts
 
 ```json
@@ -708,6 +842,28 @@ const session = await fetch("http://localhost:3070/login", {
 
 ---
 
+## Roadmap
+
+| Feature                                           | Status |
+| ------------------------------------------------- | ------ |
+| Full CRUD from `db.yml`                           | ✅     |
+| Field filters, operators, full-text search        | ✅     |
+| Relations, `_expand`, `_embed`, nested routes     | ✅     |
+| Pagination, sorting, field projection             | ✅     |
+| Watch, readonly, delay, snapshot modes            | ✅     |
+| Custom routes (`_routes`) with static responses   | ✅     |
+| Template variables in responses (`{{params.id}}`) | ✅     |
+| Handler functions (`yrest.handlers.js`)           | ✅     |
+| Visual panel (`/_panel`)                          | 🔜     |
+| Programmatic API for Vitest / Playwright          | ✅     |
+| Docker image                                      | 🔜     |
+| OpenAPI export (`yrest openapi db.yml`)           | 🔜     |
+| VS Code extension with YAML snippets              | 🔜     |
+| Request validation with JSON Schema               | 🔜     |
+| Conditional scenarios                             | 🔜     |
+
+---
+
 ## Contributing
 
 ### Prerequisites

package/dist/cli/index.js

@@ -135,7 +135,7 @@ function registerInit(program2) {
 var import_node_fs5 = require("fs");
 var import_node_path3 = require("path");
 
-// src/storage/yamlStorage.ts
+// src/storage/yrestStorage.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var import_node_crypto = require("crypto");
@@ -148,8 +148,8 @@ function deepCopyData(source) {
   );
 }
 
-// src/storage/yamlStorage.ts
-function createYamlStorage(filePath) {
+// src/storage/yrestStorage.ts
+function createYrestStorage(filePath) {
   const absPath = (0, import_node_path2.resolve)(filePath);
   const raw = (0, import_yaml.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
   const relations = raw["_rel"] ?? {};
@@ -1231,9 +1231,37 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   return server;
 }
 
+// src/server/yrestServer.ts
+function createYrestServerFromStorage(storage, options, handlers = /* @__PURE__ */ new Map()) {
+  let _port = 0;
+  let _started = false;
+  let _fastify = null;
+  return {
+    async start() {
+      if (_started) return;
+      _fastify = await createServer(storage, options, handlers);
+      await _fastify.listen({ port: options.port, host: options.host });
+      const address = _fastify.addresses()[0];
+      _port = typeof address === "object" && "port" in address ? address.port : options.port;
+      _started = true;
+    },
+    async stop() {
+      if (!_started || !_fastify) return;
+      await _fastify.close();
+      _started = false;
+    },
+    get port() {
+      return _port;
+    },
+    get url() {
+      return `http://${options.host}:${_port}${options.base}`;
+    }
+  };
+}
+
 // src/config/loadOptions.ts
 var import_zod = require("zod");
-var serverOptionsSchema = import_zod.z.object({
+var yrestOptionsSchema = import_zod.z.object({
   /** Path to the YAML database file. Must be a non-empty string. */
   file: import_zod.z.string().min(1),
   /** TCP port the server listens on. Accepts string input and coerces to number. */
@@ -1324,18 +1352,18 @@ function registerServe(program2) {
       ...cmd.args.length > 0 ? { file } : {},
       ...cliOverrides
     };
-    const options = serverOptionsSchema.parse(merged);
+    const options = yrestOptionsSchema.parse(merged);
     let storage;
     try {
-      storage = createYamlStorage(options.file);
+      storage = createYrestStorage(options.file);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`Error: cannot load "${options.file}" \u2014 ${msg}`);
       process.exit(1);
     }
     const handlers = options.handlers ? await loadHandlers((0, import_node_path3.resolve)(options.handlers)) : /* @__PURE__ */ new Map();
-    const server = await createServer(storage, options, handlers);
-    await server.listen({ port: options.port, host: options.host });
+    const yrestServer = createYrestServerFromStorage(storage, options, handlers);
+    await yrestServer.start();
     const collections = Object.keys(storage.getData());
     const customRoutes = storage.getRoutes();
     const base = options.base || "/";
@@ -1355,7 +1383,7 @@ function registerServe(program2) {
     };
     console.log(
       `
-  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${options.port}`)}
+  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${yrestServer.port}`)}
 `
     );
     console.log(`  ${b("Collections")} ${dim(`(base: ${base})`)}:`);

package/dist/cli/index.mjs

@@ -108,7 +108,7 @@ function registerInit(program2) {
 import { watchFile } from "fs";
 import { join, resolve as resolve3 } from "path";
 
-// src/storage/yamlStorage.ts
+// src/storage/yrestStorage.ts
 import { readFileSync, writeFileSync as writeFileSync2, renameSync } from "fs";
 import { resolve as resolve2, dirname } from "path";
 import { randomUUID } from "crypto";
@@ -121,8 +121,8 @@ function deepCopyData(source) {
   );
 }
 
-// src/storage/yamlStorage.ts
-function createYamlStorage(filePath) {
+// src/storage/yrestStorage.ts
+function createYrestStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
   const relations = raw["_rel"] ?? {};
@@ -1204,9 +1204,37 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   return server;
 }
 
+// src/server/yrestServer.ts
+function createYrestServerFromStorage(storage, options, handlers = /* @__PURE__ */ new Map()) {
+  let _port = 0;
+  let _started = false;
+  let _fastify = null;
+  return {
+    async start() {
+      if (_started) return;
+      _fastify = await createServer(storage, options, handlers);
+      await _fastify.listen({ port: options.port, host: options.host });
+      const address = _fastify.addresses()[0];
+      _port = typeof address === "object" && "port" in address ? address.port : options.port;
+      _started = true;
+    },
+    async stop() {
+      if (!_started || !_fastify) return;
+      await _fastify.close();
+      _started = false;
+    },
+    get port() {
+      return _port;
+    },
+    get url() {
+      return `http://${options.host}:${_port}${options.base}`;
+    }
+  };
+}
+
 // src/config/loadOptions.ts
 import { z } from "zod";
-var serverOptionsSchema = z.object({
+var yrestOptionsSchema = z.object({
   /** Path to the YAML database file. Must be a non-empty string. */
   file: z.string().min(1),
   /** TCP port the server listens on. Accepts string input and coerces to number. */
@@ -1297,18 +1325,18 @@ function registerServe(program2) {
       ...cmd.args.length > 0 ? { file } : {},
       ...cliOverrides
     };
-    const options = serverOptionsSchema.parse(merged);
+    const options = yrestOptionsSchema.parse(merged);
     let storage;
     try {
-      storage = createYamlStorage(options.file);
+      storage = createYrestStorage(options.file);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`Error: cannot load "${options.file}" \u2014 ${msg}`);
       process.exit(1);
     }
     const handlers = options.handlers ? await loadHandlers(resolve3(options.handlers)) : /* @__PURE__ */ new Map();
-    const server = await createServer(storage, options, handlers);
-    await server.listen({ port: options.port, host: options.host });
+    const yrestServer = createYrestServerFromStorage(storage, options, handlers);
+    await yrestServer.start();
     const collections = Object.keys(storage.getData());
     const customRoutes = storage.getRoutes();
     const base = options.base || "/";
@@ -1328,7 +1356,7 @@ function registerServe(program2) {
     };
     console.log(
       `
-  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${options.port}`)}
+  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${yrestServer.port}`)}
 `
     );
     console.log(`  ${b("Collections")} ${dim(`(base: ${base})`)}:`);

package/dist/index.d.mts

@@ -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>;
@@ -63,7 +63,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 +130,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 +158,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 +222,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 +263,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 };