@nomicfoundation/hardhat-utils 3.0.0-next.0

package/dist/src/request.d.ts

@@ -0,0 +1,118 @@
+import type EventEmitter from "node:events";
+import type UndiciT from "undici";
+export declare const DEFAULT_TIMEOUT_IN_MILLISECONDS = 30000;
+export declare const DEFAULT_MAX_REDIRECTS = 10;
+export declare const DEFAULT_POOL_MAX_CONNECTIONS = 128;
+export declare const DEFAULT_USER_AGENT = "Hardhat";
+export type Dispatcher = UndiciT.Dispatcher;
+export type TestDispatcher = UndiciT.MockAgent;
+export type Interceptable = UndiciT.Interceptable;
+/**
+ * Options to configure the dispatcher.
+ *
+ * @param timeout The timeout in milliseconds. Defaults to {@link DEFAULT_TIMEOUT_IN_MILLISECONDS}.
+ * @param proxy The proxy to use. If not provided, no proxy is used.
+ * @param pool Whether to use a pool dispatcher. Defaults to `false`.
+ * @param maxConnections The maximum number of connections to use in the pool. Defaults to {@link DEFAULT_POOL_MAX_CONNECTIONS}.
+ * @param isTestDispatcher Whether to use a test dispatcher. Defaults to `false`. It's highly recommended to use a test dispatcher in tests to avoid hanging tests.
+ */
+export interface DispatcherOptions {
+    timeout?: number;
+    proxy?: string;
+    pool?: boolean;
+    maxConnections?: number;
+    isTestDispatcher?: boolean;
+}
+/**
+ * Options to configure a request.
+ *
+ * @param queryParams The query parameters to append to the url.
+ * @param extraHeaders Additional headers to include in the request.
+ * @param abortSignal The signal to abort the request.
+ */
+export interface RequestOptions {
+    queryParams?: Record<string, any>;
+    extraHeaders?: Record<string, string>;
+    abortSignal?: AbortSignal | EventEmitter;
+}
+/**
+ * Performs a HTTP request.
+ *
+ * @param url The url to make the request to.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export declare function getRequest(url: string, requestOptions?: RequestOptions, dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions): Promise<UndiciT.Dispatcher.ResponseData>;
+/**
+ * Performs a POST request with a JSON body.
+ *
+ * @param url The url to make the request to.
+ * @param body The body of the request, represented as an object.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export declare function postJsonRequest(url: string, body: unknown, requestOptions?: RequestOptions, dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions): Promise<UndiciT.Dispatcher.ResponseData>;
+/**
+ * Performs a POST request with a form body.
+ *
+ * @param url The url to make the request to.
+ * @param body The body of the request, represented as an object.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export declare function postFormRequest(url: string, body: unknown, requestOptions?: RequestOptions, dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions): Promise<UndiciT.Dispatcher.ResponseData>;
+/**
+ * Downloads a file from a url to a destination path.
+ *
+ * @param url The url to download from.
+ * @param destination The absolute path to save the file to.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws DownloadFailedError If the download fails for any other reason.
+ */
+export declare function download(url: string, destination: string, requestOptions?: RequestOptions, dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions): Promise<void>;
+/**
+ * Creates a dispatcher based on the provided options.
+ * If the `proxy` option is set, it creates a {@link UndiciT.ProxyAgent} dispatcher.
+ * If the `pool` option is set to `true`, it creates a {@link UndiciT.Pool} dispatcher.
+ * Otherwise, it creates a basic {@link UndiciT.Agent} dispatcher.
+ *
+ * @param url The url to make requests to.
+ * @param options The options to configure the dispatcher. See {@link DispatcherOptions}.
+ * @returns The configured dispatcher instance.
+ * @throws DispatcherError If the dispatcher can't be created.
+ */
+export declare function getDispatcher(url: string, { timeout, proxy, pool, maxConnections, isTestDispatcher, }?: DispatcherOptions): Promise<Dispatcher>;
+export declare function getTestDispatcher(options?: {
+    timeout?: number;
+}): Promise<TestDispatcher>;
+/**
+ * Determines whether a proxy should be used for a given url.
+ *
+ * @param url The url to check.
+ * @returns `true` if a proxy should be used for the url, `false` otherwise.
+ */
+export declare function shouldUseProxy(url: string): boolean;
+/**
+ * Determines whether an absolute url is valid.
+ *
+ * @param url The url to check.
+ * @returns `true` if the url is valid, `false` otherwise.
+ */
+export declare function isValidUrl(url: string): boolean;
+export { ConnectionRefusedError, DispatcherError, DownloadError, RequestError, RequestTimeoutError, ResponseStatusCodeError, } from "./errors/request.js";
+//# sourceMappingURL=request.d.ts.map

