@vltpkg/workspaces 1.0.0-rc.23 → 1.0.0-rc.24

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import type { DepID } from '@vltpkg/dep-id';
+import { PackageJson } from '@vltpkg/package-json';
+import type { NormalizedManifest } from '@vltpkg/types';
+import type { DepResults } from '@vltpkg/graph-run';
+import { PathScurry } from 'path-scurry';
+export type WorkspacesLoadedConfig = {
+    workspace?: string[];
+    'workspace-group'?: string[];
+};
+/**
+ * The object passed to the constructor or {@link Monorepo#load} to limit which
+ * {@link Workspace Workspaces} get loaded.
+ */
+export type LoadQuery = {
+    /**
+     * A glob pattern string, or an array of them. Only workspaces found
+     * in paths matched will be loaded.
+     */
+    paths?: string[] | string;
+    /**
+     * A string, or an array of strings. If set, only workspaces in the
+     * specified groups named will be included, if set.
+     */
+    groups?: string[] | string;
+};
+/**
+ * Canonical form of the {@link WorkspaceConfig}, used
+ * internally for consistency.
+ */
+export type WorkspaceConfigObject = Record<string, string[]>;
+/**
+ * Allowed datatype in the `workspaces` field of the `vlt.json` file.
+ */
+export type WorkspaceConfig = string[] | WorkspaceConfigObject | string;
+/**
+ * Turn a {@link WorkspaceConfig} into a
+ * {@link WorkspaceConfigObject}, or throw if it's not valid.
+ */
+export declare const asWSConfig: (conf: unknown, path?: string) => WorkspaceConfigObject;
+/**
+ * Throw if the provided value is not a valid {@link WorkspaceConfig}
+ */
+export declare const assertWSConfig: (conf: unknown, path?: string) => asserts conf is WorkspaceConfig;
+export type MonorepoOptions = {
+    /**
+     * A {@link PackageJson} object, for sharing manifest caches
+     */
+    packageJson?: PackageJson;
+    /**
+     * A {@link PathScurry} object, for use in globs
+     */
+    scurry?: PathScurry;
+    /**
+     * Parsed normalized contents of the workspaces from a `vlt.json`
+     * file
+     */
+    config?: WorkspaceConfigObject;
+    /**
+     * If set, then {@link Monorepo#load} will be called immediately with
+     * this argument.
+     */
+    load?: LoadQuery;
+};
+/**
+ * Class representing a Monorepo containing multiple workspaces.
+ *
+ * Does not automatically look up the root, but that can be provided by
+ * running `Config.load()`, since it stops seeking the route when a
+ * `vlt.json` file is encountered.
+ */
+export declare class Monorepo {
+    #private;
+    /** The project root where vlt.json is found */
+    projectRoot: string;
+    /** Scurry object to cache all filesystem calls (mostly globs) */
+    scurry: PathScurry;
+    packageJson: PackageJson;
+    /**
+     * Number of {@link Workspace} objects loaded in this Monorepo
+     */
+    get size(): number;
+    constructor(projectRoot: string, options?: MonorepoOptions);
+    /**
+     * Load the workspace definitions from vlt.json,
+     * canonicalizing the result into the effective `{[group:string]:string[]}`
+     * form.
+     *
+     * Eg:
+     * - `"src/*"` => `{packages:["src/*"]}`
+     * - `{"apps": "src/*"}` => `{apps: ["src/*"]}`
+     */
+    get config(): WorkspaceConfigObject;
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    [Symbol.iterator](): Generator<Workspace, void, void>;
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<Workspace, void, void>;
+    /**
+     * By default, loads all workspaces reachable in the Monorepo.
+     *
+     * If provided with one (`string`)or more (`string[]`) group names in
+     * the {@link LoadQuery#groups} field, then only Workspaces in the named
+     * group(s) will be considered. Note that group names are unique string
+     * matches, not globs.
+     *
+     * If provided with a set of arbitrary path arguments, then only paths
+     * patching the provided pattern(s) will be included.
+     *
+     * These two options intersect, so
+     * `load({groups:'foo', paths:'./foo/[xy]*'})` will only load the workspaces
+     * in the group `foo` that match the paths glob.
+     */
+    load(query?: LoadQuery): this;
+    /**
+     * Return the array of workspace dependencies that are found in
+     * the loaded set, for use in calculating dependency graph order for
+     * build operations.
+     *
+     * This does *not* get the full set of dependencies, or expand any
+     * `workspace:` dependencies that are not loaded.
+     *
+     * Call with the `forceLoad` param set to `true` to attempt a full
+     * load if any deps are not currently loaded.
+     */
+    getDeps(ws: Workspace, forceLoad?: boolean): Workspace[];
+    onCycle(_ws: Workspace, _cycle: Workspace[], _depPath: Workspace[]): void;
+    /**
+     * Return the set of workspaces in the named group.
+     * If the group is not one we know about, then undefined is returned.
+     */
+    group(group: string): Set<Workspace> | undefined;
+    /**
+     * Get a loaded workspace by path or name.
+     *
+     * Note that this can only return workspaces that were ingested via a
+     * previous call to {@link Monorepo#load}.
+     */
+    get(nameOrPath: string): Workspace | undefined;
+    /**
+     * get the list of all loaded workspace names used as keys
+     */
+    names(): Generator<string, void, unknown>;
+    /**
+     * get the list of all loaded workspace paths used as keys
+     */
+    paths(): Generator<string, void, unknown>;
+    /**
+     * get the workspace objects in no particular order.
+     * this is ever so slightly faster than iterating, because it doesn't
+     * explore the graph to yield results in topological dependency order,
+     * and should be used instead when order doesn't matter.
+     */
+    values(): Generator<Workspace, void, unknown>;
+    /**
+     * Get all the keys (package names and paths) for loaded workspaces.
+     * Union of {@link Monorepo#names} and {@link Monorepo#paths}
+     */
+    keys(): Generator<string, void, unknown>;
+    /**
+     * Filter the monorepo object yielding the workspace objects that matches
+     * either of the {@link WorkspacesLoadedConfig} options provided, in as close
+     * to topological dependency order as possible.
+     */
+    filter({ workspace: namesOrPaths, 'workspace-group': groupName, }: WorkspacesLoadedConfig): Generator<Workspace, void, unknown>;
+    /**
+     * Run an operation asynchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `run<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    run<R>(operation: (s: Workspace, signal: AbortSignal, depResults: DepResults<Workspace, R>) => Promise<R> | R, forceLoad?: boolean): Promise<Map<Workspace, R>>;
+    /**
+     * Run an operation synchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `runSync<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    runSync<R>(operation: (s: Workspace, signal: AbortSignal, depResults: DepResults<Workspace, R>) => R, forceLoad?: boolean): Map<Workspace, R>;
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Returns undefined if the project is not a monorepo workspaces
+     * root, otherwise returns the loaded Monorepo.
+     */
+    static maybeLoad(projectRoot: string, options?: MonorepoOptions): Monorepo | undefined;
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Throws if called on a directory that is not a workspaces root.
+     */
+    static load(projectRoot: string, options?: MonorepoOptions): Monorepo;
+}
+export declare const workspaceCache: Map<string, Workspace>;
+/**
+ * Class representing a single Workspace in a {@link Monorepo}
+ */
+export declare class Workspace {
+    #private;
+    id: DepID;
+    path: string;
+    fullpath: string;
+    manifest: NormalizedManifest;
+    groups: string[];
+    name: string;
+    constructor(path: string, manifest: NormalizedManifest, fullpath: string);
+    get keys(): string[];
+}

