@vltpkg/workspaces

Classes

Monorepo

Defined in: index.ts:153

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-workspaces.json file is encountered.

Constructors

new Monorepo()

new Monorepo(projectRoot, options): Monorepo

Defined in: index.ts:172

Parameters

projectRoot

string

options

MonorepoOptions = {}

Returns

Monorepo

Properties

packageJson

packageJson: PackageJson

Defined in: index.ts:163

projectRoot

projectRoot: string

Defined in: index.ts:155

The project root where vlt-workspaces.json is found

scurry

scurry: PathScurry

Defined in: index.ts:157

Scurry object to cache all filesystem calls (mostly globs)

Accessors

config

Get Signature

get config(): WorkspaceConfigObject

Defined in: index.ts:189

Load the workspace definitions from vlt-workspaces.json, canonicalizing the result into the effective {[group:string]:string[]} form.

Eg:

• "src/*" => {packages:["src/*"]}
• {"apps": "src/*"} => {apps: ["src/*"]}

Returns

WorkspaceConfigObject

size

Get Signature

get size(): number

Defined in: index.ts:168

Number of Workspace objects loaded in this Monorepo

Returns

number

Methods

[asyncIterator]()

asyncIterator: AsyncGenerator<Workspace, void, void>

Defined in: index.ts:232

Iterating the Monorepo object yields the workspace objects, in as close to topological dependency order as possible.

Returns

AsyncGenerator<Workspace, void, void>

[iterator]()

iterator: Generator<Workspace, void, void>

Defined in: index.ts:218

Iterating the Monorepo object yields the workspace objects, in as close to topological dependency order as possible.

Returns

Generator<Workspace, void, void>

filter()

filter(__namedParameters): Generator<Workspace, void>

Defined in: index.ts:496

Filter the monorepo object yielding the workspace objects that matches either of the WorkspacesLoadedConfig options provided, in as close to topological dependency order as possible.

Parameters

__namedParameters

WorkspacesLoadedConfig

Returns

Generator<Workspace, void>

get()

get(nameOrPath): undefined | Workspace

Defined in: index.ts:443

Get a loaded workspace by path or name.

Note that this can only return workspaces that were ingested via a previous call to Monorepo#load.

Parameters

nameOrPath

string

Returns

undefined | Workspace

getDeps()

getDeps(ws, forceLoad): Workspace[]

Defined in: index.ts:383

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.

Parameters

ws

Workspace

forceLoad

boolean = false

Returns

Workspace[]

group()

group(group): undefined | Set<Workspace>

Defined in: index.ts:433

Return the set of workspaces in the named group. If the group is not one we know about, then undefined is returned.

Parameters

group

string

Returns

undefined | Set<Workspace>

keys()

keys(): Generator<string, void>

Defined in: index.ts:484

Get all the keys (package names and paths) for loaded workspaces. Union of Monorepo#names and Monorepo#paths

Returns

Generator<string, void>

load()

load(query): this

Defined in: index.ts:259

By default, loads all workspaces reachable in the Monorepo.

If provided with one (string)or more (string[]) group names in the 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.

Parameters

query

LoadQuery = {}

Returns

this

names()

names(): Generator<string, void>

Defined in: index.ts:450

get the list of all loaded workspace names used as keys

Returns

Generator<string, void>

onCycle()

onCycle(
   _ws,
   _cycle,
   _depPath): void

Defined in: index.ts:415

Parameters

_ws

Workspace

_cycle

Workspace[]

_depPath

Workspace[]

Returns

void

paths()

paths(): Generator<string, void>

Defined in: index.ts:459

get the list of all loaded workspace paths used as keys

Returns

Generator<string, void>

run()

run<R>(operation, forceLoad): Promise<Map<Workspace, R>>

Defined in: index.ts:539

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.

Type Parameters

• R

Parameters

operation

(s, signal, depResults) => R | Promise<R>

forceLoad

boolean = false

