react-on-rails-pro-node-renderer 17.0.0-rc.3 → 17.0.0-rc.4

package/lib/worker/vmSourceMapSupport.d.ts

@@ -0,0 +1,110 @@
+export interface BundleSourceMapRegistration {
+    bundleFilePath: string;
+    /**
+     * Column correction for frames on line 1 of the bundle. When the bundle is
+     * evaluated wrapped in `Module.wrap` (the `supportModules` /
+     * `additionalContext` path), the wrapper prefix shifts every first-line
+     * column by its length.
+     */
+    firstLineColumnOffset: number;
+    /**
+     * `undefined` means the bundle text was not available at registration time
+     * and must be checked lazily. `null` means it was checked and no
+     * sourceMappingURL comment was present.
+     */
+    sourceMappingUrl?: string | null;
+    /**
+     * `undefined` keeps lazy synchronous lookup behavior. `null` means registration
+     * time lookup found no usable source map. A string freezes the source-map JSON
+     * for this VM generation so same-path rebuilds cannot remap old bytecode with
+     * a newer map.
+     */
+    sourceMapJson?: string | null;
+    realBundleDirectory: string;
+    /**
+     * External source maps can arrive after a bundle first becomes visible. When
+     * true, a missing external map is retried briefly before caching the miss.
+     */
+    retryMissingSourceMap?: boolean;
+}
+interface SourceMapLookupAttempt {
+    missingSourceMaps: WeakSet<BundleSourceMapRegistration>;
+}
+export declare function retireMissingSourceMapRetry(registration: BundleSourceMapRegistration): void;
+export declare function createSourceMapLookupAttempt(): SourceMapLookupAttempt;
+/**
+ * Name of the host-callback global injected into the VM context. Used by
+ * {@link PREPARE_STACK_TRACE_INSTALL_SCRIPT}.
+ */
+export declare const SOURCE_MAP_RESOLVER_CONTEXT_KEY = "__reactOnRailsProResolveOriginalSourcePosition";
+/**
+ * Name of the host-callback global used to group resolver calls that belong to
+ * one `.stack` formatting attempt.
+ */
+export declare const SOURCE_MAP_LOOKUP_ATTEMPT_CONTEXT_KEY = "__reactOnRailsProCreateSourceMapLookupAttempt";
+/**
+ * Name of the host-callback global injected into the VM context for stacks
+ * serialized by react-on-rails before they can escape to the host formatter.
+ */
+export declare const SOURCE_MAP_STACK_REMAPPER_CONTEXT_KEY = "__reactOnRailsProRemapStackTrace";
+/** @internal Used by VM build to avoid synchronous external-map reads. */
+export declare function preloadSourceMapJsonForBundle(bundleFilePath: string, bundleContents: string): Promise<{
+    retryMissingSourceMap: boolean;
+    sourceMapJson: string | null;
+} | {
+    retryMissingSourceMap: boolean;
+    sourceMapJson: string | undefined;
+}>;
+/**
+ * Registers a bundle file so stack frames pointing into it can be remapped.
+ * Pass `bundleContents` when available; omitting it makes the first error-path
+ * lookup synchronously re-read the bundle to find its `sourceMappingURL`.
+ * `preloadedSourceMapJson` supplies known JSON/null for this VM generation;
+ * `retryMissingSourceMap` keeps external preload misses retryable until a map is
+ * found, the retry cap is reached, or a same-path generation replaces the registration.
+ */
+export declare function registerBundleForSourceMaps(bundleFilePath: string, firstLineColumnOffset?: number, bundleContents?: string, preloadedSourceMapJson?: string | null, retryMissingSourceMap?: boolean): {
+    bundleFilePath: string;
+    firstLineColumnOffset: number;
+    realBundleDirectory: string;
+    sourceMappingUrl: string | null | undefined;
+    sourceMapJson: string | null | undefined;
+    retryMissingSourceMap: boolean;
+};
+/**
+ * Drops the registration and any cached source map for a bundle.
+ */
+export declare function unregisterBundleForSourceMaps(bundleOrRegistration: string | BundleSourceMapRegistration): void;
+/** @internal Used in tests */
+export declare function resetSourceMapSupport(): void;
+export interface ResolvedSourcePosition {
+    source: string;
+    line: number;
+    column: number;
+}
+/**
+ * Resolves a 1-based generated position in a registered bundle to its original
+ * source position. Returns null when the position cannot be mapped.
+ *
+ * SECURITY: this function is exposed to untrusted bundle code inside the VM
+ * context, so it validates its inputs and only operates on registered bundle
+ * paths.
+ *
+ * @param lineNumber 1-based generated line number, matching V8 CallSite values.
+ * @param columnNumber 1-based generated column number, matching V8 CallSite values.
+ */
+export declare function resolveOriginalPositionForRegistration(registration: BundleSourceMapRegistration, fileName: unknown, lineNumber: unknown, columnNumber: unknown, lookupAttempt?: unknown): ResolvedSourcePosition | null;
+export declare function remapStackTrace(stack: unknown, registration?: BundleSourceMapRegistration): string | undefined;
+export declare function remapErrorStack(error: unknown, registration?: BundleSourceMapRegistration): void;
+/**
+ * Script run inside the VM context (before the bundle is evaluated) that
+ * installs an `Error.prepareStackTrace` mirroring V8's default format but
+ * rewriting `file:line:column` locations through the host-side resolver when a
+ * source-mapped position is available. Bundle code can replace
+ * `Error.prepareStackTrace` after this script runs; if it does, source mapping
+ * is disabled for that VM context. Any failure falls back to the original frame
+ * text.
+ */
+export declare const PREPARE_STACK_TRACE_INSTALL_SCRIPT = "\nError.prepareStackTrace = function (error, callSites) {\n  var header;\n  try {\n    header = String(error);\n  } catch (formatError) {\n    header = '<error>';\n  }\n  var parts = [header];\n  var sourceMapLookupAttempt;\n  try {\n    if (typeof __reactOnRailsProCreateSourceMapLookupAttempt === 'function') {\n      sourceMapLookupAttempt = __reactOnRailsProCreateSourceMapLookupAttempt();\n    }\n  } catch (lookupAttemptError) {\n    sourceMapLookupAttempt = undefined;\n  }\n  for (var i = 0; i < callSites.length; i++) {\n    var frameText;\n    try {\n      frameText = String(callSites[i]);\n    } catch (formatFrameError) {\n      frameText = '<frame>';\n    }\n    try {\n      var fileName = callSites[i].getFileName();\n      var line = callSites[i].getLineNumber();\n      var column = callSites[i].getColumnNumber();\n      if (\n        fileName != null &&\n        line != null &&\n        column != null &&\n        typeof __reactOnRailsProResolveOriginalSourcePosition === 'function'\n      ) {\n        var position = __reactOnRailsProResolveOriginalSourcePosition(fileName, line, column, sourceMapLookupAttempt);\n        if (position) {\n          var generatedLocation = fileName + ':' + line + ':' + column;\n          var originalLocation = position.source + ':' + position.line + ':' + position.column;\n          if (frameText.indexOf(generatedLocation) !== -1) {\n            // String first-arg: replace only the frame's canonical location once.\n            // Do not use a /g regex here; a repeated numeric location elsewhere\n            // in the frame text should not be rewritten.\n            frameText = frameText.replace(generatedLocation, function () { return originalLocation; });\n          } else {\n            frameText = frameText + ' -> ' + originalLocation;\n          }\n        }\n      }\n    } catch (resolveError) {\n      // Keep the original frame text.\n    }\n    parts.push('    at ' + frameText);\n  }\n  return parts.join('\\n');\n};\n";
+export {};
+//# sourceMappingURL=vmSourceMapSupport.d.ts.map