npm - @emeryld/rrroutes-contract - Versions diffs - 2.7.1 → 2.7.2 - Mend

@emeryld/rrroutes-contract 2.7.1 → 2.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +91 -0
package/dist/export/exportFinalizedLeaves.d.ts +13 -1
package/dist/index.cjs +100 -3
package/dist/index.cjs.map +1 -1
package/dist/index.mjs +100 -3
package/dist/index.mjs.map +1 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -365,6 +365,8 @@ import { exportFinalizedLeaves } from '@emeryld/rrroutes-contract'
 const payload = await exportFinalizedLeaves(registry, {
   outFile: './finalized-leaves.export.json',
+  htmlFile: './finalized-leaves-viewer.baked.html',
+  openOnFinish: true,
 })
 ```
@@ -373,3 +375,92 @@ const payload = await exportFinalizedLeaves(registry, {
 - `_meta`: export/documentation metadata
 - `leaves`: contract-native serialized leaves
 - `schemaFlatByLeaf`: flattened schema map per leaf
+`htmlFile` writes a self-contained viewer HTML with the export payload baked in (no file picker needed).
+`viewerTemplateFile` optionally points to a custom viewer HTML template instead of the default bundled viewer.
+`openOnFinish` opens the generated `htmlFile` in your default browser after write completes.
+### Custom `viewerTemplateFile`
+Use `viewerTemplateFile` when you want your own branded/layout HTML while still baking export data directly into the page.
+Behavior:
+- If omitted, RRRoutes uses `packages/contract/tools/finalized-leaves-viewer.html`.
+- If provided, RRRoutes reads your template and injects a script like:
+  - `window.__FINALIZED_LEAVES_PAYLOAD = {...}`
+- If your template contains this marker comment, payload is injected exactly there:
+  - `<!--__FINALIZED_LEAVES_BAKED_PAYLOAD__-->`
+- If marker is missing, payload script is inserted before `</body>` (or prepended if no `</body>` exists).
+Minimal custom template example:
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>My Leaves Viewer</title>
+  </head>
+  <body>
+    <h1>My API Routes</h1>
+    <div id="app"></div>
+    <!--__FINALIZED_LEAVES_BAKED_PAYLOAD__-->
+    <script>
+      const payload = window.__FINALIZED_LEAVES_PAYLOAD
+      document.getElementById('app').textContent = payload
+        ? `Loaded ${payload.leaves.length} leaves`
+        : 'No baked payload found'
+    </script>
+  </body>
+</html>
+```
+Runtime usage with custom template:
+```ts
+await exportFinalizedLeaves(registry, {
+  htmlFile: './dist/leaves-viewer.html',
+  viewerTemplateFile: './tools/my-viewer-template.html',
+  openOnFinish: true,
+})
+```
+### Viewer HTML (searchable UI)
+A simple local viewer is included at:
+- `packages/contract/tools/finalized-leaves-viewer.html`
+How to use:
+1. Generate an export JSON with `export:finalized-leaves`.
+2. Open the HTML file in your browser.
+3. Load the JSON file using the file picker.
+4. Use the single search textbox + field checkboxes to filter routes.
+Each result is rendered as a collapsible block with title `METHOD path`.
+To access it from your project:
+- Quick local use: open the HTML file directly.
+- Team/shared use: serve it as a static file (Express example):
+```ts
+import express from 'express'
+import path from 'node:path'
+const app = express()
+app.use(
+  '/tools/finalized-leaves-viewer',
+  express.static(
+    path.resolve(process.cwd(), 'packages/contract/tools'),
+  ),
+)
+app.listen(3000)
+// open http://localhost:3000/tools/finalized-leaves-viewer/finalized-leaves-viewer.html
+```

package/dist/export/exportFinalizedLeaves.d.ts CHANGED Viewed

@@ -25,6 +25,18 @@ export type FinalizedLeavesExport = {
 };
 export type ExportFinalizedLeavesOptions = SerializeLeafContractOptions & {
     outFile?: string;
+    htmlFile?: string;
+    viewerTemplateFile?: string;
+    openOnFinish?: boolean;
 };
-export declare function writeFinalizedLeavesExport(payload: FinalizedLeavesExport, outFile: string): Promise<string>;
+export type WriteFinalizedLeavesExportOptions = {
+    outFile?: string;
+    htmlFile?: string;
+    viewerTemplateFile?: string;
+    openOnFinish?: boolean;
+};
+export declare function writeFinalizedLeavesExport(payload: FinalizedLeavesExport, outFileOrOptions: string | WriteFinalizedLeavesExportOptions): Promise<{
+    outFile?: string;
+    htmlFile?: string;
+}>;
 export declare function exportFinalizedLeaves(input: ExportFinalizedLeavesInput, options?: ExportFinalizedLeavesOptions): Promise<FinalizedLeavesExport>;

package/dist/index.cjs CHANGED Viewed

@@ -741,6 +741,7 @@ function flattenLeafSchemas(leaf) {
 // src/export/exportFinalizedLeaves.ts
 var import_promises = __toESM(require("fs/promises"), 1);
 var import_node_path = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
 function isRegistry(value) {
   return typeof value === "object" && value !== null && "all" in value && "byKey" in value;
 }
@@ -786,13 +787,104 @@ function buildMeta() {
     }
   };
 }
-async function writeFinalizedLeavesExport(payload, outFile) {
+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 import_node_path.default.resolve(viewerTemplateFile);
+  }
+  const candidates = [
+    import_node_path.default.resolve(process.cwd(), "tools/finalized-leaves-viewer.html"),
+    import_node_path.default.resolve(
+      process.cwd(),
+      "packages/contract/tools/finalized-leaves-viewer.html"
+    )
+  ];
+  for (const candidate of candidates) {
+    try {
+      await import_promises.default.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 = 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 writeBakedHtmlExport(payload, htmlFile, viewerTemplateFile) {
+  const templatePath = await resolveViewerTemplatePath(viewerTemplateFile);
+  const template = await import_promises.default.readFile(templatePath, "utf8");
+  const baked = injectPayloadIntoViewerHtml(template, payload);
+  const resolved = import_node_path.default.resolve(htmlFile);
+  await import_promises.default.mkdir(import_node_path.default.dirname(resolved), { recursive: true });
+  await import_promises.default.writeFile(resolved, baked, "utf8");
+  return resolved;
+}
+async function openHtmlInBrowser(filePath) {
+  const resolved = import_node_path.default.resolve(filePath);
+  const platform = process.platform;
+  if (platform === "darwin") {
+    (0, import_node_child_process.spawn)("open", [resolved], { detached: true, stdio: "ignore" }).unref();
+    return;
+  }
+  if (platform === "win32") {
+    (0, import_node_child_process.spawn)("cmd", ["/c", "start", "", resolved], {
+      detached: true,
+      stdio: "ignore"
+    }).unref();
+    return;
+  }
+  (0, import_node_child_process.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);
@@ -804,8 +896,13 @@ async function exportFinalizedLeaves(input, options = {}) {
     leaves: serializedLeaves,
     schemaFlatByLeaf
   };
-  if (options.outFile) {
-    await writeFinalizedLeavesExport(payload, options.outFile);
+  if (options.outFile || options.htmlFile) {
+    await writeFinalizedLeavesExport(payload, {
+      outFile: options.outFile,
+      htmlFile: options.htmlFile,
+      viewerTemplateFile: options.viewerTemplateFile,
+      openOnFinish: options.openOnFinish
+    });
   }
   return payload;
 }