@yeoman/types 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 The Yeoman Team <admin@simonboudrias.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@yeoman/types",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Common API for yeoman's generator/environment stack",
+  "keywords": [
+    "yeoman",
+    "types"
+  ],
+  "homepage": "http://yeoman.io/authoring/testing.html",
+  "repository": "yeoman/yeoman-api",
+  "license": "MIT",
+  "author": "The Yeoman Team",
+  "type": "module",
+  "main": "",
+  "types": "./types/index.d.ts",
+  "files": [
+    "types"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "",
+    "clean-all": "rimraf node_modules",
+    "pretest": "xo",
+    "test": ""
+  },
+  "dependencies": {
+    "@types/node": "^16.18.26"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.3",
+    "mem-fs": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@types/inquirer": "^9.0.3",
+    "mem-fs": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "inquirer": {
+      "optional": true
+    },
+    "mem-fs": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^16.13.0 || >=18.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "gitHead": "c1cb1ef2d571bb6b2a1efdaf808e89ab424afb5f"
+}

package/types/environment/adapter.d.ts

@@ -0,0 +1,49 @@
+import type { DistinctQuestion, Answers as InquirerAnswers } from 'inquirer';
+import type { Logger } from './logger.js';
+
+/**
+ * Represents an answer-hash.
+ */
+export type PromptAnswers = InquirerAnswers;
+
+export type PromptQuestion<A extends PromptAnswers = PromptAnswers> = DistinctQuestion<A>;
+
+/**
+ * Provides a set of questions.
+ */
+export type PromptQuestions<A extends PromptAnswers = PromptAnswers> = PromptQuestion<A> | Array<PromptQuestion<A>>; // | Observable<Question<A>>;
+
+/**
+ * Abstraction layer that defines the I/O interactions.
+ *
+ * It provides a CLI interaction
+ */
+export type InputOutputAdapter = {
+  /**
+   * A component for logging messages.
+   */
+  log: Logger;
+
+  /**
+   * Prompts the user for one or more questions.
+   *
+   * @param questions The questions to prompt.
+   * @param initialAnswers Initial answers.
+   */
+  prompt<A extends PromptAnswers = PromptAnswers>(questions: PromptQuestions<A>, initialAnswers?: Partial<A>): Promise<A>;
+
+  /**
+   * Close underline inputs.
+   */
+  close(): void;
+
+  /**
+   * Shows a color-based diff of two strings.
+   *
+   * @param actual The actual text.
+   * @param expected The expected text.
+   * @param changes The changes returned by `diff`.
+   * @returns The formatted message.
+   */
+  diff(actual: string, expected: string, changes: unknown[]): string;
+};

package/types/environment/environment.d.ts

