@quatrain/core 1.1.24 → 1.1.29

package/src/properties/ArrayProperty.ts

@@ -0,0 +1,87 @@
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+import { StringProperty } from './StringProperty'
+
+export interface ArrayPropertyType extends BasePropertyType {
+   minLength?: number
+   maxLength?: number
+   allowNumbers?: boolean
+   allowStrings?: boolean
+}
+
+export class ArrayProperty extends BaseProperty {
+   static TYPE = 'array'
+   protected _value: Array<any> | undefined = undefined
+
+   protected _minLength: number = 0
+   protected _maxLength: number = 0
+
+   constructor(config: ArrayPropertyType) {
+      super(config)
+      this.minLength = config.minLength || 0
+      this.maxLength = config.maxLength || 0
+      if (this._enable(config.allowNumbers)) {
+         this._allows.push(StringProperty.ALLOW_NUMBERS)
+      }
+      if (this._enable(config.allowStrings)) {
+         this._allows.push(StringProperty.ALLOW_STRINGS)
+      }
+   }
+
+   set minLength(min: number) {
+      this._minLength = min >= 0 ? min : 0
+   }
+
+   get minLength() {
+      return this._minLength
+   }
+
+   set maxLength(max: number) {
+      this._maxLength = max >= 0 ? max : 0
+   }
+   get maxLength() {
+      return this._maxLength
+   }
+
+   set(value: Array<any>, setChanged = true) {
+      if (value === null) {
+         value = []
+      }
+      if (!Array.isArray(value)) {
+         throw new Error(`value ${JSON.stringify(value)} is not an array`)
+      }
+
+      if (this._minLength > 0 && value.length < this._minLength) {
+         throw new Error(`Array has too few values`)
+      }
+
+      if (this._maxLength > 0 && value.length > this._maxLength) {
+         throw new Error(`Array values are too many`)
+      }
+
+      const joined = value.join()
+
+      if (
+         this._allows.includes(StringProperty.ALLOW_STRINGS) === false &&
+         /[a-zA-Z]/.test(joined)
+      ) {
+         throw new Error(`Strings are not allowed in value`)
+      }
+
+      if (
+         this._allows.includes(StringProperty.ALLOW_NUMBERS) === false &&
+         /\d/.test(joined)
+      ) {
+         throw new Error(`Numbers are not allowed in value`)
+      }
+
+      return super.set(value, setChanged)
+   }
+
+   get(transform: Function | undefined = undefined) {
+      return transform ? transform(this._value) : this._value
+   }
+
+   toJSON() {
+      return this._value
+   }
+}

package/src/properties/BaseProperty.test.ts

@@ -0,0 +1,79 @@
+import { BaseProperty } from './BaseProperty'
+
+describe('BaseProperty', () => {
+   it('should initialize with name and default values', () => {
+      const prop = new BaseProperty({ name: 'TestProp' })
+      expect(prop.name).toBe('TestProp')
+      expect(prop.val()).toBeUndefined()
+      expect(prop.hasChanged).toBe(false)
+   })
+
+   it('should handle functional default values', () => {
+      const prop = new BaseProperty({
+         name: 'test',
+         defaultValue: () => 'dynamic-default',
+      })
+      expect(prop.val()).toBe('dynamic-default')
+   })
+
+   it('should set and get values correctly', () => {
+      const prop = new BaseProperty({ name: 'test' })
+      prop.set('new-value')
+      expect(prop.val()).toBe('new-value')
+      expect(prop.hasChanged).toBe(true)
+   })
+
+   it('should respect the protected attribute (write-once logic)', () => {
+      const prop = new BaseProperty({
+         name: 'test',
+         protected: true,
+         defaultValue: 'initial',
+      })
+
+      // First change is allowed if it moves away from default
+      prop.set('first-change')
+      expect(prop.val()).toBe('first-change')
+
+      // Subsequent changes should throw
+      expect(() => prop.set('second-change')).toThrow(/protected from change/)
+   })
+
+   it('should trigger onChange event when value changes', () => {
+      const onChange = jest.fn()
+      const prop = new BaseProperty({ name: 'test', onChange })
+
+      prop.set('updated')
+      expect(onChange).toHaveBeenCalled()
+   })
+
+   it('should transform values using the val() method', () => {
+      const prop = new BaseProperty({ name: 'test' })
+      prop.set(10)
+      const doubled = prop.val((v: number) => v * 2)
+      expect(doubled).toBe(20)
+   })
+
+   it('should clone the property correctly', () => {
+      const prop = new BaseProperty({ name: 'test' })
+      prop.set('original')
+      const cloned = prop.clone()
+
+      expect(cloned.name).toBe(prop.name)
+      expect(cloned.val()).toBe(prop.val())
+      expect(cloned).not.toBe(prop)
+   })
+
+   it('should return falsy values (0, false, "") correctly from val()', () => {
+      const propNum = new BaseProperty({ name: 'num', defaultValue: 10 })
+      propNum.set(0)
+      expect(propNum.val()).toBe(0)
+
+      const propBool = new BaseProperty({ name: 'bool', defaultValue: true })
+      propBool.set(false)
+      expect(propBool.val()).toBe(false)
+
+      const propStr = new BaseProperty({ name: 'str', defaultValue: 'default' })
+      propStr.set('')
+      expect(propStr.val()).toBe('')
+   })
+})

