@adaas/a-concept 0.0.64 → 0.1.2

package/src/global/ASEID/ASEID.class.ts

@@ -0,0 +1,275 @@
+import {
+    A_TYPES__ASEID_Constructor,
+    A_TYPES__ASEID_JSON
+} from "./ASEID.types";
+import { A_IdentityHelper } from "@adaas/a-concept/helpers/A_Identity.helper";
+import { A_TypeGuards } from "@adaas/a-concept/helpers/A_TypeGuards.helper";
+import { A_Context } from "../A-Context/A-Context.class";
+import { ASEID_Error } from "./ASEID.error";
+import { A_TYPES__Required } from "@adaas/a-concept/types/A_Common.types";
+
+
+
+export class ASEID {
+
+
+    //==========================================================================
+    //============================= STATIC METHODS ===========================
+    //==========================================================================
+    /**
+     * ASEID Regular Expression
+     */
+    static readonly regexp: RegExp = new RegExp(`^[a-z|A-Z|0-9|-]+@[a-z|A-Z|0-9|-]+:[a-z|A-Z|0-9|-]+:[a-z|A-Z|0-9|-|\\.]+(@v[0-9|\\.]+|@lts)?$`)
+    /**
+     * Tests if the identity string is an ASEID
+     * 
+     * @param identity 
+     * @returns 
+     */
+    static isASEID(identity: string): boolean {
+        return this.regexp.test(
+            identity
+        )
+    }
+
+
+
+    // ====================================================================
+    // ==================== Hidden ASEID Information ======================
+    // ====================================================================
+    /**
+     * Concept for the ASEID
+     * Generally it is the application name or code, should correspond to the concept where the entity is used
+     * Could be ID or ASEID
+     */
+    private _concept!: string;
+    /**
+     * Entity Scope the primary location of the resource 
+     * Organization, or organization Unit
+     * Could be ID or ASEID
+     * 
+     */
+    private _scope!: string
+    /**
+     * Entity Type the type of the resource
+     */
+    private _entity!: string
+    /**
+     * Entity ID the unique identifier of the resource
+     */
+    private _id!: string
+    /**
+     * Version of the entity (optional)
+     */
+    private _version?: string
+    /**
+     * Shard of the entity (optional)
+     */
+    private _shard?: string
+
+
+
+
+
+
+    /**
+     * ASEID is a structured identifier for entities in the A-Concept system. 
+     * using the format:
+     *  A - A-Concept
+     *  S - System 
+     *  E - Entity
+     *  I - Identifier
+     *  D - iDentifier
+     * 
+     * Structure: CONCEPT_NAME + @ + SCOPE + : ENTITY_NAME + : + ID + @ + VERSION 
+     * 
+     * Example:
+     *  - root@core:usr:0000000001
+     * 
+     * [!] Concept is optional, if not provided will be used the current concept name
+     * [!] Scope is optional, if not provided will be used the root scope of the current concept
+     * [!] Version is optional, if not provided will be considered as latest version
+     * 
+     * @param aseid - ASEID string representation or ASEID components as object
+     */
+    constructor(
+        /**
+         * ASEID string representation
+         */
+        aseid: string
+    )
+    constructor(
+        /**
+         * ASEID components as object 
+         */
+        props: A_TYPES__Required<Partial<A_TYPES__ASEID_Constructor>, ['id', 'entity']>
+    )
+    constructor(param1: string | A_TYPES__Required<Partial<A_TYPES__ASEID_Constructor>, ['id', 'entity']>) {
+        this.verifyInput(param1);
+
+        const initializer = this.getInitializer(param1);
+        // the returned initializer is already bound to `this` (we used .bind(this)),
+        // so calling it will run the appropriate logic on this instance:
+        initializer.call(this, param1);
+    }
+
+    /**
+     * Getters for ASEID components
+     */
+    get concept(): string {
+        return this._concept || A_Context.concept;
+    }
+    /**
+     * Get the scope of the ASEID
+     */
+    get scope(): string {
+        return this._scope || A_Context.root.name;
+    }
+    /**
+     * Get the entity of the ASEID
+     */
+    get entity(): string {
+        return this._entity;
+    }
+    /**
+     * Get the id of the ASEID
+     */
+    get id(): string {
+        return this._id;
+    }
+    /**
+     * Get the version of the ASEID (if any)
+     */
+    get version(): string | undefined {
+        return this._version;
+    }
+    /**
+     * Get the shard of the ASEID (if any)
+     */
+    get shard(): string | undefined {
+        return this._shard;
+    }
+
+    /**
+     * get Internal Initializer based on the type of the parameter provided
+     * 
+     * @param param1 
+     * @returns 
+     */
+    private getInitializer(
+        param1: string | A_TYPES__Required<Partial<A_TYPES__ASEID_Constructor>, ['id', 'entity']>
+    ): (param1: any) => void | (() => void) {
+        switch (true) {
+            case A_TypeGuards.isString(param1):
+                return this.fromString;
+
+            case A_TypeGuards.isObject<A_TYPES__ASEID_Constructor>(param1):
+                return this.fromObject;
+
+            default:
+                throw new ASEID_Error(
+                    ASEID_Error.ASEIDInitializationError,
+                    'Invalid parameters provided to ASEID constructor'
+                );
+        }
+    }
+
+
+    /**
+     * Initialize ASEID from string
+     * 
+     * @param param1 
+     */
+    private fromString(param1: string) {
+        const [concept, body, version] = param1.split('@');
+        const [scope, entity, idCandidate] = body.split(':');
+
+        const shard = idCandidate.includes('.') ? idCandidate.split('.')[0] : undefined;
+        const id = idCandidate.includes('.') ? idCandidate.split('.')[1] : idCandidate;
+
+        this._concept = concept || A_Context.root.name;
+        this._scope = scope || A_Context.root.name;
+        this._entity = entity;
+        this._id = id;
+        this._version = version;
+        this._shard = shard;
+    }
+    /**
+     * Initialize ASEID from object
+     * 
+     * @param param1 
+     */
+    private fromObject(param1: A_TYPES__Required<Partial<A_TYPES__ASEID_Constructor>, ['id', 'entity']>) {
+        this._concept = param1.concept
+            ? ASEID.isASEID(param1.concept)
+                ? new ASEID(param1.concept).id
+                : param1.concept
+            : A_Context.concept;
+
+        this._scope = param1.scope
+            ? A_TypeGuards.isNumber(param1.scope)
+                ? A_IdentityHelper.formatWithLeadingZeros(param1.scope) :
+                ASEID.isASEID(param1.scope)
+                    ? new ASEID(param1.scope).id
+                    : param1.scope
+            : A_Context.root.name
+
+        this._entity = param1.entity;
+
+        this._id = A_TypeGuards.isNumber(param1.id)
+            ? A_IdentityHelper.formatWithLeadingZeros(param1.id)
+            : param1.id;
+
+        this._version = param1.version;
+        this._shard = param1.shard;
+    }
+
+
+    /**
+     * String representation of the ASEID
+     * 
+     * @returns 
+     */
+    toString(): string {
+        return `${this.concept}@${this.scope}:${this.entity}:${this.shard ? (this.shard + '.' + this.id) : this.id}${this.version ? ('@' + this.version) : ''}`
+    }
+
+    /**
+     * JSON representation of the ASEID
+     * 
+     * @returns 
+     */
+    toJSON(): A_TYPES__ASEID_JSON {
+        return {
+            concept: this._concept,
+            scope: this._scope,
+            entity: this._entity,
+            id: this._id,
+            version: this._version,
+            shard: this._shard
+        }
+    }
+
+    // --------------------------------------------------------------------------
+    // ----------------------- PROTECTED HELPERS --------------------------------
+    // --------------------------------------------------------------------------
+
+
+    protected verifyInput(param1: string | A_TYPES__Required<Partial<A_TYPES__ASEID_Constructor>, ['id', 'entity']>) {
+
+        switch (true) {
+            // 1) check for string and validate it as ASEID
+            case A_TypeGuards.isString(param1) && !ASEID.isASEID(param1):
+                throw new ASEID_Error(ASEID_Error.ASEIDValidationError, 'Invalid ASEID format provided')
+
+            // 2) check for object and validate required fields
+            case A_TypeGuards.isObject<A_TYPES__ASEID_Constructor>(param1) && !param1.id:
+                throw new ASEID_Error(ASEID_Error.ASEIDValidationError, 'ASEID id is required')
+
+            // 3) check for object and validate required fields
+            case A_TypeGuards.isObject<A_TYPES__ASEID_Constructor>(param1) && !param1.entity:
+                throw new ASEID_Error(ASEID_Error.ASEIDValidationError, 'ASEID entity is required')
+
+        }
+    }
+}

