feat: Add basic polyfills (#5)

Author: timfish

README.md

@@ -1,10 +1,32 @@
 # javascript-debug-ids
 
+JavaScript Polyfills and Bundler Plugins for the TC39 [Debug ID proposal](https://github.com/tc39/source-map/blob/main/proposals/debug-id.md).
+
+## Polyfills
+
+### Browser
+
+```ts
+import { getDebugIdForUrl } from "@sentry/debug-ids/browser";
+
+const debugId = await getDebugIdForUrl("https://example.com/main.js");
+```
+
+### Node.js
+
+```ts
+import { getDebugIdForUrl } from "@sentry/debug-ids/node";
+
+const debugId = await getDebugIdForUrl("./path/to/main.js");
+```
+
+## Bundler Plugins
+
 Bundler plugins to inject [Debug
 IDs](https://github.com/tc39/source-map/blob/main/proposals/debug-id.md) into
-both source and source-maps, making build artifacts self-identifying.
+both source and source-maps.
 
-## Rollup
+### Rollup
 
 `rollup.config.mjs`
 ```ts
@@ -21,7 +43,7 @@ export default {
 };
 ```
 
-## webpack
+### webpack
 
 `webpack.config.mjs`
 ```ts
@@ -39,7 +61,7 @@ export default {
 };
 ```
 
-## esbuild
+### esbuild
 
 `build.mjs`
 ```ts
@@ -57,7 +79,7 @@ await esbuild.build({
 });
 ```
 
-## vite
+### vite
 
 `vite.config.mjs`
 ```ts
@@ -74,7 +96,7 @@ export default {
 };
 ```
 
-## rspack
+### rspack
 
 `rspack.config.mjs`
 ```ts
@@ -92,7 +114,7 @@ export default {
 };
 ```
 
-## Rolldown
+### Rolldown
 
 `rolldown.config.mjs`
 ```ts
@@ -109,7 +131,7 @@ export default {
 };
 ```
 
-## Parcel
+### Parcel
 
 `.parcelrc`
 ```json

package.json

@@ -30,6 +30,14 @@
     "parcel": {
       "require": "./dist/cjs/parcel.js",
       "import": "./dist/esm/parcel.js"
+    },
+    "node": {
+      "require": "./dist/cjs/node.js",
+      "import": "./dist/esm/node.js"
+    },
+    "browser": {
+      "require": "./dist/cjs/browser.js",
+      "import": "./dist/esm/browser.js"
     }
   },
   "scripts": {

rollup.config.mjs

@@ -14,23 +14,23 @@ const modulePackageJson = {
   },
 };
 
-function transpileNode(format, input, outDir) {
+function transpile(format, input, outDir, preserveModules = true) {
   return {
     input,
     output: {
       sourcemap: true,
-      strict: false,
       format,
       dir: outDir,
-      preserveModules: true,
+      preserveModules,
     },
     plugins: [typescript({ outDir, tsconfig: './tsconfig.json' }), format === 'esm' ? modulePackageJson : {}],
     external,
   };
 }
 
-const inputs = [
+const nodeInputs = [
   'src/esbuild.ts',
+  'src/node.ts',
   'src/parcel.ts',
   'src/rolldown.ts',
   'src/rollup.ts',
@@ -39,4 +39,9 @@ const inputs = [
   'src/webpack.ts',
 ];
 
-export default [transpileNode('cjs', inputs, 'dist/cjs'), transpileNode('esm', inputs, 'dist/esm')];
+export default [
+  transpile('cjs', nodeInputs, 'dist/cjs'),
+  transpile('esm', nodeInputs, 'dist/esm'),
+  transpile('cjs', ['src/browser.ts'], 'dist/cjs', false),
+  transpile('esm', ['src/browser.ts'], 'dist/esm', false),
+];

src/browser.ts

@@ -0,0 +1,10 @@
+import { getDebugIdFromString } from './common';
+
+export async function getDebugIdForUrl(url: string): Promise<string | undefined> {
+  try {
+    const text = await fetch(url, { cache: 'force-cache' }).then((res) => res.text());
+    return getDebugIdFromString(text);
+  } catch (_) {}
+
+  return;
+}

src/common.ts

@@ -34,3 +34,10 @@ export function addDebugIdToSourcemap(input: string, debugId: string): string {
   sourceMapObj.debugId = debugId;
   return JSON.stringify(sourceMapObj);
 }
+
+const DEBUG_ID_REGEX = /\/\/# debugId=([a-fA-F0-9-]+)(?![\s\S]*\/\/# debugId=)/m;
+
+export function getDebugIdFromString(input: string): string | undefined {
+  const match = input.match(DEBUG_ID_REGEX);
+  return match ? match[1] : undefined;
+}

src/node.ts

@@ -0,0 +1,21 @@
+import * as fs from 'fs/promises';
+import { getDebugIdFromString } from './common';
+
+async function getLastBytesFromFile(path: string, bytesToRead = 1024) {
+  let handle: fs.FileHandle | undefined;
+  try {
+    handle = await fs.open(path, 'r');
+    const { size } = await handle.stat();
+    const position = Math.max(0, size - bytesToRead);
+    const { buffer } = await handle.read(Buffer.alloc(bytesToRead), 0, bytesToRead, position);
+    return buffer;
+  } finally {
+    await handle?.close();
+  }
+}
+
+export async function getDebugIdForUrl(pathOrUrl: string): Promise<string | undefined> {
+  const endOfFile = await getLastBytesFromFile(pathOrUrl);
+  const eofString = endOfFile.toString('utf-8');
+  return getDebugIdFromString(eofString);
+}

test/common/common.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import { addDebugIdToSource } from '../../src/common';
+import { addDebugIdToSource, getDebugIdFromString } from '../../src/common';
 
 describe('common', () => {
   describe('addDebugIdToSource', () => {
@@ -38,20 +38,50 @@ describe('common', () => {
         //# sourceMappingURL=main.js.map"
       `);
     });
