@yeoman/types 0.4.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeoman/types",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "private": false,
   "description": "Common API for yeoman's generator/environment stack",
   "keywords": [
@@ -56,5 +56,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "fddebd6424725b9636af96a643a25f00f7314a77"
+  "gitHead": "cb5b453d1e92fcc70874d4cdaea77cf90fdd60f7"
 }

package/types/environment/environment.d.ts

@@ -1,12 +1,19 @@
-import type { Transform } from 'node:stream';
+import type { PipelineSource, Transform } from 'node:stream';
 import type { Store } from 'mem-fs';
 import type { MemFsEditorFile } from 'mem-fs-editor';
 
 import type { BaseGeneratorOptions } from '../generator/generator-options.js';
 import type { BaseGenerator, BaseGeneratorConstructor } from '../generator/generator.js';
-import type { GetGeneratorConstructor, GetGeneratorOptions } from '../generator/utils.js';
+import type { GetGeneratorConstructor } from '../generator/utils.js';
 import type { InputOutputAdapter } from './adapter.js';
-import type { GeneratorMeta, LookupGeneratorMeta, LookupOptions, BaseGeneratorMeta } from './methods-options.js';
+import type {
+  GeneratorMeta,
+  LookupGeneratorMeta,
+  LookupOptions,
+  BaseGeneratorMeta,
+  InstantiateOptions,
+  ComposeOptions,
+} from './methods-options.js';
 
 export type EnvironmentConstructor<A extends InputOutputAdapter = InputOutputAdapter> = new (
   options?: BaseEnvironmentOptions,
@@ -38,16 +45,21 @@ export type BaseEnvironmentOptions = BaseGeneratorOptions & {
 export type ApplyTransformsOptions = {
   name?: string;
   log?: boolean;
-  stream?: ReturnType<Store<MemFsEditorFile>['stream']>;
-  streamOptions: Parameters<Store<MemFsEditorFile>['stream']>[0];
+  stream?: PipelineSource<any>;
+  streamOptions?: Parameters<Store<MemFsEditorFile>['stream']>[0];
 };
 
+/**
+ * BaseEnvironment provides the api used by yeoman-test and yeoman-generator that should remain stable between major yeoman-environment versions.
+ */
 export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorFile> = Store<MemFsEditorFile>> = {
   cwd: string;
   adapter: A;
   sharedFs: S;
 
   emit(eventName: string | symbol, ...args: any[]): boolean;
+  on(eventName: string | symbol, listener: (...args: any[]) => void): unknown;
+  once(eventName: string | symbol, listener: (...args: any[]) => void): unknown;
 
   applyTransforms(transformStreams: Transform[], options?: ApplyTransformsOptions): Promise<void>;
 
@@ -65,14 +77,17 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorF
 
   create<G extends BaseGenerator = BaseGenerator>(
     namespaceOrPath: string | GetGeneratorConstructor<G>,
-    args: string[],
-    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'namespace'>>,
+    instantiateOptions: InstantiateOptions<G>,
   ): Promise<G>;
 
   instantiate<G extends BaseGenerator = BaseGenerator>(
     generator: GetGeneratorConstructor<G>,
-    args: string[],
-    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'namespace'>>,
+    instantiateOptions: InstantiateOptions<G>,
+  ): Promise<G>;
+
+  composeWith<G extends BaseGenerator = BaseGenerator>(
+    generator: string | GetGeneratorConstructor<G>,
+    composeOptions?: ComposeOptions<G>,
   ): Promise<G>;
 
   /**
@@ -117,10 +132,9 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorF
    *
    * @param dependency The name of the dependency.
    */
-  // eslint-disable-next-line @typescript-eslint/unified-signatures
-  getVersion(dependency: string): string;
+  getVersion(dependency: string): string | undefined;
 
-  queueGenerator<G extends BaseGenerator = BaseGenerator>(generator: G, schedule?: boolean): Promise<G>;
+  queueGenerator<G extends BaseGenerator = BaseGenerator>(generator: G, queueOptions?: { schedule?: boolean }): Promise<G>;
 
   rootGenerator<G extends BaseGenerator = BaseGenerator>(): G;
 
@@ -133,7 +147,7 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorF
    * @param filePath The filepath to the generator or an npm package name.
    * @param meta Generator metadata.
    */
-  register(filePath: string, meta?: Partial<BaseGeneratorMeta>): void;
+  register(filePath: string, meta?: Partial<BaseGeneratorMeta>): GeneratorMeta;
 
   /**
    * Registers a stubbed generator to this environment.
@@ -141,7 +155,7 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorF
    * @param generator The generator constructor.
    * @param meta Generator metadata.
    */
-  register(generator: unknown, meta: BaseGeneratorMeta): void;
+  register(generator: unknown, meta: BaseGeneratorMeta): GeneratorMeta;
 
   /**
    * Queue tasks
@@ -175,21 +189,8 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorF
    */
   lookup(options?: LookupOptions): Promise<LookupGeneratorMeta[]>;
 
-  /**
-   * Checks whether a package with the specified `packageNamespace` has been registered.
-   *
-   * @param packageNamespace The package-namespace to check.
-   * @returns A value indicating whether a package with the specified `packageNamespace` has been registered.
-   */
-  isPackageRegistered(packageNamespace?: string): boolean;
-
-  /**
-   * Gets the namespaces of all registered packages.
-   */
-  getRegisteredPackages(): string[];
-
   /**
    * Returns stored generators meta
    */
-  getGeneratorMeta(namespace: string): GeneratorMeta;
+  getGeneratorMeta(namespace: string): GeneratorMeta | undefined;
 };

package/types/environment/methods-options.d.ts

@@ -1,4 +1,4 @@
-import { type BaseGenerator, type GetGeneratorConstructor } from '../index.js';
+import type { GetGeneratorOptions, BaseGenerator, GetGeneratorConstructor } from '../index.js';
 
 /**
  * Provides options for the `lookup` method.
@@ -40,30 +40,21 @@ export type LookupOptions = {
 };
 
 /**
- * Provides information about a generator.
+ * Provides lookup information about a generator.
  */
-export type LookupGeneratorMeta = {
-  /**
-   * A value indicating whether the generator could be registered.
-   */
-  registered: boolean;
-
-  /**
-   * The resolved path to the generator.
-   */
-  generatorPath: string;
+export type LookupGeneratorMeta = NotRegisteredLookupGeneratorMeta | RegisteredLookupGeneratorMeta;
 
-  /**
-   * The namespace of the generator.
-   */
-  namespace: string;
-
-  /**
-   * The path to the package containing the generator.
-   */
-  packagePath: string;
+export type NotRegisteredLookupGeneratorMeta = Required<BaseGeneratorMeta> & {
+  /** Failed to register. */
+  registered: false;
 };
 
+export type RegisteredLookupGeneratorMeta = Required<BaseGeneratorMeta> &
+  GeneratorMeta & {
+    /** Successfully registered package. */
+    registered: true;
+  };
+
 export type BaseGeneratorMeta = {
   /** The key under which the generator can be retrieved */
   namespace: string;
@@ -80,7 +71,14 @@ export type GeneratorMeta = BaseGeneratorMeta & {
   /** Import the module `import(meta.resolved)` */
   importModule?: () => Promise<unknown>;
   /** Intantiate the Generator `env.instantiate(await meta.importGenerator())` */
-  instantiate: <G extends BaseGenerator = BaseGenerator>(args?: string[], options?: any) => Promise<G>;
+  instantiate: (args?: string[], options?: any) => Promise<BaseGenerator>;
   /** Intantiate the Generator passing help option */
-  instantiateHelp: <G extends BaseGenerator = BaseGenerator>() => Promise<G>;
+  instantiateHelp: () => Promise<BaseGenerator>;
 };
+
+export type InstantiateOptions<G extends BaseGenerator = BaseGenerator> = {
+  generatorArgs?: string[];
+  generatorOptions?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'namespace'>> | undefined;
+};
+
+export type ComposeOptions<G extends BaseGenerator = BaseGenerator> = InstantiateOptions<G> & { schedule?: boolean };

package/types/generator/generator.d.ts

@@ -6,6 +6,10 @@ export type EnvironmentGenerator = {
   readonly env: BaseEnvironment;
   readonly features: unknown;
 
+  emit(eventName: string | symbol, ...args: any[]): boolean;
+  on(eventName: string | symbol, listener: (...args: any[]) => void): unknown;
+  once(eventName: string | symbol, listener: (...args: any[]) => void): unknown;
+
   _postConstruct?(): Promise<void>;
 
   destinationRoot(): string;
@@ -24,6 +28,7 @@ export type BaseGenerator<
   readonly features: F | undefined;
 };
 
-export type BaseGeneratorConstructor<O extends GeneratorOptions = GeneratorOptions, F extends GeneratorFeatures = GeneratorFeatures> =
-  | (new (args?: string[], options?: O, features?: F) => BaseGenerator<O, F>)
-  | (new (options?: O, features?: F) => BaseGenerator<O, F>);
+export type BaseGeneratorConstructor<
+  O extends GeneratorOptions = GeneratorOptions,
+  F extends GeneratorFeatures = GeneratorFeatures,
+> = (new (args?: string[], options?: O, features?: F) => BaseGenerator<O, F>) & (new (options?: O, features?: F) => BaseGenerator<O, F>);