package/src/global/ASEID/ASEID.error.ts

@@ -0,0 +1,12 @@
+import { A_Error } from "../A-Error/A_Error.class";
+
+
+
+export class ASEID_Error extends A_Error {
+
+
+    static readonly ASEIDInitializationError = 'ASEID Initialization Error';
+    
+    static readonly ASEIDValidationError = 'ASEID Validation Error';
+
+}

package/src/global/ASEID/ASEID.types.ts

@@ -0,0 +1,79 @@
+export interface A_TYPES__ASEID_Constructor {
+    /**
+     * Concept for the ASEID 
+     * Generally it is the application name or code, should correspond to the concept where the entity is used
+     * Could be ID or ASEID
+     */
+    concept?: string,
+    /**
+     * Entity Scope the primary location of the resource 
+     * Organization, or organization Unit or Internal/External
+     * Could be ID or ASEID
+     * 
+     */
+    scope: number | string
+    /**
+     * Entity Type the type of the resource
+     */
+    entity: string
+    /**
+     * Entity ID the unique identifier of the resource
+     */
+    id: number | string
+    /**
+     * Version of the entity (optional)
+     */
+    version?: string
+    /**
+     * Shard of the entity (optional)
+     */
+    shard?: string
+};
+
+
+export interface A_TYPES__ASEID_ConstructorConfig {
+
+
+    /**
+     * If true, the entity ASEID will be distributed across multiple shards.
+     * In this case SHARD should be provided via Environment Variables (A_SHARD) or Configurations
+     * 
+     */
+    sharding?: boolean
+};
+
+
+
+
+export type A_TYPES__ASEID_JSON = {
+    /**
+     * Concept for the ASEID
+     */
+    concept: string,
+
+    /**
+     * Entity Scope the primary location of the resource
+     */
+    scope: string,
+
+    /**
+     * Entity Type the type of the resource
+     */
+    entity: string,
+
+    /**
+     * Entity ID the unique identifier of the resource
+     */
+    id: string,
+
+    /**
+     * Version of the entity (optional)
+     */
+    version?: string,
+
+    /**
+     * Shard of the entity (optional)
+     */
+    shard?: string
+}
+

