@rainbow-o23/n1 0.1.1

package/lib/pipeline/envs.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/pipeline/index.d.ts

@@ -0,0 +1,6 @@
+export * from './envs';
+export * from './pipeline-execution';
+export * from './pipeline-step';
+export * from './pipeline';
+export * from './step-helpers-utils';
+export * from './step-helpers';

package/lib/pipeline/pipeline-execution.d.ts

@@ -0,0 +1,38 @@
+import { Config, Logger } from '../utils';
+import { PipelineOptions } from './pipeline';
+import { PipelineStep, PipelineStepData } from './pipeline-step';
+export interface PerformanceExecutionOptions {
+    exec: 'PIPELINE' | 'STEP';
+    traceId: string;
+    start: bigint;
+    print: (message: () => any) => void;
+}
+export type MeasuredFunction<T> = () => Promise<T>;
+export declare class PerformanceExecution {
+    private readonly options;
+    constructor(options: PerformanceExecutionOptions);
+    execute<T>(measured: MeasuredFunction<T>): Promise<T>;
+}
+export interface PipelineExecutionOptions {
+    config?: Config;
+    logger?: Logger;
+}
+export declare class AbstractPipelineExecution {
+    protected readonly _config: Config;
+    protected readonly _logger: Logger;
+    protected readonly _performanceLogEnabled: boolean;
+    protected readonly _debugLogEnabled: boolean;
+    constructor(options?: PipelineOptions);
+    getConfig(): Config;
+    getLogger(): Logger;
+    protected isDebugLogEnabled(): boolean;
+    protected debug(message: any, ...optionsParams: Array<any>): void;
+    protected traceRequest<T>(traceId: string, data: T): T;
+    protected traceResponse<T>(traceId: string, data: T): T;
+    protected traceStepIn(traceId: string, step: PipelineStep, data: any): void;
+    protected traceStepOut(traceId: string, step: PipelineStep, data: any): void;
+    protected isPerformanceLogEnabled(): boolean;
+    protected debugPerformance(message: () => any): void;
+    protected measurePerformance(traceId: string, exec: 'PIPELINE' | 'STEP'): PerformanceExecution;
+    protected returnOrContinueOrClear(request: PipelineStepData, response: PipelineStepData): PipelineStepData;
+}

package/lib/pipeline/pipeline-step.d.ts

@@ -0,0 +1,41 @@
+import { Config, Logger } from '../utils';
+import { AbstractPipelineExecution, PipelineExecutionOptions } from './pipeline-execution';
+import { PipelineStepHelpers } from './step-helpers';
+export type PipelineStepCode = string;
+export type PipelineStepPayload = any;
+export interface PipelineStepContext {
+    traceId?: string;
+}
+export interface PipelineStepData<C = PipelineStepPayload, CTX = PipelineStepContext> {
+    $context?: CTX;
+    content: C;
+}
+export interface PipelineStep<In = any, Out = any> {
+    getName(): string;
+    perform(request: PipelineStepData<In>): Promise<PipelineStepData<Out>>;
+}
+export interface PipelineStepOptions extends PipelineExecutionOptions {
+    name?: string;
+    config?: Config;
+    logger?: Logger;
+}
+export interface PipelineStepType<S = PipelineStep> extends Function {
+    new (options?: PipelineStepOptions): S;
+}
+export declare abstract class AbstractPipelineStep<In = PipelineStepPayload, Out = PipelineStepPayload> extends AbstractPipelineExecution implements PipelineStep<In, Out> {
+    private _$helpers;
+    protected readonly _name?: string;
+    constructor(options?: PipelineStepOptions);
+    getName(): string;
+    getHelpers(): PipelineStepHelpers;
+    protected getHelpersVariableNames(): Array<string>;
+    abstract perform(request: PipelineStepData<In>): Promise<PipelineStepData<Out>>;
+}
+export interface PipelineStepBuilder {
+    create(options?: PipelineStepOptions): Promise<PipelineStep>;
+}
+export declare class DefaultPipelineStepBuilder implements PipelineStepBuilder {
+    protected readonly step: PipelineStepType;
+    constructor(step: PipelineStepType);
+    create(options?: PipelineStepOptions): Promise<PipelineStep>;
+}