package/src/properties/BaseProperty.ts

@@ -0,0 +1,140 @@
+import { DataObjectClass } from '../components/types/DataObjectClass'
+import { AbstractPropertyType } from './types/AbstractPropertyType'
+import { PropertyClassType } from './types/PropertyClassType'
+import { PropertyHTMLType } from './types/PropertyHTMLType'
+
+export type EventTypes =
+   | typeof BaseProperty.EVENT_ONCHANGE
+   | typeof BaseProperty.EVENT_ONDELETE
+
+export interface BasePropertyType extends AbstractPropertyType {
+   parent?: DataObjectClass<any>
+   protected?: boolean
+   mandatory?: boolean
+   defaultValue?: any
+   htmlType?: PropertyHTMLType
+   onChange?: (dao: DataObjectClass<any>) => DataObjectClass<any>
+}
+
+export class BaseProperty implements PropertyClassType {
+   static TYPE = 'any'
+   static EVENT_ONCHANGE = 'onChange'
+   static EVENT_ONDELETE = 'onDelete'
+
+   protected _parent: DataObjectClass<any> | undefined
+   protected _id: string
+   protected _name: string
+   protected _value: any = undefined
+   protected _mandatory: boolean = false
+   protected _protected: boolean = false
+   protected _allows: string[] = []
+   protected _htmlType: PropertyHTMLType = 'off'
+   protected _defaultValue: any
+   protected _hasChanged: boolean
+   protected _events: {
+      [key: EventTypes]: Function
+   } = {}
+
+   constructor(config: BasePropertyType) {
+      this._parent = config.parent
+      this._id = config.id || config.name.toLowerCase()
+      this._name = config.name
+      this._protected = config.protected || false
+      this._mandatory = config.mandatory || false
+      this._defaultValue =
+         typeof config.defaultValue === 'function'
+            ? config.defaultValue()
+            : config.defaultValue
+      this._value = this._defaultValue
+      this._hasChanged = false
+      this._htmlType = config.htmlType || 'off'
+      if (typeof config.onChange === 'function') {
+         this._events.onChange = config.onChange
+      }
+   }
+
+   get name() {
+      return this._name
+   }
+
+   get mandatory() {
+      return this._mandatory
+   }
+
+   get protected() {
+      return this._protected
+   }
+
+   get allows() {
+      return this._allows
+   }
+
+   set htmlType(type: PropertyHTMLType) {
+      this._htmlType = type
+   }
+
+   get htmlType() {
+      return this._htmlType
+   }
+
+   get hasChanged() {
+      return this._hasChanged
+   }
+
+   set hasChanged(val: boolean) {
+      this._hasChanged = val
+   }
+
+   set(value: any, setChanged: boolean = true) {
+      if (
+         this._value !== undefined &&
+         this._value !== null &&
+         this._value !== this._defaultValue &&
+         this._protected === true
+      ) {
+         throw new Error(
+            `Value '${this._name}' already defined as '${this._value}' and protected from change`
+         )
+      }
+
+      if (
+         JSON.stringify({ value: value }) !==
+         JSON.stringify({ value: this._value })
+      ) {
+         this._value = value
+         this._hasChanged = setChanged
+      }
+
+      if (this._events[BaseProperty.EVENT_ONCHANGE]) {
+         this._events[BaseProperty.EVENT_ONCHANGE](this._parent)
+      }
+
+      return this
+   }
+
+   val(transform: any = undefined): any {
+      // console.log(transform && transform(this._value), typeof transform);
+      return typeof transform === 'function'
+         ? transform(this._value)
+         : this._value !== undefined
+         ? this._value
+         : this._defaultValue
+   }
+
+   protected _enable(value: boolean | undefined) {
+      return value === undefined || value === true
+   }
+
+   toJSON() {
+      return this._value
+   }
+
+   clone() {
+      const cloned = Object.create(
+         Object.getPrototypeOf(this),
+         Object.getOwnPropertyDescriptors(this)
+      )
+
+      return cloned
+   }
+}