package/src/helpers/A_Common.helper.ts

@@ -0,0 +1,204 @@
+import { A_TYPES__DeepPartial } from "../types/A_Common.types";
+
+export class A_CommonHelper {
+
+    /**
+     * A simple promise that resolves immediately.
+     * Can be used in async functions to create a resolved promise.
+     */
+    static resolve() {
+        return new Promise<void>((resolve) => resolve());
+    }
+
+    /**
+     * Check if a class is inherited from another class
+     * 
+     * @param childClass 
+     * @param parentClass 
+     * @returns 
+     */
+    static isInheritedFrom(childClass: any, parentClass: any): boolean {
+        let current = childClass;
+
+        // Traverse the prototype chain
+        while (current) {
+            if (current === parentClass) {
+                return true;
+            }
+            current = Object.getPrototypeOf(current);
+        }
+        return false;
+    }
+
+    /**
+     *  Omit properties from an object or array with nested objects
+     * 
+     * @param input 
+     * @param paths 
+     * @returns 
+     */
+    static omitProperties<T, S extends string>(
+        input: T,
+        paths: string[]
+
+    ): Omit<T, S> {
+
+        // Deep clone the input object or array
+        const result = JSON.parse(JSON.stringify(input));
+
+        // Helper function to recursively remove properties
+        function removeProperties(target: Record<string, any> | any[], currPath: string[]) {
+            const currKey = currPath[0];
+            if (currPath.length === 1) {
+                // If current path has only one key, delete the property
+                delete target[currKey];
+            } else if (target[currKey] !== undefined && typeof target[currKey] === 'object') {
+                // If current key exists and is an object, recursively call removeProperties
+                removeProperties(target[currKey], currPath.slice(1));
+            }
+        }
+
+        // Iterate through each path and remove corresponding properties from the result
+        paths.forEach(path => {
+            const pathKeys = path.split('.');
+            removeProperties(result, pathKeys);
+        });
+
+        return result as Omit<T, S>;
+    }
+
+
+    static isObject(item: unknown): item is Record<string, any> {
+        return item !== null && typeof item === 'object' && !Array.isArray(item);
+    }
+
+    static deepMerge<T = any>(target: any, source: any, visited = new Map<any, any>()): T {
+        if (this.isObject(target) && this.isObject(source)) {
+            for (const key in source) {
+                if (this.isObject(source[key])) {
+                    if (!target[key]) {
+                        target[key] = {};
+                    }
+                    // Check if the source object has already been visited
+                    if (!visited.has(source[key])) {
+                        visited.set(source[key], {});
+                        this.deepMerge(target[key], source[key], visited);
+                    } else {
+                        target[key] = visited.get(source[key]);
+                    }
+                } else {
+                    target[key] = source[key];
+                }
+            }
+        }
+        return target;
+    }
+
+
+    static deepClone<T>(target: T): T {
+        // Check if the value is null or undefined
+        if (target === null || target === undefined) {
+            return target;
+        }
+
+        // Handle primitive types (string, number, boolean, etc.)
+        if (typeof target !== 'object') {
+            return target;
+        }
+
+        // Handle Date
+        if (target instanceof Date) {
+            return new Date(target.getTime()) as T;
+        }
+
+        // Handle Array
+        if (Array.isArray(target)) {
+            return target.map(item => this.deepClone(item)) as unknown as T;
+        }
+
+        // Handle Function
+        if (typeof target === 'function') {
+            return target;
+        }
+
+        // Handle Object
+        if (target instanceof Object) {
+            const clone = {} as T;
+            for (const key in target) {
+                if (target.hasOwnProperty(key)) {
+                    clone[key] = this.deepClone(target[key]);
+                }
+            }
+            return clone;
+        }
+
+        // For any other cases
+        throw new Error('Unable to clone the object. Unsupported type.');
+    }
+
+
+    static deepCloneAndMerge<T>(target: A_TYPES__DeepPartial<T>, source: T): T {
+        if (
+            (source === null || source === undefined) &&
+            (target === null || target === undefined))
+            return target;
+
+        // Check if the value is null or undefined
+        if ((target === null || target === undefined) &&
+            source
+        ) {
+            return this.deepClone(source);
+        }
+
+        // Handle primitive types (string, number, boolean, etc.)
+        if (typeof target !== 'object') {
+            return target
+        }
+
+
+        // Handle Date
+        if (target instanceof Date) {
+            return new Date(target.getTime()) as T;
+        }
+
+        // Handle Array
+        if (Array.isArray(target)) {
+            return target.map(item => this.deepCloneAndMerge(item, source)) as unknown as T;
+        }
+
+        // Handle Function
+        if (typeof target === 'function') {
+            return target;
+        }
+
+        // Handle Object
+        if (target instanceof Object) {
+            const clone = {} as T;
+            for (const key in target) {
+                if (
+                    source[key] !== null
+                    &&
+                    source[key] !== undefined
+                )
+                    clone[key] = this.deepCloneAndMerge(target[key as any], source[key]);
+                else
+                    clone[key as any] = this.deepClone(target[key]);
+            }
+
+            for (const key in source) {
+                if (
+                    target[key] !== undefined
+                    &&
+                    target[key] !== null
+                )
+                    clone[key] = this.deepCloneAndMerge(target[key], source[key]);
+                else
+                    clone[key] = this.deepClone(source[key]);
+            }
+            return clone;
+        }
+
+        // For any other cases
+        throw new Error('Unable to clone the object. Unsupported type.');
+    }
+}