package/lib/pipeline/pipeline.d.ts

@@ -0,0 +1,47 @@
+import { Config, Logger } from '../utils';
+import { AbstractPipelineExecution, PipelineExecutionOptions } from './pipeline-execution';
+import { PipelineStep, PipelineStepBuilder, PipelineStepData, PipelineStepOptions, PipelineStepType } from './pipeline-step';
+export type PipelineRequestPayload = any;
+export interface PipelineRequest<C = PipelineRequestPayload> {
+    payload: C;
+    traceId?: string;
+}
+export type PipelineResponsePayload = any;
+export interface PipelineResponse<C = PipelineResponsePayload> {
+    payload: C;
+}
+export type PipelineCode = string;
+export interface Pipeline<In = any, Out = any> {
+    getCode(): PipelineCode;
+    perform(request: PipelineRequest<In>): Promise<PipelineResponse<Out>>;
+}
+export interface PipelineOptions extends PipelineExecutionOptions {
+    config?: Config;
+    logger?: Logger;
+}
+export interface PipelineType<P = Pipeline> extends Function {
+    new (options?: PipelineOptions): P;
+}
+export declare abstract class AbstractPipeline<In = any, Out = any> extends AbstractPipelineExecution implements Pipeline<In, Out> {
+    constructor(options?: PipelineOptions);
+    abstract getCode(): PipelineCode;
+    protected abstract getStepBuilders(): Array<PipelineStepBuilder>;
+    protected buildStepOptions(): Pick<PipelineStepOptions, 'config' | 'logger'>;
+    createSteps(): Promise<Array<PipelineStep>>;
+    convertRequestToPipelineData<I, FirstStepIn>(request: PipelineRequest<I>): PipelineStepData<FirstStepIn>;
+    convertPipelineDataToResponse<LastStepOut, O>(result: PipelineStepData<LastStepOut>): PipelineResponse<O>;
+    protected createTraceId(request: PipelineRequest<In>): string;
+    perform(request: PipelineRequest<In>): Promise<PipelineResponse<Out>>;
+}
+export declare abstract class AbstractStaticPipeline<In = any, Out = any> extends AbstractPipeline<In, Out> {
+    protected abstract getStepTypes(): Array<PipelineStepType>;
+    protected getStepBuilders(): Array<PipelineStepBuilder>;
+}
+export interface PipelineBuilder {
+    create(options?: PipelineOptions): Promise<Pipeline>;
+}
+export declare class DefaultPipelineBuilder implements PipelineBuilder {
+    protected readonly pipeline: PipelineType;
+    constructor(pipeline: PipelineType);
+    create(options?: PipelineOptions): Promise<Pipeline>;
+}

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

@@ -0,0 +1,41 @@
+/// <reference types="node" />
+import { PipelineStepHelpers } from './index';
+export interface PipelineStepErrorOptions {
+    status: number;
+    code: string;
+    reason: string;
+}
+export interface PipelineStepFileOptions {
+    name?: string;
+    type?: string;
+    content: string | Buffer;
+}
+export declare const PIPELINE_STEP_FILE_SYMBOL: unique symbol;
+export declare const PIPELINE_STEP_RETURN_NULL: unique symbol;
+export interface PipelineStepFile {
+    $file: typeof PIPELINE_STEP_FILE_SYMBOL;
+    name?: string;
+    type?: string;
+    content: Buffer;
+}
+export declare class StepHelpersUtils {
+    private static asciiNanoId;
+    private static OBJECT_PROTOTYPE;
+    private constructor();
+    static $nano(size?: number): string;
+    static $ascii(size?: number): string;
+    static createCatchableError: (options: Omit<PipelineStepErrorOptions, 'status'>) => never;
+    static createExposedUncatchableError: (options: PipelineStepErrorOptions) => never;
+    static createUncatchableError: (options: Omit<PipelineStepErrorOptions, 'status'>) => never;
+    static readonly $errors: PipelineStepHelpers['$errors'];
+    static createFile(options: PipelineStepFileOptions): PipelineStepFile;
+    static $clearContextData(): typeof PIPELINE_STEP_RETURN_NULL;
+    static isPrototype(value: any): boolean;
+    static isLength(value: any): boolean;
+    static isArrayLike(value: any): boolean;
+    static isEmpty(value: any): boolean;
+    static isNotEmpty(value: any): boolean;
+    static isBlank(value: any): boolean;
+    static isNotBlank(value: any): boolean;
+    static trim(value: any): string;
+}

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

