@aggiovato/yrest 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# yrest
+
+Zero-config REST API mock server powered by a YAML file.
+
+Define your data in a `db.yml` file and get a fully functional CRUD REST API in seconds — no backend required.
+
+## Install
+
+```bash
+npm install -D yrest
+```
+
+Or run directly with npx:
+
+```bash
+npx yrest serve db.yml
+```
+
+## Quick start
+
+```bash
+# Create a sample db.yml in the current directory
+npx yrest init
+
+# Start the server
+npx yrest serve db.yml
+```
+
+```txt
+yrest running at http://localhost:3070
+
+Resources (base: /):
+  /users
+  /posts
+```
+
+## Commands
+
+### `init`
+
+Creates a sample `db.yml` in the current directory.
+
+```bash
+yrest init                            # basic sample (default)
+yrest init --sample relational        # with _rel relations
+yrest init --file api.yml             # custom filename
+yrest init --sample relational --file api.yml
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--file` | `db.yml` | Output filename |
+| `--sample` | `basic` | Sample data (`basic`, `relational`) |
+
+**Samples:**
+- `basic` — two independent collections: `users` and `products`
+- `relational` — three collections with `_rel` relationships: `users`, `posts` and `comments`
+
+### `serve`
+
+Starts the mock server.
+
+```bash
+yrest serve db.yml
+yrest serve db.yml --port 3001
+yrest serve db.yml --host 0.0.0.0
+yrest serve db.yml --base /api
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port` | `3070` | Port to listen on |
+| `--host` | `localhost` | Host to bind |
+| `--base` | _(none)_ | Prefix for all routes |
+
+## Database format
+
+```yaml
+users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+posts:
+  - id: 1
+    title: First post
+    userId: 1
+```
+
+Each top-level key becomes a resource with full CRUD endpoints.
+
+## Generated endpoints
+
+For each resource in `db.yml`:
+
+```txt
+GET     /users          List all
+GET     /users/:id      Get one
+POST    /users          Create
+PUT     /users/:id      Replace
+PATCH   /users/:id      Partial update
+DELETE  /users/:id      Delete
+```
+
+With `--base /api` all routes are prefixed: `/api/users`, `/api/users/:id`, etc.
+
+## HTTP responses
+
+| Status | When |
+|--------|------|
+| `200` | Successful GET, PUT, PATCH, DELETE |
+| `201` | Successful POST |
+| `404` | Resource or id not found |
+| `500` | Error reading or writing the YAML file |
+
+DELETE returns the deleted item (useful for debugging).
+
+## ID generation
+
+If a POST body does not include an `id`, yrest assigns the next incremental integer automatically. If the body includes an `id`, it is respected.
+
+## Persistence
+
+All write operations (POST, PUT, PATCH, DELETE) are saved back to `db.yml` immediately using an atomic write strategy (write to temp file → rename), so data is never corrupted even if the process is interrupted.
+
+## CORS
+
+CORS is enabled by default, so you can call the API from any frontend running on a different port without extra configuration.
+
+## Frontend usage
+
+```ts
+// List
+const users = await fetch("http://localhost:3070/users").then(r => r.json());
+
+// Create
+await fetch("http://localhost:3070/users", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "Carlos", email: "carlos@test.com" }),
+});
+
+// Partial update
+await fetch("http://localhost:3070/users/1", {
+  method: "PATCH",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "Ana Updated" }),
+});
+
+// Delete
+await fetch("http://localhost:3070/users/1", { method: "DELETE" });
+```
+
+## Use in package.json scripts
+
+```json
+{
+  "scripts": {
+    "mock": "yrest serve db.yml"
+  }
+}
+```
+
+## License
+
+MIT

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli/index.ts
+var import_commander = require("commander");
+
+// src/cli/commands/init.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/cli/commands/templates/basic.ts
+var basicTemplate = `users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+products:
+  - id: 1
+    name: Laptop
+    price: 999
+  - id: 2
+    name: Phone
+    price: 499
+`;
+
+// src/cli/commands/templates/relational.ts
+var relationalTemplate = `_rel:
+  posts:
+    userId: users
+  comments:
+    postId: posts
+
+users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+posts:
+  - id: 1
+    title: First post
+    body: Content of the first post
+    userId: 1
+  - id: 2
+    title: Second post
+    body: Content of the second post
+    userId: 1
+
+comments:
+  - id: 1
+    body: Great post!
+    postId: 1
+  - id: 2
+    body: Thanks for sharing
+    postId: 1
+`;
+
+// src/cli/commands/templates/index.ts
+var SAMPLES = ["basic", "relational"];
+var templates = {
+  basic: basicTemplate,
+  relational: relationalTemplate
+};
+
+// src/cli/commands/init.ts
+function registerInit(program2) {
+  program2.command("init").description("Create a sample db.yml in the current directory").option("-f, --file <name>", "Output filename", "db.yml").option(
+    "-s, --sample <name>",
+    `Sample data to use (${SAMPLES.join(", ")})`,
+    "basic"
+  ).action((flags) => {
+    if (!SAMPLES.includes(flags.sample)) {
+      console.error(
+        `Error: unknown sample "${flags.sample}". Available: ${SAMPLES.join(", ")}`
+      );
+      process.exit(1);
+    }
+    const target = (0, import_node_path.resolve)(process.cwd(), flags.file);
+    if ((0, import_node_fs.existsSync)(target)) {
+      console.error(`Error: ${flags.file} already exists.`);
+      process.exit(1);
+    }
+    (0, import_node_fs.writeFileSync)(target, templates[flags.sample], "utf8");
+    console.log(`Created ${flags.file} (sample: ${flags.sample})`);
+    console.log(`Run: yrest serve ${flags.file}`);
+  });
+}
+
+// src/storage/yamlStorage.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_node_crypto = require("crypto");
+var import_yaml = require("yaml");
+function createYamlStorage(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"] ?? {};
+  const data = Object.fromEntries(
+    Object.entries(raw).filter(([key]) => key !== "_rel")
+  );
+  return {
+    getData() {
+      return data;
+    },
+    getRelations() {
+      return relations;
+    },
+    getCollection(name) {
+      return data[name];
+    },
+    setCollection(name, items) {
+      data[name] = items;
+    },
+    persist() {
+      const payload = Object.keys(relations).length > 0 ? { _rel: relations, ...data } : { ...data };
+      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto.randomUUID)()}.tmp`);
+      (0, import_node_fs2.writeFileSync)(tmp, (0, import_yaml.stringify)(payload), "utf8");
+      (0, import_node_fs2.renameSync)(tmp, absPath);
+    }
+  };
+}
+
+// src/server/createServer.ts
+var import_fastify = __toESM(require("fastify"));
+var import_cors = __toESM(require("@fastify/cors"));
+
+// src/services/resourceService.ts
+function nextId(items) {
+  const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+function findById(items, id) {
+  return items.find((i) => String(i["id"]) === id);
+}
+function findIndexById(items, id) {
+  return items.findIndex((i) => String(i["id"]) === id);
+}
+function createItem(storage, resource, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const item = {
+    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    ...body
+  };
+  storage.setCollection(resource, [...collection, item]);
+  storage.persist();
+  return item;
+}
+function replaceItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...body, id: collection[idx]["id"] };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function patchItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...collection[idx], ...body };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function deleteItem(storage, resource, id) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const [deleted] = collection.splice(idx, 1);
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return deleted;
+}
+
+// src/router/routes/collection.routes.ts
+function registerCollectionRoutes(server, storage, resource, prefix) {
+  server.get(prefix, () => storage.getCollection(resource) ?? []);
+  server.post(prefix, (req, reply) => {
+    const item = createItem(storage, resource, req.body);
+    return reply.status(201).send(item);
+  });
+}
+
+// src/router/routes/item.routes.ts
+function registerItemRoutes(server, storage, resource, prefix) {
+  server.get(`${prefix}/:id`, (req, reply) => {
+    const item = findById(storage.getCollection(resource) ?? [], req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.put(`${prefix}/:id`, (req, reply) => {
+    const item = replaceItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.patch(`${prefix}/:id`, (req, reply) => {
+    const item = patchItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.delete(`${prefix}/:id`, (req, reply) => {
+    const item = deleteItem(storage, resource, req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+}
+
+// src/router/routes/nested.routes.ts
+function registerNestedRoutes(server, storage, relations, base) {
+  for (const [child, fields] of Object.entries(relations)) {
+    for (const [field, parent] of Object.entries(fields)) {
+      server.get(
+        `${base}/${parent}/:id/${child}`,
+        (req, reply) => {
+          const parentCollection = storage.getCollection(parent) ?? [];
+          const parentItem = findById(parentCollection, req.params.id);
+          if (!parentItem) return reply.status(404).send({ error: "Not found" });
+          const children = (storage.getCollection(child) ?? []).filter(
+            (item) => String(item[field]) === req.params.id
+          );
+          return children;
+        }
+      );
+    }
+  }
+}
+
+// src/router/resource.router.ts
+function registerResourceRoutes(server, storage, base) {
+  for (const resource of Object.keys(storage.getData())) {
+    const prefix = `${base}/${resource}`;
+    registerCollectionRoutes(server, storage, resource, prefix);
+    registerItemRoutes(server, storage, resource, prefix);
+  }
+  registerNestedRoutes(server, storage, storage.getRelations(), base);
+}
+
+// src/server/createServer.ts
+async function createServer(storage, options) {
+  const server = (0, import_fastify.default)();
+  await server.register(import_cors.default);
+  registerResourceRoutes(server, storage, options.base);
+  return server;
+}
+
+// src/config/loadOptions.ts
+var import_zod = require("zod");
+var serverOptionsSchema = import_zod.z.object({
+  file: import_zod.z.string().min(1),
+  port: import_zod.z.coerce.number().int().positive().default(3070),
+  host: import_zod.z.string().default("localhost"),
+  base: import_zod.z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v)
+});
+
+// src/cli/commands/serve.ts
+function registerServe(program2) {
+  program2.command("serve").description("Start the mock server using a YAML file as database").argument("[file]", "Path to the YAML database file", "db.yml").option("-p, --port <number>", "Port to listen on", "3070").option("-H, --host <host>", "Host to bind", "localhost").option("-b, --base <path>", "Base path prefix for all routes", "").action(async (file, flags) => {
+    const options = serverOptionsSchema.parse({
+      file,
+      port: flags["port"],
+      host: flags["host"],
+      base: flags["base"]
+    });
+    const storage = createYamlStorage(options.file);
+    const server = await createServer(storage, options);
+    await server.listen({ port: options.port, host: options.host });
+    const collections = Object.keys(storage.getData());
+    const baseLabel = options.base || "/";
+    console.log(`
+yrest running at http://${options.host}:${options.port}`);
+    console.log(`
+Resources (base: ${baseLabel}):`);
+    for (const name of collections) {
+      console.log(`  /${name}`);
+    }
+    console.log("");
+  });
+}
+
+// src/cli/index.ts
+import_commander.program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version("0.1.0");
+registerInit(import_commander.program);
+registerServe(import_commander.program);
+import_commander.program.parse();

