vlt / docs

    • PricingBenchmarks (opens in new window)Community (opens in new window)Feedback
  • Overview
    • Overview
    • Reference
  • Classes
  • Monorepo
  • Workspace
  • Type Aliases
  • LoadQuery
  • MonorepoOptions
  • WorkspaceConfig
  • WorkspaceConfigObject
  • WorkspacesLoadedConfig
  • Variables
  • workspaceCache
  • Functions
  • assertWSConfig()
  • asWSConfig()
  1. Client
  2. /
  3. API Reference
  4. /
  5. @vltpkg/workspaces
  6. /
  7. Reference

Reference

Classes

Monorepo

Defined in: index.ts:177

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.

Constructors

new Monorepo()
TypeScript
new Monorepo(projectRoot, options): Monorepo

Defined in: index.ts:196

Parameters
ParameterType
projectRootstring
optionsMonorepoOptions
Returns

Monorepo

Properties

PropertyTypeDescription
packageJsonPackageJson-
projectRootstringThe project root where vlt.json is found
scurryPathScurryScurry object to cache all filesystem calls (mostly globs)

Accessors

config
Get Signature
TypeScript
get config(): WorkspaceConfigObject

Defined in: index.ts:213

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/*"]}
Returns

WorkspaceConfigObject

size
Get Signature
TypeScript
get size(): number

Defined in: index.ts:192

Number of Workspace objects loaded in this Monorepo

Returns

number

Methods

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

Defined in: index.ts:239

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

Returns

AsyncGenerator<Workspace, void, void>

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

Defined in: index.ts:225

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

Returns

Generator<Workspace, void, void>

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

Defined in: index.ts:551

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
ParameterType
__namedParametersWorkspacesLoadedConfig
Returns

Generator<Workspace, void, unknown>

get()
TypeScript
get(nameOrPath): undefined | Workspace

Defined in: index.ts:498

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
ParameterType
nameOrPathstring
Returns

undefined | Workspace

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

Defined in: index.ts:438

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
ParameterTypeDefault value
wsWorkspaceundefined
forceLoadbooleanfalse
Returns

Workspace[]

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

Defined in: index.ts:488

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

Parameters
ParameterType
groupstring
Returns

undefined | Set<Workspace>

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

Defined in: index.ts:539

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

Returns

Generator<string, void, unknown>

load()
TypeScript
load(query): this

Defined in: index.ts:266

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
ParameterType
queryLoadQuery
Returns

this

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

Defined in: index.ts:505

get the list of all loaded workspace names used as keys

Returns

Generator<string, void, unknown>

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

Defined in: index.ts:470

Parameters
ParameterType
_wsWorkspace
_cycleWorkspace[]
_depPathWorkspace[]
Returns

void

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

Defined in: index.ts:514

get the list of all loaded workspace paths used as keys

Returns

Generator<string, void, unknown>

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

Defined in: index.ts:594

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
Type Parameter
R
Parameters
ParameterTypeDefault value
operation(s, signal, depResults) => R | Promise<R>undefined
forceLoadbooleanfalse
Returns

Promise<Map<Workspace, R>>

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

Defined in: index.ts:627

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
Type Parameter
R
Parameters
ParameterTypeDefault value
operation(s, signal, depResults) => Rundefined
forceLoadbooleanfalse
Returns

Map<Workspace, R>

values()
TypeScript
values(): Generator<Workspace, void, unknown>

Defined in: index.ts:526

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>

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

Defined in: index.ts:667

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

Parameters
ParameterType
projectRootstring
optionsMonorepoOptions
Returns

Monorepo

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

Defined in: index.ts:654

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
ParameterType
projectRootstring
optionsMonorepoOptions
Returns

undefined | Monorepo

Workspace

Defined in: index.ts:681

Class representing a single Workspace in a Monorepo

Constructors

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

Defined in: index.ts:690

Parameters
ParameterType
pathstring
manifestOverride
fullpathstring
Returns

Workspace

Properties

PropertyTypeDefault value
fullpathstringundefined
groupsstring[][]
idDepIDundefined
manifestOverrideundefined
namestringundefined
pathstringundefined

Accessors

keys
Get Signature
TypeScript
get keys(): string[]

Defined in: index.ts:703

Returns

string[]

Type Aliases

LoadQuery

TypeScript
type LoadQuery = object;

Defined in: index.ts:44

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

Type declaration

NameTypeDescription
groups?string[] | stringA string, or an array of strings. If set, only workspaces in the specified groups named will be included, if set.
paths?string[] | stringA glob pattern string, or an array of them. Only workspaces found in paths matched will be loaded.

MonorepoOptions

TypeScript
type MonorepoOptions = object;

Defined in: index.ts:149

Type declaration

NameTypeDescription
config?WorkspaceConfigObjectParsed normalized contents of the workspaces from a vlt.json file
load?LoadQueryIf set, then Monorepo#load will be called immediately with this argument.
packageJson?PackageJsonA PackageJson object, for sharing manifest caches
scurry?PathScurryA PathScurry object, for use in globs

WorkspaceConfig

TypeScript
type WorkspaceConfig = 
  | string[]
  | WorkspaceConfigObject
  | string;

Defined in: index.ts:66

Allowed datatype in the workspaces field of the vlt.json file.

WorkspaceConfigObject

TypeScript
type WorkspaceConfigObject = Record<string, string[]>;

Defined in: index.ts:61

Canonical form of the WorkspaceConfig, used internally for consistency.

WorkspacesLoadedConfig

TypeScript
type WorkspacesLoadedConfig = object;

Defined in: index.ts:35

Type declaration

NameType
workspace?string[]
workspace-group?string[]

Variables

workspaceCache

TypeScript
const workspaceCache: Map<string, Workspace>;

Defined in: index.ts:676

Functions

assertWSConfig()

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

Defined in: index.ts:93

Throw if the provided value is not a valid WorkspaceConfig

Parameters

ParameterType
confunknown
path?string

Returns

asserts conf is WorkspaceConfig

asWSConfig()

TypeScript
function asWSConfig(conf, path?): WorkspaceConfigObject

Defined in: index.ts:73

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

Parameters

ParameterType
confunknown
path?string

Returns

WorkspaceConfigObject

Previous@vltpkg/workspacesNext@vltpkg/xdg

On this page

  • Classes
  • Monorepo
  • Workspace
  • Type Aliases
  • LoadQuery
  • MonorepoOptions
  • WorkspaceConfig
  • WorkspaceConfigObject
  • WorkspacesLoadedConfig
  • Variables
  • workspaceCache
  • Functions
  • assertWSConfig()
  • asWSConfig()

Deploy your package on vlt.io

Publish scoped and private packages, manage organizations and access, and give every developer and CI environment a consistent source for public and private JavaScript dependencies.

Publish now