package/src/properties/BooleanProperty.ts

@@ -0,0 +1,11 @@
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+
+export interface BooleanPropertyType extends BasePropertyType {}
+
+export class BooleanProperty extends BaseProperty {
+   static TYPE = 'boolean'
+
+   set(value: boolean, setChanged = true) {
+      return super.set(value, setChanged)
+   }
+}

package/src/properties/CollectionProperty.test.ts

@@ -0,0 +1,22 @@
+import { Entity } from '../components/Entity'
+import { User } from '../components/User'
+import { DataGenerator } from '../common/DataGenerator'
+import * as statuses from '../common/statuses'
+
+describe('Collection Property', () => {
+   test('can retrieve user records matching relation', async () => {
+   //    const entity = await Entity.factory()
+   //    const user = await User.factory()
+
+   //    // Generate 3 users not associated to any entity
+   //    await DataGenerator(user, 3, { status: statuses.CREATED })
+
+   //    // Generate 3 users associated with entity 1
+   //    await DataGenerator(user, 3, { status: statuses.CREATED, entity })
+
+   //    const value = await entity.val('users')
+   //    expect(value).toBeInstanceOf(Array)
+   //    expect(value.length).toBe(3)
+   //
+   })
+})

package/src/properties/CollectionProperty.ts

@@ -0,0 +1,43 @@
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+import { ObjectUri } from '../components/ObjectUri'
+import { Core } from '../Core'
+import { DataObjectClass } from '../components/types/DataObjectClass'
+import { BaseObject } from '../components/BaseObject'
+
+export interface CollectionPropertyType extends BasePropertyType {
+   instanceOf: typeof BaseObject
+   backend?: any
+   parentKey?: string
+}
+
+export class CollectionProperty extends BaseProperty {
+   static TYPE = 'collection'
+   protected _value:
+      | Array<any>
+      | Array<DataObjectClass<any>>
+      | Array<ObjectUri>
+      | undefined = undefined
+   protected _instanceOf: typeof BaseObject
+   protected _parentKey: string
+
+   constructor(config: CollectionPropertyType) {
+      super(config)
+      if (!config.instanceOf) {
+         throw new Error(`Parameter 'instanceOf' is mandatory`)
+      }
+      this._instanceOf =
+         typeof config.instanceOf === 'string'
+            ? Core.classRegistry[config.instanceOf]
+            : config.instanceOf
+      this._parentKey =
+         config.parentKey || this._parent?.uri?.collection || 'unknown'
+   }
+
+   set(value: Array<any>, setChanged = true) {
+      return super.set(value, setChanged)
+   }
+
+   toJSON() {
+      return this._value
+   }
+}

package/src/properties/DateTimeProperty.ts