package/dist/cli/index.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { program } from "commander";
+
+// src/cli/commands/init.ts
+import { existsSync, writeFileSync } from "fs";
+import { resolve } from "path";
+
+// src/cli/commands/templates/basic.ts
+var basicTemplate = `users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+products:
+  - id: 1
+    name: Laptop
+    price: 999
+  - id: 2
+    name: Phone
+    price: 499
+`;
+
+// src/cli/commands/templates/relational.ts
+var relationalTemplate = `_rel:
+  posts:
+    userId: users
+  comments:
+    postId: posts
+
+users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+posts:
+  - id: 1
+    title: First post
+    body: Content of the first post
+    userId: 1
+  - id: 2
+    title: Second post
+    body: Content of the second post
+    userId: 1
+
+comments:
+  - id: 1
+    body: Great post!
+    postId: 1
+  - id: 2
+    body: Thanks for sharing
+    postId: 1
+`;
+
+// src/cli/commands/templates/index.ts
+var SAMPLES = ["basic", "relational"];
+var templates = {
+  basic: basicTemplate,
+  relational: relationalTemplate
+};
+
+// src/cli/commands/init.ts
+function registerInit(program2) {
+  program2.command("init").description("Create a sample db.yml in the current directory").option("-f, --file <name>", "Output filename", "db.yml").option(
+    "-s, --sample <name>",
+    `Sample data to use (${SAMPLES.join(", ")})`,
+    "basic"
+  ).action((flags) => {
+    if (!SAMPLES.includes(flags.sample)) {
+      console.error(
+        `Error: unknown sample "${flags.sample}". Available: ${SAMPLES.join(", ")}`
+      );
+      process.exit(1);
+    }
+    const target = resolve(process.cwd(), flags.file);
+    if (existsSync(target)) {
+      console.error(`Error: ${flags.file} already exists.`);
+      process.exit(1);
+    }
+    writeFileSync(target, templates[flags.sample], "utf8");
+    console.log(`Created ${flags.file} (sample: ${flags.sample})`);
+    console.log(`Run: yrest serve ${flags.file}`);
+  });
+}
+
+// src/storage/yamlStorage.ts
+import { readFileSync, writeFileSync as writeFileSync2, renameSync } from "fs";
+import { resolve as resolve2, dirname } from "path";
+import { randomUUID } from "crypto";
+import { parse, stringify } from "yaml";
+function createYamlStorage(filePath) {
+  const absPath = resolve2(filePath);
+  const raw = parse(readFileSync(absPath, "utf8")) ?? {};
+  const relations = raw["_rel"] ?? {};
+  const data = Object.fromEntries(
+    Object.entries(raw).filter(([key]) => key !== "_rel")
+  );
+  return {
+    getData() {
+      return data;
+    },
+    getRelations() {
+      return relations;
+    },
+    getCollection(name) {
+      return data[name];
+    },
+    setCollection(name, items) {
+      data[name] = items;
+    },
+    persist() {
+      const payload = Object.keys(relations).length > 0 ? { _rel: relations, ...data } : { ...data };
+      const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID()}.tmp`);
+      writeFileSync2(tmp, stringify(payload), "utf8");
+      renameSync(tmp, absPath);
+    }
+  };
+}
+
+// src/server/createServer.ts
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+
+// src/services/resourceService.ts
+function nextId(items) {
+  const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+function findById(items, id) {
+  return items.find((i) => String(i["id"]) === id);
+}
+function findIndexById(items, id) {
+  return items.findIndex((i) => String(i["id"]) === id);
+}
+function createItem(storage, resource, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const item = {
+    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    ...body
+  };
+  storage.setCollection(resource, [...collection, item]);
+  storage.persist();
+  return item;
+}
+function replaceItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...body, id: collection[idx]["id"] };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function patchItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...collection[idx], ...body };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function deleteItem(storage, resource, id) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const [deleted] = collection.splice(idx, 1);
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return deleted;
+}
+
+// src/router/routes/collection.routes.ts
+function registerCollectionRoutes(server, storage, resource, prefix) {
+  server.get(prefix, () => storage.getCollection(resource) ?? []);
+  server.post(prefix, (req, reply) => {
+    const item = createItem(storage, resource, req.body);
+    return reply.status(201).send(item);
+  });
+}
+
+// src/router/routes/item.routes.ts
+function registerItemRoutes(server, storage, resource, prefix) {
+  server.get(`${prefix}/:id`, (req, reply) => {
+    const item = findById(storage.getCollection(resource) ?? [], req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.put(`${prefix}/:id`, (req, reply) => {
+    const item = replaceItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.patch(`${prefix}/:id`, (req, reply) => {
+    const item = patchItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.delete(`${prefix}/:id`, (req, reply) => {
+    const item = deleteItem(storage, resource, req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+}
+
+// src/router/routes/nested.routes.ts
+function registerNestedRoutes(server, storage, relations, base) {
+  for (const [child, fields] of Object.entries(relations)) {
+    for (const [field, parent] of Object.entries(fields)) {
+      server.get(
+        `${base}/${parent}/:id/${child}`,
+        (req, reply) => {
+          const parentCollection = storage.getCollection(parent) ?? [];
+          const parentItem = findById(parentCollection, req.params.id);
+          if (!parentItem) return reply.status(404).send({ error: "Not found" });
+          const children = (storage.getCollection(child) ?? []).filter(
+            (item) => String(item[field]) === req.params.id
+          );
+          return children;
+        }
+      );
+    }
+  }
+}
+
+// src/router/resource.router.ts
+function registerResourceRoutes(server, storage, base) {
+  for (const resource of Object.keys(storage.getData())) {
+    const prefix = `${base}/${resource}`;
+    registerCollectionRoutes(server, storage, resource, prefix);
+    registerItemRoutes(server, storage, resource, prefix);
+  }
+  registerNestedRoutes(server, storage, storage.getRelations(), base);
+}
+
+// src/server/createServer.ts
+async function createServer(storage, options) {
+  const server = Fastify();
+  await server.register(cors);
+  registerResourceRoutes(server, storage, options.base);
+  return server;
+}
+
+// src/config/loadOptions.ts
+import { z } from "zod";
+var serverOptionsSchema = z.object({
+  file: z.string().min(1),
+  port: z.coerce.number().int().positive().default(3070),
+  host: z.string().default("localhost"),
+  base: z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v)
+});
+
+// src/cli/commands/serve.ts
+function registerServe(program2) {
+  program2.command("serve").description("Start the mock server using a YAML file as database").argument("[file]", "Path to the YAML database file", "db.yml").option("-p, --port <number>", "Port to listen on", "3070").option("-H, --host <host>", "Host to bind", "localhost").option("-b, --base <path>", "Base path prefix for all routes", "").action(async (file, flags) => {
+    const options = serverOptionsSchema.parse({
+      file,
+      port: flags["port"],
+      host: flags["host"],
+      base: flags["base"]
+    });
+    const storage = createYamlStorage(options.file);
+    const server = await createServer(storage, options);
+    await server.listen({ port: options.port, host: options.host });
+    const collections = Object.keys(storage.getData());
+    const baseLabel = options.base || "/";
+    console.log(`
+yrest running at http://${options.host}:${options.port}`);
+    console.log(`
+Resources (base: ${baseLabel}):`);
+    for (const name of collections) {
+      console.log(`  /${name}`);
+    }
+    console.log("");
+  });
+}
+
+// src/cli/index.ts
+program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version("0.1.0");
+registerInit(program);
+registerServe(program);
+program.parse();

