@kwaeri/generator
Version:
The @kwaeri/generator component module of the @kwaeri/cli user-executable framework.
159 lines (158 loc) • 7.9 kB
text/typescript
/**
* SPDX-PackageName: kwaeri/generator
* SPDX-PackageVersion: 0.9.0
* SPDX-FileCopyrightText: © 2014 - 2022 Richard Winters <kirvedx@gmail.com> and contributors
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR MIT
*/
import { Filesystem } from '@kwaeri/filesystem';
import { BaseServiceProvider, ServiceProviderSubscriptions, ServiceProviderHelpText, BaseService, ServiceEventBits, ServiceType } from '@kwaeri/service';
/**
* Derived type for NodeKit Generator Providers
*/
/**
* Service Class
*
* The {@link GeneratorService} is the class from which all kue services should inherit
* from.
*
* A service is a resource provided, typically through subsciption to a caller,
* contracted when an end user requisitions the platform, and will [or should]
* always need the Events class, and have at least some standard methods.
*
* This class helps to sensibly build a derived generator service provider, it will
* probably only be used directly in special circumstances, and instead - developers
* would extend from the {@link GeneratorServiceProvider} class.
*/
export declare abstract class GeneratorService extends Filesystem implements BaseService {
/**
* @var { ServiceType }
*/
type: ServiceType;
/**
* @var { ( eventName: string | symbol, ...args: any[] ) => boolean }
*/
protected emit?: (((data: ServiceEventBits) => boolean) | ((data: ServiceEventBits) => void));
/**
* The Service class constructor
* @param { Events.EventEmitter | ( ( data: ServiceEventBits ) => void ) } eventHandler An optional event handler will be composed
* into the instance by the Steward, but can
* be passed in directly by a caller (for
* testing) - and is typed for obvious reasons
*
* **Example**
*
* A {@link ServiceProvider} could choose to leverage an event-based progress bar, and could `.bind()` to the `.emit()` method - the
* instance of the *emitter* it's associated with. The emitter would define a **ServiceEvent** type and leverage the `Progress::
* handler()` to handle those events:
*
* ```typescript
* // Setup
* const emitter = Events.EventEmitter,
* progress = new Progress();
*
* // Define the event, binding progress.handler to it
* emitter.on( "ServiceEvent", progress.handler.bind( progress ) );
*
* // Create the service provider, passing in the event emitter's emit, using a special static wrapper method
* const serviceProvider = new ServiceProvider( ServiceProvider.getEmitWrapper( emitter.emit.bind( emitter ) ) );
*
* // Or, leverage a composition-based alternative approach (similar to the steward)
* const altServiceProvider = new ServiceProvider();
* altServiceProvider.emit = ServiceProvider.getEmitWrapper( emitter.emit.bind( emitter ) );
*
* // Now any call to serviceProvider.updateProgress() is handled
* serviceProvider.updateProgress( "TAG", { progressLevel: 50, notice: "Processing xyz ..." } );
* altServiceProvider.updateProgress( "TAG", { progressLevel: 50, notice: "Processing xyz ..." } );
* ```
*
* The other option a {@link ServiceProvider} could choose is to use the progress module directly, and leverage its `getHandler()`
* convenience method to return a pre-bound handler reference:
*
* ```typescript
* // Setup
* const progress = new Progress(),
* serviceProvider = new ServiceProvider( progress.getHandler() );
*
* // Now any call to serviceProvider.updateProgress() is handled
* ```
*
* There are merits to using an event based progress bar - so the option is supported in this fashion. However, a direct
* route to updating the progress bar was considered - and included - because it does have a more responsive result.
*/
constructor(handler?: ((data: ServiceEventBits) => boolean) | ((data: ServiceEventBits) => void));
/**
* The getServiceType method returns the string {@link ServiceType} of the {@link ServiceProvider}
*
* @returns { ServiceType }
*/
get serviceType(): string;
/**
* Wraps `Events.EventEmitter.emit()` so that the signature matches the required signature for the
* constructor's handler argument
*
* @param { ( eventName: string | symbol, ...args: any[] ) => boolean } emitFunc The `Events.EventEmitter.emit` being wrapped
*
* @returns { ( data: ServiceEventBits ) => void } A wrapped emit to service as a handler for progress bar events
*/
static getEmitWrapper(emitFunc: ((eventName: string | symbol, ...args: any[]) => boolean)): (data: ServiceEventBits) => boolean;
/**
* Renders the primary function of the {@link Service}.
*
* The generics scaffolding help to support advanced extended usage of the Service class. Please see
* the existing ServiceProviders under the kwaeri scope to see how to get around the
* generics requirements when you don't have a need for them.
*
* @param {NodeKitOptions|any} options An options object, typically an extension of {@link NodeKitOptions}
*
* @returns { T } Minimally, an object with a boolean result, and a string type. Empty template provided to allow for type limitation in derived classes..
*/
abstract renderService<T>(options?: any): Promise<T>;
/**
* Method to emit service event metadata for controlling
* progress bar display
*
* @param { ServiceEventBits } data An object of {@link ServiceEventBits}
*/
setServiceEventMetadata(data: ServiceEventBits): void;
}
/**
* GeneratorServiceProvider Class
*
* The {@link GeneratorServiceProvider} class with which all kue service providers should extend from,
* which inherits from the Events and {@link GeneratorService} classes and implements all required
* interfaces for consistency.
*/
export declare abstract class GeneratorServiceProvider extends GeneratorService implements BaseServiceProvider {
/**
* Gets the subscription object for the service provider, used by the
* Steward in order to reconcile user-provided commands with the available contracts
* offered by the currently installed ServiceProviders.
*
* @param { any } options A redundant, future proofing, options argument.
*
* @return { ServiceProviderSubscriptions } A {@link ServiceProviderSubscriptions} object
*/
abstract getServiceProviderSubscriptions(options: any): ServiceProviderSubscriptions;
/**
* Gets help text for the {@link GeneratorServiceProvider}'s contracts/commands.
*
* @param { any} options A redundant, future proofing, options object
*
* @returns { ServiceProviderHelpText } An extension of {@link ServiceProviderHelpText}
*/
abstract getServiceProviderSubscriptionHelpText<T extends ServiceProviderHelpText>(options: any): T;
/**
* Method to simplify emitting progress bar events and debugging
*
* @param tag The tag to note for debugging purposes
* @param serviceEventBits The progress bar event metadata to leverage in setting service event metadata
*
* @returns { void }
*/
updateProgress(tag: String, serviceEventBits: ServiceEventBits): void;
}
export declare class ExampleGeneratorServiceProvider extends GeneratorServiceProvider {
getServiceProviderSubscriptions(options?: any): ServiceProviderSubscriptions;
getServiceProviderSubscriptionHelpText<T extends ServiceProviderHelpText>(options?: any): T;
renderService<T extends any>(options?: any): Promise<T>;
}