@kwaeri/generator
Version:
The @kwaeri/generator component module of the @kwaeri/cli user-executable framework.
170 lines • 7.5 kB
JavaScript
/**
* 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
*/
;
// INCLUDES
//import { kdt } from '@kwaeri/developer-tools';
//import * as Events from 'events';
import { Filesystem } from '@kwaeri/filesystem';
import { SERVICE_TYPES } from '@kwaeri/service';
import debug from 'debug';
// DEFINES
/* Configure Debug module support */
const DEBUG = debug('kue:generator');
/* Prepare developer tools */
//const _ = new kdt();
/**
* Derived type for NodeKit Generator Providers
*/
//export type NodeKitGeneratorOptions = NodeKitOptions&FilesystemDescriptor;
/**
* 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 class GeneratorService extends Filesystem {
/**
* @var { ServiceType }
*/
type = SERVICE_TYPES.GENERATOR_SERVICE;
/**
* @var { ( eventName: string | symbol, ...args: any[] ) => boolean }
*/
emit;
/**
* 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) {
super();
if (handler)
this.emit = handler;
}
/**
* The getServiceType method returns the string {@link ServiceType} of the {@link ServiceProvider}
*
* @returns { ServiceType }
*/
get serviceType() {
return this.type;
}
/**
* 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) {
return (data) => emitFunc("ServiceEvent", data);
}
/**
* Method to emit service event metadata for controlling
* progress bar display
*
* @param { ServiceEventBits } data An object of {@link ServiceEventBits}
*/
setServiceEventMetadata(data) {
// Higher-Order Function fix
//this.emit!( 'ServiceEvent', data );
// Allows this change, avoiding if's ofc:
this?.emit?.(data);
}
}
// Here we convert all our named derived classes to identically named interfaces such that we're able
// to apply them as mixins, turning our GeneratorService class into a class that has all the methods
// of Filesystem and Events.EventEmitter available to it:
//export interface GeneratorService extends Filesystem, Events.EventEmitter {};
// We apply our magic here to create the final GeneratorService class:
//_.compose( GeneratorService, [ Filesystem, Events.EventEmitter ] );
/**
* 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 class GeneratorServiceProvider extends GeneratorService {
/**
* 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, serviceEventBits) {
DEBUG(`[${tag}] call 'setServiceEventMetadata' with '${serviceEventBits}`);
this.setServiceEventMetadata(serviceEventBits);
}
}
// example of a generator service provider:
export class ExampleGeneratorServiceProvider extends GeneratorServiceProvider {
getServiceProviderSubscriptions(options) {
return { commands: {}, required: {}, optional: {}, subcommands: {} };
}
getServiceProviderSubscriptionHelpText(options) {
return { helpText: { "command": `To use this service, read this HelpText.` } };
}
async renderService(options) {
this.setServiceEventMetadata({ progressLevel: 50, notice: "Test Notice", log: "Test Log", logType: 1 });
return Promise.resolve((() => console.log('Service should run at this point.')));
}
}
//# sourceMappingURL=generator.mjs.map