@yrest/cli 0.5.3 → 0.6.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>;
@@ -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 };

package/dist/index.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,20 +30,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  createServer: () => createServer,
-  createYamlStorage: () => createYamlStorage,
-  serverOptionsSchema: () => serverOptionsSchema
+// node_modules/tsup/assets/cjs_shims.js
+var init_cjs_shims = __esm({
+  "node_modules/tsup/assets/cjs_shims.js"() {
+    "use strict";
+  }
 });
-module.exports = __toCommonJS(src_exports);
-
-// src/storage/yamlStorage.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-var import_node_crypto = require("crypto");
-var import_yaml = require("yaml");
 
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
@@ -48,11 +43,21 @@ function deepCopyData(source) {
     Object.entries(source).map(([k, v]) => [k, v.map((item) => ({ ...item }))])
   );
 }
+var init_deepCopy = __esm({
+  "src/utils/deepCopy.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
 
-// src/storage/yamlStorage.ts
-function createYamlStorage(filePath) {
+// src/storage/yrestStorage.ts
+var yrestStorage_exports = {};
+__export(yrestStorage_exports, {
+  createYrestStorage: () => createYrestStorage
+});
+function createYrestStorage(filePath) {
   const absPath = (0, import_node_path.resolve)(filePath);
-  const raw = (0, import_yaml.parse)((0, import_node_fs.readFileSync)(absPath, "utf8")) ?? {};
+  const raw = (0, import_yaml2.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
   const relations = raw["_rel"] ?? {};
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
   const data = Object.fromEntries(
@@ -84,12 +89,12 @@ function createYamlStorage(filePath) {
       if (Object.keys(relations).length > 0) payload._rel = relations;
       if (routes.length > 0) payload._routes = routes;
       Object.assign(payload, data);
-      const tmp = (0, import_node_path.resolve)((0, import_node_path.dirname)(absPath), `.yrest-${(0, import_node_crypto.randomUUID)()}.tmp`);
-      (0, import_node_fs.writeFileSync)(tmp, (0, import_yaml.stringify)(payload), "utf8");
-      (0, import_node_fs.renameSync)(tmp, absPath);
+      const tmp = (0, import_node_path.resolve)((0, import_node_path.dirname)(absPath), `.yrest-${(0, import_node_crypto2.randomUUID)()}.tmp`);
+      (0, import_node_fs2.writeFileSync)(tmp, (0, import_yaml2.stringify)(payload), "utf8");
+      (0, import_node_fs2.renameSync)(tmp, absPath);
     },
     reload() {
-      const fresh = (0, import_yaml.parse)((0, import_node_fs.readFileSync)(absPath, "utf8")) ?? {};
+      const fresh = (0, import_yaml2.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
       const freshRelations = fresh["_rel"] ?? {};
       const freshData = Object.fromEntries(
         Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
@@ -119,13 +124,123 @@ function createYamlStorage(filePath) {
     }
   };
 }
+var import_node_fs2, import_node_path, import_node_crypto2, import_yaml2;
+var init_yrestStorage = __esm({
+  "src/storage/yrestStorage.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_fs2 = require("fs");
+    import_node_path = require("path");
+    import_node_crypto2 = require("crypto");
+    import_yaml2 = require("yaml");
+    init_deepCopy();
+  }
+});
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createServer: () => createServer,
+  createYrestServer: () => createYrestServer,
+  createYrestServerFromStorage: () => createYrestServerFromStorage,
+  createYrestStorage: () => createYrestStorage,
+  yrest: () => yrest,
+  yrestOptionsSchema: () => yrestOptionsSchema
+});
+module.exports = __toCommonJS(src_exports);
+init_cjs_shims();
+
+// src/api/yrest.ts
+init_cjs_shims();
+var import_yaml = require("yaml");
+function yrest(strings, ...values) {
+  const raw = strings.reduce(
+    (acc, str, i) => acc + str + (values[i] !== void 0 ? stringifyInterpolation(values[i]) : ""),
+    ""
+  );
+  const dedented = dedent(raw);
+  let parsed;
+  try {
+    parsed = (0, import_yaml.parse)(dedented);
+  } catch (e) {
+    throw new Error(`[yrest] Invalid YAML: ${e instanceof Error ? e.message : String(e)}`, {
+      cause: e
+    });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("[yrest] Template must resolve to a YAML object with collection keys.");
+  }
+  return parsed;
+}
+function stringifyInterpolation(value) {
+  if (value === null || value === void 0) return String(value);
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  const type = Array.isArray(value) ? "array" : typeof value;
+  throw new Error(
+    `[yrest] Cannot interpolate a value of type "${type}". Only string, number, and boolean are supported.`
+  );
+}
+function dedent(str) {
+  const lines = str.split("\n");
+  const minIndent = lines.filter((line) => line.trim().length > 0).reduce((min, line) => {
+    const match = line.match(/^(\s*)/);
+    return Math.min(min, match ? match[1].length : 0);
+  }, Infinity);
+  const indent = minIndent === Infinity ? 0 : minIndent;
+  return lines.map((line) => line.slice(indent)).join("\n").trim();
+}
+
+// src/api/yrestServer.ts
+init_cjs_shims();
+var import_node_path2 = require("path");
+
+// src/utils/handlers.ts
+init_cjs_shims();
+var import_node_fs = require("fs");
+async function loadHandlers(filePath) {
+  if (!(0, import_node_fs.existsSync)(filePath)) return /* @__PURE__ */ new Map();
+  try {
+    const mod = await import(filePath);
+    const map = /* @__PURE__ */ new Map();
+    for (const [name, value] of Object.entries(mod)) {
+      if (typeof value === "function") map.set(name, value);
+    }
+    return map;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`  \x1B[31m[handlers] failed to load ${filePath} \u2014 ${msg}\x1B[0m`);
+    return /* @__PURE__ */ new Map();
+  }
+}
+
+// src/api/yrestServer.ts
+init_deepCopy();
+
+// src/server/index.ts
+init_cjs_shims();
 
 // src/server/createServer.ts
+init_cjs_shims();
 var import_fastify = __toESM(require("fastify"));
 var import_cors = __toESM(require("@fastify/cors"));
 
+// src/router/resource.router.ts
+init_cjs_shims();
+
+// src/router/routes/index.ts
+init_cjs_shims();
+
+// src/router/routes/about.routes.ts
+init_cjs_shims();
+
+// src/router/templates/about.template.ts
+init_cjs_shims();
+
 // src/utils/interpolate.ts
-var import_node_crypto2 = require("crypto");
+init_cjs_shims();
+var import_node_crypto = require("crypto");
 function getPath(obj, path) {
   return path.split(".").reduce((acc, key) => {
     if (acc != null && typeof acc === "object") return acc[key];
@@ -134,7 +249,7 @@ function getPath(obj, path) {
 }
 function resolveVar(path, ctx) {
   if (path === "now") return (/* @__PURE__ */ new Date()).toISOString();
-  if (path === "uuid") return (0, import_node_crypto2.randomUUID)();
+  if (path === "uuid") return (0, import_node_crypto.randomUUID)();
   if (path === "body") return ctx.body;
   if (path.startsWith("body.")) return getPath(ctx.body, path.slice(5));
   if (path.startsWith("params.")) return ctx.params[path.slice(7)] ?? "";
@@ -609,7 +724,11 @@ var AboutRouteCommand = class {
   }
 };
 
+// src/router/routes/collection.routes.ts
+init_cjs_shims();
+
 // src/utils/params.ts
+init_cjs_shims();
 function nextId(items) {
   const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
@@ -620,6 +739,7 @@ function firstParam(value) {
 }
 
 // src/services/query.service.ts
+init_cjs_shims();
 var OPERATORS = ["_gte", "_lte", "_ne", "_like", "_start", "_regex"];
 function applyOperator(itemValue, op, filterValue) {
   const strItem = String(itemValue);
@@ -695,6 +815,7 @@ function paginate(items, page, limit) {
 }
 
 // src/services/resource.service.ts
+init_cjs_shims();
 function findById(items, id) {
   return items.find((i) => String(i["id"]) === id);
 }
@@ -742,6 +863,7 @@ function deleteItem(storage, resource, id) {
 }
 
 // src/services/expand.service.ts
+init_cjs_shims();
 function expandItems(input, query, resource, storage) {
   const isArray = Array.isArray(input);
   const items = isArray ? input : [input];
@@ -889,6 +1011,7 @@ var CollectionRouteCommand = class {
 };
 
 // src/router/routes/custom.routes.ts
+init_cjs_shims();
 var CustomRouteCommand = class {
   constructor(storage, base, handlers = /* @__PURE__ */ new Map()) {
     this.storage = storage;
@@ -955,6 +1078,7 @@ var CustomRouteCommand = class {
 };
 
 // src/router/routes/item.routes.ts
+init_cjs_shims();
 var ItemRouteCommand = class {
   constructor(storage, resource, base) {
     this.storage = storage;
@@ -1004,6 +1128,7 @@ var ItemRouteCommand = class {
 };
 
 // src/router/routes/nested.routes.ts
+init_cjs_shims();
 var NestedRouteCommand = class {
   constructor(storage, relations, base) {
     this.storage = storage;
@@ -1043,6 +1168,7 @@ var NestedRouteCommand = class {
 };
 
 // src/router/routes/snapshot.routes.ts
+init_cjs_shims();
 var SnapshotRouteCommand = class {
   constructor(storage) {
     this.storage = storage;
@@ -1132,9 +1258,119 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   return server;
 }
 
+// src/server/yrestServer.ts
+init_cjs_shims();
+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/api/yrestServer.ts
+function createYrestServer(options) {
+  const resolvedOptions = buildOptions(options);
+  let _inner = null;
+  return {
+    async start() {
+      const storage = "data" in options && options.data !== void 0 ? createInMemoryStorage(options.data) : (await Promise.resolve().then(() => (init_yrestStorage(), yrestStorage_exports))).createYrestStorage(resolvedOptions.file);
+      const handlers = resolvedOptions.handlers ? await loadHandlers((0, import_node_path2.resolve)(resolvedOptions.handlers)) : /* @__PURE__ */ new Map();
+      _inner = createYrestServerFromStorage(storage, resolvedOptions, handlers);
+      await _inner.start();
+    },
+    async stop() {
+      await _inner?.stop();
+    },
+    get port() {
+      return _inner?.port ?? 0;
+    },
+    get url() {
+      return _inner?.url ?? "";
+    }
+  };
+}
+function buildOptions(opts) {
+  const pageable = opts.pageable;
+  return {
+    file: "file" in opts && opts.file ? opts.file : "",
+    port: opts.port ?? 3070,
+    host: opts.host ?? "localhost",
+    base: opts.base ? opts.base.startsWith("/") ? opts.base : `/${opts.base}` : "",
+    watch: false,
+    snapshot: opts.snapshot ?? false,
+    readonly: opts.readonly ?? false,
+    delay: opts.delay ?? 0,
+    handlers: opts.handlers,
+    pageable: typeof pageable === "number" ? { enabled: true, limit: pageable } : pageable ? { enabled: true, limit: 10 } : { enabled: false, limit: 10 }
+  };
+}
+function createInMemoryStorage(data) {
+  const raw = data;
+  const relations = raw["_rel"] ?? {};
+  const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const collections = Object.fromEntries(
+    Object.entries(raw).filter(([k]) => k !== "_rel" && k !== "_routes")
+  );
+  let snapshot = {
+    data: deepCopyData(collections),
+    relations: { ...relations },
+    savedAt: /* @__PURE__ */ new Date()
+  };
+  return {
+    getData: () => collections,
+    getRelations: () => relations,
+    getRoutes: () => routes,
+    getCollection: (name) => collections[name],
+    setCollection: (name, items) => {
+      collections[name] = items;
+    },
+    persist: () => {
+    },
+    reload: () => {
+    },
+    getSnapshot: () => snapshot,
+    saveSnapshot: () => {
+      snapshot = {
+        data: deepCopyData(collections),
+        relations: { ...relations },
+        savedAt: /* @__PURE__ */ new Date()
+      };
+    },
+    resetToSnapshot: () => {
+      const snap = deepCopyData(snapshot.data);
+      for (const key of Object.keys(collections)) delete collections[key];
+      Object.assign(collections, snap);
+    }
+  };
+}
+
+// src/index.ts
+init_yrestStorage();
+
 // src/config/loadOptions.ts
+init_cjs_shims();
 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. */
@@ -1174,6 +1410,9 @@ var serverOptionsSchema = import_zod.z.object({
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createServer,
-  createYamlStorage,
-  serverOptionsSchema
+  createYrestServer,
+  createYrestServerFromStorage,
+  createYrestStorage,
+  yrest,
+  yrestOptionsSchema
 });