oneRepo API: builders

import { builders } from 'onerepo';

export const name = 'mycommand';

export const builder: Builder = (yargs) => builders.withWorkspaces(yargs);

export const handler: Handler = async (argv, { getWorkspaces, logger }) => {
  const workspaces = await getWorkspaces();

  logger.log(workspaces.map(({ name }) => name));
};

$ one mycommand --workspaces ws-1 ws-2
['ws-1', 'ws-2']

Common and reusable command-line option builders.

Type Aliases

FileGetterOptions

type FileGetterOptions: GetterOptions & {
  affectedThreshold: number;
};

Type declaration

affectedThreshold?

optional affectedThreshold: number;

Threshold of number of files until we fall-back and swap to Workspace locations. This exists as a safeguard from attempting to pass too many files through to subprocesses and hitting the limit on input argv, resulting in unexpected and unexplainable errors.

Default Value

100;

Defined in: modules/builders/src/getters.ts

Staged

type Staged: {
  from: never;
  staged: true;
  through: never;
};

Type declaration

from?

optional from: never;

staged

staged: true;

Limit to only changes that are currently staged. This cannot be used with from and through.

through?

optional through: never;

Defined in: modules/builders/src/getters.ts

Through

type Through: {
  from: string;
  staged: false;
  through: string;
};

Type declaration

from?

optional from: string;

Git ref to calculate changes exclusively since.

staged?

optional staged: false;

through?

optional through: string;

Git ref to calculate changes inclusively through.

Defined in: modules/builders/src/getters.ts

Builders

withAffected()

function withAffected<T>(yargs): Yargs<T & WithAffected>;

Adds the following input arguments to command `Handler`. Typically used in conjunction with getters like `builders.getAffected`, `builders.getFilepaths`, and `builders.getGetWorkspaces`.

--affected
--from-ref
--through-ref

If all of --all, --files, and --workspaces were not passed, --affected will default to true.

See WithAffected for type safety.

export const builder = (yargs) => builders.withAffected(yargs);

Type Parameters

Type Parameter
`T`

Parameters:

Parameter	Type
`yargs`	`Yargs`<`T`>

Returns: Yargs<T & WithAffected>
Defined in: modules/builders/src/with-affected.ts

withAllInputs()

function withAllInputs(yargs): Yargs<WithAllInputs>;

Helper to chain all of `builders.withAffected`, `builders.withFiles`, and `builders.withWorkspaces` on a `Builder`.

export const builder = (yargs) => builders.withAllInputs(yargs);

Parameters:

Parameter	Type
`yargs`	`Yargs`<`DefaultArgv`>

Returns: Yargs<WithAllInputs>
Defined in: modules/builders/src/with-all-inputs.ts

withFiles()

function withFiles<T>(yargs): Yargs<T & WithFiles>;

Adds the following input arguments to command `Handler`. Typically used in conjunction with getters like `builders.getFilepaths`.

--files

See WithFiles for type safety.

export const builder = (yargs) => builders.withFiles(yargs);

Type Parameters

Type Parameter
`T`

Parameters:

Parameter	Type
`yargs`	`Yargs`<`T`>

Returns: Yargs<T & WithFiles>
Defined in: modules/builders/src/with-files.ts

withWorkspaces()

function withWorkspaces<T>(yargs): Yargs<T & WithWorkspaces>;

Adds the following input arguments to command `Handler`. Typically used in conjunction with getters like `builders.getAffected` `builders.getWorkspaces`.

--all
--workspaces

See `builders.WithWorkspaces` for type safety.

export const builder = (yargs) => builders.withWorkspaces(yargs);

Type Parameters

Type Parameter
`T`

Parameters:

Parameter	Type
`yargs`	`Yargs`<`T`>

Returns: Yargs<T & WithWorkspaces>
Defined in: modules/builders/src/with-workspaces.ts

WithAffected

type WithAffected: {
  affected: boolean;
  from-ref: string;
  staged: boolean;
  through-ref: string;
};

To be paired with the `builders.withAffected`. Adds types for arguments parsed.

type Argv = builders.WithAffected & {
  // ...
};

export const builder: Builder<Argv> = (yargs) => builders.withAffected(yargs);

Type declaration

affected?

optional affected: boolean;

When used with builder helpers, will include all of the affected Workspaces based on changes within the repository.

from-ref?

optional from-ref: string;

Git ref to calculate changes exclusively since.

staged?

optional staged: boolean;

Calculate changes based inclusively on the files added to the git stage.

through-ref?

optional through-ref: string;

Git ref to calculate changes inclusively through.

