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;

Source: 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;

Source: 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.

Source: modules/builders/src/getters.ts

Builders

withAffected()

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>
Source: modules/builders/src/with-affected.ts

withAllInputs()

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>
Source: modules/builders/src/with-all-inputs.ts

withFiles()

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>
Source: modules/builders/src/with-files.ts

withWorkspaces()

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>
Source: 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.

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

Source: 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.

Source: 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.

Source: modules/builders/src/with-workspaces.ts

Getters

getAffected()

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[]>
Source: modules/builders/src/getters.ts

getFilepaths()

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

Source: modules/builders/src/getters.ts

getWorkspaces()

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[]>
Source: modules/builders/src/getters.ts

Argv

type Argv: WithAllInputs;

Source: 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

Source: modules/builders/src/getters.ts