package/dist/src/request.d.ts.map

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

package/dist/src/request.js

@@ -0,0 +1,208 @@
+import fs from "node:fs";
+import querystring from "node:querystring";
+import stream from "node:stream/promises";
+import { ensureError } from "./error.js";
+import { DownloadError, RequestError, DispatcherError, } from "./errors/request.js";
+import { move } from "./fs.js";
+import { generateTempFilePath, getBaseDispatcherOptions, getBaseRequestOptions, getBasicDispatcher, getPoolDispatcher, getProxyDispatcher, handleError, } from "./internal/request.js";
+export const DEFAULT_TIMEOUT_IN_MILLISECONDS = 30_000;
+export const DEFAULT_MAX_REDIRECTS = 10;
+export const DEFAULT_POOL_MAX_CONNECTIONS = 128;
+export const DEFAULT_USER_AGENT = "Hardhat";
+/**
+ * Performs a HTTP request.
+ *
+ * @param url The url to make the request to.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export async function getRequest(url, requestOptions = {}, dispatcherOrDispatcherOptions) {
+    const { request } = await import("undici");
+    try {
+        const baseRequestOptions = await getBaseRequestOptions(url, requestOptions, dispatcherOrDispatcherOptions);
+        return await request(url, {
+            method: "GET",
+            ...baseRequestOptions,
+        });
+    }
+    catch (e) {
+        ensureError(e);
+        handleError(e, url);
+        throw new RequestError(url, "GET", e);
+    }
+}
+/**
+ * Performs a POST request with a JSON body.
+ *
+ * @param url The url to make the request to.
+ * @param body The body of the request, represented as an object.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export async function postJsonRequest(url, body, requestOptions = {}, dispatcherOrDispatcherOptions) {
+    const { request } = await import("undici");
+    try {
+        const { headers, ...baseRequestOptions } = await getBaseRequestOptions(url, requestOptions, dispatcherOrDispatcherOptions);
+        return await request(url, {
+            method: "POST",
+            ...baseRequestOptions,
+            headers: {
+                ...headers,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        ensureError(e);
+        handleError(e, url);
+        throw new RequestError(url, "POST", e);
+    }
+}
+/**
+ * Performs a POST request with a form body.
+ *
+ * @param url The url to make the request to.
+ * @param body The body of the request, represented as an object.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export async function postFormRequest(url, body, requestOptions = {}, dispatcherOrDispatcherOptions) {
+    const { request } = await import("undici");
+    try {
+        const { headers, ...baseRequestOptions } = await getBaseRequestOptions(url, requestOptions, dispatcherOrDispatcherOptions);
+        return await request(url, {
+            method: "POST",
+            ...baseRequestOptions,
+            headers: {
+                ...headers,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Add a runtime check for body's type
+            body: querystring.stringify(body),
+        });
+    }
+    catch (e) {
+        ensureError(e);
+        handleError(e, url);
+        throw new RequestError(url, "POST", e);
+    }
+}
+/**
+ * Downloads a file from a url to a destination path.
+ *
+ * @param url The url to download from.
+ * @param destination The absolute path to save the file to.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws DownloadFailedError If the download fails for any other reason.
+ */
+export async function download(url, destination, requestOptions = {}, dispatcherOrDispatcherOptions) {
+    let statusCode;
+    try {
+        const response = await getRequest(url, requestOptions, dispatcherOrDispatcherOptions);
+        const { body } = response;
+        statusCode = response.statusCode;
+        if (statusCode < 200 || statusCode >= 300) {
+            throw new Error(await body.text());
+        }
+        const tempFilePath = await generateTempFilePath(destination);
+        const fileStream = fs.createWriteStream(tempFilePath);
+        await stream.pipeline(body, fileStream);
+        await move(tempFilePath, destination);
+    }
+    catch (e) {
+        ensureError(e);
+        handleError(e, url);
+        throw new DownloadError(url, e);
+    }
+}
+/**
+ * Creates a dispatcher based on the provided options.
+ * If the `proxy` option is set, it creates a {@link UndiciT.ProxyAgent} dispatcher.
+ * If the `pool` option is set to `true`, it creates a {@link UndiciT.Pool} dispatcher.
+ * Otherwise, it creates a basic {@link UndiciT.Agent} dispatcher.
+ *
+ * @param url The url to make requests to.
+ * @param options The options to configure the dispatcher. See {@link DispatcherOptions}.
+ * @returns The configured dispatcher instance.
+ * @throws DispatcherError If the dispatcher can't be created.
+ */
+export async function getDispatcher(url, { timeout, proxy, pool, maxConnections, isTestDispatcher, } = {}) {
+    try {
+        if (pool !== undefined && proxy !== undefined) {
+            throw new Error("The pool and proxy options can't be used at the same time");
+        }
+        const baseOptions = getBaseDispatcherOptions(timeout, isTestDispatcher);
+        if (proxy !== undefined) {
+            return await getProxyDispatcher(proxy, baseOptions);
+        }
+        if (pool === true) {
+            return await getPoolDispatcher(url, {
+                ...baseOptions,
+                connections: maxConnections ?? DEFAULT_POOL_MAX_CONNECTIONS,
+            });
+        }
+        return await getBasicDispatcher(baseOptions);
+    }
+    catch (e) {
+        ensureError(e);
+        throw new DispatcherError(e.message, e);
+    }
+}
+export async function getTestDispatcher(options = {}) {
+    const { MockAgent } = await import("undici");
+    const baseOptions = getBaseDispatcherOptions(options.timeout, true);
+    return new MockAgent(baseOptions);
+}
+/**
+ * Determines whether a proxy should be used for a given url.
+ *
+ * @param url The url to check.
+ * @returns `true` if a proxy should be used for the url, `false` otherwise.
+ */
+export function shouldUseProxy(url) {
+    const { hostname } = new URL(url);
+    const noProxy = process.env.NO_PROXY;
+    if (hostname === "localhost" || hostname === "127.0.0.1" || noProxy === "*") {
+        return false;
+    }
+    if (noProxy !== undefined && noProxy !== "") {
+        const noProxySet = new Set(noProxy.split(","));
+        if (noProxySet.has(hostname)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Determines whether an absolute url is valid.
+ *
+ * @param url The url to check.
+ * @returns `true` if the url is valid, `false` otherwise.
+ */
+export function isValidUrl(url) {
+    try {
+        new URL(url);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { ConnectionRefusedError, DispatcherError, DownloadError, RequestError, RequestTimeoutError, ResponseStatusCodeError, } from "./errors/request.js";
+//# sourceMappingURL=request.js.map

package/dist/src/request.js.map

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

package/dist/src/stream.d.ts

@@ -0,0 +1,10 @@
+import { Writable } from "node:stream";
+/**
+ * Creates a Tansform that writes everything to actualWritable, without closing it
+ * when finished.
+ *
+ * This is useful to pipe things to stdout, without closing it, while being
+ * able to await for the result of the pipe to finish.
+ */
+export declare function createNonClosingWriter(actualWritable: Writable): Writable;
+//# sourceMappingURL=stream.d.ts.map

package/dist/src/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,QAAQ,GAAG,QAAQ,CAMzE"}

package/dist/src/stream.js

@@ -0,0 +1,16 @@
+import { Writable } from "node:stream";
+/**
+ * Creates a Tansform that writes everything to actualWritable, without closing it
+ * when finished.
+ *
+ * This is useful to pipe things to stdout, without closing it, while being
+ * able to await for the result of the pipe to finish.
+ */
+export function createNonClosingWriter(actualWritable) {
+    return new Writable({
+        write(chunk, encoding, callback) {
+            actualWritable.write(chunk, encoding, callback);
+        },
+    });
+}
+//# sourceMappingURL=stream.js.map

package/dist/src/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,cAAwB;IAC7D,OAAO,IAAI,QAAQ,CAAC;QAClB,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ;YAC7B,cAAc,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAClD,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/src/string.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Converts a word in singular form to a pluralized string based on the number
+ * of items.
+ *
+ * @param singular The singular form of the word.
+ * @param count The number of items. This determines whether the singular or
+ * plural form is used.
+ * @param plural The optional plural form of the word. If not provided, the
+ * plural form is created by appending an "s" to the singular form.
+ * @returns The pluralized string.
+ */
+export declare function pluralize(singular: string, count: number, plural?: string): string;
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str The string to capitalize.
+ * @returns The string with the first letter capitalized.
+ */
+export declare function capitalize(str: string): string;
+/**
+ * Converts a kebab-case string to camelCase.
+ *
+ * @param str The kebab-case string to convert.
+ * @returns The camelCase string.
+ */
+export declare function kebabToCamelCase(str: string): string;
+/**
+ * Converts a camelCase string to snake_case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The snake_case string.
+ */
+export declare function camelToSnakeCase(str: string): string;
+/**
+ * Converts a camelCase string to kebab-case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The kebab-case string.
+ */
+export declare function camelToKebabCase(str: string): string;
+/**
+ * Ensures a string ends with a slash.
+ */
+export declare function ensureTrailingSlash(path: string): string;
+//# sourceMappingURL=string.d.ts.map

package/dist/src/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAMR;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/src/string.js

@@ -0,0 +1,60 @@
+/**
+ * Converts a word in singular form to a pluralized string based on the number
+ * of items.
+ *
+ * @param singular The singular form of the word.
+ * @param count The number of items. This determines whether the singular or
+ * plural form is used.
+ * @param plural The optional plural form of the word. If not provided, the
+ * plural form is created by appending an "s" to the singular form.
+ * @returns The pluralized string.
+ */
+export function pluralize(singular, count, plural) {
+    if (count === 1) {
+        return singular;
+    }
+    return plural !== undefined ? plural : `${singular}s`;
+}
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str The string to capitalize.
+ * @returns The string with the first letter capitalized.
+ */
+export function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+ * Converts a kebab-case string to camelCase.
+ *
+ * @param str The kebab-case string to convert.
+ * @returns The camelCase string.
+ */
+export function kebabToCamelCase(str) {
+    return str.replace(/-./g, (match) => match.charAt(1).toUpperCase());
+}
+/**
+ * Converts a camelCase string to snake_case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The snake_case string.
+ */
+export function camelToSnakeCase(str) {
+    return str.replace(/[A-Z0-9]/g, (match) => `_${match.toLowerCase()}`);
+}
+/**
+ * Converts a camelCase string to kebab-case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The kebab-case string.
+ */
+export function camelToKebabCase(str) {
+    return str.replace(/[A-Z0-9]/g, (match) => `-${match.toLowerCase()}`);
+}
+/**
+ * Ensures a string ends with a slash.
+ */
+export function ensureTrailingSlash(path) {
+    return path.endsWith("/") ? path : path + "/";
+}
+//# sourceMappingURL=string.js.map

package/dist/src/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../../src/string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CACvB,QAAgB,EAChB,KAAa,EACb,MAAe;IAEf,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;AAChD,CAAC"}

package/dist/src/subprocess.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Spawns a detached subprocess to execute a given file with optional arguments.
+ *
+ * @param absolutePathToSubProcessFile - The absolute path to the subprocess file to be executed.
+ * @param args - Optional list of string arguments to pass to the subprocess.
+ * @param env - Optional environment key-value pairs to pass to the subprocess.
+ *
+ * The subprocess runs in a detached mode and its standard input/output is ignored.
+ * This function does not wait for the subprocess to complete and the subprocess is unreferenced
+ * to allow the parent process to exit independently.
+ */
+export declare function spawnDetachedSubProcess(absolutePathToSubProcessFile: string, args?: string[], env?: Record<string, string>): Promise<void>;
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/src/subprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/subprocess.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,4BAA4B,EAAE,MAAM,EACpC,IAAI,GAAE,MAAM,EAAO,EACnB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC/B,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/src/subprocess.js

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+import { SubprocessFileNotFoundError, SubprocessPathIsDirectoryError, } from "./errors/subprocess.js";
+import { exists, isDirectory } from "./fs.js";
+/**
+ * Spawns a detached subprocess to execute a given file with optional arguments.
+ *
+ * @param absolutePathToSubProcessFile - The absolute path to the subprocess file to be executed.
+ * @param args - Optional list of string arguments to pass to the subprocess.
+ * @param env - Optional environment key-value pairs to pass to the subprocess.
+ *
+ * The subprocess runs in a detached mode and its standard input/output is ignored.
+ * This function does not wait for the subprocess to complete and the subprocess is unreferenced
+ * to allow the parent process to exit independently.
+ */
+export async function spawnDetachedSubProcess(absolutePathToSubProcessFile, args = [], env = {}) {
+    if ((await exists(absolutePathToSubProcessFile)) === false) {
+        throw new SubprocessFileNotFoundError(absolutePathToSubProcessFile);
+    }
+    if ((await isDirectory(absolutePathToSubProcessFile)) === true) {
+        throw new SubprocessPathIsDirectoryError(absolutePathToSubProcessFile);
+    }
+    const subprocessArgs = [absolutePathToSubProcessFile, ...args];
+    if (absolutePathToSubProcessFile.endsWith(".ts")) {
+        subprocessArgs.unshift("--import", "tsx/esm");
+    }
+    const subprocess = spawn(process.execPath, subprocessArgs, {
+        detached: true,
+        env,
+        stdio: "ignore",
+    });
+    subprocess.unref();
+}
+//# sourceMappingURL=subprocess.js.map

package/dist/src/subprocess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.js","sourceRoot":"","sources":["../../src/subprocess.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,4BAAoC,EACpC,OAAiB,EAAE,EACnB,MAA8B,EAAE;IAEhC,IAAI,CAAC,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;QAC3D,MAAM,IAAI,2BAA2B,CAAC,4BAA4B,CAAC,CAAC;IACtE,CAAC;IAED,IAAI,CAAC,MAAM,WAAW,CAAC,4BAA4B,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/D,MAAM,IAAI,8BAA8B,CAAC,4BAA4B,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,cAAc,GAAG,CAAC,4BAA4B,EAAE,GAAG,IAAI,CAAC,CAAC;IAE/D,IAAI,4BAA4B,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE;QACzD,QAAQ,EAAE,IAAI;QACd,GAAG;QACH,KAAK,EAAE,QAAQ;KAChB,CAAC,CAAC;IAEH,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}

package/dist/src/synchronization.d.ts

@@ -0,0 +1,6 @@
+export declare class MultiProcessMutex {
+    #private;
+    constructor(mutexName: string, maxMutexLifespanInMs?: number);
+    use<T>(f: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=synchronization.d.ts.map

package/dist/src/synchronization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synchronization.d.ts","sourceRoot":"","sources":["../../src/synchronization.ts"],"names":[],"mappings":"AAuBA,qBAAa,iBAAiB;;gBAIhB,SAAS,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM;IAQ/C,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CA0FrD"}