@rainbow-o23/n3 0.1.1

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

@@ -0,0 +1,65 @@
+import {
+	Pipeline,
+	PipelineBuilder,
+	PipelineCode,
+	PipelineOptions,
+	PipelineRepository,
+	PipelineStepData,
+	PipelineStepOptions,
+	PipelineStepPayload,
+	UncatchableError
+} from '@rainbow-o23/n1';
+import {ERR_PIPELINE_REF_NOT_EMPTY, ERR_PIPELINE_REF_NOT_FOUND} from '../error-codes';
+import {AbstractFragmentaryPipelineStep, FragmentaryPipelineStepOptions} from './abstract-fragmentary-pipeline-step';
+
+export interface RefPipelinePipelineStepOptions<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends FragmentaryPipelineStepOptions<In, Out, InFragment, OutFragment> {
+	code: PipelineCode;
+}
+
+export class RefPipelinePipelineStep<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends AbstractFragmentaryPipelineStep<In, Out, InFragment, OutFragment> {
+	private readonly _code: PipelineCode;
+	private readonly _pipelineBuilder: PipelineBuilder;
+
+	public constructor(options: RefPipelinePipelineStepOptions<In, Out, InFragment, OutFragment>) {
+		super(options);
+		if (options.code == null || options.code.trim().length === 0) {
+			throw new UncatchableError(ERR_PIPELINE_REF_NOT_EMPTY, `Reference pipeline code cannot be empty.`);
+		}
+		this._code = options.code;
+		this._pipelineBuilder = {
+			create: async (options?: PipelineOptions): Promise<Pipeline> => {
+				const pipeline = await PipelineRepository.findPipeline(this.getCode(), options ?? this.buildPipelineOptions());
+				if (pipeline == null) {
+					throw new UncatchableError(ERR_PIPELINE_REF_NOT_FOUND, `Reference pipeline builder[${this.getCode()}] not found.`);
+				}
+				return pipeline;
+			}
+		};
+	}
+
+	public getCode(): PipelineCode {
+		return this._code;
+	}
+
+	protected getPipelineBuilder(): PipelineBuilder {
+		return this._pipelineBuilder;
+	}
+
+	protected buildPipelineOptions(): PipelineOptions {
+		return {config: this.getConfig(), logger: this.getLogger()};
+	}
+
+	protected buildStepOptions(): Pick<PipelineStepOptions, 'config' | 'logger'> {
+		return {config: this.getConfig(), logger: this.getLogger()};
+	}
+
+	protected async doPerform(data: InFragment, request: PipelineStepData<In>): Promise<OutFragment> {
+		const {$context: {traceId} = {}} = request;
+		const pipeline = await this.getPipelineBuilder().create(this.buildPipelineOptions());
+		const result = await pipeline.perform({payload: data, traceId});
+		// const result = await step.perform({content: data, $context: request.$context});
+		return result.payload;
+	}
+}

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

@@ -0,0 +1,59 @@
+import {
+	PipelineRepository,
+	PipelineStep,
+	PipelineStepBuilder,
+	PipelineStepCode,
+	PipelineStepData,
+	PipelineStepOptions,
+	PipelineStepPayload,
+	UncatchableError
+} from '@rainbow-o23/n1';
+import {ERR_PIPELINE_STEP_REF_NOT_EMPTY, ERR_PIPELINE_STEP_REF_NOT_FOUND} from '../error-codes';
+import {AbstractFragmentaryPipelineStep, FragmentaryPipelineStepOptions} from './abstract-fragmentary-pipeline-step';
+
+export interface RefStepPipelineStepOptions<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends FragmentaryPipelineStepOptions<In, Out, InFragment, OutFragment> {
+	code: PipelineStepCode;
+}
+
+export class RefStepPipelineStep<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends AbstractFragmentaryPipelineStep<In, Out, InFragment, OutFragment> {
+	private readonly _code: PipelineStepCode;
+	private readonly _stepBuilder: PipelineStepBuilder;
+
+	public constructor(options: RefStepPipelineStepOptions<In, Out, InFragment, OutFragment>) {
+		super(options);
+		if (options.code == null || options.code.trim().length === 0) {
+			throw new UncatchableError(ERR_PIPELINE_STEP_REF_NOT_EMPTY, `Reference step code cannot be empty.`);
+		}
+		this._code = options.code;
+		this._stepBuilder = {
+			create: async (options?: PipelineStepOptions): Promise<PipelineStep> => {
+				const builder = await PipelineRepository.findStep(this.getCode());
+				if (builder == null) {
+					throw new UncatchableError(ERR_PIPELINE_STEP_REF_NOT_FOUND, `Reference step builder[${this.getCode()}] not found.`);
+				}
+				return builder.create(options);
+			}
+		};
+	}
+
+	public getCode(): PipelineStepCode {
+		return this._code;
+	}
+
+	protected getStepBuilder(): PipelineStepBuilder {
+		return this._stepBuilder;
+	}
+
+	protected buildStepOptions(): Pick<PipelineStepOptions, 'config' | 'logger'> {
+		return {config: this.getConfig(), logger: this.getLogger()};
+	}
+
+	protected async doPerform(data: InFragment, request: PipelineStepData<In>): Promise<OutFragment> {
+		const builder = this.getStepBuilder();
+		const step = await builder.create(this.buildStepOptions());
+		const result = await step.perform({content: data, $context: request.$context});
+		return result.content;
+	}
+}

