oneRepo API

Variables

defaultConfig

const defaultConfig: Required<RootConfig>;

Defined in: modules/onerepo/src/setup/setup.ts

Commands

Argv<CommandArgv>

type Argv<CommandArgv>: Arguments<CommandArgv & DefaultArgv>;

Helper for combining local parsed arguments along with the default arguments provided by the oneRepo command module.

Type Parameters

Type Parameter	Default type	Description
`CommandArgv`	`object`	Arguments that will be parsed for this command, always a union with `DefaultArgv` and `PositionalArgv`.

Defined in: modules/yargs/src/yargs.ts

Builder()<CommandArgv>

type Builder<CommandArgv>: (yargs) => Yargv<CommandArgv>;

Option argument parser for the given command. See Yargs .command(module) for more, but note that only the object variant is not accepted – only function variants will be accepted in oneRepo commands.

For common arguments that work in conjunction with `HandlerExtra` methods like getAffected(), you can use helpers from the `builders` namespace, like `builders.withAffected()`.

type Argv = {
  'with-tacos'?: boolean;
};

export const builder: Builder<Argv> = (yargs) =>
  yargs.usage(`$0 ${command}`).option('with-tacos', {
    description: 'Include tacos',
    type: 'boolean',
  });

Type Parameters

Type Parameter	Default type	Description
`CommandArgv`	`object`	Arguments that will be parsed for this command

Parameters:

Parameter	Type	Description
`yargs`	`Yargs`	The Yargs instance. See Yargs `.command(module)`

Returns: Yargv<CommandArgv>
See also:

Yargs .command(module) for general usage.
Common extensions via the `builders` namespace.

Defined in: modules/yargs/src/yargs.ts

DefaultArgv

type DefaultArgv: {
  dry-run: boolean;
  quiet: boolean;
  skip-engine-check: boolean;
  verbosity: number;
};

Default arguments provided globally for all commands. These arguments are included by when using `Builder` and `Handler`.

Type declaration

dry-run

dry-run: boolean;

Whether the command should run non-destructive dry-mode. This prevents all subprocesses, files, and git operations from running unless explicitly specified as safe to run.

Also internally sets process.env.ONEREPO_DRY_RUN = 'true'.

Default: false

quiet

quiet: boolean;

Silence all logger output. Prevents all stdout and stderr output from the logger entirely.

Default: false

skip-engine-check

skip-engine-check: boolean;

Skip the engines check. When false, oneRepo will the current process’s node version with the range for engines.node as defined in package.json. If not defined in the root package.json, this will be skipped.

Default: false

verbosity

verbosity: number;

Verbosity level for the Logger. See Logger.verbosity for more information.

Default: 3
Defined in: modules/yargs/src/yargs.ts

Handler()<CommandArgv>

type Handler<CommandArgv>: (argv, extra) => Promise<void>;

Command handler that includes oneRepo tools like graph, logger, and more. This function is type-safe if Argv is correctly passed through to the type definition.

type Argv = {
  'with-tacos'?: boolean;
};
export const handler: Handler<Argv> = (argv, { logger }) => {
  const { 'with-tacos': withTacos, '--': passthrough } = argv;
  logger.log(withTacos ? 'Include tacos' : 'No tacos, thanks');
  logger.debug(passthrough);
};

Type Parameters

Type Parameter	Default type	Description
`CommandArgv`	`object`	Arguments that will be parsed for this command. DefaultArguments will be automatically merged into this object for use within the handler.

Parameters:

Parameter	Type
`argv`	`Argv`<`CommandArgv`>
`extra`	`HandlerExtra`

Returns: Promise<void>
See also:

Yargs .command(module) for general usage.
`HandlerExtra` for extended extra arguments provided above and beyond the scope of Yargs.

Defined in: modules/yargs/src/yargs.ts

HandlerExtra

type HandlerExtra: {
  config: Required<RootConfig>;
  getAffected: (opts?) => Promise<Workspace[]>;
  getFilepaths: (opts?) => Promise<string[]>;
  getWorkspaces: (opts?) => Promise<Workspace[]>;
  graph: Graph;
  logger: Logger;
};

Commands in oneRepo extend beyond what Yargs is able to provide by adding a second argument to the handler.

All extras are available as the second argument on your `Handler`

export const handler: Handler = (argv, { getAffected, getFilepaths, getWorkspace, logger }) => {
  logger.warn('Nothing to do!');
};

Overriding the affected threshold in getFilepaths

export const handler: Handler = (argv, { getFilepaths }) => {
  const filepaths = await getFilepaths({ affectedThreshold: 0 });
};

Type declaration

config

config: Required<RootConfig>;

This repository’s oneRepo config, resolved with all defaults.

getAffected()

getAffected: (opts?) => Promise<Workspace[]>;

Get the affected Workspaces based on the current state of the repository.

This is a wrapped implementation of `builders.getAffected` that does not require passing the graph argument.

Parameters:

Parameter	Type
`opts`?	`GetterOptions`

Returns: Promise<Workspace[]>

getFilepaths()

getFilepaths: (opts?) => Promise<string[]>;

Get the affected filepaths based on the current inputs and state of the repository. Respects manual inputs provided by `builders.withFiles` if provided.

This is a wrapped implementation of `builders.getFilepaths` that does not require the graph and argv arguments.

Note: that when used with --affected, there is a default limit of 100 files before this will switch to returning affected Workspace paths. Use affectedThreshold: 0 to disable the limit.
Parameters:

Parameter	Type
`opts`?	`FileGetterOptions`

Returns: Promise<string[]>

getWorkspaces()

getWorkspaces: (opts?) => Promise<Workspace[]>;

Get the affected Workspaces based on the current inputs and the state of the repository. This function differs from getAffected in that it respects all input arguments provided by `builders.withWorkspaces`, `builders.withFiles` and `builders.withAffected`.

This is a wrapped implementation of `builders.getWorkspaces` that does not require the graph and argv arguments.

Parameters:

Parameter	Type
`opts`?	`GetterOptions`

Returns: Promise<Workspace[]>

graph

graph: Graph;

The full monorepo `Graph`.

logger

logger: Logger;

Standard `Logger`. This should always be used in place of console.log methods unless you have a specific need to write to standard out differently.

Defined in: modules/yargs/src/yargs.ts

PositionalArgv

type PositionalArgv: {
  _: (string | number)[];
  --: string[];
  $0: string;
};

Always present in Builder and Handler arguments as parsed by Yargs.

Type declaration

_

_: (string | number)[];

Positionals / non-option arguments. These will only be filled if you include .positional() or .strictCommands(false) in your Builder.

—

--: string[];

Any content that comes after ” — ” gets populated here. These are useful for spreading through to spawned run functions that may take extra options that you don’t want to enumerate and validate.

$0

$0: string;

The script name or node command. Similar to process.argv[1]

Defined in: modules/yargs/src/yargs.ts

Config

Config<CustomLifecycles>

type Config<CustomLifecycles>: RootConfig<CustomLifecycles> | WorkspaceConfig<CustomLifecycles>;

Picks the correct config type between RootConfig and WorkspaceConfig based on whether the root property is set. Use this to help ensure your configs do not have any incorrect keys or values.

Satisfy a RootConfig:

import type { Config } from 'onerepo';

export default {
  root: true,
} satisfies Config;

Satisfy a WorkspaceConfig with custom lifecycles on tasks:

import type { Config } from 'onerepo';

export default {
  tasks: {
    stage: {
      serial: ['$0 build'],
    },
  },
} satisfies Config<'stage'>;

Type Parameters

Type Parameter	Default type
`CustomLifecycles` extends `string` \| `void`	`void`

Defined in: modules/onerepo/src/types/index.ts

Lifecycle

type Lifecycle:
  | "pre-commit"
  | "post-commit"
  | "post-checkout"
  | "pre-merge"
  | "post-merge"
  | "pre-push"
  | "build"
  | "pre-deploy"
  | "pre-publish"
  | "post-publish";

oneRepo comes with a pre-configured list of common lifecycles for grouping tasks.

Defined in: modules/onerepo/src/types/tasks.ts

RootConfig<CustomLifecycles>

