bun-workspaces 1.0.1-alpha → 1.0.2

package/src/project/implementations/projectBase.mjs

@@ -0,0 +1,197 @@
+import path from "path";
+import { validateCurrentBunVersion } from "../../internal/bun/index.mjs";
+import { validateJSTypes } from "../../internal/core/index.mjs";
+import { logger } from "../../internal/logger/index.mjs";
+import { createWorkspaceScriptCommand } from "../../runScript/index.mjs";
+import { sortWorkspaces } from "../../workspaces/index.mjs";
+import { matchWorkspacesByPatterns } from "../../workspaces/workspacePattern.mjs";
+import { PROJECT_ERRORS } from "../errors.mjs"; // CONCATENATED MODULE: external "path"
+// CONCATENATED MODULE: external "../../internal/bun/index.mjs"
+// CONCATENATED MODULE: external "../../internal/core/index.mjs"
+// CONCATENATED MODULE: external "../../internal/logger/index.mjs"
+// CONCATENATED MODULE: external "../../runScript/index.mjs"
+// CONCATENATED MODULE: external "../../workspaces/index.mjs"
+// CONCATENATED MODULE: external "../../workspaces/workspacePattern.mjs"
+// CONCATENATED MODULE: external "../errors.mjs"
+// CONCATENATED MODULE: ./src/project/implementations/projectBase.ts
+
+const resolveWorkspacePath = (project, workspace) =>
+  path.resolve(project.rootDirectory, workspace.path);
+const ROOT_WORKSPACE_SELECTOR = "@root";
+const resolveRootWorkspaceSelector = (workspacePattern, project) =>
+  workspacePattern === ROOT_WORKSPACE_SELECTOR
+    ? project.rootWorkspace
+    : project.findWorkspaceByNameOrAlias(workspacePattern);
+class ProjectBase {
+  constructor(_ignoreBunVersion = false) {
+    const bunVersionError = validateCurrentBunVersion();
+    if (bunVersionError && !_ignoreBunVersion) {
+      logger.error(
+        bunVersionError.message + " (Features may not work as expected)",
+      );
+    }
+  }
+  listWorkspacesWithScript(scriptName) {
+    validateJSTypes(
+      {
+        scriptName: {
+          value: scriptName,
+          typeofName: "string",
+        },
+      },
+      {
+        throw: true,
+      },
+    );
+    return this.workspaces.filter((workspace) =>
+      workspace.scripts.includes(scriptName),
+    );
+  }
+  mapScriptsToWorkspaces() {
+    const scripts = new Set();
+    this.workspaces.forEach((workspace) => {
+      workspace.scripts.forEach((script) => scripts.add(script));
+    });
+    return Array.from(scripts)
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => ({
+        name,
+        workspaces: this.listWorkspacesWithScript(name),
+      }))
+      .reduce(
+        (acc, { name, workspaces }) => ({
+          ...acc,
+          [name]: {
+            name,
+            workspaces,
+          },
+        }),
+        {},
+      );
+  }
+  findWorkspaceByName(workspaceName) {
+    validateJSTypes(
+      {
+        workspaceName: {
+          value: workspaceName,
+          typeofName: "string",
+        },
+      },
+      {
+        throw: true,
+      },
+    );
+    return (
+      this.workspaces.find((workspace) => workspace.name === workspaceName) ??
+      null
+    );
+  }
+  findWorkspaceByAlias(alias) {
+    validateJSTypes(
+      {
+        alias: {
+          value: alias,
+          typeofName: "string",
+        },
+      },
+      {
+        throw: true,
+      },
+    );
+    return (
+      this.workspaces.find((workspace) => workspace.aliases.includes(alias)) ??
+      null
+    );
+  }
+  findWorkspaceByNameOrAlias(nameOrAlias) {
+    validateJSTypes(
+      {
+        nameOrAlias: {
+          value: nameOrAlias,
+          typeofName: "string",
+        },
+      },
+      {
+        throw: true,
+      },
+    );
+    return (
+      this.findWorkspaceByName(nameOrAlias) ||
+      this.findWorkspaceByAlias(nameOrAlias)
+    );
+  }
+  findWorkspacesByPattern(...workspacePatterns) {
+    const workspaces = [];
+    if (workspacePatterns.includes(ROOT_WORKSPACE_SELECTOR)) {
+      workspaces.push(this.rootWorkspace);
+      workspacePatterns = workspacePatterns.filter(
+        (pattern) => pattern !== ROOT_WORKSPACE_SELECTOR,
+      );
+    }
+    workspaces.push(
+      ...sortWorkspaces(
+        matchWorkspacesByPatterns(workspacePatterns, this.workspaces),
+      ),
+    );
+    return workspaces;
+  }
+  createScriptCommand(options) {
+    validateJSTypes(
+      {
+        "workspaceNameOrAlias option": {
+          value: options.workspaceNameOrAlias,
+          typeofName: "string",
+        },
+        "scriptName option": {
+          value: options.scriptName,
+          typeofName: "string",
+        },
+        "method option": {
+          value: options.method,
+          typeofName: "string",
+          optional: true,
+        },
+        "args option": {
+          value: options.args,
+          typeofName: "string",
+          optional: true,
+        },
+      },
+      {
+        throw: true,
+      },
+    );
+    const workspace = resolveRootWorkspaceSelector(
+      options.workspaceNameOrAlias,
+      this,
+    );
+    if (!workspace) {
+      throw new PROJECT_ERRORS.ProjectWorkspaceNotFound(
+        `Workspace not found: ${JSON.stringify(options.workspaceNameOrAlias)}`,
+      );
+    }
+    if (!workspace.scripts.includes(options.scriptName)) {
+      throw new PROJECT_ERRORS.WorkspaceScriptDoesNotExist(
+        `Script not found in workspace ${JSON.stringify(workspace.name)}: ${JSON.stringify(options.scriptName)} (available: ${workspace.scripts.join(", ") || "none"})`,
+      );
+    }
+    return {
+      workspace,
+      scriptName: options.scriptName,
+      commandDetails: createWorkspaceScriptCommand({
+        ...options,
+        workspace,
+        rootDirectory: path.resolve(this.rootDirectory),
+        method: options.method,
+        args: options.args ?? "",
+      }),
+    };
+  }
+}
+
+export {
+  ProjectBase,
+  ROOT_WORKSPACE_SELECTOR,
+  resolveRootWorkspaceSelector,
+  resolveWorkspacePath,
+};