@@ -0,0 +1,31 @@
+import dayjs from 'dayjs';
+import { Config, DateTime, Logger } from '../utils';
+import { PIPELINE_STEP_RETURN_NULL, PipelineStepErrorOptions, PipelineStepFile, PipelineStepFileOptions } from './step-helpers-utils';
+export declare class PipelineStepDateHelper {
+    private readonly _dateTimeFormat;
+    constructor(config: Config);
+    getDateTimeFormat(): string;
+    now(): DateTime;
+    get dayjs(): typeof dayjs;
+}
+export interface PipelineStepHelpers {
+    $config?: Config;
+    $logger?: Logger;
+    $date: PipelineStepDateHelper;
+    $nano: (size?: number) => string;
+    $ascii: (size?: number) => string;
+    $error: (options: PipelineStepErrorOptions) => never;
+    $errors: {
+        catchable: (options: Omit<PipelineStepErrorOptions, 'status'>) => never;
+        exposed: (options: PipelineStepErrorOptions) => never;
+        uncatchable: (options: Omit<PipelineStepErrorOptions, 'status'>) => never;
+    };
+    $file: (options: PipelineStepFileOptions) => PipelineStepFile;
+    $clearContextData: () => typeof PIPELINE_STEP_RETURN_NULL;
+    isEmpty: (value: any) => boolean;
+    isNotEmpty: (value: any) => boolean;
+    isBlank: (value: any) => boolean;
+    isNotBlank: (value: any) => boolean;
+    trim: (value: any) => string;
+}
+export declare const createStepHelpers: (config: Config, logger: Logger) => PipelineStepHelpers;

package/lib/repo/index.d.ts

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

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

@@ -0,0 +1,11 @@
+import { Pipeline, PipelineBuilder, PipelineCode, PipelineOptions, PipelineStepBuilder, PipelineStepCode } from '../pipeline';
+import { Undefinable } from '../utils';
+export declare class PipelineRepository {
+    private static readonly PIPELINE_BUILDERS;
+    private static readonly STEP_BUILDERS;
+    private constructor();
+    static findPipeline(code: PipelineCode, options: PipelineOptions): Promise<Undefinable<Pipeline>>;
+    static putPipeline(builders: Record<PipelineCode, PipelineBuilder>): Record<PipelineCode, PipelineBuilder>;
+    static findStep(code: PipelineStepCode): Promise<Undefinable<PipelineStepBuilder>>;
+    static putStep(builders: Record<PipelineStepCode, PipelineStepBuilder>): Record<PipelineStepCode, PipelineStepBuilder>;
+}

package/lib/utils/config.d.ts

@@ -0,0 +1,16 @@
+import { Logger } from './logger';
+import { Undefinable } from './types';
+export declare class Config {
+    private _logger;
+    private valueCache;
+    constructor(_logger: Logger);
+    getLogger(): Logger;
+    setLogger(value: Logger): void;
+    protected generateKey(name: string): string;
+    protected getFromCache<T>(name: string, read: () => Undefinable<T>, defaultValue?: T): Undefinable<T>;
+    getString(name: string, defaultValue?: string): Undefinable<string>;
+    getBoolean(name: string, defaultValue?: boolean): Undefinable<boolean>;
+    getNumber(name: string, defaultValue?: number): Undefinable<number>;
+    getJson(name: string, defaultValue?: any): Undefinable<any>;
+}
+export declare const createConfig: (logger?: Logger) => Config;