Returns

Promise<Map<Workspace, R>>

runSync()

runSync<R>(operation, forceLoad): Map<Workspace, R>

Defined in: index.ts:572

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.

Type Parameters

• R

Parameters

operation

(s, signal, depResults) => R

forceLoad

boolean = false

Returns

Map<Workspace, R>

values()

values(): Generator<Workspace, void>

Defined in: index.ts:471

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.

Returns

Generator<Workspace, void>

load()

static load(projectRoot, options): Monorepo

Defined in: index.ts:622

Convenience method to instantiate and load in one call. Throws if called on a directory that is not a workspaces root.

Parameters

projectRoot

string

options

MonorepoOptions = ...

Returns

Monorepo

maybeLoad()

static maybeLoad(projectRoot, options): undefined | Monorepo

Defined in: index.ts:599

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.

Parameters

projectRoot

string

options

MonorepoOptions = ...

Returns

undefined | Monorepo

---

Workspace

Defined in: index.ts:636

Class representing a single Workspace in a Monorepo

Constructors

new Workspace()

new Workspace(
   path,
   manifest,
   fullpath): Workspace

Defined in: index.ts:645

Parameters

path

string

manifest

Manifest

fullpath

string

Returns

Workspace

Properties

fullpath

fullpath: string

Defined in: index.ts:639

groups

groups: string[] = [];

Defined in: index.ts:641

id

id: DepID

Defined in: index.ts:637

manifest

manifest: Manifest

Defined in: index.ts:640

name

name: string

Defined in: index.ts:642

path

path: string

Defined in: index.ts:638

Accessors

keys

Get Signature

get keys(): string[]

Defined in: index.ts:654

Returns

string[]

Type Aliases

LoadQuery

type LoadQuery = object

Defined in: index.ts:26

The object passed to the constructor or Monorepo#load to limit which Workspaces get loaded.

Type declaration

groups?

optional groups: string[] | string;

A string, or an array of strings. If set, only workspaces in the specified groups named will be included, if set.

paths?

optional paths: string[] | string;

A glob pattern string, or an array of them. Only workspaces found in paths matched will be loaded.

---

MonorepoOptions

type MonorepoOptions = object

Defined in: index.ts:128

Type declaration

config?

optional config: WorkspaceConfigObject;

Parsed normalized contents of a vlt-workspaces.json file

load?

optional load: LoadQuery;

If set, then Monorepo#load will be called immediately with this argument.

packageJson?

optional packageJson: PackageJson;

A PackageJson object, for sharing manifest caches

scurry?

optional scurry: PathScurry;

A PathScurry object, for use in globs

---

WorkspaceConfig

type WorkspaceConfig = string[] | WorkspaceConfigObject | string

Defined in: index.ts:48

Allowed datatype in the vlt-workspaces.json file.

---

WorkspaceConfigObject

type WorkspaceConfigObject = Record<string, string[]>

Defined in: index.ts:43

Canonical form of the WorkspaceConfig, used internally for consistency.

---

WorkspacesLoadedConfig

type WorkspacesLoadedConfig = object

Defined in: index.ts:17

Type declaration

workspace?

optional workspace: string[];

workspace-group?

optional workspace-group: string[];

Variables

workspaceCache

const workspaceCache: Map<string, Workspace>

Defined in: index.ts:631

Functions

assertWSConfig()

function assertWSConfig(conf, path?): asserts conf is WorkspaceConfig

Defined in: index.ts:72

Throw if the provided value is not a valid WorkspaceConfig

Parameters

conf

unknown

path?

string

Returns

asserts conf is WorkspaceConfig

---

asWSConfig()

function asWSConfig(conf, path?): WorkspaceConfigObject

Defined in: index.ts:57

Turn a WorkspaceConfig into a WorkspaceConfigObject, or throw if it’s not valid.

Parameters

conf

unknown

path?

string

Returns

WorkspaceConfigObject