@@ -0,0 +1,47 @@
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+
+export interface DateTimePropertyType extends BasePropertyType {
+   timezone?: string
+}
+
+export class DateTimeProperty extends BaseProperty {
+   static AS_IS = 'asis'
+   static UNIX_TIMESTAMP = 'unix_timestamp'
+
+   static TYPE = 'datetime'
+
+   static RETURN_AS: string = DateTimeProperty.AS_IS
+
+   protected _timezone: string
+
+   constructor(config: DateTimePropertyType) {
+      super(config)
+      this._timezone = config.timezone || 'Z'
+   }
+
+   set(value: string | Date | number, setChanged = true) {
+      if (value && DateTimeProperty.RETURN_AS === 'unix_timestamp') {
+         if (typeof value === 'string') {
+            // Parse date strings as UTC
+            // If the string already has timezone info (ends with Z or +/-offset), use as-is
+            // Otherwise, treat as UTC by appending 'Z'
+            let utcString = value.trim()
+            if (
+               !utcString.endsWith('Z') &&
+               !/[+-]\d{2}:\d{2}$/.test(utcString)
+            ) {
+               // Replace space with T for ISO format and append Z for UTC
+               utcString = utcString.replace(' ', 'T') + 'Z'
+            }
+            value = Date.parse(utcString)
+         } else if (typeof value === 'object') {
+            value = (value as Date).getTime()
+         }
+      }
+      return super.set(value, setChanged)
+   }
+
+   get timezone() {
+      return this._timezone
+   }
+}

package/src/properties/EnumProperty.ts

@@ -0,0 +1,36 @@
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+
+export interface EnumPropertyType extends BasePropertyType {
+   values?: string[]
+}
+
+export class EnumProperty extends BaseProperty {
+   static WILDCARD = '*'
+   static TYPE = 'enum'
+   protected _values: string[] = []
+
+   constructor(config: EnumPropertyType) {
+      super(config)
+      this._values = config.values || []
+   }
+
+   set(value: string, setChanged = true) {
+      if (
+         value !== null &&
+         (!this._values.includes(EnumProperty.WILDCARD) &&
+            !this._values.includes(value))
+      ) {
+         throw new Error(
+            `Value '${value}' is not acceptable, acceptable values are: ${this._values.join(
+               ', '
+            )}`
+         )
+      }
+
+      return super.set(value, setChanged)
+   }
+
+   get values() {
+      return this._values
+   }
+}

package/src/properties/FileProperty.ts

@@ -0,0 +1,14 @@
+import { ObjectUri } from '../components/ObjectUri'
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+import { BaseObjectClass } from '../components/types/BaseObjectClass'
+
+export interface FilePropertyType extends BasePropertyType {}
+
+export class FileProperty extends BaseProperty {
+   static TYPE = 'file'
+   _value: BaseObjectClass | ObjectUri | undefined = undefined
+
+   constructor(config: FilePropertyType) {
+      super(config)
+   }
+}

package/src/properties/HashProperty.test.ts

@@ -0,0 +1,108 @@
+import { HashProperty } from './HashProperty'
+
+describe('Hash Property supports MD5 algorithm', () => {
+   test('value is hashed with MD5', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_MD5,
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         '7682fe272099ea26efe39c890b33675b'
+      )
+   })
+   test('prefix can be added', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_MD5,
+         prefixed: true,
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         'md5-7682fe272099ea26efe39c890b33675b'
+      )
+   })
+   test('salt can be added', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_MD5,
+         salt: '123456',
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         '5560d200374e249898dcb68d5fa14117'
+      )
+   })
+})
+
+describe('Hash Property supports SHA1 algorithm', () => {
+   test('value is hashed with SHA1 and optional salt', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA1,
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         '58ad983135fe15c5a8e2e15fb5b501aedcf70dc2'
+      )
+   })
+   test('prefix can be added', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA1,
+         prefixed: true,
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         'sha1-58ad983135fe15c5a8e2e15fb5b501aedcf70dc2'
+      )
+   })
+   test('salt can be added', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA1,
+         salt: '123456',
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         '19ed93bb52146515d89fb3c223277b878fc0cd6c'
+      )
+   })
+})
+
+describe('Hash Property supports SHA256 algorithm', () => {
+   test('value is hashed with SHA256 and optional salt', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA256,
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         'aa3d2fe4f6d301dbd6b8fb2d2fddfb7aeebf3bec53ffff4b39a0967afa88c609'
+      )
+   })
+   test('prefix can be added', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA256,
+         prefixed: true,
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         'sha256-aa3d2fe4f6d301dbd6b8fb2d2fddfb7aeebf3bec53ffff4b39a0967afa88c609'
+      )
+   })
+   test('salt can be added', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA256,
+         salt: '123456',
+      })
+      expect(prop.set('azertyuiop').get()).toBe(
+         'fd0142a229c2924d50c20576ac5850d9f3165f56d7630b62ad6e66a99bf5adc4'
+      )
+   })
+})
+
+describe('Hash Property allows comparison of string and hash value', () => {
+   test('compare string with hash', () => {
+      const prop = new HashProperty({
+         name: 'hash',
+         algorithm: HashProperty.ALGORITHM_SHA256,
+      })
+      expect(prop.set('azertyuiop').compare('azertyuiop')).toBe(true)
+      expect(prop.set('azertyuiop').compare('qwertz')).toBe(false)
+   })
+})

