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

@emeryld/rrroutes-contract 2.7.1 → 2.7.3

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 (10) hide show

package/README.md +92 -0
package/dist/export/defaultViewerTemplate.d.ts +1 -0
package/dist/export/exportFinalizedLeaves.d.ts +13 -1
package/dist/export/index.d.ts +1 -0
package/dist/index.cjs +179 -3
package/dist/index.cjs.map +1 -1
package/dist/index.mjs +178 -3
package/dist/index.mjs.map +1 -1
package/package.json +3 -2
package/tools/finalized-leaves-viewer.html +739 -0

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,93 @@ 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 the bundled `finalized-leaves-viewer.html` template.
+- Resolution order: package-bundled viewer, then local repo paths (`tools/...`, `packages/contract/tools/...`), then built-in string fallback.
+- 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/defaultViewerTemplate.d.ts ADDED Viewed

@@ -0,0 +1 @@

+ export declare const DEFAULT_VIEWER_TEMPLATE = "<!doctype html>\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>Finalized Leaves Viewer</title>\n <style>\n :root {\n --bg: #f5f7fb;\n --surface: #ffffff;\n --border: #d6ddea;\n --text: #172033;\n --muted: #5b6680;\n --accent: #1858c6;\n }\n body {\n margin: 0;\n font-family: 'Iosevka Web', 'SFMono-Regular', Menlo, Consolas, monospace;\n color: var(--text);\n background: linear-gradient(180deg, var(--bg), #eef2fa);\n }\n .wrap { max-width: 1100px; margin: 0 auto; padding: 20px; }\n .card { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; padding: 14px; }\n .meta { color: var(--muted); font-size: 12px; }\n #results { margin-top: 12px; display: grid; gap: 8px; }\n details { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 8px 10px; }\n summary { cursor: pointer; font-weight: 700; color: var(--accent); }\n pre { margin: 10px 0 0; overflow: auto; border: 1px solid var(--border); border-radius: 8px; padding: 10px; background: #fafcff; }\n </style>\n </head>\n <body>\n <div class=\"wrap\">\n <h1>Finalized Leaves Viewer (Baked)</h1>\n <div class=\"card\">\n <div id=\"status\" class=\"meta\">Waiting for baked payload...</div>\n </div>\n <div id=\"results\"></div>\n </div>\n\n \n\n <script>\n const statusEl = document.getElementById('status')\n const resultsEl = document.getElementById('results')\n const payload = window.__FINALIZED_LEAVES_PAYLOAD\n\n if (!payload || !Array.isArray(payload.leaves)) {\n statusEl.textContent = 'No baked payload found in this HTML file.'\n } else {\n statusEl.textContent = 'Loaded baked payload with ' + payload.leaves.length + ' routes.'\n\n payload.leaves.forEach((leaf) => {\n const details = document.createElement('details')\n const summary = document.createElement('summary')\n summary.textContent = String(leaf.method || '').toUpperCase() + ' ' + (leaf.path || '')\n\n const pre = document.createElement('pre')\n pre.textContent = JSON.stringify(leaf, null, 2)\n\n details.appendChild(summary)\n details.appendChild(pre)\n resultsEl.appendChild(details)\n })\n }\n </script>\n </body>\n</html>\n";

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/export/index.d.ts CHANGED Viewed

@@ -3,3 +3,4 @@ export * from './serializeLeafContract';
 export * from './flattenSchema';
 export * from './exportFinalizedLeaves';
 export * from './exportFinalizedLeaves.cli';
+export * from './defaultViewerTemplate';

package/dist/index.cjs CHANGED Viewed

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_VIEWER_TEMPLATE: () => DEFAULT_VIEWER_TEMPLATE,
   buildCacheKey: () => buildCacheKey,
   buildLowProfileLeaf: () => buildLowProfileLeaf,
   clearSchemaIntrospectionHandlers: () => clearSchemaIntrospectionHandlers,
@@ -741,6 +742,79 @@ 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");
+// src/export/defaultViewerTemplate.ts
+var DEFAULT_VIEWER_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Finalized Leaves Viewer</title>
+    <style>
+      :root {
+        --bg: #f5f7fb;
+        --surface: #ffffff;
+        --border: #d6ddea;
+        --text: #172033;
+        --muted: #5b6680;
+        --accent: #1858c6;
+      }
+      body {
+        margin: 0;
+        font-family: 'Iosevka Web', 'SFMono-Regular', Menlo, Consolas, monospace;
+        color: var(--text);
+        background: linear-gradient(180deg, var(--bg), #eef2fa);
+      }
+      .wrap { max-width: 1100px; margin: 0 auto; padding: 20px; }
+      .card { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; padding: 14px; }
+      .meta { color: var(--muted); font-size: 12px; }
+      #results { margin-top: 12px; display: grid; gap: 8px; }
+      details { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 8px 10px; }
+      summary { cursor: pointer; font-weight: 700; color: var(--accent); }
+      pre { margin: 10px 0 0; overflow: auto; border: 1px solid var(--border); border-radius: 8px; padding: 10px; background: #fafcff; }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <h1>Finalized Leaves Viewer (Baked)</h1>
+      <div class="card">
+        <div id="status" class="meta">Waiting for baked payload...</div>
+      </div>
+      <div id="results"></div>
+    </div>
+    <!--__FINALIZED_LEAVES_BAKED_PAYLOAD__-->
+    <script>
+      const statusEl = document.getElementById('status')
+      const resultsEl = document.getElementById('results')
+      const payload = window.__FINALIZED_LEAVES_PAYLOAD
+      if (!payload || !Array.isArray(payload.leaves)) {
+        statusEl.textContent = 'No baked payload found in this HTML file.'
+      } else {
+        statusEl.textContent =           'Loaded baked payload with ' + payload.leaves.length + ' routes.'
+        payload.leaves.forEach((leaf) => {
+          const details = document.createElement('details')
+          const summary = document.createElement('summary')
+          summary.textContent = String(leaf.method || '').toUpperCase() + ' ' + (leaf.path || '')
+          const pre = document.createElement('pre')
+          pre.textContent = JSON.stringify(leaf, null, 2)
+          details.appendChild(summary)
+          details.appendChild(pre)
+          resultsEl.appendChild(details)
+        })
+      }
+    </script>
+  </body>
+</html>
+`;
+// src/export/exportFinalizedLeaves.ts
 function isRegistry(value) {
   return typeof value === "object" && value !== null && "all" in value && "byKey" in value;
 }
@@ -786,13 +860,109 @@ 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) {
+    const resolved = import_node_path.default.resolve(viewerTemplateFile);
+    await import_promises.default.access(resolved);
+    return resolved;
+  }
+  const candidates = [
+    import_node_path.default.resolve(
+      process.cwd(),
+      "node_modules/@emeryld/rrroutes-contract/tools/finalized-leaves-viewer.html"
+    ),
+    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 {
+    }
+  }
+  return void 0;
+}
+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 = templatePath ? await import_promises.default.readFile(templatePath, "utf8") : DEFAULT_VIEWER_TEMPLATE;
+  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 +974,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;
 }
@@ -859,6 +1034,7 @@ async function runExportFinalizedLeavesCli(argv) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_VIEWER_TEMPLATE,
   buildCacheKey,
   buildLowProfileLeaf,
   clearSchemaIntrospectionHandlers,