@veryfront/ext-bundler-esbuild 0.1.1046 → 0.1.1048

package/README.md

@@ -43,3 +43,14 @@ No factory options. The extension reads no environment variables and takes no co
 ## Lifecycle
 
 The factory's `teardown()` calls `EsbuildBundler.stop()` to release the esbuild service on shutdown.
+
+All `EsbuildBundler` instances in a process share one module-level esbuild service and shutdown
+barrier. Await `stop()` after bundler work, and dispose build contexts before stopping the service.
+
+Use the Veryfront `Bundler` contract exclusively for asynchronous esbuild work. Starting the same
+raw `esbuild` module outside this adapter makes its child process impossible to track retroactively.
+The adapter rejects that mixed-ownership state and requires a process restart instead of reporting
+an unverified shutdown as successful.
+
+The service-child tracking matches the esbuild `0.28.1` process contract. Revalidate spawn capture,
+plugin disposal ordering, and child-close tests before changing that version.

package/esm/_dnt.polyfills.js

@@ -56,7 +56,7 @@ export let import_meta_ponyfill_esmodule = (Reflect.get(globalThis, Symbol.for("
         const resolveFunStr = String(importMeta.resolve);
         const shimWs = new WeakSet();
         //@ts-ignore
-        const mainUrl = ("file:///" + process.argv[1].replace(/\\/g, "/"))
+        const mainUrl = ("file:///" + (process.argv[1] ?? "").replace(/\\/g, "/"))
             .replace(/\/{3,}/, "///");
         const commonShim = (importMeta) => {
             if (typeof importMeta.main !== "boolean") {

package/esm/esbuild-bundler.d.ts

@@ -1,16 +1,10 @@
+import type { BuildContext, BundleOptions, Bundler, BundleResult, TransformOptions, TransformResult } from "veryfront/extensions/bundler";
 /**
- * esbuild-backed implementation of the {@link Bundler} contract.
- *
- * Lazy-initializes the esbuild binary (including `deno compile` VFS
- * extraction) on first use. All options pass through to esbuild unchanged
- * because the {@link BundleOptions} shape was designed to be esbuild-compatible;
- * the only translation is converting {@link BundlerPlugin}s into esbuild
- * plugins via {@link toEsbuildPlugin}.
+ * esbuild-backed {@link Bundler} implementation.
  *
- * @module extensions/ext-bundler-esbuild/esbuild-bundler
+ * Every instance coordinates through one module-wide service lifecycle. Raw
+ * asynchronous esbuild calls must not share the same module in this process.
  */
-import type { BuildContext, BundleOptions, Bundler, BundleResult, TransformOptions, TransformResult } from "veryfront/extensions/bundler";
-/** esbuild-backed {@link Bundler} implementation. */
 export declare class EsbuildBundler implements Bundler {
     bundle(options: BundleOptions): Promise<BundleResult>;
     transform(options: TransformOptions): Promise<TransformResult>;

package/esm/esbuild-bundler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"esbuild-bundler.d.ts","sourceRoot":"","sources":["../src/esbuild-bundler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAEb,OAAO,EACP,YAAY,EAGZ,gBAAgB,EAChB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAoDtC,qDAAqD;AACrD,qBAAa,cAAe,YAAW,OAAO;IACtC,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAWrD,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAW9D,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiBtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAM5B"}
+{"version":3,"file":"esbuild-bundler.d.ts","sourceRoot":"","sources":["../src/esbuild-bundler.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAEb,OAAO,EACP,YAAY,EAGZ,gBAAgB,EAChB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAwTtC;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,OAAO;IACtC,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAkBrD,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAa9D,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiCtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAiF5B"}

package/esm/esbuild-bundler.js

@@ -9,9 +9,28 @@
  *
  * @module extensions/ext-bundler-esbuild/esbuild-bundler
  */
+import * as dntShim from "./_dnt.shims.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createRequire } from "node:module";
 import { ensureEsbuildBinary } from "./binary.js";
 import { toEsbuildPlugin } from "./plugin-adapter.js";
+const ESBUILD_STOP_TIMEOUT_MS = 5_000;
+const childProcess = createRequire(globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url)("node:child_process");
 let esbuildModule = null;
+let esbuildService = null;
+let esbuildOwnershipError = null;
+let esbuildShutdownError = null;
+let pluginDisposalError = null;
+let esbuildStopPromise = null;
+let activeOperationCount = 0;
+let activeOperationsIdle = Promise.resolve();
+let resolveActiveOperationsIdle = null;
+const operationScopes = new AsyncLocalStorage();
+function recordOwnershipError(cause) {
+    const message = "[ext-bundler-esbuild] Cannot own an esbuild service started outside the module-wide adapter; restart the process and use only the Bundler contract";
+    esbuildOwnershipError ??= new Error(message, cause === undefined ? undefined : { cause });
+    return esbuildOwnershipError;
+}
 async function getEsbuild() {
     await ensureEsbuildBinary();
     if (esbuildModule)
@@ -19,6 +38,193 @@ async function getEsbuild() {
     esbuildModule = await import("esbuild");
     return esbuildModule;
 }
+function beginOperation() {
+    if (activeOperationCount === 0) {
+        activeOperationsIdle = new Promise((resolve) => {
+            resolveActiveOperationsIdle = resolve;
+        });
+    }
+    activeOperationCount += 1;
+}
+function endOperation() {
+    activeOperationCount -= 1;
+    if (activeOperationCount !== 0)
+        return;
+    const resolve = resolveActiveOperationsIdle;
+    resolveActiveOperationsIdle = null;
+    activeOperationsIdle = Promise.resolve();
+    resolve?.();
+}
+function createPluginDisposalBarrier(scope) {
+    const callbacks = [];
+    let activated = false;
+    let holdingOperation = false;
+    const releaseIfSettled = () => {
+        if (!holdingOperation || callbacks.some((callback) => !callback.settled))
+            return;
+        holdingOperation = false;
+        scope.activeCount -= 1;
+        endOperation();
+    };
+    const settle = (callback) => {
+        if (callback.settled)
+            return;
+        callback.settled = true;
+        releaseIfSettled();
+    };
+    const fail = (callback, error) => {
+        if (!pluginDisposalError) {
+            pluginDisposalError = new Error("[ext-bundler-esbuild] Plugin disposal failed", { cause: error });
+        }
+        settle(callback);
+    };
+    return {
+        wrap(callback) {
+            const state = { started: false, settled: false };
+            callbacks.push(state);
+            return () => {
+                if (state.settled)
+                    return;
+                state.started = true;
+                try {
+                    const result = callback();
+                    if (result !== null &&
+                        (typeof result === "object" || typeof result === "function") &&
+                        typeof result.then === "function") {
+                        void Promise.resolve(result).then(() => settle(state), (error) => fail(state, error));
+                    }
+                    else {
+                        settle(state);
+                    }
+                }
+                catch (error) {
+                    fail(state, error);
+                }
+            };
+        },
+        activate() {
+            if (activated)
+                return;
+            activated = true;
+            if (callbacks.length === 0 || callbacks.every((callback) => callback.settled))
+                return;
+            holdingOperation = true;
+            beginOperation();
+            scope.activeCount += 1;
+            // esbuild 0.28 schedules disposal callbacks with zero-delay timers
+            // before settling build/dispose. Queueing a sentinel after settlement
+            // identifies callbacks that setup failures left unscheduled. Callbacks
+            // that started async cleanup retain the operation until they settle.
+            dntShim.setTimeout(() => {
+                for (const callback of callbacks) {
+                    if (!callback.started)
+                        settle(callback);
+                }
+                releaseIfSettled();
+            }, 0);
+        },
+    };
+}
+async function runBundlerOperation(operation, preferredScope) {
+    if (esbuildOwnershipError)
+        throw esbuildOwnershipError;
+    if (esbuildShutdownError)
+        throw esbuildShutdownError;
+    const inheritedScope = operationScopes.getStore();
+    const isReentrant = inheritedScope !== undefined && inheritedScope.activeCount > 0;
+    if (!isReentrant) {
+        while (esbuildStopPromise)
+            await esbuildStopPromise;
+    }
+    // Admission is synchronous after the stop barrier check. This makes a stop
+    // exclusive without serializing independent operations. Work re-entered by
+    // an active plugin shares its live scope so shutdown cannot deadlock on it.
+    const scope = preferredScope ?? (isReentrant ? inheritedScope : { activeCount: 0 });
+    beginOperation();
+    scope.activeCount += 1;
+    try {
+        return await operationScopes.run(scope, () => operation(scope));
+    }
+    finally {
+        scope.activeCount -= 1;
+        endOperation();
+    }
+}
+function isEsbuildServiceSpawn(spawnArgs) {
+    const args = spawnArgs[1];
+    return Array.isArray(args) &&
+        args.some((arg) => typeof arg === "string" && arg.startsWith("--service=")) &&
+        args.includes("--ping");
+}
+function isLiveService(service) {
+    return !service.child.killed &&
+        service.child.exitCode === null &&
+        service.child.signalCode === null;
+}
+function invokeEsbuild(operation) {
+    const originalSpawn = childProcess.spawn;
+    let capturedService = null;
+    let result;
+    // esbuild does not expose its service child, and stop() resolves before that
+    // child closes. esbuild 0.28 starts it synchronously with --service and
+    // --ping, so keep interception to this operation and restore the shared
+    // binding with compare-and-swap.
+    const trackedSpawn = ((...spawnArgs) => {
+        const child = Reflect.apply(originalSpawn, childProcess, spawnArgs);
+        if (isEsbuildServiceSpawn(spawnArgs)) {
+            let resolveClosed = () => { };
+            const closed = new Promise((resolve) => {
+                resolveClosed = resolve;
+            });
+            const service = { child, closed, expectedClose: false };
+            child.once("close", () => {
+                if (!service.expectedClose)
+                    recordOwnershipError();
+                resolveClosed();
+                if (esbuildService === service)
+                    esbuildService = null;
+            });
+            capturedService = service;
+            esbuildService = service;
+            if (childProcess.spawn === trackedSpawn)
+                childProcess.spawn = originalSpawn;
+        }
+        return child;
+    });
+    childProcess.spawn = trackedSpawn;
+    try {
+        result = operation();
+    }
+    finally {
+        if (childProcess.spawn === trackedSpawn)
+            childProcess.spawn = originalSpawn;
+    }
+    const ownedService = capturedService ?? esbuildService;
+    if (!ownedService || !isLiveService(ownedService)) {
+        const ownershipError = recordOwnershipError();
+        return result.then(() => {
+            throw ownershipError;
+        }, (cause) => {
+            throw recordOwnershipError(cause);
+        });
+    }
+    return result;
+}
+async function waitForServiceClose(service) {
+    let timeoutId;
+    const timeout = new Promise((_resolve, reject) => {
+        timeoutId = dntShim.setTimeout(() => {
+            reject(new Error(`[ext-bundler-esbuild] Timed out after ${ESBUILD_STOP_TIMEOUT_MS}ms waiting for the esbuild service to close`));
+        }, ESBUILD_STOP_TIMEOUT_MS);
+    });
+    try {
+        await Promise.race([service.closed, timeout]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}
 // deno-lint-ignore no-explicit-any
 function toMessage(m) {
     return {
@@ -42,57 +248,162 @@ function toOutput(f) {
         hash: f.hash,
     };
 }
-function mapOptions(options) {
+function mapOptions(options, scope) {
     const { plugins, ...rest } = options;
     const mapped = { ...rest };
+    const pluginDisposals = createPluginDisposalBarrier(scope);
     if (plugins && plugins.length > 0) {
-        mapped.plugins = plugins.map(toEsbuildPlugin);
+        const runInOperationScope = (callback) => operationScopes.run(scope, callback);
+        mapped.plugins = plugins.map((plugin) => toEsbuildPlugin(plugin, runInOperationScope, pluginDisposals.wrap));
     }
-    return mapped;
+    return {
+        options: mapped,
+        activatePluginDisposals: pluginDisposals.activate,
+    };
 }
-/** esbuild-backed {@link Bundler} implementation. */
+/**
+ * esbuild-backed {@link Bundler} implementation.
+ *
+ * Every instance coordinates through one module-wide service lifecycle. Raw
+ * asynchronous esbuild calls must not share the same module in this process.
+ */
 export class EsbuildBundler {
     async bundle(options) {
-        const esbuild = await getEsbuild();
-        const result = await esbuild.build(mapOptions(options));
-        return {
-            outputFiles: (result.outputFiles ?? []).map(toOutput),
-            warnings: toMessages(result.warnings),
-            errors: toMessages(result.errors),
-            metafile: result.metafile,
-        };
-    }
-    async transform(options) {
-        const esbuild = await getEsbuild();
-        const { code, ...rest } = options;
-        const result = await esbuild.transform(code, rest);
-        return {
-            code: result.code,
-            map: result.map,
-            warnings: toMessages(result.warnings).map((m) => m.text),
-        };
-    }
-    async context(options) {
-        const esbuild = await getEsbuild();
-        const ctx = await esbuild.context(mapOptions(options));
-        return {
-            rebuild: async () => {
-                const result = await ctx.rebuild();
+        return runBundlerOperation(async (scope) => {
+            const esbuild = await getEsbuild();
+            const mapped = mapOptions(options, scope);
+            try {
+                const result = await invokeEsbuild(() => esbuild.build(mapped.options));
                 return {
                     outputFiles: (result.outputFiles ?? []).map(toOutput),
                     warnings: toMessages(result.warnings),
                     errors: toMessages(result.errors),
                     metafile: result.metafile,
                 };
-            },
-            dispose: () => ctx.dispose(),
-        };
+            }
+            finally {
+                mapped.activatePluginDisposals();
+            }
+        });
+    }
+    async transform(options) {
+        return runBundlerOperation(async () => {
+            const esbuild = await getEsbuild();
+            const { code, ...rest } = options;
+            const result = await invokeEsbuild(() => esbuild.transform(code, rest));
+            return {
+                code: result.code,
+                map: result.map,
+                warnings: toMessages(result.warnings).map((m) => m.text),
+            };
+        });
+    }
+    async context(options) {
+        return runBundlerOperation(async (contextScope) => {
+            const esbuild = await getEsbuild();
+            const mapped = mapOptions(options, contextScope);
+            const ctx = await invokeEsbuild(() => esbuild.context(mapped.options)).catch((error) => {
+                mapped.activatePluginDisposals();
+                throw error;
+            });
+            return {
+                rebuild: () => runBundlerOperation(async () => {
+                    const result = await ctx.rebuild();
+                    return {
+                        outputFiles: (result.outputFiles ?? []).map(toOutput),
+                        warnings: toMessages(result.warnings),
+                        errors: toMessages(result.errors),
+                        metafile: result.metafile,
+                    };
+                }, contextScope),
+                dispose: () => runBundlerOperation(async () => {
+                    try {
+                        await ctx.dispose();
+                    }
+                    finally {
+                        mapped.activatePluginDisposals();
+                    }
+                }, contextScope),
+            };
+        });
     }
     async stop() {
-        const m = esbuildModule;
-        if (!m)
+        if ((operationScopes.getStore()?.activeCount ?? 0) > 0) {
+            throw new Error("[ext-bundler-esbuild] Cannot stop the esbuild service from an active bundler operation");
+        }
+        if (esbuildStopPromise) {
+            await esbuildStopPromise;
             return;
-        esbuildModule = null;
-        await m.stop();
+        }
+        const stopping = (async () => {
+            await activeOperationsIdle;
+            const m = esbuildModule;
+            const trackedService = esbuildService;
+            if (trackedService && !trackedService.expectedClose && !isLiveService(trackedService)) {
+                recordOwnershipError();
+            }
+            const ownershipError = esbuildOwnershipError;
+            const disposalError = pluginDisposalError;
+            if (!m) {
+                if (ownershipError)
+                    throw ownershipError;
+                if (esbuildShutdownError)
+                    throw esbuildShutdownError;
+                if (disposalError) {
+                    pluginDisposalError = null;
+                    throw disposalError;
+                }
+                return;
+            }
+            const service = esbuildService ?? trackedService;
+            if (service) {
+                service.expectedClose = true;
+                service.child.ref();
+            }
+            try {
+                await m.stop();
+                if (service)
+                    await waitForServiceClose(service);
+            }
+            catch (error) {
+                const shutdownError = error instanceof Error
+                    ? error
+                    : new Error("[ext-bundler-esbuild] Failed to stop the esbuild service", {
+                        cause: error,
+                    });
+                esbuildShutdownError = shutdownError;
+                if (service) {
+                    void service.closed.then(() => {
+                        if (esbuildShutdownError === shutdownError)
+                            esbuildShutdownError = null;
+                    });
+                }
+                throw shutdownError;
+            }
+            finally {
+                service?.child.unref();
+            }
+            if (ownershipError) {
+                throw new Error("[ext-bundler-esbuild] Cannot verify closure of an externally owned esbuild service; restart the process", { cause: ownershipError });
+            }
+            if (esbuildModule === m)
+                esbuildModule = null;
+            if (esbuildService === service)
+                esbuildService = null;
+            esbuildShutdownError = null;
+            if (disposalError) {
+                if (pluginDisposalError === disposalError)
+                    pluginDisposalError = null;
+                throw disposalError;
+            }
+        })();
+        esbuildStopPromise = stopping;
+        try {
+            await stopping;
+        }
+        finally {
+            if (Object.is(esbuildStopPromise, stopping))
+                esbuildStopPromise = null;
+        }
     }
 }

package/esm/plugin-adapter.d.ts

@@ -9,6 +9,8 @@
  */
 import type { BundlerPlugin } from "veryfront/extensions/bundler";
 type EsbuildPlugin = any;
-export declare function toEsbuildPlugin(plugin: BundlerPlugin): EsbuildPlugin;
+type PluginContextRunner = <T>(callback: () => T) => T;
+type PluginDisposeWrapper = (callback: () => unknown) => () => void;
+export declare function toEsbuildPlugin(plugin: BundlerPlugin, runInContext: PluginContextRunner, wrapDispose: PluginDisposeWrapper): EsbuildPlugin;
 export {};
 //# sourceMappingURL=plugin-adapter.d.ts.map

package/esm/plugin-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-adapter.d.ts","sourceRoot":"","sources":["../src/plugin-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,aAAa,EAMd,MAAM,8BAA8B,CAAC;AAEtC,KAAK,aAAa,GAAG,GAAG,CAAC;AAEzB,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CA4CpE"}
+{"version":3,"file":"plugin-adapter.d.ts","sourceRoot":"","sources":["../src/plugin-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,aAAa,EAMd,MAAM,8BAA8B,CAAC;AAEtC,KAAK,aAAa,GAAG,GAAG,CAAC;AAEzB,KAAK,mBAAmB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,CAAC,QAAQ,EAAE,MAAM,OAAO,KAAK,MAAM,IAAI,CAAC;AAEpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,mBAAmB,EACjC,WAAW,EAAE,oBAAoB,GAChC,aAAa,CA8Cf"}

package/esm/plugin-adapter.js

@@ -7,7 +7,7 @@
  *
  * @module extensions/ext-bundler-esbuild/plugin-adapter
  */
-export function toEsbuildPlugin(plugin) {
+export function toEsbuildPlugin(plugin, runInContext, wrapDispose) {
     return {
         name: plugin.name,
         // deno-lint-ignore no-explicit-any
@@ -15,7 +15,7 @@ export function toEsbuildPlugin(plugin) {
             const bridged = {
                 onResolve(options, callback) {
                     // deno-lint-ignore no-explicit-any
-                    build.onResolve(options, async (args) => {
+                    build.onResolve(options, (args) => runInContext(async () => {
                         const resolveArgs = {
                             path: args.path,
                             importer: args.importer,
@@ -28,11 +28,11 @@ export function toEsbuildPlugin(plugin) {
                         if (result == null)
                             return result ?? null;
                         return result;
-                    });
+                    }));
                 },
                 onLoad(options, callback) {
                     // deno-lint-ignore no-explicit-any
-                    build.onLoad(options, async (args) => {
+                    build.onLoad(options, (args) => runInContext(async () => {
                         const loadArgs = {
                             path: args.path,
                             namespace: args.namespace,
@@ -43,13 +43,13 @@ export function toEsbuildPlugin(plugin) {
                         if (result == null)
                             return result ?? null;
                         return result;
-                    });
+                    }));
                 },
                 onDispose(callback) {
-                    build.onDispose(callback);
+                    build.onDispose(wrapDispose(() => runInContext(callback)));
                 },
             };
-            plugin.setup(bridged);
+            return runInContext(() => plugin.setup(bridged));
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veryfront/ext-bundler-esbuild",
-  "version": "0.1.1046",
+  "version": "0.1.1048",
   "description": "Veryfront first-party extension package for ext-bundler-esbuild",
   "keywords": [
     "veryfront",
@@ -50,7 +50,7 @@
     "esbuild": "0.28.1"
   },
   "peerDependencies": {
-    "veryfront": "^0.1.1046"
+    "veryfront": "^0.1.1048"
   },
   "type": "module",
   "types": "./esm/index.d.ts",