@adaas/a-utils 0.0.9 → 0.1.1

package/src/lib/A-Command/A-Command.constants.ts

@@ -0,0 +1,31 @@
+export enum A_TYPES__CommandMetaKey {
+    EXTENSIONS = 'a-command-extensions',
+    FEATURES = 'a-command-features',
+    ABSTRACTIONS = 'a-command-abstractions',
+}
+
+export enum A_CONSTANTS__A_Command_Status {
+    INITIALIZED = 'INITIALIZED',
+    IN_PROGRESS = 'IN_PROGRESS',
+    COMPLETED = 'COMPLETED',
+    FAILED = 'FAILED',
+}
+
+/**
+ * A-Command Lifecycle Features
+ */
+export enum A_CONSTANTS_A_Command_Features {
+    INIT = 'init',
+    COMPLIED = 'complied',
+    EXECUTE = 'execute',
+    COMPLETE = 'complete',
+    FAIL = 'fail',
+}
+
+
+
+
+export type A_CONSTANTS__A_Command_Event = 'init' | 'compile' | 'execute' | 'complete' | 'fail';
+
+
+

package/src/lib/A-Command/A-Command.entity.ts

@@ -0,0 +1,327 @@
+import {
+    A_TYPES__Command_Init,
+    A_TYPES__Command_Listener,
+    A_TYPES__Command_Serialized
+} from "./A-Command.types";
+import {
+    A_CONSTANTS__A_Command_Event,
+    A_CONSTANTS__A_Command_Status
+} from "./A-Command.constants";
+import { A_Context, A_Entity, A_Error, A_Scope } from "@adaas/a-concept";
+import { A_Memory } from "../A-Memory/A-Memory.context";
+
+
+export class A_Command<
+    InvokeType extends A_TYPES__Command_Init = A_TYPES__Command_Init,
+    ResultType extends Record<string, any> = Record<string, any>,
+    LifecycleEvents extends string = A_CONSTANTS__A_Command_Event
+> extends A_Entity<InvokeType, A_TYPES__Command_Serialized<ResultType>> {
+
+    // ====================================================================
+    // ================== Static A-Command Information ====================
+    // ====================================================================
+
+    /**
+     * Command Identifier that corresponds to the class name
+     */
+    static get code(): string {
+        return super.entity;
+    }
+
+    // ====================================================================
+    // ================ Instance A-Command Information ====================
+    // ====================================================================
+    protected _result?: ResultType;
+    protected _executionScope!: A_Scope;
+    protected _errors?: Set<A_Error>;
+
+    protected _params!: InvokeType;
+    protected _status!: A_CONSTANTS__A_Command_Status
+
+    protected _listeners: Map<
+        // the name of the event
+        LifecycleEvents | A_CONSTANTS__A_Command_Event,
+        // the listeners for the event
+        Set<A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>>
+    > = new Map();
+
+    protected _startTime?: Date;
+    protected _endTime?: Date
+
+    /**
+     * Execution Duration in milliseconds
+     */
+    get duration() {
+        return this._endTime && this._startTime
+            ? this._endTime.getTime() - this._startTime.getTime()
+            : this._startTime
+                ? new Date().getTime() - this._startTime.getTime()
+                : undefined;
+    }
+    /**
+     * A shared scope between all features of the command during its execution
+     */
+    get scope(): A_Scope {
+        return this._executionScope;
+    }
+    /**
+     * Unique code identifying the command type
+     * Example: 'user.create', 'task.complete', etc.
+     * 
+     */
+    get code(): string {
+        return (this.constructor as typeof A_Command).code;
+    }
+    /**
+     * Current status of the command
+     */
+    get status(): A_CONSTANTS__A_Command_Status {
+        return this._status;
+    }
+    /**
+     * Start time of the command execution
+     */
+    get startedAt(): Date | undefined {
+        return this._startTime;
+    }
+    /**
+     * End time of the command execution
+     */
+    get endedAt(): Date | undefined {
+        return this._endTime;
+    }
+    /**
+     * Result of the command execution stored in the context
+     */
+    get result(): ResultType | undefined {
+        return this._result;
+    }
+    /**
+     * Errors encountered during the command execution stored in the context
+     */
+    get errors(): Set<A_Error> | undefined {
+        return this._errors;
+    }
+    /**
+     * Parameters used to invoke the command
+     */
+    get params(): InvokeType {
+        return this._params;
+    }
+    /**
+     * Indicates if the command has failed
+     */
+    get isFailed(): boolean {
+        return this._status === A_CONSTANTS__A_Command_Status.FAILED;
+    }
+    /**
+     * Indicates if the command has completed successfully
+     */
+    get isCompleted(): boolean {
+        return this._status === A_CONSTANTS__A_Command_Status.COMPLETED;
+    }
+
+    /**
+     * 
+     * A-Command represents an executable command with a specific code and parameters.
+     * It can be executed within a given scope and stores execution results and errors.
+     * 
+     * 
+     * A-Command should be context independent and execution logic should be based on attached components 
+     * 
+     * @param code 
+     * @param params 
+     */
+    constructor(
+        /**
+         * Command invocation parameters
+         */
+        params: InvokeType | A_TYPES__Command_Serialized<ResultType> | string
+    ) {
+        super(params as any)
+    }
+
+
+    // --------------------------------------------------------------------------
+    // A-Command Lifecycle Methods
+    // --------------------------------------------------------------------------
+
+    // should create a new Task in DB  with basic records
+    async init(): Promise<void> {
+        this._status = A_CONSTANTS__A_Command_Status.IN_PROGRESS;
+        this._startTime = new Date();
+        if (!this.scope.isInheritedFrom(A_Context.scope(this))) {
+            this.scope.inherit(A_Context.scope(this));
+        }
+
+
+        this.emit('init');
+        return await this.call('init', this.scope);
+    }
+
+    // Should compile everything before execution
+    async compile() {
+        this.emit('compile');
+        return await this.call('compile', this.scope);
+    }
+
+    /**
+     * Executes the command logic.
+     */
+    async execute(): Promise<any> {
+        try {
+            await this.init();
+            await this.compile();
+            this.emit('execute');
+            await this.call('execute', this.scope);
+            await this.complete();
+
+        } catch (error) {
+            await this.fail();
+        }
+    }
+
+    /**
+     * Marks the command as completed
+     */
+    async complete() {
+        this._status = A_CONSTANTS__A_Command_Status.COMPLETED;
+        this._endTime = new Date();
+        this._result = this.scope.resolve(A_Memory).toJSON() as ResultType;
+
+        this.emit('complete');
+        return await this.call('complete', this.scope);
+    }
+
+
+    /**
+     * Marks the command as failed
+     */
+    async fail() {
+        this._status = A_CONSTANTS__A_Command_Status.FAILED;
+        this._endTime = new Date();
+        this._errors = this.scope.resolve(A_Memory).Errors;
+
+        this.emit('fail');
+        return await this.call('fail', this.scope);
+    }
+
+
+    // --------------------------------------------------------------------------   
+    // A-Command Event-Emitter methods
+    // --------------------------------------------------------------------------
+
+    /**
+     * Registers an event listener for a specific event
+     * 
+     * @param event 
+     * @param listener 
+     */
+    on(event: LifecycleEvents | A_CONSTANTS__A_Command_Event, listener: A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>) {
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set());
+        }
+        this._listeners.get(event)!.add(listener);
+    }
+    /**
+     * Removes an event listener for a specific event
+     * 
+     * @param event 
+     * @param listener 
+     */
+    off(event: LifecycleEvents | A_CONSTANTS__A_Command_Event, listener: A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>) {
+        this._listeners.get(event)?.delete(listener);
+    }
+    /**
+     * Emits an event to all registered listeners
+     * 
+     * @param event 
+     */
+    emit(event: LifecycleEvents | A_CONSTANTS__A_Command_Event) {
+        this._listeners.get(event)?.forEach(listener => {
+            listener(this);
+        });
+    }
+
+
+    // --------------------------------------------------------------------------
+    // A-Entity Base Class Overrides
+    // --------------------------------------------------------------------------
+    // Serialization / Deserialization
+    // -------------------------------------------------------------------------
+
+
+    /**
+     * Allows to create a Command instance from new data
+     * 
+     * @param newEntity 
+     */
+    fromNew(newEntity: InvokeType): void {
+        super.fromNew(newEntity);
+
+        this._executionScope = new A_Scope();
+
+        this._executionScope.register(new A_Memory<ResultType>());
+
+        this._params = newEntity;
+
+        this._status = A_CONSTANTS__A_Command_Status.INITIALIZED;
+    }
+
+
+
+    /**
+     * Allows to convert serialized data to Command instance
+     * 
+     * [!] By default it omits params as they are not stored in the serialized data
+     * 
+     * @param serialized 
+     */
+    fromJSON(serialized: A_TYPES__Command_Serialized<ResultType>): void {
+        super.fromJSON(serialized);
+
+        this._executionScope = new A_Scope();
+
+        const memory = new A_Memory<ResultType>();
+
+        this._executionScope.register(memory);
+
+        if (serialized.startedAt) this._startTime = new Date(serialized.startedAt);
+        if (serialized.endedAt) this._endTime = new Date(serialized.endedAt);
+
+
+        // Restore result and errors in the memory
+        if (serialized.result) {
+            Object.entries(serialized.result).forEach(([key, value]) => {
+                memory.set(key, value);
+            });
+        }
+
+        if (serialized.errors) {
+            serialized.errors.forEach(err => {
+                memory.error(new A_Error(err));
+            });
+        }
+
+        this._status = serialized.status || A_CONSTANTS__A_Command_Status.INITIALIZED;
+    }
+
+
+    /**
+     * Converts the Command instance to a plain object
+     * 
+     * @returns 
+     */
+    toJSON(): A_TYPES__Command_Serialized<ResultType> {
+        return {
+            ...super.toJSON(),
+            code: this.code,
+            status: this._status,
+            startedAt: this._startTime ? this._startTime.toISOString() : undefined,
+            endedAt: this._endTime ? this._endTime.toISOString() : undefined,
+            duration: this.duration,
+            result: this.result,
+            errors: this.errors ? Array.from(this.errors).map(err => err.toJSON()) : undefined
+        }
+    };
+}