package/lib/utils/error.d.ts

@@ -0,0 +1,21 @@
+export type O23ReservedErrorCode = `O${number}-${number}`;
+export type O23ExternalErrorCode = `O${Uppercase<string>}-${number}`;
+export type O23ErrorCode = O23ReservedErrorCode | O23ExternalErrorCode;
+export declare const ERR_PIPELINE_NOT_FOUND: O23ReservedErrorCode;
+export declare const ERR_TRIM_NON_STRING: O23ReservedErrorCode;
+export declare const ERR_UNKNOWN: O23ReservedErrorCode;
+export declare class CatchableError extends Error {
+    private readonly _code;
+    constructor(_code: string, message: string);
+    getCode(): string;
+}
+export declare class UncatchableError extends Error {
+    private readonly _code;
+    constructor(_code: string, message: string);
+    getCode(): string;
+}
+export declare class ExposedUncatchableError extends UncatchableError {
+    private readonly _status;
+    constructor(status: number, code: string, message: string);
+    getStatus(): number;
+}

package/lib/utils/index.d.ts

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

package/lib/utils/logger.d.ts

@@ -0,0 +1,50 @@
+export type LoggerLevel = 'debug' | 'verbose' | 'log' | 'warn' | 'error';
+export type LoggerName = `${string}.${LoggerLevel}`;
+export type LoggerEnablement = Record<LoggerName, boolean>;
+export interface Logger {
+    log(message: any, ...optionalParams: any[]): any;
+    error(message: any, ...optionalParams: any[]): any;
+    warn(message: any, ...optionalParams: any[]): any;
+    debug?(message: any, ...optionalParams: any[]): any;
+    verbose?(message: any, ...optionalParams: any[]): any;
+}
+export declare class EnhancedLogger implements Logger {
+    private static ENABLED_LEVELS;
+    private static ENABLEMENTS;
+    private _logger;
+    constructor(logger: Logger);
+    getInternalLogger(): Logger;
+    static enableLevel(level: LoggerLevel): void;
+    static disableLevel(level: LoggerLevel): void;
+    static isLevelEnabled(level: LoggerLevel): boolean;
+    static enable(name: LoggerName | string): void;
+    static disable(name: LoggerName | string): void;
+    static isEnabled(name: LoggerName): boolean;
+    takeover(to: Logger): void;
+    restore(): void;
+    debug(message: any, ...optionalParams: any[]): any;
+    verbose(message: any, ...optionalParams: any[]): any;
+    log(message: any, ...optionalParams: any[]): any;
+    warn(message: any, ...optionalParams: any[]): any;
+    error(message: any, ...optionalParams: any[]): any;
+}
+export declare class ConsoleLogger implements Logger {
+    private buildPrefix;
+    debug(message: any, ...optionalParams: any[]): any;
+    verbose(message: any, ...optionalParams: any[]): any;
+    log(message: any, ...optionalParams: any[]): any;
+    warn(message: any, ...optionalParams: any[]): any;
+    error(message: any, ...optionalParams: any[]): any;
+}
+export declare const createLogger: (logger?: Logger) => EnhancedLogger;
+export declare class LoggerPerformanceSaver {
+    private readonly message;
+    constructor(message: () => string);
+    get [Symbol.toStringTag](): string;
+}
+export declare const saveLoggerPerformance: (message: () => string) => LoggerPerformanceSaver;
+export declare class LoggerUtils {
+    private constructor();
+    static stringifyObject(given: any): string;
+    static normalizeObject(given: any): any;
+}

package/lib/utils/types.d.ts