package/src/project/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./errors";
+export type * from "./project";
+export * from "./implementations/projectBase";
+export * from "./implementations/fileSystemProject";
+export * from "./implementations/memoryProject";

package/src/project/index.mjs

@@ -0,0 +1,4 @@
+export * from "./errors.mjs";
+export * from "./implementations/projectBase.mjs";
+export * from "./implementations/fileSystemProject.mjs";
+export * from "./implementations/memoryProject.mjs"; // CONCATENATED MODULE: ./src/project/index.ts

package/src/project/project.d.ts

@@ -0,0 +1,75 @@
+import type { ResolvedRootConfig, ResolvedWorkspaceConfig } from "../config";
+import type { ScriptCommand, WorkspaceScriptCommandMethod } from "../runScript";
+import type { Workspace } from "../workspaces";
+/** Metadata about a {@link Project}'s script, including the workspaces that have it in their package.json */
+export type WorkspaceScriptMetadata = {
+  name: string;
+  workspaces: Workspace[];
+};
+/** Arguments for {@link Project.createScriptCommand} */
+export type CreateProjectScriptCommandOptions = {
+  /** The workspace to run the script in */
+  workspaceNameOrAlias: string;
+  /** The name of the script to run */
+  scriptName: string;
+  /**
+   * The method to use to run the script.
+   * Either run in the workspace directory or use bun's --filter option.
+   * Defaults to "cd".
+   */
+  method?: WorkspaceScriptCommandMethod;
+  /** The arguments to append to the command */
+  args?: string;
+};
+/** Result of {@link Project.createScriptCommand}. Includes a command string that will run a workspace's script. */
+export type CreateProjectScriptCommandResult = {
+  /** Data including a command string using the `bun`
+   * CLI that will run a workspace's script and the
+   * directory to run it in. */
+  commandDetails: ScriptCommand;
+  /** The name of the script to run */
+  scriptName: string;
+  /** The workspace that the script belongs to */
+  workspace: Workspace;
+};
+/** The config for a project and its workspaces */
+export type ProjectConfig = {
+  root: ResolvedRootConfig;
+  /** A map of workspace names to their resolved config */
+  workspaces: Record<string, ResolvedWorkspaceConfig>;
+};
+/**
+ * A project contains a collection of workspaces and is the core of `bun-workspaces`'s functionality.
+ *
+ * Typically based on a root package.json file's `"workspaces"` field and any matching nested package.json files that are found.
+ */
+export interface Project {
+  /** The name of the project. This is typically the name of the root package.json unless otherwise provided. */
+  name: string;
+  /** The root directory of the project */
+  rootDirectory: string;
+  /** The root workspace of the project */
+  rootWorkspace: Workspace;
+  /** The list of all workspaces in the project */
+  workspaces: Workspace[];
+  /** The config for the project and its workspaces */
+  config: ProjectConfig;
+  /** The means by which the project was created */
+  sourceType: "fileSystem" | "memory";
+  /** Find a workspace by its package.json name */
+  findWorkspaceByName(workspaceName: string): Workspace | null;
+  /** Find a workspace by a workspace alias */
+  findWorkspaceByAlias(alias: string): Workspace | null;
+  /** Find a workspace that matches a workspace's name or an alias if no name matches. */
+  findWorkspaceByNameOrAlias(nameOrAlias: string): Workspace | null;
+  /** Accepts a wildcard pattern for finding a list of workspaces by their name*/
+  findWorkspacesByPattern(workspacePattern: string): Workspace[];
+  /** Get an array of all workspaces that have a given script in their package.json */
+  listWorkspacesWithScript(scriptName: string): Workspace[];
+  /** Get a mapping of all scripts to the workspaces that have them in their package.json */
+  mapScriptsToWorkspaces(): Record<string, WorkspaceScriptMetadata>;
+  /** Create metadata that can be used to run a workspace's script */
+  createScriptCommand(
+    options: CreateProjectScriptCommandOptions,
+  ): CreateProjectScriptCommandResult;
+}