package/src/lib/A-Command/A-Command.error.ts

@@ -0,0 +1,6 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_CommandError extends A_Error {
+
+}

package/src/lib/A-Command/A-Command.types.ts

@@ -0,0 +1,100 @@
+import { A_Command } from "./A-Command.entity";
+import { A_CONSTANTS__A_Command_Event, A_CONSTANTS__A_Command_Status, A_TYPES__CommandMetaKey } from "./A-Command.constants";
+import { A_Meta, A_TYPES__Entity_Serialized, A_TYPES__Error_Serialized, A_TYPES__FeatureDefineDecoratorMeta, A_TYPES__FeatureExtendDecoratorMeta } from "@adaas/a-concept";
+
+
+
+// ============================================================================
+// --------------------------- Primary Types ----------------------------------
+// ============================================================================
+/**
+ * Command constructor type
+ * Uses the generic type T to specify the type of the entity
+ */
+export type A_TYPES__Command_Constructor<T = A_Command> = new (...args: any[]) => T;
+/**
+ * Command initialization type
+ */
+export type A_TYPES__Command_Init = any;
+/**
+ * Command serialized type
+ */
+export type A_TYPES__Command_Serialized<
+    ResultType extends Record<string, any> = Record<string, any>
+> = {
+    /**
+     * Unique code of the command
+     */
+    code: string;
+    /**
+     * Current status of the command
+     */
+    status: A_CONSTANTS__A_Command_Status;
+    // --------------------------------------------------
+    /**
+     * The time when the command was created
+     */
+    startedAt?: string;
+    /**
+     * The time when the command execution ended
+     */
+    endedAt?: string;
+    /**
+     * Duration of the command execution in milliseconds
+     */
+    duration?: number;
+    // --------------------------------------------------
+    /**
+     * Result of the command execution
+     */
+    result?: ResultType;
+    /**
+     * List of errors occurred during the command execution
+     */
+    errors?: Array<A_TYPES__Error_Serialized>;
+} & A_TYPES__Entity_Serialized
+
+// ============================================================================
+// ---------------------------- Common Types ----------------------------------
+// ============================================================================
+/**
+ * Command listener type
+ */
+export type A_TYPES__Command_Listener<
+    InvokeType extends A_TYPES__Command_Init = A_TYPES__Command_Init,
+    ResultType extends Record<string, any> = Record<string, any>,
+    LifecycleEvents extends string = A_CONSTANTS__A_Command_Event
+> = (command?: A_Command<InvokeType, ResultType, LifecycleEvents>) => void;
+
+
+// ============================================================================
+// --------------------------- Meta Types -------------------------------------
+// ============================================================================
+/**
+ * Command meta type
+ */
+export type A_TYPES__CommandMeta = {
+    [A_TYPES__CommandMetaKey.EXTENSIONS]: A_Meta<{
+
+        /**
+         * Where Key the regexp for what to apply the extension
+         * A set of container names or a wildcard, or a regexp
+         * 
+         *
+         * Where value is the extension instructions
+         */
+        [Key: string]: A_TYPES__FeatureExtendDecoratorMeta[]
+
+    }>, case
+
+
+    [A_TYPES__CommandMetaKey.FEATURES]: A_Meta<{
+        /**
+         * Where Key is the name of the feature
+         * 
+         * Where value is the list of features
+         */
+        [Key: string]: A_TYPES__FeatureDefineDecoratorMeta
+    }>
+}
+