package/dist/index.d.mts

@@ -0,0 +1,38 @@
+import * as fastify from 'fastify';
+import * as http from 'http';
+import { z } from 'zod';
+
+type Resource = Record<string, unknown>;
+type DbData = Record<string, Resource[]>;
+type Relations = Record<string, Record<string, string>>;
+
+interface YamlStorage {
+    getData(): DbData;
+    getRelations(): Relations;
+    getCollection(name: string): Resource[] | undefined;
+    setCollection(name: string, items: Resource[]): void;
+    persist(): void;
+}
+declare function createYamlStorage(filePath: string): YamlStorage;
+
+declare const serverOptionsSchema: z.ZodObject<{
+    file: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
+    base: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    port: number;
+    host: string;
+    base: string;
+}, {
+    file: string;
+    port?: number | undefined;
+    host?: string | undefined;
+    base?: string | undefined;
+}>;
+type ServerOptions = z.infer<typeof serverOptionsSchema>;
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import * as fastify from 'fastify';
+import * as http from 'http';
+import { z } from 'zod';
+
+type Resource = Record<string, unknown>;
+type DbData = Record<string, Resource[]>;
+type Relations = Record<string, Record<string, string>>;
+
+interface YamlStorage {
+    getData(): DbData;
+    getRelations(): Relations;
+    getCollection(name: string): Resource[] | undefined;
+    setCollection(name: string, items: Resource[]): void;
+    persist(): void;
+}
+declare function createYamlStorage(filePath: string): YamlStorage;
+
+declare const serverOptionsSchema: z.ZodObject<{
+    file: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
+    base: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    port: number;
+    host: string;
+    base: string;
+}, {
+    file: string;
+    port?: number | undefined;
+    host?: string | undefined;
+    base?: string | undefined;
+}>;
+type ServerOptions = z.infer<typeof serverOptionsSchema>;
+
+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 };

