yeoman-generator/dist/types.d.ts

Rails-inspired generator system that provides scaffolding for your apps

import type {
  BaseGenerator,
  ComposeOptions as EnvironmentComposeOptions,
  GeneratorFeatures as FeaturesApi,
  GeneratorOptions as OptionsApi,
  ProgressOptions,
} from '@yeoman/types';
import type { PipelineOptions } from 'mem-fs';
import type { MemFsEditorFile } from 'mem-fs-editor';
import type { JsonValue, Merge } from 'type-fest';
import type Storage from './util/storage.js';
import type Generator from './index.js';

export type StorageValue = JsonValue;
export type GeneratorPipelineOptions = PipelineOptions<MemFsEditorFile> & ProgressOptions & { pendingFiles?: boolean };

export type StorageTransform<A extends Record<string, any>> = (content: A, name?: string) => A;

/**
 * Queue options.
 */
type QueueOptions = {
  /** Name of the queue. */
  queueName?: string;

  /** Execute only once by namespace and taskName. */
  once?: boolean;

  /** Run the queue if not running yet. */
  run?: boolean;

  /** Edit a priority */
  edit?: boolean;

  /** Queued manually only */
  skip?: boolean;

  /** Arguments to pass to tasks */
  args?: any[] | ((generator: Generator) => any[]);
};

/**
 * Task options.
 */
export type TaskOptions = QueueOptions & {
  /** Reject callback. */
  reject?: (error: unknown) => void;

  taskPrefix?: string;

  auto?: boolean;

  taskOrigin?: any;

  cancellable?: boolean;
};

/**
 * Priority object.
 */
export type Priority = QueueOptions & {
  /** Name of the priority. */
  priorityName: string;
  /** The queue which this priority should be added before. */
  before?: string;
};

/**
 * Complete Task object.
 */
export type Task<TaskContext = any> = TaskOptions & {
  /** Function to be queued. */

  method: (this: TaskContext, ...args: any[]) => unknown | Promise<unknown>;

  /** Name of the task. */
  taskName: string;
};

// Use Merge to override local features by official features from @yeoman/types when they are available.
export type BaseFeatures = Merge<
  {
    /** UniqueBy calculation method */
    unique?: true | 'argument' | 'namespace';

    /** Only queue methods that matches a priority. */
    tasksMatchingPriority?: boolean;

    /** Tasks methods starts with prefix. Allows api methods (non tasks) without prefix. */
    taskPrefix?: string;

    // Provided by @yeoman/types since v1.11.0
    /** Provides a custom install task. Environment built-in task will not be executed */
    customInstallTask?: boolean | ((...args: any[]) => void | Promise<void>);

    // Provided by @yeoman/types since v1.11.0
    /** Provides a custom commit task. */
    customCommitTask?: boolean | ((...args: any[]) => void | Promise<void>);

    /** Disable args/options parsing. Whenever options/arguments are provided parsed like using commander based parsing. */
    skipParseOptions?: boolean;

    /** Disable args/options support. Whenever options/arguments are provided parsed like using commander based parsing. */
    disableInGeneratorOptionsSupport?: boolean;

    /** Custom priorities for more fine tuned workflows. */
    customPriorities?: Priority[];

    /** Inherit tasks from parent prototypes, implies tasksMatchingPriority */
    inheritTasks?: boolean;

    /** Transform the configuration before reading. */
    configTransform?: StorageTransform<Record<string, any>>;

    /**
     * Allow `templatePath()` to resolve paths outside the source root.
     * By default a resulting path that is not inside the source root throws.
     * Can be overridden per call using the `allowOutsideRoot` option.
     */
    allowTemplatesOutsideRoot?: boolean;

    /**
     * Allow `templatePath()` to resolve paths anywhere inside the generator package.
     * The package root is the `packagePath` from the generator meta provided by the environment.
     * When the meta has no `packagePath`, the feature is ignored and only the source root is allowed.
     * Useful to share templates between generators of the same package.
     * Can be overridden per call using the `allowOutsideRoot` option.
     */
    allowPackageTemplates?: boolean;

    /**
     * Allow `destinationPath()` to resolve paths outside the destination root.
     * By default a resulting path that is not inside the destination root throws.
     * Can be overridden per call using the `allowOutsideRoot` option.
     */
    allowDestinationOutsideRoot?: boolean;

    /**
     * Do not provide lodash as the `_` property of the generator: reading it throws. lodash, which the property loads at
     * its first use, is then never loaded by the generator.
     */
    disableLodashProperty?: boolean;

    /**
     * The context (`this`) of the templates of `renderTemplate`, `renderTemplateAsync`, `renderTemplates` and
     * `renderTemplatesAsync`:
     * - `'generator'` (default): the generator, without a warning.
     * - `'warn'`: the generator, with a warning once by template and property read from `this`.
     * - `'throw'`: no context, a template reads only its data, and reading a property of `this` throws, naming the
     *   template. It will be the default in the next major.
     * - `'none'`: no context is passed, EJS gives the template its default `this`.
     *
     * A `context` passed in `transformOptions` is still used. Templates rendered with `this.fs.copyTpl` directly are not
     * affected.
     *
     * EJS keeps the context with the compiled template: with the EJS cache, a template rendered by several generators
     * has an unpredictable context, which `'throw'` and `'none'` avoid.
     */
    templateContext?: 'warn' | 'throw' | 'none' | 'generator';
  },
  FeaturesApi
>;

export type PathOptions = {
  /**
   * Allow the resulting path to be outside the root, overriding the `allowTemplatesOutsideRoot`/`allowPackageTemplates`/`allowDestinationOutsideRoot` feature.
   */
  allowOutsideRoot?: boolean;
};

export type BaseOptions = OptionsApi & {
  destinationRoot?: string;

  skipInstall?: boolean;

  skipCheckEnv?: boolean;

  ignoreVersionCheck?: boolean;

  askAnswered?: boolean;

  localConfigOnly?: boolean;

  /** Do not use the global config storage (`~/.yo-rc-global.json`), the local config is used in its place. */
  skipGlobalConfig?: boolean;

  skipCache?: boolean;

  skipLocalCache?: boolean;

  description?: string;

  /**
   * The namespace the generator was created for, complete with its version, instance id, methods and flags
   * (`namespace@semver@#id+method?`), passed by the environment. `namespace` stays the one of the generator, without
   * them.
   */
  namespaceId?: string;
};

export type ArgumentSpec = {
  name: string;

  /** Description for the argument. */
  description?: string;

  /** A value indicating whether the argument is required. */
  required?: boolean;

  /** A value indicating whether the argument is optional. */
  optional?: boolean;

  /** The type of the argument. */
  type: typeof String | typeof Number | typeof Array | typeof Object;

  /** The default value of the argument. */
  default?: any;
};

export type CliOptionSpec = {
  name: string;

  /** The type of the option. */
  type: typeof Boolean | typeof String | typeof Number | ((opt: string) => any);

  required?: boolean;

  /** The option name alias (example `-h` and --help`). */
  alias?: string;

  /** The default value. */
  default?: any;

  /** The description for the option. */
  description?: string;

  /** A value indicating whether the option should be hidden from the help output. */
  hide?: boolean;

  /** The storage to persist the option */
  storage?: string | Storage<any>;
};

export type ComposeOptions<G extends BaseGenerator = BaseGenerator> = EnvironmentComposeOptions<G> & {
  skipEnvRegister?: boolean;
  forceResolve?: boolean;
  forwardOptions?: boolean;
};