@use-worker/node 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Ingram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @use-worker/node
+
+```sh
+node --enable-source-maps --import @use-worker/node/register ./src/main.ts
+```
+
+Requires Node 24 or later. Local ESM source and its Worker view are compiled in
+memory through the packaged native SWC plugin. No application codegen step is
+required. This package installs `@swc/core`; it does not install Vite or Oxc.
+
+The root exports async `register()` and `disposeClients()`. Register before
+loading application modules with dynamic imports. Idle pools allow process exit;
+active calls and iterators retain their Workers. CommonJS and dependency source
+under `node_modules` are outside the transform contract.
+
+The native transform implements a subset: anonymous async arrow/function
+expressions and whole modules of named async function/generator declarations.
+Inline declarations, methods and complete capture validation remain unfinished.
+Use the SWC package's compatibility guidance before adopting it.
+
+Experimental, unpublished `0.0.0` packages.
+
+See the [telemetry guide](../../docs/telemetry.md) for optional `otel: true`,
+Worker setup, and graceful shutdown.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,63 @@
+# Third-party notices
+
+Parts of the scope analysis and function-hoisting approach in
+`src/compiler/closure-scope.ts` and `src/compiler/hoist.ts` are adapted from the official Vite
+React Server Components transform:
+
+https://github.com/vitejs/vite-plugin-react/tree/11ad0af/packages/plugin-rsc/src/transforms
+
+Vite is distributed under the following license:
+
+> MIT License
+>
+> Copyright (c) 2019-present, Yuxi (Evan) You and Vite contributors
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+The directive typo-detection algorithm in `src/compiler/transform.ts` and capture-path
+coalescing in `src/compiler/hoist.ts` are adapted from the Next.js Server Actions
+transform:
+
+https://github.com/vercel/next.js/blob/090f1b72753b2d0094235d27d46ffa0da5fc7d35/crates/next-custom-transforms/src/transforms/server_actions.rs#L3231-L3285
+
+https://github.com/vercel/next.js/blob/090f1b72753b2d0094235d27d46ffa0da5fc7d35/crates/next-custom-transforms/src/transforms/server_actions.rs#L2920-L2966
+
+Next.js is distributed under the following license:
+
+> The MIT License (MIT)
+>
+> Copyright (c) 2025 Vercel, Inc.
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import { type WorkerLike } from "@use-worker/core/internal/client-runtime";
+export * from "@use-worker/core/internal/client-runtime";
+export declare const createWorkerClient: (createWorker: () => WorkerLike, options?: {
+    poolSize?: number;
+    instrumentation?: import("@use-worker/core/internal/instrumentation").Instrumentation;
+    hooks?: import("@use-worker/core/internal/instrumentation").InvocationHooks;
+    gracefulShutdown?: boolean;
+} | undefined) => import("@use-worker/core/internal/client-runtime").WorkerRuntimeClient, disposeClients: () => Promise<void>;
+export declare function createNodeWorker(url: URL, execArgv?: string[]): WorkerLike;

package/dist/client.js

@@ -0,0 +1,8 @@
+import { Worker } from "node:worker_threads";
+import { adaptNodeWorker } from "@use-worker/core/internal/node-client";
+import { createWorkerClientRegistry, } from "@use-worker/core/internal/client-runtime";
+export * from "@use-worker/core/internal/client-runtime";
+export const { createWorkerClient, disposeClients } = createWorkerClientRegistry();
+export function createNodeWorker(url, execArgv = ["--enable-source-maps"]) {
+    return adaptNodeWorker(new Worker(url, { execArgv }));
+}

package/dist/hooks.d.ts

@@ -0,0 +1,7 @@
+export declare const transformCounts: Map<string, number>;
+export interface RegisterOptions {
+    otel?: boolean | "forward";
+    instrumentation?: string;
+    workerSetup?: string;
+}
+export declare function register(options?: RegisterOptions): import("module").ModuleHooks;

package/dist/hooks.js

