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

Properties

from?

optional from: never;

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

staged

staged: true;

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

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

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

Properties

from?

optional from: string;

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

Git ref to calculate changes exclusively since.

staged?

optional staged: false;

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

through?

optional through: string;

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

Git ref to calculate changes inclusively through.

Builders

withAffected()

const 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()

const 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()

const 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()

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

Properties

affected?

optional affected: boolean;

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

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

from-ref?

optional from-ref: string;

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

Git ref to calculate changes exclusively since.

staged?

optional staged: boolean;

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

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

through-ref?

optional through-ref: string;

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

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

Properties

files?

optional files: string[];

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

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

Properties

all?

optional all: boolean;

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

Include all Workspaces.

workspaces?

optional workspaces: string[];

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

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