@@ -0,0 +1,7 @@
+export type Nullable<T> = T | null | undefined;
+export type Undefinable<T> = T | undefined;
+export type DateTime = string;
+export interface Type<T = any> extends Function {
+    new (...args: any[]): T;
+}
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@rainbow-o23/n1",
+	"version": "0.1.1",
+	"description": "o23 interfaces",
+	"main": "index.cjs",
+	"module": "index.js",
+	"types": "index.d.ts",
+	"type": "module",
+	"scripts": {
+		"build": "rollup -c",
+		"build:ci": "rollup -c rollup.config.ci.js",
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"license": "UNLICENSED",
+	"author": "Rainbow Team",
+	"dependencies": {
+		"dayjs": "^1.11.8",
+		"nanoid": "3.3.6"
+	},
+	"devDependencies": {
+		"@babel/core": "^7.20.5",
+		"@babel/preset-env": "^7.20.2",
+		"@babel/preset-typescript": "^7.18.6",
+		"@rollup/plugin-babel": "^6.0.4",
+		"@rollup/plugin-eslint": "^9.0.3",
+		"@types/events": "^3.0.1",
+		"@types/node": "18.16.12",
+		"@typescript-eslint/eslint-plugin": "^5.46.0",
+		"@typescript-eslint/parser": "^5.46.0",
+		"eslint": "^8.29.0",
+		"rollup": "^3.7.0",
+		"rollup-plugin-tslint": "^0.2.2",
+		"rollup-plugin-typescript2": "^0.34.1",
+		"tslib": "^2.4.1",
+		"typescript": "5.1.6"
+	},
+	"volta": {
+		"node": "18.19.0",
+		"yarn": "1.22.21"
+	}
+}

package/rollup.config.base.js

@@ -0,0 +1,30 @@
+import {babel} from '@rollup/plugin-babel';
+import eslint from '@rollup/plugin-eslint';
+import typescript from 'rollup-plugin-typescript2';
+
+export const buildConfig = (lint) => {
+	// ['./index.d.ts', './index.js', './index.cjs', './lib'].forEach(f => {
+	// 	const cwd = path.resolve(process.cwd(), f);
+	// 	if (fs.existsSync(cwd)) {
+	// 		fs.rmSync(cwd, {recursive: true, force: true});
+	// 	}
+	// });
+
+	return {
+		input: './src/index.ts',
+		output: [
+			{format: 'es', dir: '.'},
+			{format: 'cjs', file: './index.cjs'}
+		],
+		plugins: [
+			lint ? eslint({exclude: ['../node_modules/**', 'node_modules/**']}) : null,
+			// lint ? tslint({exclude: ['../node_modules/**', 'node_modules/**']}) : null,
+			typescript({clean: true}),
+			babel({babelHelpers: 'bundled'})
+		].filter(x => x != null),
+		external(id) {
+			return ["dayjs/plugin/"].some(scope => id.startsWith(scope))
+				|| ['nanoid', 'dayjs'].includes(id);
+		}
+	};
+};

package/rollup.config.ci.js

@@ -0,0 +1,3 @@
+import {buildConfig} from './rollup.config.base.js';
+
+export default [buildConfig(false)];

package/rollup.config.js

@@ -0,0 +1,3 @@
+import {buildConfig} from './rollup.config.base.js';
+
+export default [buildConfig(true)];

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/utils';
+
+export * from './lib/pipeline';
+export * from './lib/repo';

package/src/lib/pipeline/envs.ts

@@ -0,0 +1,20 @@
+import dayjs from 'dayjs';
+import ArraySupport from 'dayjs/plugin/arraySupport.js';
+import CustomParseFormat from 'dayjs/plugin/customParseFormat.js';
+import Duration from 'dayjs/plugin/duration.js';
+import IsToday from 'dayjs/plugin/isToday.js';
+import ObjectSupport from 'dayjs/plugin/objectSupport.js';
+import QuarterOfYear from 'dayjs/plugin/quarterOfYear.js';
+import RelativeTime from 'dayjs/plugin/relativeTime.js';
+import UTC from 'dayjs/plugin/utc.js';
+import WeekOfYear from 'dayjs/plugin/weekOfYear.js';
+
+dayjs.extend(WeekOfYear);
+dayjs.extend(QuarterOfYear);
+dayjs.extend(Duration);
+dayjs.extend(IsToday);
+dayjs.extend(RelativeTime);
+dayjs.extend(ArraySupport);
+dayjs.extend(ObjectSupport);
+dayjs.extend(CustomParseFormat);
+dayjs.extend(UTC);