package/src/lib/A-Config/A-Config.constants.ts

@@ -0,0 +1,13 @@
+export const A_CONSTANTS__CONFIG_ENV_VARIABLES = {
+
+} as const
+
+
+//should be an array
+export type A_TYPES__ConfigENVVariables = (typeof A_CONSTANTS__CONFIG_ENV_VARIABLES)[keyof typeof A_CONSTANTS__CONFIG_ENV_VARIABLES][];
+
+
+export const A_CONSTANTS__CONFIG_ENV_VARIABLES_ARRAY = [
+
+] as const;
+

package/src/lib/A-Config/A-Config.container.ts

@@ -0,0 +1,63 @@
+import { A_Concept, A_Container, A_Context, A_Inject, A_ScopeError } from "@adaas/a-concept";
+import { ConfigReader } from "./components/ConfigReader.component";
+import { A_Config } from "./A-Config.context";
+import { A_Polyfill } from "../A-Polyfill/A-Polyfill.component";
+import { A_ConfigError } from "./A-Config.error";
+import { FileConfigReader } from "./components/FileConfigReader.component";
+import { ENVConfigReader } from "./components/ENVConfigReader.component";
+
+
+export class A_ConfigLoader extends A_Container {
+
+    private reader!: ConfigReader
+
+
+    @A_Concept.Load()
+    async prepare(
+        @A_Inject(A_Polyfill) polyfill: A_Polyfill,
+    ) {
+        const fs = await polyfill.fs();
+
+        try {
+            switch (true) {
+
+                case A_Context.environment === 'server' && !!fs.existsSync(`${A_Context.concept}.conf.json`):
+                    this.reader = this.scope.resolve<ConfigReader>(FileConfigReader);
+                    break;
+
+                case A_Context.environment === 'server' && !fs.existsSync(`${A_Context.concept}.conf.json`):
+                    this.reader = this.scope.resolve<ConfigReader>(ENVConfigReader);
+                    break;
+
+                case A_Context.environment === 'browser':
+                    this.reader = this.scope.resolve<ConfigReader>(ENVConfigReader);
+                    break;
+
+                default:
+                    throw new A_ConfigError(
+                        A_ConfigError.InitializationError,
+                        `Environment ${A_Context.environment} is not supported`
+                    );
+            }
+        } catch (error) {
+            if (error instanceof A_ScopeError) {
+                throw new A_ConfigError({
+                    title: A_ConfigError.InitializationError,
+                    description: `Failed to initialize A_ConfigLoader. Reader not found for environment ${A_Context.environment}`,
+                    originalError: error,
+                })
+            }
+        }
+
+    }
+
+
+    @A_Concept.Load({
+        after: ['A_ConfigLoader.prepare']
+    })
+    async readVariables(
+        @A_Inject(A_Config) config: A_Config,
+    ) {
+        await this.reader.inject(config);
+    }
+}