package/src/project/project.mjs

@@ -0,0 +1,6 @@
+// CONCATENATED MODULE: ./src/project/project.ts
+/**
+ * A project contains a collection of workspaces and is the core of `bun-workspaces`'s functionality.
+ *
+ * Typically based on a root package.json file's `"workspaces"` field and any matching nested package.json files that are found.
+ */

package/src/runScript/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./runScript";
+export * from "./runScripts";
+export * from "./scriptCommand";
+export * from "./output";
+export * from "./parallel";
+export * from "./scriptRuntimeMetadata";
+export * from "./scriptShellOption";

package/src/runScript/index.mjs

@@ -0,0 +1,7 @@
+export * from "./runScript.mjs";
+export * from "./runScripts.mjs";
+export * from "./scriptCommand.mjs";
+export * from "./output/index.mjs";
+export * from "./parallel.mjs";
+export * from "./scriptRuntimeMetadata.mjs";
+export * from "./scriptShellOption.mjs"; // CONCATENATED MODULE: ./src/runScript/index.ts

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

@@ -0,0 +1,3 @@
+export type * from "./outputStream";
+export * from "./multiProcessOutput";
+export * from "./processOutput";

package/src/runScript/output/index.mjs

@@ -0,0 +1,2 @@
+export * from "./multiProcessOutput.mjs";
+export * from "./processOutput.mjs"; // CONCATENATED MODULE: ./src/runScript/output/index.ts

package/src/runScript/output/multiProcessOutput.d.ts

@@ -0,0 +1,14 @@
+import {
+  type ProcessOutput,
+  type BytesOutput,
+  type TextOutput,
+} from "./processOutput";
+export interface MultiProcessOutput<Metadata extends object = object> {
+  bytes(): BytesOutput<Metadata>;
+  text(): TextOutput<Metadata>;
+}
+export declare const createMultiProcessOutput: <
+  Metadata extends object = object,
+>(
+  processes: ProcessOutput<Metadata>[],
+) => MultiProcessOutput<Metadata>;

package/src/runScript/output/multiProcessOutput.mjs

@@ -0,0 +1,21 @@
+import { mergeAsyncIterables } from "../../internal/core/index.mjs"; // CONCATENATED MODULE: external "../../internal/core/index.mjs"
+// CONCATENATED MODULE: ./src/runScript/output/multiProcessOutput.ts
+
+class _MultiProcessOutput {
+  processes;
+  constructor(processes) {
+    this.processes = processes;
+  }
+  bytes() {
+    return mergeAsyncIterables(
+      this.processes.map((process) => process.bytes()),
+    );
+  }
+  text() {
+    return mergeAsyncIterables(this.processes.map((process) => process.text()));
+  }
+}
+const createMultiProcessOutput = (processes) =>
+  new _MultiProcessOutput(processes);
+
+export { createMultiProcessOutput };

package/src/runScript/output/outputStream.d.ts

@@ -0,0 +1 @@
+export type OutputStreamName = "stdout" | "stderr";

package/src/runScript/output/outputStream.mjs

@@ -0,0 +1 @@
+// CONCATENATED MODULE: ./src/runScript/output/outputStream.ts

package/src/runScript/output/processOutput.d.ts

