@quatrain/core 1.2.5 → 1.2.7

package/src/properties/ObjectProperty.ts

@@ -12,13 +12,39 @@ export enum returnAs {
    AS_IS = 'asIs',
 }
 
+/**
+ * Configuration dictionary for instantiating an `ObjectProperty`.
+ * Defines the class type of the expected object.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `instanceOf` | any | The class constructor or class name string the object must match. | **Required** |
+ */
 export interface ObjectPropertyType extends BasePropertyType {
    instanceOf: any //Function | string | Object
 }
 
+/**
+ * A relational property type designed to store references to other `BaseObjectClass` instances.
+ * Handles polymorphic resolution between raw `ObjectUri`, underlying `DataObject`, or the full class instance.
+ * 
+ * @example
+ * ```typescript
+ * const owner = new ObjectProperty({
+ *    name: 'owner',
+ *    instanceOf: User
+ * });
+ * 
+ * owner.set(userInstance);
+ * const uri = owner.val(returnAs.AS_OBJECTURIS); // Returns just the reference
+ * ```
+ */
 export class ObjectProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'object'
+   /** The internal stored value, either a class instance or a URI. */
    _value: BaseObjectClass | ObjectUri | undefined = undefined
+   /** The class constructor or class name string the object must match. */
    _instanceOf: any //Function | string | Object
 
    constructor(config: ObjectPropertyType) {
@@ -30,6 +56,12 @@ export class ObjectProperty extends BaseProperty {
       return this._instanceOf
    }
 
+   /**
+    * Retrieves the object, optionally resolving it to a specific representation.
+    * 
+    * @param transform - The desired format (`returnAs.AS_OBJECTURIS`, `AS_DATAOBJECTS`, `AS_INSTANCES`).
+    * @returns The resolved object, data object, or URI based on the requested transform.
+    */
    val(transform: string | undefined = undefined) {
       try {
          if (typeof this._instanceOf === 'string') {
@@ -89,6 +121,15 @@ export class ObjectProperty extends BaseProperty {
       }
    }
 
+   /**
+    * Assigns an object or an object reference to the property.
+    * Validates that the provided object matches the `instanceOf` class definition.
+    * 
+    * @param value - The `BaseObjectClass`, `DataObject`, or `ObjectUri` to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    * @throws {Error} If the assigned value is not an instance of the configured class.
+    */
    set(value: object, setChanged = true) {
       if (
          value! instanceof ObjectUri &&
@@ -105,6 +146,11 @@ export class ObjectProperty extends BaseProperty {
       return super.set(value, setChanged)
    }
 
+   /**
+    * Serializes the object property into a reference format suitable for storage.
+    * 
+    * @returns The `ObjectUri` JSON representation, or a reference object.
+    */
    toJSON() {
       if (this._value instanceof ObjectUri) {
          return this._value.toJSON()

package/src/properties/Property.ts

@@ -12,19 +12,43 @@ import { ArrayProperty } from './ArrayProperty'
 import { MapProperty } from './MapProperty'
 import { FileProperty, FilePropertyType } from './FileProperty'
 
+/**
+ * A central factory class for instantiating property objects dynamically based on a configuration payload.
+ * It routes property definitions to their respective concrete classes.
+ */
 export class Property {
+   /** Identifier for the `BaseProperty` class. */
    static TYPE_ANY = 'any'
+   /** Identifier for the `NumberProperty` class. */
    static TYPE_NUMBER = 'number'
+   /** Identifier for the `StringProperty` class. */
    static TYPE_STRING = 'string'
+   /** Identifier for the `ObjectProperty` class. */
    static TYPE_OBJECT = 'object'
+   /** Identifier for the `EnumProperty` class. */
    static TYPE_ENUM = 'enum'
+   /** Identifier for the `BooleanProperty` class. */
    static TYPE_BOOLEAN = 'boolean'
+   /** Identifier for the `HashProperty` class. */
    static TYPE_HASH = 'hash'
+   /** Identifier for the `DateTimeProperty` class. */
    static TYPE_DATETIME = 'datetime'
+   /** Identifier for the `ArrayProperty` class. */
    static TYPE_ARRAY = 'array'
+   /** Identifier for the `MapProperty` class. */
    static TYPE_MAP = 'map'
+   /** Identifier for the `FileProperty` class. */
    static TYPE_FILE = 'file'
 
+   /**
+    * Dynamically creates a concrete Property instance based on the provided configuration.
+    * Uses the `type` field to route to the correct subclass constructor.
+    * 
+    * @param params - A comprehensive dictionary covering parameters for all possible property types. Must include `type`.
+    * @param parent - The parent `DataObjectClass` attaching this property.
+    * @returns The instantiated concrete property class (e.g. `StringProperty`, `NumberProperty`).
+    * @throws {Error} If the specified property type is unknown or missing required fields.
+    */
    static factory(
       params: ObjectPropertyType &
          StringPropertyType &

package/src/properties/StringProperty.ts

@@ -1,6 +1,20 @@
 //import { Property } from './Property'
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 
+/**
+ * Configuration dictionary for instantiating a `StringProperty`.
+ * Defines length constraints and character-level validation.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `minLength` | number | Minimum length of the string. | `0` |
+ * | `maxLength` | number | Maximum length of the string. | `0` (unlimited) |
+ * | `allowSpaces` | boolean | If false, throws an error if the string contains whitespace. | `true` |
+ * | `allowDigits` | boolean | If false, throws an error if the string contains digits (0-9). | `true` |
+ * | `allowLetters` | boolean | If false, throws an error if the string contains letters (a-z, A-Z). | `true` |
+ * | `allowPattern` | string | A regular expression pattern the string must match. | `undefined` |
+ * | `fullSearch` | boolean | Indicates to the backend if this field should be indexed for full-text search. | `false` |
+ */
 export interface StringPropertyType extends BasePropertyType {
    minLength?: number
    maxLength?: number
@@ -11,16 +25,42 @@ export interface StringPropertyType extends BasePropertyType {
    fullSearch?: boolean
 }
 
+/**
+ * A property type strictly validating and handling strings.
+ * It ensures that length constraints and specific character rules are respected before saving.
+ * 
+ * @example
+ * ```typescript
+ * const username = new StringProperty({
+ *    name: 'username',
+ *    minLength: 3,
+ *    maxLength: 15,
+ *    allowSpaces: false
+ * });
+ * 
+ * username.set('my user'); // Throws Error: Spaces are not allowed
+ * username.set('my_user'); // OK
+ * console.log(username.get(StringProperty.TRANSFORM_UCASE)); // "MY_USER"
+ * ```
+ */
 export class StringProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'string'
 
+   /** Transformation identifier to convert string to uppercase. */
    static TRANSFORM_UCASE = 'upper'
+   /** Transformation identifier to convert string to lowercase. */
    static TRANSFORM_LCASE = 'lower'
 
+   /** Permission flag to allow whitespace characters. */
    static ALLOW_SPACES = 'spaces'
+   /** Permission flag to allow alphabetic letters. */
    static ALLOW_LETTERS = 'letters'
+   /** Permission flag to allow numeric digits. */
    static ALLOW_DIGITS = 'digits'
+   /** Permission flag to allow string values. */
    static ALLOW_STRINGS = 'strings'
+   /** Permission flag to allow number values. */
    static ALLOW_NUMBERS = 'numbers'
 
    protected _minLength: number = 0
@@ -50,6 +90,14 @@ export class StringProperty extends BaseProperty {
       }
    }
 
+   /**
+    * Assigns a new string value while strictly enforcing length and character constraints.
+    * 
+    * @param value - The string to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    * @throws {Error} If the string contains forbidden characters (spaces, letters, digits) or violates length limits.
+    */
    set(value: any, setChanged = true) {
       if (this._rawValue && value !== null && value !== undefined) {
          if (
@@ -84,6 +132,12 @@ export class StringProperty extends BaseProperty {
       return super.set(value, setChanged)
    }
 
+   /**
+    * Retrieves the string value, optionally applying a casing transformation.
+    * 
+    * @param transform - Use `TRANSFORM_LCASE` or `TRANSFORM_UCASE` to mutate output case.
+    * @returns The raw or transformed string, or undefined.
+    */
    get(transform: string | undefined = undefined) {
       switch (transform) {
          case StringProperty.TRANSFORM_LCASE: