bun-workspaces 1.0.0-alpha.21 → 1.0.0-alpha.23

package/README.md

@@ -1,15 +1,25 @@
 <img src="./packages/doc-website/src/docs/public/bw-eye.png" alt="bun-workspaces" width="50" />
 
+### [📖 **See Full Documentation Here**: _https://bunworkspaces.com_](https://bunworkspaces.com)
+
 # bun-workspaces
 
-### [**See Full Documentation Here:** _https://bunworkspaces.com_](https://bunworkspaces.com)
+A CLI and API to enhance your monorepo development with Bun's [native workspaces](https://bun.sh/docs/install/workspaces) feature for nested JavaScript/TypeScript packages.
+
+- Works right away, with no boilerplate required 🍔🍴
+- Get metadata about your monorepo 🤖
+- Run package.json scripts across workspaces 📋
+- Supports running inline scripts as well ⌨️
 
-**_New: [An API is now officially released!](https://bunworkspaces.com/api)_**
+This tool lets you decide the complexity of how you use it.
+To get started, all you need is a normal project using [Bun's native workspaces](https://bun.sh/docs/install/workspaces) feature for nested JavaScript/TypeScript packages.
 
-This is a CLI and API that help you manage your monorepo on top of native [Bun workspaces](https://bun.sh/docs/install/workspaces), with no additional setup required. Get metadata about your workspaces and scripts, and run scripts across your workspaces.
+Think of this as a power suit you can snap onto native workspaces, rather than another monorepo framework.
 
+Start running some [CLI commands](https://bunworkspaces.com/cli) right away in your repo, or take full advantage of the [scripting API](https://bunworkspaces.com/api) and its features.
+<br/><br/>
 <a href="https://buymeacoffee.com/scottmorse">
-<img src="./packages/doc-website/src/docs/public/bmac-logo-circle.png" alt="Link to Buy Me A Coffee" width="60" />
+<img src="./packages/doc-website/src/docs/public/bmac-logo-circle.png" alt="Link to Buy Me A Coffee" width="50" />
 </a>
 
 ## Quick Start
@@ -37,7 +47,7 @@ bw list-workspaces
 bw ls --json --pretty # Output as formatted JSON
 
 # Run the lint script for all workspaces
-# that have it in their "scripts" field
+# that have it in their package.json "scripts" field
 bw run-script lint
 
 # run is an alias for run-script
@@ -47,14 +57,15 @@ bw run lint "my-workspace-*" # Run for matching workspace names
 bw run lint --parallel # Run at the same time
 bw run lint --args="--my-appended-args" # Add args to each script call
 bw run lint --args="--my-arg=<workspaceName>" # Use the workspace name in args
-
-# Run an inline command from the workspace directory
-bw run "echo 'this is my inline script for <workspaceName>'" --inline
+bw run "bun build" --inline --inline-name=build # Run an inline command
 
 # Show usage (you can pass --help to any command)
 bw help
 bw --help
 
+# Show version
+bw --version
+
 # Pass --cwd to any command
 bw --cwd=/path/to/your/project ls
 bw --cwd=/path/to/your/project run my-script
@@ -93,10 +104,11 @@ const runSingleScript = async () => {
   });
 
   // Get a stream of the script subprocess's output
-  for await (const { text, textNoAnsi, streamName } of output) {
-    console.log(text); // The output chunk's content (string)
-    console.log(textNoAnsi); // Text with ANSI codes sanitized (string)
-    console.log(streamName); // The output stream, "stdout" or "stderr"
+  for await (const chunk of output) {
+    console.log(chunk.raw); // The raw output content (Uint8Array)
+    console.log(chunk.decode()); // The output chunk's content (string)
+    console.log(chunk.decode({ stripAnsi: true })); // Text with ANSI codes sanitized
+    console.log(chunk.streamName); // The output stream, "stdout" or "stderr"
   }
 
   // Get data about the script execution after it exits
@@ -122,8 +134,9 @@ const runManyScripts = async () => {
 
   // Get a stream of script output
   for await (const { outputChunk, scriptMetadata } of output) {
-    console.log(outputChunk.text); // the output chunk's content (string)
-    console.log(outputChunk.textNoAnsi); // text with ANSI codes sanitized (string)
+    console.log(outputChunk.raw); // The raw output content (Uint8Array)
+    console.log(outputChunk.decode()); // the output chunk's content (string)
+    console.log(outputChunk.decode({ stripAnsi: true })); // text with ANSI codes sanitized (string)
     console.log(outputChunk.streamName); // "stdout" or "stderr"
 
     // The metadata can distinguish which workspace script
@@ -155,4 +168,4 @@ const runManyScripts = async () => {
 };
 ```
 
-_`bun-workspaces` is independent from the [Bun](https://bun.sh) project and is not affiliated with or endorsed by Oven. This project aims to enhance enhance the experience of Bun for its users._
+_`bun-workspaces` is independent from the [Bun](https://bun.sh) project and is not affiliated with or endorsed by Anthropic. This project aims to enhance enhance the experience of Bun for its users._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.23",
   "license": "MIT",
   "main": "src/index.mjs",
   "types": "src/index.d.ts",
@@ -15,7 +15,7 @@
   },
   "custom": {
     "bunVersion": {
-      "build": "1.3.1",
+      "build": "1.3.4",
       "libraryConsumer": "^1.1.x"
     }
   },

package/src/cli/projectCommands/handleRunScript.mjs

@@ -64,16 +64,34 @@ const runScript = handleCommand(
     const { output, summary } = project.runScriptAcrossWorkspaces({
       workspacePatterns: workspaces.map(({ name }) => name),
       script,
-      inline: options.inline,
+      inline: options.inline
+        ? options.inlineName
+          ? {
+              scriptName: options.inlineName,
+            }
+          : true
+        : undefined,
       args: options.args,
-      parallel: !!options.parallel,
+      parallel:
+        typeof options.parallel === "boolean" ||
+        typeof options.parallel === "undefined"
+          ? options.parallel
+          : options.parallel === "true"
+            ? true
+            : options.parallel === "false"
+              ? false
+              : {
+                  max: options.parallel,
+                },
     });
-    const scriptName = options.inline ? "(inline)" : script;
+    const scriptName = options.inline
+      ? options.inlineName || "(inline)"
+      : script;
     const handleOutput = async () => {
       if (logger.printLevel === "silent") return;
       for await (const { outputChunk, scriptMetadata } of output) {
         commandOutputLogger.logOutput(
-          outputChunk.text,
+          outputChunk.decode(),
           "info",
           process[outputChunk.streamName],
           options.prefix

package/src/cli/projectCommands/projectCommandsConfig.d.ts

@@ -90,8 +90,8 @@ declare const CLI_PROJECT_COMMANDS_CONFIG: {
     readonly description: 'Run a script in all workspaces that have it in their "scripts" field in package.json';
     readonly options: {
       readonly parallel: {
-        readonly flags: "--parallel";
-        readonly description: "Run the scripts in parallel";
+        readonly flags: "--parallel [max]";
+        readonly description: "Run the scripts in parallel. Pass an optional number, percentage, or keyword: 'default', 'auto', 'unbounded'";
       };
       readonly args: {
         readonly flags: "--args <args>";
@@ -105,6 +105,10 @@ declare const CLI_PROJECT_COMMANDS_CONFIG: {
         readonly flags: "--inline";
         readonly description: "Run the script as an inline command from the workspace directory";
       };
+      readonly inlineName: {
+        readonly flags: "--inline-name <name>";
+        readonly description: "An optional name for the script when --inline is passed";
+      };
       readonly jsonOutfile: {
         readonly flags: "--json-outfile <file>";
         readonly description: "Output results in a JSON file";
@@ -193,8 +197,8 @@ export declare const getProjectCommandConfig: (
       readonly description: 'Run a script in all workspaces that have it in their "scripts" field in package.json';
       readonly options: {
         readonly parallel: {
-          readonly flags: "--parallel";
-          readonly description: "Run the scripts in parallel";
+          readonly flags: "--parallel [max]";
+          readonly description: "Run the scripts in parallel. Pass an optional number, percentage, or keyword: 'default', 'auto', 'unbounded'";
         };
         readonly args: {
           readonly flags: "--args <args>";
@@ -208,6 +212,10 @@ export declare const getProjectCommandConfig: (
           readonly flags: "--inline";
           readonly description: "Run the script as an inline command from the workspace directory";
         };
+        readonly inlineName: {
+          readonly flags: "--inline-name <name>";
+          readonly description: "An optional name for the script when --inline is passed";
+        };
         readonly jsonOutfile: {
           readonly flags: "--json-outfile <file>";
           readonly description: "Output results in a JSON file";

package/src/cli/projectCommands/projectCommandsConfig.mjs

@@ -79,8 +79,9 @@ const CLI_PROJECT_COMMANDS_CONFIG = {
       'Run a script in all workspaces that have it in their "scripts" field in package.json',
     options: {
       parallel: {
-        flags: "--parallel",
-        description: "Run the scripts in parallel",
+        flags: "--parallel [max]",
+        description:
+          "Run the scripts in parallel. Pass an optional number, percentage, or keyword: 'default', 'auto', 'unbounded'",
       },
       args: {
         flags: "--args <args>",
@@ -95,6 +96,10 @@ const CLI_PROJECT_COMMANDS_CONFIG = {
         description:
           "Run the script as an inline command from the workspace directory",
       },
+      inlineName: {
+        flags: "--inline-name <name>",
+        description: "An optional name for the script when --inline is passed",
+      },
       jsonOutfile: {
         flags: "--json-outfile <file>",
         description: "Output results in a JSON file",

package/src/config/userEnvVars.d.ts

@@ -0,0 +1,8 @@
+export declare const USER_ENV_VARS: {
+  readonly parallelMaxDefault: "BW_PARALLEL_MAX_DEFAULT";
+};
+export type UserEnvVarName = keyof typeof USER_ENV_VARS;
+export declare const getUserEnvVar: (key: UserEnvVarName) => string | undefined;
+export declare const getUserEnvVarName: (
+  key: UserEnvVarName,
+) => "BW_PARALLEL_MAX_DEFAULT";

package/src/config/userEnvVars.mjs

@@ -0,0 +1,8 @@
+// CONCATENATED MODULE: ./src/config/userEnvVars.ts
+const USER_ENV_VARS = {
+  parallelMaxDefault: "BW_PARALLEL_MAX_DEFAULT",
+};
+const getUserEnvVar = (key) => process.env[USER_ENV_VARS[key]];
+const getUserEnvVarName = (key) => USER_ENV_VARS[key];
+
+export { USER_ENV_VARS, getUserEnvVar, getUserEnvVarName };

package/src/index.d.ts

@@ -13,10 +13,15 @@ export {
   type WorkspaceScriptCommandMethod,
   type RunWorkspaceScriptOptions,
   type RunWorkspaceScriptResult,
+  type InlineScriptOptions,
   type RunScriptAcrossWorkspacesOptions,
   type RunScriptAcrossWorkspacesResult,
   type OutputChunk,
   type OutputStreamName,
+  type PercentageValue,
+  type ParallelMaxValue,
+  type ParallelOption,
+  type RunScriptsParallelOptions,
 } from "./project";
 export { type Workspace } from "./workspaces";
 export { type SimpleAsyncIterable } from "./internal/types";

package/src/internal/env.mjs

@@ -19,7 +19,7 @@ const RUNTIME_MODE = RUNTIME_MODE_VALUES.includes(_RUNTIME_MODE)
 if (RUNTIME_MODE !== _RUNTIME_MODE) {
   // eslint-disable-next-line no-console
   console.error(
-    `Env var RUNTIME_MODE has an invalid value: "${_RUNTIME_MODE}". Defaulting to "${RUNTIME_MODE}". Accepted values: ${RUNTIME_MODE_VALUES.join(", ")}.`,
+    `Env var _BW_RUNTIME_MODE has an invalid value: "${_RUNTIME_MODE}". Defaulting to "${RUNTIME_MODE}". Accepted values: ${RUNTIME_MODE_VALUES.join(", ")}.`,
   );
 }
 const IS_TEST = RUNTIME_MODE === "test";

package/src/project/implementations/fileSystemProject.d.ts

@@ -1,7 +1,11 @@
 import type { Simplify } from "../../internal/types";
 import { type Workspace } from "../../workspaces";
 import type { Project } from "../project";
-import { type RunScriptResult, type RunScriptsResult } from "../runScript";
+import {
+  type RunScriptResult,
+  type RunScriptsParallelOptions,
+  type RunScriptsResult,
+} from "../runScript";
 import { ProjectBase } from "./projectBase";
 /** Arguments for {@link createFileSystemProject} */
 export type CreateFileSystemProjectOptions = {
@@ -14,6 +18,10 @@ export type CreateFileSystemProjectOptions = {
    */
   name?: string;
 };
+export interface InlineScriptOptions {
+  /** A name to act as a label for the inline script */
+  scriptName: string;
+}
 /** Arguments for `FileSystemProject.runWorkspaceScript` */
 export type RunWorkspaceScriptOptions = {
   /** The name of the workspace to run the script in */
@@ -21,7 +29,7 @@ export type RunWorkspaceScriptOptions = {
   /** The name of the script to run, or an inline command when `inline` is true */
   script: string;
   /** Whether to run the script as an inline command */
-  inline?: boolean;
+  inline?: boolean | InlineScriptOptions;
   /** The arguments to append to the script command */
   args?: string;
 };
@@ -33,6 +41,7 @@ export type RunWorkspaceScriptMetadata = {
 export type RunWorkspaceScriptResult = Simplify<
   RunScriptResult<RunWorkspaceScriptMetadata>
 >;
+export type ParallelOption = boolean | RunScriptsParallelOptions;
 /** Arguments for `FileSystemProject.runScriptAcrossWorkspaces` */
 export type RunScriptAcrossWorkspacesOptions = {
   /** Workspace names, aliases, or patterns including a wildcard */
@@ -40,11 +49,11 @@ export type RunScriptAcrossWorkspacesOptions = {
   /** The name of the script to run, or an inline command when `inline` is true */
   script: string;
   /** Whether to run the script as an inline command */
-  inline?: boolean;
+  inline?: boolean | InlineScriptOptions;
   /** The arguments to append to the script command. `<workspaceName>` will be replaced with the workspace name */
   args?: string;
   /** Whether to run the scripts in parallel (series by default) */
-  parallel?: boolean;
+  parallel?: ParallelOption;
 };
 /** Result of `FileSystemProject.runScriptAcrossWorkspaces` */
 export type RunScriptAcrossWorkspacesResult = Simplify<

package/src/project/implementations/fileSystemProject.mjs

@@ -69,13 +69,17 @@ class _FileSystemProject extends ProjectBase {
     logger.debug(
       `Running script ${options.script} in workspace: ${workspace.name}`,
     );
+    const inlineScriptName =
+      typeof options.inline === "object"
+        ? (options.inline?.scriptName ?? "")
+        : "";
     const scriptRuntimeMetadata = {
       projectPath: this.rootDirectory,
       projectName: this.name,
       workspacePath: resolveWorkspacePath(this, workspace),
       workspaceRelativePath: workspace.path,
       workspaceName: workspace.name,
-      scriptName: options.inline ? "" : options.script,
+      scriptName: options.inline ? inlineScriptName : options.script,
     };
     const args = interpolateScriptRuntimeMetadata(
       options.args ?? "",
@@ -134,13 +138,17 @@ class _FileSystemProject extends ProjectBase {
     );
     return runScripts({
       scripts: workspaces.map((workspace) => {
+        const inlineScriptName =
+          typeof options.inline === "object"
+            ? (options.inline?.scriptName ?? "")
+            : "";
         const scriptRuntimeMetadata = {
           projectPath: this.rootDirectory,
           projectName: this.name,
           workspacePath: resolveWorkspacePath(this, workspace),
           workspaceRelativePath: workspace.path,
           workspaceName: workspace.name,
-          scriptName: options.inline ? "" : options.script,
+          scriptName: options.inline ? inlineScriptName : options.script,
         };
         const args = interpolateScriptRuntimeMetadata(
           options.args ?? "",
@@ -170,7 +178,7 @@ class _FileSystemProject extends ProjectBase {
           env: createScriptRuntimeEnvVars(scriptRuntimeMetadata),
         };
       }),
-      parallel: !!options.parallel,
+      parallel: options.parallel ?? false,
     });
   }
 }

package/src/project/runScript/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./runScript";
 export * from "./runScripts";
 export * from "./scriptCommand";
+export * from "./outputChunk";
+export * from "./parallel";

package/src/project/runScript/index.mjs

@@ -1,3 +1,5 @@
 export * from "./runScript.mjs";
 export * from "./runScripts.mjs";
-export * from "./scriptCommand.mjs"; // CONCATENATED MODULE: ./src/project/runScript/index.ts
+export * from "./scriptCommand.mjs";
+export * from "./outputChunk.mjs";
+export * from "./parallel.mjs"; // CONCATENATED MODULE: ./src/project/runScript/index.ts

package/src/project/runScript/outputChunk.d.ts

@@ -0,0 +1,22 @@
+import type { OutputStreamName } from "./runScript";
+export interface DecodeOptions {
+  /** Whether to strip ANSI escape codes */
+  stripAnsi?: boolean;
+}
+/** Output captured from a script subprocess */
+export interface OutputChunk {
+  /** The source of the output, `"stdout"` or `"stderr"` */
+  streamName: OutputStreamName;
+  /** Raw output text. Pass `true` to strip ANSI escape codes. */
+  decode(options?: DecodeOptions): string;
+  /** The raw output content */
+  raw: Uint8Array<ArrayBuffer>;
+  /** @deprecated Use `decode()` instead */
+  text: string;
+  /** @deprecated Use `decode({ stripAnsi: true })` instead */
+  textNoAnsi: string;
+}
+export declare const createOutputChunk: (
+  streamName: OutputStreamName,
+  raw: Uint8Array<ArrayBuffer>,
+) => OutputChunk;

package/src/project/runScript/outputChunk.mjs

@@ -0,0 +1,30 @@
+import { sanitizeAnsi } from "../../internal/regex.mjs"; // CONCATENATED MODULE: external "../../internal/regex.mjs"
+// CONCATENATED MODULE: ./src/project/runScript/outputChunk.ts
+
+class _OutputChunk {
+  streamName;
+  raw;
+  constructor(streamName, raw) {
+    this.streamName = streamName;
+    this.raw = raw;
+  }
+  decode(options) {
+    const { stripAnsi = false } = options ?? {};
+    const text = new TextDecoder().decode(this.raw);
+    return stripAnsi ? sanitizeAnsi(text) : text;
+  }
+  /** @deprecated Use `decode()` instead */ get text() {
+    // TODO remove in future major release
+    return this.decode();
+  }
+  /** @deprecated Use `decode(true)` instead */ get textNoAnsi() {
+    // TODO remove in future major release
+    return this.decode({
+      stripAnsi: true,
+    });
+  }
+}
+const createOutputChunk = (streamName, raw) =>
+  new _OutputChunk(streamName, raw);
+
+export { createOutputChunk };

package/src/project/runScript/parallel.d.ts

@@ -0,0 +1,12 @@
+export type PercentageValue = `${number}%`;
+export type ParallelMaxValue =
+  | number
+  | "auto"
+  | "default"
+  | "unbounded"
+  | PercentageValue;
+/** Should always return at least 1 */
+export declare const determineParallelMax: (
+  value: ParallelMaxValue,
+  fromEnvVar?: boolean,
+) => number;

package/src/project/runScript/parallel.mjs

@@ -0,0 +1,52 @@
+import { availableParallelism } from "node:os";
+import { getUserEnvVar, getUserEnvVarName } from "../../config/userEnvVars.mjs";
+import { BunWorkspacesError } from "../../internal/error.mjs"; // CONCATENATED MODULE: external "node:os"
+// CONCATENATED MODULE: external "../../config/userEnvVars.mjs"
+// CONCATENATED MODULE: external "../../internal/error.mjs"
+// CONCATENATED MODULE: ./src/project/runScript/parallel.ts
+
+/** Should always return at least 1 */ const determineParallelMax = (
+  value,
+  fromEnvVar = false,
+) => {
+  const errorMessageSuffix = fromEnvVar
+    ? ` (set by env var ${getUserEnvVarName("parallelMaxDefault")})`
+    : "";
+  if (!isNaN(Number(value))) {
+    value = Math.floor(Number(value));
+  }
+  if (typeof value === "number") {
+    if (value < 1 || isNaN(value)) {
+      throw new BunWorkspacesError(
+        `Parallel max value must be at least 1${errorMessageSuffix}`,
+      );
+    }
+    return Math.floor(value);
+  }
+  if (value === "default") {
+    const defaultMax = getUserEnvVar("parallelMaxDefault")?.trim();
+    if (defaultMax === "default") return determineParallelMax("auto");
+    return determineParallelMax(defaultMax ?? "auto", true);
+  }
+  if (value === "unbounded") {
+    return Infinity;
+  }
+  const cpuCount = Math.max(1, availableParallelism());
+  if (value === "auto") {
+    return cpuCount;
+  }
+  if (value.endsWith("%")) {
+    const percentage = parseFloat(value.slice(0, -1));
+    if (isNaN(percentage) || percentage <= 0 || percentage > 100) {
+      throw new BunWorkspacesError(
+        `Parallel max value must be a number greater than 0 and less than or equal to 100${errorMessageSuffix}`,
+      );
+    }
+    return Math.max(1, Math.floor((cpuCount * percentage) / 100));
+  }
+  throw new BunWorkspacesError(
+    `Invalid parallel max value: ${JSON.stringify(value)}${errorMessageSuffix}`,
+  );
+};
+
+export { determineParallelMax };

package/src/project/runScript/runScript.d.ts

@@ -1,15 +1,7 @@
 import type { SimpleAsyncIterable } from "../../internal/types";
+import { type OutputChunk } from "./outputChunk";
 import type { ScriptCommand } from "./scriptCommand";
 export type OutputStreamName = "stdout" | "stderr";
-/** Output captured from a script subprocess */
-export type OutputChunk = {
-  /** The source of the output, `"stdout"` or `"stderr"` */
-  streamName: OutputStreamName;
-  /** Raw output text */
-  text: string;
-  /** Stripped of ANSI escape codes */
-  textNoAnsi: string;
-};
 export type RunScriptExit<ScriptMetadata extends object = object> = {
   exitCode: number;
   signal: NodeJS.Signals | null;

package/src/project/runScript/runScript.mjs

@@ -1,8 +1,8 @@
 import { mergeAsyncIterables } from "../../internal/mergeAsyncIterables.mjs";
 import { IS_WINDOWS } from "../../internal/os.mjs";
-import { sanitizeAnsi } from "../../internal/regex.mjs"; // CONCATENATED MODULE: external "../../internal/mergeAsyncIterables.mjs"
+import { createOutputChunk } from "./outputChunk.mjs"; // CONCATENATED MODULE: external "../../internal/mergeAsyncIterables.mjs"
 // CONCATENATED MODULE: external "../../internal/os.mjs"
-// CONCATENATED MODULE: external "../../internal/regex.mjs"
+// CONCATENATED MODULE: external "./outputChunk.mjs"
 // CONCATENATED MODULE: ./src/project/runScript/runScript.ts
 
 /**
@@ -28,12 +28,7 @@ import { sanitizeAnsi } from "../../internal/regex.mjs"; // CONCATENATED MODULE:
     const stream = proc[streamName];
     if (stream) {
       for await (const chunk of stream) {
-        const text = new TextDecoder().decode(chunk);
-        yield {
-          streamName,
-          text,
-          textNoAnsi: sanitizeAnsi(text),
-        };
+        yield createOutputChunk(streamName, chunk);
       }
     }
   }

package/src/project/runScript/runScripts.d.ts

@@ -1,9 +1,7 @@
 import type { SimpleAsyncIterable } from "../../internal/types";
-import {
-  type OutputChunk,
-  type RunScriptExit,
-  type RunScriptResult,
-} from "./runScript";
+import type { OutputChunk } from "./outputChunk";
+import { type ParallelMaxValue } from "./parallel";
+import { type RunScriptExit, type RunScriptResult } from "./runScript";
 import { type ScriptCommand } from "./scriptCommand";
 export type RunScriptsScript<ScriptMetadata extends object = object> = {
   scriptCommand: ScriptCommand;
@@ -36,9 +34,12 @@ export type RunScriptsResult<ScriptMetadata extends object = object> = {
   /** Resolves with a results summary after all scripts have exited */
   summary: Promise<RunScriptsSummary<ScriptMetadata>>;
 };
+export type RunScriptsParallelOptions = {
+  max: ParallelMaxValue;
+};
 export type RunScriptsOptions<ScriptMetadata extends object = object> = {
   scripts: RunScriptsScript<ScriptMetadata>[];
-  parallel: boolean;
+  parallel: boolean | RunScriptsParallelOptions;
 };
 /** Run a list of scripts */
 export declare const runScripts: <ScriptMetadata extends object = object>({

package/src/project/runScript/runScripts.mjs

@@ -1,49 +1,85 @@
 import { createAsyncIterableQueue } from "../../internal/asyncIterableQueue.mjs";
+import { logger } from "../../internal/logger.mjs";
+import { determineParallelMax } from "./parallel.mjs";
 import { runScript } from "./runScript.mjs"; // CONCATENATED MODULE: external "../../internal/asyncIterableQueue.mjs"
+// CONCATENATED MODULE: external "../../internal/logger.mjs"
+// CONCATENATED MODULE: external "./parallel.mjs"
 // CONCATENATED MODULE: external "./runScript.mjs"
 // CONCATENATED MODULE: ./src/project/runScript/runScripts.ts
 
 /** Run a list of scripts */ const runScripts = ({ scripts, parallel }) => {
   const startTime = new Date();
-  const scriptStartTriggers = scripts.map((_, index) => {
+  const scriptTriggers = scripts.map((_, index) => {
     let trigger = () => {
       void 0;
     };
-    let result = {};
     const promise = new Promise((res) => {
       trigger = () => res(result);
     });
-    result = {
-      promise,
-      trigger,
-      index,
-    };
-    return {
+    const result = {
       promise,
       trigger,
       index,
     };
+    return result;
   });
   const outputQueue = createAsyncIterableQueue();
   const scriptResults = scripts.map(() => null);
-  function triggerScript(index) {
+  const parallelMax =
+    parallel === false
+      ? 1
+      : determineParallelMax(
+          typeof parallel === "boolean" ? "default" : parallel.max,
+        );
+  const parallelBatchSize = Math.min(parallelMax, scripts.length);
+  const recommendedParallelMax = determineParallelMax("auto");
+  if (
+    parallel &&
+    parallelBatchSize > recommendedParallelMax &&
+    process.env._BW_IS_INTERNAL_TEST !== "true"
+  ) {
+    logger.warn(
+      `Number of scripts to run in parallel (${parallelBatchSize}) is greater than the available CPUs (${recommendedParallelMax})`,
+    );
+  }
+  let runningScriptCount = 0;
+  let nextScriptIndex = 0;
+  const queueScript = (index) => {
+    if (runningScriptCount >= parallelMax) {
+      return;
+    }
     const scriptResult = {
       ...scripts[index],
-      result: runScript(scripts[index]),
+      result: runScript({
+        ...scripts[index],
+        env: {
+          ...scripts[index].env,
+          _BW_PARALLEL_MAX: parallelMax.toString(),
+        },
+      }),
     };
     scriptResults[index] = scriptResult;
-    scriptStartTriggers[index].trigger();
+    scriptTriggers[index].trigger();
+    runningScriptCount++;
+    nextScriptIndex++;
+    scriptResults[index].result.exit.then(() => {
+      runningScriptCount--;
+      if (nextScriptIndex < scripts.length) {
+        queueScript(nextScriptIndex);
+      }
+    });
     return scriptResult;
-  }
-  const awaitScriptResults = async () => {
+  };
+  const handleScriptProcesses = async () => {
     const outputReaders = [];
+    const scriptExits = [];
     let pendingScriptCount = scripts.length;
     while (pendingScriptCount > 0) {
       const { index } = await Promise.race(
-        scriptStartTriggers.map((trigger) => trigger.promise),
+        scriptTriggers.map((trigger) => trigger.promise),
       );
       pendingScriptCount--;
-      scriptStartTriggers[index].promise = new Promise(() => {
+      scriptTriggers[index].promise = new Promise(() => {
         void 0;
       });
       outputReaders.push(
@@ -58,18 +94,12 @@ import { runScript } from "./runScript.mjs"; // CONCATENATED MODULE: external ".
       );
     }
     await Promise.all(outputReaders);
+    await Promise.all(scriptExits);
     outputQueue.close();
   };
   const awaitSummary = async () => {
-    if (parallel) {
-      await Promise.all(
-        scripts.map((_, index) => triggerScript(index).result.exit),
-      );
-    } else {
-      for (let index = 0; index < scripts.length; index++) {
-        await triggerScript(index).result.exit;
-      }
-    }
+    scripts.forEach((_, index) => queueScript(index));
+    await handleScriptProcesses();
     const scriptExitResults = await Promise.all(
       scripts.map((_, index) => scriptResults[index].result.exit),
     );
@@ -85,7 +115,6 @@ import { runScript } from "./runScript.mjs"; // CONCATENATED MODULE: external ".
       scriptResults: scriptExitResults,
     };
   };
-  awaitScriptResults();
   return {
     output: outputQueue,
     summary: awaitSummary(),