@@ -0,0 +1,33 @@
+import { type SimpleAsyncIterable } from "../../internal/core";
+export type ByteStream = SimpleAsyncIterable<Uint8Array<ArrayBufferLike>>;
+export type ProcessOutputChunk<
+  Chunk = unknown,
+  Metadata extends object = object,
+> = {
+  /** The metadata for the script that produced the output chunk */
+  metadata: Metadata;
+  /** The output chunk */
+  chunk: Chunk;
+};
+export type ByteChunk<Metadata extends object = object> = ProcessOutputChunk<
+  Uint8Array<ArrayBufferLike>,
+  Metadata
+>;
+export type TextChunk<Metadata extends object = object> = ProcessOutputChunk<
+  string,
+  Metadata
+>;
+export type BytesOutput<Metadata extends object = object> = SimpleAsyncIterable<
+  ByteChunk<Metadata>
+>;
+export type TextOutput<Metadata extends object = object> = SimpleAsyncIterable<
+  TextChunk<Metadata>
+>;
+export interface ProcessOutput<Metadata extends object = object> {
+  bytes(): BytesOutput<Metadata>;
+  text(): TextOutput<Metadata>;
+}
+export declare const createProcessOutput: <Metadata extends object = object>(
+  stream: ByteStream,
+  metadata: Metadata,
+) => ProcessOutput<Metadata>;

package/src/runScript/output/processOutput.mjs

@@ -0,0 +1,124 @@
+import {
+  BunWorkspacesError,
+  createAsyncIterableQueue,
+  defineErrors,
+} from "../../internal/core/index.mjs"; // CONCATENATED MODULE: external "../../internal/core/index.mjs"
+// CONCATENATED MODULE: ./src/runScript/output/processOutput.ts
+
+const ERRORS = defineErrors(
+  BunWorkspacesError,
+  "OutputStreamStarted",
+  "OutputStreamDone",
+);
+class _ProcessOutput {
+  constructor(stream, metadata) {
+    this.#inputStream = stream;
+    this.#metadata = metadata;
+    this.#done = new Promise((resolve, reject) => {
+      this.#onDone = (error) => {
+        if (this.#isDone) return;
+        this.#isDone = true;
+        this.#byteChunkQueue.close();
+        this.#onDone = null;
+        if (!this.isCancelled && error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+    });
+    (async () => {
+      // Drain the stream immediately to prevent pipe buffer overflow from subprocesses,
+      // the queue acting as a() forwarded async iterable in a way.
+      try {
+        for await (const chunk of stream) {
+          if (this.#isCancelled) break;
+          this.#byteChunkQueue.push(chunk.slice());
+        }
+      } catch (error) {
+        this.#error = error;
+      } finally {
+        this.#onDone?.(this.#error);
+      }
+    })();
+  }
+  get done() {
+    return this.#done;
+  }
+  get isCancelled() {
+    return this.#isCancelled;
+  }
+  bytes() {
+    this.#onStart();
+    const metadata = this.#metadata;
+    const byteChunkQueue = this.#byteChunkQueue;
+    return (async function* () {
+      for await (const chunk of byteChunkQueue) {
+        yield {
+          metadata,
+          chunk,
+        };
+      }
+    })();
+  }
+  text() {
+    this.#onStart();
+    const metadata = this.#metadata;
+    const byteChunkQueue = this.#byteChunkQueue;
+    return (async function* () {
+      const decoder = new TextDecoder();
+      for await (const byteChunk of byteChunkQueue) {
+        yield {
+          metadata,
+          chunk: decoder.decode(byteChunk, {
+            stream: true,
+          }),
+        };
+      }
+      // flush any remaining data in the decoder
+      const danglingChunk = decoder.decode();
+      if (danglingChunk)
+        yield {
+          metadata,
+          chunk: danglingChunk,
+        };
+    })();
+  }
+  async cancel(reason) {
+    this.#isCancelled = true;
+    this.#onDone?.();
+    await this.#inputStream.cancel?.(reason);
+  }
+  get isDone() {
+    return this.#isDone;
+  }
+  get error() {
+    return this.#error;
+  }
+  #onStart() {
+    if (this.#isDone) {
+      throw new ERRORS.OutputStreamDone(
+        "The output stream has already been closed.",
+      );
+    }
+    if (this.#isStarted) {
+      throw new ERRORS.OutputStreamStarted(
+        "Only one stream can be opened via .bytes() or .text(). This stream has already been opened.",
+      );
+    }
+    this.#isStarted = true;
+  }
+  #isStarted = false;
+  #done;
+  #error = null;
+  #onDone = null;
+  #isDone = false;
+  #isCancelled = false;
+  #inputStream;
+  #byteChunkQueue = createAsyncIterableQueue();
+  #metadata;
+}
+const createProcessOutput = (stream, metadata) =>
+  new _ProcessOutput(stream, metadata);
+
+export { createProcessOutput };

