@emeryld/rrroutes-contract 2.7.0 → 2.7.1

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "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)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   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
@@ -22,19 +32,33 @@ var index_exports = {};
 __export(index_exports, {
   buildCacheKey: () => buildCacheKey,
   buildLowProfileLeaf: () => buildLowProfileLeaf,
+  clearSchemaIntrospectionHandlers: () => clearSchemaIntrospectionHandlers,
   collectNestedFieldSuggestions: () => collectNestedFieldSuggestions,
   compilePath: () => compilePath,
+  createSchemaIntrospector: () => createSchemaIntrospector,
   defineSocketEvents: () => defineSocketEvents,
+  exportFinalizedLeaves: () => exportFinalizedLeaves,
   finalize: () => finalize,
+  flattenLeafSchemas: () => flattenLeafSchemas,
+  flattenSerializableSchema: () => flattenSerializableSchema,
   getZodShape: () => getZodShape,
+  introspectSchema: () => introspectSchema,
   keyOf: () => keyOf,
+  loadFinalizedLeavesInput: () => loadFinalizedLeavesInput,
   lowProfileParse: () => lowProfileParse,
   lowProfileSafeParse: () => lowProfileSafeParse,
   mergeArrays: () => mergeArrays,
   mergeSchemas: () => mergeSchemas,
+  parseFinalizedLeavesCliArgs: () => parseFinalizedLeavesCliArgs,
+  registerSchemaIntrospectionHandler: () => registerSchemaIntrospectionHandler,
   resource: () => resource,
   routeSchemaParse: () => routeSchemaParse,
-  staticBase: () => staticBase
+  runExportFinalizedLeavesCli: () => runExportFinalizedLeavesCli,
+  serializableSchemaKinds: () => serializableSchemaKinds,
+  serializeLeafContract: () => serializeLeafContract,
+  serializeLeavesContract: () => serializeLeavesContract,
+  staticBase: () => staticBase,
+  writeFinalizedLeavesExport: () => writeFinalizedLeavesExport
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -82,9 +106,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);
@@ -159,8 +183,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;
 };
 
@@ -336,8 +360,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];
@@ -375,22 +399,494 @@ function finalize(leaves) {
 function defineSocketEvents(config, events) {
   return { config, events };
 }
+
+// src/export/schemaIntrospection.ts
+var z3 = __toESM(require("zod"), 1);
+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
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path = __toESM(require("path"), 1);
+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"]
+    }
+  };
+}
+async function writeFinalizedLeavesExport(payload, outFile) {
+  const resolved = import_node_path.default.resolve(outFile);
+  await import_promises.default.mkdir(import_node_path.default.dirname(resolved), { recursive: true });
+  await import_promises.default.writeFile(resolved, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  return resolved;
+}
+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) {
+    await writeFinalizedLeavesExport(payload, options.outFile);
+  }
+  return payload;
+}
+
+// src/export/exportFinalizedLeaves.cli.ts
+var import_node_path2 = __toESM(require("path"), 1);
+var import_node_url = require("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 = import_node_path2.default.resolve(process.cwd(), modulePath);
+  const mod = await import((0, import_node_url.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: import_node_path2.default.resolve(args.outFile)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   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.cjs.map