@api-client/core 0.19.9 → 0.19.10

package/src/modeling/ExposedEntity.ts

@@ -6,7 +6,7 @@ import { 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 { restoreAccessRule } from './rules/index.js'
+import { type RateLimitRule, restoreAccessRule } from './rules/index.js'
 import { RateLimitingConfiguration } from './rules/RateLimitingConfiguration.js'
 import type { AssociationTarget, ExposeOptions, ExposeParentRef, ExposedEntitySchema } from './types.js'
 
@@ -98,7 +98,7 @@ export class ExposedEntity extends EventTarget {
   /**
    * Optional configuration for rate limiting for this exposure.
    */
-  @observed({ deep: true }) accessor rateLimiting: RateLimitingConfiguration | undefined
+  @observed() accessor rateLimiting: RateLimitingConfiguration | undefined
 
   /**
    * When true, generation for this exposure hit configured limits
@@ -184,7 +184,7 @@ export class ExposedEntity extends EventTarget {
     this.isRoot = init.isRoot
     this.parent = init.parent
     this.exposeOptions = init.exposeOptions
-    this.actions = init.actions ? init.actions.map((a) => restoreAction(a)) : []
+    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
     this.truncated = init.truncated
@@ -259,9 +259,7 @@ export class ExposedEntity extends EventTarget {
 
     // Check for collision if this is a root entity
     if (this.isRoot) {
-      const collision = this.api.exposes.find(
-        (e) => e.isRoot && e.key !== this.key && e.collectionPath === normalizedCollection
-      )
+      const collision = this.api.findCollectionPathCollision(normalizedCollection, this.key)
       if (collision) {
         throw new Error(`Collection path "${normalizedCollection}" is already in use by another root entity.`)
       }
@@ -328,7 +326,7 @@ export class ExposedEntity extends EventTarget {
     }
     // Check for collision if this is a root entity (singleton case)
     if (this.isRoot) {
-      const collision = this.api.exposes.find((e) => e.isRoot && e.key !== this.key && e.resourcePath === cleaned)
+      const collision = this.api.findResourcePathCollision(cleaned, this.key)
       if (collision) {
         throw new Error(`Resource path "${cleaned}" is already in use by another root entity.`)
       }
@@ -350,7 +348,7 @@ export class ExposedEntity extends EventTarget {
     // Traverse parents, always joining with the parent's resource path
     let parentKey = this.parent?.key
     while (parentKey) {
-      const parent = this.api.exposes.find((e) => e.key === parentKey)
+      const parent = this.api.exposes.get(parentKey)
       if (!parent) break
       const parentResource = ensureLeadingSlash(parent.resourcePath)
       absolute = joinPaths(parentResource, absolute)
@@ -372,7 +370,7 @@ export class ExposedEntity extends EventTarget {
     // Traverse parents, always joining with the parent's resource path
     let parentKey = this.parent?.key
     while (parentKey) {
-      const parent = this.api.exposes.find((e) => e.key === parentKey)
+      const parent = this.api.exposes.get(parentKey)
       if (!parent) break
       const parentResource = ensureLeadingSlash(parent.resourcePath)
       absolute = joinPaths(parentResource, absolute)
@@ -380,4 +378,60 @@ export class ExposedEntity extends EventTarget {
     }
     return absolute
   }
+
+  /**
+   * Returns all access rules for this exposure, including the ones from all the parents up to the API.
+   */
+  getAllRules(): AccessRule[] {
+    const rules: AccessRule[] = []
+    this.api.accessRule.forEach((rule) => rules.push(rule))
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current: ExposedEntity | undefined = this
+    while (current) {
+      if (current.accessRule) {
+        rules.push(...current.accessRule)
+      }
+      current = current.parent ? this.api.exposes.get(current.parent.key) : undefined
+    }
+    return rules
+  }
+
+  /**
+   * Returns all rate limiters for this exposure, including the ones from all the parents up to the API.
+   */
+  getAllRateLimiters(): RateLimitingConfiguration[] {
+    const rateLimiters: RateLimitingConfiguration[] = []
+    if (this.api.rateLimiting) {
+      rateLimiters.push(this.api.rateLimiting)
+    }
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current: ExposedEntity | undefined = this
+    while (current) {
+      if (current.rateLimiting) {
+        rateLimiters.push(current.rateLimiting)
+      }
+      current = current.parent ? this.api.exposes.get(current.parent.key) : undefined
+    }
+    return rateLimiters
+  }
+
+  /**
+   * Returns all rate limiter rules for this exposure, including the ones from all the parents up to the API.
+   * Similar to the getAllRules() method, but it flattens the rate limiters into a single list of rules.
+   */
+  getAllRateLimiterRules(): RateLimitRule[] {
+    const rules: RateLimitRule[] = []
+    if (this.api.rateLimiting) {
+      rules.push(...this.api.rateLimiting.rules)
+    }
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current: ExposedEntity | undefined = this
+    while (current) {
+      if (current.rateLimiting) {
+        rules.push(...current.rateLimiting.rules)
+      }
+      current = current.parent ? this.api.exposes.get(current.parent.key) : undefined
+    }
+    return rules
+  }
 }

package/src/modeling/actions/Action.ts

@@ -2,6 +2,7 @@ import { AccessRule, AccessRuleSchema } from '../rules/AccessRule.js'
 import { RateLimitingConfiguration, RateLimitingConfigurationSchema } from '../rules/RateLimitingConfiguration.js'
 import { observed } from '../../decorators/observed.js'
 import { restoreAccessRule } from '../rules/index.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
 
 /**
  * A base interface for common properties across all actions.
@@ -37,10 +38,13 @@ export interface ActionSchema {
 export class Action extends EventTarget implements ActionSchema {
   @observed() accessor kind: string
   @observed({ deep: true }) accessor accessRule: AccessRule[]
-  @observed({ deep: true }) accessor rateLimiting: RateLimitingConfiguration | undefined
+  @observed() accessor rateLimiting: RateLimitingConfiguration | undefined
 
-  constructor(state: Partial<ActionSchema> = {}) {
+  protected parent: ExposedEntity
+
+  constructor(parent: ExposedEntity, state: Partial<ActionSchema> = {}) {
     super()
+    this.parent = parent
     this.kind = state.kind || ''
     this.accessRule = state.accessRule ? state.accessRule.map((rule) => restoreAccessRule(rule)) : []
     this.rateLimiting = state.rateLimiting ? new RateLimitingConfiguration(state.rateLimiting) : undefined
@@ -62,4 +66,23 @@ export class Action extends EventTarget implements ActionSchema {
     }
     return result
   }
+
+  /**
+   * Returns all access rules for this action, including the ones from all the parents up to the API.
+   */
+  getAllRules(): AccessRule[] {
+    const rules: AccessRule[] = [...this.parent.getAllRules(), ...this.accessRule]
+    return rules
+  }
+
+  /**
+   * Returns all rate limiters for this action, including the ones from all the parents up to the API.
+   */
+  getAllRateLimiters(): RateLimitingConfiguration[] {
+    const rateLimiters = this.parent.getAllRateLimiters()
+    if (this.rateLimiting) {
+      rateLimiters.push(this.rateLimiting)
+    }
+    return rateLimiters
+  }
 }

