@yrest/cli 0.12.0 → 0.13.0

package/README.md

@@ -10,7 +10,7 @@
 [![CI](https://github.com/aggiovato/yRest/actions/workflows/ci.yml/badge.svg)](https://github.com/aggiovato/yRest/actions)
 [![Node](https://img.shields.io/node/v/@yrest/cli)](https://www.npmjs.com/package/@yrest/cli)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.typescriptlang.org/)
-[![Socket](https://badge.socket.dev/npm/package/@yrest/cli/0.12.0)](https://socket.dev/npm/package/@yrest/cli)
+[![Socket](https://badge.socket.dev/npm/package/@yrest/cli/0.13.0)](https://socket.dev/npm/package/@yrest/cli)
 
 YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a `db.yml` file.
 
@@ -257,6 +257,31 @@ _data:
 
 Both formats are equivalent. You can also mix them — if the same collection name appears both inside `_data` and at the root level, the root-level entry wins. The file is persisted in whichever format it was originally written.
 
+### Data directives (`__uuid_gen`, `__fk`)
+
+Use `__uuid_gen` and `__fk` directives to generate UUID-based IDs and cross-collection references automatically. yRest resolves all directives on first load and rewrites the file with real values — subsequent restarts are stable.
+
+```yaml
+users:
+  - id: __uuid_gen:ana # generates a UUID and registers alias "ana"
+    name: Ana
+  - id: __uuid_gen:luis # generates a UUID and registers alias "luis"
+    name: Luis
+
+posts:
+  - id: __uuid_gen # generates a UUID (no alias needed)
+    title: Hello World
+    userId: __fk.users:ana # resolves to the UUID registered as "ana" in users
+```
+
+| Directive               | Meaning                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| `__uuid_gen`            | Generate a UUID v4 for this field                                |
+| `__uuid_gen:alias`      | Generate a UUID and register it under `alias` in this collection |
+| `__fk.collection:alias` | Resolve to the UUID registered as `alias` in `collection`        |
+
+Aliases are scoped to their collection — `__uuid_gen:ale` in `users` and `__uuid_gen:ale` in `categories` are independent.
+
 ---
 
 ## Field annotations (`_schema`)

package/dist/cli/index.js

@@ -115,6 +115,7 @@ categories:
 // src/cli/commands/templates/relational.ts
 var relationalTemplate = `# yrest relational sample \u2014 blog
 # Demonstrates: many2one, one2one and many2many relationships
+# Also shows __uuid_gen and __fk directives for UUID-based IDs
 # Run: npx @yrest/cli serve db.yml
 # Docs: GET http://localhost:3070/_about
 
@@ -139,33 +140,36 @@ _rel:
       _type: one2one
       _target: users
 
+# __uuid_gen:alias generates a UUID and registers it under that alias.
+# __fk.collection:alias resolves to the UUID registered in that collection.
+# yRest rewrites this file on first run, replacing all directives with real values.
 users:
-  - id: 1
+  - id: __uuid_gen:ana
     name: Ana Garc\xEDa
     email: ana@example.com
     role: author
-  - id: 2
+  - id: __uuid_gen:luis
     name: Luis Mart\xEDnez
     email: luis@example.com
     role: author
-  - id: 3
+  - id: __uuid_gen:sara
     name: Sara L\xF3pez
     email: sara@example.com
     role: reader
 
 profiles:
-  - id: 1
-    userId: 1
+  - id: __uuid_gen
+    userId: __fk.users:ana
     bio: Full-stack developer and open-source enthusiast
     avatar: https://i.pravatar.cc/150?img=1
     website: https://ana.dev
-  - id: 2
-    userId: 2
+  - id: __uuid_gen
+    userId: __fk.users:luis
     bio: Backend engineer, coffee addict
     avatar: https://i.pravatar.cc/150?img=2
     website: https://luisdev.io
-  - id: 3
-    userId: 3
+  - id: __uuid_gen
+    userId: __fk.users:sara
     bio: Designer turned frontend developer
     avatar: https://i.pravatar.cc/150?img=3
     website: null
@@ -188,75 +192,75 @@ tags:
     color: "#ef4444"
 
 posts:
-  - id: 1
+  - id: __uuid_gen:post-ts
     title: Getting started with TypeScript
     slug: getting-started-typescript
     body: TypeScript adds static typing to JavaScript, catching errors at compile time...
-    userId: 1
+    userId: __fk.users:ana
     published: true
     views: 1420
     createdAt: "2024-11-01"
-  - id: 2
+  - id: __uuid_gen:post-fastify
     title: Building REST APIs with Fastify
     slug: rest-apis-fastify
     body: Fastify is the fastest Node.js web framework, perfect for building APIs...
-    userId: 1
+    userId: __fk.users:ana
     published: true
     views: 980
     createdAt: "2024-11-15"
-  - id: 3
+  - id: __uuid_gen:post-testing
     title: Testing strategies for modern apps
     slug: testing-strategies-modern
     body: A solid test strategy covers unit, integration and end-to-end scenarios...
-    userId: 2
+    userId: __fk.users:luis
     published: true
     views: 640
     createdAt: "2024-12-03"
-  - id: 4
+  - id: __uuid_gen:post-yaml
     title: YAML as a database format
     slug: yaml-database-format
     body: YAML is human-readable and expressive enough for mock data during development...
-    userId: 2
+    userId: __fk.users:luis
     published: false
     views: 0
     createdAt: "2025-01-10"
 
 # pivot table for posts \u2194 tags (many2many)
 post_tags:
-  - { id: 1, postId: 1, tagId: 1 }
-  - { id: 2, postId: 1, tagId: 2 }
-  - { id: 3, postId: 2, tagId: 2 }
-  - { id: 4, postId: 2, tagId: 4 }
-  - { id: 5, postId: 3, tagId: 3 }
-  - { id: 6, postId: 3, tagId: 1 }
-  - { id: 7, postId: 4, tagId: 5 }
-  - { id: 8, postId: 4, tagId: 2 }
+  - { id: 1, postId: __fk.posts:post-ts,      tagId: 1 }
+  - { id: 2, postId: __fk.posts:post-ts,      tagId: 2 }
+  - { id: 3, postId: __fk.posts:post-fastify, tagId: 2 }
+  - { id: 4, postId: __fk.posts:post-fastify, tagId: 4 }
+  - { id: 5, postId: __fk.posts:post-testing, tagId: 3 }
+  - { id: 6, postId: __fk.posts:post-testing, tagId: 1 }
+  - { id: 7, postId: __fk.posts:post-yaml,    tagId: 5 }
+  - { id: 8, postId: __fk.posts:post-yaml,    tagId: 2 }
 
 comments:
   - id: 1
     body: Great introduction! This helped me a lot.
-    postId: 1
-    userId: 3
+    postId: __fk.posts:post-ts
+    userId: __fk.users:sara
     likes: 5
   - id: 2
     body: Could you cover generics in a follow-up post?
-    postId: 1
-    userId: 2
+    postId: __fk.posts:post-ts
+    userId: __fk.users:luis
     likes: 3
   - id: 3
     body: Fastify is indeed much faster than Express in my benchmarks.
-    postId: 2
-    userId: 3
+    postId: __fk.posts:post-fastify
+    userId: __fk.users:sara
     likes: 8
   - id: 4
     body: Do you have a GitHub repo with these examples?
-    postId: 2
-    userId: 1
+    postId: __fk.posts:post-fastify
+    userId: __fk.users:ana
     likes: 1
   - id: 5
     body: E2E tests are underrated. Solid post!
-    postId: 3
-    userId: 1
+    postId: __fk.posts:post-testing
+    userId: __fk.users:ana
     likes: 4
 
 # Try these queries:
@@ -546,7 +550,7 @@ var import_node_path4 = require("path");
 // src/storage/yrestStorage.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var import_yaml = require("yaml");
 
 // src/storage/parseRelations.ts
@@ -818,6 +822,51 @@ function hasDataBlock(raw) {
   return d !== null && d !== void 0 && typeof d === "object" && !Array.isArray(d);
 }
 
+// src/storage/resolveDirectives.ts
+var import_node_crypto = require("crypto");
+var UUID_GEN_RE = /^__uuid_gen(?::([a-zA-Z0-9_-]+))?$/;
+var FK_RE = /^__fk\.([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)$/;
+function resolveDirectives(data) {
+  const registry = /* @__PURE__ */ new Map();
+  let modified = false;
+  for (const [collection, items] of Object.entries(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = UUID_GEN_RE.exec(value);
+        if (!m) continue;
+        const uuid = (0, import_node_crypto.randomUUID)();
+        item[field] = uuid;
+        modified = true;
+        const alias = m[1];
+        if (alias) {
+          if (!registry.has(collection)) registry.set(collection, /* @__PURE__ */ new Map());
+          registry.get(collection).set(alias, uuid);
+        }
+      }
+    }
+  }
+  for (const items of Object.values(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = FK_RE.exec(value);
+        if (!m) continue;
+        const col = m[1];
+        const alias = m[2];
+        const uuid = registry.get(col)?.get(alias);
+        if (uuid !== void 0) {
+          item[field] = uuid;
+          modified = true;
+        } else {
+          console.warn(`yrest: cannot resolve __fk.${col}:${alias} \u2014 alias not registered`);
+        }
+      }
+    }
+  }
+  return modified;
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -889,12 +938,13 @@ function createYrestStorage(filePath) {
   const schema = parseSchema(raw["_schema"]);
   const dataBlock = hasDataBlock(raw);
   const data = parseData(raw);
+  const directivesModified = resolveDirectives(data);
   let snapshot = {
     data: deepCopyData(data),
     relations: { ...relations },
     savedAt: /* @__PURE__ */ new Date()
   };
-  return {
+  const storage = {
     getData() {
       return data;
     },
@@ -925,7 +975,7 @@ function createYrestStorage(filePath) {
       } else {
         Object.assign(payload, data);
       }
-      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto.randomUUID)()}.tmp`);
+      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto2.randomUUID)()}.tmp`);
       (0, import_node_fs2.writeFileSync)(tmp, (0, import_yaml.stringify)(payload), "utf8");
       (0, import_node_fs2.renameSync)(tmp, absPath);
     },
@@ -937,6 +987,7 @@ function createYrestStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+      if (resolveDirectives(data)) storage.persist();
     },
     getSnapshot() {
       return snapshot;
@@ -957,6 +1008,8 @@ function createYrestStorage(filePath) {
       this.persist();
     }
   };
+  if (directivesModified) storage.persist();
+  return storage;
 }
 
 // src/server/createServer.ts
@@ -969,7 +1022,7 @@ var import_node_path3 = require("path");
 var import_node_url = require("url");
 
 // src/utils/interpolate.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 function getPath(obj, path) {
   return path.split(".").reduce((acc, key) => {
     if (acc != null && typeof acc === "object") return acc[key];
@@ -978,7 +1031,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_crypto3.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)] ?? "";
@@ -3483,11 +3536,18 @@ function registerServe(program2) {
     "--id-strategy <strategy>",
     "Id generation strategy for new items: increment (default) or uuid",
     "increment"
+  ).option(
+    "--uuid",
+    "Shorthand for --id-strategy uuid: assign UUID ids to new items created via POST"
   ).action(async (file, flags, cmd) => {
     const fileConfig = loadConfigFile((0, import_node_path4.join)(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
       Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
     );
+    if (cliOverrides["uuid"] === true) {
+      cliOverrides["idStrategy"] = "uuid";
+      delete cliOverrides["uuid"];
+    }
     const options = buildServeOptions(file, fileConfig, cliOverrides, cmd.args.length > 0);
     let storage;
     try {

package/dist/cli/index.mjs

@@ -88,6 +88,7 @@ categories:
 // src/cli/commands/templates/relational.ts
 var relationalTemplate = `# yrest relational sample \u2014 blog
 # Demonstrates: many2one, one2one and many2many relationships
+# Also shows __uuid_gen and __fk directives for UUID-based IDs
 # Run: npx @yrest/cli serve db.yml
 # Docs: GET http://localhost:3070/_about
 
@@ -112,33 +113,36 @@ _rel:
       _type: one2one
       _target: users
 
+# __uuid_gen:alias generates a UUID and registers it under that alias.
+# __fk.collection:alias resolves to the UUID registered in that collection.
+# yRest rewrites this file on first run, replacing all directives with real values.
 users:
-  - id: 1
+  - id: __uuid_gen:ana
     name: Ana Garc\xEDa
     email: ana@example.com
     role: author
-  - id: 2
+  - id: __uuid_gen:luis
     name: Luis Mart\xEDnez
     email: luis@example.com
     role: author
-  - id: 3
+  - id: __uuid_gen:sara
     name: Sara L\xF3pez
     email: sara@example.com
     role: reader
 
 profiles:
-  - id: 1
-    userId: 1
+  - id: __uuid_gen
+    userId: __fk.users:ana
     bio: Full-stack developer and open-source enthusiast
     avatar: https://i.pravatar.cc/150?img=1
     website: https://ana.dev
-  - id: 2
-    userId: 2
+  - id: __uuid_gen
+    userId: __fk.users:luis
     bio: Backend engineer, coffee addict
     avatar: https://i.pravatar.cc/150?img=2
     website: https://luisdev.io
-  - id: 3
-    userId: 3
+  - id: __uuid_gen
+    userId: __fk.users:sara
     bio: Designer turned frontend developer
     avatar: https://i.pravatar.cc/150?img=3
     website: null
@@ -161,75 +165,75 @@ tags:
     color: "#ef4444"
 
 posts:
-  - id: 1
+  - id: __uuid_gen:post-ts
     title: Getting started with TypeScript
     slug: getting-started-typescript
     body: TypeScript adds static typing to JavaScript, catching errors at compile time...
-    userId: 1
+    userId: __fk.users:ana
     published: true
     views: 1420
     createdAt: "2024-11-01"
-  - id: 2
+  - id: __uuid_gen:post-fastify
     title: Building REST APIs with Fastify
     slug: rest-apis-fastify
     body: Fastify is the fastest Node.js web framework, perfect for building APIs...
-    userId: 1
+    userId: __fk.users:ana
     published: true
     views: 980
     createdAt: "2024-11-15"
-  - id: 3
+  - id: __uuid_gen:post-testing
     title: Testing strategies for modern apps
     slug: testing-strategies-modern
     body: A solid test strategy covers unit, integration and end-to-end scenarios...
-    userId: 2
+    userId: __fk.users:luis
     published: true
     views: 640
     createdAt: "2024-12-03"
-  - id: 4
+  - id: __uuid_gen:post-yaml
     title: YAML as a database format
     slug: yaml-database-format
     body: YAML is human-readable and expressive enough for mock data during development...
-    userId: 2
+    userId: __fk.users:luis
     published: false
     views: 0
     createdAt: "2025-01-10"
 
 # pivot table for posts \u2194 tags (many2many)
 post_tags:
-  - { id: 1, postId: 1, tagId: 1 }
-  - { id: 2, postId: 1, tagId: 2 }
-  - { id: 3, postId: 2, tagId: 2 }
-  - { id: 4, postId: 2, tagId: 4 }
-  - { id: 5, postId: 3, tagId: 3 }
-  - { id: 6, postId: 3, tagId: 1 }
-  - { id: 7, postId: 4, tagId: 5 }
-  - { id: 8, postId: 4, tagId: 2 }
+  - { id: 1, postId: __fk.posts:post-ts,      tagId: 1 }
+  - { id: 2, postId: __fk.posts:post-ts,      tagId: 2 }
+  - { id: 3, postId: __fk.posts:post-fastify, tagId: 2 }
+  - { id: 4, postId: __fk.posts:post-fastify, tagId: 4 }
+  - { id: 5, postId: __fk.posts:post-testing, tagId: 3 }
+  - { id: 6, postId: __fk.posts:post-testing, tagId: 1 }
+  - { id: 7, postId: __fk.posts:post-yaml,    tagId: 5 }
+  - { id: 8, postId: __fk.posts:post-yaml,    tagId: 2 }
 
 comments:
   - id: 1
     body: Great introduction! This helped me a lot.
-    postId: 1
-    userId: 3
+    postId: __fk.posts:post-ts
+    userId: __fk.users:sara
     likes: 5
   - id: 2
     body: Could you cover generics in a follow-up post?
-    postId: 1
-    userId: 2
+    postId: __fk.posts:post-ts
+    userId: __fk.users:luis
     likes: 3
   - id: 3
     body: Fastify is indeed much faster than Express in my benchmarks.
-    postId: 2
-    userId: 3
+    postId: __fk.posts:post-fastify
+    userId: __fk.users:sara
     likes: 8
   - id: 4
     body: Do you have a GitHub repo with these examples?
-    postId: 2
-    userId: 1
+    postId: __fk.posts:post-fastify
+    userId: __fk.users:ana
     likes: 1
   - id: 5
     body: E2E tests are underrated. Solid post!
-    postId: 3
-    userId: 1
+    postId: __fk.posts:post-testing
+    userId: __fk.users:ana
     likes: 4
 
 # Try these queries:
@@ -519,7 +523,7 @@ import { join as join2, resolve as resolve3 } from "path";
 // src/storage/yrestStorage.ts
 import { readFileSync, writeFileSync as writeFileSync2, renameSync } from "fs";
 import { resolve as resolve2, dirname } from "path";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { parse, stringify } from "yaml";
 
 // src/storage/parseRelations.ts
@@ -791,6 +795,51 @@ function hasDataBlock(raw) {
   return d !== null && d !== void 0 && typeof d === "object" && !Array.isArray(d);
 }
 
+// src/storage/resolveDirectives.ts
+import { randomUUID } from "crypto";
+var UUID_GEN_RE = /^__uuid_gen(?::([a-zA-Z0-9_-]+))?$/;
+var FK_RE = /^__fk\.([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)$/;
+function resolveDirectives(data) {
+  const registry = /* @__PURE__ */ new Map();
+  let modified = false;
+  for (const [collection, items] of Object.entries(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = UUID_GEN_RE.exec(value);
+        if (!m) continue;
+        const uuid = randomUUID();
+        item[field] = uuid;
+        modified = true;
+        const alias = m[1];
+        if (alias) {
+          if (!registry.has(collection)) registry.set(collection, /* @__PURE__ */ new Map());
+          registry.get(collection).set(alias, uuid);
+        }
+      }
+    }
+  }
+  for (const items of Object.values(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = FK_RE.exec(value);
+        if (!m) continue;
+        const col = m[1];
+        const alias = m[2];
+        const uuid = registry.get(col)?.get(alias);
+        if (uuid !== void 0) {
+          item[field] = uuid;
+          modified = true;
+        } else {
+          console.warn(`yrest: cannot resolve __fk.${col}:${alias} \u2014 alias not registered`);
+        }
+      }
+    }
+  }
+  return modified;
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -862,12 +911,13 @@ function createYrestStorage(filePath) {
   const schema = parseSchema(raw["_schema"]);
   const dataBlock = hasDataBlock(raw);
   const data = parseData(raw);
+  const directivesModified = resolveDirectives(data);
   let snapshot = {
     data: deepCopyData(data),
     relations: { ...relations },
     savedAt: /* @__PURE__ */ new Date()
   };
-  return {
+  const storage = {
     getData() {
       return data;
     },
@@ -898,7 +948,7 @@ function createYrestStorage(filePath) {
       } else {
         Object.assign(payload, data);
       }
-      const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID()}.tmp`);
+      const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID2()}.tmp`);
       writeFileSync2(tmp, stringify(payload), "utf8");
       renameSync(tmp, absPath);
     },
@@ -910,6 +960,7 @@ function createYrestStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+      if (resolveDirectives(data)) storage.persist();
     },
     getSnapshot() {
       return snapshot;
@@ -930,6 +981,8 @@ function createYrestStorage(filePath) {
       this.persist();
     }
   };
+  if (directivesModified) storage.persist();
+  return storage;
 }
 
 // src/server/createServer.ts
@@ -942,7 +995,7 @@ import { dirname as dirname2, join } from "path";
 import { fileURLToPath } from "url";
 
 // src/utils/interpolate.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 function getPath(obj, path) {
   return path.split(".").reduce((acc, key) => {
     if (acc != null && typeof acc === "object") return acc[key];
@@ -951,7 +1004,7 @@ function getPath(obj, path) {
 }
 function resolveVar(path, ctx) {
   if (path === "now") return (/* @__PURE__ */ new Date()).toISOString();
-  if (path === "uuid") return randomUUID2();
+  if (path === "uuid") return randomUUID3();
   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)] ?? "";
@@ -3456,11 +3509,18 @@ function registerServe(program2) {
     "--id-strategy <strategy>",
     "Id generation strategy for new items: increment (default) or uuid",
     "increment"
+  ).option(
+    "--uuid",
+    "Shorthand for --id-strategy uuid: assign UUID ids to new items created via POST"
   ).action(async (file, flags, cmd) => {
     const fileConfig = loadConfigFile(join2(process.cwd(), "yrest.config.yml"));
     const cliOverrides = Object.fromEntries(
       Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
     );
+    if (cliOverrides["uuid"] === true) {
+      cliOverrides["idStrategy"] = "uuid";
+      delete cliOverrides["uuid"];
+    }
     const options = buildServeOptions(file, fileConfig, cliOverrides, cmd.args.length > 0);
     let storage;
     try {

package/dist/index.js

@@ -355,6 +355,58 @@ var init_parseData = __esm({
   }
 });
 
+// src/storage/resolveDirectives.ts
+function resolveDirectives(data) {
+  const registry = /* @__PURE__ */ new Map();
+  let modified = false;
+  for (const [collection, items] of Object.entries(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = UUID_GEN_RE.exec(value);
+        if (!m) continue;
+        const uuid = (0, import_node_crypto2.randomUUID)();
+        item[field] = uuid;
+        modified = true;
+        const alias = m[1];
+        if (alias) {
+          if (!registry.has(collection)) registry.set(collection, /* @__PURE__ */ new Map());
+          registry.get(collection).set(alias, uuid);
+        }
+      }
+    }
+  }
+  for (const items of Object.values(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = FK_RE.exec(value);
+        if (!m) continue;
+        const col = m[1];
+        const alias = m[2];
+        const uuid = registry.get(col)?.get(alias);
+        if (uuid !== void 0) {
+          item[field] = uuid;
+          modified = true;
+        } else {
+          console.warn(`yrest: cannot resolve __fk.${col}:${alias} \u2014 alias not registered`);
+        }
+      }
+    }
+  }
+  return modified;
+}
+var import_node_crypto2, UUID_GEN_RE, FK_RE;
+var init_resolveDirectives = __esm({
+  "src/storage/resolveDirectives.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto2 = require("crypto");
+    UUID_GEN_RE = /^__uuid_gen(?::([a-zA-Z0-9_-]+))?$/;
+    FK_RE = /^__fk\.([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)$/;
+  }
+});
+
 // src/storage/yrestStorage.ts
 var yrestStorage_exports = {};
 __export(yrestStorage_exports, {
@@ -423,12 +475,13 @@ function createYrestStorage(filePath) {
   const schema = parseSchema(raw["_schema"]);
   const dataBlock = hasDataBlock(raw);
   const data = parseData(raw);
+  const directivesModified = resolveDirectives(data);
   let snapshot = {
     data: deepCopyData(data),
     relations: { ...relations },
     savedAt: /* @__PURE__ */ new Date()
   };
-  return {
+  const storage = {
     getData() {
       return data;
     },
@@ -459,7 +512,7 @@ function createYrestStorage(filePath) {
       } else {
         Object.assign(payload, data);
       }
-      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto2.randomUUID)()}.tmp`);
+      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto3.randomUUID)()}.tmp`);
       (0, import_node_fs3.writeFileSync)(tmp, (0, import_yaml3.stringify)(payload), "utf8");
       (0, import_node_fs3.renameSync)(tmp, absPath);
     },
@@ -471,6 +524,7 @@ function createYrestStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+      if (resolveDirectives(data)) storage.persist();
     },
     getSnapshot() {
       return snapshot;
@@ -491,21 +545,24 @@ function createYrestStorage(filePath) {
       this.persist();
     }
   };
+  if (directivesModified) storage.persist();
+  return storage;
 }
-var import_node_fs3, import_node_path2, import_node_crypto2, import_yaml3;
+var import_node_fs3, import_node_path2, import_node_crypto3, import_yaml3;
 var init_yrestStorage = __esm({
   "src/storage/yrestStorage.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs3 = require("fs");
     import_node_path2 = require("path");
-    import_node_crypto2 = require("crypto");
+    import_node_crypto3 = require("crypto");
     import_yaml3 = require("yaml");
     init_parseRelations();
     init_parseRoutes();
     init_parseSseRoutes();
     init_parseSchema();
     init_parseData();
+    init_resolveDirectives();
     init_deepCopy();
   }
 });

package/dist/index.mjs

@@ -332,6 +332,58 @@ var init_parseData = __esm({
   }
 });
 
+// src/storage/resolveDirectives.ts
+import { randomUUID as randomUUID2 } from "crypto";
+function resolveDirectives(data) {
+  const registry = /* @__PURE__ */ new Map();
+  let modified = false;
+  for (const [collection, items] of Object.entries(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = UUID_GEN_RE.exec(value);
+        if (!m) continue;
+        const uuid = randomUUID2();
+        item[field] = uuid;
+        modified = true;
+        const alias = m[1];
+        if (alias) {
+          if (!registry.has(collection)) registry.set(collection, /* @__PURE__ */ new Map());
+          registry.get(collection).set(alias, uuid);
+        }
+      }
+    }
+  }
+  for (const items of Object.values(data)) {
+    for (const item of items) {
+      for (const [field, value] of Object.entries(item)) {
+        if (typeof value !== "string") continue;
+        const m = FK_RE.exec(value);
+        if (!m) continue;
+        const col = m[1];
+        const alias = m[2];
+        const uuid = registry.get(col)?.get(alias);
+        if (uuid !== void 0) {
+          item[field] = uuid;
+          modified = true;
+        } else {
+          console.warn(`yrest: cannot resolve __fk.${col}:${alias} \u2014 alias not registered`);
+        }
+      }
+    }
+  }
+  return modified;
+}
+var UUID_GEN_RE, FK_RE;
+var init_resolveDirectives = __esm({
+  "src/storage/resolveDirectives.ts"() {
+    "use strict";
+    init_esm_shims();
+    UUID_GEN_RE = /^__uuid_gen(?::([a-zA-Z0-9_-]+))?$/;
+    FK_RE = /^__fk\.([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)$/;
+  }
+});
+
 // src/storage/yrestStorage.ts
 var yrestStorage_exports = {};
 __export(yrestStorage_exports, {
@@ -339,7 +391,7 @@ __export(yrestStorage_exports, {
 });
 import { readFileSync as readFileSync2, writeFileSync, renameSync } from "fs";
 import { resolve, dirname as dirname2 } from "path";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { parse as parse2, stringify as stringify2 } from "yaml";
 function serializeRelations(relations) {
   const out = {};
@@ -404,12 +456,13 @@ function createYrestStorage(filePath) {
   const schema = parseSchema(raw["_schema"]);
   const dataBlock = hasDataBlock(raw);
   const data = parseData(raw);
+  const directivesModified = resolveDirectives(data);
   let snapshot = {
     data: deepCopyData(data),
     relations: { ...relations },
     savedAt: /* @__PURE__ */ new Date()
   };
-  return {
+  const storage = {
     getData() {
       return data;
     },
@@ -440,7 +493,7 @@ function createYrestStorage(filePath) {
       } else {
         Object.assign(payload, data);
       }
-      const tmp = resolve(dirname2(absPath), `.yrest-${randomUUID2()}.tmp`);
+      const tmp = resolve(dirname2(absPath), `.yrest-${randomUUID3()}.tmp`);
       writeFileSync(tmp, stringify2(payload), "utf8");
       renameSync(tmp, absPath);
     },
@@ -452,6 +505,7 @@ function createYrestStorage(filePath) {
       Object.assign(data, freshData);
       for (const key of Object.keys(relations)) delete relations[key];
       Object.assign(relations, freshRelations);
+      if (resolveDirectives(data)) storage.persist();
     },
     getSnapshot() {
       return snapshot;
@@ -472,6 +526,8 @@ function createYrestStorage(filePath) {
       this.persist();
     }
   };
+  if (directivesModified) storage.persist();
+  return storage;
 }
 var init_yrestStorage = __esm({
   "src/storage/yrestStorage.ts"() {
@@ -482,6 +538,7 @@ var init_yrestStorage = __esm({
     init_parseSseRoutes();
     init_parseSchema();
     init_parseData();
+    init_resolveDirectives();
     init_deepCopy();
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yrest/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a db.yml file.",
   "keywords": [
     "yrest",