package/dist/index.js

@@ -0,0 +1,558 @@
+import { joinDepIDTuple } from '@vltpkg/dep-id';
+import { error } from '@vltpkg/error-cause';
+import { PackageJson } from '@vltpkg/package-json';
+import { load } from '@vltpkg/vlt-json';
+import { globSync } from 'glob';
+import { graphRun, graphRunSync } from '@vltpkg/graph-run';
+import { minimatch } from 'minimatch';
+import { basename, posix, resolve } from 'node:path';
+import { PathScurry } from 'path-scurry';
+/**
+ * Check if an error (potentially wrapped by @vltpkg/error-cause) is
+ * caused by a JSON syntax error. The error chain from PackageJson.read()
+ * is: Error { cause: { path, cause: SyntaxError } }
+ */
+/* c8 ignore start - defensive helper, primary path tested via workspace integration */
+const isSyntaxError = (err) => {
+    if (err instanceof SyntaxError)
+        return true;
+    if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause instanceof SyntaxError)
+            return true;
+        if (cause && typeof cause === 'object' && 'cause' in cause) {
+            return (cause.cause instanceof SyntaxError);
+        }
+    }
+    return false;
+};
+/**
+ * Turn a {@link WorkspaceConfig} into a
+ * {@link WorkspaceConfigObject}, or throw if it's not valid.
+ */
+export const asWSConfig = (conf, path) => {
+    assertWSConfig(conf, path);
+    return (typeof conf === 'string' ? { packages: [conf] }
+        : Array.isArray(conf) ? { packages: conf }
+            : Object.fromEntries(Object.entries(conf).map(([k, v]) => [
+                k,
+                typeof v === 'string' ? [v] : v,
+            ])));
+};
+/**
+ * Throw if the provided value is not a valid {@link WorkspaceConfig}
+ */
+export const assertWSConfig = (conf, path) => {
+    if (typeof conf === 'string')
+        return;
+    if (Array.isArray(conf)) {
+        for (const c of conf) {
+            if (typeof c !== 'string') {
+                throw error('Invalid workspace definition', {
+                    path,
+                    found: c,
+                    wanted: 'string',
+                });
+            }
+        }
+        return;
+    }
+    if (conf && typeof conf === 'object') {
+        for (const [group, value] of Object.entries(conf)) {
+            if (typeof value === 'string')
+                continue;
+            if (Array.isArray(value)) {
+                for (const c of value) {
+                    if (typeof c !== 'string') {
+                        throw error('Invalid workspace definition', {
+                            path,
+                            name: group,
+                            found: c,
+                            wanted: 'string',
+                        });
+                    }
+                }
+                continue;
+            }
+            throw error('Invalid workspace definition', {
+                path,
+                name: group,
+                found: value,
+                wanted: 'string | string[]',
+            });
+        }
+        return;
+    }
+    throw error('Invalid workspace definition', {
+        path,
+        found: conf,
+        wanted: 'string | string[] | { [group: string]: string | string[] }',
+    });
+};
+/**
+ * Class representing a Monorepo containing multiple workspaces.
+ *
+ * Does not automatically look up the root, but that can be provided by
+ * running `Config.load()`, since it stops seeking the route when a
+ * `vlt.json` file is encountered.
+ */
+export class Monorepo {
+    /** The project root where vlt.json is found */
+    projectRoot;
+    /** Scurry object to cache all filesystem calls (mostly globs) */
+    scurry;
+    // maps both name and path to the workspace objects
+    #workspaces = new Map();
+    #groups = new Map();
+    #config;
+    packageJson;
+    /**
+     * Number of {@link Workspace} objects loaded in this Monorepo
+     */
+    get size() {
+        return [...this.values()].length;
+    }
+    constructor(projectRoot, options = {}) {
+        this.projectRoot = resolve(projectRoot);
+        this.scurry = options.scurry ?? new PathScurry(projectRoot);
+        this.packageJson = options.packageJson ?? new PackageJson();
+        this.#config = options.config;
+        if (options.load)
+            this.load(options.load);
+    }
+    /**
+     * Load the workspace definitions from vlt.json,
+     * canonicalizing the result into the effective `{[group:string]:string[]}`
+     * form.
+     *
+     * Eg:
+     * - `"src/*"` => `{packages:["src/*"]}`
+     * - `{"apps": "src/*"}` => `{apps: ["src/*"]}`
+     */
+    get config() {
+        if (this.#config)
+            return this.#config;
+        this.#config = asWSConfig(load('workspaces', assertWSConfig) ?? {});
+        return this.#config;
+    }
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    *[Symbol.iterator]() {
+        const [ws] = [...this.values()];
+        if (!ws)
+            return;
+        // leverage the fact that graphRun returns results in
+        // as close to topological order as possible.
+        for (const workspace of this.runSync(() => { }).keys()) {
+            yield workspace;
+        }
+    }
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    async *[Symbol.asyncIterator]() {
+        const [ws] = [...this.values()];
+        if (!ws)
+            return;
+        for (const workspace of (await this.run(() => { })).keys()) {
+            yield workspace;
+        }
+    }
+    /**
+     * By default, loads all workspaces reachable in the Monorepo.
+     *
+     * If provided with one (`string`)or more (`string[]`) group names in
+     * the {@link LoadQuery#groups} field, then only Workspaces in the named
+     * group(s) will be considered. Note that group names are unique string
+     * matches, not globs.
+     *
+     * If provided with a set of arbitrary path arguments, then only paths
+     * patching the provided pattern(s) will be included.
+     *
+     * These two options intersect, so
+     * `load({groups:'foo', paths:'./foo/[xy]*'})` will only load the workspaces
+     * in the group `foo` that match the paths glob.
+     */
+    load(query = {}) {
+        const paths = new Set(typeof query.paths === 'string' ?
+            [query.paths]
+            : (query.paths ?? []));
+        const groups = new Set(typeof query.groups === 'string' ?
+            [query.groups]
+            : (query.groups ?? []));
+        const groupsExpanded = {};
+        for (const [group, pattern] of Object.entries(this.config)) {
+            if (groups.size && !groups.has(group))
+                continue;
+            groupsExpanded[group] = this.#glob(pattern);
+        }
+        const filter = paths.size ? this.#glob([...paths]) : paths;
+        // if we specified paths, but none matched, nothing to do
+        if (paths.size && !filter.size)
+            return this;
+        for (const [group, matches] of Object.entries(groupsExpanded)) {
+            for (const path of matches) {
+                if (filter.size && !filter.has(path))
+                    continue;
+                this.#loadWS(path, group);
+            }
+        }
+        return this;
+    }
+    // Either load a workspace from disk, or from our internal set,
+    // and assign it to the named group
+    #loadWS(path, group) {
+        const fullpath = resolve(this.projectRoot, path);
+        const loaded = this.#workspaces.get(fullpath);
+        if (loaded)
+            return loaded;
+        const fromCache = workspaceCache.get(fullpath);
+        const manifest = fromCache?.manifest ?? this.packageJson.read(fullpath);
+        const ws = fromCache ?? new Workspace(path, manifest, fullpath);
+        if (group)
+            ws.groups.push(group);
+        // Check for duplicate workspace names
+        const existingWS = this.#workspaces.get(ws.name);
+        if (existingWS && existingWS.fullpath !== ws.fullpath) {
+            throw error('Duplicate workspace name found', {
+                name: ws.name,
+                path: this.projectRoot,
+                wanted: ws.fullpath,
+                found: existingWS.fullpath,
+            });
+        }
+        this.#workspaces.set(ws.fullpath, ws);
+        this.#workspaces.set(ws.path, ws);
+        this.#workspaces.set(ws.name, ws);
+        for (const name of ws.groups) {
+            const group = this.#groups.get(name) ?? new Set();
+            group.add(ws);
+            this.#groups.set(name, group);
+        }
+        return ws;
+    }
+    // can't be cached, because it's dependent on the matches set
+    // but still worthwhile to have it defined in one place
+    #globOptions(matches, parseErrors) {
+        // if the entry or any of its parent dirs are already matched,
+        // then we should not explore further down that directory tree.
+        // if we hit the projectRoot then stop searching.
+        const inMatches = (p) => {
+            return (!!p?.relativePosix() &&
+                (matches.has(p.relativePosix()) || inMatches(p.parent)));
+        };
+        return {
+            root: this.projectRoot,
+            cwd: this.projectRoot,
+            posix: true,
+            scurry: this.scurry,
+            withFileTypes: false,
+            ignore: {
+                childrenIgnored: p => basename(p.relativePosix()) === 'node_modules' ||
+                    inMatches(p),
+                // ignore if fails to load package.json
+                ignored: p => {
+                    p.lstatSync();
+                    const rel = p.relativePosix();
+                    if (!rel)
+                        return true;
+                    const maybeDelete = [];
+                    for (const m of matches) {
+                        if (rel.startsWith(m + '/'))
+                            return true;
+                        if (m.startsWith(rel + '/')) {
+                            maybeDelete.push(m);
+                        }
+                    }
+                    if (!p.isDirectory())
+                        return true;
+                    const pj = p.resolve('package.json').lstatSync();
+                    if (!pj?.isFile())
+                        return true;
+                    try {
+                        this.packageJson.read(p.fullpath());
+                    }
+                    catch (err) {
+                        // Track JSON parse errors for later reporting.
+                        // We can't throw here because the glob is still running
+                        // and we don't yet know if this path is a true workspace
+                        // match or a subdirectory of another workspace.
+                        if (parseErrors && isSyntaxError(err)) {
+                            parseErrors.set(rel, err);
+                        }
+                        return true;
+                    }
+                    for (const m of maybeDelete) {
+                        matches.delete(m);
+                    }
+                    matches.add(rel);
+                    return false;
+                },
+            },
+        };
+    }
+    #glob(pattern) {
+        const matches = new Set();
+        const parseErrors = new Map();
+        globSync(pattern, this.#globOptions(matches, parseErrors));
+        // After the glob completes, check for JSON parse errors in paths
+        // that are NOT nested inside an already-matched workspace.
+        // Nested directories (like app/bar/badjson inside workspace app/bar)
+        // are legitimately ignored, but top-level workspace matches with
+        // broken package.json should surface an error.
+        for (const [rel, err] of parseErrors) {
+            let isNested = false;
+            for (const m of matches) {
+                if (rel.startsWith(m + '/')) {
+                    isNested = true;
+                    break;
+                }
+            }
+            if (!isNested) {
+                throw error(`Failed to parse package.json in workspace "${rel}"`, {
+                    path: resolve(this.projectRoot, rel, 'package.json'),
+                    cause: err,
+                });
+            }
+        }
+        return matches;
+    }
+    /**
+     * Return the array of workspace dependencies that are found in
+     * the loaded set, for use in calculating dependency graph order for
+     * build operations.
+     *
+     * This does *not* get the full set of dependencies, or expand any
+     * `workspace:` dependencies that are not loaded.
+     *
+     * Call with the `forceLoad` param set to `true` to attempt a full
+     * load if any deps are not currently loaded.
+     */
+    getDeps(ws, forceLoad = false) {
+        // load manifest and find workspace: deps
+        // filter by those loaded
+        const { manifest } = ws;
+        const depWorkspaces = [];
+        let didForceLoad = false;
+        for (const depType of [
+            'dependencies',
+            'devDependencies',
+            'optionalDependencies',
+            'peerDependencies',
+        ]) {
+            const deps = manifest[depType];
+            if (!deps)
+                continue;
+            for (const [dep, spec] of Object.entries(deps)) {
+                if (spec.startsWith('workspace:')) {
+                    let depWS = this.#workspaces.get(dep);
+                    if (!depWS) {
+                        if (!forceLoad)
+                            continue;
+                        if (didForceLoad)
+                            continue;
+                        didForceLoad = true;
+                        this.load();
+                        depWS = this.#workspaces.get(dep);
+                        if (!depWS)
+                            continue;
+                    }
+                    depWorkspaces.push(depWS);
+                }
+            }
+        }
+        return depWorkspaces;
+    }
+    onCycle(_ws, _cycle, _depPath) {
+        // XXX - process logging? Need to say something like:
+        // Cyclical workspace dependency warning!
+        // When evaluating dependency ${ws.name} via ${
+        //   path.map(ws => ws.name).join(' -> ')
+        // }, a dependency cycle was detected: ${
+        //   cycle.map(ws => ws.name).join(' -> ')
+        // }. Operation will continue, but dependency order not guaranteed.`
+    }
+    /**
+     * Return the set of workspaces in the named group.
+     * If the group is not one we know about, then undefined is returned.
+     */
+    group(group) {
+        return this.#groups.get(group);
+    }
+    /**
+     * Get a loaded workspace by path or name.
+     *
+     * Note that this can only return workspaces that were ingested via a
+     * previous call to {@link Monorepo#load}.
+     */
+    get(nameOrPath) {
+        return this.#workspaces.get(nameOrPath);
+    }
+    /**
+     * get the list of all loaded workspace names used as keys
+     */
+    *names() {
+        for (const [key, ws] of this.#workspaces) {
+            if (key === ws.name)
+                yield key;
+        }
+    }
+    /**
+     * get the list of all loaded workspace paths used as keys
+     */
+    *paths() {
+        for (const [key, ws] of this.#workspaces) {
+            if (key === ws.path)
+                yield key;
+        }
+    }
+    /**
+     * get the workspace objects in no particular order.
+     * this is ever so slightly faster than iterating, because it doesn't
+     * explore the graph to yield results in topological dependency order,
+     * and should be used instead when order doesn't matter.
+     */
+    *values() {
+        const seen = new Set();
+        for (const ws of this.#workspaces.values()) {
+            if (seen.has(ws.fullpath))
+                continue;
+            seen.add(ws.fullpath);
+            yield ws;
+        }
+    }
+    /**
+     * Get all the keys (package names and paths) for loaded workspaces.
+     * Union of {@link Monorepo#names} and {@link Monorepo#paths}
+     */
+    *keys() {
+        for (const ws of this.values()) {
+            yield ws.path;
+            if (ws.name !== ws.path)
+                yield ws.name;
+        }
+    }
+    /**
+     * Filter the monorepo object yielding the workspace objects that matches
+     * either of the {@link WorkspacesLoadedConfig} options provided, in as close
+     * to topological dependency order as possible.
+     */
+    *filter({ workspace: namesOrPaths, 'workspace-group': groupName, }) {
+        const globPatternChecks = namesOrPaths?.map(glob => minimatch.filter(posix.join(glob)));
+        for (const ws of this) {
+            // check if any group has any of the provided group names
+            if (groupName?.some(i => ws.groups.includes(i))) {
+                yield ws;
+                continue;
+            }
+            // check if any workspace-provided name directly matches any of the
+            // configured workspaces by either name or file path
+            if (namesOrPaths
+                ?.map(i => posix.join(i))
+                .some(i => ws.keys.includes(i))) {
+                yield ws;
+                continue;
+            }
+            // check if one of the workspace values are matching glob patterns
+            if (ws.keys.some(key => globPatternChecks?.some(fn => fn(key)))) {
+                yield ws;
+            }
+        }
+    }
+    /**
+     * Run an operation asynchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `run<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    async run(operation, forceLoad = false) {
+        const [ws, ...rest] = [...this.#workspaces.values()];
+        if (!ws) {
+            throw error('No workspaces loaded', undefined, this.run);
+        }
+        return graphRun({
+            graph: [ws, ...rest],
+            getDeps: ws => this.getDeps(ws, forceLoad),
+            visit: async (ws, signal, _, depResults) => await operation(ws, signal, depResults),
+            onCycle: (ws, cycle, path) => this.onCycle(ws, cycle, path),
+        });
+    }
+    /**
+     * Run an operation synchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `runSync<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    runSync(operation, forceLoad = false) {
+        const [ws, ...rest] = [...this.#workspaces.values()];
+        if (!ws) {
+            throw error('No workspaces loaded', undefined, this.run);
+        }
+        return graphRunSync({
+            graph: [ws, ...rest],
+            getDeps: ws => this.getDeps(ws, forceLoad),
+            visit: (ws, signal, _, depResults) => operation(ws, signal, depResults),
+            onCycle: (ws, cycle, path) => this.onCycle(ws, cycle, path),
+        });
+    }
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Returns undefined if the project is not a monorepo workspaces
+     * root, otherwise returns the loaded Monorepo.
+     */
+    static maybeLoad(projectRoot, options = { load: {} }) {
+        const config = load('workspaces', assertWSConfig);
+        if (!config)
+            return;
+        return new Monorepo(projectRoot, { load: {}, ...options });
+    }
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Throws if called on a directory that is not a workspaces root.
+     */
+    static load(projectRoot, options = { load: {} }) {
+        const { load = {} } = options;
+        return new Monorepo(projectRoot, { ...options, load });
+    }
+}
+export const workspaceCache = new Map();
+/**
+ * Class representing a single Workspace in a {@link Monorepo}
+ */
+export class Workspace {
+    id;
+    path;
+    fullpath;
+    manifest;
+    groups = [];
+    name;
+    #keys;
+    constructor(path, manifest, fullpath) {
+        this.id = joinDepIDTuple(['workspace', path]);
+        workspaceCache.set(fullpath, this);
+        this.path = path;
+        this.fullpath = fullpath;
+        this.manifest = manifest;
+        this.name = manifest.name ?? path;
+    }
+    get keys() {
+        if (this.#keys) {
+            return this.#keys;
+        }
+        this.#keys = [this.name, this.path, this.fullpath];
+        return this.#keys;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/workspaces",
   "description": "Utility for working with vlt workspaces",
-  "version": "1.0.0-rc.23",
+  "version": "1.0.0-rc.24",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -12,12 +12,12 @@
     "email": "support@vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/dep-id": "1.0.0-rc.23",
-    "@vltpkg/error-cause": "1.0.0-rc.23",
-    "@vltpkg/graph-run": "1.0.0-rc.23",
-    "@vltpkg/package-json": "1.0.0-rc.23",
-    "@vltpkg/types": "1.0.0-rc.23",
-    "@vltpkg/vlt-json": "1.0.0-rc.23",
+    "@vltpkg/dep-id": "1.0.0-rc.24",
+    "@vltpkg/error-cause": "1.0.0-rc.24",
+    "@vltpkg/graph-run": "1.0.0-rc.24",
+    "@vltpkg/package-json": "1.0.0-rc.24",
+    "@vltpkg/types": "1.0.0-rc.24",
+    "@vltpkg/vlt-json": "1.0.0-rc.24",
     "glob": "^13.0.0",
     "minimatch": "^10.1.1",
     "path-scurry": "^2.0.1"