@@ -0,0 +1,89 @@
+// Node ESM source views are compiled on demand and returned in memory.
+import { existsSync, readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { transformSync } from "@use-worker/swc/compiler";
+import { pluginPath as wasm } from "@use-worker/swc";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+// Per-realm instrumentation for the integration test; not a transform cache.
+export const transformCounts = new Map();
+export function register(options = {}) {
+    return registerHooks({
+        resolve(specifier, context, nextResolve) {
+            try {
+                return nextResolve(specifier, context);
+            }
+            catch (error) {
+                // Match TypeScript's .js source imports, without overriding existing JS
+                // files or changing package resolution.
+                if (!(error instanceof Error) || !("code" in error) ||
+                    error.code !== "ERR_MODULE_NOT_FOUND" ||
+                    !(specifier.startsWith("./") || specifier.startsWith("../")) ||
+                    !context.parentURL)
+                    throw error;
+                const source = new URL(specifier, context.parentURL);
+                if (source.protocol !== "file:" || !source.pathname.endsWith(".js"))
+                    throw error;
+                source.pathname = source.pathname.slice(0, -3) + ".ts";
+                if (!existsSync(source))
+                    throw error;
+                return nextResolve(source.href, context);
+            }
+        },
+        load(url, context, nextLoad) {
+            const source = new URL(url);
+            if (source.protocol !== "file:" || !/\.(?:ts|mts|js|mjs|tsx|jsx)$/.test(source.pathname) ||
+                source.pathname.includes("/node_modules/"))
+                return nextLoad(url, context);
+            if (context.format === "commonjs" || context.format === "commonjs-typescript") {
+                if (readFileSync(source, "utf8").includes("use worker")) {
+                    throw new Error("use-worker Node hooks require an ESM source module");
+                }
+                return nextLoad(url, context);
+            }
+            const mode = source.searchParams.get("use-worker") === "entry" ? "worker" : "main";
+            const encoded = source.searchParams.get("use-worker-options");
+            const telemetry = encoded ? JSON.parse(encoded) : options;
+            const workerSetup = telemetry.workerSetup ? pathToFileURL(resolve(telemetry.workerSetup)).href : undefined;
+            const instrumentation = telemetry.instrumentation ? pathToFileURL(resolve(telemetry.instrumentation)).href : undefined;
+            const workerEntry = new URL(source);
+            workerEntry.searchParams.set("use-worker", "entry");
+            if (telemetry.otel || telemetry.workerSetup || telemetry.instrumentation) {
+                workerEntry.searchParams.set("use-worker-options", JSON.stringify({ ...telemetry,
+                    instrumentation: telemetry.instrumentation ? resolve(telemetry.instrumentation) : undefined,
+                    workerSetup: telemetry.workerSetup ? resolve(telemetry.workerSetup) : undefined }));
+            }
+            const filename = fileURLToPath(source);
+            const result = transformSync(readFileSync(source, "utf8"), {
+                filename,
+                swcrc: false,
+                configFile: false,
+                sourceMaps: "inline",
+                jsc: {
+                    parser: /\.(?:ts|mts|tsx)$/.test(source.pathname)
+                        ? { syntax: "typescript", tsx: source.pathname.endsWith(".tsx") }
+                        : { syntax: "ecmascript", jsx: source.pathname.endsWith(".jsx") },
+                    target: "es2022",
+                    experimental: {
+                        plugins: [[wasm, {
+                                    mode,
+                                    otel: telemetry.otel ?? false, workerSetup, instrumentation,
+                                    // Resolve optional forwarding imports from the application's source module.
+                                    otelRuntime: telemetry.otel === "forward"
+                                        ? mode === "worker" ? "@use-worker/otel/worker" : "@use-worker/otel"
+                                        : import.meta.resolve("@use-worker/core/otel"),
+                                    clientRuntime: new URL("./loader-client.js", import.meta.url).href,
+                                    workerRuntime: import.meta.resolve("@use-worker/core/internal/node-worker"),
+                                    workerEntry: workerEntry.href,
+                                }]],
+                        cacheRoot: join(tmpdir(), "use-worker-swc-cache"),
+                    },
+                },
+                module: { type: "es6" },
+            });
+            transformCounts.set(url, (transformCounts.get(url) ?? 0) + 1);
+            return { format: "module", shortCircuit: true, source: result.code };
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { disposeClients } from "./client.js";
+/** Install source hooks before dynamically importing application modules. */
+export declare function register(options?: import("./hooks.js").RegisterOptions): Promise<import("module").ModuleHooks>;

package/dist/index.js

@@ -0,0 +1,5 @@
+export { disposeClients } from "./client.js";
+/** Install source hooks before dynamically importing application modules. */
+export async function register(options = {}) {
+    return (await import("./hooks.js")).register(options);
+}

package/dist/loader-client.d.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export declare function createNodeWorker(url: URL): import("@use-worker/core/internal/client-runtime").WorkerLike;

package/dist/loader-client.js

@@ -0,0 +1,15 @@
+import { createNodeWorker as createTransport } from "./client.js";
+export * from "./client.js";
+export function createNodeWorker(url) {
+    // Import from a data entry so the worker variant's URL query survives worker
+    // startup. The actual transformed module retains its original file URL.
+    const registration = new URL("./register.js", import.meta.url);
+    const options = url.searchParams.get("use-worker-options");
+    if (options)
+        registration.searchParams.set("use-worker-options", options);
+    const bootstrap = new URL(`data:text/javascript,${encodeURIComponent(`await import(${JSON.stringify(url.href)})`)}`);
+    return createTransport(bootstrap, [
+        "--enable-source-maps",
+        "--import", registration.href,
+    ]);
+}

package/dist/register.d.ts

@@ -0,0 +1 @@
+export { transformCounts } from "./hooks.js";

package/dist/register.js

@@ -0,0 +1,4 @@
+import { register } from "./hooks.js";
+export { transformCounts } from "./hooks.js";
+const options = new URL(import.meta.url).searchParams.get("use-worker-options");
+register(options ? JSON.parse(options) : {});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@use-worker/node",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": "./dist/register.js",
+    "./internal/client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./internal/loader-client": {
+      "types": "./dist/loader-client.d.ts",
+      "default": "./dist/loader-client.js"
+    }
+  },
+  "dependencies": {
+    "@swc/core": "1.16.2",
+    "@use-worker/core": "0.1.0-beta.0",
+    "@use-worker/swc": "0.1.0-beta.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "description": "Node ESM runtime loading for use-worker through native SWC.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}