Skip to content
docs | vlt

Modules | @vltpkg/workspaces

Classes

Monorepo

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
Parameters

• projectRoot: string

• options: MonorepoOptions = {}

Returns

Monorepo

Defined in

index.ts:168

Properties

packageJson
packageJson: PackageJson
Defined in

index.ts:159

projectRoot
projectRoot: string

The project root where vlt-workspaces.json is found

Defined in

index.ts:151

scurry
scurry: PathScurry

Scurry object to cache all filesystem calls (mostly globs)

Defined in

index.ts:153

Accessors

config
get config(): WorkspaceConfigObject

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

Defined in

index.ts:185

size
get size(): number

Number of Workspace objects loaded in this Monorepo

Returns

number

Defined in

index.ts:164

Methods

[asyncIterator]()
asyncIterator: AsyncGenerator<Workspace, void, void>

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

Returns

AsyncGenerator<Workspace, void, void>

Defined in

index.ts:228

[iterator]()
iterator: Generator<Workspace, void, void>

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

Returns

Generator<Workspace, void, void>

Defined in

index.ts:214

filter()
filter(__namedParameters): Generator<Workspace, void, unknown>

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, unknown>

Defined in

index.ts:492

get()
get(nameOrPath): undefined | Workspace

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

Defined in

index.ts:439

getDeps()
getDeps(ws, forceLoad): Workspace[]

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[]

Defined in

index.ts:379

group()
group(group): undefined | Set<Workspace>

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>

Defined in

index.ts:429

keys()
keys(): Generator<string, void, unknown>

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

Returns

Generator<string, void, unknown>

Defined in

index.ts:480

load()
load(query): this

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

Defined in

index.ts:255

names()
names(): Generator<string, void, unknown>

get the list of all loaded workspace names used as keys

Returns

Generator<string, void, unknown>

Defined in

index.ts:446

onCycle()
onCycle(
   _ws,
   _cycle,
   _depPath): void
Parameters

• _ws: Workspace

• _cycle: Workspace[]

• _depPath: Workspace[]

Returns

void

Defined in

index.ts:411

paths()
paths(): Generator<string, void, unknown>

get the list of all loaded workspace paths used as keys

Returns

Generator<string, void, unknown>

Defined in

index.ts:455

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

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

• forceLoad: boolean = false

Returns

Promise<Map<Workspace, R>>

Defined in

index.ts:535

runSync()
runSync<R>(operation, forceLoad): 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.

Type Parameters

• R

Parameters

• operation

• forceLoad: boolean = false

Returns

Map<Workspace, R>

Defined in

index.ts:568

values()
values(): Generator<Workspace, 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.

Returns

Generator<Workspace, void, unknown>

Defined in

index.ts:467

load()
static load(projectRoot, options): Monorepo

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

Defined in

index.ts:618

maybeLoad()
static maybeLoad(projectRoot, options): undefined | Monorepo

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

Defined in

index.ts:595

Workspace

Class representing a single Workspace in a Monorepo

Constructors

new Workspace()
new Workspace(
   path,
   manifest,
   fullpath): Workspace
Parameters

• path: string

• manifest: Manifest

• fullpath: string

Returns

Workspace

Defined in

index.ts:641

Properties

fullpath
fullpath: string
Defined in

index.ts:635

groups
groups: string[] = [];
Defined in

index.ts:637

id
id: DepID
Defined in

index.ts:633

manifest
manifest: Manifest
Defined in

index.ts:636

name
name: string
Defined in

index.ts:638

path
path: string
Defined in

index.ts:634

Accessors

keys
get keys(): string[]
Returns

string[]

Defined in

index.ts:650

Type Aliases

LoadQuery

type LoadQuery: object;

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.

Defined in

index.ts:22

MonorepoOptions

type MonorepoOptions: object;

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

Defined in

index.ts:124

WorkspaceConfig

type WorkspaceConfig: string[] | WorkspaceConfigObject | string;

Allowed datatype in the vlt-workspaces.json file.

Defined in

index.ts:44

WorkspaceConfigObject

type WorkspaceConfigObject: Record<string, string[]>;

Canonical form of the WorkspaceConfig, used internally for consistency.

Defined in

index.ts:39

WorkspacesLoadedConfig

type WorkspacesLoadedConfig: object;

Type declaration

workspace?
optional workspace: string[];
workspace-group?
optional workspace-group: string[];

Defined in

index.ts:13

Variables

workspaceCache

const workspaceCache: Map<string, Workspace>

Defined in

index.ts:627

Functions

assertWSConfig()

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

Throw if the provided value is not a valid WorkspaceConfig

Parameters

• conf: unknown

• path?: string

Returns

asserts conf is WorkspaceConfig

Defined in

index.ts:68

asWSConfig()

function asWSConfig(conf, path?): WorkspaceConfigObject

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

Parameters

• conf: unknown

• path?: string

Returns

WorkspaceConfigObject

Defined in

index.ts:53