@rainbow-o23/n1 0.1.1

package/src/lib/pipeline/pipeline.ts

@@ -0,0 +1,148 @@
+import {nanoid} from 'nanoid';
+import {Config, Logger} from '../utils';
+import {AbstractPipelineExecution, PipelineExecutionOptions} from './pipeline-execution';
+import {
+	DefaultPipelineStepBuilder,
+	PipelineStep,
+	PipelineStepBuilder,
+	PipelineStepData,
+	PipelineStepOptions,
+	PipelineStepType
+} from './pipeline-step';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PipelineRequestPayload = any;
+
+export interface PipelineRequest<C = PipelineRequestPayload> {
+	payload: C;
+	traceId?: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PipelineResponsePayload = any;
+
+export interface PipelineResponse<C = PipelineResponsePayload> {
+	payload: C;
+}
+
+export type PipelineCode = string;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface Pipeline<In = any, Out = any> {
+	/**
+	 * code should be unique globally
+	 */
+	getCode(): PipelineCode;
+
+	/**
+	 * perform pipeline
+	 */
+	perform(request: PipelineRequest<In>): Promise<PipelineResponse<Out>>;
+}
+
+export interface PipelineOptions extends PipelineExecutionOptions {
+	config?: Config;
+	logger?: Logger;
+}
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export interface PipelineType<P = Pipeline> extends Function {
+	new(options?: PipelineOptions): P;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export abstract class AbstractPipeline<In = any, Out = any> extends AbstractPipelineExecution implements Pipeline<In, Out> {
+	// noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected
+	public constructor(options?: PipelineOptions) {
+		super(options);
+	}
+
+	public abstract getCode(): PipelineCode;
+
+	/**
+	 * get type of steps
+	 */
+	protected abstract getStepBuilders(): Array<PipelineStepBuilder>;
+
+	protected buildStepOptions(): Pick<PipelineStepOptions, 'config' | 'logger'> {
+		return {config: this._config, logger: this._logger};
+	}
+
+	/**
+	 * create all steps
+	 */
+	public async createSteps(): Promise<Array<PipelineStep>> {
+		const options = this.buildStepOptions();
+		return await Promise.all(this.getStepBuilders().map(async builder => await builder.create(options)));
+	}
+
+	public convertRequestToPipelineData<I, FirstStepIn>(request: PipelineRequest<I>): PipelineStepData<FirstStepIn> {
+		return {content: request.payload as unknown as FirstStepIn};
+	}
+
+	public convertPipelineDataToResponse<LastStepOut, O>(result: PipelineStepData<LastStepOut>): PipelineResponse<O> {
+		return {payload: result.content as unknown as O};
+	}
+
+	protected createTraceId(request: PipelineRequest<In>): string {
+		const {traceId} = request;
+		if (traceId == null || traceId.trim().length === 0) {
+			return nanoid(16);
+		} else {
+			return traceId;
+		}
+	}
+
+	/**
+	 * perform pipeline.
+	 * - first step use request as input,
+	 * - other steps use the result of previous step,
+	 * - use last step's result as response.
+	 */
+	public async perform(request: PipelineRequest<In>): Promise<PipelineResponse<Out>> {
+		const traceId = this.createTraceId(request);
+		const response = await this.measurePerformance(traceId, 'PIPELINE')
+			.execute(async () => {
+				this.traceRequest(traceId, request);
+				const steps = await this.createSteps();
+				const data = await steps.reduce(async (promise, step) => {
+					const request = await promise;
+					return await this.measurePerformance(traceId, 'STEP')
+						.execute(async () => {
+							this.traceStepIn(traceId, step, request);
+							const response = await step.perform({
+								...request, $context: {...request.$context, traceId}
+							});
+							this.traceStepOut(traceId, step, response);
+							// if no response returned, keep using request for next
+							return this.returnOrContinueOrClear(request, response);
+						});
+				}, Promise.resolve(this.convertRequestToPipelineData(request)));
+				return this.traceResponse(traceId, this.convertPipelineDataToResponse(data));
+			});
+		return response as PipelineResponse<Out>;
+	}
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export abstract class AbstractStaticPipeline<In = any, Out = any> extends AbstractPipeline<In, Out> {
+	protected abstract getStepTypes(): Array<PipelineStepType>;
+
+	protected getStepBuilders(): Array<PipelineStepBuilder> {
+		return this.getStepTypes().map(type => new DefaultPipelineStepBuilder(type));
+	}
+}
+
+export interface PipelineBuilder {
+	create(options?: PipelineOptions): Promise<Pipeline>;
+}
+
+// noinspection JSUnusedGlobalSymbols
+export class DefaultPipelineBuilder implements PipelineBuilder {
+	public constructor(protected readonly pipeline: PipelineType) {
+	}
+
+	public async create(options?: PipelineOptions): Promise<Pipeline> {
+		return new this.pipeline(options);
+	}
+}

package/src/lib/pipeline/step-helpers-utils.ts

@@ -0,0 +1,143 @@
+import {customAlphabet, nanoid} from 'nanoid';
+import {CatchableError, ERR_TRIM_NON_STRING, ExposedUncatchableError, UncatchableError} from '../utils';
+import {PipelineStepHelpers} from './index';
+
+export interface PipelineStepErrorOptions {
+	// exactly same as http status
+	status: number;
+	code: string;
+	reason: string;
+}
+
+export interface PipelineStepFileOptions {
+	name?: string;
+	type?: string;
+	content: string | Buffer;
+}
+
+export const PIPELINE_STEP_FILE_SYMBOL = Symbol();
+export const PIPELINE_STEP_RETURN_NULL = Symbol();
+
+export interface PipelineStepFile {
+	$file: typeof PIPELINE_STEP_FILE_SYMBOL;
+	name?: string;
+	type?: string;
+	content: Buffer;
+}
+
+export class StepHelpersUtils {
+	private static asciiNanoId = customAlphabet('1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_', 32);
+	private static OBJECT_PROTOTYPE = Object.prototype;
+
+	private constructor() {
+		// avoid extend
+	}
+
+	// nano id
+	public static $nano(size?: number): string {
+		return nanoid(size);
+	}
+
+	public static $ascii(size?: number): string {
+		return StepHelpersUtils.asciiNanoId(size);
+	}
+
+	// error
+	public static createCatchableError = (options: Omit<PipelineStepErrorOptions, 'status'>): never => {
+		throw new CatchableError(options.code, options.reason);
+	};
+	public static createExposedUncatchableError = (options: PipelineStepErrorOptions): never => {
+		throw new ExposedUncatchableError(options.status, options.code, options.reason);
+	};
+	public static createUncatchableError = (options: Omit<PipelineStepErrorOptions, 'status'>): never => {
+		throw new UncatchableError(options.code, options.reason);
+	};
+	public static readonly $errors: PipelineStepHelpers['$errors'] = {
+		catchable: StepHelpersUtils.createCatchableError,
+		exposed: StepHelpersUtils.createExposedUncatchableError,
+		uncatchable: StepHelpersUtils.createUncatchableError
+	};
+
+	// file
+	public static createFile(options: PipelineStepFileOptions): PipelineStepFile {
+		return {
+			$file: PIPELINE_STEP_FILE_SYMBOL,
+			name: options.name, type: options.type,
+			content: typeof options.content === 'string' ? Buffer.from(options.content) : options.content
+		};
+	}
+
+	// semaphore
+	public static $clearContextData(): typeof PIPELINE_STEP_RETURN_NULL {
+		return PIPELINE_STEP_RETURN_NULL;
+	}
+
+	// utils
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isPrototype(value: any): boolean {
+		const Ctor = value && value.constructor;
+		const proto = (typeof Ctor === 'function' && Ctor.prototype) || StepHelpersUtils.OBJECT_PROTOTYPE;
+
+		return value === proto;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isLength(value: any): boolean {
+		return typeof value === 'number' && value > -1 && value % 1 === 0 && value <= Number.MAX_SAFE_INTEGER;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isArrayLike(value: any): boolean {
+		return value != null && typeof value !== 'function' && StepHelpersUtils.isLength(value.length);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isEmpty(value: any): boolean {
+		if (value == null) {
+			return true;
+		}
+		if (StepHelpersUtils.isArrayLike(value) && (Array.isArray(value) || typeof value === 'string')) {
+			return value.length === 0;
+		} else if (value instanceof Map) {
+			return value.size === 0;
+		} else if (value instanceof Set) {
+			return value.size === 0;
+		} else if (StepHelpersUtils.isPrototype(value)) {
+			return Object.keys(value).length === 0;
+		}
+
+		return false;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isNotEmpty(value: any): boolean {
+		return !StepHelpersUtils.isEmpty(value);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isBlank(value: any): boolean {
+		if (value == null) {
+			return true;
+		}
+		if (typeof value !== 'string') {
+			return false;
+		}
+		return value.trim().length === 0;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isNotBlank(value: any): boolean {
+		return !StepHelpersUtils.isBlank(value);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static trim(value: any): string {
+		if (value == null) {
+			return '';
+		}
+		if (typeof value === 'string') {
+			return value.trim();
+		}
+		throw new UncatchableError(ERR_TRIM_NON_STRING, `Cannot apply trim to non-string object[type=${typeof value}, value=${value}].`);
+	}
+}

package/src/lib/pipeline/step-helpers.ts

@@ -0,0 +1,77 @@
+import dayjs from 'dayjs';
+import {Config, DateTime, Logger} from '../utils';
+import {
+	PIPELINE_STEP_RETURN_NULL,
+	PipelineStepErrorOptions,
+	PipelineStepFile,
+	PipelineStepFileOptions,
+	StepHelpersUtils
+} from './step-helpers-utils';
+
+export class PipelineStepDateHelper {
+	private readonly _dateTimeFormat: string;
+
+	public constructor(config: Config) {
+		this._dateTimeFormat = config.getString('format.datetime', 'YYYY-MM-DD HH:mm:ss');
+	}
+
+	public getDateTimeFormat(): string {
+		return this._dateTimeFormat;
+	}
+
+	public now(): DateTime {
+		return dayjs().format(this.getDateTimeFormat());
+	}
+
+	public get dayjs(): typeof dayjs {
+		return dayjs;
+	}
+}
+
+export interface PipelineStepHelpers {
+	$config?: Config;
+	$logger?: Logger;
+	$date: PipelineStepDateHelper;
+	$nano: (size?: number) => string;
+	$ascii: (size?: number) => string;
+	/** create an exposed uncatchable error*/
+	$error: (options: PipelineStepErrorOptions) => never;
+	$errors: {
+		catchable: (options: Omit<PipelineStepErrorOptions, 'status'>) => never;
+		exposed: (options: PipelineStepErrorOptions) => never;
+		uncatchable: (options: Omit<PipelineStepErrorOptions, 'status'>) => never;
+	};
+	/** create a file */
+	$file: (options: PipelineStepFileOptions) => PipelineStepFile;
+	$clearContextData: () => typeof PIPELINE_STEP_RETURN_NULL;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	isEmpty: (value: any) => boolean;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	isNotEmpty: (value: any) => boolean;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	isBlank: (value: any) => boolean;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	isNotBlank: (value: any) => boolean;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	trim: (value: any) => string;
+}
+
+export const createStepHelpers = (config: Config, logger: Logger): PipelineStepHelpers => {
+	return {
+		$config: config, $logger: logger,
+		// date
+		$date: new PipelineStepDateHelper(config),
+		// nano
+		$nano: StepHelpersUtils.$nano, $ascii: StepHelpersUtils.$ascii,
+		// errors
+		$error: StepHelpersUtils.createExposedUncatchableError, $errors: StepHelpersUtils.$errors,
+		// file
+		$file: StepHelpersUtils.createFile,
+		// semaphore
+		$clearContextData: StepHelpersUtils.$clearContextData,
+		// utilities
+		isEmpty: StepHelpersUtils.isEmpty, isNotEmpty: StepHelpersUtils.isNotEmpty,
+		isBlank: StepHelpersUtils.isBlank, isNotBlank: StepHelpersUtils.isNotBlank,
+		trim: StepHelpersUtils.trim
+	};
+};

package/src/lib/repo/index.ts

@@ -0,0 +1 @@
+export * from './pipeline-repository';

package/src/lib/repo/pipeline-repository.ts

@@ -0,0 +1,53 @@
+import {
+	Pipeline,
+	PipelineBuilder,
+	PipelineCode,
+	PipelineOptions,
+	PipelineStepBuilder,
+	PipelineStepCode
+} from '../pipeline';
+import {Undefinable} from '../utils';
+
+export class PipelineRepository {
+	private static readonly PIPELINE_BUILDERS: Record<PipelineCode, PipelineBuilder> = {};
+	private static readonly STEP_BUILDERS: Record<PipelineStepCode, PipelineStepBuilder> = {};
+
+	private constructor() {
+		// avoid extend
+	}
+
+	public static async findPipeline(code: PipelineCode, options: PipelineOptions): Promise<Undefinable<Pipeline>> {
+		const builder = this.PIPELINE_BUILDERS[code];
+		if (builder == null) {
+			return (void 0);
+		} else {
+			return await builder.create(options);
+		}
+	}
+
+	public static putPipeline(builders: Record<PipelineCode, PipelineBuilder>): Record<PipelineCode, PipelineBuilder> {
+		return Object.keys(builders).reduce((duplicated, code) => {
+			const existing = PipelineRepository.PIPELINE_BUILDERS[code];
+			PipelineRepository.PIPELINE_BUILDERS[code] = builders[code];
+			if (existing != null) {
+				duplicated[code] = existing;
+			}
+			return duplicated;
+		}, {} as Record<PipelineCode, PipelineBuilder>);
+	}
+
+	public static async findStep(code: PipelineStepCode): Promise<Undefinable<PipelineStepBuilder>> {
+		return PipelineRepository.STEP_BUILDERS[code];
+	}
+
+	public static putStep(builders: Record<PipelineStepCode, PipelineStepBuilder>): Record<PipelineStepCode, PipelineStepBuilder> {
+		return Object.keys(builders).reduce((duplicated, code) => {
+			const existing = PipelineRepository.STEP_BUILDERS[code];
+			PipelineRepository.STEP_BUILDERS[code] = builders[code];
+			if (existing != null) {
+				duplicated[code] = existing;
+			}
+			return duplicated;
+		}, {} as Record<PipelineStepCode, PipelineStepBuilder>);
+	}
+}

package/src/lib/utils/config.ts

@@ -0,0 +1,110 @@
+import {createLogger, Logger} from './logger';
+import {Undefinable} from './types';
+
+const MISSED = Symbol();
+
+export class Config {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	private valueCache: Record<string, any> = {};
+
+	public constructor(private _logger: Logger) {
+	}
+
+	public getLogger(): Logger {
+		return this._logger;
+	}
+
+	public setLogger(value: Logger) {
+		this._logger = value;
+	}
+
+	protected generateKey(name: string) {
+		const key = name
+			.split('.')
+			.filter(s => s.trim().length !== 0)
+			.map(s => s.toUpperCase())
+			.join('_');
+		return `CFG_${key}`;
+	}
+
+	protected getFromCache<T>(name: string, read: () => Undefinable<T>, defaultValue?: T): Undefinable<T> {
+		const cached = this.valueCache[name];
+		if (cached === MISSED) {
+			return defaultValue ?? (void 0);
+		} else if (cached != null) {
+			return cached;
+		} else {
+			const value = read();
+			this.valueCache[name] = value ?? MISSED;
+			return value ?? defaultValue ?? (void 0);
+		}
+	}
+
+	public getString(name: string, defaultValue?: string): Undefinable<string> {
+		return this.getFromCache(name, () => {
+			// noinspection JSUnresolvedReference
+			const value = process.env[this.generateKey(name)];
+			if (value == null || value.trim().length === 0) {
+				return (void 0);
+			} else {
+				return value.trim();
+			}
+		}, defaultValue);
+	}
+
+	public getBoolean(name: string, defaultValue?: boolean): Undefinable<boolean> {
+		return this.getFromCache(name, () => {
+			// noinspection JSUnresolvedReference
+			const value = process.env[this.generateKey(name)];
+			if (value == null || value.trim().length === 0) {
+				return (void 0);
+			} else if (['TRUE', 'YES', 'ON', '1'].includes(value.trim().toUpperCase())) {
+				return true;
+			} else if (['FALSE', 'NO', 'OFF', '0'].includes(value.trim().toUpperCase())) {
+				return false;
+			} else {
+				this._logger.warn(`Cannot parse given configuration item value[${value}] to boolean, ignored.`, Config.name);
+				return (void 0);
+			}
+		}, defaultValue);
+	}
+
+	public getNumber(name: string, defaultValue?: number): Undefinable<number> {
+		return this.getFromCache(name, () => {
+			// noinspection JSUnresolvedReference
+			const value = process.env[this.generateKey(name)];
+			if (value == null || value.trim().length === 0) {
+				return (void 0);
+			}
+			const v = Number(value);
+			if (isNaN(v)) {
+				this._logger.error(`Cannot parse given configuration item value[${value}] to number, ignored.`, Config.name);
+				return (void 0);
+			} else {
+				return v;
+			}
+		}, defaultValue);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public getJson(name: string, defaultValue?: any): Undefinable<any> {
+		return this.getFromCache(name, () => {
+			// noinspection JSUnresolvedReference
+			const value = process.env[this.generateKey(name)];
+			if (value == null || value.trim().length === 0) {
+				return (void 0);
+			} else {
+				try {
+					return JSON.parse(value);
+				} catch {
+					this._logger.warn(`Cannot parse given configuration item value[${value}] to boolean, ignored.`, Config.name);
+					return (void 0);
+				}
+			}
+		}, defaultValue);
+	}
+}
+
+export const createConfig = (logger?: Logger) => {
+	return new Config(logger ?? createLogger());
+};

package/src/lib/utils/error.ts

@@ -0,0 +1,41 @@
+/** should be O00-00000 - O99-99999 */
+export type O23ReservedErrorCode = `O${number}-${number}`;
+/** prefix should be any uppercase but O00 - O99, number should be 00000 - 99999 */
+export type O23ExternalErrorCode = `O${Uppercase<string>}-${number}`;
+export type O23ErrorCode = O23ReservedErrorCode | O23ExternalErrorCode;
+export const ERR_PIPELINE_NOT_FOUND: O23ReservedErrorCode = 'O01-00001';
+export const ERR_TRIM_NON_STRING: O23ReservedErrorCode = 'O01-00002';
+export const ERR_UNKNOWN: O23ReservedErrorCode = 'O01-99999';
+
+export class CatchableError extends Error {
+	public constructor(private readonly _code: string, message: string) {
+		super(message);
+	}
+
+	public getCode(): string {
+		return this._code;
+	}
+}
+
+export class UncatchableError extends Error {
+	public constructor(private readonly _code: string, message: string) {
+		super(message);
+	}
+
+	public getCode(): string {
+		return this._code;
+	}
+}
+
+export class ExposedUncatchableError extends UncatchableError {
+	private readonly _status: number;
+
+	public constructor(status: number, code: string, message: string) {
+		super(code, message);
+		this._status = status;
+	}
+
+	public getStatus(): number {
+		return this._status;
+	}
+}

package/src/lib/utils/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+
+export * from './error';
+
+export * from './logger';
+export * from './config';