package/src/lib/A-Config/A-Config.context.ts

@@ -0,0 +1,117 @@
+import { A_CommonHelper, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_FormatterHelper, A_Fragment, A_TYPES__ConceptENVVariables } from "@adaas/a-concept";
+import { A_TYPES__ConfigContainerConstructor } from "./A-Config.types";
+import { A_CONSTANTS__CONFIG_ENV_VARIABLES_ARRAY } from "./A-Config.constants";
+
+
+export class A_Config<
+    T extends Array<string | A_TYPES__ConceptENVVariables[number]> = any[]
+> extends A_Fragment {
+
+    config: A_TYPES__ConfigContainerConstructor<T>;
+
+
+    private VARIABLES: Map<T[number], any> = new Map<T[number], any>();
+
+    CONFIG_PROPERTIES!: T;
+
+    protected DEFAULT_ALLOWED_TO_READ_PROPERTIES = [
+        ...A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY,
+        ...A_CONSTANTS__CONFIG_ENV_VARIABLES_ARRAY
+    ];
+
+
+    constructor(
+        config: Partial<A_TYPES__ConfigContainerConstructor<T>>
+    ) {
+        super({
+            name: 'A_Config'
+        });
+
+        this.config = A_CommonHelper.deepCloneAndMerge<A_TYPES__ConfigContainerConstructor<T>>(config as any, {
+            strict: false,
+            defaults: {},
+            variables: A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY as any as T
+        } as any);
+
+        this.CONFIG_PROPERTIES = this.config.variables ? this.config.variables : [] as any as T;
+
+        this.config.variables.forEach((variable) => {
+            this.VARIABLES.set(
+                A_FormatterHelper.toUpperSnakeCase(variable),
+                this.config.defaults[variable]
+            );
+        });
+    }
+
+
+    /** 
+     * This method is used to get the configuration property by name
+     * 
+     * @param property 
+     * @returns 
+     */
+    get<_OutType = any>(
+        property: T[number] | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]
+    ): _OutType {
+        if (this.CONFIG_PROPERTIES.includes(property as any)
+            || this.DEFAULT_ALLOWED_TO_READ_PROPERTIES.includes(property as any)
+            || !(this.config.strict)
+        )
+            return this.VARIABLES.get(A_FormatterHelper.toUpperSnakeCase(property)) as _OutType;
+
+        throw new Error('Property not exists or not allowed to read') as never;
+        // return this.concept.Errors.throw(A_SDK_CONSTANTS__ERROR_CODES.CONFIGURATION_PROPERTY_NOT_EXISTS_OR_NOT_ALLOWED_TO_READ) as never;
+    }
+
+
+
+    /**
+     * 
+     * This method is used to set the configuration property by name
+     * OR set multiple properties at once by passing an array of objects
+     * 
+     * @param variables 
+     */
+    set(
+        variables: Array<{
+            property: T[number] | A_TYPES__ConceptENVVariables[number],
+            value: any
+        }>
+    )
+    set(
+        variables: Partial<Record<T[number] | A_TYPES__ConceptENVVariables[number], any>>
+    )
+    set(
+        property: T[number] | A_TYPES__ConceptENVVariables[number],
+        value: any
+    )
+    set(
+        property: T[number] | A_TYPES__ConceptENVVariables[number] | Array<{
+            property: T[number] | A_TYPES__ConceptENVVariables[number],
+            value: any
+        }> | Partial<Record<T[number] | A_TYPES__ConceptENVVariables[number], any>>,
+        value?: any
+    ) {
+        const array = Array.isArray(property)
+            ? property
+            : typeof property === 'string'
+                ? [{ property, value }]
+                : Object
+                    .keys(property)
+                    .map((key) => ({
+                        property: key,
+                        value: property[key]
+                    }));
+
+        for (const { property, value } of array) {
+
+            let targetValue = value
+                ? value
+                : this.config?.defaults
+                    ? this.config.defaults[property as T[number]]
+                    : undefined;
+
+            this.VARIABLES.set(A_FormatterHelper.toUpperSnakeCase(property), targetValue);
+        }
+    }
+}

package/src/lib/A-Config/A-Config.error.ts

@@ -0,0 +1,7 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_ConfigError extends A_Error {
+
+    static readonly InitializationError = 'A-Config Initialization Error';
+}

package/src/lib/A-Config/A-Config.types.ts

@@ -0,0 +1,26 @@
+import { A_TYPES__ConceptENVVariables, A_TYPES__Fragment_Constructor } from "@adaas/a-concept";
+
+export enum A_TYPES__ConfigFeature {
+
+}
+
+
+export type A_TYPES__ConfigContainerConstructor<T extends  Array<string | A_TYPES__ConceptENVVariables[number]>> = {
+
+    /**
+     * If set to true, the SDK will throw an error if the variable is not defined OR not presented in the defaults
+     */
+    strict: boolean
+
+    /**
+     * Allows to define the names of variable to be loaded
+     */
+    variables: T
+
+    /**
+     * Allows to set the default values for the variables
+     */
+    defaults: {
+        [key in T[number]]?: any
+    }
+} & A_TYPES__Fragment_Constructor;