@kwaeri/xfmr
Version:
The @kwaeri/xfmr component module of the @kwaeri application framework.
195 lines (194 loc) • 8.72 kB
text/typescript
/*******************************************************************************
* @module kwaeri/xfmr
* @version 0.4.0
* @license
* Copyright © 2014 - 2022 Richard Winters <kirvedx@gmail.com> and contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
******************************************************************************/
import { ServiceProviderSubscriptions, ServiceProviderHelpText, ServiceProvider, ServiceEventBits } from '@kwaeri/service';
import { NodeKitOptions } from '@kwaeri/standards-types';
import { Configuration } from '@kwaeri/configuration';
import { Path, GlobOptions } from "glob";
export type XfmConfKeyBits = {
version?: string;
copyright?: string;
};
export type XfmConfigurationBits = {
match: string[];
globOptions?: any;
key: string | XfmConfKeyBits;
destination?: string;
testDestination?: string;
};
export type XfmConfiguration = {
source: XfmConfigurationBits;
module: XfmConfigurationBits;
};
export type XfmConf = {
xfmConf: XfmConfiguration;
};
export type VersionTransformOptions = {
byType?: string;
toVersion?: string;
projectFlag?: boolean;
sourceFlag?: boolean;
testFlag?: boolean;
};
export type CopyrightTransformOptions = {
copyrightType: string;
toYear?: string;
testFlag?: boolean;
};
export type XfmOptions = {
xfmOptions: {
version: VersionTransformOptions;
copyright: CopyrightTransformOptions;
};
};
export type BumpOptions = {
version?: string;
type?: string;
key?: string;
};
export type XfmrTarget = {
paths: string | string[];
};
export type XfmrOptions = NodeKitOptions & XfmOptions & XfmConf;
/**
* The Transformer class is a replacement for gulp-bump-version within
* our newly redesigned project template that excludes gulp altogether
* as the primary build tool in favor of our own end-to-end tooling.
*
* The service provider can also be used as a template for other similar
* service provider types.
*/
export declare class Transformer extends ServiceProvider {
/**
* @var { Configuration }
*/
configuration: Configuration;
/**
* Class constructor
*/
constructor(handler?: (data: ServiceEventBits) => void, configuration?: NodeKitOptions);
getServiceProviderSubscriptions(options?: any): ServiceProviderSubscriptions;
getServiceProviderSubscriptionHelpText<T extends ServiceProviderHelpText>(options?: any): T;
/**
* Method to resettle the { NodeKitProjectGeneratorOptions }. Essentially we
* merge NodeKitOptions with FilesystemDescriptor by combining provided
* command options with either a stored configuration or sane default.
*
* @param { ReactComponentGeneratorOptions } options
*
* @returns { ReactComponentGeneratorOptions } The options object, with the configuration partially populated with user-provided information
*/
assembleOptions<T extends XfmrOptions>(options: XfmrOptions): Promise<T>;
renderService(options: NodeKitOptions): Promise<any>;
/**
* 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;
/**
* Gets an array of string paths returned by the glob processor
*
* @param { string|string[] } target The string or string array of glob patterns to match
* @param { any } options The glob processor's options (see {@link glob})
*
* @returns { Promise<string[]> } The promise of an array of string paths
*/
getTargetPaths(target: string | string[], options: any): Promise<(string | Path)[]>;
/**
* Wraps `glob` with a promise
*
* @param { string } target A string pattern for glob to match against
* @param { any } options `glob`'s options object
*
* @returns { string[] } An array of matched PlatformPaths as strings
*/
globIt(target: string, options: GlobOptions): Promise<string[] | Path[]>;
/**
* Applies a transform stream to each target path provided. This method wraps the
* process and responds appropriately for the service provider
*
* @param { XfmrOptions } options
*
* @returns { Promise<any> } A promise of any - though expect an extended object of type {@link ServicePromiseBits}
*/
transformTarget(options: XfmrOptions): Promise<any>;
/**
* A middle-man method that eases readability due to needing to support
* several related transformations, each of which have certain catche
* cases that differentiate and nuance them from one another.
*
* A different method is called from here depending on whether we are
* transforming the version or the copyright; If the former, we may
* make upwards of two calls to support the differentiation between
* the version within typical source and that of the module's
* package.json file.
*
*
* @param { string[] } files An array of target paths matched for transformation
* @param { VersionTransformOptions | CopyrightTransformOptions } opts A {@link VersionTransformOptions} or {@link CopyrightTransformOptions} object
* @param { XfmConfigurationBits } conf Eitehr the source or module {@link XfmConfigurationBits} object from the {@link XfmConfiguration} objecct
* @param { boolean } version Denotes whether or not we're doing a version transform. Defaults to false
* @param { boolean } copyright Denotes whether or not we're doing a copyright transform. Defaults to false
*
* @returns { Promise<string[]> } The promise of an array of strings
*/
process(files: (string | Path)[], opts: VersionTransformOptions | CopyrightTransformOptions, conf: XfmConfigurationBits, version?: boolean, copyright?: boolean): Promise<string[]>;
/**
* Ensures that the destination for a target exists so that the
* target can be written .
*
* @param { string } target The path to the target, relative the cwd
* @param { boolean } test Denotes whether this is a test run
* @param { string } destination The destination of the target, relative to cwd
*
* @return { Promise<string> } A promise of the new string path to target
*/
satisfyDestFs(target: string, test?: boolean, testDestination?: string, destination?: string): Promise<string>;
/**
* Applies a transform stream between a read and write stream so as to bump
* the semantic version string found within each target according to options
* provided.
*
* @param { string } file The string path of the target file
* @param { XfmConfigurationBits } conf A {@link XfmConfigurationBits} object
* @param { VersionTransformOptions } options A {@link VersionTransformOptions} object
* @param { boolean } version Denotes whether to transform the version
* @param { boolean } copyright Denotes whether to transform the copyright
*
* @returns { string } The string destination path of the target
*/
processFile(source: string, target: string, conf: XfmConfigurationBits, options: VersionTransformOptions, version?: boolean, copyright?: boolean): Promise<string>;
/**
* Method intended to apply the correct transformation of those available, based on the request
*
* @param { string } data The read in data
* @param { XfmConfigurationBits } conf A {@link XfmConfigurationBits} object
* @param { VersionTransformOptions } options A {@link VersionTransformOptions} object
* @param { boolean } version Denotes whether to transform the version
* @param { copyright } copyright Denotes whether to transform the copyright
*
* @returns { string } The transformed data. If an error is caught, its `throw`n
*/
transformData(data: string, conf: XfmConfigurationBits, options: VersionTransformOptions, version?: boolean, copyright?: boolean): string;
}