package/src/helpers/A_Formatter.helper.ts

@@ -0,0 +1,58 @@
+
+/**
+ * A_FormatterHelper
+ * 
+ * Helper class for formatting strings into different cases.
+ */
+export class A_FormatterHelper {
+    /**
+     * Convert string to UPPER_SNAKE_CASE
+     * 
+     * @param str 
+     * @returns 
+     */
+    static toUpperSnakeCase(str: string): string {
+        return str
+            .replace(/([a-z])([A-Z])/g, '$1_$2')  // Handle lowercase followed by uppercase
+            .replace(/[-\s]([A-Z])/g, '_$1')      // Handle non-alphabetical followed by uppercase
+            .replace(/-/g, '_')
+            .toUpperCase();
+    }
+    /**
+     * Convert string to camelCase
+     * 
+     * @param str 
+     * @returns 
+     */
+    static toCamelCase(str: string): string {
+        return str.toLowerCase().replace(/_([a-z])/g, (match, letter) => letter.toUpperCase());
+    }
+    /**
+     * Convert string to PascalCase
+     * 
+     * @param str 
+     * @returns 
+     */
+    static toPascalCase(str: string): string {
+        const camelCase = this.toCamelCase(str);
+        return camelCase.charAt(0).toUpperCase() + camelCase.slice(1);
+    }
+    /**
+     * Convert string to kebab-case
+     * 
+     * @param str 
+     * @returns 
+     */
+    static toKebabCase(str: string): string {
+        return str
+            // 1. Replace all non-alphanumeric (underscore, dot, etc.) with a space
+            .replace(/[^a-zA-Z0-9]+/g, ' ')
+            // 2. Insert space before any uppercase preceded by lowercase or digit
+            .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+            // 3. Trim spaces at both ends and replace remaining spaces with dashes
+            .trim()
+            .replace(/\s+/g, '-')
+            // 4. Lowercase everything
+            .toLowerCase();
+    }
+}