+
+    test('adds debugId to source with sourceMapURL and existing debugId', () => {
+      expect(
+        addDebugIdToSource(
+          `console.log('nothing');
+  //# debugId=302a139c-0c62-4af7-bfd3-03d083925e5e
+  //# sourceMappingURL=main.js.map`,
+          '000-000-000-000',
+        ),
+      ).toMatchInlineSnapshot(`
+        "console.log('nothing');
+        //# debugId=000-000-000-000
+        //# sourceMappingURL=main.js.map"
+      `);
+    });
   });
 
-  test('adds debugId to source with sourceMapURL and existing debugId', () => {
-    expect(
-      addDebugIdToSource(
-        `console.log('nothing');
-//# debugId=302a139c-0c62-4af7-bfd3-03d083925e5e
-//# sourceMappingURL=main.js.map`,
-        '000-000-000-000',
-      ),
-    ).toMatchInlineSnapshot(`
-      "console.log('nothing');
-      //# debugId=000-000-000-000
-      //# sourceMappingURL=main.js.map"
-    `);
+  describe('getDebugIdFromString', () => {
+    test('simple', () => {
+      expect(
+        getDebugIdFromString(`
+console.log('here')
+//# debugId=797b2e77-cda7-4d05-b93f-e4df1d24b5f6`),
+      ).toBe('797b2e77-cda7-4d05-b93f-e4df1d24b5f6');
+    });
+
+    test('with sourcemap url', () => {
+      expect(
+        getDebugIdFromString(`
+console.log('here')
+//# debugId=b4b9bc99-7b69-4204-a399-e1899a41fc94
+//# sourceMappingURL=main.js.map`),
+      ).toBe('b4b9bc99-7b69-4204-a399-e1899a41fc94');
+    });
+
+    test('only matches last occurrence', () => {
+      expect(
+        getDebugIdFromString(`
+console.log('here')
+//# debugId=797b2e77-cda7-4d05-b93f-e4df1d24b5f6
+console.log('here')
+//# debugId=b4b9bc99-7b69-4204-a399-e1899a41fc94
+//# sourceMappingURL=main.js.map`),
+      ).toBe('b4b9bc99-7b69-4204-a399-e1899a41fc94');
+    });
   });
 });

test/esbuild/no-sourcemaps/build.mjs

@@ -1,15 +1,15 @@
-import { join } from "path";
-import * as esbuild from "esbuild";
-import debugIds from "../../../dist/esm/esbuild.js";
+import { join } from 'path';
+import * as esbuild from 'esbuild';
+import debugIds from '../../../dist/esm/esbuild.js';
 
-const __dirname = new URL(".", import.meta.url).pathname;
+const __dirname = new URL('.', import.meta.url).pathname;
 
 await esbuild.build({
-  entryPoints: [join(__dirname, "src", "main.js")],
+  entryPoints: [join(__dirname, 'src', 'main.js')],
   bundle: true,
-  format: "esm",
+  format: 'esm',
   minify: true,
   sourcemap: false,
   plugins: [debugIds],
-  outdir: join(__dirname, "dist"),
+  outdir: join(__dirname, 'dist'),
 });

tsconfig.json

@@ -3,7 +3,7 @@
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules"],
   "compilerOptions": {
-    "lib": ["ES2018"],
+    "lib": ["ES2018", "DOM"],
     "module": "ESNext",
     "ignoreDeprecations": "5.0"
   }