package/src/lib/pipeline/index.ts

@@ -0,0 +1,7 @@
+export * from './envs';
+export * from './pipeline-execution';
+export * from './pipeline-step';
+export * from './pipeline';
+
+export * from './step-helpers-utils';
+export * from './step-helpers';

package/src/lib/pipeline/pipeline-execution.ts

@@ -0,0 +1,137 @@
+import {Config, createConfig, createLogger, Logger, LoggerUtils} from '../utils';
+import {PipelineOptions} from './pipeline';
+import {PipelineStep, PipelineStepData} from './pipeline-step';
+import {PIPELINE_STEP_RETURN_NULL} from './step-helpers-utils';
+
+export interface PerformanceExecutionOptions {
+	exec: 'PIPELINE' | 'STEP';
+	traceId: string;
+	start: bigint;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	print: (message: () => any) => void;
+}
+
+export type MeasuredFunction<T> = () => Promise<T>;
+
+export class PerformanceExecution {
+	public constructor(private readonly options: PerformanceExecutionOptions) {
+	}
+
+	public async execute<T>(measured: MeasuredFunction<T>): Promise<T> {
+		try {
+			return await measured();
+		} finally {
+			this.options.print(() => {
+				return {
+					exec: this.options.exec, ptraceId: this.options.traceId,
+					spent: Number((process.hrtime.bigint() - this.options.start) / 1000000n)
+				};
+			});
+		}
+	}
+}
+
+export interface PipelineExecutionOptions {
+	config?: Config;
+	logger?: Logger;
+}
+
+export class AbstractPipelineExecution {
+	protected readonly _config: Config;
+	protected readonly _logger: Logger;
+	protected readonly _performanceLogEnabled: boolean;
+	protected readonly _debugLogEnabled: boolean;
+
+	// noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected
+	public constructor(options?: PipelineOptions) {
+		const {config, logger} = options ?? {};
+		this._logger = logger ?? createLogger();
+		this._config = config ?? createConfig(this._logger);
+		this._debugLogEnabled = this._config.getBoolean('pipeline.debug.log.enabled', false);
+		this._performanceLogEnabled = this._debugLogEnabled || this._config.getBoolean('pipeline.performance.log.enabled', false);
+	}
+
+	public getConfig(): Config {
+		return this._config;
+	}
+
+	public getLogger(): Logger {
+		return this._logger;
+	}
+
+	protected isDebugLogEnabled(): boolean {
+		return this._debugLogEnabled;
+	}
+
+	/**
+	 * must check {@link isDebugLogEnabled} first
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	protected debug(message: any, ...optionsParams: Array<any>): void {
+		if (this.isDebugLogEnabled()) {
+			message = typeof message === 'function' ? message() : message;
+			message = Array.isArray(message) ? message : [message];
+			const [first, ...rest] = [...message, ...optionsParams.map(m => typeof m === 'function' ? m() : m)];
+			this.getLogger().debug(first ?? '', ...rest, this.constructor.name);
+		}
+	}
+
+	protected traceRequest<T>(traceId: string, data: T): T {
+		this.debug(() => ({exec: 'PIPELINE', ptraceId: traceId, request: LoggerUtils.normalizeObject(data)}));
+		return data;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	protected traceResponse<T>(traceId: string, data: T): T {
+		this.debug(() => ({exec: 'PIPELINE', ptraceId: traceId, response: LoggerUtils.normalizeObject(data)}));
+		return data;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	protected traceStepIn(traceId: string, step: PipelineStep, data: any) {
+		this.debug(() => ({
+			exec: 'STEP', name: step.getName(), ptraceId: traceId, in: LoggerUtils.normalizeObject(data)
+		}));
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	protected traceStepOut(traceId: string, step: PipelineStep, data: any) {
+		this.debug(() => ({
+			exec: 'STEP', name: step.getName(), ptraceId: traceId, out: LoggerUtils.normalizeObject(data)
+		}));
+	}
+
+	protected isPerformanceLogEnabled(): boolean {
+		return this._performanceLogEnabled;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	protected debugPerformance(message: () => any): void {
+		if (this.isPerformanceLogEnabled()) {
+			this.getLogger().debug(message(), this.constructor.name);
+		}
+	}
+
+	protected measurePerformance(traceId: string, exec: 'PIPELINE' | 'STEP'): PerformanceExecution {
+		return new PerformanceExecution({
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			exec, traceId, start: process.hrtime.bigint(), print: (message: () => any) => this.debugPerformance(message)
+		});
+	}
+
+	/**
+	 * check given response's content
+	 * 1. is {@link PIPELINE_STEP_RETURN_NULL}, return directly, identify as clear
+	 * 2. is null, continue using request
+	 * 3. return directly
+	 */
+	protected returnOrContinueOrClear(request: PipelineStepData, response: PipelineStepData): PipelineStepData {
+		if (response.content === PIPELINE_STEP_RETURN_NULL) {
+			return response;
+		} else if (response.content == null) {
+			return request;
+		} else {
+			return response;
+		}
+	}
+}

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

