@quatrain/core 1.2.4 → 1.2.6

package/src/properties/BaseProperty.ts

@@ -7,6 +7,21 @@ export type EventTypes =
    | typeof BaseProperty.EVENT_ONCHANGE
    | typeof BaseProperty.EVENT_ONDELETE
 
+/**
+ * Configuration dictionary for instantiating a BaseProperty.
+ * Defines the behavior, constraints, and default state of a property within a Quatrain DataObject.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `name` | string | The canonical name of the property. | **Required** |
+ * | `id` | string | The internal identifier (defaults to lowercase `name`). | `name.toLowerCase()` |
+ * | `parent` | DataObjectClass | The parent object containing this property. | `undefined` |
+ * | `protected` | boolean | If true, the value can only be set once and becomes read-only. | `false` |
+ * | `mandatory` | boolean | If true, the property must have a value before saving. | `false` |
+ * | `defaultValue` | any | The default value or a function returning the default value. | `undefined` |
+ * | `htmlType` | PropertyHTMLType | The suggested HTML input type for rendering in a UI. | `'off'` |
+ * | `onChange` | function | Callback triggered whenever the property value is modified. | `undefined` |
+ */
 export interface BasePropertyType extends AbstractPropertyType {
    parent?: DataObjectClass<any>
    protected?: boolean
@@ -17,9 +32,30 @@ export interface BasePropertyType extends AbstractPropertyType {
 }
 
 // TODO: add `meta: boolean`. If meta is true, it is a meta-property strictly manipulated by the backend, and read-only for the user.
+
+/**
+ * The core foundation class for all Quatrain properties.
+ * It manages the state, immutability (protected), change tracking, and events of a data field.
+ * 
+ * @example
+ * ```typescript
+ * const myProp = new BaseProperty({
+ *    name: 'status',
+ *    defaultValue: 'active',
+ *    protected: false,
+ *    onChange: (dao) => console.log('Status changed on', dao.id)
+ * });
+ * 
+ * myProp.set('inactive');
+ * console.log(myProp.val()); // "inactive"
+ * ```
+ */
 export class BaseProperty implements PropertyClassType {
+   /** The string literal type identifier for this property. */
    static TYPE = 'any'
+   /** Event name triggered when the property value changes. */
    static EVENT_ONCHANGE = 'onChange'
+   /** Event name triggered when the property is deleted. */
    static EVENT_ONDELETE = 'onDelete'
 
    protected _parent: DataObjectClass<any> | undefined
@@ -86,6 +122,14 @@ export class BaseProperty implements PropertyClassType {
       this._hasChanged = val
    }
 
+   /**
+    * Sets a new value for the property and triggers the `onChange` event if modified.
+    * 
+    * @param value - The new value to assign.
+    * @param setChanged - Whether to mark the property as modified (defaults to true).
+    * @returns The current property instance for chaining.
+    * @throws {Error} If the property is marked as `protected` and already has a value.
+    */
    set(value: any, setChanged: boolean = true) {
       if (
          this._value !== undefined &&
@@ -113,6 +157,12 @@ export class BaseProperty implements PropertyClassType {
       return this
    }
 
+   /**
+    * Retrieves the current value of the property, or its default value if currently undefined.
+    * 
+    * @param transform - An optional transformation function applied to the value before returning it.
+    * @returns The raw or transformed property value.
+    */
    val(transform: any = undefined): any {
       // console.log(transform && transform(this._value), typeof transform);
       return typeof transform === 'function'
@@ -126,10 +176,20 @@ export class BaseProperty implements PropertyClassType {
       return value === undefined || value === true
    }
 
+   /**
+    * Serializes the property for JSON stringification.
+    * 
+    * @returns The raw internal value of the property.
+    */
    toJSON() {
       return this._value
    }
 
+   /**
+    * Creates a deep clone of the current property instance, preserving its prototype chain.
+    * 
+    * @returns A new independent instance of the property.
+    */
    clone() {
       const cloned = Object.create(
          Object.getPrototypeOf(this),

package/src/properties/BooleanProperty.ts

@@ -1,10 +1,36 @@
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 
+/**
+ * Configuration dictionary for instantiating a `BooleanProperty`.
+ * Inherits all core parameters from `BasePropertyType` with no additional constraints.
+ */
 export interface BooleanPropertyType extends BasePropertyType {}
 
+/**
+ * A property type strictly handling boolean values (`true` or `false`).
+ * 
+ * @example
+ * ```typescript
+ * const isActive = new BooleanProperty({
+ *    name: 'isActive',
+ *    defaultValue: false
+ * });
+ * 
+ * isActive.set(true);
+ * console.log(isActive.val()); // true
+ * ```
+ */
 export class BooleanProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'boolean'
 
+   /**
+    * Assigns a new boolean value to the property.
+    * 
+    * @param value - The boolean value to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    */
    set(value: boolean, setChanged = true) {
       return super.set(value, setChanged)
    }

package/src/properties/CollectionProperty.ts

@@ -4,13 +4,36 @@ import { Core } from '../Core'
 import { DataObjectClass } from '../components/types/DataObjectClass'
 import { BaseObject } from '../components/BaseObject'
 
+/**
+ * Configuration dictionary for instantiating a core `CollectionProperty`.
+ * Defines a relationship containing multiple objects.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `instanceOf` | typeof BaseObject | The class of the objects contained in this collection. | **Required** |
+ * | `backend` | any | An optional specific backend instance for persistence handling. | `undefined` |
+ * | `parentKey` | string | The foreign key field pointing back to the parent. | `parent.uri.collection` |
+ */
 export interface CollectionPropertyType extends BasePropertyType {
    instanceOf: typeof BaseObject
    backend?: any
    parentKey?: string
 }
 
+/**
+ * A basic relational property type representing a collection of `BaseObject` instances.
+ * This core class manages the in-memory array representation. For dynamic querying, see the backend `CollectionProperty`.
+ * 
+ * @example
+ * ```typescript
+ * const permissions = new CollectionProperty({
+ *    name: 'permissions',
+ *    instanceOf: Permission
+ * });
+ * ```
+ */
 export class CollectionProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'collection'
    protected _value:
       | Array<any>
@@ -33,10 +56,22 @@ export class CollectionProperty extends BaseProperty {
          config.parentKey || this._parent?.uri?.collection || 'unknown'
    }
 
+   /**
+    * Assigns an array of related objects or URIs to the collection.
+    * 
+    * @param value - The array of elements to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    */
    set(value: Array<any>, setChanged = true) {
       return super.set(value, setChanged)
    }
 
+   /**
+    * Serializes the collection for JSON output.
+    * 
+    * @returns The raw array of values.
+    */
    toJSON() {
       return this._value
    }

package/src/properties/DateTimeProperty.ts

@@ -1,15 +1,42 @@
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 
+/**
+ * Configuration dictionary for instantiating a `DateTimeProperty`.
+ * Extends `BasePropertyType` to handle date and time manipulations.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `timezone` | string | The timezone string (e.g. 'UTC', 'Europe/Paris', or 'Z'). | `'Z'` |
+ */
 export interface DateTimePropertyType extends BasePropertyType {
    timezone?: string
 }
 
+/**
+ * A property type that manages Dates, Timestamps, and ISO date strings.
+ * It automatically parses strings and standardizes UTC conversions depending on the global `RETURN_AS` setting.
+ * 
+ * @example
+ * ```typescript
+ * const createdAt = new DateTimeProperty({
+ *    name: 'createdAt',
+ *    timezone: 'UTC'
+ * });
+ * 
+ * createdAt.set(new Date()); // Will store as UNIX timestamp if RETURN_AS is configured
+ * console.log(createdAt.val());
+ * ```
+ */
 export class DateTimeProperty extends BaseProperty {
+   /** Return behavior to return the original Date object or string as is. */
    static AS_IS = 'asis'
+   /** Return behavior to auto-convert dates into numeric UNIX timestamps. */
    static UNIX_TIMESTAMP = 'unix_timestamp'
 
+   /** The string literal type identifier for this property. */
    static TYPE = 'datetime'
 
+   /** Global configuration determining the default format returned by `val()`. */
    static RETURN_AS: string = DateTimeProperty.AS_IS
 
    protected _timezone: string
@@ -19,6 +46,14 @@ export class DateTimeProperty extends BaseProperty {
       this._timezone = config.timezone || 'Z'
    }
 
+   /**
+    * Assigns a new date value. If `RETURN_AS` is set to `unix_timestamp`, 
+    * strings and JS Date objects are automatically parsed and converted to UNIX timestamps (milliseconds).
+    * 
+    * @param value - The date string, timestamp, or Date object to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    */
    set(value: string | Date | number, setChanged = true) {
       if (value && DateTimeProperty.RETURN_AS === 'unix_timestamp') {
          if (typeof value === 'string') {

package/src/properties/EnumProperty.ts

@@ -1,11 +1,36 @@
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 
+/**
+ * Configuration dictionary for instantiating an `EnumProperty`.
+ * Restricts the property value to a specific set of allowed strings.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `values` | string[] | Array of acceptable string values. | `[]` |
+ */
 export interface EnumPropertyType extends BasePropertyType {
    values?: string[]
 }
 
+/**
+ * A property type that validates string values against a strict list of allowed options.
+ * Useful for status fields, categories, or predefined states.
+ * 
+ * @example
+ * ```typescript
+ * const status = new EnumProperty({
+ *    name: 'status',
+ *    values: ['pending', 'active', 'deleted']
+ * });
+ * 
+ * status.set('active'); // OK
+ * status.set('archived'); // Throws Error: Value 'archived' is not acceptable
+ * ```
+ */
 export class EnumProperty extends BaseProperty {
+   /** Special wildcard value allowing any string to be accepted if configured in `values`. */
    static WILDCARD = '*'
+   /** The string literal type identifier for this property. */
    static TYPE = 'enum'
    protected _values: string[] = []
 
@@ -14,6 +39,15 @@ export class EnumProperty extends BaseProperty {
       this._values = config.values || []
    }
 
+   /**
+    * Assigns a new value, validating it against the allowed enum values.
+    * If the wildcard (`*`) is present in the allowed values, any value is accepted.
+    * 
+    * @param value - The enum string to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    * @throws {Error} If the value is not in the allowed list.
+    */
    set(value: string, setChanged = true) {
       if (
          value !== null &&

package/src/properties/FileProperty.ts

@@ -2,10 +2,27 @@ import { ObjectUri } from '../components/ObjectUri'
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 import { BaseObjectClass } from '../components/types/BaseObjectClass'
 
+/**
+ * Configuration dictionary for instantiating a `FileProperty`.
+ * Inherits all core parameters from `BasePropertyType`.
+ */
 export interface FilePropertyType extends BasePropertyType {}
 
+/**
+ * A property type designed to hold a reference to a File or Blob.
+ * It usually stores either the raw `BaseObjectClass` representing the file, or an `ObjectUri` pointing to the storage location.
+ * 
+ * @example
+ * ```typescript
+ * const avatar = new FileProperty({
+ *    name: 'avatar'
+ * });
+ * ```
+ */
 export class FileProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'file'
+   /** The internal stored value, either a class instance or a URI. */
    _value: BaseObjectClass | ObjectUri | undefined = undefined
 
    constructor(config: FilePropertyType) {

package/src/properties/HashProperty.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto'
 import { StringProperty, StringPropertyType } from './StringProperty'
+import { Core } from '../Core'
 
 export type HashPropertyAlgos =
    | typeof HashProperty.ALGORITHM_MD5
@@ -7,17 +8,50 @@ export type HashPropertyAlgos =
    | typeof HashProperty.ALGORITHM_SHA256
    | typeof HashProperty.ALGORITHM_BCRYPT
 
+/**
+ * Configuration dictionary for instantiating a `HashProperty`.
+ * Extends `StringPropertyType` to add hashing capabilities.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `algorithm` | HashPropertyAlgos | The cryptographic hashing algorithm to use. | `ALGORITHM_MD5` |
+ * | `salt` | string | An optional salt string appended to the value before hashing. | `""` |
+ * | `prefixed` | boolean | If true, prepends the algorithm name to the output (e.g. `md5-abc...`). | `false` |
+ */
 export interface HashPropertyType extends StringPropertyType {
    algorithm?: HashPropertyAlgos
    salt?: string
    prefixed?: boolean
 }
 
+/**
+ * A specialized string property that automatically hashes incoming values before storing them.
+ * Useful for storing passwords, secret tokens, or generating unique fingerprints.
+ * Values set on this property are one-way hashed and cannot be reversed.
+ * 
+ * @example
+ * ```typescript
+ * const password = new HashProperty({
+ *    name: 'password',
+ *    algorithm: HashProperty.ALGORITHM_SHA256,
+ *    salt: 'mySecretSalt'
+ * });
+ * 
+ * password.set('mySuperPassword');
+ * console.log(password.val()); // Returns the SHA256 hashed string
+ * const isValid = password.compare('mySuperPassword'); // true
+ * ```
+ */
 export class HashProperty extends StringProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'hash'
+   /** Identifier for the MD5 hashing algorithm. */
    static ALGORITHM_MD5 = 'md5'
+   /** Identifier for the SHA1 hashing algorithm. */
    static ALGORITHM_SHA1 = 'sha1'
+   /** Identifier for the SHA256 hashing algorithm. */
    static ALGORITHM_SHA256 = 'sha256'
+   /** Identifier for the BCRYPT hashing algorithm. */
    static ALGORITHM_BCRYPT = 'bcrypt'
 
    protected _algorithm: HashPropertyAlgos
@@ -31,15 +65,29 @@ export class HashProperty extends StringProperty {
       this._prefixed = config.prefixed || false
    }
 
+   /**
+    * Internal method to perform the cryptographic hash on a raw string.
+    * Uses Node.js native crypto module.
+    * 
+    * @param value - The raw string to hash.
+    * @returns The hexadecimal representation of the hashed string.
+    * @throws {Error} If the chosen algorithm is unsupported.
+    */
    _hash(value: string): string {
       let algo
       switch (this._algorithm) {
          case HashProperty.ALGORITHM_MD5:
             algo = createHash('md5')
+            Core.warn(
+               `HashProperty: MD5 is deprecated for security reasons`
+            )
             break
 
          case HashProperty.ALGORITHM_SHA1:
             algo = createHash('sha1')
+            Core.warn(
+               `HashProperty: SHA1 is deprecated for security reasons`
+            )
             break
 
          case HashProperty.ALGORITHM_SHA256:
@@ -60,10 +108,25 @@ export class HashProperty extends StringProperty {
       return hash
    }
 
+   /**
+    * Hashes the provided value and stores the hashed result.
+    * String length constraints (from StringProperty) are bypassed after hashing.
+    * 
+    * @param value - The raw cleartext string to hash and store.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    */
    set(value: string, setChanged = true) {
       return super.set(this._hash(value), setChanged)
    }
 
+   /**
+    * Compares a raw cleartext string against the stored hashed value.
+    * Automatically applies the configured salt and algorithm to the input before comparison.
+    * 
+    * @param value - The raw cleartext string to test.
+    * @returns True if the hashed input matches the stored hash, false otherwise.
+    */
    compare(value: string): boolean {
       return this._hash(value) === this._value
    }

package/src/properties/MapProperty.ts

@@ -1,10 +1,36 @@
 import { BaseProperty, BasePropertyType } from './BaseProperty'
 
+/**
+ * Configuration dictionary for instantiating a `MapProperty`.
+ * Inherits all core parameters from `BasePropertyType`.
+ */
 export interface MapPropertyType extends BasePropertyType {}
 
+/**
+ * A property type designed to store arbitrary JSON objects or Key-Value maps.
+ * 
+ * @example
+ * ```typescript
+ * const metadata = new MapProperty({
+ *    name: 'metadata',
+ *    defaultValue: {}
+ * });
+ * 
+ * metadata.set({ theme: 'dark', version: 2 });
+ * ```
+ */
 export class MapProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'map'
 
+   /**
+    * Assigns a new object or map to the property.
+    * 
+    * @param value - The object to assign. Must be of type 'object'.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    * @throws {Error} If the provided value is not an object.
+    */
    set(value: any, setChanged = true) {
       if (typeof value! !== 'object') {
          throw new Error(`value ${JSON.stringify(value)} is not an object`)
@@ -13,6 +39,11 @@ export class MapProperty extends BaseProperty {
       return super.set(value, setChanged)
    }
 
+   /**
+    * Serializes the map property for database storage.
+    * 
+    * @returns A JSON string representation of the map, or an empty object.
+    */
    toJSON() {
       return this._value ? JSON.stringify(this._value) : {}
    }

package/src/properties/NumberProperty.ts

@@ -8,6 +8,20 @@ export type NumberType =
    | typeof NumberProperty.TYPE_INTEGER
    | typeof NumberProperty.TYPE_FLOAT
 
+/**
+ * Configuration dictionary for instantiating a `NumberProperty`.
+ * Enforces numeric bounds, types (integer vs float), signs, and UI formatting.
+ *
+ * | Parameter | Type | Description | Default |
+ * | :--- | :--- | :--- | :--- |
+ * | `minVal` | number | The minimum allowed value (inclusive). | `undefined` |
+ * | `maxVal` | number | The maximum allowed value (inclusive). | `undefined` |
+ * | `sign` | NumberSign | Restricts the number to `signed` or `unsigned` (positive only). | `TYPE_SIGNED` |
+ * | `type` | NumberType | The numeric type: `integer` (floored) or `float`. | `TYPE_INTEGER` |
+ * | `prefix` | string | A string prepended to the formatted output (e.g., "$"). | `""` |
+ * | `suffix` | string | A string appended to the formatted output (e.g., "kg"). | `""` |
+ * | `precision` | number | Number of decimal places for floats. | `0` |
+ */
 export interface NumberPropertyType extends BasePropertyType {
    minVal?: number
    maxVal?: number
@@ -18,16 +32,42 @@ export interface NumberPropertyType extends BasePropertyType {
    precision?: number
 }
 
+/**
+ * A property type strictly validating and formatting numeric values.
+ * Allows enforcement of integers, positive-only limits, and boundary checking.
+ * 
+ * @example
+ * ```typescript
+ * const price = new NumberProperty({
+ *    name: 'price',
+ *    type: NumberProperty.TYPE_FLOAT,
+ *    sign: NumberProperty.TYPE_UNSIGNED,
+ *    prefix: '$',
+ *    minVal: 0
+ * });
+ * 
+ * price.set(19.99);
+ * console.log(price.val(NumberProperty.TRANSFORM_FORMATTED)); // "$ 19.99"
+ * price.set(-5); // Throws Error: Value must be unsigned
+ * ```
+ */
 export class NumberProperty extends BaseProperty {
+   /** The string literal type identifier for this property. */
    static TYPE = 'number'
+   /** Constraint flag for signed numbers (positive and negative). */
    static TYPE_SIGNED = 'signed'
+   /** Constraint flag for unsigned numbers (positive only). */
    static TYPE_UNSIGNED = 'unsigned'
 
+   /** Type flag indicating an integer value. */
    static TYPE_INTEGER = 'integer'
+   /** Type flag indicating a floating-point value. */
    static TYPE_FLOAT = 'float'
 
+   /** Default separator used for string formatting. */
    static SEPARATOR = ' '
 
+   /** Transformation identifier to return the number as a formatted string. */
    static TRANSFORM_FORMATTED = 'formatted'
 
    protected _minVal: number | undefined = undefined
@@ -58,6 +98,15 @@ export class NumberProperty extends BaseProperty {
       }
    }
 
+   /**
+    * Assigns a new numeric value while strictly enforcing boundary, sign, and type constraints.
+    * If configured as an integer, the input is floored.
+    * 
+    * @param value - The number to assign.
+    * @param setChanged - Whether to mark the property as modified.
+    * @returns The property instance for chaining.
+    * @throws {Error} If the number violates the min, max, or sign constraints.
+    */
    set(value: number, setChanged = true) {
       if (this._sign === NumberProperty.TYPE_UNSIGNED && value < 0) {
          throw new Error(`Value must be unsigned`)
@@ -78,6 +127,12 @@ export class NumberProperty extends BaseProperty {
       return super.set(value, setChanged)
    }
 
+   /**
+    * Retrieves the numeric value, optionally applying UI string formatting.
+    * 
+    * @param transform - Use `TRANSFORM_FORMATTED` to return a string with the configured prefix and suffix.
+    * @returns The raw number or the formatted string representation.
+    */
    val(transform: string | undefined = undefined) {
       switch (transform) {
          case NumberProperty.TRANSFORM_FORMATTED:

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()