@api-client/core 0.14.1 → 0.14.3

package/src/modeling/ApiModel.ts

@@ -0,0 +1,327 @@
+import { nanoid } from '../nanoid.js'
+import { ApiModelKind } from '../models/kinds.js'
+import { type IThing, Thing } from '../models/Thing.js'
+import type {
+  AccessRule,
+  AuthenticationConfiguration,
+  AuthorizationConfiguration,
+  ExposedEntity,
+  ForeignDomainDependency,
+  RateLimitingConfiguration,
+  SessionConfiguration,
+} from './types.js'
+import { DataDomain, type DataDomainSchema } from './DataDomain.js'
+
+export interface ApiModelSchema {
+  /**
+   * The data domain kind recognizable by the ecosystem.
+   */
+  kind: typeof ApiModelKind
+  /**
+   * The unique key of the data domain schema.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+  /**
+   * Contains the name, display name, description, and the version of the data domain schema.
+   */
+  info: IThing
+
+  /**
+   * The designated Data Entity that represents a "User".
+   * This entity must be marked with the "User" semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  userKey?: string
+
+  /**
+   * Reference to the stable, version-controlled data definition from the
+   * Data Catalog. When not set, the model cannot be published.
+   */
+  domain?: ForeignDomainDependency
+
+  /**
+   * Configuration for how users prove their identity.
+   * The API model is invalid if this is not set.
+   */
+  authentication?: AuthenticationConfiguration
+
+  /**
+   * Configuration for what authenticated users are allowed to do.
+   * The API model is invalid if this is not set.
+   */
+  authorization?: AuthorizationConfiguration
+
+  /**
+   * Configuration for the transport and payload of the user session.
+   * The API model is invalid if this is not set.
+   */
+  session?: SessionConfiguration
+  /**
+   * The specific subset of Data Entities to be exposed by this API.
+   * These are the entities that are included in the data domain schema.
+   */
+  exposes: ExposedEntity[]
+
+  /**
+   * Optional array of access rules that define the access control policies
+   * for the API. These rules are used to enforce security and permissions
+   * on the exposed entities.
+   *
+   * These rules apply to all exposed entities and actions. An API action
+   * can declare its own access rules, which will override these.
+   */
+  accessRule?: AccessRule[]
+  /**
+   * Optional configuration for API-wide rate limiting and throttling.
+   * Defines rules to protect the API from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+}
+
+export class ApiModel extends EventTarget {
+  /**
+   * The data domain kind recognizable by the ecosystem.
+   */
+  kind: typeof ApiModelKind
+  /**
+   * The unique key of the data domain schema.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+
+  /**
+   * The description of the domain property.
+   */
+  info: Thing
+  /**
+   * The designated Data Entity that represents a "User".
+   * This entity must be marked with the "User" semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  userKey?: string
+
+  /**
+   * Reference to the stable, version-controlled data definition from the
+   * Data Catalog. When not set, the model cannot be published.
+   */
+  domain?: ForeignDomainDependency
+
+  /**
+   * Configuration for how users prove their identity.
+   * The API model is invalid if this is not set.
+   */
+  authentication?: AuthenticationConfiguration
+
+  /**
+   * Configuration for what authenticated users are allowed to do.
+   * The API model is invalid if this is not set.
+   */
+  authorization?: AuthorizationConfiguration
+
+  /**
+   * Configuration for the transport and payload of the user session.
+   * The API model is invalid if this is not set.
+   */
+  session?: SessionConfiguration
+  /**
+   * The specific subset of Data Entities to be exposed by this API.
+   * These are the entities that are included in the data domain schema.
+   */
+  exposes: ExposedEntity[]
+  /**
+   * Optional array of access rules that define the access control policies
+   * for the API. These rules are used to enforce security and permissions
+   * on the exposed entities.
+   *
+   * These rules apply to all exposed entities and actions. An API action
+   * can declare its own access rules, which will override these.
+   */
+  accessRule?: AccessRule[]
+  /**
+   * Optional configuration for API-wide rate limiting and throttling.
+   * Defines rules to protect the API from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+
+  /**
+   * When the initializing flag is set to true,
+   * the domain is not notified of changes.
+   */
+  #initializing = true
+
+  /**
+   * When the notifying flag is set to true,
+   * the domain is pending a notification.
+   * No other notifications will be sent until
+   * the current notification is sent.
+   */
+  #notifying = false
+
+  /**
+   * A reference to the published data domain.
+   */
+  dataDomain?: DataDomain
+
+  static createSchema(input: Partial<ApiModelSchema> = {}): ApiModelSchema {
+    const { key = nanoid(), exposes = [] } = input
+    const info = Thing.fromJSON(input.info, { name: 'Unnamed API' }).toJSON()
+    const result: ApiModelSchema = {
+      kind: ApiModelKind,
+      key,
+      info,
+      exposes,
+    }
+    if (input.userKey) {
+      result.userKey = input.userKey
+    }
+    if (input.domain) {
+      result.domain = input.domain
+    }
+    if (input.authentication) {
+      result.authentication = input.authentication
+    }
+    if (input.authorization) {
+      result.authorization = input.authorization
+    }
+    if (input.session) {
+      result.session = input.session
+    }
+    if (input.accessRule) {
+      result.accessRule = input.accessRule
+    }
+    if (input.rateLimiting) {
+      result.rateLimiting = input.rateLimiting
+    }
+    return result
+  }
+
+  constructor(state?: Partial<ApiModelSchema>, domain?: DataDomainSchema) {
+    super()
+    const init = ApiModel.createSchema(state)
+    this.kind = init.kind
+    this.key = init.key
+    this.info = new Thing(init.info)
+    this.userKey = init.userKey
+    if (init.domain) {
+      this.domain = structuredClone(init.domain)
+    }
+    if (init.authentication) {
+      this.authentication = structuredClone(init.authentication)
+    }
+    if (init.authorization) {
+      this.authorization = structuredClone(init.authorization)
+    }
+    if (init.session) {
+      this.session = structuredClone(init.session)
+    }
+    if (Array.isArray(init.exposes)) {
+      this.exposes = structuredClone(init.exposes)
+    } else {
+      this.exposes = []
+    }
+    if (init.accessRule) {
+      this.accessRule = structuredClone(init.accessRule)
+    }
+    if (init.rateLimiting) {
+      this.rateLimiting = structuredClone(init.rateLimiting)
+    }
+    if (domain) {
+      this.dataDomain = new DataDomain(domain)
+    }
+    this.#initializing = false
+    this.info.addEventListener('change', () => {
+      this.notifyChange()
+    })
+  }
+
+  toJSON(): ApiModelSchema {
+    const result: ApiModelSchema = {
+      kind: this.kind,
+      key: this.key,
+      info: this.info.toJSON(),
+      exposes: structuredClone(this.exposes),
+    }
+    if (this.userKey) {
+      result.userKey = this.userKey
+    }
+    if (this.domain) {
+      result.domain = structuredClone(this.domain)
+    }
+    if (this.authentication) {
+      result.authentication = structuredClone(this.authentication)
+    }
+    if (this.authorization) {
+      result.authorization = structuredClone(this.authorization)
+    }
+    if (this.session) {
+      result.session = structuredClone(this.session)
+    }
+    if (this.accessRule) {
+      result.accessRule = structuredClone(this.accessRule)
+    }
+    if (this.rateLimiting) {
+      result.rateLimiting = structuredClone(this.rateLimiting)
+    }
+    return result
+  }
+
+  /**
+   * This function is used internally by all domain elements to notify that something has changed.
+   * Since we want to notify listeners after the operation commits, we use microtask
+   * to ensure that the event is dispatched after the current operation.
+   */
+  notifyChange() {
+    if (this.#notifying || this.#initializing) {
+      return
+    }
+    this.#notifying = true
+    queueMicrotask(() => {
+      this.#notifying = false
+      const event = new Event('change')
+      this.dispatchEvent(event)
+    })
+  }
+
+  /**
+   * Exposes a new entity in the API model.
+   * If the entity already exists, it returns the existing one.
+   * @param entityKey The key of the entity to expose.
+   * @returns The exposed entity.
+   */
+  exposeEntity(entityKey: string): ExposedEntity {
+    const existing = this.exposes.find((e) => e.key === entityKey)
+    if (existing) {
+      return existing
+    }
+    const newEntity: ExposedEntity = {
+      key: entityKey,
+      actions: [],
+    }
+    this.exposes.push(newEntity)
+    this.notifyChange()
+    return newEntity
+  }
+
+  /**
+   * Removes an entity from the API model.
+   * @param entityKey The key of the entity to remove.
+   */
+  removeEntity(entityKey: string): void {
+    const index = this.exposes.findIndex((e) => e.key === entityKey)
+    if (index !== -1) {
+      this.exposes.splice(index, 1)
+      this.notifyChange()
+    }
+  }
+  /**
+   * Returns the exposed entity by its key.
+   * @param entityKey The key of the entity to find.
+   * @returns The exposed entity or undefined if not found.
+   */
+  getExposedEntity(entityKey: string): ExposedEntity | undefined {
+    return this.exposes.find((e) => e.key === entityKey)
+  }
+}