@@ -0,0 +1,79 @@
+import {Config, Logger} from '../utils';
+import {AbstractPipelineExecution, PipelineExecutionOptions} from './pipeline-execution';
+import {createStepHelpers, PipelineStepHelpers} from './step-helpers';
+
+export type PipelineStepCode = string;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PipelineStepPayload = any;
+
+export interface PipelineStepContext {
+	traceId?: string;
+}
+
+export interface PipelineStepData<C = PipelineStepPayload, CTX = PipelineStepContext> {
+	/** this is runtime context */
+	$context?: CTX;
+	content: C;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface PipelineStep<In = any, Out = any> {
+	getName(): string;
+
+	perform(request: PipelineStepData<In>): Promise<PipelineStepData<Out>>;
+}
+
+export interface PipelineStepOptions extends PipelineExecutionOptions {
+	name?: string;
+	config?: Config;
+	logger?: Logger;
+}
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export interface PipelineStepType<S = PipelineStep> extends Function {
+	new(options?: PipelineStepOptions): S;
+}
+
+export abstract class AbstractPipelineStep<In = PipelineStepPayload, Out = PipelineStepPayload>
+	extends AbstractPipelineExecution implements PipelineStep<In, Out> {
+	private _$helpers: PipelineStepHelpers;
+	protected readonly _name?: string;
+
+	// noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected
+	public constructor(options?: PipelineStepOptions) {
+		super(options);
+		this._name = options?.name;
+	}
+
+	public getName(): string {
+		return (this._name == null || this._name.trim().length === 0) ? this.constructor.name : this._name;
+	}
+
+	public getHelpers(): PipelineStepHelpers {
+		if (this._$helpers == null) {
+			this._$helpers = createStepHelpers(this.getConfig(), this.getLogger());
+		}
+		return this._$helpers;
+	}
+
+	protected getHelpersVariableNames(): Array<string> {
+		return ['$helpers', '$'];
+	}
+
+	public abstract perform(request: PipelineStepData<In>): Promise<PipelineStepData<Out>>;
+}
+
+export interface PipelineStepBuilder {
+	create(options?: PipelineStepOptions): Promise<PipelineStep>;
+}
+
+export class DefaultPipelineStepBuilder implements PipelineStepBuilder {
+	public constructor(protected readonly step: PipelineStepType) {
+	}
+
+	public async create(options?: PipelineStepOptions): Promise<PipelineStep> {
+		return new this.step(options);
+	}
+}
+