@api-client/core 0.11.11 → 0.12.0

package/src/modeling/{DataProperty.ts → legacy/DataProperty.ts}

@@ -1,11 +1,11 @@
 import { Json } from '@api-client/json'
-import { IThing, Thing } from '../models/Thing.js'
-import v4 from '../lib/uuid.js'
+import { IThing, Thing } from '../../models/Thing.js'
+import v4 from '../../lib/uuid.js'
 import { DataNamespace } from './DataNamespace.js'
-import { IApiPropertyShape } from '../amf/definitions/Shapes.js'
-import { AmfShapeGenerator } from '../amf/AmfShapeGenerator.js'
-import { PropertyBinding, PropertyBindings, PropertyWebBindings } from './Bindings.js'
-import { DataPropertyKind } from '../models/kinds.js'
+import { IApiPropertyShape } from '../../amf/definitions/Shapes.js'
+import { AmfShapeGenerator } from '../../amf/AmfShapeGenerator.js'
+import { PropertyBinding, PropertyBindings, PropertyWebBindings } from '../Bindings.js'
+import { DataPropertyKind } from '../../models/kinds.js'
 import {
   type BinaryFormat,
   BinaryFormats,
@@ -17,11 +17,12 @@ import {
   DataPropertyTypes,
   type NumberFormat,
   NumberFormats,
-} from './DataFormat.js'
+} from '../DataFormat.js'
 import type { DataEntity } from './DataEntity.js'
 
 /**
  * Describes the default value set on a property schema.
+ * @deprecated
  */
 export interface SchemaDefaultValue {
   /**
@@ -41,6 +42,7 @@ export interface SchemaDefaultValue {
 /**
  * A general schema definition for a property.
  * This is propagated to all bindings (when they support these properties).
+ * @deprecated
  */
 export interface DataPropertySchema {
   /**
@@ -109,6 +111,9 @@ export interface DataPropertySchema {
   examples?: string[]
 }
 
+/**
+ * @deprecated
+ */
 export interface IDataProperty {
   kind: typeof DataPropertyKind
   /**
@@ -180,6 +185,9 @@ export interface IDataProperty {
   bindings?: PropertyBinding[]
 }
 
+/**
+ * @deprecated
+ */
 export class DataProperty {
   kind = DataPropertyKind
 

package/src/modeling/observed.ts

@@ -0,0 +1,267 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const reactiveSymbol = Symbol('reactive')
+const proxySymbol = Symbol('proxy')
+
+interface DomainInstance {
+  domain?: { notifyChange(): void }
+  notifyChange?: () => void
+}
+
+export interface PropertyDecorator {
+  // accessor decorator signature
+  <C extends DomainInstance, V>(
+    target: ClassAccessorDecoratorTarget<C, V>,
+    context: ClassAccessorDecoratorContext<C, V>
+  ): ClassAccessorDecoratorResult<C, V>
+  // setter decorator signature
+  <C extends DomainInstance, V>(
+    target: (value: V) => void,
+    context: ClassSetterDecoratorContext<C, V>
+  ): (this: C, value: V) => void
+}
+
+type StandardPropertyContext<C, V> = ClassAccessorDecoratorContext<C, V> | ClassSetterDecoratorContext<C, V>
+type StandardPropertyTarget<C, V> = ClassAccessorDecoratorTarget<C, V> | ((value: V) => void)
+
+export interface ObserveConfig {
+  /**
+   * To be used when observing an object and not a primitive.
+   * It creates a proxy that observes changes in the object.
+   */
+  deep?: boolean
+}
+
+/**
+ * Reads the raw value of the object, that is, not proxied object.
+ * @param source The source object that contains the object
+ * @param target The target object set on the source object
+ * @returns The not proxied object or undefined
+ */
+export function toRaw<T extends object = object>(source: object, target: T): T | undefined {
+  const proxies = Reflect.get(source, proxySymbol) as Map<object, object>
+  if (!proxies) {
+    return undefined
+  }
+  for (const [key, value] of proxies.entries()) {
+    if (value === target) {
+      return key as T
+    }
+  }
+}
+
+/**
+ * Turns a class property or a setter into an observed property
+ * that notifies the root domain when changed.
+ *
+ * A property has to be declared with the `accessor` type to be
+ * observed.
+ *
+ * ```typescript
+ * @observed() accessor name: string | undefined
+ *
+ * @observed()
+ * set height(value: number) {
+ *   this.#height = value
+ * }
+ *
+ * get height(): number {
+ *   return this.#height
+ * }
+ * ```
+ *
+ * The decorator can be used in the following ways:
+ * - As a class property decorator
+ * - As a class setter decorator
+ *
+ * The property class either has to have a `root` property
+ * or a `notifyChange` method. The decorator will call the
+ * `notifyChange` method if it exists. Otherwise, it will
+ * call the `notifyChange` method of the root domain.
+ */
+export function observed(config: ObserveConfig = {}): PropertyDecorator {
+  return <C extends DomainInstance, V>(
+    target: StandardPropertyTarget<C, V>,
+    context: StandardPropertyContext<C, V>
+  ): any => {
+    const { kind } = context
+    const { deep } = config
+
+    function createDeepProxy(this: DomainInstance, obj: unknown, notifyChange: () => void): any {
+      if (typeof obj !== 'object' || obj === null) {
+        return obj
+      }
+      // instead of using the target object to store the proxy info, we
+      // reflect the proxy info to the object itself. This way we can
+      // keep the stored values clean, which helps with testing (deep equal would include symbols)
+      // Keys are original objects, values are proxies
+      let proxies = Reflect.get(this, proxySymbol) as Map<object, object>
+      if (!proxies) {
+        proxies = new Map()
+        Reflect.set(this, proxySymbol, proxies)
+      }
+
+      if (proxies.has(obj)) {
+        return obj
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      const targetObject = this
+
+      const proxy = new Proxy(obj, {
+        get(target, prop) {
+          const value = Reflect.get(target, prop)
+          return createDeepProxy.bind(targetObject)(value, notifyChange)
+        },
+        set(target, prop, value) {
+          const oldValue = Reflect.get(target, prop)
+          if (oldValue !== value) {
+            Reflect.set(target, prop, value)
+            notifyChange()
+          }
+          return true
+        },
+        deleteProperty(target, prop) {
+          Reflect.deleteProperty(target, prop)
+          notifyChange()
+          return true
+        },
+      })
+      proxies.set(obj, proxy)
+      return proxy
+    }
+
+    if (kind === 'accessor') {
+      return {
+        set(this: DomainInstance, value: V): void {
+          let map = Reflect.get(this, reactiveSymbol)
+          if (!map) {
+            map = {}
+            Reflect.set(this, reactiveSymbol, map)
+          }
+          if (map[context.name] === context.name) {
+            return
+          }
+          const notify = () => {
+            if (this.domain) {
+              this.domain.notifyChange()
+            } else if (this.notifyChange) {
+              this.notifyChange()
+            }
+          }
+          if (deep) {
+            value = createDeepProxy.bind(this)(value, notify)
+          }
+          if (value === undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete map[context.name]
+          } else {
+            map[context.name] = value
+          }
+          notify()
+        },
+
+        get(): V {
+          const map = Reflect.get(this, reactiveSymbol) || {}
+          return map[context.name]
+        },
+      }
+    } else if (kind === 'setter') {
+      const { name } = context
+      return function (this: DomainInstance, value: V): void {
+        const oldValue = this[name as keyof DomainInstance]
+        if (value === oldValue) {
+          return
+        }
+        const notify = () => {
+          if (this.domain) {
+            this.domain.notifyChange()
+          } else if (this.notifyChange) {
+            this.notifyChange()
+          }
+        }
+        ;(target as (value: V) => void).call(this, value)
+        notify()
+      }
+    }
+    throw new Error(`Unsupported decorator location: ${kind}`)
+  }
+}
+
+/**
+ * A decorator that can be used to retarget the change event
+ * of a property to the root domain.
+ *
+ * This decorator should not be used with the `observed` decorator.
+ * It does the same thing. It will notify about a change to the
+ * property itself.
+ */
+export function retargetChange() {
+  return <C extends DomainInstance, V extends EventTarget>(
+    target: StandardPropertyTarget<C, V>,
+    context: StandardPropertyContext<C, V>
+  ): any => {
+    const { kind } = context
+    function observer(this: DomainInstance) {
+      if (this.domain) {
+        this.domain.notifyChange()
+      }
+    }
+    let binding: ((this: DomainInstance) => void) | undefined
+    if (kind === 'accessor') {
+      return {
+        set(this: DomainInstance, value: V): void {
+          let map = Reflect.get(this, reactiveSymbol)
+          if (!map) {
+            map = {}
+            Reflect.set(this, reactiveSymbol, map)
+          }
+          if (map[context.name] === context.name) {
+            return
+          }
+          const oldValue = map[context.name]
+          if (oldValue === value) {
+            return
+          }
+          if (value === undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete map[context.name]
+          } else {
+            map[context.name] = value
+          }
+          if (oldValue && binding) {
+            oldValue.removeEventListener('change', binding)
+          }
+          if (value) {
+            binding = observer.bind(this)
+            value.addEventListener('change', binding)
+          }
+          if (this.domain) {
+            this.domain.notifyChange()
+          }
+        },
+
+        get(): V {
+          const map = Reflect.get(this, reactiveSymbol) || {}
+          return map[context.name]
+        },
+      }
+    } else if (kind === 'setter') {
+      const { name } = context
+      return function (this: DomainInstance, value: V): void {
+        const oldValue = this[name as keyof DomainInstance] as unknown as V
+        if (value === oldValue) {
+          return
+        }
+        ;(target as (value: V) => void).call(this, value)
+        if (oldValue && binding) {
+          oldValue.removeEventListener('change', binding)
+        }
+        if (value) {
+          binding = observer.bind(this)
+          value.addEventListener('change', binding)
+        }
+      }
+    }
+    throw new Error(`Unsupported decorator location: ${kind}`)
+  }
+}

package/src/modeling/types.ts

@@ -1,6 +1,13 @@
+import type { Graph, GraphJson } from '@api-client/graph'
+import type { DomainAssociation } from './DomainAssociation.js'
+import type { DomainEntity } from './DomainEntity.js'
+import type { DomainModel } from './DomainModel.js'
+import type { DomainNamespace } from './DomainNamespace.js'
+import type { DomainProperty } from './DomainProperty.js'
+
 export interface DataDomainRemoveOptions {
   /**
-   * When true, the object will be forcebly removed.
+   * When true, the object will be forcibly removed.
    * The resolution defined in the `ImpactResolution` class will be applied.
    *
    * For example, when removing an entity that is a parent to another entity, it will
@@ -11,3 +18,169 @@ export interface DataDomainRemoveOptions {
    */
   force?: boolean
 }
+
+export interface AssociationAddOptions {
+  /**
+   * When set, it is the the association target's origin data domain.
+   * The key of the target data domain where this target entity is defined.
+   * Only used when `key` is specified.
+   */
+  domain?: string
+  /**
+   * The key of the association target, if known.
+   * If the target of the association is not specified, and the association has no other targets,
+   * the association is ignored in the namespace while processing.
+   */
+  key?: string
+}
+
+export interface DomainGraphEdge {
+  /**
+   * Indicates that the edge is to or from a foreign domain.
+   */
+  foreign?: boolean
+  /**
+   * The key of the foreign domain. Always set with the `foreign` property.
+   */
+  domain?: string
+  /**
+   * The type of the edge.
+   * - `association` The edge is to an association object.
+   *   - When coming **from** an entiry (the `v` property), that entity owns the association.
+   *   - When coming **to** an entity (the `w` property), that entity is the target of the association.
+   *     An association can have multiple targets.
+   * - `property` The edge is to a property object. Can only be created between an entity and a property.
+   *   - The **from** (`v`) is the entity.
+   *   - The **to** (`w`) is the property.
+   * - `parent` The edge is to a parent object.
+   *   - The **from** (`v`) is the child entity.
+   *   - The **to** (`w`) is the parent entity.
+   */
+  type: 'association' | 'property' | 'parent'
+}
+
+export type DomainGraphNodeType = DomainNamespace | DomainModel | DomainEntity | DomainProperty | DomainAssociation
+
+/**
+ * An interface that describes the data domain dependency.
+ */
+export interface ForeignDomainDependency {
+  /**
+   * The system registered key of the foreign domain.
+   */
+  key: string
+  /**
+   * The version of the foreign domain used in this domain.
+   */
+  version: string
+}
+
+export interface AssociationTarget {
+  /**
+   * The key of the target entity.
+   */
+  key: string
+  /**
+   * The key of the target data domain.
+   * This is only set when the target is in a different data domain.
+   */
+  domain?: string
+}
+
+/**
+ * Describes the default value set on a property schema.
+ */
+export interface SchemaDefaultValue {
+  /**
+   * The type of the default value.
+   *
+   * - `literal` The `value` should be used as-is.
+   * - `function` The value represents the name of the function to be used.
+   */
+  type: 'literal' | 'function'
+  /**
+   * The actual value type depends on the `type`.
+   * It is always a string and it has to be casted to the property's data type.
+   */
+  value: string
+}
+
+/**
+ * A general schema definition for a property.
+ * This is propagated to all bindings (when they support these properties).
+ */
+export interface PropertySchema {
+  /**
+   * The minimum value of the property.
+   *
+   * By default it is inclusive value. Use the `exclusiveMinimum` property to make it exclusive.
+   *
+   * Used with:
+   * - string
+   * - number
+   * - date
+   * - time
+   * - datetime
+   */
+  minimum?: number
+  /**
+   * The maximum value of the property.
+   *
+   * By default it is inclusive value. Use the `exclusiveMaximum` property to make it exclusive.
+   *
+   * Used with:
+   * - string
+   * - number
+   * - date
+   * - time
+   * - datetime
+   */
+  maximum?: number
+  /**
+   * When set, the minimum value is exclusive.
+   *
+   * - When `false`: value ≥ minimum.
+   * - When `true`: value > minimum.
+   */
+  exclusiveMinimum?: boolean
+  /**
+   * When set, the exclusiveMaximum value is exclusive.
+   *
+   * - When `false`: value ≤ maximum.
+   * - When `true`: value < minimum.
+   */
+  exclusiveMaximum?: boolean
+  /**
+   * The multiplier value for a number scalar.
+   *
+   * Examples:
+   * - if `1` then every integer is allowed
+   * - if `2` than every even number is allowed
+   * - if `0.5` than every number dividable by `0.5` is allowed
+   */
+  multipleOf?: number
+  /**
+   * The enum values for the property.
+   * They are always encoded as strings. The actual type is defined in the `dataType` property.
+   */
+  enum?: string[]
+  /**
+   * The default value for the property.
+   * This is always encoded as a string. The actual type is defined in the `dataType` property.
+   */
+  defaultValue?: SchemaDefaultValue
+  /**
+   * The example values for the property.
+   * They are always encoded as strings. The actual type is defined in the `dataType` property.
+   */
+  examples?: string[]
+}
+
+/**
+ * The shortcut type for the data domain graph.
+ */
+export type DataDomainGraph = Graph<unknown, DomainGraphNodeType, DomainGraphEdge>
+/**
+ * The serialized version of the data domain graph.
+ */
+export type SerializedGraph = GraphJson<unknown, object, DomainGraphEdge>

package/src/models/Thing.ts

@@ -1,4 +1,6 @@
 import { ThingKind } from './kinds.js'
+import { ModelValidationOptions } from './types.js'
+import { observed } from '../modeling/observed.js'
 
 /**
  * An interface describing a base metadata of a thing.
@@ -28,31 +30,33 @@ export declare interface IThing {
   version?: string
 }
 
-export class Thing {
+export class Thing extends EventTarget {
   kind = ThingKind
   /**
    * The name of the thing.
    */
-  name?: string
+  @observed() accessor name: string | undefined
   /**
    * Optional value to overwrite the `name` in the UI.
    * The primary descriptive field is the `name`. The display name is only used in the presentation of the data.
    */
-  displayName?: string
+  @observed() accessor displayName: string | undefined
   /**
    * The description of the thing.
    */
-  description?: string
+  @observed() accessor description: string | undefined
   /**
    * The version number of the thing.
    */
-  version?: string
+  @observed() accessor version: string | undefined
 
   /**
    * Returns one in this order:
    * - displayName
    * - name
    * - 'Unnamed object'
+   *
+   * @deprecated Use `getLabel()` instead.
    */
   get renderLabel(): string {
     return this.displayName || this.name || 'Unnamed object'
@@ -69,10 +73,42 @@ export class Thing {
     return thing
   }
 
+  /**
+   * Creates a new thing instance.
+   *
+   * @param input The thing definition used to restore the state.
+   */
+  static fromJSON(input: Partial<IThing> = {}, defaults: Partial<IThing> = {}): Thing {
+    const result = new Thing()
+    const { name, displayName, description, version } = input || {}
+    if (typeof name === 'string') {
+      result.name = name
+    } else if (typeof defaults.name === 'string') {
+      result.name = defaults.name
+    }
+    if (typeof displayName === 'string') {
+      result.displayName = displayName
+    } else if (typeof defaults.displayName === 'string') {
+      result.displayName = defaults.displayName
+    }
+    if (description) {
+      result.description = description
+    } else if (typeof defaults.description === 'string') {
+      result.description = defaults.description
+    }
+    if (version) {
+      result.version = version
+    } else if (typeof defaults.version === 'string') {
+      result.version = defaults.version
+    }
+    return result
+  }
+
   /**
    * @param input The thing definition used to restore the state.
    */
   constructor(input?: string | IThing) {
+    super()
     let init: IThing
     if (typeof input === 'string') {
       init = JSON.parse(input)
@@ -103,6 +139,22 @@ export class Thing {
     this.version = version
   }
 
+  notifyChange(): void {
+    this.dispatchEvent(new Event('change'))
+  }
+
+  static validate(input: unknown, options: ModelValidationOptions = {}): boolean {
+    const { strict } = options
+    if (input && typeof input === 'object') {
+      const typed = input as IThing
+      if (strict && typed.kind !== ThingKind) {
+        return false
+      }
+      return true
+    }
+    return false
+  }
+
   /**
    * Checks whether the input is a definition of a server.
    */
@@ -132,4 +184,17 @@ export class Thing {
     }
     return result
   }
+
+  /**
+   * Returns one in this order:
+   * - `this.displayName`
+   * - `this.name`
+   * - `defaultName`
+   * - 'Unnamed object'
+   *
+   * @param defaultName The default name to use when no other is available.
+   */
+  getLabel(defaultName?: string): string {
+    return this.displayName || this.name || defaultName || 'Unnamed object'
+  }
 }

package/src/models/kinds.ts

@@ -2,16 +2,42 @@ export const ProjectFolderKind = 'Core#ProjectFolder'
 export const ResponseKind = 'Core#HttpResponse'
 export const HttpResponseKind = 'Core#HttpResponse'
 export const CertificateFileKind = 'Core#CertificateFile'
-export const DataNamespaceKind = 'Core#DataNamespace'
-export const DataModelKind = 'Core#DataModel'
-export const DataEntityKind = 'Core#DataEntity'
-export const DataAssociationKind = 'Core#DataAssociation'
-export const DataPropertyKind = 'Core#DataProperty'
 export const FolderKind = 'Core#Folder'
 export const ProjectKind = 'Core#Project'
 export const ThingKind = 'Core#Thing'
-export const DataFileKind = 'Core#DataFile'
 export const DeletionKind = 'Core#Deletion'
 export const RevisionKind = 'Core#Revision'
 export const UnresolvedDependencyKind = 'Core#UnresolvedDependency'
 export const UserKind = 'Core#User'
+export const DomainFileKind = 'Data#DomainFile'
+export const DataDomainKind = 'Data#Domain'
+export const DomainNamespaceKind = 'Domain#Namespace'
+export const DomainModelKind = 'Domain#Model'
+export const DomainEntityKind = 'Domain#Entity'
+export const DomainAssociationKind = 'Domain#Association'
+export const DomainPropertyKind = 'Domain#Property'
+
+/**
+ * @deprecated Not used anymore.
+ */
+export const DataFileKind = 'Core#DataFile'
+/**
+ * @deprecated Not used anymore.
+ */
+export const DataNamespaceKind = 'Data#DataNamespace'
+/**
+ * @deprecated Not used anymore.
+ */
+export const DataModelKind = 'Data#DataModel'
+/**
+ * @deprecated Not used anymore.
+ */
+export const DataEntityKind = 'Data#DataEntity'
+/**
+ * @deprecated Not used anymore.
+ */
+export const DataAssociationKind = 'Data#DataAssociation'
+/**
+ * @deprecated Not used anymore.
+ */
+export const DataPropertyKind = 'Data#DataProperty'