package/src/modeling/actions/CreateAction.ts

@@ -1,5 +1,6 @@
 import { Action, type ActionSchema } from './Action.js'
 import { observed } from '../../decorators/observed.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
 
 /**
  * Enables adding a new resource to a collection.
@@ -16,8 +17,8 @@ export interface CreateActionSchema extends ActionSchema {
 export class CreateAction extends Action implements CreateActionSchema {
   @observed() override accessor kind: 'create'
 
-  constructor(state: Partial<CreateActionSchema> = {}) {
-    super(state)
+  constructor(parent: ExposedEntity, state: Partial<CreateActionSchema> = {}) {
+    super(parent, state)
     this.kind = 'create'
   }
 

package/src/modeling/actions/DeleteAction.ts

@@ -1,5 +1,6 @@
 import { Action, type ActionSchema } from './Action.js'
 import { observed } from '../../decorators/observed.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
 
 export type DeleteStrategy = 'soft' | 'hard'
 
@@ -33,8 +34,8 @@ export class DeleteAction extends Action implements DeleteActionSchema {
   @observed() accessor strategy: DeleteStrategy
   @observed() accessor retentionPeriod: number
 
-  constructor(state: Partial<DeleteActionSchema> = {}) {
-    super(state)
+  constructor(parent: ExposedEntity, state: Partial<DeleteActionSchema> = {}) {
+    super(parent, state)
     this.kind = 'delete'
     this.strategy = state.strategy || 'soft'
     this.retentionPeriod = state.retentionPeriod ?? 30

package/src/modeling/actions/ListAction.ts

@@ -1,6 +1,7 @@
 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'
 
 /**
  * Enables retrieving a collection of resources.
@@ -35,8 +36,8 @@ export class ListAction extends Action implements ListActionSchema {
   @observed({ deep: true }) accessor filterableFields: string[] = []
   @observed({ deep: true }) accessor sortableFields: string[] = []
 
-  constructor(state: Partial<ListActionSchema> = {}) {
-    super(state)
+  constructor(parent: ExposedEntity, state: Partial<ListActionSchema> = {}) {
+    super(parent, state)
     this.kind = state.kind || 'list'
     this.pagination = state.pagination
       ? { ...state.pagination }

package/src/modeling/actions/ReadAction.ts

@@ -1,5 +1,6 @@
 import { Action, type ActionSchema } from './Action.js'
 import { observed } from '../../decorators/observed.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
 
 /**
  * Enables retrieving a single resource by its ID.
@@ -18,8 +19,8 @@ export interface ReadActionSchema extends ActionSchema {
 export class ReadAction extends Action implements ReadActionSchema {
   @observed() override accessor kind: 'read'
 
-  constructor(state: Partial<ReadActionSchema> = {}) {
-    super(state)
+  constructor(parent: ExposedEntity, state: Partial<ReadActionSchema> = {}) {
+    super(parent, state)
     this.kind = 'read'
   }
 

package/src/modeling/actions/SearchAction.ts

@@ -1,5 +1,6 @@
 import { Action, type ActionSchema } from './Action.js'
 import { observed, toRaw } from '../../decorators/observed.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
 
 /**
  * Enables keyword-based search across specified fields.
@@ -22,8 +23,8 @@ export class SearchAction extends Action implements SearchActionSchema {
   @observed() override accessor kind: 'search'
   @observed({ deep: true }) accessor fields: string[]
 
-  constructor(state: Partial<SearchActionSchema> = {}) {
-    super(state)
+  constructor(parent: ExposedEntity, state: Partial<SearchActionSchema> = {}) {
+    super(parent, state)
     this.kind = 'search'
     this.fields = state.fields ? [...state.fields] : []
   }

package/src/modeling/actions/UpdateAction.ts

@@ -1,5 +1,6 @@
 import { Action, type ActionSchema } from './Action.js'
 import { observed, toRaw } from '../../decorators/observed.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
 
 /**
  * Enables modifying an existing resource.
@@ -25,8 +26,8 @@ export class UpdateAction extends Action implements UpdateActionSchema {
   @observed() override accessor kind: 'update'
   @observed({ deep: true }) accessor allowedMethods: ('PUT' | 'PATCH')[]
 
-  constructor(state: Partial<UpdateActionSchema> = {}) {
-    super(state)
+  constructor(parent: ExposedEntity, state: Partial<UpdateActionSchema> = {}) {
+    super(parent, state)
     this.kind = 'update'
     this.allowedMethods = state.allowedMethods ? [...state.allowedMethods] : ['PATCH']
   }

package/src/modeling/types.ts

@@ -769,3 +769,73 @@ export interface DomainSearchResult {
    */
   isForeign: boolean
 }