package/src/lib/step/routes-step-sets.ts

@@ -0,0 +1,147 @@
+import {
+	PipelineStepBuilder,
+	PipelineStepData,
+	PipelineStepOptions,
+	PipelineStepPayload,
+	UncatchableError,
+	Undefinable
+} from '@rainbow-o23/n1';
+import {ERR_PIPELINE_STEP_CONDITIONAL_SNIPPET_NOT_EMPTY, ERR_PIPELINE_STEP_METHOD_NOT_SUPPORTED} from '../error-codes';
+import {AbstractFragmentaryPipelineStep, FragmentaryPipelineStepOptions} from './abstract-fragmentary-pipeline-step';
+import {
+	ConditionCheckFunc,
+	ConditionCheckWithInFragment,
+	ConditionCheckWithoutInFragment
+} from './conditional-step-sets';
+import {PipelineStepSets} from './step-sets';
+import {ScriptFuncOrBody} from './types';
+import {Utils} from './utils';
+
+export interface RoutesConditionalStepOptions<InFragment> {
+	check: ScriptFuncOrBody<ConditionCheckFunc<InFragment>>,
+	steps?: Array<PipelineStepBuilder>;
+}
+
+export interface RoutesPipelineStepSetsOptions<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends FragmentaryPipelineStepOptions<In, Out, InFragment, OutFragment> {
+	conditionalSteps: Array<RoutesConditionalStepOptions<InFragment>>;
+	otherwiseSteps?: Array<PipelineStepBuilder>;
+}
+
+export interface RoutesConditionalStep<InFragment> {
+	check: ConditionCheckFunc<InFragment>;
+	steps: Array<PipelineStepBuilder>;
+}
+
+/**
+ * pipeline steps to execute routes of steps, only one route will be executed
+ */
+export class RoutesPipelineStepSets<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends AbstractFragmentaryPipelineStep<In, Out, InFragment, OutFragment> {
+	private readonly _conditionalStepBuilders: Array<RoutesConditionalStep<InFragment>>;
+	private readonly _otherwiseStepBuilders: Undefinable<Array<PipelineStepBuilder>>;
+
+	constructor(options: RoutesPipelineStepSetsOptions<In, Out, InFragment, OutFragment>) {
+		super(options);
+		this._conditionalStepBuilders = (options.conditionalSteps || []).map(({check, steps}, stepIndex) => {
+			return {
+				check: Utils.createAsyncFunction(check, {
+					createDefault: (): never => {
+						throw new UncatchableError(ERR_PIPELINE_STEP_CONDITIONAL_SNIPPET_NOT_EMPTY, 'Cannot create perform func on empty conditional snippet.');
+					},
+					getVariableNames: () => this.generateVariableNames(),
+					error: (e: Error) => {
+						this.getLogger().error(`Failed on create function for route check[${stepIndex + 1}], snippet is [${check}].`);
+						throw e;
+					}
+				}),
+				steps
+			};
+		});
+		this._otherwiseStepBuilders = options.otherwiseSteps;
+	}
+
+	protected getConditionalStepBuilders(): Array<RoutesConditionalStep<InFragment>> {
+		return this._conditionalStepBuilders;
+	}
+
+	protected getOtherwiseStepBuilders(): Undefinable<Array<PipelineStepBuilder>> {
+		return this._otherwiseStepBuilders;
+	}
+
+	protected buildStepOptions(): Pick<PipelineStepOptions, 'config' | 'logger'> {
+		return {config: this.getConfig(), logger: this.getLogger()};
+	}
+
+	protected generateVariableNames(): Array<string> {
+		return [
+			this.isInFragmentIgnored() ? null : this.getInFragmentVariableName(),
+			...this.getHelpersVariableNames()
+		].filter(x => x != null);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	protected async check(func: ConditionCheckFunc<InFragment>, data: InFragment, _request: PipelineStepData<In>): Promise<boolean> {
+		const $helpers = this.getHelpers();
+		if (this.isInFragmentIgnored()) {
+			return await (func as ConditionCheckWithoutInFragment)($helpers, $helpers);
+		} else {
+			return await (func as ConditionCheckWithInFragment<InFragment>)(data, $helpers, $helpers);
+		}
+	}
+
+	/**
+	 * not used, throw error
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	protected async doPerform(data: InFragment, request: PipelineStepData<In>): Promise<OutFragment> {
+		throw new UncatchableError(ERR_PIPELINE_STEP_METHOD_NOT_SUPPORTED, `Method[${RoutesPipelineStepSets.name}.doPerform] not supported.`);
+	}
+
+	public async perform(request: PipelineStepData<In>): Promise<PipelineStepData<Out>> {
+		return await this.performAndCatch(request, async (fragment) => {
+			const conditionalStepBuilders = this.getConditionalStepBuilders();
+			if (conditionalStepBuilders != null && conditionalStepBuilders.length !== 0) {
+				for (const conditionalStepBuilder of conditionalStepBuilders) {
+					const {check, steps} = conditionalStepBuilder;
+					const checked = await this.check(check, fragment, request);
+					if (checked) {
+						const sets = new PipelineStepSets({
+							...this.buildStepOptions(), name: this.getName(), steps
+						});
+						const result = await sets.perform(request);
+						return this.setToOutput(result.content, request);
+					}
+				}
+			}
+			// noinspection DuplicatedCode
+			const otherwiseStepBuilders = this.getOtherwiseStepBuilders();
+			if (otherwiseStepBuilders != null) {
+				// no conditional step performed
+				const sets = new PipelineStepSets({
+					...this.buildStepOptions(), name: this.getName(), steps: otherwiseStepBuilders
+				});
+				const result = await sets.perform(request);
+				return this.setToOutput(result.content, request);
+			} else {
+				// otherwise route not declared
+				return request as unknown as PipelineStepData<Out>;
+			}
+		});
+	}
+
+	/**
+	 * is request step data ignored to snippet function.
+	 * default returns false
+	 */
+	protected isInFragmentIgnored(): boolean {
+		return false;
+	}
+
+	/**
+	 * override this method when want to use another variable name rather than "$factor"
+	 */
+	protected getInFragmentVariableName(): string {
+		return '$factor';
+	}
+}

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

@@ -0,0 +1,80 @@
+import {PipelineStepData, PipelineStepHelpers, PipelineStepPayload, UncatchableError} from '@rainbow-o23/n1';
+import {ERR_PIPELINE_STEP_SNIPPET_NOT_EMPTY} from '../error-codes';
+import {AbstractFragmentaryPipelineStep, FragmentaryPipelineStepOptions} from './abstract-fragmentary-pipeline-step';
+import {ScriptFuncOrBody} from './types';
+import {Utils} from './utils';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PerformWithInFragment<InFragment, OutFragment> = ($factor: InFragment, $helpers: PipelineStepHelpers, $: PipelineStepHelpers) => Promise<OutFragment>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PerformWithoutInFragment<OutFragment> = ($helpers: PipelineStepHelpers, $: PipelineStepHelpers) => Promise<OutFragment>;
+export type PerformFunc<InFragment, OutFragment> =
+	PerformWithInFragment<InFragment, OutFragment> | PerformWithoutInFragment<OutFragment>;
+
+export interface SnippetPipelineStepOptions<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends FragmentaryPipelineStepOptions<In, Out, InFragment, OutFragment> {
+	snippet: ScriptFuncOrBody<PerformFunc<InFragment, OutFragment>>;
+}
+
+/**
+ * Please note this step use given snippet to create dynamic function,
+ * which means THERE MIGHT BE SECURITY CONCERN.
+ *
+ * await is supported in snippet.
+ */
+export class SnippetPipelineStep<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends AbstractFragmentaryPipelineStep<In, Out, InFragment, OutFragment> {
+	private readonly _snippet: ScriptFuncOrBody<PerformFunc<InFragment, OutFragment>>;
+	private readonly _func: PerformFunc<InFragment, OutFragment>;
+
+	public constructor(options: SnippetPipelineStepOptions<In, Out, InFragment, OutFragment>) {
+		super(options);
+		this._snippet = options.snippet;
+		this._func = Utils.createAsyncFunction(this.getSnippet(), {
+			createDefault: (): never => {
+				throw new UncatchableError(ERR_PIPELINE_STEP_SNIPPET_NOT_EMPTY, 'Cannot create perform func on empty snippet.');
+			},
+			getVariableNames: () => this.generateVariableNames(),
+			error: (e: Error) => {
+				this.getLogger().error(`Failed on create function for snippet[${this.getSnippet()}].`);
+				throw e;
+			}
+		});
+	}
+
+	public getSnippet(): ScriptFuncOrBody<PerformFunc<InFragment, OutFragment>> {
+		return this._snippet;
+	}
+
+	protected generateVariableNames(): Array<string> {
+		return [
+			this.isInFragmentIgnored() ? null : this.getInFragmentVariableName(),
+			...this.getHelpersVariableNames()
+		].filter(x => x != null);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	protected async doPerform(data: InFragment, _request: PipelineStepData<In>): Promise<OutFragment> {
+		const $helpers = this.getHelpers();
+		if (this.isInFragmentIgnored()) {
+			return await (this._func as PerformWithoutInFragment<OutFragment>)($helpers, $helpers);
+		} else {
+			return await (this._func as PerformWithInFragment<InFragment, OutFragment>)(data, $helpers, $helpers);
+		}
+	}
+
+	/**
+	 * is request step data ignored to snippet function.
+	 * default returns false
+	 */
+	protected isInFragmentIgnored(): boolean {
+		return false;
+	}
+
+	/**
+	 * override this method when want to use another variable name rather than "$factor"
+	 */
+	protected getInFragmentVariableName(): string {
+		return '$factor';
+	}
+}

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

@@ -0,0 +1,16 @@
+import {PipelineStepData, PipelineStepPayload} from '@rainbow-o23/n1';
+import {Snowflake} from '@theinternetfolks/snowflake';
+import {AbstractFragmentaryPipelineStep} from './abstract-fragmentary-pipeline-step';
+
+export type SnowflakeId = string;
+
+/**
+ * create a snowflake id as out fragment
+ */
+export class SnowflakePipelineStep<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In>
+	extends AbstractFragmentaryPipelineStep<In, Out, InFragment, SnowflakeId> {
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	protected async doPerform(_data: InFragment, _request: PipelineStepData<In>): Promise<SnowflakeId> {
+		return Snowflake.generate();
+	}
+}

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

@@ -0,0 +1,99 @@
+import {
+	PipelineStep,
+	PipelineStepBuilder,
+	PipelineStepData,
+	PipelineStepOptions,
+	PipelineStepPayload
+} from '@rainbow-o23/n1';
+import {AbstractFragmentaryPipelineStep, FragmentaryPipelineStepOptions} from './abstract-fragmentary-pipeline-step';
+import {Utils} from './utils';
+
+export interface PipelineStepSetsContext {
+}
+
+export interface PipelineStepSetsOptions<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends FragmentaryPipelineStepOptions<In, Out, InFragment, OutFragment> {
+	steps: Array<PipelineStepBuilder>;
+}
+
+/**
+ * pipeline steps to execute sets of steps. it will build a context for sub steps.
+ */
+export class PipelineStepSets<In = PipelineStepPayload, Out = PipelineStepPayload, InFragment = In, OutFragment = Out>
+	extends AbstractFragmentaryPipelineStep<In, Out, InFragment, OutFragment> {
+	private readonly _stepBuilders: Array<PipelineStepBuilder>;
+
+	// noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected
+	public constructor(options: PipelineStepSetsOptions<In, Out, InFragment, OutFragment>) {
+		super(options);
+		this._stepBuilders = options.steps;
+	}
+
+	protected getStepBuilders(): Array<PipelineStepBuilder> {
+		return this._stepBuilders ?? [];
+	}
+
+	protected buildStepOptions(): Pick<PipelineStepOptions, 'config' | 'logger'> {
+		return {config: this.getConfig(), logger: this.getLogger()};
+	}
+
+	/**
+	 * 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)));
+	}
+
+	protected inheritContext(request: PipelineStepData<In>): PipelineStepSetsContext {
+		const context = request.$context;
+		if (context == null) {
+			return {};
+		} else {
+			return Utils.clone(context);
+		}
+	}
+
+	/**
+	 * default do nothing, return given inherited context directly
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	protected async attachMineToInternalContext(inheritedContext: PipelineStepSetsContext, _request: PipelineStepData<In>): Promise<PipelineStepSetsContext> {
+		return inheritedContext;
+	}
+
+	protected async createInternalContext<Ctx extends PipelineStepSetsContext>(request: PipelineStepData<In>): Promise<Ctx> {
+		return await this.attachMineToInternalContext(this.inheritContext(request), request) as Ctx;
+	}
+
+	/**
+	 * to create an internal context which should be mounted on the step data
+	 */
+	protected async performWithContext(
+		request: PipelineStepData<In>,
+		run: (request: PipelineStepData<In>, context: PipelineStepSetsContext) => Promise<OutFragment>): Promise<OutFragment> {
+		const context = await this.createInternalContext(request);
+		return await run(request, context);
+	}
+
+	protected async doPerform(data: InFragment, request: PipelineStepData<In>): Promise<OutFragment> {
+		return await this.performWithContext(
+			request, async (request: PipelineStepData<In>, context: PipelineStepSetsContext): Promise<OutFragment> => {
+				const {$context: {traceId} = {}} = request;
+				const steps = await this.createSteps();
+				const response = await steps.reduce(async (promise, step) => {
+					const request = await promise;
+					return await this.measurePerformance(traceId, 'STEP')
+						.execute(async () => {
+							this.traceStepOut(traceId, step, request);
+							const response = await step.perform({...request, $context: {...context, traceId}});
+							this.traceStepOut(traceId, step, response);
+							// if no response returned, keep using request for next
+							return this.returnOrContinueOrClear(request, response);
+						});
+					// build request for first step
+				}, Promise.resolve({content: data, $context: request.$context}));
+				return response.content;
+			});
+	}
+}

package/src/lib/step/types.ts

@@ -0,0 +1,23 @@
+import {
+	CatchableError,
+	ExposedUncatchableError,
+	PipelineStepData,
+	PipelineStepHelpers,
+	UncatchableError
+} from '@rainbow-o23/n1';
+
+export type ScriptFunctionBody = string;
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type ScriptFuncOrBody<F = Function> = F | ScriptFunctionBody;
+
+export interface ErrorHandleOptions<In, InFragment, E extends Error = Error> {
+	$code: string;
+	$error: E;
+	$factor: InFragment;
+	$request: PipelineStepData<In>;
+}
+
+export type HandleCatchableError<In, InFragment, OutFragment> = ($options: ErrorHandleOptions<In, InFragment, CatchableError>, $helpers: PipelineStepHelpers, $: PipelineStepHelpers) => Promise<OutFragment> | never;
+export type HandleUncatchableError<In, InFragment, OutFragment> = ($options: ErrorHandleOptions<In, InFragment, UncatchableError>, $helpers: PipelineStepHelpers, $: PipelineStepHelpers) => Promise<OutFragment> | never;
+export type HandleExposedUncatchableError<In, InFragment, OutFragment> = ($options: ErrorHandleOptions<In, InFragment, ExposedUncatchableError>, $helpers: PipelineStepHelpers, $: PipelineStepHelpers) => Promise<OutFragment> | never;
+export type HandleAnyError<In, InFragment, OutFragment> = ($options: ErrorHandleOptions<In, InFragment>, $helpers: PipelineStepHelpers, $: PipelineStepHelpers) => Promise<OutFragment> | never;

package/src/lib/step/utils.ts

@@ -0,0 +1,109 @@
+import {Nullable, Undefinable} from '@rainbow-o23/n1';
+import {ScriptFuncOrBody} from './types';
+
+// get async function constructor, to create the dynamic function
+const AsyncFunction = Object.getPrototypeOf(async function () {
+	// nothing, since this purpose is get the constructor, body is not concerned
+}).constructor;
+
+export class Utils {
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	public static createFunction<F = Function>(snippet: ScriptFuncOrBody<F>, creators: {
+		createDefault: () => Undefinable<F> | never;
+		getVariableNames: () => Array<string>;
+		async?: true;
+		error: (e: Error) => never;
+	}): F {
+		try {
+			if (snippet == null || (typeof snippet === 'string' && snippet.trim().length === 0)) {
+				return creators.createDefault();
+			} else if (typeof snippet === 'string') {
+				const F = creators.async ? AsyncFunction : Function;
+				return new F(...creators.getVariableNames(), snippet) as F;
+			} else {
+				return snippet;
+			}
+		} catch (e) {
+			creators.error(e);
+		}
+	}
+
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	public static createSyncFunction<F = Function>(snippet: ScriptFuncOrBody<F>, creators: {
+		createDefault: () => Undefinable<F> | never;
+		getVariableNames: () => Array<string>;
+		error: (e: Error) => never;
+	}): F {
+		return Utils.createFunction(snippet, {...creators});
+	}
+
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	public static createAsyncFunction<F = Function>(snippet: ScriptFuncOrBody<F>, creators: {
+		createDefault: () => Undefinable<F> | never;
+		getVariableNames: () => Array<string>;
+		error: (e: Error) => never;
+	}): F {
+		return Utils.createFunction(snippet, {...creators, async: true});
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static isPrimitive(value: any): value is string | number | boolean | symbol | bigint {
+		return value != null && ['string', 'number', 'boolean', 'symbol', 'bigint'].includes(typeof value);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static getValue<V>(model: any, propertyPath: string): Nullable<V> {
+		if (model == null) {
+			return null;
+		}
+		if (propertyPath == null || propertyPath.trim() === '.' || propertyPath.trim() === '.') {
+			// returns parent itself if property points me
+			return model;
+		}
+
+		const segments = propertyPath.split('.');
+
+		return segments.reduce((fromModel, segment) => {
+			if (fromModel == null) {
+				// cannot know what the accurate type of parent, return null anyway.
+				return null;
+			}
+			if (Utils.isPrimitive(fromModel)) {
+				// cannot get property from primitive value, raise exception here
+				return null;
+			}
+
+			if (Array.isArray(fromModel)) {
+				// get values from every item and merge into one array
+				return fromModel.map(item => {
+					if (item == null) {
+						return null;
+					}
+					if (Utils.isPrimitive(item)) {
+						return null;
+					}
+					return item[segment];
+				});
+			} else {
+				// get value from model directly
+				return fromModel[segment];
+			}
+		}, model);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public static clone(obj: any): any {
+		if (obj == null) {
+			return obj;
+		} else if (Array.isArray(obj)) {
+			return obj.map(item => Utils.clone(item));
+		} else if (typeof obj === 'object') {
+			return Object.keys(obj).reduce((cloned: object, key: string) => {
+				cloned[key] = Utils.clone(obj[key]);
+				return cloned;
+			}, {});
+		} else {
+			return obj;
+		}
+	}
+}

package/src/lib/typeorm/abstract-datasource.ts

@@ -0,0 +1,58 @@
+import {Config} from '@rainbow-o23/n1';
+import {DataSource, DataSourceOptions} from 'typeorm';
+
+export interface TypeOrmDataSource {
+	getName(): string;
+
+	shouldKeptOnGlobal(): boolean;
+
+	getDataSource(): DataSource;
+
+	initialize(config: Config, entities: DataSourceOptions['entities']): Promise<DataSource>;
+
+	destroy(): Promise<void>;
+}
+
+export abstract class AbstractTypeOrmDataSource<O extends DataSourceOptions> implements TypeOrmDataSource {
+	private _initialized = false;
+	private _dataSource: DataSource;
+
+	// noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected
+	public constructor(private readonly _name: string) {
+	}
+
+	public getName(): string {
+		return this._name;
+	}
+
+	public isInitialized(): boolean {
+		return this._initialized;
+	}
+
+	public getDataSource(): DataSource {
+		return this._dataSource;
+	}
+
+	/**
+	 * default true
+	 */
+	public shouldKeptOnGlobal(): boolean {
+		return true;
+	}
+
+	protected abstract createOptions(config: Config): O;
+
+	public async initialize(config: Config, entities: DataSourceOptions['entities']): Promise<DataSource> {
+		if (this.isInitialized()) {
+			return this._dataSource;
+		}
+
+		this._dataSource = new DataSource({...this.createOptions(config), entities});
+		this._dataSource = await this._dataSource.initialize();
+		return this._dataSource;
+	}
+
+	public async destroy(): Promise<void> {
+		return await this._dataSource.destroy();
+	}
+}