package/src/runScript/parallel.d.ts

@@ -0,0 +1,15 @@
+export declare const PARALLEL_MAX_VALUES: readonly [
+  "auto",
+  "unbounded",
+  "default",
+];
+export type PercentageValue = `${number}%`;
+export type ParallelMaxValue =
+  | number
+  | (typeof PARALLEL_MAX_VALUES)[number]
+  | PercentageValue;
+/** Should always return at least 1 */
+export declare const determineParallelMax: (
+  value: ParallelMaxValue,
+  errorMessageSuffix?: string,
+) => number;

package/src/runScript/parallel.mjs

@@ -0,0 +1,56 @@
+import os from "os";
+import {
+  getUserEnvVar,
+  getUserEnvVarName,
+} from "../config/userEnvVars/index.mjs";
+import { BunWorkspacesError } from "../internal/core/index.mjs"; // CONCATENATED MODULE: external "os"
+// CONCATENATED MODULE: external "../config/userEnvVars/index.mjs"
+// CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: ./src/runScript/parallel.ts
+
+const PARALLEL_MAX_VALUES = ["auto", "unbounded", "default"];
+/** Should always return at least 1 */ const determineParallelMax = (
+  value,
+  errorMessageSuffix = "",
+) => {
+  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",
+      ` (set by env var ${getUserEnvVarName("parallelMaxDefault")})`,
+    );
+  }
+  if (value === "unbounded") {
+    return Infinity;
+  }
+  const cpuCount = Math.max(1, os.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 { PARALLEL_MAX_VALUES, determineParallelMax };

package/src/runScript/recursion.d.ts

@@ -0,0 +1,4 @@
+export declare const checkIsRecursiveScript: (
+  workspaceName: string,
+  scriptName: string,
+) => boolean | undefined;

package/src/runScript/recursion.mjs

@@ -0,0 +1,17 @@
+import { getScriptRuntimeMetadataConfig } from "./scriptRuntimeMetadata.mjs"; // CONCATENATED MODULE: external "./scriptRuntimeMetadata.mjs"
+// CONCATENATED MODULE: ./src/runScript/recursion.ts
+
+const checkIsRecursiveScript = (workspaceName, scriptName) => {
+  const parentWorkspace =
+    process.env[getScriptRuntimeMetadataConfig("workspaceName").envVarName];
+  const parentScript =
+    process.env[getScriptRuntimeMetadataConfig("scriptName").envVarName];
+  if (!parentWorkspace || !parentScript) {
+    return false;
+  }
+  if (parentWorkspace === workspaceName && parentScript === scriptName) {
+    return true;
+  }
+};
+
+export { checkIsRecursiveScript };

package/src/runScript/runScript.d.ts

@@ -0,0 +1,45 @@
+import { type MultiProcessOutput, type OutputStreamName } from "./output";
+import type { ScriptCommand } from "./scriptCommand";
+import type { ScriptShellOption } from "./scriptShellOption";
+export type RunScriptExit<ScriptMetadata extends object = object> = {
+  exitCode: number;
+  signal: NodeJS.Signals | null;
+  success: boolean;
+  /** Whether the script was skipped due to a failed dependency */
+  skipped?: boolean;
+  startTimeISO: string;
+  endTimeISO: string;
+  durationMs: number;
+  metadata: ScriptMetadata;
+};
+export type RunScriptResult<ScriptMetadata extends object = object> = {
+  output: MultiProcessOutput<
+    ScriptMetadata & {
+      streamName: OutputStreamName;
+    }
+  >;
+  exit: Promise<RunScriptExit<ScriptMetadata>>;
+  metadata: ScriptMetadata;
+  kill: (exit?: number | NodeJS.Signals) => void;
+};
+export type RunScriptOptions<ScriptMetadata extends object = object> = {
+  scriptCommand: ScriptCommand;
+  metadata: ScriptMetadata;
+  env: Record<string, string>;
+  /** The shell to use to run the script. Defaults to "system". */
+  shell?: ScriptShellOption;
+  /** Set to `true` to ignore all output from the script. This saves memory when you don't need script output. */
+  ignoreOutput?: boolean;
+};
+/**
+ * Run some script and get an async output stream of
+ * stdout and stderr chunks and a result object
+ * containing exit details.
+ */
+export declare const runScript: <ScriptMetadata extends object = object>({
+  scriptCommand,
+  metadata,
+  env,
+  shell,
+  ignoreOutput,
+}: RunScriptOptions<ScriptMetadata>) => RunScriptResult<ScriptMetadata>;