package/src/helpers/A_Identity.helper.ts

@@ -0,0 +1,53 @@
+
+export type A_ID_TYPES__TimeId_Parts = {
+    timestamp: Date;
+    random: string;
+}
+
+
+export class A_IdentityHelper {
+    /**
+   * Generates a short, time-based unique ID.
+   * Encodes current time (ms since epoch) and random bits in base36.
+   * Example: "mb4f1g-7f9a1c"
+   */
+    static generateTimeId(
+        parts: A_ID_TYPES__TimeId_Parts = { timestamp: new Date(), random: Math.random().toString(36).slice(2, 8) }
+    ): string {
+        const time = parts.timestamp.getTime().toString(36); // base36-encoded timestamp
+        const random = parts.random; // use provided random string
+        return `${time}-${random}`;
+    }
+
+    /**
+     * Parses a short ID back into its parts.
+     * Returns an object with the original timestamp (as Date) and random string.
+     */
+    static parseTimeId(id: string): A_ID_TYPES__TimeId_Parts {
+        const [timePart, randomPart] = id.split('-');
+        const timestamp = new Date(parseInt(timePart, 36));
+        return { timestamp, random: randomPart };
+    }
+
+
+    /**
+     *  Format a number with leading zeros to a fixed length
+     * 
+     * @param number 
+     * @param maxZeros 
+     * @returns 
+     */
+    static formatWithLeadingZeros(number, maxZeros = 10) {
+        const formattedNumber = String(number).padStart(maxZeros + 1, '0');
+        return formattedNumber.slice(-maxZeros);
+    }
+
+    /**
+     * Remove leading zeros from a formatted number
+     */
+    static removeLeadingZeros(formattedNumber) {
+        return String(Number(formattedNumber)); // Convert to number and back to string to remove leading zeros
+    }
+
+
+}