@emeryld/rrroutes-contract 2.7.0 → 2.7.2

package/dist/index.mjs

@@ -42,9 +42,9 @@ function collectNestedFieldSuggestions(shape, prefix = []) {
   }
   return suggestions;
 }
-function compilePath(path, params) {
-  if (!params) return path;
-  const withParams = path.replace(/:([A-Za-z0-9_]+)/g, (_, k) => {
+function compilePath(path3, params) {
+  if (!params) return path3;
+  const withParams = path3.replace(/:([A-Za-z0-9_]+)/g, (_, k) => {
     const v = params[k];
     if (v === void 0 || v === null) throw new Error(`Missing param :${k}`);
     return String(v);
@@ -119,8 +119,8 @@ function buildLowProfileLeaf(leaf) {
     }
   };
 }
-var keyOf = (method, path, encodeSafe) => {
-  const key = `${method.toUpperCase()} ${path}`;
+var keyOf = (method, path3, encodeSafe) => {
+  const key = `${method.toUpperCase()} ${path3}`;
   return encodeSafe ? encodeURIComponent(key) : key;
 };
 
@@ -296,8 +296,8 @@ function joinPaths(parent, child) {
   if (!trimmedChild) return trimmedParent;
   return `${trimmedParent}/${trimmedChild}`;
 }
-function assertDynamicLayerUniqueness(path, dynamicLayerMap) {
-  const segments = path.split("/").filter(Boolean);
+function assertDynamicLayerUniqueness(path3, dynamicLayerMap) {
+  const segments = path3.split("/").filter(Boolean);
   if (segments.length === 0) return;
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i];
@@ -335,21 +335,590 @@ function finalize(leaves) {
 function defineSocketEvents(config, events) {
   return { config, events };
 }
+
+// src/export/schemaIntrospection.ts
+import * as z3 from "zod";
+var serializableSchemaKinds = [
+  "object",
+  "string",
+  "number",
+  "boolean",
+  "bigint",
+  "date",
+  "array",
+  "enum",
+  "literal",
+  "union",
+  "record",
+  "tuple",
+  "unknown",
+  "any"
+];
+var globalHandlers = {};
+function registerSchemaIntrospectionHandler(kind, handler) {
+  globalHandlers[kind] = handler;
+}
+function clearSchemaIntrospectionHandlers() {
+  for (const key of Object.keys(globalHandlers)) {
+    delete globalHandlers[key];
+  }
+}
+function getDef(schema) {
+  if (!schema || typeof schema !== "object") return void 0;
+  const anySchema = schema;
+  return anySchema._zod?.def ?? anySchema._def;
+}
+function getDescription(schema) {
+  const anyZ = z3;
+  const registry = anyZ.globalRegistry?.get ? anyZ.globalRegistry.get(schema) : void 0;
+  if (registry && typeof registry.description === "string") {
+    return registry.description;
+  }
+  const def = getDef(schema);
+  if (def && typeof def.description === "string") {
+    return def.description;
+  }
+  return void 0;
+}
+function unwrap(schema) {
+  let current = schema;
+  let optional = false;
+  let nullable = false;
+  const ZodEffectsCtor = z3.ZodEffects;
+  while (true) {
+    if (ZodEffectsCtor && current instanceof ZodEffectsCtor) {
+      const def = getDef(current) || {};
+      const sourceType = typeof current.sourceType === "function" ? current.sourceType() : def.schema;
+      if (!sourceType) break;
+      current = sourceType;
+      continue;
+    }
+    if (current instanceof z3.ZodOptional) {
+      optional = true;
+      const def = getDef(current);
+      current = def && def.innerType || current;
+      continue;
+    }
+    if (current instanceof z3.ZodNullable) {
+      nullable = true;
+      const def = getDef(current);
+      current = def && def.innerType || current;
+      continue;
+    }
+    if (current instanceof z3.ZodDefault) {
+      const def = getDef(current);
+      current = def && def.innerType || current;
+      continue;
+    }
+    break;
+  }
+  return { base: current, optional, nullable };
+}
+function mergeProps(a, b) {
+  if (!a && !b) return void 0;
+  return { ...a ?? {}, ...b ?? {} };
+}
+function inferKind(schema) {
+  if (schema instanceof z3.ZodString) return "string";
+  if (schema instanceof z3.ZodNumber) return "number";
+  if (schema instanceof z3.ZodBoolean) return "boolean";
+  if (schema instanceof z3.ZodBigInt) return "bigint";
+  if (schema instanceof z3.ZodDate) return "date";
+  if (schema instanceof z3.ZodArray) return "array";
+  if (schema instanceof z3.ZodObject) return "object";
+  if (schema instanceof z3.ZodUnion) return "union";
+  if (schema instanceof z3.ZodLiteral) return "literal";
+  if (schema instanceof z3.ZodEnum) return "enum";
+  if (schema instanceof z3.ZodRecord) return "record";
+  if (schema instanceof z3.ZodTuple) return "tuple";
+  if (schema instanceof z3.ZodUnknown) return "unknown";
+  if (schema instanceof z3.ZodAny) return "any";
+  return "unknown";
+}
+var defaultHandlers = {
+  intersection({ base, def, node }, ctx) {
+    const left = def?.left;
+    const right = def?.right;
+    const leftNode = left ? ctx.introspect(left) : void 0;
+    const rightNode = right ? ctx.introspect(right) : void 0;
+    const leftIsObj = leftNode?.kind === "object" && !!leftNode.properties;
+    const rightIsObj = rightNode?.kind === "object" && !!rightNode.properties;
+    if (leftIsObj && rightIsObj) {
+      node.kind = "object";
+      node.description = node.description ?? leftNode.description ?? rightNode.description;
+      node.properties = mergeProps(leftNode.properties, rightNode.properties);
+      return node;
+    }
+    if (leftNode && rightNode) {
+      node.properties = {
+        left: leftNode,
+        right: rightNode
+      };
+    }
+    return node;
+  },
+  object({ base, def, node }, ctx) {
+    const rawShape = base.shape ?? (def && typeof def.shape === "function" ? def.shape() : def?.shape);
+    const shape = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+    const props = {};
+    for (const key of Object.keys(shape)) {
+      const child = shape[key];
+      const childNode = ctx.introspect(child);
+      if (childNode) props[key] = childNode;
+    }
+    node.properties = props;
+    return node;
+  },
+  array({ def, node }, ctx) {
+    const inner = def && def.element || def && def.type || void 0;
+    if (inner) {
+      node.element = ctx.introspect(inner);
+    }
+    return node;
+  },
+  union({ def, node }, ctx) {
+    const options = def && def.options || [];
+    node.union = options.map((opt) => ctx.introspect(opt)).filter(Boolean);
+    return node;
+  },
+  literal({ def, node }) {
+    if (def) {
+      if (Array.isArray(def.values)) {
+        node.literal = def.values.length === 1 ? def.values[0] : def.values.slice();
+      } else {
+        node.literal = def.value;
+      }
+    }
+    return node;
+  },
+  enum({ def, node }) {
+    if (def) {
+      if (Array.isArray(def.values)) {
+        node.enumValues = def.values.slice();
+      } else if (def.entries && typeof def.entries === "object") {
+        node.enumValues = Object.values(def.entries).map((v) => String(v));
+      }
+    }
+    return node;
+  }
+};
+function createSchemaIntrospector(options = {}) {
+  const handlers = {
+    ...defaultHandlers,
+    ...globalHandlers,
+    ...options.handlers ?? {}
+  };
+  const introspect = (schema) => {
+    if (!schema) return void 0;
+    const unwrapped = unwrap(schema);
+    const base = unwrapped.base;
+    const def = getDef(base);
+    const kind = base instanceof z3.ZodIntersection ? "intersection" : inferKind(base);
+    const node = {
+      kind: kind === "intersection" ? "unknown" : kind,
+      optional: unwrapped.optional || void 0,
+      nullable: unwrapped.nullable || void 0,
+      description: getDescription(base)
+    };
+    const handler = handlers[kind];
+    if (!handler) return node;
+    return handler(
+      {
+        schema,
+        base,
+        def,
+        kind,
+        optional: unwrapped.optional,
+        nullable: unwrapped.nullable,
+        node
+      },
+      {
+        zod: z3,
+        introspect,
+        getDef,
+        unwrap,
+        getDescription
+      }
+    );
+  };
+  return introspect;
+}
+function introspectSchema(schema, options = {}) {
+  const introspect = createSchemaIntrospector(options);
+  return introspect(schema);
+}
+
+// src/export/serializeLeafContract.ts
+function serializeContractSchema(schema, options) {
+  return schema ? introspectSchema(routeSchemaParse(schema), options) : void 0;
+}
+function serializeBodyFiles(cfg) {
+  if (!Array.isArray(cfg.bodyFiles) || cfg.bodyFiles.length === 0) {
+    return void 0;
+  }
+  return cfg.bodyFiles.map(({ name, maxCount }) => ({ name, maxCount }));
+}
+function serializeLeafContract(leaf, options = {}) {
+  const cfg = leaf.cfg;
+  return {
+    key: `${leaf.method.toUpperCase()} ${leaf.path}`,
+    method: leaf.method,
+    path: leaf.path,
+    cfg: {
+      description: cfg.description,
+      summary: cfg.summary,
+      docsGroup: cfg.docsGroup,
+      tags: Array.isArray(cfg.tags) ? cfg.tags.slice() : void 0,
+      deprecated: cfg.deprecated,
+      stability: cfg.stability,
+      docsHidden: cfg.docsHidden,
+      docsMeta: cfg.docsMeta,
+      feed: cfg.feed,
+      bodyFiles: serializeBodyFiles(cfg),
+      schemas: {
+        body: serializeContractSchema(cfg.bodySchema, options),
+        query: serializeContractSchema(cfg.querySchema, options),
+        params: serializeContractSchema(cfg.paramsSchema, options),
+        output: serializeContractSchema(cfg.outputSchema, options),
+        outputMeta: serializeContractSchema(cfg.outputMetaSchema, options),
+        queryExtension: serializeContractSchema(cfg.queryExtensionSchema, options)
+      }
+    }
+  };
+}
+function serializeLeavesContract(leaves, options = {}) {
+  return leaves.map((leaf) => serializeLeafContract(leaf, options));
+}
+
+// src/export/flattenSchema.ts
+function normalizeType(schema) {
+  switch (schema.kind) {
+    case "string":
+    case "number":
+    case "date":
+    case "boolean":
+    case "object":
+    case "array":
+      return schema.kind;
+    case "enum": {
+      if (Array.isArray(schema.enumValues) && schema.enumValues.length > 0) {
+        return schema.enumValues.join("|");
+      }
+      return "unknown";
+    }
+    case "literal": {
+      const lit = schema.literal;
+      if (typeof lit === "string") return "string";
+      if (typeof lit === "number") return "number";
+      if (typeof lit === "boolean") return "boolean";
+      return "unknown";
+    }
+    default:
+      return "unknown";
+  }
+}
+function isNonEmptyPath(path3) {
+  return typeof path3 === "string" && path3.length > 0;
+}
+function setNode(out, path3, schema, inherited) {
+  if (!isNonEmptyPath(path3)) return;
+  out[path3] = {
+    type: normalizeType(schema),
+    nullable: inherited.nullable || Boolean(schema.nullable),
+    optional: inherited.optional || Boolean(schema.optional)
+  };
+}
+function flattenInto(out, schema, path3, inherited) {
+  if (!schema || !isNonEmptyPath(path3)) return;
+  const nextInherited = {
+    optional: inherited.optional || Boolean(schema.optional),
+    nullable: inherited.nullable || Boolean(schema.nullable)
+  };
+  if (schema.kind === "union" && Array.isArray(schema.union) && schema.union.length > 0) {
+    schema.union.forEach((option, index) => {
+      const optionPath = `${path3}-${index + 1}`;
+      flattenInto(out, option, optionPath, inherited);
+    });
+    return;
+  }
+  setNode(out, path3, schema, inherited);
+  if (schema.kind === "object" && schema.properties) {
+    for (const [key, child] of Object.entries(schema.properties)) {
+      const childPath = `${path3}.${key}`;
+      flattenInto(out, child, childPath, nextInherited);
+    }
+    return;
+  }
+  if (schema.kind === "array" && schema.element) {
+    flattenInto(out, schema.element, `${path3}[]`, nextInherited);
+  }
+}
+function flattenSerializableSchema(schema, path3) {
+  const out = {};
+  flattenInto(out, schema, path3, { optional: false, nullable: false });
+  return out;
+}
+function isSerializedLeaf(value) {
+  if (!value || typeof value !== "object") return false;
+  const item = value;
+  return typeof item.key === "string" && !!item.cfg && typeof item.cfg === "object";
+}
+function flattenLeafSchemas(leaf) {
+  const serialized = isSerializedLeaf(leaf) ? leaf : serializeLeafContract(leaf);
+  const out = {};
+  const sections = serialized.cfg.schemas;
+  Object.assign(out, flattenSerializableSchema(sections.params, "params"));
+  Object.assign(out, flattenSerializableSchema(sections.query, "query"));
+  Object.assign(out, flattenSerializableSchema(sections.body, "body"));
+  Object.assign(out, flattenSerializableSchema(sections.output, "output"));
+  return out;
+}
+
+// src/export/exportFinalizedLeaves.ts
+import fs from "fs/promises";
+import path from "path";
+import { spawn } from "child_process";
+function isRegistry(value) {
+  return typeof value === "object" && value !== null && "all" in value && "byKey" in value;
+}
+function getLeaves(input) {
+  return isRegistry(input) ? input.all : input;
+}
+function buildMeta() {
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    description: "Finalized RRRoutes leaves export with serialized schemas and flattened schema paths for downstream processing.",
+    fieldCatalog: {
+      leaf: ["key", "method", "path", "cfg"],
+      cfg: [
+        "description?",
+        "summary?",
+        "docsGroup?",
+        "tags?",
+        "deprecated?",
+        "stability?",
+        "docsHidden?",
+        "docsMeta?",
+        "feed?",
+        "bodyFiles?",
+        "schemas"
+      ],
+      schemaNode: [
+        "kind",
+        "optional?",
+        "nullable?",
+        "description?",
+        "properties?",
+        "element?",
+        "union?",
+        "literal?",
+        "enumValues?"
+      ],
+      flatSchemaEntry: ["type", "nullable", "optional"]
+    },
+    flattening: {
+      notation: "dot+[]",
+      unionBranchSuffix: "-N",
+      sections: ["params", "query", "body", "output"]
+    }
+  };
+}
+var BAKED_PAYLOAD_MARKER = "<!--__FINALIZED_LEAVES_BAKED_PAYLOAD__-->";
+function escapePayloadForInlineScript(payload) {
+  return JSON.stringify(payload).replace(/<\//g, "<\\/").replace(/<!--/g, "<\\!--");
+}
+function injectPayloadIntoViewerHtml(htmlTemplate, payload) {
+  const payloadScript = `${BAKED_PAYLOAD_MARKER}
+<script id="finalized-leaves-baked-payload">window.__FINALIZED_LEAVES_PAYLOAD = ${escapePayloadForInlineScript(
+    payload
+  )};</script>`;
+  if (htmlTemplate.includes(BAKED_PAYLOAD_MARKER)) {
+    return htmlTemplate.replace(BAKED_PAYLOAD_MARKER, payloadScript);
+  }
+  if (htmlTemplate.includes("</body>")) {
+    return htmlTemplate.replace("</body>", `${payloadScript}
+</body>`);
+  }
+  return `${payloadScript}
+${htmlTemplate}`;
+}
+async function resolveViewerTemplatePath(viewerTemplateFile) {
+  if (viewerTemplateFile) {
+    return path.resolve(viewerTemplateFile);
+  }
+  const candidates = [
+    path.resolve(process.cwd(), "tools/finalized-leaves-viewer.html"),
+    path.resolve(
+      process.cwd(),
+      "packages/contract/tools/finalized-leaves-viewer.html"
+    )
+  ];
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new Error(
+    `Could not locate finalized-leaves viewer template. Checked: ${candidates.join(
+      ", "
+    )}`
+  );
+}
+async function writeJsonExport(payload, outFile) {
+  const resolved = path.resolve(outFile);
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  await fs.writeFile(resolved, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  return resolved;
+}
+async function writeBakedHtmlExport(payload, htmlFile, viewerTemplateFile) {
+  const templatePath = await resolveViewerTemplatePath(viewerTemplateFile);
+  const template = await fs.readFile(templatePath, "utf8");
+  const baked = injectPayloadIntoViewerHtml(template, payload);
+  const resolved = path.resolve(htmlFile);
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  await fs.writeFile(resolved, baked, "utf8");
+  return resolved;
+}
+async function openHtmlInBrowser(filePath) {
+  const resolved = path.resolve(filePath);
+  const platform = process.platform;
+  if (platform === "darwin") {
+    spawn("open", [resolved], { detached: true, stdio: "ignore" }).unref();
+    return;
+  }
+  if (platform === "win32") {
+    spawn("cmd", ["/c", "start", "", resolved], {
+      detached: true,
+      stdio: "ignore"
+    }).unref();
+    return;
+  }
+  spawn("xdg-open", [resolved], { detached: true, stdio: "ignore" }).unref();
+}
+async function writeFinalizedLeavesExport(payload, outFileOrOptions) {
+  const options = typeof outFileOrOptions === "string" ? { outFile: outFileOrOptions } : outFileOrOptions;
+  const written = {};
+  if (options.outFile) {
+    written.outFile = await writeJsonExport(payload, options.outFile);
+  }
+  if (options.htmlFile) {
+    written.htmlFile = await writeBakedHtmlExport(
+      payload,
+      options.htmlFile,
+      options.viewerTemplateFile
+    );
+  }
+  if (options.openOnFinish) {
+    if (!written.htmlFile) {
+      throw new Error(
+        "openOnFinish requires htmlFile. Provide htmlFile to open the baked viewer."
+      );
+    }
+    await openHtmlInBrowser(written.htmlFile);
+  }
+  return written;
+}
+async function exportFinalizedLeaves(input, options = {}) {
+  const leaves = getLeaves(input);
+  const serializedLeaves = serializeLeavesContract(leaves, options);
+  const schemaFlatByLeaf = Object.fromEntries(
+    serializedLeaves.map((leaf) => [leaf.key, flattenLeafSchemas(leaf)])
+  );
+  const payload = {
+    _meta: buildMeta(),
+    leaves: serializedLeaves,
+    schemaFlatByLeaf
+  };
+  if (options.outFile || options.htmlFile) {
+    await writeFinalizedLeavesExport(payload, {
+      outFile: options.outFile,
+      htmlFile: options.htmlFile,
+      viewerTemplateFile: options.viewerTemplateFile,
+      openOnFinish: options.openOnFinish
+    });
+  }
+  return payload;
+}
+
+// src/export/exportFinalizedLeaves.cli.ts
+import path2 from "path";
+import { pathToFileURL } from "url";
+function parseFinalizedLeavesCliArgs(argv) {
+  const args = /* @__PURE__ */ new Map();
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    if (key === "--") continue;
+    if (!key.startsWith("--")) continue;
+    const value = argv[i + 1];
+    if (!value || value.startsWith("--")) {
+      throw new Error(`Missing value for ${key}`);
+    }
+    args.set(key, value);
+    i += 1;
+  }
+  const modulePath = args.get("--module");
+  if (!modulePath) {
+    throw new Error("Missing required --module argument");
+  }
+  return {
+    modulePath,
+    exportName: args.get("--export") ?? "leaves",
+    outFile: args.get("--out") ?? "finalized-leaves.export.json"
+  };
+}
+async function loadFinalizedLeavesInput({
+  modulePath,
+  exportName
+}) {
+  const resolvedModule = path2.resolve(process.cwd(), modulePath);
+  const mod = await import(pathToFileURL(resolvedModule).href);
+  const value = mod[exportName] ?? (mod.default && mod.default[exportName]);
+  if (!value) {
+    throw new Error(`Export "${exportName}" not found in module: ${resolvedModule}`);
+  }
+  return value;
+}
+async function runExportFinalizedLeavesCli(argv) {
+  const args = parseFinalizedLeavesCliArgs(argv);
+  const input = await loadFinalizedLeavesInput(args);
+  const payload = await exportFinalizedLeaves(input, { outFile: args.outFile });
+  return {
+    payload,
+    outFile: path2.resolve(args.outFile)
+  };
+}
 export {
   buildCacheKey,
   buildLowProfileLeaf,
+  clearSchemaIntrospectionHandlers,
   collectNestedFieldSuggestions,
   compilePath,
+  createSchemaIntrospector,
   defineSocketEvents,
+  exportFinalizedLeaves,
   finalize,
+  flattenLeafSchemas,
+  flattenSerializableSchema,
   getZodShape,
+  introspectSchema,
   keyOf,
+  loadFinalizedLeavesInput,
   lowProfileParse,
   lowProfileSafeParse,
   mergeArrays,
   mergeSchemas,
+  parseFinalizedLeavesCliArgs,
+  registerSchemaIntrospectionHandler,
   resource,
   routeSchemaParse,
-  staticBase
+  runExportFinalizedLeavesCli,
+  serializableSchemaKinds,
+  serializeLeafContract,
+  serializeLeavesContract,
+  staticBase,
+  writeFinalizedLeavesExport
 };
 //# sourceMappingURL=index.mjs.map