@@ -0,0 +1,103 @@
+import type { Transform } from 'node:stream';
+import type { Store } from 'mem-fs';
+
+import type { GeneratorBaseOptions } from '../generator/generator-options.js';
+import type { BaseGenerator } from '../generator/generator.js';
+import type { GetGeneratorConstructor, GetGeneratorOptions } from '../generator/utils.js';
+import type { InputOutputAdapter } from './adapter.js';
+
+export type EnvironmentConstructor<A extends InputOutputAdapter = InputOutputAdapter> = new (
+  options?: BaseEnvironmentOptions,
+  adapter?: A,
+) => BaseEnvironment<A>;
+
+export type BaseEnvironmentOptions = GeneratorBaseOptions & {
+  /**
+   * The working-directory of the environment.
+   */
+  cwd?: string | undefined;
+
+  /**
+   * A value indicating whether the experimental features should be enabled.
+   */
+  experimental?: boolean;
+
+  /**
+   * Options to pass to every generator instantiated by this Environment.
+   */
+  sharedOptions?: GeneratorBaseOptions;
+
+  /**
+   * `mem-fs` Store.
+   */
+  sharedFs?: Store;
+};
+
+export type BaseEnvironment<A = InputOutputAdapter, S extends Store = Store> = {
+  cwd: string;
+  adapter: A;
+  sharedFs: S;
+
+  emit(eventName: string | symbol, ...args: any[]): boolean;
+
+  applyTransforms(transformStreams: Transform[], stream?: NodeJS.ReadableStream): Promise<void>;
+
+  create<G extends BaseGenerator = BaseGenerator>(
+    namespaceOrPath: string | GetGeneratorConstructor<G>,
+    args: string[],
+    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'resolvec'>>,
+  ): Promise<G>;
+
+  instantiate<G extends BaseGenerator = BaseGenerator>(
+    generator: GetGeneratorConstructor<G>,
+    args: string[],
+    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'resolvec'>>,
+  ): Promise<G>;
+
+  /**
+   * Converts the specified `filePath` to a namespace.
+   *
+   * @param filePath The path to convert.
+   * @param lookups The path-part to exclude (such as `lib/generators`).
+   */
+  namespace(filePath: string, lookups?: string[]): string;
+
+  /**
+   * Gets the version of this `Environment` object.
+   */
+  getVersion(): string;
+
+  /**
+   * Gets the version of the specified `dependency`.
+   *
+   * @param dependency The name of the dependency.
+   */
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  getVersion(dependency: string): string;
+
+  queueGenerator<G extends BaseGenerator = BaseGenerator>(generator: G, schedule?: boolean): Promise<G>;
+
+  rootGenerator<G extends BaseGenerator = BaseGenerator>(): G;
+
+  runGenerator(generator: BaseGenerator): Promise<void>;
+
+  /**
+   * Registers a specific `generator` to this environment.
+   * This generator is stored under the provided `namespace` or, if not specified, a default namespace format.
+   *
+   * @param filePath The filepath to the generator or an npm package name.
+   * @param namespace The namespace under which the generator should be registered.
+   * @param packagePath The path to the npm package of the generator.
+   */
+  register(filePath: string, namespace?: string, packagePath?: string): Promise<void>;
+
+  /**
+   * Registers a stubbed generator to this environment.
+   *
+   * @param generator The generator constructor.
+   * @param namespace The namespace under which the generator should be registered.
+   * @param resolved The file-path to the generator.
+   * @param packagePath The path to the npm package of the generator.
+   */
+  registerStub(generator: GetGeneratorConstructor, namespace: string, resolved?: string, packagePath?: string): void;
+};

package/types/environment/logger.d.ts

@@ -0,0 +1,53 @@
+import type { format } from 'node:util';
+
+/**
+ * Provides default color-categories.
+ */
+export type DefaultLoggerCategories = 'skip' | 'force' | 'create' | 'invoke' | 'conflict' | 'identical' | 'info';
+
+/**
+ * Provides the functionality to log messages.
+ */
+export type Logger<LoggerCategories extends string | number | symbol = DefaultLoggerCategories> = {
+  /**
+   * Logs a message of the specified category.
+   */
+  [P in LoggerCategories]: (...args: Parameters<typeof format>) => Logger<LoggerCategories>;
+} & {
+  /**
+   * Writes a log-message.
+   *
+   * @param format
+   * The format of the log-messages.
+   * See <https://github.com/mikeal/logref> for more info.
+   *
+   * @param params
+   * The parameters to replace variables with.
+   */
+  (format?: string, parameters?: Record<string, any>): Logger<LoggerCategories>;
+
+  /**
+   * Writes a log-message.
+   */
+  (message?: any, ...optionalParameters: any[]): Logger<LoggerCategories>;
+
+  /**
+   * Writes a log-message.
+   */
+  write(...args: Parameters<typeof format>): Logger<LoggerCategories>;
+
+  /**
+   * Writes a log-message with an appended newline character.
+   */
+  writeln(...args: Parameters<typeof format>): Logger<LoggerCategories>;
+
+  /**
+   * Writes a success status with a check mark `✔`.
+   */
+  ok(...args: Parameters<typeof format>): Logger<LoggerCategories>;
+
+  /**
+   * Writes an error-message with a prepended cross mark.
+   */
+  error(...args: Parameters<typeof format>): Logger<LoggerCategories>;
+};

