ts-repo-utils 3.0.1 → 3.1.1

package/dist/functions/index.d.mts

@@ -6,4 +6,5 @@ export * from './exec-async.mjs';
 export * from './format.mjs';
 export * from './gen-index.mjs';
 export * from './should-run.mjs';
+export * from './workspace-utils/index.mjs';
 //# sourceMappingURL=index.d.mts.map

package/dist/functions/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/functions/index.mts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/functions/index.mts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC"}

package/dist/functions/index.mjs

@@ -6,4 +6,8 @@ export { $ } from './exec-async.mjs';
 export { formatDiffFrom, formatFiles, formatFilesList, formatUntracked } from './format.mjs';
 export { genIndex } from './gen-index.mjs';
 export { checkShouldRunTypeChecks } from './should-run.mjs';
+export { executeParallel, executeStages } from './workspace-utils/execute-parallel.mjs';
+export { getWorkspacePackages } from './workspace-utils/get-workspace-packages.mjs';
+export { runCmdInParallelAcrossWorkspaces } from './workspace-utils/run-cmd-in-parallel.mjs';
+export { runCmdInStagesAcrossWorkspaces } from './workspace-utils/run-cmd-in-stages.mjs';
 //# sourceMappingURL=index.mjs.map

package/dist/functions/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}

package/dist/functions/should-run.d.mts

@@ -1,3 +1,17 @@
 import '../node-global.mjs';
+/**
+ * Checks if TypeScript type checks should run based on the diff from origin/main.
+ * Skips type checks if all changed files are documentation files, spell check config,
+ * or other non-TypeScript files that don't affect type checking.
+ *
+ * Ignored file patterns:
+ * - '.cspell.json'
+ * - '**.md'
+ * - '**.txt'
+ * - 'docs/**'
+ *
+ * @returns A promise that resolves when the check is complete. Sets GITHUB_OUTPUT
+ * environment variable with should_run=true/false if running in GitHub Actions.
+ */
 export declare const checkShouldRunTypeChecks: () => Promise<void>;
 //# sourceMappingURL=should-run.d.mts.map