package/src/modeling/DataDomain.ts

@@ -134,7 +134,7 @@ export class DataDomain extends EventTarget {
   /**
    * The description of the domain property.
    */
-  accessor info: Thing
+  info: Thing
 
   /**
    * When the initializing flag is set to true,

package/src/modeling/DomainAssociation.ts

@@ -12,6 +12,26 @@ import type { AssociationTarget, DomainGraphEdge } from './types.js'
 import { ShapeGenerator } from './amf/ShapeGenerator.js'
 import { DataSemantics, isAssociationSemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
 
+/**
+ * Defines the behavior when a parent entity in an association is deleted.
+ *
+ * - `restrict`: Prevents the deletion of a parent entity if it has any associated child entities.
+ *               The generated API should return a clear and specific error message (e.g., 409 Conflict).
+ *   - _Example_: Do not allow a Department to be deleted if it still has Employees.
+ * - `cascade`: Automatically deletes all associated child entities when the parent entity is deleted.
+ *   - _Example_: Deleting a User will also delete all their associated Posts and Comments.
+ * - `setNull`: Sets the foreign key of the associated child entities to NULL. This is only valid if the
+ *   association property on the child entity is nullable.
+ *   - _Example_: When a `Project` is deleted, the `project_id` on associated `Tasks` is set to NULL,
+ *   making them unassigned but not deleting them.
+ * - `doNothing`: No action is taken on the associated child entities when the parent entity is deleted.
+ *   - _Example_: Deleting a `Category` does not affect associated `Products`, which remain in the database
+ *               but may become orphaned.
+ *               This is useful when the association is optional or when child entities should not be deleted
+ *               or modified upon the deletion of a parent entity.
+ */
+export type OnDeleteRule = 'restrict' | 'cascade' | 'setNull' | 'doNothing'
+
 export interface DomainAssociationSchema extends DomainElementSchema {
   kind: typeof DomainAssociationKind
   /**
@@ -54,6 +74,14 @@ export interface DomainAssociationSchema extends DomainElementSchema {
    * describe the association in more detail.
    */
   semantics?: AppliedDataSemantic[]
+  /**
+   * Defines the behavior when a parent entity in an association is deleted.
+   */
+  onDelete?: OnDeleteRule
+  /**
+   * Whether the association is read-only.
+   */
+  readOnly?: boolean
 }
 
 /**
@@ -153,6 +181,16 @@ export class DomainAssociation extends DomainElement {
    */
   @observed({ deep: true }) accessor semantics: AppliedDataSemantic[] = []
 
+  /**
+   * Defines the behavior when a parent entity in an association is deleted.
+   */
+  @observed() accessor onDelete: OnDeleteRule | undefined
+
+  /**
+   * Whether the association is read-only.
+   */
+  @observed() accessor readOnly: boolean | undefined
+
   /**
    * Creates a full data association schema with defaults.
    *
@@ -170,6 +208,12 @@ export class DomainAssociation extends DomainElement {
     if (Array.isArray(semantics)) {
       result.semantics = [...semantics]
     }
+    if (input.onDelete) {
+      result.onDelete = input.onDelete
+    }
+    if (typeof input.readOnly === 'boolean') {
+      result.readOnly = input.readOnly
+    }
     if (input.schema) {
       result.schema = structuredClone(input.schema)
     }
@@ -227,6 +271,12 @@ export class DomainAssociation extends DomainElement {
     } else {
       this.semantics = []
     }
+    if (init.onDelete) {
+      this.onDelete = init.onDelete
+    }
+    if (typeof init.readOnly === 'boolean') {
+      this.readOnly = init.readOnly
+    }
   }
 
   /**
@@ -258,6 +308,12 @@ export class DomainAssociation extends DomainElement {
     if (Array.isArray(this.semantics) && this.semantics.length) {
       result.semantics = toRaw(this, this.semantics)?.map((i) => structuredClone(i))
     }
+    if (this.onDelete) {
+      result.onDelete = this.onDelete
+    }
+    if (typeof this.readOnly === 'boolean' && this.readOnly) {
+      result.readOnly = this.readOnly
+    }
     return result
   }
 

package/src/modeling/DomainEntity.ts

@@ -165,7 +165,7 @@ export class DomainEntity extends DomainElement {
    */
   static createSchema(input: Partial<DomainEntitySchema> = {}): DomainEntitySchema {
     const { key = nanoid(), tags, semantics, fields, deprecated } = input
-    const info = Thing.fromJSON(input.info, { name: 'New entity' }).toJSON()
+    const info = Thing.fromJSON(input.info, { name: 'new_entity' }).toJSON()
     const result: DomainEntitySchema = {
       kind: DomainEntityKind,
       key,

package/src/modeling/DomainFile.ts

@@ -1,6 +1,4 @@
-import { nanoid } from '../nanoid.js'
 import { File, type IFile } from '../models/store/File.js'
-import { Thing } from '../models/Thing.js'
 import type { DataDomain, DataDomainSchema } from './DataDomain.js'
 import { DomainFileKind } from '../models/kinds.js'
 
@@ -30,46 +28,11 @@ export class DomainFile extends File {
     } else {
       final = input as DataDomainSchema
     }
-    const init: IDomainFile = {
-      kind: DomainFileKind,
-      key: final.key,
-      info: { ...final.info },
-      lastModified: { user: '', time: 0, byMe: false },
-      parents: [],
-      permissionIds: [],
-      permissions: [],
-    }
-    return new DomainFile(init)
+    return new DomainFile({ key: final.key, info: final.info })
   }
 
-  constructor(input?: string | IDomainFile) {
-    super()
-    let init: IDomainFile
-    if (typeof input === 'string') {
-      init = JSON.parse(input)
-    } else if (typeof input === 'object') {
-      init = input
-    } else {
-      init = {
-        kind: DomainFileKind,
-        key: nanoid(),
-        info: Thing.fromName('').toJSON(),
-        parents: [],
-        permissionIds: [],
-        permissions: [],
-        lastModified: { user: '', time: 0, byMe: false },
-      }
-    }
-    this.new(init)
-  }
-
-  override new(init: IDomainFile): this {
-    if (!DomainFile.isDomainFile(init)) {
-      throw new Error(`Not a data file.`)
-    }
-    super.new(init)
-    this.kind = DomainFileKind
-    return this
+  constructor(state: Partial<IDomainFile> = {}) {
+    super({ ...state, kind: DomainFileKind })
   }
 
   static isDomainFile(input: unknown): boolean {

package/src/modeling/Semantics.ts

@@ -1,3 +1,4 @@
+/* eslint-disable max-len */
 import type { DomainPropertyType } from './DataFormat.js'
 
 /**
@@ -9,24 +10,79 @@ export enum SemanticType {
   /**
    * Designates a Data Entity that represents users of the system.
    */
-  User = 'https://apinow.app/semantics/entities/#User',
+  User = 'Semantic#User',
 
   // Property-Level Semantics
-  CreatedTimestamp = 'https://apinow.app/semantics/properties/#CreatedTimestamp',
-  UpdatedTimestamp = 'https://apinow.app/semantics/properties/#UpdatedTimestamp',
-  DeletedTimestamp = 'https://apinow.app/semantics/properties/#DeletedTimestamp',
-  DeletedFlag = 'https://apinow.app/semantics/properties/#DeletedFlag',
-  PublicUniqueName = 'https://apinow.app/semantics/properties/#PublicUniqueName',
+  /**
+   * Annotates the field as the user password.
+   * The runtime should treat this field with special care,
+   * ensuring it is encrypted and not exposed in API responses.
+   */
+  Password = 'Semantic#Password',
+  /**
+   * Designates a Data Property as the `createdAt` timestamp of an entity.
+   * This is used to track when the entity was first created.
+   */
+  CreatedTimestamp = 'Semantic#CreatedTimestamp',
+  /**
+   * Designates a Data Property as the `updatedAt` timestamp of an entity.
+   * This is used to track when the entity was last modified.
+   */
+  UpdatedTimestamp = 'Semantic#UpdatedTimestamp',
+  /**
+   * Designates a Data Property as the `deletedAt` timestamp of an entity.
+   * This is used to track when the entity was soft-deleted.
+   * Soft-deletion means the entity is not physically removed from the database,
+   * but marked as deleted for logical deletion purposes.
+   */
+  DeletedTimestamp = 'Semantic#DeletedTimestamp',
+  /**
+   * Designates a Data Property as a boolean flag indicating whether the entity is deleted.
+   * This is used for soft-deletion, where the entity is not physically removed from the database,
+   * but marked as deleted.
+   */
+  DeletedFlag = 'Semantic#DeletedFlag',
+  /**
+   * Designates a Data Property as a unique public identifier for a resource.
+   * This is often used in URLs to provide a user-friendly way to access the resource.
+   * For example, a blog post might have a public unique name like "my-first-post".
+   */
+  PublicUniqueName = 'Semantic#PublicUniqueName',
+  /**
+   * Designates a Data Property as the `role` of a user within the system.
+   * This is used to define the user's permissions and access levels.
+   * For example, a user with the role of "admin" would have elevated permissions
+   * compared to a user with the role of "guest".
+   * Roles are defined on the entity as enums, or as a string property with a controlled vocabulary.
+   */
+  UserRole = 'Semantic#UserRole',
   // Association-Level Semantics
-  ResourceOwnerIdentifier = 'https://apinow.app/semantics/associations/#ResourceOwnerIdentifier',
+  /**
+   * Designates an association that links a resource to a "User" entity instance.
+   * This is used to indicate ownership of the resource for access control purposes.
+   * For example, a blog post might have a resource owner identifier that points to the user who created it.
+   */
+  ResourceOwnerIdentifier = 'Semantic#ResourceOwnerIdentifier',
 }
 
 /**
  * Defines the scope at which a semantic can be applied.
  */
 export enum SemanticScope {
+  /**
+   * The semantic applies to an entire Data Entity.
+   * This is used for semantics that provide context or constraints at the entity level.
+   */
   Entity = 'Entity',
+  /**
+   * The semantic applies to a single Data Property.
+   * This is used for semantics that provide context or constraints at the property level.
+   */
   Property = 'Property',
+  /**
+   * The semantic applies to an Association between Data Entities.
+   * This is used for semantics that provide context or constraints at the association level.
+   */
   Association = 'Association',
 }
 
@@ -118,6 +174,14 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
   },
 
   // Property-Level Definitions
+  [SemanticType.Password]: {
+    id: SemanticType.Password,
+    displayName: 'User Password',
+    scope: SemanticScope.Property,
+    description:
+      'Annotates the field as the user password. The runtime should treat this field with special care, ensuring it is encrypted and not exposed in API responses.',
+    applicableDataTypes: ['string'],
+  },
   [SemanticType.CreatedTimestamp]: {
     id: SemanticType.CreatedTimestamp,
     displayName: 'Creation Timestamp',
@@ -159,6 +223,14 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'A user-friendly, unique public identifier for a resource, often used in URLs.',
     applicableDataTypes: ['string'],
   },
+  [SemanticType.UserRole]: {
+    id: SemanticType.UserRole,
+    displayName: 'User Role Field',
+    scope: SemanticScope.Property,
+    description:
+      'A text field that is recognized by the runtime as a role of a user in the API. Used with the role-based authorization strategy.',
+    applicableDataTypes: ['string'],
+  },
 }
 
 /**

package/src/modeling/amf/ShapeGenerator.ts

@@ -107,7 +107,7 @@ export class ShapeGenerator {
    * const amfShape = generator.entity(myDomainEntity);
    * ```
    */
-  entity(input: DomainEntity, visited: Set<string> = new Set<string>()): IApiNodeShape | IApiRecursiveShape {
+  entity(input: DomainEntity, visited = new Set<string>()): IApiNodeShape | IApiRecursiveShape {
     if (visited.has(input.key)) {
       // create a recursive shape.
       return this.createRecursiveShape(input)