package/types/generator/generator-features.d.ts

@@ -0,0 +1,6 @@
+export type GeneratorCustomFeatures = Record<string, unknown>;
+
+export type GeneratorFeatures = {
+  uniqueBy?: string;
+  uniqueGlobally?: boolean;
+};

package/types/generator/generator-options.d.ts

@@ -0,0 +1,66 @@
+import type { BaseEnvironment } from '../environment/environment.js';
+
+export type GeneratorCustomOptions = Record<string, unknown>;
+
+export type GeneratorBaseOptions = {
+  /**
+   * Skip package manager install task.
+   */
+  skipInstall?: boolean;
+
+  /**
+   * Fail on package manager install task failure.
+   */
+  forceInstall?: boolean;
+
+  /**
+   * Skip working dir cacheable prompts cache.
+   */
+  skipCache?: boolean;
+
+  /**
+   * Skip working dir cacheable prompts cache.
+   */
+  skipLocalCache?: boolean;
+
+  /**
+   * Skip options parsing.
+   * Options is already parsed.
+   */
+  skipParseOptions?: boolean;
+
+  /**
+   * Store global storage at working dir.
+   */
+  localConfigOnly?: boolean;
+
+  /**
+   * Show prompts for already answered questions.
+   */
+  askAnswered?: boolean;
+};
+
+type GeneratorNamespace = {
+  namespace: string;
+};
+
+type GeneratorEnvironmentOptions = {
+  help?: boolean;
+
+  /** Environment being to run */
+  env: BaseEnvironment;
+
+  /** The path to the current generator */
+  resolved: string;
+};
+
+type GeneratorHelpOptions<H extends boolean | undefined> = {
+  help: H;
+};
+
+export type GeneratorOptions = GeneratorBaseOptions &
+  GeneratorNamespace &
+  (
+    | (GeneratorHelpOptions<false | undefined> & GeneratorEnvironmentOptions)
+    | (GeneratorHelpOptions<true> & Partial<GeneratorEnvironmentOptions>)
+  );

package/types/generator/generator.d.ts

@@ -0,0 +1,25 @@
+import type { BaseEnvironment } from '../environment/environment.js';
+import type { GeneratorCustomFeatures, GeneratorFeatures } from './generator-features.js';
+import type { GeneratorCustomOptions, GeneratorOptions } from './generator-options.js';
+
+export type EnvironmentGenerator = {
+  readonly env: BaseEnvironment;
+  readonly features: unknown;
+
+  _postConstruct?(): Promise<void>;
+
+  destinationRoot(): string;
+
+  // Generator >= v5
+  queueTasks?(): Promise<void>;
+};
+
+export type BaseGenerator<
+  O extends GeneratorOptions = GeneratorOptions,
+  F extends GeneratorFeatures = GeneratorFeatures,
+> = EnvironmentGenerator & {
+  readonly options: O;
+
+  // Generator >= v5
+  readonly features: F | undefined;
+};

package/types/generator/utils.d.ts

@@ -0,0 +1,9 @@
+import type { BaseGenerator } from './generator.js';
+
+export type GetGeneratorOptions<T extends BaseGenerator = BaseGenerator> = T extends BaseGenerator<infer Options> ? Options : never;
+
+export type GetGeneratorFeatures<T extends BaseGenerator = BaseGenerator> = T extends BaseGenerator<any, infer features> ? features : never;
+
+export type GetGeneratorConstructor<T extends BaseGenerator = BaseGenerator> =
+  | (new (args: string[], options: GetGeneratorOptions<T>, features: GetGeneratorFeatures<T>) => BaseGenerator)
+  | (new (options: GetGeneratorOptions<T>, features: GetGeneratorFeatures<T>) => BaseGenerator);

package/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from './environment/adapter.js';
+export * from './environment/environment.js';
+export * from './environment/logger.js';
+
+export * from './generator/generator-features.js';
+export * from './generator/generator-options.js';
+export * from './generator/generator.js';
+export * from './generator/utils.js';