praetom 0.2.4 → 0.3.0-rc.1

package/dist/_active-channel.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Live active-feature-map channel.
+ *
+ * Default transport is **SSE** over fetch (`text/event-stream`). The
+ * server pushes a `snapshot` event on connect and on every server-side
+ * change to the active set; each event carries the full active list,
+ * which we hand to `setActiveMap` so existing late-binding wraps pick
+ * up the new state on their next call.
+ *
+ * Edge / serverless environments (Vercel Edge, AWS Lambda, Cloudflare
+ * Workers) don't keep long-lived connections — we fall back to 30s
+ * polling on `/api/runtime/active`. The fallback also fires
+ * permanently after `MAX_RECONNECT_FAILURES` consecutive SSE
+ * connection failures.
+ */
+interface ChannelConfig {
+    configEndpoint: string;
+    ingestId: string;
+    warn: (msg: string) => void;
+    /** SDK version stamp; surfaces in the dashboard's live-instances panel. */
+    sdkVersion?: string;
+    /** Service identifier (heartbeat key); surfaces alongside SDK version. */
+    serviceName?: string | null;
+}
+export declare function startActiveChannel(cfg: ChannelConfig): void;
+export declare function stopActiveChannel(): void;
+export {};
+//# sourceMappingURL=_active-channel.d.ts.map

package/dist/_active-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_active-channel.d.ts","sourceRoot":"","sources":["../src/_active-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH,UAAU,aAAa;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAYD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAU3D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CASxC"}

package/dist/_active-channel.js

