@api-client/core 0.19.19 → 0.19.21

package/eslint.config.js

@@ -3,6 +3,7 @@ import pluginJs from '@eslint/js'
 import tseslint from 'typescript-eslint'
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
 import noOnlyTests from 'eslint-plugin-no-only-tests'
+import jsdoc from 'eslint-plugin-jsdoc'
 // import eslintPluginPrettier from 'eslint-plugin-prettier'
 
 // import eslintConfigPrettier from 'eslint-config-prettier'
@@ -40,6 +41,7 @@ export default [
   // eslintConfigPrettier,
   eslintPluginPrettierRecommended,
   {
+    ...jsdoc.configs['flat/recommended-typescript'],
     files: ['**/*.ts'],
     languageOptions: {
       globals: {
@@ -69,6 +71,9 @@ export default [
       'no-console': ['error'],
       'no-redeclare': ['error'],
     },
+    plugins: {
+      jsdoc,
+    },
   },
   {
     files: [
@@ -106,6 +111,7 @@ export default [
       '@typescript-eslint/no-non-null-assertion': 'off',
       '@typescript-eslint/no-empty-function': 'off',
       'no-only-tests/no-only-tests': 'error',
+      '@typescript-eslint/no-explicit-any': 'off',
       'no-console': ['warn'],
     },
   },

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.19",
+  "version": "0.19.21",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {
@@ -97,6 +97,7 @@
     "console-table-printer": "^2.11.2",
     "dompurify": "^3.2.6",
     "jsdom": "^29.0.0",
+    "json-schema-typed": "^8.0.2",
     "nanoid": "^5.1.5",
     "tslog": "^4.9.3",
     "ws": "^8.12.0",
@@ -129,6 +130,7 @@
     "cors": "^2.8.5",
     "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-jsdoc": "^62.9.0",
     "eslint-plugin-no-only-tests": "^3.3.0",
     "eslint-plugin-prettier": "^5.2.3",
     "express": "^5.1.0",

package/src/authorization/Utils.ts

@@ -32,20 +32,20 @@ export function sanityCheck(settings: IOAuth2Authorization): void {
     try {
       checkUrl(settings.authorizationUri as string)
     } catch (e) {
-      throw new Error(`authorizationUri: ${(e as Error).message}`)
+      throw new Error(`authorizationUri: ${(e as Error).message}`, { cause: e })
     }
     if (settings.accessTokenUri) {
       try {
         checkUrl(settings.accessTokenUri)
       } catch (e) {
-        throw new Error(`accessTokenUri: ${(e as Error).message}`)
+        throw new Error(`accessTokenUri: ${(e as Error).message}`, { cause: e })
       }
     }
   } else if (settings.accessTokenUri) {
     try {
       checkUrl(settings.accessTokenUri)
     } catch (e) {
-      throw new Error(`accessTokenUri: ${(e as Error).message}`)
+      throw new Error(`accessTokenUri: ${(e as Error).message}`, { cause: e })
     }
   }
 }

package/src/modeling/ApiModel.ts

@@ -3,13 +3,15 @@ import { ApiModelKind, DataDomainKind, ExposedEntityKind } from '../models/kinds
 import { type ThingSchema, Thing } from '../models/Thing.js'
 import type {
   AssociationTarget,
-  AuthenticationConfiguration,
-  AuthorizationConfiguration,
+  AuthenticationStrategy,
+  AuthorizationStrategy,
   ExposedEntitySchema,
   RolesBasedAccessControl,
   SessionConfiguration,
   UsernamePasswordConfiguration,
   ExposeOptions,
+  OffsetPaginationStrategy,
+  CursorPaginationStrategy,
 } from './types.js'
 import { DataDomain } from './DataDomain.js'
 import { DependentModel, type DependentModelSchema, type DomainDependency } from './DependentModel.js'
@@ -67,7 +69,6 @@ export interface ApiModelSchema extends DependentModelSchema {
    * Contains the name, display name, description, and the version of the API model schema.
    */
   info: ThingSchema
-
   /**
    * The designated Data Entity that represents a "User".
    * This entity should be marked with the "User" semantic in the Data Modeler.
@@ -80,13 +81,13 @@ export interface ApiModelSchema extends DependentModelSchema {
    * Configuration for how users prove their identity.
    * The API model is invalid if this is not set.
    */
-  authentication?: AuthenticationConfiguration
+  authentication?: AuthenticationStrategy
 
   /**
    * Configuration for what authenticated users are allowed to do.
    * The API model is invalid if this is not set.
    */
-  authorization?: AuthorizationConfiguration
+  authorization?: AuthorizationStrategy
 
   /**
    * Configuration for the transport and payload of the user session.
@@ -125,6 +126,12 @@ export interface ApiModelSchema extends DependentModelSchema {
    * The license information for the API.
    */
   license?: ApiLicense
+  /**
+   * The pagination strategy used by all endpoints in this API. The configuration
+   * is shared across all endpoints to ensure consistency and security.
+   * This defines how the results are paginated when retrieving a collection of resources.
+   */
+  pagination: CursorPaginationStrategy | OffsetPaginationStrategy
 }
 
 export class ApiModel extends DependentModel {
@@ -154,13 +161,13 @@ export class ApiModel extends DependentModel {
    * Configuration for how users prove their identity.
    * The API model is invalid if this is not set.
    */
-  authentication?: AuthenticationConfiguration
+  authentication?: AuthenticationStrategy
 
   /**
    * Configuration for what authenticated users are allowed to do.
    * The API model is invalid if this is not set.
    */
-  authorization?: AuthorizationConfiguration
+  authorization?: AuthorizationStrategy
 
   /**
    * Configuration for the transport and payload of the user session.
@@ -200,6 +207,11 @@ export class ApiModel extends DependentModel {
    * The license information for the API.
    */
   @observed({ deep: true }) accessor license: ApiLicense | undefined
+  /**
+   * The pagination strategy used by all endpoints in this API.
+   * This defines how the results are paginated when retrieving a collection of resources.
+   */
+  @observed({ deep: true }) accessor pagination: CursorPaginationStrategy | OffsetPaginationStrategy
 
   /**
    * When the initializing flag is set to true,
@@ -232,13 +244,14 @@ export class ApiModel extends DependentModel {
   }
 
   static createSchema(input: Partial<ApiModelSchema> = {}): ApiModelSchema {
-    const { key = nanoid(), exposes = [] } = input
+    const { key = nanoid(), exposes = [], pagination } = input
     const info = Thing.fromJSON(input.info, { name: 'Unnamed API' }).toJSON()
     const result: ApiModelSchema = {
       kind: ApiModelKind,
       key,
       info,
       exposes,
+      pagination: pagination ? structuredClone(pagination) : { kind: 'cursor' },
     }
     if (input.user) {
       result.user = structuredClone(input.user)
@@ -298,6 +311,7 @@ export class ApiModel extends DependentModel {
     this.key = init.key
     this.info = new Thing(init.info)
     this.user = init.user
+    this.pagination = init.pagination ? structuredClone(init.pagination) : { kind: 'cursor' }
     if (init.authentication) {
       this.authentication = structuredClone(init.authentication)
     }
@@ -341,6 +355,7 @@ export class ApiModel extends DependentModel {
       key: this.key,
       info: this.info.toJSON(),
       exposes: Array.from(this.exposes.values()).map((e) => e.toJSON()),
+      pagination: structuredClone(toRaw(this, this.pagination)) as CursorPaginationStrategy | OffsetPaginationStrategy,
     }
     if (this.user) {
       result.user = { ...this.user }

package/src/modeling/ApiValidation.ts

@@ -7,6 +7,7 @@ import {
   validateApiModelSecurity,
   validateApiModelMetadata,
   validateExposedEntity,
+  validateApiPagination,
 } from './validation/api_model_rules.js'
 
 /**
@@ -58,6 +59,7 @@ export class ApiValidation {
     this.report.push(...validateApiModelInfo(this.model))
     this.report.push(...validateApiModelDependency(this.model))
     this.report.push(...validateApiModelSecurity(this.model))
+    this.report.push(...validateApiPagination(this.model))
     this.report.push(...validateApiModelMetadata(this.model))
 
     if (!this.model.exposes || this.model.exposes.size === 0) {

package/src/modeling/DomainProperty.ts

@@ -50,8 +50,14 @@ export interface DomainPropertySchema extends DomainElementSchema {
   unique?: boolean
   /**
    * Whether this property describes an indexed property of the entity.
+   * This enables a standard B-Tree index.
    */
   index?: boolean
+  /**
+   * Whether this property describes a search index of the entity.
+   * This enables a specialized Inverted Index (e.g., a GIN or `pg_trgm` index in PostgreSQL).
+   */
+  search?: boolean
   /**
    * Whether the property is read only in the schema.
    */
@@ -170,8 +176,14 @@ export class DomainProperty extends DomainElement {
 
   /**
    * Whether this property describes an indexed property of the entity.
+   * This enables a standard B-Tree index.
    */
   @observed() accessor index: boolean | undefined
+  /**
+   * Whether this property describes a search index of the entity.
+   * This enables a specialized Inverted Index (e.g., a GIN or `pg_trgm` index in PostgreSQL).
+   */
+  @observed() accessor search: boolean | undefined
 
   /**
    * Whether the property is read only in the schema.
@@ -239,6 +251,7 @@ export class DomainProperty extends DomainElement {
       required,
       type = DomainPropertyList.string,
       index,
+      search,
       primary,
       unique,
       readOnly,
@@ -270,6 +283,9 @@ export class DomainProperty extends DomainElement {
     if (typeof index === 'boolean') {
       result.index = index
     }
+    if (typeof search === 'boolean') {
+      result.search = search
+    }
     if (typeof primary === 'boolean') {
       result.primary = primary
     }
@@ -330,43 +346,30 @@ export class DomainProperty extends DomainElement {
 
     if (typeof init.multiple === 'boolean') {
       this.multiple = init.multiple
-    } else {
-      this.multiple = undefined
     }
     if (typeof init.required === 'boolean') {
       this.required = init.required
-    } else {
-      this.required = undefined
     }
     if (typeof init.index === 'boolean') {
       this.index = init.index
-    } else {
-      this.index = undefined
+    }
+    if (typeof init.search === 'boolean') {
+      this.search = init.search
     }
     if (typeof init.deprecated === 'boolean') {
       this.deprecated = init.deprecated
-    } else {
-      this.deprecated = undefined
     }
     if (typeof init.primary === 'boolean') {
       this.primary = init.primary
-    } else {
-      this.primary = undefined
     }
     if (typeof init.unique === 'boolean') {
       this.unique = init.unique
-    } else {
-      this.unique = undefined
     }
     if (typeof init.readOnly === 'boolean') {
       this.readOnly = init.readOnly
-    } else {
-      this.readOnly = undefined
     }
     if (typeof init.writeOnly === 'boolean') {
       this.writeOnly = init.writeOnly
-    } else {
-      this.writeOnly = undefined
     }
     if (Array.isArray(init.tags)) {
       this.tags = [...init.tags]
@@ -380,8 +383,6 @@ export class DomainProperty extends DomainElement {
     }
     if (init.schema) {
       this.schema = structuredClone(init.schema)
-    } else {
-      this.schema = undefined
     }
     if (Array.isArray(init.bindings)) {
       this.bindings = init.bindings.map((i) => structuredClone(i))
@@ -418,6 +419,9 @@ export class DomainProperty extends DomainElement {
     if (typeof this.index === 'boolean') {
       result.index = this.index
     }
+    if (typeof this.search === 'boolean') {
+      result.search = this.search
+    }
     if (typeof this.deprecated === 'boolean') {
       result.deprecated = this.deprecated
     }

package/src/modeling/DomainSerialization.ts

@@ -513,7 +513,7 @@ export function deserialize(root: DataDomain, options: DeserializeOptions = {}):
         const message = `Failed to merge dependency "${dependency.key}": ${error instanceof Error ? error.message : String(error)}`
 
         if (mode === 'strict') {
-          throw new Error(message)
+          throw new Error(message, { cause: error })
         }
 
         const issue: DeserializationIssue = {

package/src/modeling/ExposedEntity.ts

@@ -1,14 +1,20 @@
-import { observed } from '../decorators/observed.js'
+import { observed, toRaw } from '../decorators/observed.js'
 import { ExposedEntityKind } from '../models/kinds.js'
 import { nanoid } from '../nanoid.js'
 import { Action } from './actions/Action.js'
-import { restoreAction } from './actions/index.js'
+import { type ApiActionSchema, restoreAction } from './actions/index.js'
 import type { ApiModel } from './ApiModel.js'
 import { ensureLeadingSlash, joinPaths } from './helpers/endpointHelpers.js'
 import { AccessRule } from './rules/AccessRule.js'
 import { type RateLimitRule, restoreAccessRule } from './rules/index.js'
 import { RateLimitingConfiguration } from './rules/RateLimitingConfiguration.js'
-import type { AssociationTarget, ExposeOptions, ExposeParentRef, ExposedEntitySchema } from './types.js'
+import type {
+  AssociationTarget,
+  ExposeOptions,
+  ExposeParentRef,
+  ExposedEntitySchema,
+  PaginationContract,
+} from './types.js'
 
 /**
  * A class that specializes in representing an exposed Data Entity within an API Model.
@@ -100,6 +106,14 @@ export class ExposedEntity extends EventTarget {
    */
   @observed() accessor rateLimiting: RateLimitingConfiguration | undefined
 
+  /**
+   * Pagination contract for this exposure.
+   * Defines a list of fields that can be used for filtering, sorting, and searching.
+   * The pagination contract is only valid for that specific exposure. It cannot be inherited
+   * by other exposures.
+   */
+  @observed({ deep: true }) accessor paginationContract: PaginationContract | undefined
+
   /**
    * When true, generation for this exposure hit configured limits
    *
@@ -138,6 +152,7 @@ export class ExposedEntity extends EventTarget {
       accessRule,
       rateLimiting,
       truncated,
+      paginationContract,
     } = input
     const result: ExposedEntitySchema = {
       kind: ExposedEntityKind,
@@ -168,6 +183,9 @@ export class ExposedEntity extends EventTarget {
     if (truncated !== undefined) {
       result.truncated = truncated
     }
+    if (paginationContract !== undefined) {
+      result.paginationContract = structuredClone(paginationContract)
+    }
     return result
   }
 
@@ -186,8 +204,13 @@ export class ExposedEntity extends EventTarget {
     this.exposeOptions = init.exposeOptions
     this.actions = init.actions ? init.actions.map((a) => restoreAction(this, a)) : []
     this.accessRule = init.accessRule ? init.accessRule.map((ar) => restoreAccessRule(ar)) : []
-    this.rateLimiting = init.rateLimiting ? new RateLimitingConfiguration(init.rateLimiting) : undefined
+    if (init.rateLimiting) {
+      this.rateLimiting = new RateLimitingConfiguration(init.rateLimiting)
+    }
     this.truncated = init.truncated
+    if (init.paginationContract) {
+      this.paginationContract = structuredClone(init.paginationContract)
+    }
     this.#initializing = false
   }
 
@@ -233,6 +256,9 @@ export class ExposedEntity extends EventTarget {
     if (this.truncated !== undefined) {
       result.truncated = this.truncated
     }
+    if (this.paginationContract) {
+      result.paginationContract = structuredClone(toRaw(this, this.paginationContract))
+    }
     return result
   }
 
@@ -434,4 +460,18 @@ export class ExposedEntity extends EventTarget {
     }
     return rules
   }
+
+  /**
+   * Adds an action to the exposure.
+   * @param schema The schema of the action to add.
+   * @returns The added action.
+   */
+  addAction(schema: ApiActionSchema): Action {
+    if (this.actions.some((action) => action.kind === schema.kind)) {
+      throw new Error(`Action of kind "${schema.kind}" already exists for this exposure`)
+    }
+    const action = restoreAction(this, schema)
+    this.actions.push(action)
+    return action
+  }
 }

package/src/modeling/actions/Action.ts

@@ -52,6 +52,7 @@ export class Action extends EventTarget implements ActionSchema {
 
   notifyChange() {
     this.dispatchEvent(new Event('change'))
+    // this.parent.api.notifyChange()
   }
 
   toJSON(): ActionSchema {

package/src/modeling/actions/ListAction.ts

@@ -1,7 +1,6 @@
-import type { PaginationStrategy } from '../types.js'
 import { Action, type ActionSchema } from './Action.js'
-import { observed, toRaw } from '../../decorators/observed.js'
 import type { ExposedEntity } from '../ExposedEntity.js'
+import { observed } from '../../decorators/observed.js'
 
 /**
  * Enables retrieving a collection of resources.
@@ -10,20 +9,9 @@ import type { ExposedEntity } from '../ExposedEntity.js'
 export interface ListActionSchema extends ActionSchema {
   kind: 'list'
   /**
-   * The pagination strategy used for this action.
-   * This defines how the results are paginated when retrieving a collection of resources.
-   * It can be either 'cursor' or 'offset'.
+   * The time to live for the cache in seconds.
    */
-  pagination: PaginationStrategy
-  /**
-   * Fields from the entity that can be used for filtering.
-   * Must be marked as "indexable" in the Data Model.
-   */
-  filterableFields: string[]
-  /**
-   * Fields from the entity that can be used for sorting.
-   */
-  sortableFields: string[]
+  cacheTtl?: number
 }
 
 /**
@@ -32,29 +20,23 @@ export interface ListActionSchema extends ActionSchema {
  */
 export class ListAction extends Action implements ListActionSchema {
   @observed() override accessor kind: 'list'
-  @observed({ deep: true }) accessor pagination: PaginationStrategy
-  @observed({ deep: true }) accessor filterableFields: string[] = []
-  @observed({ deep: true }) accessor sortableFields: string[] = []
+  @observed() accessor cacheTtl: number | undefined
 
   constructor(parent: ExposedEntity, state: Partial<ListActionSchema> = {}) {
     super(parent, state)
-    this.kind = state.kind || 'list'
-    this.pagination = state.pagination
-      ? { ...state.pagination }
-      : {
-          kind: 'offset',
-        }
-    this.filterableFields = state.filterableFields ? [...state.filterableFields] : []
-    this.sortableFields = state.sortableFields ? [...state.sortableFields] : []
+    this.kind = 'list'
+    this.cacheTtl = state.cacheTtl
   }
 
   override toJSON(): ListActionSchema {
-    return {
+    const result: ListActionSchema = {
       ...(super.toJSON() as ListActionSchema),
-      pagination: structuredClone(toRaw(this, this.pagination)) as PaginationStrategy,
-      filterableFields: structuredClone(toRaw(this, this.filterableFields)) as string[],
-      sortableFields: structuredClone(toRaw(this, this.sortableFields)) as string[],
+      kind: 'list',
+    }
+    if (this.cacheTtl !== undefined) {
+      result.cacheTtl = this.cacheTtl
     }
+    return result
   }
 
   static isListAction(action: Action): action is ListAction {

package/src/modeling/actions/SearchAction.ts

@@ -1,6 +1,6 @@
 import { Action, type ActionSchema } from './Action.js'
-import { observed, toRaw } from '../../decorators/observed.js'
 import type { ExposedEntity } from '../ExposedEntity.js'
+import { observed } from '../../decorators/observed.js'
 
 /**
  * Enables keyword-based search across specified fields.
@@ -9,10 +9,10 @@ import type { ExposedEntity } from '../ExposedEntity.js'
 export interface SearchActionSchema extends ActionSchema {
   kind: 'search'
   /**
-   * The fields within the entity to be included in the search scope.
-   * Must be "indexable" and typically text-based.
+   * The maximum depth of the Abstract Syntax Tree (AST) that will be used to parse the search query.
+   * This is used to prevent denial of service attacks.
    */
-  fields: string[]
+  maxAstDepth?: number
 }
 
 /**
@@ -21,20 +21,23 @@ export interface SearchActionSchema extends ActionSchema {
  */
 export class SearchAction extends Action implements SearchActionSchema {
   @observed() override accessor kind: 'search'
-  @observed({ deep: true }) accessor fields: string[]
+  @observed() accessor maxAstDepth: number | undefined
 
   constructor(parent: ExposedEntity, state: Partial<SearchActionSchema> = {}) {
     super(parent, state)
     this.kind = 'search'
-    this.fields = state.fields ? [...state.fields] : []
+    this.maxAstDepth = state.maxAstDepth
   }
 
   override toJSON(): SearchActionSchema {
-    return {
+    const result: SearchActionSchema = {
       ...(super.toJSON() as SearchActionSchema),
       kind: 'search',
-      fields: structuredClone(toRaw(this, this.fields)) as string[],
     }
+    if (this.maxAstDepth !== undefined) {
+      result.maxAstDepth = this.maxAstDepth
+    }
+    return result
   }
 
   static isSearchActionSchema(schema: ActionSchema): schema is SearchActionSchema {