@api-client/core 0.19.16 → 0.19.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.19.16",
+  "version": "0.19.18",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/exceptions/exception.ts

@@ -1,3 +1,8 @@
+/**
+ * A serialized representation of an Exception.
+ * Provides a standardized structure for pure data objects,
+ * typically used when converting errors for JSON responses.
+ */
 export interface ExceptionSchema {
   name: string
   message: string
@@ -75,39 +80,49 @@ export class Exception extends Error {
    */
   static fromRawException(init: object, defaultMessage: string): Exception {
     const typed = init as Record<string, string | number>
-    const options: ErrorOptions & { code?: string; status?: number } = {}
-    if (typed.code) {
-      options.code = typed.code as string
+    const options: ErrorOptions & { code?: string; status?: number; help?: string } = {}
+    if (typed.code !== undefined) {
+      options.code = String(typed.code)
     }
-    if (typed.status) {
-      options.status = Number(typed.status)
+    if (typed.status !== undefined) {
+      const parsedStatus = Number(typed.status)
+      if (!isNaN(parsedStatus)) {
+        options.status = parsedStatus
+      }
     }
-    const message = typed.message ?? defaultMessage
-    const result = new this(message as string, options)
-    if (typed.help) {
-      result.setHelp(typed.help as string)
+    if (typed.help !== undefined) {
+      options.help = String(typed.help)
     }
-    if (typed.name) {
-      result.name = typed.name as string
+    const message = typed.message !== undefined ? String(typed.message) : defaultMessage
+    const result = new this(message, options)
+    if (typed.name !== undefined) {
+      result.name = String(typed.name)
     }
     return result
   }
 
+  /**
+   * Initializes a new Exception instance.
+   *
+   * @param message - The primary human-readable error message.
+   * @param options - Additional properties configuration. Accepts standard `ErrorOptions`
+   * (like `cause`), plus custom `code`, `status`, and `help`.
+   */
   constructor(message?: string, options?: ErrorOptions & { code?: string; status?: number; help?: string }) {
     super(message, options)
 
     const ErrorConstructor = this.constructor as typeof Exception
 
     this.name = ErrorConstructor.name
-    this.message = message || ErrorConstructor.message || ''
-    this.status = options?.status || ErrorConstructor.status || 500
+    this.message = message ?? ErrorConstructor.message ?? ''
+    this.status = options?.status ?? ErrorConstructor.status ?? 500
 
-    const code = options?.code || ErrorConstructor.code
+    const code = options?.code ?? ErrorConstructor.code
     if (code !== undefined) {
       this.code = code
     }
 
-    const help = options?.help || ErrorConstructor.help
+    const help = options?.help ?? ErrorConstructor.help
     if (help !== undefined) {
       this.help = help
     }
@@ -115,25 +130,53 @@ export class Exception extends Error {
     Error.captureStackTrace(this, ErrorConstructor)
   }
 
+  /**
+   * Assigns a human-readable help description for troubleshooting and returns
+   * the exception instance to allow for method chaining.
+   *
+   * @param help - The detailed help informational text.
+   * @returns The current exception instance.
+   */
   setHelp(help: string): this {
     this.help = help
     return this
   }
 
+  /**
+   * Assigns a programmatic error code and returns the exception instance
+   * to allow for method chaining.
+   *
+   * @param code - The string error code (e.g., 'E_FILE_NOT_FOUND').
+   * @returns The current exception instance.
+   */
   setCode(code: string): this {
     this.code = code
     return this
   }
 
+  /**
+   * Assigns an HTTP-style status code and returns the exception instance
+   * to allow for method chaining.
+   *
+   * @param status - The numeric status code (e.g., 404, 500).
+   * @returns The current exception instance.
+   */
   setStatus(status: number): this {
     this.status = status
     return this
   }
 
+  /**
+   * Provides the string tag used by `Object.prototype.toString`.
+   */
   get [Symbol.toStringTag]() {
     return this.constructor.name
   }
 
+  /**
+   * Computes a string representation of the exception, including the
+   * programmatic code if one is defined.
+   */
   override toString(): string {
     if (this.code) {
       return `${this.name} [${this.code}]: ${this.message}`
@@ -141,6 +184,12 @@ export class Exception extends Error {
     return `${this.name}: ${this.message}`
   }
 
+  /**
+   * Serializes the exception into a plain JavaScript object.
+   * This ensures safe passing across boundaries and correct format in JSON responses.
+   *
+   * @returns The serialized exception object matching `ExceptionSchema`.
+   */
   toJSON(): ExceptionSchema {
     const result: ExceptionSchema = {
       name: this.name,
@@ -158,3 +207,58 @@ export class Exception extends Error {
     return result
   }
 }
+
+/**
+ * Converts a standard Error object (or thrown primitive) into an Exception instance.
+ * This function extracts relevant properties from the raw error
+ * and sets them on the Exception instance, allowing for a more
+ * consistent error handling experience across the application.
+ * @param error The unknown error value to convert.
+ * @param defaults Optional default properties to apply if they are missing on the Error object.
+ * @returns An Exception instance with properties set from the Error object.
+ */
+export function fromError(error: unknown, defaults: Partial<ExceptionSchema> = {}): Exception {
+  let message: string | undefined
+  let typed: Record<string, string | number> = {}
+
+  if (error instanceof Error) {
+    message = error.message
+    typed = error as unknown as Record<string, string | number>
+  } else if (typeof error === 'string') {
+    message = error
+  } else if (error !== null && typeof error === 'object') {
+    typed = error as Record<string, string | number>
+    if (typeof typed.message === 'string') {
+      message = typed.message
+    }
+  }
+
+  const e = new Exception(message || defaults.message || 'An error occurred')
+
+  if (typed.code !== undefined) {
+    e.code = String(typed.code)
+  } else if (defaults.code !== undefined) {
+    e.code = defaults.code
+  }
+
+  if (typed.status !== undefined) {
+    const status = Number(typed.status)
+    e.status = isNaN(status) ? (defaults.status ?? 500) : status
+  } else if (defaults.status !== undefined) {
+    e.status = defaults.status
+  }
+
+  if (typed.help !== undefined) {
+    e.setHelp(String(typed.help))
+  } else if (defaults.help !== undefined) {
+    e.setHelp(defaults.help)
+  }
+
+  if (typed.name !== undefined) {
+    e.name = String(typed.name)
+  } else if (defaults.name !== undefined) {
+    e.name = defaults.name
+  }
+
+  return e
+}

package/src/mocking/ProjectMock.ts

@@ -10,7 +10,7 @@ import { HostRules } from './lib/HostRules.js'
 
 export type { IRequestLogInit } from './lib/Request.js'
 export type { IResponseInit } from './lib/Response.js'
-export type { IUserInit } from './lib/User.js'
+export type { UserInitSchema, IUserInit } from './lib/User.js'
 export type { IHttpHistoryInit, IHttpHistoryListInit } from './lib/History.js'
 
 export class ProjectMock extends DataMock {

package/src/mocking/lib/File.ts

@@ -1,6 +1,6 @@
 import { faker } from '@faker-js/faker'
 import { ProjectKind, DomainFileKind, CertificateFileKind, FolderKind, ApiFileKind } from '../../models/kinds.js'
-import { File as CoreFile, type IFile, type FileBreadcrumb } from '../../models/store/File.js'
+import { File as CoreFile, type FileSchema, type FileBreadcrumb } from '../../models/store/File.js'
 import { nanoid } from '../../nanoid.js'
 
 export class File {
@@ -10,7 +10,7 @@ export class File {
    * @param init Optional values to be present in the object.
    * @returns Random file
    */
-  file(init: Partial<IFile> = {}): IFile {
+  file(init: Partial<FileSchema> = {}): FileSchema {
     const {
       kind = faker.helpers.arrayElement([ProjectKind, DomainFileKind, CertificateFileKind, ApiFileKind] as const),
       info = { name: faker.system.fileName() },
@@ -23,7 +23,7 @@ export class File {
    * @param size Number of files to generate. Default is 25.
    * @returns List of random files
    */
-  files(size = 25, init?: Partial<IFile>): IFile[] {
+  files(size = 25, init?: Partial<FileSchema>): FileSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
       result.push(this.file(init))
@@ -36,7 +36,7 @@ export class File {
    * @param init Optional values to be present in the object.
    * @returns Random folder
    */
-  folder(init: Partial<IFile> = {}): IFile {
+  folder(init: Partial<FileSchema> = {}): FileSchema {
     return this.file({ kind: FolderKind, ...init })
   }
 
@@ -45,7 +45,7 @@ export class File {
    * @param size Number of folders to generate. Default is 25.
    * @returns List of random folders
    */
-  folders(size = 25, init?: Partial<IFile>): IFile[] {
+  folders(size = 25, init?: Partial<FileSchema>): FileSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
       result.push(this.folder(init))

package/src/mocking/lib/Organization.ts

@@ -1,7 +1,7 @@
 import { faker } from '@faker-js/faker'
 import { OrganizationKind } from '../../models/kinds.js'
 import { nanoid } from '../../nanoid.js'
-import type { IOrganization } from '../../models/store/Organization.js'
+import type { OrganizationSchema } from '../../models/store/Organization.js'
 
 export class Organization {
   /**
@@ -9,10 +9,11 @@ export class Organization {
    * @param init Optional values to be present in the object.
    * @returns Random organization
    */
-  organization(init: Partial<IOrganization> = {}): IOrganization {
+  organization(init: Partial<OrganizationSchema> = {}): OrganizationSchema {
     const {
       key = nanoid(),
       name = faker.company.name(),
+      slug = faker.helpers.slugify(name),
       createdBy = nanoid(),
       createdDate = faker.date.past().getTime(),
       grantType = faker.helpers.arrayElement(['owner', 'manager', 'editor', 'viewer'] as const),
@@ -21,6 +22,7 @@ export class Organization {
       kind: OrganizationKind,
       key,
       name,
+      slug,
       createdBy,
       createdDate,
       grantType,
@@ -32,7 +34,7 @@ export class Organization {
    * @param size Number of organizations to generate. Default is 25.
    * @returns List of random organizations
    */
-  organizations(size = 25, init?: Partial<IOrganization>): IOrganization[] {
+  organizations(size = 25, init?: Partial<OrganizationSchema>): OrganizationSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
       result.push(this.organization(init))

package/src/mocking/lib/Permission.ts

@@ -1,7 +1,7 @@
 import { faker } from '@faker-js/faker'
 import { nanoid } from '../../nanoid.js'
 import {
-  IPermission,
+  PermissionSchema,
   Kind as PermissionKind,
   type PermissionRole,
   type PermissionType,
@@ -14,11 +14,11 @@ export class Permission {
    * @param init Configuration options for the permission object.
    * @returns Random permission
    */
-  permission(init: Partial<IPermission> = {}): IPermission {
+  permission(init: Partial<PermissionSchema> = {}): PermissionSchema {
     const type = init.type ?? faker.helpers.arrayElement(['user', 'group', 'organization'] as PermissionType[])
     const role = init.role ?? faker.helpers.arrayElement(['reader', 'commenter', 'writer', 'owner'] as PermissionRole[])
 
-    const result: IPermission = {
+    const result: PermissionSchema = {
       kind: PermissionKind,
       key: init.key ?? nanoid(),
       type,
@@ -62,7 +62,7 @@ export class Permission {
    * @param init Configuration options for the permission object.
    * @returns Random user permission
    */
-  userPermission(init: Partial<IPermission> = {}): IPermission {
+  userPermission(init: Partial<PermissionSchema> = {}): PermissionSchema {
     return this.permission({ ...init, type: 'user' })
   }
 
@@ -71,7 +71,7 @@ export class Permission {
    * @param init Configuration options for the permission object.
    * @returns Random group permission
    */
-  groupPermission(init: Partial<IPermission> = {}): IPermission {
+  groupPermission(init: Partial<PermissionSchema> = {}): PermissionSchema {
     return this.permission({ ...init, type: 'group' })
   }
 
@@ -80,7 +80,7 @@ export class Permission {
    * @param init Configuration options for the permission object.
    * @returns Random organization permission
    */
-  organizationPermission(init: Partial<IPermission> = {}): IPermission {
+  organizationPermission(init: Partial<PermissionSchema> = {}): PermissionSchema {
     return this.permission({ ...init, type: 'organization' })
   }
 
@@ -90,8 +90,8 @@ export class Permission {
    * @param init Configuration options for the permission object.
    * @returns List of random permissions
    */
-  permissions(size = 25, init: Partial<IPermission> = {}): IPermission[] {
-    const result: IPermission[] = []
+  permissions(size = 25, init: Partial<PermissionSchema> = {}): PermissionSchema[] {
+    const result: PermissionSchema[] = []
     for (let i = 0; i < size; i++) {
       result.push(this.permission(init))
     }

package/src/mocking/lib/User.ts

@@ -1,21 +1,26 @@
 import { faker } from '@faker-js/faker'
 import { nanoid } from '../../nanoid.js'
-import { IUser, Kind as UserKind } from '../../models/store/User.js'
+import { UserSchema, Kind as UserKind } from '../../models/store/User.js'
 
-export interface IUserInit {
+export interface UserInitSchema {
   noEmail?: boolean
   noPicture?: boolean
   noProvider?: boolean
 }
 
+/**
+ * @deprecated Use {@link UserInitSchema} instead.
+ */
+export type IUserInit = UserInitSchema
+
 export class User {
   /**
    * Generates a random user object.
    * @param init Configuration options for the user object.
    * @returns Random user
    */
-  user(init: IUserInit = {}): IUser {
-    const result: IUser = {
+  user(init: UserInitSchema = {}): UserSchema {
+    const result: UserSchema = {
       kind: UserKind,
       key: nanoid(),
       name: faker.person.fullName(),
@@ -51,8 +56,8 @@ export class User {
    * @param init Configuration options for the user object.
    * @returns List of random users
    */
-  users(size = 25, init: IUserInit = {}): IUser[] {
-    const result: IUser[] = []
+  users(size = 25, init: UserInitSchema = {}): UserSchema[] {
+    const result: UserSchema[] = []
     for (let i = 0; i < size; i++) {
       result.push(this.user(init))
     }

package/src/modeling/ApiFile.ts

@@ -1,11 +1,16 @@
-import { File, type IFile } from '../models/store/File.js'
+import { File, type FileSchema } from '../models/store/File.js'
 import { ApiFileKind } from '../models/kinds.js'
 import { ApiModel, ApiModelSchema } from './ApiModel.js'
 
-export interface IApiFile extends IFile {
+export interface ApiFileSchema extends FileSchema {
   kind: typeof ApiFileKind
 }
 
+/**
+ * @deprecated Use {@link ApiFileSchema} instead.
+ */
+export type IApiFile = ApiFileSchema
+
 /**
  * Used by the store. A file definition for the ApiModel.
  */
@@ -31,20 +36,20 @@ export class ApiFile extends File {
     return new ApiFile({ key: final.key, info: final.info })
   }
 
-  constructor(state: Partial<IApiFile> = {}) {
+  constructor(state: Partial<ApiFileSchema> = {}) {
     super({ ...state, kind: ApiFileKind })
   }
 
   static isApiFile(input: unknown): boolean {
-    const typed = input as IApiFile
+    const typed = input as ApiFileSchema
     if (!input || typed.kind !== ApiFileKind) {
       return false
     }
     return true
   }
 
-  override toJSON(): IApiFile {
-    const result: IApiFile = {
+  override toJSON(): ApiFileSchema {
+    const result: ApiFileSchema = {
       ...super.toJSON(),
       kind: ApiFileKind,
     }

package/src/modeling/ApiModel.ts

@@ -1,6 +1,6 @@
 import { nanoid } from '../nanoid.js'
 import { ApiModelKind, DataDomainKind, ExposedEntityKind } from '../models/kinds.js'
-import { type IThing, Thing } from '../models/Thing.js'
+import { type ThingSchema, Thing } from '../models/Thing.js'
 import type {
   AssociationTarget,
   AuthenticationConfiguration,
@@ -66,7 +66,7 @@ export interface ApiModelSchema extends DependentModelSchema {
   /**
    * Contains the name, display name, description, and the version of the API model schema.
    */
-  info: IThing
+  info: ThingSchema
 
   /**
    * The designated Data Entity that represents a "User".

package/src/modeling/DataDomain.ts

@@ -23,13 +23,13 @@ import { type DomainModelSchema, DomainModel } from './DomainModel.js'
 import { type DomainEntitySchema, DomainEntity } from './DomainEntity.js'
 import { DomainAssociation, DomainAssociationSchema } from './DomainAssociation.js'
 import { DomainProperty, DomainPropertySchema } from './DomainProperty.js'
-import { type IThing, Thing } from '../models/Thing.js'
+import { type ThingSchema, Thing } from '../models/Thing.js'
 import { removeGraphNode } from './GraphUtils.js'
 import { serialize, deserialize, mergeGraph, removeForeignGraph } from './DomainSerialization.js'
 import { DependentModel, type DependentModelSchema, type DomainDependency } from './DependentModel.js'
 
 export interface DataDomainSchema extends DependentModelSchema {
-  info: IThing
+  info: ThingSchema
   kind: typeof DataDomainKind
   key: string
   graph?: SerializedGraph

package/src/modeling/DomainAssociation.ts

@@ -2,7 +2,7 @@ import type { DataDomain } from './DataDomain.js'
 import { DomainAssociationKind } from '../models/kinds.js'
 import { DomainElement, type DomainElementSchema } from './DomainElement.js'
 import { nanoid } from '../nanoid.js'
-import { type IThing, Thing } from '../models/Thing.js'
+import { type ThingSchema, Thing } from '../models/Thing.js'
 import { observed, retargetChange, toRaw } from '../decorators/observed.js'
 import type { DomainEntity } from './DomainEntity.js'
 import type { Shapes } from '@api-client/amf-core'
@@ -37,7 +37,7 @@ export interface DomainAssociationSchema extends DomainElementSchema {
   /**
    * The data association description.
    */
-  info: IThing
+  info: ThingSchema
   /**
    * Wether the data association is required.
    */

package/src/modeling/DomainEntity.ts

@@ -2,7 +2,7 @@ import type { DataDomain } from './DataDomain.js'
 import { DomainAssociationKind, DomainEntityKind, DomainPropertyKind } from '../models/kinds.js'
 import { DomainElement, type DomainElementSchema } from './DomainElement.js'
 import { nanoid } from '../nanoid.js'
-import { type IThing, Thing } from '../models/Thing.js'
+import { type ThingSchema, Thing } from '../models/Thing.js'
 import { observed, retargetChange, toRaw } from '../decorators/observed.js'
 import type { Shapes, IShapeRenderOptions } from '@api-client/amf-core'
 import { ApiSchemaGenerator } from '@api-client/amf-core'
@@ -34,7 +34,7 @@ export interface DomainEntitySchema extends DomainElementSchema {
   /**
    * The domain entity description.
    */
-  info: IThing
+  info: ThingSchema
 
   /**
    * Optional general purpose tags for the UI.

package/src/modeling/DomainFile.ts

@@ -1,11 +1,16 @@
-import { File, type IFile } from '../models/store/File.js'
+import { File, type FileSchema } from '../models/store/File.js'
 import type { DataDomain, DataDomainSchema } from './DataDomain.js'
 import { DomainFileKind } from '../models/kinds.js'
 
-export interface IDomainFile extends IFile {
+export interface DomainFileSchema extends FileSchema {
   kind: typeof DomainFileKind
 }
 
+/**
+ * @deprecated Use {@link DomainFileSchema} instead.
+ */
+export type IDomainFile = DomainFileSchema
+
 /**
  * Used by the store. A file definition for the DataDomain
  */
@@ -31,20 +36,20 @@ export class DomainFile extends File {
     return new DomainFile({ key: final.key, info: final.info })
   }
 
-  constructor(state: Partial<IDomainFile> = {}) {
+  constructor(state: Partial<DomainFileSchema> = {}) {
     super({ ...state, kind: DomainFileKind })
   }
 
   static isDomainFile(input: unknown): boolean {
-    const typed = input as IDomainFile
+    const typed = input as DomainFileSchema
     if (!input || typed.kind !== DomainFileKind) {
       return false
     }
     return true
   }
 
-  override toJSON(): IDomainFile {
-    const result: IDomainFile = {
+  override toJSON(): DomainFileSchema {
+    const result: DomainFileSchema = {
       ...super.toJSON(),
       kind: DomainFileKind,
     }

package/src/modeling/DomainModel.ts

@@ -2,7 +2,7 @@ import type { DataDomain } from './DataDomain.js'
 import { DomainEntityKind, DomainModelKind } from '../models/kinds.js'
 import { DomainElement, DomainElementSchema } from './DomainElement.js'
 import { nanoid } from '../nanoid.js'
-import { type IThing, Thing } from '../models/Thing.js'
+import { type ThingSchema, Thing } from '../models/Thing.js'
 import { observed, retargetChange } from '../decorators/observed.js'
 import type { DomainNamespace } from './DomainNamespace.js'
 import type { FileBreadcrumb } from '../models/store/File.js'
@@ -29,7 +29,7 @@ export interface DomainModelSchema extends DomainElementSchema {
   /**
    * The data model description.
    */
-  info: IThing
+  info: ThingSchema
   /**
    * The ordered list of entities in the schema.
    */

package/src/modeling/DomainNamespace.ts

@@ -2,7 +2,7 @@ import type { DataDomain } from './DataDomain.js'
 import { DomainModelKind, DomainNamespaceKind } from '../models/kinds.js'
 import { DomainElement, DomainElementSchema } from './DomainElement.js'
 import { nanoid } from '../nanoid.js'
-import { IThing, Thing } from '../models/Thing.js'
+import { ThingSchema, Thing } from '../models/Thing.js'
 import { observed, retargetChange } from '../decorators/observed.js'
 import { DomainModel, DomainModelSchema } from './DomainModel.js'
 import { RemoveNamespaceException } from '../exceptions/remove_namespace_exception.js'
@@ -28,7 +28,7 @@ export interface DomainNamespaceSchema extends DomainElementSchema {
   /**
    * The data namespace description.
    */
-  info: IThing
+  info: ThingSchema
   /**
    * The ordered list of fields (namespace and models) in the schema.
    * These only keep references to define the order of these properties

package/src/modeling/DomainProperty.ts

@@ -2,7 +2,7 @@ import type { DataDomain } from './DataDomain.js'
 import { DomainPropertyKind } from '../models/kinds.js'
 import { DomainElement, type DomainElementSchema } from './DomainElement.js'
 import { nanoid } from '../nanoid.js'
-import { type IThing, Thing } from '../models/Thing.js'
+import { type ThingSchema, Thing } from '../models/Thing.js'
 import { observed, retargetChange, toRaw } from '../decorators/observed.js'
 import {
   type BinaryFormat,
@@ -30,7 +30,7 @@ export interface DomainPropertySchema extends DomainElementSchema {
   /**
    * The domain property description.
    */
-  info: IThing
+  info: ThingSchema
   /**
    * Wether the data property is required.
    */