package/src/properties/HashProperty.ts

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto'
+import { StringProperty, StringPropertyType } from './StringProperty'
+
+export type HashPropertyAlgos =
+   | typeof HashProperty.ALGORITHM_MD5
+   | typeof HashProperty.ALGORITHM_SHA1
+   | typeof HashProperty.ALGORITHM_SHA256
+   | typeof HashProperty.ALGORITHM_BCRYPT
+
+export interface HashPropertyType extends StringPropertyType {
+   algorithm?: HashPropertyAlgos
+   salt?: string
+   prefixed?: boolean
+}
+
+export class HashProperty extends StringProperty {
+   static TYPE = 'hash'
+   static ALGORITHM_MD5 = 'md5'
+   static ALGORITHM_SHA1 = 'sha1'
+   static ALGORITHM_SHA256 = 'sha256'
+   static ALGORITHM_BCRYPT = 'bcrypt'
+
+   protected _algorithm: HashPropertyAlgos
+   protected _salt: string = ''
+   protected _prefixed = false
+
+   constructor(config: HashPropertyType) {
+      super(config)
+      this._algorithm = config.algorithm || HashProperty.ALGORITHM_MD5
+      this._salt = config.salt || ''
+      this._prefixed = config.prefixed || false
+   }
+
+   _hash(value: string): string {
+      let algo
+      switch (this._algorithm) {
+         case HashProperty.ALGORITHM_MD5:
+            algo = createHash('md5')
+            break
+
+         case HashProperty.ALGORITHM_SHA1:
+            algo = createHash('sha1')
+            break
+
+         case HashProperty.ALGORITHM_SHA256:
+            algo = createHash('sha256')
+            break
+
+         default:
+            throw new Error(
+               `Unsupported or missing hash algorithm: ${this._algorithm}`
+            )
+      }
+
+      let hash = this._prefixed ? `${this._algorithm}-` : ''
+      hash += algo.update(`${this._salt}${value}`).digest('hex')
+
+      this._rawValue = false // don't test some constraints after hashing
+
+      return hash
+   }
+
+   set(value: string, setChanged = true) {
+      return super.set(this._hash(value), setChanged)
+   }
+
+   compare(value: string): boolean {
+      return this._hash(value) === this._value
+   }
+}

package/src/properties/MapProperty.ts

@@ -0,0 +1,19 @@
+import { BaseProperty, BasePropertyType } from './BaseProperty'
+
+export interface MapPropertyType extends BasePropertyType {}
+
+export class MapProperty extends BaseProperty {
+   static TYPE = 'map'
+
+   set(value: any, setChanged = true) {
+      if (typeof value! !== 'object') {
+         throw new Error(`value ${JSON.stringify(value)} is not an object`)
+      }
+
+      return super.set(value, setChanged)
+   }
+
+   toJSON() {
+      return this._value ? JSON.stringify(this._value) : {}
+   }
+}