+
+/**
+ * Contextual information about where the API Model validation issue occurred.
+ * This allows the UI to trace back a validation error to a specific module or component.
+ */
+export interface ApiModelValidationContext {
+  /**
+   * The key of the ApiModel itself.
+   */
+  apiModelKey: string
+  /**
+   * The kind of the affected component (e.g., 'ApiModel', 'ExposedEntity', 'Action').
+   */
+  kind: string
+  /**
+   * The key of the specific entity or action where the issue occurred.
+   * If the error is at the root API model, this might be the ApiModel's key.
+   */
+  key: string
+  /**
+   * The specific property being validated, if applicable.
+   */
+  property?: string
+  /**
+   * The key of the parent ExposedEntity, if this issue occurred on a nested entity or an action.
+   */
+  parentExposedEntityKey?: string
+}
+
+/**
+ * Represents a single validation issue found within an ApiModel.
+ */
+export interface ApiModelValidationItem {
+  /**
+   * A unique code identifying the type of validation error. This enables
+   * programmatic handling or auto-fixing in the UI (e.g., 'API_MISSING_NAME', 'LIST_ACTION_MISSING_PAGINATION').
+   */
+  code: string
+  /**
+   * A human-readable description of the problem.
+   */
+  message: string
+  /**
+   * A human-readable suggestion on how to fix the issue.
+   */
+  suggestion: string
+  /**
+   * The severity of the validation issue.
+   */
+  severity: 'error' | 'warning' | 'info'
+  /**
+   * Contextual information to trace the issue back to its source component.
+   */
+  context: ApiModelValidationContext
+}
+
+/**
+ * The consolidated result of validating an entire ApiModel or a subset of it.
+ */
+export interface ApiModelValidationResult {
+  /**
+   * A boolean indicating whether the model is structurally sound and ready for publication.
+   * Typically true if there are no 'error' severity issues.
+   */
+  isValid: boolean
+  /**
+   * The aggregated list of all validation issues found.
+   */
+  issues: ApiModelValidationItem[]
+}