@yeoman/types 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeoman/types",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Common API for yeoman's generator/environment stack",
   "keywords": [
@@ -15,7 +15,8 @@
   "main": "",
   "types": "./types/index.d.ts",
   "files": [
-    "types"
+    "types",
+    "!**/*.test.ts"
   ],
   "scripts": {
     "build": "tsc",
@@ -55,5 +56,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "1982816cfe6af4e92f999e344cf9b8539ff308eb"
+  "gitHead": "fddebd6424725b9636af96a643a25f00f7314a77"
 }

package/types/environment/environment.d.ts

@@ -2,17 +2,18 @@ import type { Transform } from 'node:stream';
 import type { Store } from 'mem-fs';
 import type { MemFsEditorFile } from 'mem-fs-editor';
 
-import type { GeneratorBaseOptions } from '../generator/generator-options.js';
-import type { BaseGenerator } from '../generator/generator.js';
+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 { InputOutputAdapter } from './adapter.js';
+import type { GeneratorMeta, LookupGeneratorMeta, LookupOptions, BaseGeneratorMeta } from './methods-options.js';
 
 export type EnvironmentConstructor<A extends InputOutputAdapter = InputOutputAdapter> = new (
   options?: BaseEnvironmentOptions,
   adapter?: A,
 ) => BaseEnvironment<A>;
 
-export type BaseEnvironmentOptions = GeneratorBaseOptions & {
+export type BaseEnvironmentOptions = BaseGeneratorOptions & {
   /**
    * The working-directory of the environment.
    */
@@ -26,7 +27,7 @@ export type BaseEnvironmentOptions = GeneratorBaseOptions & {
   /**
    * Options to pass to every generator instantiated by this Environment.
    */
-  sharedOptions?: GeneratorBaseOptions;
+  sharedOptions?: BaseGeneratorOptions;
 
   /**
    * `mem-fs` Store.
@@ -41,7 +42,7 @@ export type ApplyTransformsOptions = {
   streamOptions: Parameters<Store<MemFsEditorFile>['stream']>[0];
 };
 
-export type BaseEnvironment<A = InputOutputAdapter, S extends Store = Store> = {
+export type BaseEnvironment<A = InputOutputAdapter, S extends Store<MemFsEditorFile> = Store<MemFsEditorFile>> = {
   cwd: string;
   adapter: A;
   sharedFs: S;
@@ -50,16 +51,28 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store = Store> = {
 
   applyTransforms(transformStreams: Transform[], options?: ApplyTransformsOptions): Promise<void>;
 
+  /**
+   * Gets a single constructor of a generator from the registered list of generators.
+   *
+   * The lookup is based on generator's namespace, "walking up" the namespaces until a matching is found.
+   * Eg. if an `angular:common` namespace is registered, and we try to get `angular:common:all`,
+   * then we get `angular:common` as a fallback (unless an `angular:common:all` generator is registered).
+   *
+   * @param namespaceOrPath The namespace of the generator or the path to a generator.
+   * @returns The constructor of the generator registered under the namespace.
+   */
+  get<C extends BaseGeneratorConstructor = BaseGeneratorConstructor>(namespaceOrPath: string): Promise<C | undefined>;
+
   create<G extends BaseGenerator = BaseGenerator>(
     namespaceOrPath: string | GetGeneratorConstructor<G>,
     args: string[],
-    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'resolvec'>>,
+    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'namespace'>>,
   ): Promise<G>;
 
   instantiate<G extends BaseGenerator = BaseGenerator>(
     generator: GetGeneratorConstructor<G>,
     args: string[],
-    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'resolvec'>>,
+    options?: Partial<Omit<GetGeneratorOptions<G>, 'env' | 'resolved' | 'namespace'>>,
   ): Promise<G>;
 
   /**
@@ -70,6 +83,30 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store = Store> = {
    */
   namespace(filePath: string, lookups?: string[]): string;
 
+  /**
+   * Creates an alias.
+   *
+   * Alias allows the `get()` and `lookup()` methods to search in alternate filepath for a given namespaces.
+   * It's used for example to map `generator-*` npm package to their namespace equivalent (without the generator- prefix),
+   * or to default a single namespace like `angular` to `angular:app` or `angular:all`.
+   *
+   * If multiple aliases are defined, then the replacement is recursive, replacing each alias in reverse order.
+   *
+   * An alias can be a single String or a Regular Expression.
+   * The finding is done based on .match().
+   *
+   * @param match The name to match.
+   * @param value The replacement for the specified `match`.
+   *
+   * @example
+   * env.alias(/^([a-zA-Z0-9:\*]+)$/, 'generator-$1');
+   * env.alias(/^([^:]+)$/, '$1:app');
+   * env.alias(/^([^:]+)$/, '$1:all');
+   * env.alias('foo');
+   * // => generator-foo:all
+   */
+  alias(match: string | RegExp, value: string): void;
+
   /**
    * Gets the version of this `Environment` object.
    */
@@ -94,20 +131,17 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store = Store> = {
    * 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.
+   * @param meta Generator metadata.
    */
-  register(filePath: string, namespace?: string, packagePath?: string): Promise<void>;
+  register(filePath: string, meta?: Partial<BaseGeneratorMeta>): 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.
+   * @param meta Generator metadata.
    */
-  registerStub(generator: GetGeneratorConstructor, namespace: string, resolved?: string, packagePath?: string): void;
+  register(generator: unknown, meta: BaseGeneratorMeta): void;
 
   /**
    * Queue tasks
@@ -123,4 +157,39 @@ export type BaseEnvironment<A = InputOutputAdapter, S extends Store = Store> = {
    * @param before
    */
   addPriority(priority: string, before?: string): void;
+
+  /**
+   * Searches for generators and their sub-generators.
+   *
+   * A generator is a `:lookup/:name/index.js` file placed inside an npm package.
+   *
+   * Default lookups are:
+   *   - `./`
+   *   - `./generators/`
+   *   - `./lib/generators/`
+   *
+   * So the index file `node_modules/generator-dummy/lib/generators/yo/index.js` would be registered as `dummy:yo` generator.
+   *
+   * @param options The options for the lookup.
+   * @returns A list of generators.
+   */
+  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;
 };

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

@@ -0,0 +1,86 @@
+import { type BaseGenerator, type GetGeneratorConstructor } from '../index.js';
+
+/**
+ * Provides options for the `lookup` method.
+ */
+export type LookupOptions = {
+  /**
+   * The paths to look for generators.
+   */
+  packagePaths?: string[];
+
+  /**
+   * The repüository paths to look for generator packages.
+   */
+  npmPaths?: string[];
+
+  /**
+   * The file-patterns to look for.
+   */
+  filePatterns?: string[];
+
+  /**
+   * The package patterns to look for.
+   */
+  packagePatterns?: string[];
+
+  /**
+   * A value indicating whether the lookup should be stopped after finding the first result.
+   */
+  singleResult?: boolean;
+
+  /**
+   * The `deep` option to pass to `globby`.
+   */
+  globbyDeep?: number;
+  /**
+   * A value indicating whether globally installed packages should be ignored.
+   */
+  localOnly?: boolean;
+};
+
+/**
+ * Provides 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;
+
+  /**
+   * The namespace of the generator.
+   */
+  namespace: string;
+
+  /**
+   * The path to the package containing the generator.
+   */
+  packagePath: string;
+};
+
+export type BaseGeneratorMeta = {
+  /** The key under which the generator can be retrieved */
+  namespace: string;
+  /** The file path to the generator (used only if generator is a module) */
+  resolved?: string;
+  /** PackagePath to the generator npm package */
+  packagePath?: string;
+};
+
+export type GeneratorMeta = BaseGeneratorMeta & {
+  packageNamespace?: string;
+  /** Import and find the Generator Class */
+  importGenerator: () => Promise<GetGeneratorConstructor>;
+  /** 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>;
+  /** Intantiate the Generator passing help option */
+  instantiateHelp: <G extends BaseGenerator = BaseGenerator>() => Promise<G>;
+};

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

@@ -2,7 +2,7 @@ import type { BaseEnvironment } from '../environment/environment.js';
 
 export type GeneratorCustomOptions = Record<string, unknown>;
 
-export type GeneratorBaseOptions = {
+export type BaseGeneratorOptions = {
   /**
    * Skip package manager install task.
    */
@@ -58,7 +58,7 @@ type GeneratorHelpOptions<H extends boolean | undefined> = {
   help: H;
 };
 
-export type GeneratorOptions = GeneratorBaseOptions &
+export type GeneratorOptions = BaseGeneratorOptions &
   GeneratorNamespace &
   (
     | (GeneratorHelpOptions<false | undefined> & GeneratorEnvironmentOptions)

package/types/generator/generator.d.ts

@@ -23,3 +23,7 @@ export type BaseGenerator<
   // Generator >= v5
   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>);

package/types/generator/utils.d.ts

@@ -1,9 +1,10 @@
-import type { BaseGenerator } from './generator.js';
+import type { BaseGenerator, BaseGeneratorConstructor } 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>) => T)
-  | (new (options: GetGeneratorOptions<T>, features: GetGeneratorFeatures<T>) => T);
+export type GetGeneratorConstructor<T extends BaseGenerator = BaseGenerator> = BaseGeneratorConstructor<
+  GetGeneratorOptions<T>,
+  GetGeneratorFeatures<T>
+>;

package/types/index.d.ts

@@ -1,6 +1,7 @@
 export * from './environment/adapter.js';
 export * from './environment/environment.js';
 export * from './environment/logger.js';
+export * from './environment/methods-options.js';
 
 export * from './generator/generator-features.js';
 export * from './generator/generator-options.js';