type RootConfig<CustomLifecycles>: {
  changes: {
     filenames: "hash" | "human";
     formatting: {
        commit: string;
        footer: string;
       };
     prompts: "guided" | "semver";
    };
  codeowners: Record<string, string[]>;
  commands: {
     directory: string | false;
     ignore: RegExp;
    };
  dependencies: {
     dedupe: boolean;
     mode: "strict" | "loose" | "off";
    };
  head: string;
  ignore: string[];
  meta: Record<string, unknown>;
  plugins: Plugin[];
  root: true;
  taskConfig: {
     lifecycles: CustomLifecycles[];
     stashUnstaged: CustomLifecycles extends string ? Lifecycle | CustomLifecycles : Lifecycle[];
    };
  tasks: TaskConfig<CustomLifecycles>;
  templateDir: string;
  validation: {
     schema: string | null;
    };
  vcs: {
     autoSyncHooks: boolean;
     hooksPath: string;
     provider: "github" | "gitlab" | "bitbucket" | "gitea";
    };
  visualizationUrl: string;
};

Setup configuration for the root of the repository.

Type Parameters

Type Parameter	Default type
`CustomLifecycles` extends `string` \| `void`	`void`

Type declaration

changes?

optional changes: {
  filenames: "hash" | "human";
  formatting: {
     commit: string;
     footer: string;
    };
  prompts: "guided" | "semver";
};

Type declaration

changes.filenames?

optional filenames: "hash" | "human";

Default: 'hash'

To generate human-readable unique filenames for change files, ensure human-id is installed.

changes.formatting?

optional formatting: {
  commit: string;
  footer: string;
};

Type declaration

Default: {}

Override some formatting strings in generated changelog files.

export default {
  root: true,
  changes: {
    formatting: {
      commit: '([${ref.short}](https://github.com/paularmstrong/onerepo/commit/${ref}))',
      footer:
        '> Full changelog [${fromRef.short}...${throughRef.short}](https://github.com/my-repo/commits/${fromRef}...${throughRef})',
    },
  },
};

changes.formatting.commit?

optional commit: string;

Default: '(${ref.short})'

Format how the commit ref will appear at the end of the first line of each change entry.

Available replacement strings:

Replacement	Description
`${ref.short}`	8-character version of the commit ref
`${ref}`	Full commit ref

changes.formatting.footer?

optional footer: string;

Default: '_View git logs for full change list._'

Format the footer at the end of each version in the generated changelog files.

Available replacement strings:

Replacement	Description
`${fromRef.short}`	8-character version of the first commit ref in the version
`${fromRef}`	Full commit ref of the first commit in the version
`${through.short}`	8-character version of the last commit ref in the version
`${through}`	Full commit ref of the last commit in the version
`${version}`	New version string

changes.prompts?

optional prompts: "guided" | "semver";

Default: 'guided'

Change the prompt question & answer style when adding change entries.

'guided': Gives more detailed explanations when release types.
'semver': A simple choice list of semver release types.

codeowners?

optional codeowners: Record<string, string[]>;

Default: {}

Map of paths to array of owners.

When used with the codeowners commands, this configuration enables syncing configurations from Workspaces to the appropriate root level CODEOWNERS file given your vcsProvider as well as verifying that the root file is up to date.

export default {
  root: true,
  codeowners: {
    '*': ['@my-team', '@person'],
    scripts: ['@infra-team'],
  },
};

commands?

optional commands: {
  directory: string | false;
  ignore: RegExp;
};

Configuration for custom commands.

Type declaration

commands.directory?

optional directory: string | false;

Default: 'commands'

A string to use as filepaths to subcommands. We’ll look for commands in all Workspaces using this string. If any are found, they’ll be available from the CLI.

export default {
  root: true,
  commands: {
    directory: 'commands',
  },
};

Given the preceding configuration, commands will be searched for within the commands/ directory at the root of the repository as well as a directory of the same name at the root of each Workspace:

