@quatrain/core 1.2.5 → 1.2.7

package/src/Core.ts

@@ -7,14 +7,30 @@ import {
 import { spawn } from 'node:child_process'
 import which from 'which'
 
+/**
+ * Core foundation class for Quatrain architecture.
+ * Manages central configuration, logger registry, storage binding, and class mapping.
+ */
 export class Core {
+   /** Identifying namespace for this core component. */
    static readonly me = this.name
+   /** Persistent key-value storage engine reference. */
    static readonly storage = require('node-persist')
+   /** Context prefix string for scoped storage keys. */
    static readonly storagePrefix = 'core'
+   /** Dictionary holding registered active Quatrain models/components. */
    static readonly classRegistry: { [key: string]: any } = {}
+   /** System-wide base log verbosity. */
    static readonly logLevel = LogLevel.DEBUG
+   /** Active logger instance for the Core domain. */
    static readonly logger: AbstractLoggerAdapter = this.addLogger()
 
+   /**
+    * Injects a new logger block under a specific namespace alias.
+    * 
+    * @param alias - The logging context name.
+    * @returns Instantiated LoggerAdapter.
+    */
    static addLogger(alias: string = this.name) {
       return Log.addLogger(
          '@' + alias,
@@ -23,13 +39,27 @@ export class Core {
       )
    }
 
+   /**
+    * Mutates the underlying verbosity constraints.
+    * 
+    * @param level - Active LogLevel filter.
+    */
    static setLogLevel(level: LogLevel) {
       this.logger.logLevel(level)
    }
 
    // How timestamp are formatted
+   /**
+    * Returns an ISO string representing the current time.
+    */
    static readonly timestamp = () => new Date().toISOString()
 
+   /**
+    * Deprecated: Reserved schema definition hook.
+    * 
+    * @param key - The property block to generate.
+    * @returns Field definitions block.
+    */
    static definition(key: string) {
       return {
          manifest: {
@@ -39,6 +69,12 @@ export class Core {
       }
    }
 
+   /**
+    * Stores a primitive value durably in the core storage instance.
+    * 
+    * @param key - Identification string.
+    * @param value - Value.
+    */
    static async addConfig(key: string, value: any) {
       if (!this.storage.set) {
          await this.storage.init()
@@ -46,6 +82,12 @@ export class Core {
       await this.storage.set(`${this.storagePrefix}_${key}`, value)
    }
 
+   /**
+    * Recovers a durably persisted value from the storage layer.
+    * 
+    * @param key - The target identifier.
+    * @returns The recovered value.
+    */
    static async getConfig(key: string) {
       if (!this.storage.get) {
          await this.storage.init()
@@ -53,10 +95,22 @@ export class Core {
       return await this.storage.get(`${this.storagePrefix}_${key}`)
    }
 
+   /**
+    * Maps a specific entity class to an active name so the factory reflection can locate it.
+    * 
+    * @param name - Semantic registry name.
+    * @param obj - Class constructor.
+    */
    static addClass(name: string, obj: any) {
       Core.classRegistry[name] = obj
    }
 
+   /**
+    * Returns an injected class constructor by its registry identifier.
+    * 
+    * @param name - The semantic name to resolve.
+    * @returns Class definition.
+    */
    static getClass(name: string) {
       return Core.classRegistry[name]
    }
@@ -104,9 +158,21 @@ export class Core {
       }
    }
 
+   /**
+    * Utility lookup to find executable paths in the system using `which`.
+    * 
+    * @param command - The executable.
+    * @returns The resolved system path.
+    */
    static readonly getSystemCommandPath = (command: string): Promise<string> =>
       which(command)
 
+   /**
+    * Execution suspension utility blocking the event loop context.
+    * 
+    * @param seconds - Duration count.
+    * @returns The promise to await.
+    */
    static sleep(seconds: number = 1) {
       return new Promise((resolve) => setTimeout(resolve, seconds * 1000))
    }
@@ -119,26 +185,56 @@ export class Core {
       this.addClass('User', cls)
    }
 
+   /**
+    * Triggers a standard log on the core logger.
+    * 
+    * @param message - Content to log.
+    */
    static log(...message: any): void {
       return this.logger.log(message)
    }
 
+   /**
+    * Triggers a debug log on the core logger.
+    * 
+    * @param message - Content to log.
+    */
    static debug(...message: any): void {
       return this.logger.debug(message)
    }
 
+   /**
+    * Triggers a warning log on the core logger.
+    * 
+    * @param message - Content to log.
+    */
    static warn(...message: any): void {
       return this.logger.warn(message)
    }
 
+   /**
+    * Triggers an info log on the core logger.
+    * 
+    * @param message - Content to log.
+    */
    static info(...message: any): void {
       return this.logger.info(message)
    }
 
+   /**
+    * Triggers an error log on the core logger.
+    * 
+    * @param message - Content to log.
+    */
    static error(...message: any): void {
       return this.logger.error(message)
    }
 
+   /**
+    * Triggers a trace log on the core logger.
+    * 
+    * @param message - Content to log.
+    */
    static trace(...message: any): void {
       return this.logger.trace(message)
    }

package/src/common/ResourcesErrors.ts

@@ -1,3 +1,6 @@
+/**
+ * Global abstraction identifying Quatrain-specific execution exceptions.
+ */
 export class ResourceError extends Error {
    constructor(message: string) {
       super(message)
@@ -6,17 +9,26 @@ export class ResourceError extends Error {
    }
 }
 
+/** Indicates a structurally flawed request (e.g., HTTP 400). */
 export class BadRequestError extends ResourceError {}
 
+/** Indicates missing or invalid authentication credentials (e.g., HTTP 401). */
 export class UnauthorizedError extends ResourceError {}
 
+/** Indicates an authenticated action denied by privileges (e.g., HTTP 403). */
 export class ForbiddenError extends ResourceError {}
 
+/** Indicates a non-existent database or file resource lookup (e.g., HTTP 404). */
 export class NotFoundError extends ResourceError {}
 
+/** Indicates an originally valid asset that has been purged (e.g., HTTP 410). */
 export class GoneError extends ResourceError {}
 
+/**
+ * Indicates property rejection. Holds a payload of granular property-specific validation issues.
+ */
 export class ValidationError extends ResourceError {
+   /** Detailed key-value map linking property names to specific violation causes. */
    public errors: Record<string, string>
 
    constructor(message: string, errors: Record<string, string> = {}) {

package/src/components/AbstractObject.ts

@@ -1,16 +1,22 @@
 import { DataObjectClass } from './types/DataObjectClass'
 import { DataObjectProperties } from '../properties'
 
+/**
+ * Foundational wrapper for interacting with properties dynamically.
+ */
 export abstract class AbstractObject {
+   /** Array defining the structure and constraints of properties belonging to this model. */
    static PROPS_DEFINITION: DataObjectProperties = []
 
-   // Which name to use in backend as table/collection identifer
+   /** The backend identifier (table or collection name) representing this class. */
    static COLLECTION: string | undefined
 
-   // which property handles relation to parent
+   /** The name of the property handling hierarchical parent relationships. */
    static PARENT_PROP: string | undefined
 
-   // Which property's value to use in backend as label for object reference
+   /**
+    * Which property's value to use in backend as label for object reference
+    */
    static LABEL_KEY = 'name'
 
    protected _dataObject: DataObjectClass<any>
@@ -28,10 +34,23 @@ export abstract class AbstractObject {
       return this._dataObject.get(key)
    }
 
+   /**
+    * Proxies a set command to the underlying data object.
+    * 
+    * @param key - The property key.
+    * @param val - The value to assign.
+    * @returns The DataObject instance for chaining.
+    */
    set(key: string, val: any) {
       return this._dataObject.set(key, val)
    }
 
+   /**
+    * Fetches the value of a property.
+    * 
+    * @param key - The property key.
+    * @returns The property value or null if undefined.
+    */
    val(key: string): any {
       const prop = this.get(key)
       if (prop) {
@@ -41,6 +60,12 @@ export abstract class AbstractObject {
       }
    }
 
+   /**
+    * Checks if a property exists on the data object.
+    * 
+    * @param key - The property key.
+    * @returns True if the property exists.
+    */
    has(key: string) {
       return Reflect.has(this._dataObject.properties, key)
    }
@@ -65,6 +90,11 @@ export abstract class AbstractObject {
       return this._dataObject.uri
    }
 
+   /**
+    * Serializes the current object path / identity.
+    * 
+    * @returns The JSON serialized ObjectUri.
+    */
    toJSON() {
       return typeof this.uri === 'string' ? this.uri : this.uri?.toJSON()
    }

package/src/components/BaseObject.ts

@@ -7,14 +7,31 @@ import { AbstractObject } from './AbstractObject'
 import { DataObjectType } from './types/DataObjectType'
 import { ValidationError } from '../common/ResourcesErrors'
 
+/**
+ * Base generic model class. All Quatrain models inherit from this object.
+ * Provides the lifecycle methods and structural properties logic.
+ */
 export class BaseObject extends AbstractObject {
    // implements BaseObjectClass {
+   /** Standard properties inherited by all children models. */
    static PROPS_DEFINITION: any /*DataObjectProperties*/ = BaseObjectProperties
 
+   /**
+    * Returns the definition of a specific property from the model schema.
+    * 
+    * @param key - The property name.
+    * @returns The property definition object.
+    */
    static getProperty(key: string) {
       return BaseObject.PROPS_DEFINITION.find((prop: any) => prop.name === key)
    }
 
+   /**
+    * Compiles the merged properties of a given child class down to its parents.
+    * 
+    * @param child - The target child class.
+    * @returns The resulting populated DataObject.
+    */
    static fillProperties(child: any = this) {
       // merge base properties with additional or redefined ones
       const base = [...BaseObject.PROPS_DEFINITION]
@@ -38,6 +55,13 @@ export class BaseObject extends AbstractObject {
       return dao
    }
 
+   /**
+    * Instantiates the DataObject for a specific model class.
+    * 
+    * @param src - Potential source path or object.
+    * @param child - The class constructor context.
+    * @returns A promise resolving to the inner DataObject payload.
+    */
    static async daoFactory(
       src: string | ObjectUri | DataObjectType | undefined = undefined,
       child: any = this
@@ -76,6 +100,14 @@ export class BaseObject extends AbstractObject {
       return obj
    }
 
+   /**
+    * Main initialization factory. Evaluates path or object sources and returns a fully
+    * initialized model instance.
+    * 
+    * @param src - Source data payload or path reference.
+    * @param child - Model subclass context.
+    * @returns The generated model instance.
+    */
    static async factory(
       src: string | ObjectUri | BaseObjectType | undefined = undefined,
       child: any = this
@@ -128,6 +160,11 @@ export class BaseObject extends AbstractObject {
       return obj //.toProxy()
    }
 
+   /**
+    * Serializes the object down to an identifier reference map.
+    * 
+    * @returns The Object reference payload.
+    */
    asReference() {
       return this._dataObject.toReference()
    }

package/src/components/DataObject.ts

@@ -83,6 +83,11 @@ export class DataObject implements DataObjectType {
       })
    }
 
+   /**
+    * Forces a completely new set of properties into the registry.
+    * 
+    * @param properties - The dictionary of PropertyClassType entities.
+    */
    public setProperties(properties: Properties) {
       // TODO check if doable
       this._properties = properties
@@ -108,6 +113,11 @@ export class DataObject implements DataObjectType {
       return this._properties
    }
 
+   /**
+    * Appends a new property definition instance to the registry dynamically.
+    * 
+    * @param property - The instantiated Property element.
+    */
    public addProperty(property: PropertyClassType) {
       if (Object.keys(this._properties).includes(property.name)) {
          throw new Error(`Property ${property.name} already exists`)
@@ -178,6 +188,11 @@ export class DataObject implements DataObjectType {
       return this
    }
 
+   /**
+    * State check indicating if the object is fully populated.
+    * 
+    * @returns true if populated.
+    */
    isPopulated() {
       return this._populated
    }
@@ -232,6 +247,12 @@ export class DataObject implements DataObjectType {
       this._parentProp = str
    }
 
+   /**
+    * Checks if a specific property exists.
+    * 
+    * @param key - The property name.
+    * @returns Boolean indicating existence.
+    */
    has(key: string) {
       return Reflect.has(this._properties, key)
    }
@@ -248,6 +269,13 @@ export class DataObject implements DataObjectType {
       return Reflect.get(this._properties, key)
    }
 
+   /**
+    * Modifies a property value directly.
+    * 
+    * @param key - The property name.
+    * @param val - The desired value.
+    * @returns The updated DataObject for chaining.
+    */
    set(key: string, val: any) {
       if (!this.has(key)) {
          throw new Error(`Unknown property in data object: ${key}`)
@@ -272,6 +300,12 @@ export class DataObject implements DataObjectType {
       }
    }
 
+   /**
+    * Serializes the data object using advanced configuration params.
+    * 
+    * @param params - Serialization settings (e.g. resolve references, remove nulls).
+    * @returns The raw serialized dictionary.
+    */
    toJSON(params: boolean | toJSONParams = false): { [x: string]: any } {
       let objectsAsReferences: boolean = false,
          withoutURIData: boolean = false,
@@ -300,6 +334,11 @@ export class DataObject implements DataObjectType {
       }
    }
 
+   /**
+    * Flattens the object to a standard ObjectUri wrapper reference format.
+    * 
+    * @returns Reference object format.
+    */
    toReference() {
       return {
          ...this._objectUri.toReference(),
@@ -400,6 +439,12 @@ export class DataObject implements DataObjectType {
       }
    }
 
+   /**
+    * Returns a completely duplicated payload and registry.
+    * 
+    * @param data - Optional data overrides.
+    * @returns The cloned DataObject.
+    */
    async clone(data: any = {}): Promise<DataObject> {
       const cloned = await (this.constructor as any).factory()
       cloned.uri.class = this.uri.class

package/src/components/Entity.ts

@@ -10,9 +10,15 @@ export interface EntityType extends BaseObjectType {
    //   users?: User[]
 }
 
+/**
+ * Represents a generic grouping structure, such as a company or organization, 
+ * to which Users may be associated.
+ */
 export class Entity extends BaseObject {
+   /** Base collection scope name. */
    static COLLECTION = 'entities'
 
+   /** Component structure declaration. */
    static PROPS_DEFINITION = [
       ...BaseObjectProperties,
       {
@@ -32,6 +38,12 @@ export class Entity extends BaseObject {
       // },
    ]
 
+   /**
+    * Entity creation factory.
+    * 
+    * @param src - Identifier or content array.
+    * @returns The generated Entity instance.
+    */
    static async factory(src: any = undefined): Promise<Entity> {
       return super.factory(src, Entity)
    }

package/src/components/ObjectUri.ts

@@ -1,5 +1,11 @@
+/**
+ * Unique global reference system for all Quatrain models.
+ * Used for backend identification and cross-system relational links.
+ */
 export class ObjectUri {
+   /** Root path divider. */
    static DEFAULT = '/'
+   /** Placeholder used when collections cannot be guessed. */
    static MISSING_COLLECTION = '_?_'
 
    protected _str: string
@@ -164,6 +170,11 @@ export class ObjectUri {
       }
    }
 
+   /**
+    * Output pure object dictionary representation.
+    * 
+    * @returns Rendered URI block.
+    */
    toJSON() {
       return {
          backend: this._backend,

package/src/components/User.ts

@@ -101,10 +101,22 @@ export const UserProperties: any = [
    },
 ]
 
+/**
+ * Built-in User representation model handling authentication, profiles, 
+ * and entity bindings out of the box.
+ */
 export class User extends BaseObject {
+   /** User internal schema layout. */
    static PROPS_DEFINITION = UserProperties
+   /** Standard persistence namespace. */
    static COLLECTION = 'user'
 
+   /**
+    * Constructs a new User.
+    * 
+    * @param src - Values or identifier.
+    * @returns The generated user object.
+    */
    static async factory(src: any = undefined): Promise<User> {
       return super.factory(src, User)
    }

package/src/properties/ArrayProperty.ts

@@ -1,6 +1,17 @@
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 import { StringProperty } from './StringProperty'
 
+/**
+ * Configuration dictionary for instantiating an `ArrayProperty`.
+ * Restricts the length and content types of an array.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `minLength` | number | Minimum number of elements required in the array. | `0` |
+ * | `maxLength` | number | Maximum number of elements allowed in the array. | `0` (unlimited) |
+ * | `allowNumbers` | boolean | If false, throws an error if the array contains numeric elements. | `true` |
+ * | `allowStrings` | boolean | If false, throws an error if the array contains string elements. | `true` |
+ */
 export interface ArrayPropertyType extends BasePropertyType {
    minLength?: number
    maxLength?: number
@@ -8,7 +19,25 @@ export interface ArrayPropertyType extends BasePropertyType {
    allowStrings?: boolean
 }
 
+/**
+ * A property type that validates and manages arrays of primitive values.
+ * Allows enforcement of minimum and maximum element counts, as well as primitive type restrictions.
+ * 
+ * @example
+ * ```typescript
+ * const tags = new ArrayProperty({
+ *    name: 'tags',
+ *    minLength: 1,
+ *    maxLength: 5,
+ *    allowNumbers: false // Only string tags allowed
+ * });
+ * 
+ * tags.set(['typescript', 'quatrain']); // OK
+ * tags.set([123]); // Throws Error: Numbers are not allowed in value
+ * ```
+ */
 export class ArrayProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'array'
    protected _value: Array<any> | undefined = undefined
 
@@ -42,6 +71,14 @@ export class ArrayProperty extends BaseProperty {
       return this._maxLength
    }
 
+   /**
+    * Assigns a new array value while enforcing length constraints and content type rules.
+    * 
+    * @param value - The array to assign. Null values are cast to empty arrays `[]`.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    * @throws {Error} If the value is not an array, violates length bounds, or contains forbidden types.
+    */
    set(value: Array<any>, setChanged = true) {
       if (value === null) {
          value = []
@@ -77,10 +114,21 @@ export class ArrayProperty extends BaseProperty {
       return super.set(value, setChanged)
    }
 
+   /**
+    * Retrieves the array, optionally applying a mapping/transformation function.
+    * 
+    * @param transform - A custom function to apply to the array before returning it.
+    * @returns The raw or transformed array.
+    */
    get(transform: Function | undefined = undefined) {
       return transform ? transform(this._value) : this._value
    }
 
+   /**
+    * Serializes the array for JSON stringification.
+    * 
+    * @returns The raw internal array.
+    */
    toJSON() {
       return this._value
    }

package/src/properties/BaseProperty.test.ts

@@ -76,4 +76,35 @@ describe('BaseProperty', () => {
       propStr.set('')
       expect(propStr.val()).toBe('')
    })
+
+   it('should set hasChanged to true when mutating an object by reference and setting it again', () => {
+      const prop = new BaseProperty({ name: 'obj' })
+      const arr = [1, 2]
+      prop.set(arr)
+      expect(prop.hasChanged).toBe(true)
+      
+      prop.hasChanged = false
+      arr.push(3)
+      prop.set(arr)
+      expect(prop.hasChanged).toBe(true)
+   })
+
+   it('should set hasChanged to false when setting a different object reference with identical contents', () => {
+      const prop = new BaseProperty({ name: 'obj' })
+      prop.set([1, 2])
+      expect(prop.hasChanged).toBe(true)
+      
+      prop.hasChanged = false
+      prop.set([1, 2])
+      expect(prop.hasChanged).toBe(false)
+   })
+
+   it('should handle circular references safely without throwing and mark as changed', () => {
+      const prop = new BaseProperty({ name: 'circular' })
+      const obj: any = { a: 1 }
+      obj.self = obj
+      
+      expect(() => prop.set(obj)).not.toThrow()
+      expect(prop.hasChanged).toBe(true)
+   })
 })