package/dist/functions/should-run.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAG5B,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CA4B7D,CAAC"}
+{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CA4B7D,CAAC"}

package/dist/functions/should-run.mjs

@@ -2,6 +2,20 @@ import { Result, pipe } from 'ts-data-forge';
 import '../node-global.mjs';
 import { getDiffFrom } from './diff.mjs';
 
+/**
+ * Checks if TypeScript type checks should run based on the diff from origin/main.
+ * Skips type checks if all changed files are documentation files, spell check config,
+ * or other non-TypeScript files that don't affect type checking.
+ *
+ * Ignored file patterns:
+ * - '.cspell.json'
+ * - '**.md'
+ * - '**.txt'
+ * - 'docs/**'
+ *
+ * @returns A promise that resolves when the check is complete. Sets GITHUB_OUTPUT
+ * environment variable with should_run=true/false if running in GitHub Actions.
+ */
 const checkShouldRunTypeChecks = async () => {
     // paths-ignore:
     //   - '.cspell.json'

package/dist/functions/should-run.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIO,MAAM,wBAAwB,GAAG,YAA0B;;;;;;IAOhE,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAElD,IAAA,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC;AAE9C,IAAA,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC;AACjD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;;AAGjB,IAAA,MAAM,iBAAiB,GAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CACnD,CAAC,IAAI,KACH,IAAI,KAAK,cAAc;AACvB,QAAA,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;AACxB,QAAA,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAC3B,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CACpE,CAAC,KAAK,CACV;AAED,IAAA,IAAI,aAAa,KAAK,SAAS,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,WAAA,EAAc,iBAAiB,CAAA,EAAA,CAAI,CAAC;;AAE3E;;;;"}
+{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;AAaG;AACI,MAAM,wBAAwB,GAAG,YAA0B;;;;;;IAOhE,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAElD,IAAA,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC;AAE9C,IAAA,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC;AACjD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;;AAGjB,IAAA,MAAM,iBAAiB,GAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CACnD,CAAC,IAAI,KACH,IAAI,KAAK,cAAc;AACvB,QAAA,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;AACxB,QAAA,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAC3B,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CACpE,CAAC,KAAK,CACV;AAED,IAAA,IAAI,aAAa,KAAK,SAAS,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,WAAA,EAAc,iBAAiB,CAAA,EAAA,CAAI,CAAC;;AAE3E;;;;"}

package/dist/functions/workspace-utils/execute-parallel.d.mts

@@ -0,0 +1,25 @@
+import { Result } from 'ts-data-forge';
+import '../../node-global.mjs';
+import { type Package } from './types.mjs';
+/**
+ * Executes a npm script across multiple packages in parallel with a concurrency limit.
+ * @param packages - Array of Package objects to execute the script in
+ * @param scriptName - The name of the npm script to execute
+ * @param concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @returns A promise that resolves to an array of execution results
+ */
+export declare const executeParallel: (packages: readonly Package[], scriptName: string, concurrency?: number) => Promise<readonly Result<Readonly<{
+    code?: number;
+    skipped?: boolean;
+}>, Error>[]>;
+/**
+ * Executes a npm script across packages in dependency order stages.
+ * Packages are grouped into stages where each stage contains packages whose
+ * dependencies have been completed in previous stages.
+ * @param packages - Array of Package objects to execute the script in
+ * @param scriptName - The name of the npm script to execute
+ * @param concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @returns A promise that resolves when all stages are complete
+ */
+export declare const executeStages: (packages: readonly Package[], scriptName: string, concurrency?: number) => Promise<void>;
+//# sourceMappingURL=execute-parallel.d.mts.map

package/dist/functions/workspace-utils/execute-parallel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-parallel.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/execute-parallel.mts"],"names":[],"mappings":"AACA,OAAO,EAML,MAAM,EACP,MAAM,eAAe,CAAC;AACvB,OAAO,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAI3C;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,SAAS,OAAO,EAAE,EAC5B,YAAY,MAAM,EAClB,cAAa,MAAU,KACtB,OAAO,CACR,SAAS,MAAM,CAAC,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAkCzE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,SAAS,OAAO,EAAE,EAC5B,YAAY,MAAM,EAClB,cAAa,MAAU,KACtB,OAAO,CAAC,IAAI,CAuCd,CAAC"}

package/dist/functions/workspace-utils/execute-parallel.mjs

@@ -0,0 +1,162 @@
+import { spawn } from 'child_process';
+import { pipe, createPromise, isRecord, hasKey, Result, isNotUndefined } from 'ts-data-forge';
+import '../../node-global.mjs';
+
+/**
+ * Executes a npm script across multiple packages in parallel with a concurrency limit.
+ * @param packages - Array of Package objects to execute the script in
+ * @param scriptName - The name of the npm script to execute
+ * @param concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @returns A promise that resolves to an array of execution results
+ */
+const executeParallel = async (packages, scriptName, concurrency = 3) => {
+    const mut_resultPromises = [];
+    const executing = new Set();
+    for (const pkg of packages) {
+        const promise = executeScript(pkg, scriptName);
+        mut_resultPromises.push(promise);
+        const wrappedPromise = promise.finally(() => {
+            executing.delete(wrappedPromise);
+        });
+        executing.add(wrappedPromise);
+        // If we reach concurrency limit, wait for one to finish
+        if (executing.size >= concurrency) {
+            // eslint-disable-next-line no-await-in-loop
+            await Promise.race(executing);
+        }
+    }
+    return Promise.all(mut_resultPromises);
+};
+/**
+ * Executes a npm script across packages in dependency order stages.
+ * Packages are grouped into stages where each stage contains packages whose
+ * dependencies have been completed in previous stages.
+ * @param packages - Array of Package objects to execute the script in
+ * @param scriptName - The name of the npm script to execute
+ * @param concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @returns A promise that resolves when all stages are complete
+ */
+const executeStages = async (packages, scriptName, concurrency = 3) => {
+    const dependencyGraph = buildDependencyGraph(packages);
+    const sorted = topologicalSortPackages(packages, dependencyGraph);
+    const stages = [];
+    const completed = new Set();
+    while (completed.size < sorted.length) {
+        const stage = [];
+        for (const pkg of sorted) {
+            if (completed.has(pkg.name))
+                continue;
+            const deps = dependencyGraph.get(pkg.name) ?? [];
+            const depsCompleted = deps.every((dep) => completed.has(dep));
+            if (depsCompleted) {
+                stage.push(pkg);
+            }
+        }
+        if (stage.length === 0) {
+            throw new Error('Circular dependency detected');
+        }
+        stages.push(stage);
+        for (const pkg of stage)
+            completed.add(pkg.name);
+    }
+    console.log(`\nExecuting ${scriptName} in ${stages.length} stages...\n`);
+    for (const [i, stage] of stages.entries()) {
+        if (stage.length > 0) {
+            console.log(`Stage ${i + 1}: ${stage.map((p) => p.name).join(', ')}`);
+            // eslint-disable-next-line no-await-in-loop
+            await executeParallel(stage, scriptName, concurrency);
+        }
+    }
+};
+/**
+ * Executes a npm script in a specific package directory.
+ * @param pkg - The package object containing path and metadata
+ * @param scriptName - The name of the npm script to execute
+ * @param options - Configuration options
+ * @param options.prefix - Whether to prefix output with package name (default: true)
+ * @returns A promise that resolves to execution result with exit code or skipped flag
+ */
+const executeScript = (pkg, scriptName, { prefix = true } = {}) => pipe(createPromise((resolve, reject) => {
+    const packageJsonScripts = isRecord(pkg.packageJson) && isRecord(pkg.packageJson['scripts'])
+        ? pkg.packageJson['scripts']
+        : {};
+    const hasScript = hasKey(packageJsonScripts, scriptName);
+    if (!hasScript) {
+        resolve({ skipped: true });
+        return;
+    }
+    const prefixStr = prefix ? `[${pkg.name}] ` : '';
+    const proc = spawn('npm', ['run', scriptName], {
+        cwd: pkg.path,
+        shell: true,
+        stdio: 'pipe',
+    });
+    proc.stdout.on('data', (data) => {
+        process.stdout.write(prefixStr + data.toString());
+    });
+    proc.stderr.on('data', (data) => {
+        process.stderr.write(prefixStr + data.toString());
+    });
+    proc.on('close', (code) => {
+        if (code === 0) {
+            resolve({ code });
+        }
+        else {
+            reject(new Error(`${pkg.name} exited with code ${code}`));
+        }
+    });
+    proc.on('error', reject);
+})).map((result) => result.then(Result.mapErr((err) => {
+    const errorMessage = err instanceof Error
+        ? err.message
+        : isRecord(err) && hasKey(err, 'message')
+            ? (err.message?.toString() ?? 'Unknown error message')
+            : 'Unknown error';
+    console.error(`\nError in ${pkg.name}:`, errorMessage);
+    return err instanceof Error ? err : new Error(errorMessage);
+}))).value;
+/**
+ * Performs a topological sort on packages based on their dependencies,
+ * ensuring dependencies are ordered before their dependents.
+ * @param packages - Array of Package objects to sort
+ * @returns An array of packages in dependency order (dependencies first)
+ */
+const topologicalSortPackages = (packages, dependencyGraph) => {
+    const visited = new Set();
+    const result = [];
+    const packageMap = new Map(packages.map((p) => [p.name, p]));
+    const visit = (pkgName) => {
+        if (visited.has(pkgName))
+            return;
+        visited.add(pkgName);
+        const deps = dependencyGraph.get(pkgName) ?? [];
+        for (const dep of deps) {
+            visit(dep);
+        }
+        result.push(pkgName);
+    };
+    for (const pkg of packages) {
+        visit(pkg.name);
+    }
+    return result
+        .map((pkgName) => packageMap.get(pkgName))
+        .filter(isNotUndefined);
+};
+/**
+ * Builds a dependency graph from the given packages, mapping each package name
+ * to its internal workspace dependencies.
+ * @param packages - Array of Package objects to analyze
+ * @returns A readonly map where keys are package names and values are arrays of their dependency package names
+ */
+const buildDependencyGraph = (packages) => {
+    const packageMap = new Map(packages.map((p) => [p.name, p]));
+    const graph = new Map();
+    for (const pkg of packages) {
+        const deps = Object.keys(pkg.dependencies).filter((depName) => packageMap.has(depName));
+        graph.set(pkg.name, deps);
+    }
+    return graph;
+};
+
+export { executeParallel, executeStages };
+//# sourceMappingURL=execute-parallel.mjs.map

package/dist/functions/workspace-utils/execute-parallel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-parallel.mjs","sources":["../../../src/functions/workspace-utils/execute-parallel.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/functions/workspace-utils/get-workspace-packages.d.mts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import '../../node-global.mjs';
+import { type Package } from './types.mjs';
+/**
+ * Retrieves all workspace packages from a monorepo based on the workspace patterns
+ * defined in the root package.json file.
+ * @param rootPackageJsonDir - The directory containing the root package.json file
+ * @returns A promise that resolves to an array of Package objects containing package metadata
+ */
+export declare const getWorkspacePackages: (rootPackageJsonDir: string) => Promise<readonly Package[]>;
+//# sourceMappingURL=get-workspace-packages.d.mts.map

package/dist/functions/workspace-utils/get-workspace-packages.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-workspace-packages.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/get-workspace-packages.mts"],"names":[],"mappings":";AAUA,OAAO,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,oBAAoB,MAAM,KACzB,OAAO,CAAC,SAAS,OAAO,EAAE,CA+D5B,CAAC"}

package/dist/functions/workspace-utils/get-workspace-packages.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env tsx
+import { Result, Json, isNotUndefined, isRecord, hasKey, isString } from 'ts-data-forge';
+import '../../node-global.mjs';
+
+/**
+ * Retrieves all workspace packages from a monorepo based on the workspace patterns
+ * defined in the root package.json file.
+ * @param rootPackageJsonDir - The directory containing the root package.json file
+ * @returns A promise that resolves to an array of Package objects containing package metadata
+ */
+const getWorkspacePackages = async (rootPackageJsonDir) => {
+    // Read root package.json
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const rootPackageJson = JSON.parse(await fs.readFile(path.join(rootPackageJsonDir, 'package.json'), 'utf8'));
+    const workspacePatterns = getStrArrayFromJsonValue(rootPackageJson, 'workspaces');
+    const packagePromises = workspacePatterns.map(async (pattern) => {
+        const matches = await glob(pattern, {
+            cwd: rootPackageJsonDir,
+            ignore: ['**/node_modules/**'],
+            onlyDirectories: true,
+            absolute: true,
+        });
+        const packageJsonList = await Promise.all(matches.map(async (match) => {
+            const maybePackagePath = path.join(match, 'package.json');
+            const result = await Result.fromPromise(fs.readFile(maybePackagePath, 'utf8'));
+            if (Result.isErr(result))
+                return undefined;
+            const parsed = Json.parse(result.value);
+            if (Result.isErr(parsed))
+                return undefined;
+            return [maybePackagePath, parsed.value];
+        }));
+        const packageInfos = await Promise.all(packageJsonList
+            .filter(isNotUndefined)
+            .map(([packagePath, packageJson]) => ({
+            name: getStrFromJsonValue(packageJson, 'name'),
+            path: path.dirname(packagePath),
+            packageJson,
+            dependencies: {
+                ...getKeyValueRecordFromJsonValue(packageJson, 'dependencies'),
+                ...getKeyValueRecordFromJsonValue(packageJson, 'devDependencies'),
+                ...getKeyValueRecordFromJsonValue(packageJson, 'peerDependencies'),
+            },
+        })));
+        return packageInfos;
+    });
+    const allPackageArrays = await Promise.all(packagePromises);
+    const finalPackages = allPackageArrays.flat();
+    return finalPackages;
+};
+const getStrFromJsonValue = (value, key) => isRecord(value) && hasKey(value, key) && isString(value[key])
+    ? value[key]
+    : '';
+const getStrArrayFromJsonValue = (value, key) => isRecord(value) &&
+    hasKey(value, key) &&
+    Array.isArray(value[key]) &&
+    value[key].every(isString)
+    ? value[key]
+    : [];
+const getKeyValueRecordFromJsonValue = (value, key) => {
+    if (!isRecord(value) || !hasKey(value, key)) {
+        return {};
+    }
+    const obj = value[key];
+    if (!isRecord(obj)) {
+        return {};
+    }
+    const entries = Object.entries(obj).filter((entry) => isString(entry[1]));
+    return Object.fromEntries(entries);
+};
+
+export { getWorkspacePackages };
+//# sourceMappingURL=get-workspace-packages.mjs.map

package/dist/functions/workspace-utils/get-workspace-packages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-workspace-packages.mjs","sources":["../../../src/functions/workspace-utils/get-workspace-packages.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/functions/workspace-utils/index.d.mts

@@ -0,0 +1,6 @@
+export * from './execute-parallel.mjs';
+export * from './get-workspace-packages.mjs';
+export * from './run-cmd-in-parallel.mjs';
+export * from './run-cmd-in-stages.mjs';
+export * from './types.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/functions/workspace-utils/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/index.mts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC"}

package/dist/functions/workspace-utils/index.mjs

@@ -0,0 +1,5 @@
+export { executeParallel, executeStages } from './execute-parallel.mjs';
+export { getWorkspacePackages } from './get-workspace-packages.mjs';
+export { runCmdInParallelAcrossWorkspaces } from './run-cmd-in-parallel.mjs';
+export { runCmdInStagesAcrossWorkspaces } from './run-cmd-in-stages.mjs';
+//# sourceMappingURL=index.mjs.map

package/dist/functions/workspace-utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/functions/workspace-utils/run-cmd-in-parallel.d.mts

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+/**
+ * Executes a npm script command across all workspace packages in parallel.
+ * @param options - Configuration options for the parallel execution
+ * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.cmd - The npm script command to execute in each package
+ * @param options.concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @returns A promise that resolves when all packages have completed execution
+ */
+export declare const runCmdInParallelAcrossWorkspaces: ({ rootPackageJsonDir, cmd, concurrency, filterWorkspacePattern, }: Readonly<{
+    rootPackageJsonDir: string;
+    cmd: string;
+    concurrency?: number;
+    filterWorkspacePattern?: (packageName: string) => boolean;
+}>) => Promise<void>;
+//# sourceMappingURL=run-cmd-in-parallel.d.mts.map

package/dist/functions/workspace-utils/run-cmd-in-parallel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cmd-in-parallel.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/run-cmd-in-parallel.mts"],"names":[],"mappings":";AAKA;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,GAAU,mEAKpD,QAAQ,CAAC;IACV,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3D,CAAC,KAAG,OAAO,CAAC,IAAI,CAkBhB,CAAC"}

package/dist/functions/workspace-utils/run-cmd-in-parallel.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+import { executeParallel } from './execute-parallel.mjs';
+import { getWorkspacePackages } from './get-workspace-packages.mjs';
+
+/**
+ * Executes a npm script command across all workspace packages in parallel.
+ * @param options - Configuration options for the parallel execution
+ * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.cmd - The npm script command to execute in each package
+ * @param options.concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @returns A promise that resolves when all packages have completed execution
+ */
+const runCmdInParallelAcrossWorkspaces = async ({ rootPackageJsonDir, cmd, concurrency = 3, filterWorkspacePattern, }) => {
+    try {
+        const packages = await getWorkspacePackages(rootPackageJsonDir);
+        const filteredPackages = filterWorkspacePattern === undefined
+            ? packages
+            : packages.filter((pkg) => filterWorkspacePattern(pkg.name));
+        await executeParallel(filteredPackages, cmd, concurrency);
+        console.log(`\n✅ ${cmd} completed successfully`);
+    }
+    catch (err) {
+        console.error(`\n❌ ${cmd} failed:`, err instanceof Error ? err.message : (err?.toString() ?? ''));
+        process.exit(1);
+    }
+};
+
+export { runCmdInParallelAcrossWorkspaces };
+//# sourceMappingURL=run-cmd-in-parallel.mjs.map

package/dist/functions/workspace-utils/run-cmd-in-parallel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cmd-in-parallel.mjs","sources":["../../../src/functions/workspace-utils/run-cmd-in-parallel.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;;;AAQG;AACI,MAAM,gCAAgC,GAAG,OAAO,EACrD,kBAAkB,EAClB,GAAG,EACH,WAAW,GAAG,CAAC,EACf,sBAAsB,GAMtB,KAAmB;AACnB,IAAA,IAAI;AACF,QAAA,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,kBAAkB,CAAC;AAE/D,QAAA,MAAM,gBAAgB,GACpB,sBAAsB,KAAK;AACzB,cAAE;AACF,cAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEhE,MAAM,eAAe,CAAC,gBAAgB,EAAE,GAAG,EAAE,WAAW,CAAC;AACzD,QAAA,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAA,uBAAA,CAAyB,CAAC;;IAChD,OAAO,GAAG,EAAE;AACZ,QAAA,OAAO,CAAC,KAAK,CACX,CAAA,IAAA,EAAO,GAAG,CAAA,QAAA,CAAU,EACpB,GAAG,YAAY,KAAK,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC7D;AACD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;;AAEnB;;;;"}

package/dist/functions/workspace-utils/run-cmd-in-stages.d.mts

@@ -0,0 +1,19 @@
+#!/usr/bin/env tsx
+/**
+ * Executes a npm script command across all workspace packages in dependency order stages.
+ * Packages are grouped into stages where each stage contains packages whose
+ * dependencies have been completed in previous stages.
+ * @param options - Configuration options for the staged execution
+ * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.cmd - The npm script command to execute in each package
+ * @param options.concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @returns A promise that resolves when all stages have completed execution
+ */
+export declare const runCmdInStagesAcrossWorkspaces: ({ rootPackageJsonDir, cmd, concurrency, filterWorkspacePattern, }: Readonly<{
+    rootPackageJsonDir: string;
+    cmd: string;
+    concurrency?: number;
+    filterWorkspacePattern?: (packageName: string) => boolean;
+}>) => Promise<void>;
+//# sourceMappingURL=run-cmd-in-stages.d.mts.map

package/dist/functions/workspace-utils/run-cmd-in-stages.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cmd-in-stages.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/run-cmd-in-stages.mts"],"names":[],"mappings":";AAKA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAAU,mEAKlD,QAAQ,CAAC;IACV,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3D,CAAC,KAAG,OAAO,CAAC,IAAI,CAkBhB,CAAC"}

package/dist/functions/workspace-utils/run-cmd-in-stages.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env tsx
+import { executeStages } from './execute-parallel.mjs';
+import { getWorkspacePackages } from './get-workspace-packages.mjs';
+
+/**
+ * Executes a npm script command across all workspace packages in dependency order stages.
+ * Packages are grouped into stages where each stage contains packages whose
+ * dependencies have been completed in previous stages.
+ * @param options - Configuration options for the staged execution
+ * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.cmd - The npm script command to execute in each package
+ * @param options.concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @returns A promise that resolves when all stages have completed execution
+ */
+const runCmdInStagesAcrossWorkspaces = async ({ rootPackageJsonDir, cmd, concurrency = 3, filterWorkspacePattern, }) => {
+    try {
+        const packages = await getWorkspacePackages(rootPackageJsonDir);
+        const filteredPackages = filterWorkspacePattern === undefined
+            ? packages
+            : packages.filter((pkg) => filterWorkspacePattern(pkg.name));
+        await executeStages(filteredPackages, cmd, concurrency);
+        console.log(`\n✅ ${cmd} completed successfully`);
+    }
+    catch (err) {
+        console.error(`\n❌ ${cmd} failed:`, err instanceof Error ? err.message : (err?.toString() ?? ''));
+        process.exit(1);
+    }
+};
+
+export { runCmdInStagesAcrossWorkspaces };
+//# sourceMappingURL=run-cmd-in-stages.mjs.map

package/dist/functions/workspace-utils/run-cmd-in-stages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cmd-in-stages.mjs","sources":["../../../src/functions/workspace-utils/run-cmd-in-stages.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA;;;;;;;;;;AAUG;AACI,MAAM,8BAA8B,GAAG,OAAO,EACnD,kBAAkB,EAClB,GAAG,EACH,WAAW,GAAG,CAAC,EACf,sBAAsB,GAMtB,KAAmB;AACnB,IAAA,IAAI;AACF,QAAA,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,kBAAkB,CAAC;AAE/D,QAAA,MAAM,gBAAgB,GACpB,sBAAsB,KAAK;AACzB,cAAE;AACF,cAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEhE,MAAM,aAAa,CAAC,gBAAgB,EAAE,GAAG,EAAE,WAAW,CAAC;AACvD,QAAA,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAA,uBAAA,CAAyB,CAAC;;IAChD,OAAO,GAAG,EAAE;AACZ,QAAA,OAAO,CAAC,KAAK,CACX,CAAA,IAAA,EAAO,GAAG,CAAA,QAAA,CAAU,EACpB,GAAG,YAAY,KAAK,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC7D;AACD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;;AAEnB;;;;"}

package/dist/functions/workspace-utils/types.d.mts

@@ -0,0 +1,7 @@
+export type Package = Readonly<{
+    name: string;
+    path: string;
+    packageJson: JsonValue;
+    dependencies: ReadonlyRecord<string, string>;
+}>;
+//# sourceMappingURL=types.d.mts.map

package/dist/functions/workspace-utils/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/types.mts"],"names":[],"mappings":"AACA,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,SAAS,CAAC;IACvB,YAAY,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C,CAAC,CAAC"}

package/dist/functions/workspace-utils/types.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.mjs.map

package/dist/functions/workspace-utils/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/index.mjs

@@ -6,4 +6,8 @@ export { $ } from './functions/exec-async.mjs';
 export { formatDiffFrom, formatFiles, formatFilesList, formatUntracked } from './functions/format.mjs';
 export { genIndex } from './functions/gen-index.mjs';
 export { checkShouldRunTypeChecks } from './functions/should-run.mjs';
+export { executeParallel, executeStages } from './functions/workspace-utils/execute-parallel.mjs';
+export { getWorkspacePackages } from './functions/workspace-utils/get-workspace-packages.mjs';
+export { runCmdInParallelAcrossWorkspaces } from './functions/workspace-utils/run-cmd-in-parallel.mjs';
+export { runCmdInStagesAcrossWorkspaces } from './functions/workspace-utils/run-cmd-in-stages.mjs';
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-repo-utils",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "private": false,
   "keywords": [
     "typescript"
@@ -30,14 +30,14 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npm run z:node-esm -- ./scripts/cmd/build.mjs",
-    "check-all": "npm run z:node-esm -- ./scripts/cmd/check-all.mjs",
-    "check:ext": "npm run z:node-esm -- ./scripts/cmd/check-ext.mjs",
+    "build": "tsx ./scripts/cmd/build.mjs",
+    "check-all": "tsx ./scripts/cmd/check-all.mjs",
+    "check:ext": "tsx ./scripts/cmd/check-ext.mjs",
     "cspell": "cspell \"**\" --gitignore --gitignore-root ./ --no-progress",
-    "doc": "npm run z:node-esm -- ./scripts/cmd/gen-docs.mjs",
-    "fmt": "npm run z:node-esm -- ./scripts/cmd/fmt-diff.mjs",
+    "doc": "tsx ./scripts/cmd/gen-docs.mjs",
+    "fmt": "tsx ./scripts/cmd/fmt-diff.mjs",
     "fmt:full": "prettier --write .",
-    "gi": "npm run z:node-esm -- ./scripts/cmd/gi.mjs",
+    "gi": "tsx ./scripts/cmd/gi.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "md": "markdownlint-cli2",
@@ -50,7 +50,6 @@
     "tscw": "tsc --noEmit --watch",
     "type-check": "tsc --noEmit",
     "update-packages": "npx npm-check-updates -u --install always --reject @types/node",
-    "z:node-esm": "node --import tsx/esm",
     "z:vitest": "vitest --config ./configs/vitest.config.ts"
   },
   "dependencies": {
@@ -58,7 +57,7 @@
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
     "prettier": "^3.6.2",
-    "ts-data-forge": "^1.2.0"
+    "ts-data-forge": "^2.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.30.0",
@@ -72,21 +71,21 @@
     "@semantic-release/github": "^11.0.3",
     "@semantic-release/npm": "^12.0.1",
     "@semantic-release/release-notes-generator": "^14.0.3",
-    "@types/node": "^20.19.1",
+    "@types/node": "^20.19.4",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "conventional-changelog-conventionalcommits": "^9.0.0",
     "cspell": "^9.1.2",
     "dedent": "^1.6.0",
-    "eslint": "^9.29.0",
+    "eslint": "^9.30.1",
     "markdownlint-cli2": "^0.18.1",
     "prettier-plugin-organize-imports": "^4.1.0",
-    "prettier-plugin-packagejson": "^2.5.15",
+    "prettier-plugin-packagejson": "^2.5.18",
     "rollup": "^4.44.1",
-    "semantic-release": "^24.2.5",
+    "semantic-release": "^24.2.6",
     "ts-type-forge": "^2.0.3",
     "tsx": "^4.20.3",
-    "typedoc": "^0.28.5",
+    "typedoc": "^0.28.7",
     "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.0",

package/src/functions/index.mts

@@ -6,3 +6,4 @@ export * from './exec-async.mjs';
 export * from './format.mjs';
 export * from './gen-index.mjs';
 export * from './should-run.mjs';
+export * from './workspace-utils/index.mjs';

package/src/functions/should-run.mts

@@ -2,6 +2,20 @@ import { pipe, Result } from 'ts-data-forge';
 import '../node-global.mjs';
 import { getDiffFrom } from './diff.mjs';
 
+/**
+ * Checks if TypeScript type checks should run based on the diff from origin/main.
+ * Skips type checks if all changed files are documentation files, spell check config,
+ * or other non-TypeScript files that don't affect type checking.
+ *
+ * Ignored file patterns:
+ * - '.cspell.json'
+ * - '**.md'
+ * - '**.txt'
+ * - 'docs/**'
+ *
+ * @returns A promise that resolves when the check is complete. Sets GITHUB_OUTPUT
+ * environment variable with should_run=true/false if running in GitHub Actions.
+ */
 export const checkShouldRunTypeChecks = async (): Promise<void> => {
   // paths-ignore:
   //   - '.cspell.json'

package/src/functions/workspace-utils/execute-parallel.mts

@@ -0,0 +1,247 @@
+import { spawn } from 'child_process';
+import {
+  createPromise,
+  hasKey,
+  isNotUndefined,
+  isRecord,
+  pipe,
+  Result,
+} from 'ts-data-forge';
+import '../../node-global.mjs';
+import { type Package } from './types.mjs';
+
+const DEBUG = false as boolean;
+
+/**
+ * Executes a npm script across multiple packages in parallel with a concurrency limit.
+ * @param packages - Array of Package objects to execute the script in
+ * @param scriptName - The name of the npm script to execute
+ * @param concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @returns A promise that resolves to an array of execution results
+ */
+export const executeParallel = async (
+  packages: readonly Package[],
+  scriptName: string,
+  concurrency: number = 3,
+): Promise<
+  readonly Result<Readonly<{ code?: number; skipped?: boolean }>, Error>[]
+> => {
+  const mut_resultPromises: Promise<
+    Result<Readonly<{ code?: number; skipped?: boolean }>, Error>
+  >[] = [];
+
+  const executing = new Set<Promise<unknown>>();
+
+  for (const pkg of packages) {
+    const promise = executeScript(pkg, scriptName);
+
+    mut_resultPromises.push(promise);
+
+    const wrappedPromise = promise.finally(() => {
+      executing.delete(wrappedPromise);
+      if (DEBUG) {
+        console.debug('executing size', executing.size);
+      }
+    });
+
+    executing.add(wrappedPromise);
+
+    if (DEBUG) {
+      console.debug('executing size', executing.size);
+    }
+
+    // If we reach concurrency limit, wait for one to finish
+    if (executing.size >= concurrency) {
+      // eslint-disable-next-line no-await-in-loop
+      await Promise.race(executing);
+    }
+  }
+
+  return Promise.all(mut_resultPromises);
+};
+
+/**
+ * Executes a npm script across packages in dependency order stages.
+ * Packages are grouped into stages where each stage contains packages whose
+ * dependencies have been completed in previous stages.
+ * @param packages - Array of Package objects to execute the script in
+ * @param scriptName - The name of the npm script to execute
+ * @param concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @returns A promise that resolves when all stages are complete
+ */
+export const executeStages = async (
+  packages: readonly Package[],
+  scriptName: string,
+  concurrency: number = 3,
+): Promise<void> => {
+  const dependencyGraph = buildDependencyGraph(packages);
+
+  const sorted = topologicalSortPackages(packages, dependencyGraph);
+
+  const stages: (readonly Package[])[] = [];
+  const completed = new Set<string>();
+
+  while (completed.size < sorted.length) {
+    const stage: Package[] = [];
+
+    for (const pkg of sorted) {
+      if (completed.has(pkg.name)) continue;
+
+      const deps = dependencyGraph.get(pkg.name) ?? [];
+      const depsCompleted = deps.every((dep) => completed.has(dep));
+
+      if (depsCompleted) {
+        stage.push(pkg);
+      }
+    }
+
+    if (stage.length === 0) {
+      throw new Error('Circular dependency detected');
+    }
+
+    stages.push(stage);
+    for (const pkg of stage) completed.add(pkg.name);
+  }
+
+  console.log(`\nExecuting ${scriptName} in ${stages.length} stages...\n`);
+
+  for (const [i, stage] of stages.entries()) {
+    if (stage.length > 0) {
+      console.log(`Stage ${i + 1}: ${stage.map((p) => p.name).join(', ')}`);
+      // eslint-disable-next-line no-await-in-loop
+      await executeParallel(stage, scriptName, concurrency);
+    }
+  }
+};
+
+/**
+ * Executes a npm script in a specific package directory.
+ * @param pkg - The package object containing path and metadata
+ * @param scriptName - The name of the npm script to execute
+ * @param options - Configuration options
+ * @param options.prefix - Whether to prefix output with package name (default: true)
+ * @returns A promise that resolves to execution result with exit code or skipped flag
+ */
+const executeScript = (
+  pkg: Package,
+  scriptName: string,
+  { prefix = true }: Readonly<{ prefix?: boolean }> = {},
+): Promise<Result<Readonly<{ code?: number; skipped?: boolean }>, Error>> =>
+  pipe(
+    createPromise(
+      (
+        resolve: (
+          value: Readonly<{ code?: number; skipped?: boolean }>,
+        ) => void,
+        reject: (reason: unknown) => void,
+      ) => {
+        const packageJsonScripts =
+          isRecord(pkg.packageJson) && isRecord(pkg.packageJson['scripts'])
+            ? pkg.packageJson['scripts']
+            : {};
+
+        const hasScript = hasKey(packageJsonScripts, scriptName);
+        if (!hasScript) {
+          resolve({ skipped: true });
+          return;
+        }
+
+        const prefixStr = prefix ? `[${pkg.name}] ` : '';
+        const proc = spawn('npm', ['run', scriptName], {
+          cwd: pkg.path,
+          shell: true,
+          stdio: 'pipe',
+        });
+
+        proc.stdout.on('data', (data: Readonly<Buffer>) => {
+          process.stdout.write(prefixStr + data.toString());
+        });
+
+        proc.stderr.on('data', (data: Readonly<Buffer>) => {
+          process.stderr.write(prefixStr + data.toString());
+        });
+
+        proc.on('close', (code: number | null) => {
+          if (code === 0) {
+            resolve({ code });
+          } else {
+            reject(new Error(`${pkg.name} exited with code ${code}`));
+          }
+        });
+
+        proc.on('error', reject);
+      },
+    ),
+  ).map((result) =>
+    result.then(
+      Result.mapErr((err) => {
+        const errorMessage: string =
+          err instanceof Error
+            ? err.message
+            : isRecord(err) && hasKey(err, 'message')
+              ? (err.message?.toString() ?? 'Unknown error message')
+              : 'Unknown error';
+
+        console.error(`\nError in ${pkg.name}:`, errorMessage);
+        return err instanceof Error ? err : new Error(errorMessage);
+      }),
+    ),
+  ).value;
+
+/**
+ * Performs a topological sort on packages based on their dependencies,
+ * ensuring dependencies are ordered before their dependents.
+ * @param packages - Array of Package objects to sort
+ * @returns An array of packages in dependency order (dependencies first)
+ */
+const topologicalSortPackages = (
+  packages: readonly Package[],
+  dependencyGraph: ReadonlyMap<string, readonly string[]>,
+): readonly Package[] => {
+  const visited = new Set<string>();
+  const result: string[] = [];
+
+  const packageMap = new Map(packages.map((p) => [p.name, p]));
+
+  const visit = (pkgName: string): void => {
+    if (visited.has(pkgName)) return;
+    visited.add(pkgName);
+
+    const deps = dependencyGraph.get(pkgName) ?? [];
+    for (const dep of deps) {
+      visit(dep);
+    }
+
+    result.push(pkgName);
+  };
+
+  for (const pkg of packages) {
+    visit(pkg.name);
+  }
+
+  return result
+    .map((pkgName) => packageMap.get(pkgName))
+    .filter(isNotUndefined);
+};
+
+/**
+ * Builds a dependency graph from the given packages, mapping each package name
+ * to its internal workspace dependencies.
+ * @param packages - Array of Package objects to analyze
+ * @returns A readonly map where keys are package names and values are arrays of their dependency package names
+ */
+const buildDependencyGraph = (
+  packages: readonly Package[],
+): ReadonlyMap<string, readonly string[]> => {
+  const packageMap = new Map(packages.map((p) => [p.name, p]));
+  const graph = new Map<string, readonly string[]>();
+
+  for (const pkg of packages) {
+    const deps = Object.keys(pkg.dependencies).filter((depName) =>
+      packageMap.has(depName),
+    );
+    graph.set(pkg.name, deps);
+  }
+
+  return graph;
+};

package/src/functions/workspace-utils/get-workspace-packages.mts

@@ -0,0 +1,118 @@
+#!/usr/bin/env tsx
+
+import {
+  hasKey,
+  isNotUndefined,
+  isRecord,
+  isString,
+  Json,
+  Result,
+} from 'ts-data-forge';
+import '../../node-global.mjs';
+import { type Package } from './types.mjs';
+
+/**
+ * Retrieves all workspace packages from a monorepo based on the workspace patterns
+ * defined in the root package.json file.
+ * @param rootPackageJsonDir - The directory containing the root package.json file
+ * @returns A promise that resolves to an array of Package objects containing package metadata
+ */
+export const getWorkspacePackages = async (
+  rootPackageJsonDir: string,
+): Promise<readonly Package[]> => {
+  // Read root package.json
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const rootPackageJson: JsonValue = JSON.parse(
+    await fs.readFile(path.join(rootPackageJsonDir, 'package.json'), 'utf8'),
+  );
+
+  const workspacePatterns: readonly string[] = getStrArrayFromJsonValue(
+    rootPackageJson,
+    'workspaces',
+  );
+
+  const packagePromises = workspacePatterns.map(async (pattern) => {
+    const matches = await glob(pattern, {
+      cwd: rootPackageJsonDir,
+      ignore: ['**/node_modules/**'],
+      onlyDirectories: true,
+      absolute: true,
+    });
+
+    const packageJsonList: readonly (
+      | readonly [string, JsonValue]
+      | undefined
+    )[] = await Promise.all(
+      matches.map(async (match) => {
+        const maybePackagePath = path.join(match, 'package.json');
+
+        const result = await Result.fromPromise(
+          fs.readFile(maybePackagePath, 'utf8'),
+        );
+
+        if (Result.isErr(result)) return undefined;
+
+        const parsed = Json.parse(result.value);
+
+        if (Result.isErr(parsed)) return undefined;
+
+        return [maybePackagePath, parsed.value] as const;
+      }),
+    );
+
+    const packageInfos: readonly Package[] = await Promise.all(
+      packageJsonList
+        .filter(isNotUndefined)
+        .map(([packagePath, packageJson]) => ({
+          name: getStrFromJsonValue(packageJson, 'name'),
+          path: path.dirname(packagePath),
+          packageJson,
+          dependencies: {
+            ...getKeyValueRecordFromJsonValue(packageJson, 'dependencies'),
+            ...getKeyValueRecordFromJsonValue(packageJson, 'devDependencies'),
+            ...getKeyValueRecordFromJsonValue(packageJson, 'peerDependencies'),
+          },
+        })),
+    );
+
+    return packageInfos;
+  });
+
+  const allPackageArrays = await Promise.all(packagePromises);
+  const finalPackages = allPackageArrays.flat();
+
+  return finalPackages;
+};
+
+const getStrFromJsonValue = (value: JsonValue, key: string): string =>
+  isRecord(value) && hasKey(value, key) && isString(value[key])
+    ? value[key]
+    : '';
+
+const getStrArrayFromJsonValue = (
+  value: JsonValue,
+  key: string,
+): readonly string[] =>
+  isRecord(value) &&
+  hasKey(value, key) &&
+  Array.isArray(value[key]) &&
+  value[key].every(isString)
+    ? value[key]
+    : [];
+
+const getKeyValueRecordFromJsonValue = (
+  value: JsonValue,
+  key: string,
+): ReadonlyRecord<string, string> => {
+  if (!isRecord(value) || !hasKey(value, key)) {
+    return {};
+  }
+  const obj = value[key];
+  if (!isRecord(obj)) {
+    return {};
+  }
+  const entries = Object.entries(obj).filter(
+    (entry): entry is [string, string] => isString(entry[1]),
+  );
+  return Object.fromEntries(entries);
+};

package/src/functions/workspace-utils/index.mts

@@ -0,0 +1,5 @@
+export * from './execute-parallel.mjs';
+export * from './get-workspace-packages.mjs';
+export * from './run-cmd-in-parallel.mjs';
+export * from './run-cmd-in-stages.mjs';
+export * from './types.mjs';

package/src/functions/workspace-utils/run-cmd-in-parallel.mts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+
+import { executeParallel } from './execute-parallel.mjs';
+import { getWorkspacePackages } from './get-workspace-packages.mjs';
+
+/**
+ * Executes a npm script command across all workspace packages in parallel.
+ * @param options - Configuration options for the parallel execution
+ * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.cmd - The npm script command to execute in each package
+ * @param options.concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @returns A promise that resolves when all packages have completed execution
+ */
+export const runCmdInParallelAcrossWorkspaces = async ({
+  rootPackageJsonDir,
+  cmd,
+  concurrency = 3,
+  filterWorkspacePattern,
+}: Readonly<{
+  rootPackageJsonDir: string;
+  cmd: string;
+  concurrency?: number;
+  filterWorkspacePattern?: (packageName: string) => boolean;
+}>): Promise<void> => {
+  try {
+    const packages = await getWorkspacePackages(rootPackageJsonDir);
+
+    const filteredPackages =
+      filterWorkspacePattern === undefined
+        ? packages
+        : packages.filter((pkg) => filterWorkspacePattern(pkg.name));
+
+    await executeParallel(filteredPackages, cmd, concurrency);
+    console.log(`\n✅ ${cmd} completed successfully`);
+  } catch (err) {
+    console.error(
+      `\n❌ ${cmd} failed:`,
+      err instanceof Error ? err.message : (err?.toString() ?? ''),
+    );
+    process.exit(1);
+  }
+};

package/src/functions/workspace-utils/run-cmd-in-stages.mts

@@ -0,0 +1,45 @@
+#!/usr/bin/env tsx
+
+import { executeStages } from './execute-parallel.mjs';
+import { getWorkspacePackages } from './get-workspace-packages.mjs';
+
+/**
+ * Executes a npm script command across all workspace packages in dependency order stages.
+ * Packages are grouped into stages where each stage contains packages whose
+ * dependencies have been completed in previous stages.
+ * @param options - Configuration options for the staged execution
+ * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.cmd - The npm script command to execute in each package
+ * @param options.concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @returns A promise that resolves when all stages have completed execution
+ */
+export const runCmdInStagesAcrossWorkspaces = async ({
+  rootPackageJsonDir,
+  cmd,
+  concurrency = 3,
+  filterWorkspacePattern,
+}: Readonly<{
+  rootPackageJsonDir: string;
+  cmd: string;
+  concurrency?: number;
+  filterWorkspacePattern?: (packageName: string) => boolean;
+}>): Promise<void> => {
+  try {
+    const packages = await getWorkspacePackages(rootPackageJsonDir);
+
+    const filteredPackages =
+      filterWorkspacePattern === undefined
+        ? packages
+        : packages.filter((pkg) => filterWorkspacePattern(pkg.name));
+
+    await executeStages(filteredPackages, cmd, concurrency);
+    console.log(`\n✅ ${cmd} completed successfully`);
+  } catch (err) {
+    console.error(
+      `\n❌ ${cmd} failed:`,
+      err instanceof Error ? err.message : (err?.toString() ?? ''),
+    );
+    process.exit(1);
+  }
+};

package/src/functions/workspace-utils/types.mts

@@ -0,0 +1,7 @@
+// Get all workspace packages
+export type Package = Readonly<{
+  name: string;
+  path: string;
+  packageJson: JsonValue;
+  dependencies: ReadonlyRecord<string, string>;
+}>;