@@ -0,0 +1,237 @@
+/**
+ * Live active-feature-map channel.
+ *
+ * Default transport is **SSE** over fetch (`text/event-stream`). The
+ * server pushes a `snapshot` event on connect and on every server-side
+ * change to the active set; each event carries the full active list,
+ * which we hand to `setActiveMap` so existing late-binding wraps pick
+ * up the new state on their next call.
+ *
+ * Edge / serverless environments (Vercel Edge, AWS Lambda, Cloudflare
+ * Workers) don't keep long-lived connections — we fall back to 30s
+ * polling on `/api/runtime/active`. The fallback also fires
+ * permanently after `MAX_RECONNECT_FAILURES` consecutive SSE
+ * connection failures.
+ */
+import { setActiveMap } from "./_internal.js";
+const POLL_INTERVAL_MS = 30_000;
+const MAX_RECONNECT_FAILURES = 5;
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 60_000;
+let _abort = null;
+let _pollTimer = null;
+let _lastPollEtag = null;
+let _reconnectFailures = 0;
+export function startActiveChannel(cfg) {
+    stopActiveChannel(); // idempotent — register() can be called twice
+    if (shouldPollOnly()) {
+        cfg.warn("active-channel using polling (edge/serverless environment)");
+        startPolling(cfg);
+        return;
+    }
+    void connectSse(cfg);
+}
+export function stopActiveChannel() {
+    if (_abort) {
+        _abort.abort();
+        _abort = null;
+    }
+    if (_pollTimer) {
+        clearInterval(_pollTimer);
+        _pollTimer = null;
+    }
+}
+/**
+ * Detect runtime contexts where SSE is a bad fit. Short-lived per-
+ * request invocations can't keep a connection open across requests, so
+ * they fall back to per-boot polling.
+ */
+function shouldPollOnly() {
+    const env = globalThis.process?.env ?? {};
+    if (typeof globalThis.EdgeRuntime !== "undefined") {
+        return true;
+    }
+    if (env.AWS_LAMBDA_FUNCTION_NAME)
+        return true;
+    if (env.VERCEL && env.VERCEL_REGION) {
+        // Vercel serverless functions; long-running services on Vercel
+        // (rare for Node, common for Hono/Cloudflare) won't set
+        // VERCEL_REGION at runtime.
+        return true;
+    }
+    return false;
+}
+async function connectSse(cfg) {
+    while (true) {
+        const abort = new AbortController();
+        _abort = abort;
+        const url = activeStreamUrl(cfg.configEndpoint);
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: identityHeaders(cfg, "text/event-stream"),
+                signal: abort.signal,
+            });
+            if (!res.ok || !res.body) {
+                throw new Error(`HTTP ${res.status}`);
+            }
+            _reconnectFailures = 0;
+            await consumeSseStream(res.body, cfg.warn);
+            // Stream ended cleanly (server closed). Reconnect after a short
+            // pause unless we're shutting down.
+            if (abort.signal.aborted)
+                return;
+        }
+        catch (e) {
+            if (abort.signal.aborted)
+                return;
+            _reconnectFailures += 1;
+            cfg.warn(`active-channel SSE error (${_reconnectFailures}/${MAX_RECONNECT_FAILURES}): ${e.message}`);
+            if (_reconnectFailures >= MAX_RECONNECT_FAILURES) {
+                cfg.warn(`active-channel falling back to polling after ${MAX_RECONNECT_FAILURES} consecutive failures`);
+                startPolling(cfg);
+                return;
+            }
+        }
+        await sleep(backoffMs(_reconnectFailures), _abort?.signal);
+    }
+}
+async function consumeSseStream(body, warn) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            buffer += decoder.decode(value, { stream: true });
+            // SSE events are separated by blank lines (\n\n). Parse one at a time.
+            let idx;
+            while ((idx = buffer.indexOf("\n\n")) !== -1) {
+                const rawEvent = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                const parsed = parseSseEvent(rawEvent);
+                if (!parsed)
+                    continue;
+                if (parsed.event === "snapshot") {
+                    try {
+                        const payload = JSON.parse(parsed.data);
+                        setActiveMap(payload.active);
+                    }
+                    catch (e) {
+                        warn(`active-channel: invalid snapshot payload: ${e.message}`);
+                    }
+                }
+                else if (parsed.event === "error") {
+                    warn(`active-channel: server error event: ${parsed.data}`);
+                }
+                // 'heartbeat' (SSE comment) is dropped during parsing — see below.
+            }
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // already released
+        }
+    }
+}
+function parseSseEvent(raw) {
+    let event = "message";
+    const dataLines = [];
+    for (const line of raw.split("\n")) {
+        if (line.startsWith(":"))
+            continue; // SSE comment (heartbeats land here)
+        if (line.startsWith("event:")) {
+            event = line.slice(6).trim();
+        }
+        else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).replace(/^ /, ""));
+        }
+    }
+    if (dataLines.length === 0 && event === "message")
+        return null;
+    return { event, data: dataLines.join("\n") };
+}
+function startPolling(cfg) {
+    // Fire immediately so initial state lands before the first interval.
+    void pollOnce(cfg);
+    _pollTimer = setInterval(() => {
+        void pollOnce(cfg);
+    }, POLL_INTERVAL_MS);
+    if (typeof _pollTimer.unref === "function") {
+        _pollTimer.unref();
+    }
+}
+async function pollOnce(cfg) {
+    const url = activeSnapshotUrl(cfg.configEndpoint);
+    try {
+        const headers = identityHeaders(cfg, "application/json");
+        if (_lastPollEtag)
+            headers["if-none-match"] = _lastPollEtag;
+        const res = await fetch(url, { headers });
+        if (res.status === 304)
+            return;
+        if (!res.ok) {
+            cfg.warn(`active-channel poll: HTTP ${res.status}`);
+            return;
+        }
+        _lastPollEtag = res.headers.get("etag");
+        const payload = (await res.json());
+        setActiveMap(payload.active);
+    }
+    catch (e) {
+        cfg.warn(`active-channel poll error: ${e.message}`);
+    }
+}
+/**
+ * Standard request identity headers — surface the SDK + Node version
+ * and the service name so the dashboard's live-instances panel can
+ * group connections meaningfully.
+ */
+function identityHeaders(cfg, accept) {
+    const headers = {
+        authorization: `Bearer ${cfg.ingestId}`,
+        accept,
+    };
+    if (cfg.sdkVersion)
+        headers["x-praetom-sdk-version"] = cfg.sdkVersion;
+    const nodeVersion = globalThis
+        .process?.versions?.node;
+    if (nodeVersion)
+        headers["x-praetom-node-version"] = nodeVersion;
+    if (cfg.serviceName)
+        headers["x-praetom-service"] = cfg.serviceName;
+    return headers;
+}
+function activeStreamUrl(configEndpoint) {
+    // Replace `/runtime/config` → `/runtime/active/stream` so customers
+    // overriding the endpoint keep their override semantics.
+    return configEndpoint.replace(/\/config(?:\/?$|\?)/, "/active/stream$1");
+}
+function activeSnapshotUrl(configEndpoint) {
+    return configEndpoint.replace(/\/config(?:\/?$|\?)/, "/active$1");
+}
+function backoffMs(attempt) {
+    const exp = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** attempt);
+    // Add ±25% jitter to avoid thundering herd on widespread server restarts.
+    return Math.floor(exp * (0.75 + Math.random() * 0.5));
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const t = setTimeout(resolve, ms);
+        if (typeof t.unref === "function") {
+            t.unref();
+        }
+        signal?.addEventListener("abort", () => {
+            clearTimeout(t);
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=_active-channel.js.map

package/dist/_active-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_active-channel.js","sourceRoot":"","sources":["../src/_active-channel.ts"],"names":[],"mappings":"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"}

package/dist/_esm-loader.d.ts

@@ -4,36 +4,34 @@
  * (Express/Fastify/Hono/Nest with `.mjs`/`.ts`), Bun, and pre-bundle
  * dev mode for several frameworks.
  *
- * Registered via `module.register('./dist/_esm-loader.js', import.meta.url,
- * { data: { featureMap: [...] } })` from server.ts's installEsmLoader().
+ * Registered via `module.register('./dist/_esm-loader.js',
+ * import.meta.url, { data: { eligibility: [...] } })` from server.ts's
+ * installEsmLoader().
  *
- * Strategy: regex-level source rewriting on files matching a feature
- * path. Detects common named-function export shapes, renames the
- * underlying function, and appends a wrapped re-export that calls
- * `__praetomWrapEntryPoint`. Falls back to no-op (with a `[praetom]`
- * warning) for shapes that don't match.
+ * Strategy: source rewriting on files matching an *eligibility* entry.
+ * The rewrite emits late-binding wraps (`__praetomLateBindWrap`) — no
+ * slug is baked in. At call time, the wrap reads the shared
+ * `activeMap` on globalThis and decides whether to emit a span.
  *
- * Handles:
- *   export async function NAME(...)
- *   export function NAME(...)
- *   export const NAME = async (...)
- *   export const NAME = (...)
- *
- * Does NOT handle (yet):
- *   export default ...
- *   export { NAME }
- *   export { NAME as default }
- *   class exports
- *
- * The bundler plugins (Vite/Webpack) cover the cases this loader skips
- * — bundled apps go through the plugin, not this loader.
+ * The loader appends an inline `//# sourceMappingURL=data:` so stack
+ * traces stay aligned to the original lines after the rewrite.
  */
-interface FeatureMapEntry {
-    slug: string;
-    entrySymbol?: string;
-}
+import type { MessagePort } from "node:worker_threads";
 interface InitData {
-    featureMap: Array<[string, FeatureMapEntry]>;
+    eligibility: Array<[string, ReadonlyArray<{
+        exportName: string;
+    }>]>;
+    /**
+     * Optional MessagePort the main thread uses to push eligibility
+     * updates after boot. When provided, the loader listens for messages
+     * shaped `{ type: "eligibility", eligibility: [...] }` and swaps the
+     * in-memory map. When omitted, eligibility is frozen at boot
+     * (back-compat with pre-hot-pickup SDK builds).
+     *
+     * Already-loaded modules keep their boot-time wrap (or lack of wrap)
+     * — the loader only runs on `load()` for fresh imports.
+     */
+    port?: MessagePort;
 }
 interface LoadResult {
     format: string;

package/dist/_esm-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_esm-loader.d.ts","sourceRoot":"","sources":["../src/_esm-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,QAAQ;IAChB,UAAU,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CAC9C;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,CAAC;IAChD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,KAAK,QAAQ,GAAG,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,UAAU,CAAC,CAAC;AAKzB,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAG/C;AAED,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,UAAU,CAAC,CAoCrB"}
+{"version":3,"file":"_esm-loader.d.ts","sourceRoot":"","sources":["../src/_esm-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AASvD,UAAU,QAAQ;IAChB,WAAW,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC,CAAC;IACpE;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAOD,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,CAAC;IAChD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,KAAK,QAAQ,GAAG,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,UAAU,CAAC,CAAC;AAKzB,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAiB/C;AAgBD,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,UAAU,CAAC,CA+CrB"}

package/dist/_esm-loader.js

@@ -4,35 +4,48 @@
  * (Express/Fastify/Hono/Nest with `.mjs`/`.ts`), Bun, and pre-bundle
  * dev mode for several frameworks.
  *
- * Registered via `module.register('./dist/_esm-loader.js', import.meta.url,
- * { data: { featureMap: [...] } })` from server.ts's installEsmLoader().
+ * Registered via `module.register('./dist/_esm-loader.js',
+ * import.meta.url, { data: { eligibility: [...] } })` from server.ts's
+ * installEsmLoader().
  *
- * Strategy: regex-level source rewriting on files matching a feature
- * path. Detects common named-function export shapes, renames the
- * underlying function, and appends a wrapped re-export that calls
- * `__praetomWrapEntryPoint`. Falls back to no-op (with a `[praetom]`
- * warning) for shapes that don't match.
+ * Strategy: source rewriting on files matching an *eligibility* entry.
+ * The rewrite emits late-binding wraps (`__praetomLateBindWrap`) — no
+ * slug is baked in. At call time, the wrap reads the shared
+ * `activeMap` on globalThis and decides whether to emit a span.
  *
- * Handles:
- *   export async function NAME(...)
- *   export function NAME(...)
- *   export const NAME = async (...)
- *   export const NAME = (...)
- *
- * Does NOT handle (yet):
- *   export default ...
- *   export { NAME }
- *   export { NAME as default }
- *   class exports
- *
- * The bundler plugins (Vite/Webpack) cover the cases this loader skips
- * — bundled apps go through the plugin, not this loader.
+ * The loader appends an inline `//# sourceMappingURL=data:` so stack
+ * traces stay aligned to the original lines after the rewrite.
  */
-let _featureMap = new Map();
+import { wrapModuleSourceForLateBinding } from "./webpack/shared";
+let _eligibility = new Map();
 let _initialized = false;
 export function initialize(data) {
-    _featureMap = new Map(data.featureMap);
+    applyEligibility(data.eligibility);
     _initialized = true;
+    // Subscribe to live updates from the main thread. Once the loader's
+    // map is replaced, every subsequent `load()` call wraps against the
+    // fresh eligibility set — same semantics as the CJS hook's runtime-
+    // re-read of mapByPath.
+    if (data.port) {
+        data.port.on("message", (msg) => {
+            if (!isEligibilityUpdate(msg))
+                return;
+            applyEligibility(msg.eligibility);
+        });
+        // Don't let the loader's port keep the process alive past its
+        // real work.
+        if (typeof data.port.unref === "function")
+            data.port.unref();
+    }
+}
+function applyEligibility(next) {
+    _eligibility = new Map(next.map(([path, exports]) => [path, { exports: [...exports] }]));
+}
+function isEligibilityUpdate(msg) {
+    if (!msg || typeof msg !== "object")
+        return false;
+    const m = msg;
+    return m.type === "eligibility" && Array.isArray(m.eligibility);
 }
 export async function load(url, context, nextLoad) {
     const result = await nextLoad(url, context);
@@ -49,7 +62,7 @@ export async function load(url, context, nextLoad) {
     catch {
         return result;
     }
-    const match = matchFeature(filePath);
+    const match = matchEligibility(filePath);
     if (!match)
         return result;
     const source = typeof result.source === "string"
@@ -59,76 +72,27 @@ export async function load(url, context, nextLoad) {
                 ? new Uint8Array(result.source)
                 : result.source)
             : "";
-    const wrapped = wrapModuleSource(source, match.slug, match.entrySymbol);
+    const wrapped = wrapModuleSourceForLateBinding(source, match.featurePath, match.file.exports.map((e) => e.exportName), filePath);
     if (!wrapped) {
         // eslint-disable-next-line no-console
         console.warn(`[praetom] could not wrap ${filePath} (export shape not recognized; falling back to no-op)`);
         return result;
     }
-    return { ...result, source: wrapped };
+    const mapJson = wrapped.map.toString();
+    const inlined = Buffer.from(mapJson, "utf8").toString("base64");
+    const sourceWithMap = wrapped.code + `\n//# sourceMappingURL=data:application/json;base64,${inlined}\n`;
+    return { ...result, source: sourceWithMap };
 }
-function matchFeature(absPath) {
+function matchEligibility(absPath) {
     const normalized = absPath.replace(/\\/g, "/");
-    for (const [featurePath, info] of _featureMap) {
-        if (normalized === featurePath)
-            return info;
-        // Anchored suffix: see server.ts matchFeatureForPath. Single-
-        // segment featurePaths are skipped (ambiguous).
+    const direct = _eligibility.get(normalized);
+    if (direct)
+        return { featurePath: normalized, file: direct };
+    for (const [featurePath, file] of _eligibility) {
         if (featurePath.includes("/") && normalized.endsWith(`/${featurePath}`)) {
-            return info;
+            return { featurePath, file };
         }
     }
     return null;
 }
-const PRAETOM_IMPORT_MARKER = "__praetom_wrap_import__";
-const HTTP_METHODS = new Set([
-    "GET",
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "OPTIONS",
-    "HEAD",
-]);
-function wrapModuleSource(source, slug, entrySymbol) {
-    if (source.includes(PRAETOM_IMPORT_MARKER)) {
-        // Already wrapped (shouldn't happen with nextLoad short-circuit but
-        // belt + suspenders).
-        return null;
-    }
-    // Pattern A: `export (async )?function NAME(` — rewrite the export
-    // keyword off, rename the function to __praetom_orig_NAME, and
-    // append an `export const NAME = __wrap(...)`.
-    // Pattern B: `export const NAME = ` (function value) — same shape.
-    const targets = new Set();
-    let rewritten = source.replace(/^export\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/gm, (_match, asyncKw, name) => {
-        targets.add(name);
-        return `${asyncKw ?? ""}function __praetom_orig_${name}(`;
-    });
-    rewritten = rewritten.replace(/^export\s+const\s+([A-Za-z_$][\w$]*)\s*=/gm, (_match, name) => {
-        // Only wrap if the entry name is the requested entrySymbol (when
-        // specified) or an HTTP method (Next.js App Router convention).
-        // Otherwise leave alone — `export const foo = "bar"` shouldn't
-        // become `wrapEntryPoint(..., "bar")`.
-        if (!shouldWrap(name, entrySymbol))
-            return `export const ${name} =`;
-        targets.add(name);
-        return `const __praetom_orig_${name} =`;
-    });
-    if (targets.size === 0)
-        return null;
-    const filtered = [...targets].filter((n) => shouldWrap(n, entrySymbol));
-    if (filtered.length === 0)
-        return null;
-    const importLine = `import { __praetomWrapEntryPoint as ${PRAETOM_IMPORT_MARKER} } from "praetom";\n`;
-    const wraps = filtered
-        .map((name) => `export const ${name} = ${PRAETOM_IMPORT_MARKER}(${JSON.stringify(slug)}, ${JSON.stringify(name)}, __praetom_orig_${name});`)
-        .join("\n");
-    return `${importLine}${rewritten}\n${wraps}\n`;
-}
-function shouldWrap(name, entrySymbol) {
-    if (entrySymbol)
-        return name === entrySymbol;
-    return HTTP_METHODS.has(name) || name === "handler" || name === "default";
-}
 //# sourceMappingURL=_esm-loader.js.map

package/dist/_esm-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"_esm-loader.js","sourceRoot":"","sources":["../src/_esm-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_esm-loader.js","sourceRoot":"","sources":["../src/_esm-loader.ts"],"names":[],"mappings":"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"}

package/dist/_internal.d.ts

@@ -47,6 +47,37 @@ export declare function currentFeatureContext(): FeatureContext | undefined;
  * bundler-plugin-injected code can call it; customers should never
  * import it directly.
  */
+/**
+ * Late-binding wrap. Installed once at module-load time for every
+ * `(path, exportName)` pair the server declares as eligible. The wrap
+ * defers the slug decision to call time: each invocation reads the
+ * shared `activeMap` (mutated by the active-channel client when the
+ * dashboard adds/removes features) and either:
+ *   - finds an entry for `path:exportName` → feature-wraps with that slug, or
+ *   - finds nothing → passes straight through to the original.
+ *
+ * The passthrough path adds one `Map.get(string)` per call (~tens of
+ * ns). The active path is identical cost to a normal `wrapEntryPoint`.
+ *
+ * Preserves `.name`, `.length`, and `Function.prototype.toString` so
+ * frameworks that introspect function shape (Express middleware's
+ * length-based handler detection, NestJS decorators, etc.) keep
+ * working.
+ */
+export declare function lateBindWrap(path: string, exportName: string, original: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown;
+/**
+ * Snapshot-mode update: replace the active map wholesale. Called by
+ * the active-channel client on every snapshot event (SSE or poll).
+ * Cheap — single Map mutation, no allocation per entry beyond the
+ * source iteration.
+ */
+export declare function setActiveMap(entries: ReadonlyArray<{
+    path: string;
+    exportName: string;
+    slug: string;
+}>): void;
+/** Read-only access for diagnostic / test code. */
+export declare function getActiveMapSize(): number;
 export declare function wrapEntryPoint(slug: string, entryName: string, original: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown;
 /**
  * Public primitive — fire a point-in-time event tagged with the current
@@ -54,8 +85,44 @@ export declare function wrapEntryPoint(slug: string, entryName: string, original
  * latency splits, business events, or error context that the entry-
  * point wrap doesn't capture by itself.
  *
+ * ## Context propagation (Node.js)
+ *
+ * `emit()` discovers the current feature via Node's `AsyncLocalStorage`.
+ * That means it works **only inside the async causality chain started
+ * by a wrapped entry point**:
+ *
+ *   - ✅ awaited code paths inside the handler (`await db.query(...)` →
+ *     subsequent `emit()`)
+ *   - ✅ `setTimeout` / `setImmediate` / `queueMicrotask` callbacks
+ *     scheduled inside the handler — they inherit the ALS store
+ *   - ✅ Promise chains that fork off the handler's call stack
+ *   - ❌ `EventEmitter` listeners attached *outside* the handler and
+ *     fired *from* it — listeners run in the caller's ALS scope, not
+ *     the emitter's. Wrap listener attachment inside the handler (or
+ *     pass the slug explicitly via a closure) to keep context.
+ *   - ❌ Code executed from a **background worker / cron / queue
+ *     consumer** that wasn't itself wrapped. There's no entry-point
+ *     wrap, so there's no feature context. The `emit()` still records
+ *     as a root span with no parent, but won't aggregate into any
+ *     feature's signal.
+ *   - ❌ Code that escapes the request via a detached `setImmediate`
+ *     chain where you intentionally `als.exit()` (unusual; if you're
+ *     doing this you already know).
+ *
+ * If you need feature context on a background path, wrap the background
+ * worker's entry point itself (the bundler plugin handles this when
+ * you point a feature contract at the worker's `path`).
+ *
  * Outside a feature context the span still emits, but with no parent —
  * use sparingly for top-level signals.
+ *
+ * ## Browser
+ *
+ * Browser builds don't use ALS (it doesn't exist in the browser). The
+ * current feature is read from a per-tab stack maintained by
+ * `__praetomWrapEntryPoint` — same shape, different mechanism. Same
+ * gotchas: `emit()` inside an event listener attached outside the wrap
+ * won't pick up the feature.
  */
 export declare function emit(eventName: string, payload?: Record<string, unknown>): void;
 export declare function flush(): Promise<void>;

package/dist/_internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_internal.d.ts","sourceRoot":"","sources":["../src/_internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4CH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAsCD,wBAAgB,IAAI,CAAC,IAAI,EAAE;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAOP;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAiB3D;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,EAC3F,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAqBD,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,SAAS,CAElE;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GACxC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAsBjC;AA8CD;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAgBN;AAqCD,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C"}
+{"version":3,"file":"_internal.d.ts","sourceRoot":"","sources":["../src/_internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4CH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAgDD,wBAAgB,IAAI,CAAC,IAAI,EAAE;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAOP;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAiB3D;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,EAC3F,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAqBD,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,SAAS,CAElE;AAYD;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GACxC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CA0BjC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACzE,IAAI,CAKN;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AA6CD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GACxC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CA6BjC;AA8CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,IAAI,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAgBN;AAqCD,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C"}