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;
};

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

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;

Staged

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

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

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;

Through

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

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

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.

Builders

withAffected()

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

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

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>

withAllInputs()

function withAllInputs(yargs): Yargs<WithAllInputs>;

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

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>

withFiles()

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

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

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>

withWorkspaces()

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

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

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>

WithAffected

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

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

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.

WithAllInputs

type WithAllInputs = WithAffected & WithFiles & WithWorkspaces;

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

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);

WithFiles

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

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

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.

WithWorkspaces

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

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

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.

Getters

getAffected()

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

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

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

getFilepaths()

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

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

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

getWorkspaces()

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

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

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

Argv

type Argv = WithAllInputs;

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

GetterOptions

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

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

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