@yrest/cli 0.9.0 → 0.10.0

package/dist/index.mjs

@@ -67,6 +67,42 @@ var init_parseRelations = __esm({
   }
 });
 
+// src/storage/parseSchema.ts
+function parseSchema(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result = {};
+  for (const [collection, fields] of Object.entries(raw)) {
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) continue;
+    result[collection] = {};
+    for (const [field, value] of Object.entries(fields)) {
+      const def = normaliseFieldDef(value);
+      if (def) result[collection][field] = def;
+    }
+  }
+  return result;
+}
+function normaliseFieldDef(value) {
+  if (value === "required") return { required: true };
+  if (value === "optional") return { required: false };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value;
+  const def = {};
+  if (v["required"] === true || v["required"] === false) def.required = v["required"];
+  if (typeof v["type"] === "string" && ["string", "integer", "number", "boolean", "object", "array"].includes(v["type"]))
+    def.type = v["type"];
+  if (typeof v["format"] === "string") def.format = v["format"];
+  if (Array.isArray(v["enum"])) def.enum = v["enum"];
+  if (typeof v["description"] === "string") def.description = v["description"];
+  if (v["default"] !== void 0) def.default = v["default"];
+  return def;
+}
+var init_parseSchema = __esm({
+  "src/storage/parseSchema.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -88,14 +124,16 @@ __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 { parse as parse2, stringify } from "yaml";
+import { parse as parse2, stringify as stringify2 } from "yaml";
 function createYrestStorage(filePath) {
   const absPath = resolve(filePath);
   const raw = parse2(readFileSync2(absPath, "utf8")) ?? {};
+  const RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const schema = parseSchema(raw["_schema"]);
   const data = Object.fromEntries(
-    Object.entries(raw).filter(([key]) => key !== "_rel" && key !== "_routes")
+    Object.entries(raw).filter(([key]) => !RESERVED.has(key))
   );
   let snapshot = {
     data: deepCopyData(data),
@@ -109,6 +147,9 @@ function createYrestStorage(filePath) {
     getRelations() {
       return relations;
     },
+    getSchema() {
+      return schema;
+    },
     getRoutes() {
       return routes;
     },
@@ -124,14 +165,14 @@ function createYrestStorage(filePath) {
       if (routes.length > 0) payload._routes = routes;
       Object.assign(payload, data);
       const tmp = resolve(dirname2(absPath), `.yrest-${randomUUID2()}.tmp`);
-      writeFileSync(tmp, stringify(payload), "utf8");
+      writeFileSync(tmp, stringify2(payload), "utf8");
       renameSync(tmp, absPath);
     },
     reload() {
       const fresh = parse2(readFileSync2(absPath, "utf8")) ?? {};
       const freshRelations = parseRelations(fresh["_rel"]);
       const freshData = Object.fromEntries(
-        Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
+        Object.entries(fresh).filter(([key]) => !RESERVED.has(key))
       );
       for (const key of Object.keys(data)) delete data[key];
       Object.assign(data, freshData);
@@ -163,6 +204,7 @@ var init_yrestStorage = __esm({
     "use strict";
     init_esm_shims();
     init_parseRelations();
+    init_parseSchema();
     init_deepCopy();
   }
 });
@@ -215,6 +257,7 @@ function dedent(str) {
 // src/api/yrestServer.ts
 init_esm_shims();
 init_parseRelations();
+init_parseSchema();
 import { resolve as resolve2 } from "path";
 
 // src/utils/handlers.ts
@@ -348,7 +391,7 @@ function endpointRow(method, path2, desc) {
 }
 function resourceAccordion(name, base, isOpen) {
   const p = `${base}/${name}`;
-  const singular = name.endsWith("s") ? name.slice(0, -1) : name;
+  const singular2 = name.endsWith("s") ? name.slice(0, -1) : name;
   const rows = [
     endpointRow(
       "GET",
@@ -358,20 +401,20 @@ function resourceAccordion(name, base, isOpen) {
     endpointRow(
       "POST",
       p,
-      `Create a new ${singular}. Auto-assigns <code>id</code> if not provided.`
+      `Create a new ${singular2}. Auto-assigns <code>id</code> if not provided.`
     ),
-    endpointRow("GET", `${p}/:id`, `Get a single ${singular} by id.`),
+    endpointRow("GET", `${p}/:id`, `Get a single ${singular2} by id.`),
     endpointRow(
       "PUT",
       `${p}/:id`,
-      `Fully replace a ${singular}. Original <code>id</code> is always preserved.`
+      `Fully replace a ${singular2}. Original <code>id</code> is always preserved.`
     ),
     endpointRow(
       "PATCH",
       `${p}/:id`,
-      `Partially update a ${singular} \u2014 only provided fields change.`
+      `Partially update a ${singular2} \u2014 only provided fields change.`
     ),
-    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular} and return it as confirmation.`)
+    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular2} and return it as confirmation.`)
   ].join("");
   return `
   <details class="resource-card" ${isOpen ? "open" : ""}>
@@ -390,13 +433,13 @@ function nestedRoutesAccordion(relations, base) {
     for (const [key, def] of Object.entries(fields)) {
       const nestedBadge = def.nested ? ` ${badge("nested", "#facc15", "#facc1518")}` : "";
       if (def.type === "many2many") {
-        const singular = source.endsWith("s") ? source.slice(0, -1) : source;
+        const singular2 = source.endsWith("s") ? source.slice(0, -1) : source;
         const m2mBadge = badge("many2many", "#818cf8", "#818cf818");
         rows.push(
           endpointRow(
             "GET",
             `${base}/${source}/:id/${key}`,
-            `List ${def.target} linked to a ${singular} via ${def.through}. ${m2mBadge}${nestedBadge}`
+            `List ${def.target} linked to a ${singular2} via ${def.through}. ${m2mBadge}${nestedBadge}`
           )
         );
         const targetSingular = def.target.endsWith("s") ? def.target.slice(0, -1) : def.target;
@@ -522,7 +565,7 @@ function examplesBlock(collections, relations, base, host, options, firstCustomR
   const firstCol = collections[0];
   if (firstCol) {
     const p = `${host}${base}/${firstCol}`;
-    const singular = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
+    const singular2 = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
     examples.push(
       `# List all ${firstCol}
 curl ${p}`,
@@ -530,17 +573,17 @@ curl ${p}`,
 curl "${p}?name=value"`,
       `# Sort and paginate
 curl "${p}?_sort=id&_order=desc&_page=1&_limit=5"`,
-      `# Get single ${singular}
+      `# Get single ${singular2}
 curl ${p}/1`,
-      `# Create ${singular}
+      `# Create ${singular2}
 curl -X POST ${p} \\
   -H "Content-Type: application/json" \\
   -d '{"name":"example"}'`,
-      `# Partially update ${singular}
+      `# Partially update ${singular2}
 curl -X PATCH ${p}/1 \\
   -H "Content-Type: application/json" \\
   -d '{"name":"updated"}'`,
-      `# Delete ${singular}
+      `# Delete ${singular2}
 curl -X DELETE ${p}/1`
     );
   }
@@ -1477,6 +1520,379 @@ var NestedRouteCommand = class {
   }
 };
 
+// src/router/routes/openapi.routes.ts
+init_esm_shims();
+
+// src/openapi/generateOpenApi.ts
+init_esm_shims();
+
+// src/openapi/inferSchema.ts
+init_esm_shims();
+function buildCollectionSchema(items, fieldDefs = {}) {
+  const sample = items.slice(0, 10);
+  const inferredTypes = /* @__PURE__ */ new Map();
+  for (const item of sample) {
+    for (const [key, value] of Object.entries(item)) {
+      if (!inferredTypes.has(key)) {
+        inferredTypes.set(key, jsToOpenApiType(value));
+      }
+    }
+  }
+  const allFields = /* @__PURE__ */ new Set([...inferredTypes.keys(), ...Object.keys(fieldDefs)]);
+  const properties = {};
+  const required = [];
+  for (const field of allFields) {
+    const def = fieldDefs[field];
+    const inferred = inferredTypes.get(field) ?? "string";
+    const prop = {
+      type: def?.type ?? inferred
+    };
+    if (def?.format) prop.format = def.format;
+    if (def?.description) prop.description = def.description;
+    if (def?.enum) prop.enum = def.enum;
+    if (def?.default !== void 0) prop.default = def.default;
+    properties[field] = prop;
+    if (def?.required === true) required.push(field);
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+function jsToOpenApiType(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/buildPaths.ts
+init_esm_shims();
+var COLLECTION_QUERY_PARAMS = [
+  { name: "_page", in: "query", schema: { type: "integer" }, description: "Page number (1-based)" },
+  { name: "_limit", in: "query", schema: { type: "integer" }, description: "Items per page" },
+  { name: "_sort", in: "query", schema: { type: "string" }, description: "Field name to sort by" },
+  {
+    name: "_order",
+    in: "query",
+    schema: { type: "string", enum: ["asc", "desc"] },
+    description: "Sort direction"
+  },
+  {
+    name: "_q",
+    in: "query",
+    schema: { type: "string" },
+    description: "Full-text search across all scalar fields (case-insensitive)"
+  },
+  {
+    name: "_expand",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed related parent object inline (e.g. ?_expand=user)"
+  },
+  {
+    name: "_embed",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed child collection into each item (e.g. ?_embed=posts)"
+  },
+  {
+    name: "_fields",
+    in: "query",
+    schema: { type: "string" },
+    description: "Comma-separated field projection (e.g. ?_fields=id,name)"
+  }
+];
+var ID_PATH_PARAM = {
+  name: "id",
+  in: "path",
+  required: true,
+  schema: { type: "string" },
+  description: "Item id"
+};
+function toOpenApiPath(fastifyPath) {
+  return fastifyPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+}
+function extractPathParams(fastifyPath) {
+  const matches = fastifyPath.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g) ?? [];
+  return matches.map((m) => ({
+    name: m.slice(1),
+    in: "path",
+    required: true,
+    schema: { type: "string" }
+  }));
+}
+function singular(name) {
+  return name.endsWith("s") ? name.slice(0, -1) : name;
+}
+function schemaRef(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+function jsonContent(schema) {
+  return { "application/json": { schema } };
+}
+function ok(schema, description = "OK") {
+  return { description, content: jsonContent(schema) };
+}
+function buildCrudPaths(collection, base, schemaName) {
+  const ref = schemaRef(schemaName);
+  const tag = collection;
+  const sing = singular(collection);
+  const collPath = `${base}/${collection}`;
+  const itemPath = `${base}/${collection}/{id}`;
+  return {
+    [collPath]: {
+      get: {
+        summary: `List ${collection}`,
+        tags: [tag],
+        parameters: COLLECTION_QUERY_PARAMS,
+        responses: {
+          "200": {
+            description: "OK",
+            content: jsonContent({ type: "array", items: ref }),
+            headers: {
+              "X-Total-Count": {
+                description: "Total items (when using ?_page / ?_limit)",
+                schema: { type: "integer" }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        summary: `Create ${sing}`,
+        tags: [tag],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "201": ok(ref, "Created") }
+      }
+    },
+    [itemPath]: {
+      get: {
+        summary: `Get ${sing}`,
+        tags: [tag],
+        parameters: [
+          ID_PATH_PARAM,
+          ...COLLECTION_QUERY_PARAMS.filter(
+            (p) => ["_expand", "_embed", "_fields"].includes(p.name)
+          )
+        ],
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      put: {
+        summary: `Replace ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      patch: {
+        summary: `Update ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: false, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      delete: {
+        summary: `Delete ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        responses: { "200": ok(ref, "Deleted item returned"), "404": { description: "Not found" } }
+      }
+    }
+  };
+}
+function buildRelationPaths(relations, base) {
+  const paths = {};
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type === "many2many") {
+        const forwardPath = `${base}/${source}/{id}/${key}`;
+        const inversePath = `${base}/${def.target}/{id}/${source}`;
+        paths[forwardPath] = {
+          get: {
+            summary: `List ${def.target} linked to ${singular(source)} via ${def.through}`,
+            tags: [source],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(source)} not found` }
+            }
+          }
+        };
+        paths[inversePath] = {
+          get: {
+            summary: `List ${source} linked to ${singular(def.target)} via ${def.through} (inverse)`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(def.target)} not found` }
+            }
+          }
+        };
+      } else {
+        const parentSing = singular(def.target);
+        const collPath = `${base}/${def.target}/{id}/${source}`;
+        const isOne2One = def.type === "one2one";
+        const responseSchema = isOne2One ? { type: "object" } : { type: "array", items: { type: "object" } };
+        paths[collPath] = {
+          get: {
+            summary: isOne2One ? `Get ${singular(source)} belonging to ${parentSing}` : `List ${source} belonging to ${parentSing}`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": { description: "OK", content: jsonContent(responseSchema) },
+              "404": { description: `${parentSing} not found` }
+            }
+          }
+        };
+        if (!isOne2One) {
+          const itemPath = `${base}/${def.target}/{id}/${source}/{childId}`;
+          paths[itemPath] = {
+            get: {
+              summary: `Get single ${singular(source)} scoped to ${parentSing}`,
+              tags: [def.target],
+              parameters: [
+                ID_PATH_PARAM,
+                { name: "childId", in: "path", required: true, schema: { type: "string" } }
+              ],
+              responses: {
+                "200": { description: "OK", content: jsonContent({ type: "object" }) },
+                "404": { description: "Not found" }
+              }
+            }
+          };
+        }
+      }
+    }
+  }
+  return paths;
+}
+function buildCustomRoutePaths(routes, base) {
+  const paths = {};
+  for (const route of routes) {
+    const openApiPath = toOpenApiPath(`${base}${route.path}`);
+    const method = route.method.toLowerCase();
+    const pathParams = extractPathParams(route.path);
+    const responses = {};
+    if (route.error) {
+      responses[String(route.error)] = { description: `Forced error ${route.error}` };
+    } else {
+      const statuses = /* @__PURE__ */ new Set();
+      for (const s of route.scenarios ?? []) statuses.add(s.response.status ?? 200);
+      if (route.otherwise) statuses.add(route.otherwise.status ?? 200);
+      if (route.response) statuses.add(route.response.status ?? 200);
+      if (statuses.size === 0) statuses.add(200);
+      for (const status of statuses) {
+        const bodySource = (route.scenarios ?? []).find((s) => (s.response.status ?? 200) === status)?.response.body ?? (route.otherwise?.status ?? 200) === status ? route.otherwise?.body : route.response?.body;
+        responses[String(status)] = {
+          description: status < 400 ? "OK" : "Error",
+          ...bodySource != null ? { content: jsonContent(inferResponseSchema(bodySource)) } : {}
+        };
+      }
+    }
+    const desc = route.handler ? `Handler: ${route.handler}()` : route.scenarios?.length ? `Conditional scenarios (${route.scenarios.length})` : "Custom static route";
+    const operation = {
+      summary: `${route.method.toUpperCase()} ${route.path}`,
+      description: desc,
+      tags: ["custom"],
+      ...pathParams.length > 0 ? { parameters: pathParams } : {},
+      responses
+    };
+    if (!paths[openApiPath]) paths[openApiPath] = {};
+    paths[openApiPath][method] = operation;
+  }
+  return paths;
+}
+function inferResponseSchema(body) {
+  if (body === null || body === void 0) return {};
+  if (typeof body !== "object" || Array.isArray(body)) return { type: "object" };
+  const properties = {};
+  for (const [key, value] of Object.entries(body)) {
+    properties[key] = { type: jsToOpenApiType2(value) };
+  }
+  return { type: "object", properties };
+}
+function jsToOpenApiType2(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/generateOpenApi.ts
+function generateOpenApi(storage, options, title = "yRest API") {
+  const collections = Object.keys(storage.getData());
+  const relations = storage.getRelations();
+  const schemaBlock = storage.getSchema();
+  const customRoutes = storage.getRoutes();
+  const base = options.base ?? "";
+  const schemas = {};
+  for (const collection of collections) {
+    const items = storage.getCollection(collection) ?? [];
+    const fieldDefs = schemaBlock[collection] ?? {};
+    const schemaName = toSchemaName(collection);
+    schemas[schemaName] = buildCollectionSchema(items, fieldDefs);
+  }
+  const paths = {};
+  for (const collection of collections) {
+    const schemaName = toSchemaName(collection);
+    Object.assign(paths, buildCrudPaths(collection, base, schemaName));
+  }
+  Object.assign(paths, buildRelationPaths(relations, base));
+  Object.assign(paths, buildCustomRoutePaths(customRoutes, base));
+  return {
+    openapi: "3.0.3",
+    info: {
+      title,
+      version: "1.0.0",
+      description: "Generated by yRest from db.yml"
+    },
+    servers: [
+      {
+        url: `http://${options.host}:${options.port}${base}`,
+        description: "yRest mock server"
+      }
+    ],
+    paths,
+    components: { schemas }
+  };
+}
+function toSchemaName(collection) {
+  const withoutS = collection.endsWith("s") ? collection.slice(0, -1) : collection;
+  return withoutS.charAt(0).toUpperCase() + withoutS.slice(1);
+}
+
+// src/router/routes/openapi.routes.ts
+import { stringify } from "yaml";
+var OpenApiRouteCommand = class {
+  constructor(storage, options) {
+    this.storage = storage;
+    this.options = options;
+  }
+  storage;
+  options;
+  register(server) {
+    server.get("/_openapi", (_req, reply) => {
+      const doc = generateOpenApi(this.storage, this.options);
+      reply.header("Content-Type", "text/yaml; charset=utf-8");
+      return reply.send(stringify(doc, { lineWidth: 0, aliasDuplicateObjects: false }));
+    });
+    server.get("/_openapi.json", (_req, reply) => {
+      return reply.send(generateOpenApi(this.storage, this.options));
+    });
+  }
+};
+
 // src/router/routes/snapshot.routes.ts
 init_esm_shims();
 var SnapshotRouteCommand = class {
@@ -1558,6 +1974,7 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   }
   const commands = [
     new AboutRouteCommand(storage, options, handlers),
+    new OpenApiRouteCommand(storage, options),
     ...options.snapshot ? [new SnapshotRouteCommand(storage)] : [],
     new CustomRouteCommand(storage, options.base, handlers),
     ...buildResourceRouteCommands(storage, options)
@@ -1637,10 +2054,12 @@ function buildOptions(opts) {
 }
 function createInMemoryStorage(data) {
   const raw = data;
+  const RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const schema = parseSchema(raw["_schema"]);
   const collections = Object.fromEntries(
-    Object.entries(raw).filter(([k]) => k !== "_rel" && k !== "_routes")
+    Object.entries(raw).filter(([k]) => !RESERVED.has(k))
   );
   let snapshot = {
     data: deepCopyData(collections),
@@ -1650,6 +2069,7 @@ function createInMemoryStorage(data) {
   return {
     getData: () => collections,
     getRelations: () => relations,
+    getSchema: () => schema,
     getRoutes: () => routes,
     getCollection: (name) => collections[name],
     setCollection: (name, items) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yrest/cli",
-  "version": "0.9.0",
+  "version": "0.10.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",