package/dist/index.js

@@ -0,0 +1,212 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createServer: () => createServer,
+  createYamlStorage: () => createYamlStorage,
+  serverOptionsSchema: () => serverOptionsSchema
+});
+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");
+function createYamlStorage(filePath) {
+  const absPath = (0, import_node_path.resolve)(filePath);
+  const raw = (0, import_yaml.parse)((0, import_node_fs.readFileSync)(absPath, "utf8")) ?? {};
+  const relations = raw["_rel"] ?? {};
+  const data = Object.fromEntries(
+    Object.entries(raw).filter(([key]) => key !== "_rel")
+  );
+  return {
+    getData() {
+      return data;
+    },
+    getRelations() {
+      return relations;
+    },
+    getCollection(name) {
+      return data[name];
+    },
+    setCollection(name, items) {
+      data[name] = items;
+    },
+    persist() {
+      const payload = Object.keys(relations).length > 0 ? { _rel: relations, ...data } : { ...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);
+    }
+  };
+}
+
+// src/server/createServer.ts
+var import_fastify = __toESM(require("fastify"));
+var import_cors = __toESM(require("@fastify/cors"));
+
+// src/services/resourceService.ts
+function nextId(items) {
+  const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+function findById(items, id) {
+  return items.find((i) => String(i["id"]) === id);
+}
+function findIndexById(items, id) {
+  return items.findIndex((i) => String(i["id"]) === id);
+}
+function createItem(storage, resource, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const item = {
+    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    ...body
+  };
+  storage.setCollection(resource, [...collection, item]);
+  storage.persist();
+  return item;
+}
+function replaceItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...body, id: collection[idx]["id"] };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function patchItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...collection[idx], ...body };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function deleteItem(storage, resource, id) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const [deleted] = collection.splice(idx, 1);
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return deleted;
+}
+
+// src/router/routes/collection.routes.ts
+function registerCollectionRoutes(server, storage, resource, prefix) {
+  server.get(prefix, () => storage.getCollection(resource) ?? []);
+  server.post(prefix, (req, reply) => {
+    const item = createItem(storage, resource, req.body);
+    return reply.status(201).send(item);
+  });
+}
+
+// src/router/routes/item.routes.ts
+function registerItemRoutes(server, storage, resource, prefix) {
+  server.get(`${prefix}/:id`, (req, reply) => {
+    const item = findById(storage.getCollection(resource) ?? [], req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.put(`${prefix}/:id`, (req, reply) => {
+    const item = replaceItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.patch(`${prefix}/:id`, (req, reply) => {
+    const item = patchItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.delete(`${prefix}/:id`, (req, reply) => {
+    const item = deleteItem(storage, resource, req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+}
+
+// src/router/routes/nested.routes.ts
+function registerNestedRoutes(server, storage, relations, base) {
+  for (const [child, fields] of Object.entries(relations)) {
+    for (const [field, parent] of Object.entries(fields)) {
+      server.get(
+        `${base}/${parent}/:id/${child}`,
+        (req, reply) => {
+          const parentCollection = storage.getCollection(parent) ?? [];
+          const parentItem = findById(parentCollection, req.params.id);
+          if (!parentItem) return reply.status(404).send({ error: "Not found" });
+          const children = (storage.getCollection(child) ?? []).filter(
+            (item) => String(item[field]) === req.params.id
+          );
+          return children;
+        }
+      );
+    }
+  }
+}
+
+// src/router/resource.router.ts
+function registerResourceRoutes(server, storage, base) {
+  for (const resource of Object.keys(storage.getData())) {
+    const prefix = `${base}/${resource}`;
+    registerCollectionRoutes(server, storage, resource, prefix);
+    registerItemRoutes(server, storage, resource, prefix);
+  }
+  registerNestedRoutes(server, storage, storage.getRelations(), base);
+}
+
+// src/server/createServer.ts
+async function createServer(storage, options) {
+  const server = (0, import_fastify.default)();
+  await server.register(import_cors.default);
+  registerResourceRoutes(server, storage, options.base);
+  return server;
+}
+
+// src/config/loadOptions.ts
+var import_zod = require("zod");
+var serverOptionsSchema = import_zod.z.object({
+  file: import_zod.z.string().min(1),
+  port: import_zod.z.coerce.number().int().positive().default(3070),
+  host: import_zod.z.string().default("localhost"),
+  base: import_zod.z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v)
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createServer,
+  createYamlStorage,
+  serverOptionsSchema
+});

package/dist/index.mjs

@@ -0,0 +1,173 @@
+// src/storage/yamlStorage.ts
+import { readFileSync, writeFileSync, renameSync } from "fs";
+import { resolve, dirname } from "path";
+import { randomUUID } from "crypto";
+import { parse, stringify } from "yaml";
+function createYamlStorage(filePath) {
+  const absPath = resolve(filePath);
+  const raw = parse(readFileSync(absPath, "utf8")) ?? {};
+  const relations = raw["_rel"] ?? {};
+  const data = Object.fromEntries(
+    Object.entries(raw).filter(([key]) => key !== "_rel")
+  );
+  return {
+    getData() {
+      return data;
+    },
+    getRelations() {
+      return relations;
+    },
+    getCollection(name) {
+      return data[name];
+    },
+    setCollection(name, items) {
+      data[name] = items;
+    },
+    persist() {
+      const payload = Object.keys(relations).length > 0 ? { _rel: relations, ...data } : { ...data };
+      const tmp = resolve(dirname(absPath), `.yrest-${randomUUID()}.tmp`);
+      writeFileSync(tmp, stringify(payload), "utf8");
+      renameSync(tmp, absPath);
+    }
+  };
+}
+
+// src/server/createServer.ts
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+
+// src/services/resourceService.ts
+function nextId(items) {
+  const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+function findById(items, id) {
+  return items.find((i) => String(i["id"]) === id);
+}
+function findIndexById(items, id) {
+  return items.findIndex((i) => String(i["id"]) === id);
+}
+function createItem(storage, resource, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const item = {
+    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    ...body
+  };
+  storage.setCollection(resource, [...collection, item]);
+  storage.persist();
+  return item;
+}
+function replaceItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...body, id: collection[idx]["id"] };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function patchItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...collection[idx], ...body };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function deleteItem(storage, resource, id) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const [deleted] = collection.splice(idx, 1);
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return deleted;
+}
+
+// src/router/routes/collection.routes.ts
+function registerCollectionRoutes(server, storage, resource, prefix) {
+  server.get(prefix, () => storage.getCollection(resource) ?? []);
+  server.post(prefix, (req, reply) => {
+    const item = createItem(storage, resource, req.body);
+    return reply.status(201).send(item);
+  });
+}
+
+// src/router/routes/item.routes.ts
+function registerItemRoutes(server, storage, resource, prefix) {
+  server.get(`${prefix}/:id`, (req, reply) => {
+    const item = findById(storage.getCollection(resource) ?? [], req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.put(`${prefix}/:id`, (req, reply) => {
+    const item = replaceItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.patch(`${prefix}/:id`, (req, reply) => {
+    const item = patchItem(storage, resource, req.params.id, req.body);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+  server.delete(`${prefix}/:id`, (req, reply) => {
+    const item = deleteItem(storage, resource, req.params.id);
+    if (!item) return reply.status(404).send({ error: "Not found" });
+    return item;
+  });
+}
+
+// src/router/routes/nested.routes.ts
+function registerNestedRoutes(server, storage, relations, base) {
+  for (const [child, fields] of Object.entries(relations)) {
+    for (const [field, parent] of Object.entries(fields)) {
+      server.get(
+        `${base}/${parent}/:id/${child}`,
+        (req, reply) => {
+          const parentCollection = storage.getCollection(parent) ?? [];
+          const parentItem = findById(parentCollection, req.params.id);
+          if (!parentItem) return reply.status(404).send({ error: "Not found" });
+          const children = (storage.getCollection(child) ?? []).filter(
+            (item) => String(item[field]) === req.params.id
+          );
+          return children;
+        }
+      );
+    }
+  }
+}
+
+// src/router/resource.router.ts
+function registerResourceRoutes(server, storage, base) {
+  for (const resource of Object.keys(storage.getData())) {
+    const prefix = `${base}/${resource}`;
+    registerCollectionRoutes(server, storage, resource, prefix);
+    registerItemRoutes(server, storage, resource, prefix);
+  }
+  registerNestedRoutes(server, storage, storage.getRelations(), base);
+}
+
+// src/server/createServer.ts
+async function createServer(storage, options) {
+  const server = Fastify();
+  await server.register(cors);
+  registerResourceRoutes(server, storage, options.base);
+  return server;
+}
+
+// src/config/loadOptions.ts
+import { z } from "zod";
+var serverOptionsSchema = z.object({
+  file: z.string().min(1),
+  port: z.coerce.number().int().positive().default(3070),
+  host: z.string().default("localhost"),
+  base: z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v)
+});
+export {
+  createServer,
+  createYamlStorage,
+  serverOptionsSchema
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@aggiovato/yrest",
+  "version": "0.1.0",
+  "description": "Zero-config REST API mock server powered by a YAML file",
+  "keywords": [
+    "yaml",
+    "rest",
+    "mock",
+    "api",
+    "cli",
+    "fastify"
+  ],
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "yrest": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.0",
+    "commander": "^12.1.0",
+    "fastify": "^5.0.0",
+    "yaml": "^2.4.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}