<root>/commands/*
<root>/<workspaces>/commands/*

commands.ignore?

optional ignore: RegExp;

Default: /(/__\w+__/|\.test\.|\.spec\.|\.config\.)/

Prevent reading matched files in the commands.directory as commands.

When writing custom commands and Workspace-level subcommands, we may need to ignore certain files like tests, fixtures, and other helpers. Use a regular expression here to configure which files will be ignored when oneRepo parses and executes commands.

export default {
  root: true,
  commands: {
    ignore: /(/__\w+__/|\.test\.|\.spec\.|\.config\.)/,
  },
};

dependencies?

optional dependencies: {
  dedupe: boolean;
  mode: "strict" | "loose" | "off";
};

Type declaration

dependencies.dedupe?

optional dedupe: boolean;

Default: true

When modifying dependencies using the one dependencies command, a dedupe will automatically be run to reduce duplicate package versions that overlap the requested ranges. Set this to false to disable this behavior.

dependencies.mode?

optional mode: "strict" | "loose" | "off";

Default: 'loose'

The dependency mode will be used for node module dependency management and verification.

off: No validation will occur. Everything goes.
loose: Reused third-party dependencies will be required to have semantic version overlap across unique branches of the Graph.
strict: Versions of all dependencies across each discrete Workspace dependency tree must be strictly equal.

head?

optional head: string;

Default: 'main'

The default branch of your repo? Probably main, but it might be something else, so it’s helpful to put that here so that we can determine changed files accurately.

export default {
  root: true,
  head: 'develop',
};

ignore?

optional ignore: string[];

Default: []

Array of fileglobs to ignore when calculating the changed Workspaces.

Periodically we may find that there are certain files or types of files that we know for a fact do not affect the validity of the repository or any code. When this happens and the files are modified, unnecessary tasks and processes will be spun up that don’t have any bearing on the outcome of the change.

To avoid extra processing, we can add file globs to ignore when calculated the afected Workspace graph.

export default {
  root: true,
  ignore: ['.github/\*'],
};

meta?

optional meta: Record<string, unknown>;

Default: {}

A place to put any custom information or configuration. A helpful space for you to extend Workspace configurations for your own custom commands.

export default {
  root: true,
  meta: {
    tacos: 'are delicious',
  },
};

plugins?

optional plugins: Plugin[];

Default: []

Add shared commands and extra handlers. See the official plugin list for more information.

import { eslint } from '@onerepo/plugins-eslint';
export default {
  plugins: [eslint()],
};

root

root: true;

Must be set to true in order to denote that this is the root of the repository.

taskConfig?

optional taskConfig: {
  lifecycles: CustomLifecycles[];
  stashUnstaged: CustomLifecycles extends string ? Lifecycle | CustomLifecycles : Lifecycle[];
};

Optional extra configuration for tasks.

Type declaration

taskConfig.lifecycles?

optional lifecycles: CustomLifecycles[];

Default: []

Additional task lifecycles to make available.

See `Lifecycle` for a list of pre-configured lifecycles.

export default {
  root: true,
  tasks: {
    lifecycles: ['deploy-staging'],
  },
};

taskConfig.stashUnstaged?

optional stashUnstaged: CustomLifecycles extends string ? Lifecycle | CustomLifecycles : Lifecycle[];

Default: ['pre-commit'] Stash unstaged changes before running these tasks and re-apply them after the task has completed.

export default {
  root: true,
  tasks: {
    stashUnstaged: ['pre-commit', 'post-checkout'],
  },
};

tasks?

optional tasks: TaskConfig<CustomLifecycles>;

Default: {}

Globally defined tasks per lifecycle. Tasks defined here will be assumed to run for all changes, regardless of affected Workspaces. Refer to the tasks command specifications for details and examples.

templateDir?

optional templateDir: string;

Default: './config/templates'

Folder path for generate command’s templates.

validation?

optional validation: {
  schema: string | null;
};

Type declaration

validation.schema?

optional schema: string | null;

Default: undefined

File path for custom Graph and configuration file validation schema.

vcs?

optional vcs: {
  autoSyncHooks: boolean;
  hooksPath: string;
  provider: "github" | "gitlab" | "bitbucket" | "gitea";
};

Version control system settings.

Type declaration

vcs.autoSyncHooks?

optional autoSyncHooks: boolean;

Default: false

Automatically set and sync oneRepo-managed git hooks. Change the directory for your git hooks with the vcs.hooksPath setting. Refer to the Git hooks documentation to learn more.

export default {
  root: true,
  vcs: {
    autoSyncHooks: false,
  },
};

vcs.hooksPath?

optional hooksPath: string;

Default: '.hooks'

Modify the default git hooks path for the repository. This will automatically be synchronized via one hooks sync unless explicitly disabled by setting vcs.autoSyncHooks to false.

export default {
  root: true,
  vcs: {
    hooksPath: '.githooks',
  },
};

vcs.provider?

optional provider: "github" | "gitlab" | "bitbucket" | "gitea";

Default: 'github'

The provider will be factored in to various commands, like CODEOWNERS generation.

export default {
  root: true,
  vcs: {
    provider: 'github',
  },
};

visualizationUrl?

optional visualizationUrl: string;

Default: 'https://onerepo.tools/visualize/'

Override the URL used to visualize the Graph. The Graph data will be attached the the g query parameter as a JSON string of the DAG, compressed using zLib deflate.

Defined in: modules/onerepo/src/types/config-root.ts

Task

type Task: string | TaskDef | string[];

A Task can either be a string or `TaskDef` object with extra options, or an array of strings. If provided as an array of strings, each command will be run sequentially, waiting for the previous to succeed. If one command fails, the rest in the sequence will not be run.

To run sequences of commands with match and meta information, you can pass an array of strings to the cmd property of a `TaskDef`.

Defined in: modules/onerepo/src/types/tasks.ts

TaskConfig<CustomLifecycles>

type TaskConfig<CustomLifecycles>: Partial<Record<CustomLifecycles extends string ? Lifecycle | CustomLifecycles : Lifecycle, Tasks>>;

Type Parameters

Type Parameter	Default type
`CustomLifecycles` extends `string` \| `void`	`void`

Defined in: modules/onerepo/src/types/tasks.ts

TaskDef

type TaskDef: {
  cmd: string | string[];
  match: string | string[];
  meta: Record<string, unknown>;
};

Tasks can optionally include meta information or only be run if the configured match glob string matches the modified files. If no files match, the individual task will not be run.

export default {
  tasks: {
    'pre-commit': {
      parallel: [
        // Only run `astro check` if astro files have been modified
        { match: '*.astro', cmd: '$0 astro check' },
        // Use a glob match with sequential tasks
        { match: '*.{ts,js}', cmd: ['$0 lint', '$0 format'] },
      ],
    },
  },
} satisfies Config;

Type declaration

cmd

cmd: string | string[];

String command(s) to run. If provided as an array of strings, each command will be run sequentially, waiting for the previous to succeed. If one command fails, the rest in the sequence will not be run.

The commands can use replaced tokens:

$0: the oneRepo CLI for your repository
${workspaces}: replaced with a space-separated list of Workspace names necessary for the given lifecycle

match?

optional match: string | string[];

Glob file match. This will force the cmd to run if any of the paths in the modified files list match the glob. Conversely, if no files are matched, the cmd will not run.

meta?

optional meta: Record<string, unknown>;

Extra information that will be provided only when listing tasks with the --list option from the tasks command. This object is helpful when creating a matrix of runners with GitHub actions or similar CI pipelines.

Defined in: modules/onerepo/src/types/tasks.ts

Tasks

type Tasks: {
  parallel: Task[];
  serial: Task[];
};

Individual `Task`s in any `Lifecycle` may be grouped to run either serial (one after the other) or in parallel (multiple at the same time).

Type declaration

parallel?

optional parallel: Task[];

serial?

optional serial: Task[];

Defined in: modules/onerepo/src/types/tasks.ts

WorkspaceConfig<CustomLifecycles>

type WorkspaceConfig<CustomLifecycles>: {
  codeowners: Record<string, string[]>;
  commands: {
     passthrough: Record<string, {
        command: string;
        description: string;
       }>;
    };
  meta: Record<string, unknown>;
  tasks: TaskConfig<CustomLifecycles>;
};

Type Parameters

Type Parameter	Default type
`CustomLifecycles` extends `string` \| `void`	`void`

Type declaration

codeowners?

optional codeowners: Record<string, string[]>;

Default: {}. Map of paths to array of owners.

When used with the codeowners commands, this configuration enables syncing configurations from Workspaces to the appropriate root level CODEOWNERS file given your RootConfig.vcs.provider as well as verifying that the root file is up to date.

export default {
  codeowners: {
    '*': ['@my-team', '@person'],
    scripts: ['@infra-team'],
  },
};

commands?

optional commands: {
  passthrough: Record<string, {
     command: string;
     description: string;
    }>;
};

Configuration for custom commands. To configure the commands directory, see RootConfig commands.directory.

Type declaration

commands.passthrough

passthrough: Record<
  string,
  {
    command: string;
    description: string;
  }
>;

Default: {}

Enable commands from installed dependencies. Similar to running npx <command>, but pulled into the oneRepo CLI and able to be limited by Workspace. Passthrough commands must have helpful descriptions.

export default {
  commands: {
    passthrough: {
      astro: { description: 'Run Astro commands directly.' },
      start: { description: 'Run the Astro dev server.', command: 'astro dev --port=8000' },
    },
  },
};

meta?

optional meta: Record<string, unknown>;

Default: {} A place to put any custom information or configuration. A helpful space for you to extend Workspace configurations for your own custom commands.

export default {
  meta: {
    tacos: 'are delicious',
  },
};

tasks?

optional tasks: TaskConfig<CustomLifecycles>;

Default: {} Tasks for this Workspace. These will be merged with global tasks and any other affected Workspace tasks. Refer to the tasks command specifications for details and examples.

Defined in: modules/onerepo/src/types/config-workspace.ts

Graph

getGraph()

function getGraph(workingDir?): Graph;

Get the `Graph` given a particular root working directory. If the working directory is not a monorepo’s root, an empty Graph will be given in its place.

const graph = getGraph(process.cwd());
assert.ok(graph.isRoot);

Parameters:

Parameter	Type
`workingDir`?	`string`

Returns: Graph
Defined in: modules/graph/src/index.ts

Graph

The oneRepo Graph is a representation of the entire repository’s `Workspaces` and how they depend upon each other. Most commonly, you will want to use the Graph to get lists of Workspaces that either depend on some input or are dependencies thereof:

const workspacesToCheck = graph.affected('tacos');
for (const ws of workspacesToCheck) {
  // verify no issues based on changes
}

The Graph also includes various helpers for determining workspaces based on filepaths, name, and other factors.

Accessors

packageManager

Get Signature

get packageManager(): PackageManager

Get the PackageManager that this Graph depends on. This object allows you to run many common package management commands safely, agnostic of any particular flavor of package management. Works with npm, Yarn, and pnpm.

await graph.packageManager.install();

Returns: PackageManager
Defined in: modules/graph/src/Graph.ts

root

Get Signature

get root(): Workspace

This returns the `Workspace` that is at the root of the repository.

Regardless of how the workspaces are configured with the package manager, the root package.json is always registered as a Workspace.

const root = graph.root;
root.isRoot === true;

Returns: Workspace
Defined in: modules/graph/src/Graph.ts

workspaces

Get Signature

get workspaces(): Workspace[]

Get a list of all `Workspaces` that are part of the repository {@Link Graph | Graph}.

for (const workspace of graph.workspaces) {
  logger.info(workspace.name);
}

Returns: Workspace[]
Defined in: modules/graph/src/Graph.ts

Methods

affected()

affected<T>(source, type?): Workspace[]

Get a list of `Workspaces` that will be affected by the given source(s). This is equivalent to graph.dependents(sources, true). See also `dependents`.

const dependents = graph.dependents(sources, true);
const affected = graph.affected(sources);

assert.isEqual(dependents, affecteed);

Type Parameters

Type Parameter
`T` extends `string` \| `Workspace`

Parameters:

Parameter	Type	Description
`source`	`T` \| `T`[]	-
`type`?	`DepType`	Filter the dependents to a dependency type.

Returns: Workspace[]
Defined in: modules/graph/src/Graph.ts

dependencies()

dependencies<T>(
   sources?,
   includeSelf?,
   type?): Workspace[]

Get all dependency `Workspaces` of one or more input Workspaces or qualified names of Workspaces. This not only returns the direct dependencies, but all dependencies throughout the entire `Graph`. This returns the opposite result of `dependents`.

for (const workspace of graph.dependencies('tacos')) {
  logger.info(`"${workspace.name}" is a dependency of "tacos"`);
}

Type Parameters

Type Parameter
`T` extends `string` \| `Workspace`

Parameters:

Parameter	Type	Description
`sources`?	`T` \| `T`[]	A list of `Workspaces` by `name`s or any available `aliases`.
`includeSelf`?	`boolean`	Whether to include the `Workspaces` for the input `sources` in the return array.
`type`?	`DepType`	Filter the dependencies to a dependency type.

Returns: Workspace[]
Defined in: modules/graph/src/Graph.ts

dependents()

dependents<T>(
   sources?,
   includeSelf?,
   type?): Workspace[]

Get all dependent `Workspaces` of one or more input Workspaces or qualified names of Workspaces. This not only returns the direct dependents, but all dependents throughout the entire `Graph`. This returns the opposite result of `dependencies`.

for (const workspace of graph.dependents('tacos')) {
  logger.info(`"${workspace.name}" depends on "tacos"`);
}

Type Parameters

Type Parameter
`T` extends `string` \| `Workspace`

Parameters:

Parameter	Type	Description
`sources`?	`T` \| `T`[]	One or more Workspaces by name or `Workspace` instance
`includeSelf`?	`boolean`	Whether to include the `Workspaces` for the input `sources` in the return array.
`type`?	`DepType`	Filter the dependents to a dependency type.

Returns: Workspace[]
Defined in: modules/graph/src/Graph.ts

getAllByLocation()

getAllByLocation(locations): Workspace[]

Get all Workspaces given an array of filepaths.

const workspaces = graph.getAllByLocation([__dirname, 'file:///foo/bar']);

Parameters:

Parameter	Type	Description
`locations`	`string`[]	A list of filepath strings. May be file URLs or string paths.

Returns: Workspace[]
Defined in: modules/graph/src/Graph.ts

getAllByName()

getAllByName(names): Workspace[]

Get a list of `Workspaces` by string names.

const workspaces = graph.getAllByName(['tacos', 'burritos']);

Parameters:

Parameter	Type	Description
`names`	`string`[]	A list of Workspace `name`s or any available `aliases`.

Returns: Workspace[]
Defined in: modules/graph/src/Graph.ts

getByLocation()

getByLocation(location): Workspace

Get the equivalent `Workspace` for a filepath. This can be any location within a Workspace, not just its root.

// in Node.js
graph.getByLocation(__dirname);

graph.getByLocation(import.meta.url);

Parameters:

Parameter	Type	Description
`location`	`string`	A string or URL-based filepath.

Returns: Workspace

Throws

Error if no Workspace can be found.

Defined in: modules/graph/src/Graph.ts

getByName()

getByName(name): Workspace

Get a `Workspace` by string name.

const workspace = graph.getByName('my-cool-package');

Parameters:

Parameter	Type	Description
`name`	`string`	A Workspace’s `name` or any available `aliases`.

Returns: Workspace

Throws

Error if no Workspace exists with the given input name.

Defined in: modules/graph/src/Graph.ts

Workspace

Accessors

aliases

Get Signature

get aliases(): string[]

Allow custom array of aliases. If the fully qualified package name is scoped, this will include the un-scoped name

Returns: string[]
Defined in: modules/graph/src/Workspace.ts

codeowners

Get Signature

get codeowners(): Required<Record<string, string[]>>

Returns: Required<Record<string, string[]>>
Defined in: modules/graph/src/Workspace.ts

config

Get Signature

get config(): Required<RootConfig | WorkspaceConfig>

Get the Workspace’s configuration

Returns: Required<RootConfig | WorkspaceConfig>
Defined in: modules/graph/src/Workspace.ts

dependencies

Get Signature

get dependencies(): Record<string, string>

Get the package.json defined production dependencies for the Workspace.

Returns: Record<string, string>

Map of modules to their version.

Defined in: modules/graph/src/Workspace.ts

description

Get Signature

get description(): undefined | string

Canonical to the package.json "description" field.

Returns: undefined | string
Defined in: modules/graph/src/Workspace.ts

devDependencies

Get Signature

get devDependencies(): Record<string, string>

Get the package.json defined development dependencies for the Workspace.

Returns: Record<string, string>

Map of modules to their version.

Defined in: modules/graph/src/Workspace.ts

isRoot

Get Signature

get isRoot(): boolean

Whether or not this Workspace is the root of the repository / Graph.

Returns: boolean
Defined in: modules/graph/src/Workspace.ts

location

Get Signature

get location(): string

Absolute path on the current filesystem to the Workspace.

Returns: string
Defined in: modules/graph/src/Workspace.ts

main

Get Signature

get main(): string

Returns: string
Defined in: modules/graph/src/Workspace.ts

name

Get Signature

get name(): string

The full name of the Workspace, as defined in its package.json

Returns: string
Defined in: modules/graph/src/Workspace.ts

packageJson

Get Signature

get packageJson(): PackageJson

A full deep copy of the package.json file for the Workspace. Modifications to this object will not be preserved on the Workspace.

Returns: PackageJson
Defined in: modules/graph/src/Workspace.ts

peerDependencies

Get Signature

get peerDependencies(): Record<string, string>

Get the package.json defined peer dependencies for the Workspace.

Returns: Record<string, string>

Map of modules to their version.

Defined in: modules/graph/src/Workspace.ts

private

Get Signature

get private(): boolean

If a Workspace package.json is set to private: true, it will not be available to publish through NPM or other package management registries.

Returns: boolean
Defined in: modules/graph/src/Workspace.ts

publishablePackageJson

Get Signature

get publishablePackageJson(): null | PublicPackageJson

Get a version of the Workspace’s package.json that is meant for publishing.

This strips off devDependencies and applies appropriate `publishConfig` values to the root of the package.json. This feature enables your monorepo to use source-dependencies and avoid manually building shared Workspaces for every change in order to see them take affect in dependent Workspaces.

To take advantage of this, configure your package.json root level to point to source files and the publishConfig entries to point to the build location of those entrypoints.

{
3 collapsed lines
  "name": "my-module",
  "license": "MIT",
  "type": "module",
  "main": "./src/index.ts",
  "publishConfig": {
    "access": "public",
    "main": "./dist/index.js",
    "typings": "./dist/index.d.ts"
  }
}

Returns: null | PublicPackageJson
Defined in: modules/graph/src/Workspace.ts

scope

Get Signature

get scope(): string

Get module name scope if there is one, eg @onerepo

Returns: string
Defined in: modules/graph/src/Workspace.ts

tasks

Get Signature

get tasks(): Partial<Record<Lifecycle, Tasks>>

Get the task configuration as defined in the onerepo.config.js file at the root of the Workspace.

Returns: Partial<Record<Lifecycle, Tasks>>

If a config does not exist, an empty object will be given.

Defined in: modules/graph/src/Workspace.ts

version

Get Signature

get version(): undefined | string

Returns: undefined | string
Defined in: modules/graph/src/Workspace.ts

Methods

getCodeowners()

getCodeowners(filepath): string[]

Parameters:

Parameter	Type
`filepath`	`string`

Returns: string[]
Defined in: modules/graph/src/Workspace.ts

getTasks()

getTasks(lifecycle): Required<Tasks>

Get a list of Workspace tasks for the given lifecycle

Parameters:

Parameter	Type
`lifecycle`	`string`

Returns: Required<Tasks>
Defined in: modules/graph/src/Workspace.ts

relative()

relative(to): string

Get the relative path of an absolute path to the Workspace’s location root

const relativePath = workspace.relative('/some/absolute/path');

Parameters:

Parameter	Type	Description
`to`	`string`	Absolute filepath

Returns: string

Relative path to the workspace’s root location.

Defined in: modules/graph/src/Workspace.ts

resolve()

resolve(...pathSegments): string

Resolve a full filepath within the Workspace given the path segments. Similar to Node.js’s path.resolve().

const main = workspace.resolve(workspace.main);

Parameters:

Parameter	Type	Description
…`pathSegments`	`string`[]	A sequence of paths or path segments

Returns: string

Absolute path based on the input path segments

Defined in: modules/graph/src/Workspace.ts

DependencyType

const DependencyType: {
  DEV: 2;
  PEER: 1;
  PROD: 3;
};

Type declaration

DEV

readonly DEV: 2;

Development-only dependency (defined in devDependencies keys of package.json)

PEER

readonly PEER: 1;

Peer dependency (defined in peerDependencies key of package.json)

PROD

readonly PROD: 3;

Production dependency (defined in dependencies of package.json)

Defined in: modules/graph/src/Graph.ts

DepType

type DepType: 1 | 2 | 3;

Dependency type value.

See also: `DependencyType`

Defined in: modules/graph/src/Graph.ts

GraphSchemaValidators

type GraphSchemaValidators: Record<string, Record<string, Schema & {
  $required: boolean;
 } | (workspace, graph) => Schema & {
  $required: boolean;
}>>;

Definition for graph verify JSON schema validators.

See “Validating configurations” for more examples and use cases.

import type { GraphSchemaValidators } from 'onerepo';

export default {
  '**': {
    'package.json': {
      type: 'object',
      $required: true,
      properties: {
        name: { type: 'string' },
      },
      required: ['name'],
    },
  },
} satisfies GraphSchemaValidators;

Defined in: modules/onerepo/src/core/graph/schema.ts

Logger

bufferSubLogger()

function bufferSubLogger(step): {
  end: () => Promise<void>;
  logger: Logger;
};

Alpha

Create a new Logger instance that has its output buffered up to a LogStep.

const step = logger.createStep(name, { writePrefixes: false });
const subLogger = bufferSubLogger(step);
const substep = subLogger.logger.createStep('Sub-step');
substep.warning('This gets buffered');
await substep.end();
await subLogger.end();
await step.en();

Parameters:

Parameter	Type
`step`	`LogStep`

Returns: ```ts { end: () => Promise; logger: Logger; }

##### end()

```ts
end: () => Promise<void>;

Returns: Promise<void>

logger

logger: Logger;

Defined in: modules/logger/src/index.ts

getLogger()

function getLogger(opts?): Logger;

This gets the logger singleton for use across all of oneRepo and its commands.

Available directly as `HandlerExtra` on `Handler` functions:

export const handler: Handler = (argv, { logger }) => {
  logger.log('Hello!');
};

Parameters:

Parameter	Type
`opts`?	`Partial`<`LoggerOptions`>

Returns: Logger
Defined in: modules/logger/src/index.ts

stepWrapper()

function stepWrapper<T>(options, fn): Promise<T>;

For cases where multiple processes need to be completed, but should be joined under a single `LogStep` to avoid too much noisy output, this safely wraps an asynchronous function and handles step creation and completion, unless a step override is given.

export async function exists(filename: string, { step }: Options = {}) {
  return stepWrapper({ step, name: 'Step fallback name' }, (step) => {
    return; // do some work
  });
}

Type Parameters

Type Parameter
`T`

Parameters:

Parameter	Type
`options`	{ `name`: `string`; `step`: `LogStep`; }
`options.name`	`string`
`options.step`?	`LogStep`
`fn`	(`step`) => `Promise`<`T`>

Returns: Promise<T>
Defined in: modules/logger/src/index.ts

Logger

The oneRepo logger helps build commands and capture output from spawned subprocess in a way that’s both delightful to the end user and includes easy to scan and follow output.

All output will be redirected from stdout to stderr to ensure order of output and prevent confusion of what output can be piped and written to files.

If the current terminal is a TTY, output will be buffered and asynchronous steps will animated with a progress logger.

See `HandlerExtra` for access the the global Logger instance.

Accessors

hasError

Get Signature

get hasError(): boolean

Whether or not an error has been sent to the logger or any of its steps. This is not necessarily indicative of uncaught thrown errors, but solely on whether .error() has been called in the Logger or any Step instance.

Returns: boolean
Defined in: modules/logger/src/Logger.ts

hasInfo

Get Signature

get hasInfo(): boolean

Whether or not an info message has been sent to the logger or any of its steps.

Returns: boolean
Defined in: modules/logger/src/Logger.ts

hasLog

Get Signature

get hasLog(): boolean

Whether or not a log message has been sent to the logger or any of its steps.

Returns: boolean
Defined in: modules/logger/src/Logger.ts

hasWarning

Get Signature

get hasWarning(): boolean

Whether or not a warning has been sent to the logger or any of its steps.

Returns: boolean
Defined in: modules/logger/src/Logger.ts

verbosity

Get Signature

get verbosity(): Verbosity

Get the logger’s verbosity level

Returns: Verbosity

Set Signature

set verbosity(value): void

Recursively applies the new verbosity to the logger and all of its active steps.

Parameters:

Parameter	Type
`value`	`Verbosity`

Returns: void
Defined in: modules/logger/src/Logger.ts

writable

Get Signature

get writable(): boolean

Returns: boolean
Defined in: modules/logger/src/Logger.ts

Methods

createStep()

createStep(name, __namedParameters?): LogStep

Create a sub-step, `LogStep`, for the logger. This and any other step will be tracked and required to finish before exit.

const step = logger.createStep('Do fun stuff');
// do some work
await step.end();

Parameters:

Parameter	Type	Description
`name`	`string`	The name to be written and wrapped around any output logged to this new step.
`__namedParameters`?	{ `writePrefixes`: `boolean`; }	-
`__namedParameters.writePrefixes`?	`boolean`	-

Returns: LogStep
Defined in: modules/logger/src/Logger.ts

pause()

pause(write?): void

When the terminal is a TTY, steps are automatically animated with a progress indicator. There are times when it’s necessary to stop this animation, like when needing to capture user input from stdin. Call the pause() method before requesting input and `logger.unpause()` when complete.

This process is also automated by the `run()` function when stdio is set to pipe.

logger.pause();
// capture input
logger.unpause();

Parameters:

Parameter	Type
`write`?	`boolean`

Returns: void
Defined in: modules/logger/src/Logger.ts

unpause()

unpause(): void

Unpause the logger and resume writing buffered logs to stderr. See `logger.pause()` for more information.

Returns: void
Defined in: modules/logger/src/Logger.ts

Logging

debug()

debug(contents): void

Extra debug logging when verbosity greater than or equal to 4.

logger.debug('Log this content when verbosity is >= 4');

If a function with zero arguments is passed, the function will be executed before writing. This is helpful for avoiding extra work in the event that the verbosity is not actually high enough to render the logged debug information:

logger.debug(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
See also: `debug()` This is a pass-through for the main step’s `debug()` method.

Defined in: modules/logger/src/Logger.ts

error()

error(contents): void

Log an error. This will cause the root logger to include an error and fail a command.

logger.error('Log this content when verbosity is >= 1');

logger.error(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
See also: `error()` This is a pass-through for the main step’s `error()` method.

Defined in: modules/logger/src/Logger.ts

info()

info(contents): void

Should be used to convey information or instructions through the log, will log when verbositu >= 1

logger.info('Log this content when verbosity is >= 1');

logger.info(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
See also: `info()` This is a pass-through for the main step’s `info()` method.

Defined in: modules/logger/src/Logger.ts

log()

log(contents): void

General logging information. Useful for light informative debugging. Recommended to use sparingly.

logger.log('Log this content when verbosity is >= 3');

logger.log(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
See also: `log()` This is a pass-through for the main step’s `log()` method.

Defined in: modules/logger/src/Logger.ts

timing()

timing(start, end): void

Log timing information between two Node.js performance mark names.

Parameters:

Parameter	Type	Description
`start`	`string`	A `PerformanceMark` entry name
`end`	`string`	A `PerformanceMark` entry name

Returns: void
See also: `timing()` This is a pass-through for the main step’s `timing()` method.

Defined in: modules/logger/src/Logger.ts

warn()

warn(contents): void

Log a warning. Does not have any effect on the command run, but will be called out.

logger.warn('Log this content when verbosity is >= 2');

logger.warn(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
See also: `warn()` This is a pass-through for the main step’s `warn()` method.

Defined in: modules/logger/src/Logger.ts

LogStep

Log steps should only be created via the `logger.createStep()` method.

const step = logger.createStep('Do some work');
// ... long task with a bunch of potential output
await step.end();

Properties

Property	Type	Description	Defined in
`hasError`	`boolean`	Whether or not an error has been sent to the step. This is not necessarily indicative of uncaught thrown errors, but solely on whether `.error()` has been called in this step.	modules/logger/src/LogStep.ts
`hasInfo`	`boolean`	Whether or not an info message has been sent to this step.	modules/logger/src/LogStep.ts
`hasLog`	`boolean`	Whether or not a log message has been sent to this step.	modules/logger/src/LogStep.ts
`hasWarning`	`boolean`	Whether or not a warning has been sent to this step.	modules/logger/src/LogStep.ts

Methods

end()

end(): Promise<void>

Finish this step and flush all buffered logs. Once a step is ended, it will no longer accept any logging output and will be effectively removed from the base logger. Consider this method similar to a destructor or teardown.

await step.end();

Returns: Promise<void>
Defined in: modules/logger/src/LogStep.ts

Logging

debug()

debug(contents): void

Extra debug logging when verbosity greater than or equal to 4.

step.debug('Log this content when verbosity is >= 4');

step.debug(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
Defined in: modules/logger/src/LogStep.ts

error()

error(contents): void

Log an error. This will cause the root logger to include an error and fail a command.

step.error('Log this content when verbosity is >= 1');

step.error(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
Defined in: modules/logger/src/LogStep.ts

info()

info(contents): void

Log an informative message. Should be used when trying to convey information with a user that is important enough to always be returned.

step.info('Log this content when verbosity is >= 1');

step.info(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
Defined in: modules/logger/src/LogStep.ts

log()

log(contents): void

General logging information. Useful for light informative debugging. Recommended to use sparingly.

step.log('Log this content when verbosity is >= 3');

step.log(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
Defined in: modules/logger/src/LogStep.ts

timing()

timing(start, end): void

Log timing information between two Node.js performance mark names.

Parameters:

Parameter	Type	Description
`start`	`string`	A `PerformanceMark` entry name
`end`	`string`	A `PerformanceMark` entry name

Returns: void
Defined in: modules/logger/src/LogStep.ts

warn()

warn(contents): void

Log a warning. Does not have any effect on the command run, but will be called out.

step.warn('Log this content when verbosity is >= 2');

step.warn(() => bigArray.map((item) => item.name));

Parameters:

Parameter	Type	Description
`contents`	`unknown`	Any value that can be converted to a string for writing to `stderr`.

Returns: void
Defined in: modules/logger/src/LogStep.ts

LoggerOptions

type LoggerOptions: {
  stream: Writable;
  verbosity: Verbosity;
};

Type declaration

stream?

optional stream: Writable;

Advanced – override the writable stream in order to pipe logs elsewhere. Mostly used for dependency injection for @onerepo/test-cli.

verbosity

verbosity: Verbosity;

Control how much and what kind of output the Logger will provide.

Defined in: modules/logger/src/Logger.ts

Verbosity

type Verbosity:
  | 0
  | 1
  | 2
  | 3
  | 4
  | 5;

Control the verbosity of the log output

Value	What	Description
`<= 0`	Silent	No output will be read or written.
`>= 1`	Error, Info
`>= 2`	Warnings
`>= 3`	Log
`>= 4`	Debug	`logger.debug()` will be included
`>= 5`	Timing	Extra performance timing metrics will be written

Defined in: modules/logger/src/Logger.ts

Package management

getLockfile()

function getLockfile(cwd): string | null;

Get the absolute path for the package manager’s lock file for this repository.

Parameters:

Parameter	Type
`cwd`	`string`

Returns: string | null
Defined in: modules/package-manager/src/get-package-manager.ts

getPackageManager()

function getPackageManager(type): PackageManager;

Get the `PackageManager` for the given package manager type (NPM, PNPm, or Yarn)

Parameters:

Parameter	Type
`type`	`"yarn"` \| `"pnpm"` \| `"npm"`

Returns: PackageManager
Defined in: modules/package-manager/src/index.ts

getPackageManagerName()

function getPackageManagerName(cwd, fromPkgJson?): 'npm' | 'pnpm' | 'yarn';

Get the package manager for the current working directory with some confidence

Parameters:

Parameter	Type	Description
`cwd`	`string`	Current working directory. Should be the root of the module/repository.
`fromPkgJson`?	`string`	Value as defined in a package.json file, typically the `packageManager` value

Returns: "npm" | "pnpm" | "yarn"
Defined in: modules/package-manager/src/get-package-manager.ts

PackageManager

Implementation details for all package managers. This interface defines a subset of common methods typically needed when interacting with a monorepo and its dependency `Graph` & `Workspace`s.

Methods

add()

add(packages, opts?): Promise<void>

Add one or more packages from external registries

Parameters:

Parameter	Type	Description
`packages`	`string` \| `string`[]	One or more packages, by name and/or `'name@version'`.
`opts`?	{ `dev`: `boolean`; }	Various options to pass while installing the packages
`opts.dev`?	`boolean`	Set to true to install as a `devDependency`. Default `false`

Returns: Promise<void>
Defined in: modules/package-manager/src/methods.ts

batch()

batch(processes): Promise<(Error | [string, string])[]>

Batch commands from npm packages as a batch of subprocesses using the package manager. Alternative to batching with npm exec and compatible APIs.

Parameters:

Parameter	Type
`processes`	`RunSpec`[]

Returns: Promise<(Error | [string, string])[]>
See also: `batch` for general subprocess batching.

Defined in: modules/package-manager/src/methods.ts

dedupe()

dedupe(): Promise<void>

Reduce duplication in the package tree by checking overlapping ranges.

Returns: Promise<void>
Defined in: modules/package-manager/src/methods.ts

info()

info(name, opts?): Promise<null | NpmInfo>

Get standard information about a package

Parameters:

Parameter	Type
`name`	`string`
`opts`?	`Partial`<`RunSpec`>

Returns: Promise<null | NpmInfo>
Defined in: modules/package-manager/src/methods.ts

install()

install(cwd?): Promise<string>

Install current dependencies as listed in the package manager’s lock file

Parameters:

Parameter	Type
`cwd`?	`string`

Returns: Promise<string>
Defined in: modules/package-manager/src/methods.ts

loggedIn()

loggedIn(opts?): Promise<boolean>

Check if the current user is logged in to the external registry

Parameters:

Parameter	Type	Description
`opts`?	{ `registry`: `string`; `scope`: `string`; }	-
`opts.registry`?	`string`	The base URL of your NPM registry. PNPM and NPM ignore scope and look up per-registry.
`opts.scope`?	`string`	When using Yarn, lookups are done by registry configured by scope. This value must be included if you have separate registries for separate scopes.

Returns: Promise<boolean>
Defined in: modules/package-manager/src/methods.ts

publish()

publish<T>(opts): Promise<void>

Publish Workspaces to the external registry

Type Parameters

Type Parameter
`T` extends `MinimalWorkspace`

Parameters:

Parameter	Type	Description
`opts`	{ `access`: `"restricted"` \| `"public"`; `cwd`: `string`; `otp`: `string`; `tag`: `string`; `workspaces`: `T`[]; }	-
`opts.access`?	`"restricted"` \| `"public"`	Set the registry access level for the package Default inferred from Workspaces `publishConfig.access` or `'public'`
`opts.cwd`?	`string`	Command working directory. Defaults to the repository root.
`opts.otp`?	`string`	This is a one-time password from a two-factor authenticator.
`opts.tag`?	`string`	If you ask npm to install a package and don’t tell it a specific version, then it will install the specified tag. Default `'latest'`
`opts.workspaces`	`T`[]	Workspaces to publish. If not provided or empty array, only the given Workspace at `cwd` will be published. This type is generally compatible with `Workspace`.

Returns: Promise<void>
Defined in: modules/package-manager/src/methods.ts

publishable()

publishable<T>(workspaces): Promise<T[]>

Filter Workspaces to the set of those that are actually publishable. This will check both whether the package is not marked as “private” and if the current version is not in the external registry.

Type Parameters

Type Parameter
`T` extends `MinimalWorkspace`

Parameters:

Parameter	Type	Description
`workspaces`	`T`[]	List of compatible `Workspace` objects.

Returns: Promise<T[]>
Defined in: modules/package-manager/src/methods.ts

remove()

remove(packages): Promise<void>

Remove one or more packages.

Parameters:

Parameter	Type	Description
`packages`	`string` \| `string`[]	One or more packages, by name

Returns: Promise<void>
Defined in: modules/package-manager/src/methods.ts

run()

run(opts): Promise<[string, string]>

Run a command from an npm package as a subprocess using the package manager. Alternative to npm exec and compatible APIs.

Parameters:

Parameter	Type
`opts`	`RunSpec`

Returns: Promise<[string, string]>
See also: `batch` for general subprocess running.

Defined in: modules/package-manager/src/methods.ts

MinimalWorkspace

type MinimalWorkspace: {
  location: string;
  name: string;
  private: boolean;
  version: string;
};

Type declaration

location?

optional location: string;

name

name: string;

private?

optional private: boolean;

version?

optional version: string;

Defined in: modules/package-manager/src/methods.ts

NpmInfo

type NpmInfo: {
  dependencies: Record<string, string>;
  dist-tags: {
   [key: string]: string;   latest: string;
    };
  homepage: string;
  license: string;
  name: string;
  version: string;
  versions: string[];
};

Type declaration

dependencies

dependencies: Record<string, string>;

dist-tags

dist-tags: {
[key: string]: string;   latest: string;
};

Type declaration

Index Signature

[key: string]: string

dist-tags.latest

latest: string;

homepage

homepage: string;

license

license: string;

name

name: string;

version

version: string;

versions

versions: string[];

Defined in: modules/package-manager/src/methods.ts

Plugins

Plugin

type Plugin: PluginObject | (config, graph) => PluginObject;

Defined in: modules/onerepo/src/types/plugin.ts

PluginObject

type PluginObject: {
  shutdown: (argv) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
  startup: (argv) => Promise<void> | void;
  yargs: (yargs, visitor) => Yargs;
};

Type declaration

shutdown()?

optional shutdown: (argv) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;

Runs just before the application process is exited. Allows returning data that will be merged with all other shutdown handlers.

Parameters:

Parameter	Type
`argv`	`Argv`<`DefaultArgv`>

Returns: Promise<Record<string, unknown> | void> | Record<string, unknown> | void

startup()?

optional startup: (argv) => Promise<void> | void;

Runs before any and all commands after argument parsing. This is similar to global Yargs middleware, but guaranteed to have the fully resolved and parsed arguments.

Use this function for setting up global even listeners like PerformanceObserver, process events, etc.

Parameters:

Parameter	Type
`argv`	`Argv`<`DefaultArgv`>

Returns: Promise<void> | void

yargs()?

optional yargs: (yargs, visitor) => Yargs;

A function that is called with the CLI’s yargs object and a visitor. It is important to ensure every command passed through the visitor to enable all of the features of oneRepo. Without this step, you will not have access to the Workspace Graph, affected list, and much more.

Parameters:

Parameter	Type
`yargs`	`Yargs`
`visitor`	`NonNullable`<`RequireDirectoryOptions`[`"visit"`]>

Returns: Yargs
Defined in: modules/onerepo/src/types/plugin.ts

Subprocess

batch()

function batch(processes, options?): Promise<([string, string] | Error)[]>;

Batch multiple subprocesses, similar to Promise.all, but only run as many processes at a time fulfilling N-1 cores. If there are more processes than cores, as each process finishes, a new process will be picked to run, ensuring maximum CPU usage at all times.

If any process throws a SubprocessError, this function will reject with a BatchError, but only after all processes have completed running.

Most oneRepo commands will consist of at least one `run()` or `batch()` processes.

const processes: Array<RunSpec> = [
  { name: 'Say hello', cmd: 'echo', args: ['"hello"'] },
  { name: 'Say world', cmd: 'echo', args: ['"world"'] },
];

const results = await batch(processes);

expect(results).toEqual([
  ['hello', ''],
  ['world', ''],
]);

Parameters:

Parameter	Type
`processes`	(`RunSpec` \| `PromiseFn`)[]
`options`?	`BatchOptions`

Returns: Promise<([string, string] | Error)[]>

Throws

`BatchError` An object that includes a list of all of the `SubprocessError`s thrown.

See also: `PackageManager.batch` to safely batch executables exposed from third party modules.

Defined in: modules/subprocess/src/index.ts

run()

function run(options): Promise<[string, string]>;

Spawn a process and capture its stdout and stderr through a Logger Step. Most oneRepo commands will consist of at least one `run()` or `batch()` processes.

The run() command is an async wrapper around Node.js’s child_process.spawn and has a very similar API, with some additions. This command will buffer and catch all stdout and stderr responses.

await run({
  name: 'Do some work',
  cmd: 'echo',
  args: ['"hello!"'],
});

Skipping failures:

If a subprocess fails when called through run(), a `SubprocessError` will be thrown. Some third-party tooling will exit with error codes as an informational tool. While this is discouraged, there’s nothing we can do about how they’ve been chosen to work. To prevent throwing errors, but still act on the stderr response, include the skipFailures option:

const [stdout, stderr] = await run({
  name: 'Run dry',
  cmd: 'echo',
  args: ['"hello"'],
  skipFailures: true,
});

logger.error(stderr);

Dry-run:

By default, run() will respect oneRepo’s --dry-run option (see `DefaultArgv`, process.env.ONEREPO_DRY_RUN). When set, the process will not be spawned, but merely log information about what would run instead. To continue running a command, despite the --dry-run option being set, use runDry: true:

await run({
  name: 'Run dry',
  cmd: 'echo',
  args: ['"hello"'],
  runDry: true,
});

Parameters:

Parameter	Type
`options`	`RunSpec`

Returns: Promise<[string, string]>

A promise with an array of [stdout, stderr], as captured from the command run.

Throws

`SubprocessError` if not skipFailures and the spawned process does not exit cleanly (with code 0)

See also: `PackageManager.run` to safely run executables exposed from third party modules.

Defined in: modules/subprocess/src/index.ts

runTasks()

function runTasks(lifecycle, args, graph, logger?): Promise<void>;

Alpha

Run Lifecycle tasks in commands other than the one tasks command. Use this function when you have a command triggering a Lifecycle in non-standard ways.

await runTasks('pre-publish', ['-w', 'my-workspace'], graph);

Parameters:

Parameter	Type	Description
`lifecycle`	`Lifecycle`	The individual Lifecycle to trigger.
`args`	`string`[]	Array of string arguments as if passed in from the command-line.
`graph`	`Graph`	The current repository Graph.
`logger`?	`Logger`	Optional Logger instance. Defaults to the current `Logger` (usually there is only one).

Returns: Promise<void>
Defined in: modules/onerepo/src/core/tasks/run-tasks.ts

start()

function start(options): ChildProcess;

Start a subprocess. For use when control over watching the stdout and stderr or long-running processes that are not expected to complete without SIGINT/SIGKILL.

Parameters:

Parameter	Type
`options`	`Omit`<`RunSpec`, `"name"` \| `"runDry"`>

Returns: ChildProcess
Defined in: modules/subprocess/src/index.ts

sudo()

function sudo(options): Promise<[string, string]>;

This function is similar to run, but can request and run with elevated sudo permissions. This function should not be used unless you absolutely know that you will need to spawn an executable with elevated permissions.

This function will first check if sudo permissions are valid. If not, the logger will warn the user that sudo permissions are being requested and properly pause the animated logger while the user enters their password directly through stdin. If permissions are valid, no warning will be given.

await sudo({
  name: 'Change permissions',
  cmd: 'chmod',
  args: ['a+x', '/usr/bin/thing'],
  reason: 'When prompted, please type your password and hit [RETURN] to allow `thing` to be run later',
});

Parameters:

Parameter	Type
`options`	`Omit`<`RunSpec`, `"opts"`> & { `reason`: `string`; }

Returns: Promise<[string, string]>
Defined in: modules/subprocess/src/index.ts

BatchError

Extends

Error

Constructors

new BatchError()

new BatchError(errors, options?): BatchError

Parameters:

Parameter	Type
`errors`	(`string` \| `SubprocessError`)[]
`options`?	`ErrorOptions`

Returns: BatchError

Overrides

Error.constructor

Defined in: modules/subprocess/src/index.ts

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`cause?`	`public`	`unknown`	-	`Error.cause`	node_modules/typescript/lib/lib.es2022.error.d.ts:26
`errors`	`public`	(`string` \| `SubprocessError`)[]	-	-	modules/subprocess/src/index.ts
`message`	`public`	`string`	-	`Error.message`	node_modules/typescript/lib/lib.es5.d.ts:1077
`name`	`public`	`string`	-	`Error.name`	node_modules/typescript/lib/lib.es5.d.ts:1076
`prepareStackTrace?`	`static`	(`err`: `Error`, `stackTraces`: `CallSite`[]) => `any`	Optional override for formatting stack traces See https://v8.dev/docs/stack-trace-api#customizing-stack-traces	`Error.prepareStackTrace`	node_modules/@types/node/globals.d.ts:98
`stack?`	`public`	`string`	-	`Error.stack`	node_modules/typescript/lib/lib.es5.d.ts:1078
`stackTraceLimit`	`static`	`number`	-	`Error.stackTraceLimit`	node_modules/@types/node/globals.d.ts:100

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Create .stack property on a target object

Parameters:

Parameter	Type
`targetObject`	`object`
`constructorOpt`?	`Function`

Returns: void

Inherited from

Error.captureStackTrace

Defined in: node_modules/@types/node/globals.d.ts:91

SubprocessError

Extends

Error

Constructors

new SubprocessError()

new SubprocessError(message, options?): SubprocessError

Parameters:

Parameter	Type
`message`	`string`
`options`?	`ErrorOptions`

Returns: SubprocessError

Overrides

Error.constructor

Defined in: modules/subprocess/src/index.ts

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`cause?`	`public`	`unknown`	-	`Error.cause`	node_modules/typescript/lib/lib.es2022.error.d.ts:26
`message`	`public`	`string`	-	`Error.message`	node_modules/typescript/lib/lib.es5.d.ts:1077
`name`	`public`	`string`	-	`Error.name`	node_modules/typescript/lib/lib.es5.d.ts:1076
`prepareStackTrace?`	`static`	(`err`: `Error`, `stackTraces`: `CallSite`[]) => `any`	Optional override for formatting stack traces See https://v8.dev/docs/stack-trace-api#customizing-stack-traces	`Error.prepareStackTrace`	node_modules/@types/node/globals.d.ts:98
`stack?`	`public`	`string`	-	`Error.stack`	node_modules/typescript/lib/lib.es5.d.ts:1078
`stackTraceLimit`	`static`	`number`	-	`Error.stackTraceLimit`	node_modules/@types/node/globals.d.ts:100

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Create .stack property on a target object

Parameters:

Parameter	Type
`targetObject`	`object`
`constructorOpt`?	`Function`

Returns: void

Inherited from

Error.captureStackTrace

Defined in: node_modules/@types/node/globals.d.ts:91

BatchOptions

type BatchOptions: {
  maxParallel: number;
};

Options for running `batch()` subprocesses.

Type declaration

maxParallel?

optional maxParallel: number;

The absolute maximum number of subprocesses to batch. This amount will always be limited by the number of CPUs/cores available on the current machine.

Default: deterministic Number of CPUs - 1
Defined in: modules/subprocess/src/index.ts

PromiseFn()

type PromiseFn: () => Promise<[string, string]>;

Returns: Promise<[string, string]>
Defined in: modules/subprocess/src/index.ts

RunSpec

type RunSpec: {
  args: string[];
  cmd: string;
  name: string;
  opts: SpawnOptions;
  runDry: boolean;
  skipFailures: boolean;
  step: LogStep;
};

The core configuration for `run`, `start`, `sudo`, and `batch` subprocessing.

Type declaration

args?

optional args: string[];

Arguments to pass to the executable. All arguments must be separate string entries.

Beware that some commands have different ways of parsing arguments.

Typically, it is safest to have separate entries in the args array for the flag and its value:

args: ['--some-flag', 'some-flags-value']

However, if an argument parser is implemented in a non-standard way, the flag and its value may need to be a single entry:

args: ['--some-flag=some-flags-value']

cmd

cmd: string;

The command to run. This should be an available executable or path to an executable.

name

name: string;

A friendly name for the Step in log output.

opts?

optional opts: SpawnOptions;

See the Node.js child_process.spawn() documentation for available options.

runDry?

optional runDry: boolean;

Skip the --dry-run check and run this command anyway.

skipFailures?

optional skipFailures: boolean;

Prevents throwing a `SubprocessError` in the event of the process failing and exiting with an unclean state.

step?

optional step: LogStep;

Pass a custom `LogStep` to bundle this process input & output into another step instead of creating a new one.

Defined in: modules/subprocess/src/index.ts

package.json

getPublishablePackageJson()

function getPublishablePackageJson(input): PublicPackageJson;

Return a deep copy of a package.json suitabkle for publishing. Moves all non-standard publishConfig keys to the root of the package.json and deletes devDependencies.

Parameters:

Parameter	Type
`input`	`PublicPackageJson`

Returns: PublicPackageJson
Defined in: modules/package-manager/src/package-json.ts

BasePackageJson

type BasePackageJson: {
  alias: string[];
  author: string | Person;
  bin: string | Record<string, string>;
  bugs: {
     email: string;
     url: string;
    };
  bundleDependencies: string[];
  contributors: (Person | string)[];
  dependencies: Record<string, string>;
  description: string;
  devDependencies: Record<string, string>;
  engines: Record<string, string>;
  exports: Record<string, string | {
     default: string;
     import: string;
     require: string;
     types: string;
    }>;
  files: string[];
  homepage: string;
  keywords: string[];
  license: string;
  main: string;
  name: string;
  optionalDependencies: string[];
  os: string[];
  overrides: Record<string, string>;
  packageManager: string;
  peerDependencies: Record<string, string>;
  peerDependenciesMeta: Record<string, {
     optional: boolean;
    }>;
  scripts: Record<string, string>;
  version: string;
};

Type declaration

alias?

optional alias: string[];

Enable’s the `Graph` to look up `Workspace`s by shorter names or common `aliases` used by teams. This enables much short command-line execution. See `Graph.getByName` and `Graph.getAllByName`.

author?

optional author: string | Person;

bin?

optional bin: string | Record<string, string>;

bugs?

optional bugs: {
  email: string;
  url: string;
};

Type declaration

bugs.email?

optional email: string;

bugs.url?

optional url: string;

bundleDependencies?

optional bundleDependencies: string[];

contributors?

optional contributors: (Person | string)[];

dependencies?

optional dependencies: Record<string, string>;

description?

optional description: string;

devDependencies?

optional devDependencies: Record<string, string>;

engines?

optional engines: Record<string, string>;

exports?

optional exports: Record<string, string | {
  default: string;
  import: string;
  require: string;
  types: string;
}>;

files?

optional files: string[];

homepage?

optional homepage: string;

keywords?

optional keywords: string[];

license?

optional license: string;

main?

optional main: string;

name

name: string;

The full name for the `Workspace`. This will be used within the package manager and publishable registry.

optionalDependencies?

optional optionalDependencies: string[];

os?

optional os: string[];

overrides?

optional overrides: Record<string, string>;

packageManager?

optional packageManager: string;

peerDependencies?

optional peerDependencies: Record<string, string>;

peerDependenciesMeta?

optional peerDependenciesMeta: Record<string, {
  optional: boolean;
}>;

scripts?

optional scripts: Record<string, string>;

version?

optional version: string;

Defined in: modules/package-manager/src/package-json.ts

PackageJson

type PackageJson: PrivatePackageJson | PublicPackageJson;

Defined in: modules/package-manager/src/package-json.ts

Person

type Person: {
  email: string;
  name: string;
  url: string;
};

Type declaration

email?

optional email: string;

name?

optional name: string;

url?

optional url: string;

Defined in: modules/package-manager/src/package-json.ts

PrivatePackageJson

type PrivatePackageJson: {
  license: "UNLICENSED";
  private: true;
  workspaces: string[];
 } & BasePackageJson;

Type declaration

license?

optional license: "UNLICENSED";

private

private: true;

workspaces?

optional workspaces: string[];

Defined in: modules/package-manager/src/package-json.ts

PublicPackageJson

type PublicPackageJson: {
  private: false;
  publishConfig: PublishConfig;
  workspaces: never;
 } & BasePackageJson;

Type declaration

private?

optional private: false;

publishConfig?

optional publishConfig: PublishConfig;

workspaces?

optional workspaces: never;

Defined in: modules/package-manager/src/package-json.ts

PublishConfig

type PublishConfig: {
[key: string]: unknown;   bin: string | Record<string, string>;
  exports: Record<string, string | {
     default: string;
     import: string;
     require: string;
     types: string;
    }>;
  main: string;
  module: string;
  typings: string;
};

The publishConfig should follow NPM’s guidelines, apart from the possible defined extra keys here. Anything defined here will be merged back to the root of the package.json at publish time.

Use these keys to help differentiate between your repository’s source-dependency entrypoints vs published module entrypoints.

{
3 collapsed lines
  "name": "my-module",
  "license": "MIT",
  "type": "module",
  "main": "./src/index.ts",
  "publishConfig": {
    "access": "public",
    "main": "./dist/index.js",
    "typings": "./dist/index.d.ts"
  }
}

Type declaration

Index Signature

[key: string]: unknown

bin?

optional bin: string | Record<string, string>;

exports?

optional exports: Record<string, string | {
  default: string;
  import: string;
  require: string;
  types: string;
}>;

main?

optional main: string;

module?

optional module: string;

typings?

optional typings: string;

Defined in: modules/package-manager/src/package-json.ts

Namespaces

Namespace	Description
builders	Common and reusable command-line option builders.
file	File manipulation functions.
git	Special handlers for managing complex queries and manipulation of the git repository’s state.