Defined in: modules/builders/src/with-affected.ts

WithAllInputs

type WithAllInputs: WithAffected & WithFiles & WithWorkspaces;

Helper to include all of `builders.withAffected`, `builders.withFiles`, and `builders.withWorkspaces` on builder `Argv`.

type Argv = builders.WithAllInputs & {
  // ...
};

export const builder: Builder<Argv> = (yargs) => builders.withAllInputs(yargs);

Defined in: modules/builders/src/with-all-inputs.ts

WithFiles

type WithFiles: {
  files: string[];
};

To be paired with the `builders.withFiles`. Adds types for arguments parsed.

type Argv = builders.WithFiles & {
  // ...
};

export const builder: Builder<Argv> = (yargs) => builders.withFiles(yargs);

Type declaration

files?

optional files: string[];

List of filepaths.

Defined in: modules/builders/src/with-files.ts

WithWorkspaces

type WithWorkspaces: {
  all: boolean;
  workspaces: string[];
};

To be paired with the `builders.withWorkspaces`. Adds types for arguments parsed.

type Argv = builders.WithWorkspaces & {
  // ...
};

export const builder: Builder<Argv> = (yargs) => builders.withWorkspaces(yargs);

Type declaration

all?

optional all: boolean;

Include all Workspaces.

workspaces?

optional workspaces: string[];

One or more Workspaces by name or alias string.

Defined in: modules/builders/src/with-workspaces.ts

Getters

getAffected()

function getAffected(graph, __namedParameters?): Promise<Workspace[]>;

Get a list of the affected Workspaces.

Typically, this should be used from the helpers provided by the command `Handler`, in which case the first argument has been scoped for you already.

If the root Workspace is included in the list, all Workspaces will be presumed affected and returned.

export const handler: Handler = (argv, { getAffected, logger }) => {
  const workspaces = await getAffected();
  for (const ws of workspaces) {
    logger.log(ws.name);
  }
};

Parameters:

Parameter	Type
`graph`	`Graph`
`__namedParameters`?	`GetterOptions`

Returns: Promise<Workspace[]>
Defined in: modules/builders/src/getters.ts

getFilepaths()

function getFilepaths(graph, argv, __namedParameters?): Promise<string[]>;

Get a list of filepaths based on the input arguments made available with the builders `builders.withAffected`, `builders.withAllInputs`, `builders.withFiles`, and `builders.withWorkspaces`.

When providing --workspaces <names>, the paths will be paths to the requested Workspaces, not individual files.

Typically, this should be used from the helpers provided by the command handler’s `HandlerExtra`, in which case the first argument has been scoped for you already.

When using this function to get affected filenames, a soft threshold is provided at 100 files. This is a safeguard against overloading subprocess `run` arguments. When the threshold is hit, this function will swap to return the set of parent Workspace locations for the affected file lists.

export const handler: Handler = (argv, { getFilepaths, logger }) => {
  const filepaths = await getFilepaths();
  for (const files of filepaths) {
    logger.log(files);
  }
};

Parameters:

Parameter	Type
`graph`	`Graph`
`argv`	`WithAllInputs`
`__namedParameters`?	`FileGetterOptions`

Returns: Promise<string[]>
See also: !HandlerExtra

Defined in: modules/builders/src/getters.ts

getWorkspaces()

function getWorkspaces(graph, argv, __namedParameters?): Promise<Workspace[]>;

Get a list of Workspaces based on the input arguments made available with the builders `builders.withAffected`, `builders.withAllInputs`, `builders.withFiles`, and `builders.withWorkspaces`.

Typically, this should be used from the helpers provided by the command `Handler`, in which case the first argument has been scoped for you already.

If the root Workspace is included in the list, all Workspaces will be presumed affected and returned.

export const handler: Handler = (argv, { getWorkspaces, logger }) => {
  const workspaces = await getWorkspaces();
  for (const ws of workspaces) {
    logger.log(ws.name);
  }
};

Parameters:

Parameter	Type
`graph`	`Graph`
`argv`	`WithAllInputs`
`__namedParameters`?	`GetterOptions`

Returns: Promise<Workspace[]>
Defined in: modules/builders/src/getters.ts

Argv

type Argv: WithAllInputs;

Defined in: modules/builders/src/getters.ts

GetterOptions

type GetterOptions: Through | Staged & {
  ignore: string[];
  step: LogStep;
};

Type declaration

ignore?

optional ignore: string[];

List of files to not take into account when getting the list of files, workspaces, and affected.

step?

optional step: LogStep;

Optional logger step to avoid creating a new

Defined in: modules/builders/src/getters.ts