@api-client/core 0.18.27 → 0.18.28

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.18.27",
+  "version": "0.18.28",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -87,6 +87,7 @@
     "@api-client/graph": "^0.3.5",
     "@api-client/json": "^0.2.0",
     "@esm-bundle/chai": "^4.3.4-fix.0",
+    "@jarrodek/pluralize": "^1.0.2",
     "@metrichor/jmespath": "^0.3.1",
     "@pawel-up/csv": "^0.2.0",
     "@pawel-up/data-mock": "^0.4.0",

package/src/modeling/ApiModel.ts

@@ -11,10 +11,13 @@ import type {
   RolesBasedAccessControl,
   SessionConfiguration,
   UsernamePasswordConfiguration,
+  ExposeOptions,
 } from './types.js'
 import { DataDomain } from './DataDomain.js'
 import { DependentModel, type DependentModelSchema, type DomainDependency } from './DependentModel.js'
 import { observed, toRaw } from '../decorators/observed.js'
+import pluralize from '@jarrodek/pluralize'
+import { createDomainKey } from './helpers/keying.js'
 
 /**
  * Contact information for the exposed API.
@@ -54,12 +57,12 @@ export interface ApiModelSchema extends DependentModelSchema {
    */
   kind: typeof ApiModelKind
   /**
-   * The unique key of the data domain schema.
+   * The unique key of the API model 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.
+   * Contains the name, display name, description, and the version of the API model schema.
    */
   info: IThing
 
@@ -376,41 +379,182 @@ export class ApiModel extends DependentModel {
   /**
    * 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.
+   * @param entity The entity key and domain to expose.
    * @returns The exposed entity.
    */
-  exposeEntity(entityKey: string): ExposedEntity {
-    const existing = this.exposes.find((e) => e.key === entityKey)
+  exposeEntity(entity: AssociationTarget, options?: ExposeOptions): ExposedEntity {
+    const domain = this.domain
+    if (!domain) {
+      throw new Error(`No domain attached to API model`)
+    }
+    // checks whether the entity is already exposed as a root exposure.
+    const existing = this.exposes.find(
+      (e) => e.isRoot && e.entity.key === entity.key && e.entity.domain === entity.domain
+    )
     if (existing) {
+      // quietly return the existing exposure
+      // TBD: should we throw an error here?
       return existing
     }
+    const domainEntity = domain.findEntity(entity.key, entity.domain)
+    if (!domainEntity) {
+      throw new Error(`Entity not found in domain: ${entity.key}`)
+    }
+    const name = domainEntity.info.name || ''
     const newEntity: ExposedEntity = {
-      key: entityKey,
+      key: nanoid(),
+      entity: { ...entity },
       actions: [],
+      isRoot: true,
+      path: pluralize(name.toLocaleLowerCase()),
+    }
+    if (options) {
+      newEntity.exposeOptions = { ...options }
     }
     this.exposes.push(newEntity)
+
+    // Follow associations if requested
+    if (options?.followAssociations) {
+      if (options?.maxDepth === undefined || options.maxDepth > 0) {
+        this.followEntityAssociations(newEntity, options)
+      }
+    }
     this.notifyChange()
     return newEntity
   }
 
   /**
-   * Removes an entity from the API model.
-   * @param entityKey The key of the entity to remove.
+   * Follows associations for a newly exposed entity if configured to do so.
+   * This creates nested exposures based on the entity's associations.
+   *
+   * @param parentExposure The root exposure to follow associations from
+   * @param options The expose options containing follow configuration
    */
-  removeEntity(entityKey: string): void {
-    const index = this.exposes.findIndex((e) => e.key === entityKey)
-    if (index !== -1) {
-      this.exposes.splice(index, 1)
-      this.notifyChange()
+  private followEntityAssociations(parentExposure: ExposedEntity, options: ExposeOptions): void {
+    const domain = this.domain
+    if (!domain) {
+      return
+    }
+    const maxDepth = options.maxDepth ?? 6
+    const visited = new Set<string>()
+    // Add parent entity's key to the visited set so we won't skip it when traversing
+    // associations.
+    visited.add(createDomainKey(parentExposure.entity))
+
+    const follow = (currentEntity: AssociationTarget, parentKey: string, depth: number) => {
+      // Find the domain entity
+      const domainEntity = domain.findEntity(currentEntity.key, currentEntity.domain)
+      if (!domainEntity) return
+
+      // Iterate through associations
+      for (const association of domainEntity.listAssociations()) {
+        for (const target of association.targets) {
+          // Skip self-referencing associations
+          if (target.key === currentEntity.key && target.domain === currentEntity.domain) {
+            continue
+          }
+
+          // Create unique identifier for circular detection
+          const visitKey = createDomainKey(target)
+          if (visited.has(visitKey)) {
+            continue // Skip circular references
+          }
+          visited.add(visitKey)
+
+          // Check if this nested exposure already exists
+          const existingNested = this.exposes.find(
+            (e) =>
+              !e.isRoot &&
+              e.entity.key === target.key &&
+              e.entity.domain === target.domain &&
+              e.parent?.key === parentKey
+          )
+
+          if (existingNested) {
+            continue // Already exposed under this parent
+          }
+
+          // Find the target domain entity for path generation
+          const targetDomainEntity = domain.findEntity(target.key, target.domain)
+          if (!targetDomainEntity) continue
+
+          const name = association.info.name || ''
+          // Create nested exposure
+          const nestedExposure: ExposedEntity = {
+            key: nanoid(),
+            entity: { ...target },
+            actions: [],
+            isRoot: false,
+            path: pluralize(name.toLocaleLowerCase()),
+            parent: {
+              key: parentKey,
+              association: {
+                key: association.key,
+                domain: currentEntity.domain,
+              },
+              depth: depth + 1,
+            },
+          }
+
+          this.exposes.push(nestedExposure)
+          if (depth + 1 >= maxDepth) {
+            nestedExposure.truncated = true
+          } else {
+            // Recursively follow associations
+            follow(target, nestedExposure.key, depth + 1)
+          }
+        }
+      }
+    }
+
+    // Start following from the root exposure
+    follow(parentExposure.entity, parentExposure.key, 0)
+  }
+
+  /**
+   * Removes an exposed entity from the API model.
+   * @param entity The entity to remove.
+   */
+  removeEntity(entity: AssociationTarget): void {
+    const current = this.exposes.find((e) => e.entity.key === entity.key && e.entity.domain === entity.domain)
+    if (!current) {
+      return
+    }
+    this.removeWithChildren(current.key)
+    this.notifyChange()
+  }
+
+  private removeWithChildren(key: string): void {
+    const index = this.exposes.findIndex((e) => e.key === key)
+    if (index < 0) {
+      return
     }
+    // Remove the parent itself
+    this.exposes.splice(index, 1)
+    // Remove all children recursively
+    const removeChildren = (parentKey: string) => {
+      // Find all exposures whose parent.key matches parentKey
+      const children = this.exposes.filter((e) => e.parent?.key === parentKey)
+      for (const child of children) {
+        removeChildren(child.key)
+        const childIndex = this.exposes.findIndex((e) => e.key === child.key)
+        if (childIndex >= 0) {
+          this.exposes.splice(childIndex, 1)
+        }
+      }
+    }
+    // Then also remove children
+    removeChildren(key)
+    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)
+  getExposedEntity(entity: AssociationTarget): ExposedEntity | undefined {
+    return this.exposes.find((e) => e.entity.key === entity.key && e.entity.domain === entity.domain)
   }
 
   /**

package/src/modeling/helpers/endpointHelpers.ts

@@ -0,0 +1,5 @@
+export function paramNameFor(entityKeyLocal: string): string {
+  const parts = entityKeyLocal.split(':')
+  const key = parts[parts.length - 1]
+  return `${key}Id`
+}

package/src/modeling/helpers/keying.ts

@@ -0,0 +1,11 @@
+import { AssociationTarget } from '../types.js'
+
+/**
+ * Creates a consistent key for a given association target within its domain.
+ *
+ * @param target The association target to create a key for.
+ * @returns A unique key for the association target.
+ */
+export function createDomainKey(target: AssociationTarget): string {
+  return target.domain ? `${target.domain}:${target.key}` : target.key
+}

package/src/modeling/readme.md

@@ -122,13 +122,159 @@ Let's imagine a simple e-commerce domain:
 - **Entity-Parent**: A `DomainEntity` can have `DomainEntity` instances as parents.
 - **Namespace-Foreign**: A `DomainNamespace` can have references to `DomainNamespace` instances.
 
+## API Modeling
+
+Beyond data modeling, the system also provides **API Modeling** capabilities that allow you to define how your data domain is exposed as a secure, production-ready API.
+
+### ApiModel
+
+The `ApiModel` class extends the data modeling system to define how Data Entities from a `DataDomain` are exposed via HTTP APIs. It provides configuration for:
+
+**Core API Configuration:**
+
+- **Exposed Entities**: Select which Data Entities from your Data Domain should be accessible via the API
+- **API Actions**: Define what operations (List, Read, Create, Update, Delete, Search) are available for each entity
+- **User Entity**: Designate which Data Entity represents a "User" for authentication purposes
+
+**Security & Authentication:**
+
+- **Authentication**: Configure how users prove their identity (e.g., username/password)
+- **Authorization**: Define what authenticated users are allowed to do (e.g., Role-Based Access Control)
+- **Session Management**: Configure transport and payload for user sessions (JWT, cookies)
+- **Access Rules**: Define fine-grained access control policies for entities and actions
+
+**API Metadata:**
+
+- **Contact Information**: API maintainer details
+- **License Information**: Legal information about API usage
+- **Terms of Service**: Link to API usage terms
+- **Rate Limiting**: Protect the API from overuse and abuse
+
+### How API Modeling Works with Data Modeling
+
+The API modeling system builds on top of the data modeling foundation:
+
+1. **Start with a Data Domain**: Create your `DataDomain` with entities, properties, and associations
+2. **Create an API Model**: Instantiate an `ApiModel` and attach your `DataDomain`
+3. **Expose Entities**: Select which entities should be available via the API using `exposeEntity()`
+4. **Configure Security**: Set up authentication, authorization, and session management
+5. **Define Actions**: Configure what operations are available for each exposed entity
+6. **Set API Metadata**: Add contact info, license, terms of service
+
+### Example: E-Commerce API
+
+Building on the e-commerce data domain example:
+
+```typescript
+// 1. Create the data domain (as shown in previous example)
+const domain = new DataDomain({ key: 'ecommerce', info: { name: 'E-Commerce Platform' } })
+const userModel = domain.addModel({ info: { name: 'User Management' } })
+const userEntity = userModel.addEntity({ 
+  info: { name: 'user' },
+  semantics: [{ type: SemanticType.User }] // Mark as User entity
+})
+
+// 2. Create an API model
+const apiModel = new ApiModel({
+  info: { name: 'E-Commerce API', version: '1.0.0' },
+  termsOfService: 'https://example.com/terms',
+  contact: { name: 'API Team', email: 'api@example.com' },
+  license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' }
+})
+
+// 3. Attach the data domain
+apiModel.attachDataDomain(domain)
+
+// 4. Configure security
+apiModel.user = { key: userEntity.key }
+apiModel.authentication = { strategy: 'UsernamePassword', passwordKey: 'password' }
+apiModel.authorization = { strategy: 'RBAC', roleKey: 'role' }
+apiModel.session = { 
+  secret: 'your-secure-secret',
+  properties: ['email', 'role'],
+  cookie: { enabled: true, kind: 'cookie', lifetime: '7d' }
+}
+
+// 5. Expose entities and configure actions
+const exposedUser = apiModel.exposeEntity(userEntity.key)
+exposedUser.actions = [
+  { type: 'Read', enabled: true },
+  { type: 'Update', enabled: true },
+  { type: 'Create', enabled: true }
+]
+```
+
+### Key API Modeling Concepts
+
+#### ExposedEntity
+
+Represents a Data Entity that is exposed via the API. Contains:
+
+- **Key**: Reference to the Data Entity
+- **Actions**: List of available API operations (CRUD, Search)
+- **Access Rules**: Entity-specific access control
+- **Rate Limiting**: Entity-specific rate limiting rules
+
+#### API Actions
+
+Standard RESTful operations that can be enabled for each entity:
+
+- **List**: Retrieve collections of entities with filtering and pagination
+- **Read**: Retrieve a single entity by ID
+- **Create**: Create new entities
+- **Update**: Modify existing entities
+- **Delete**: Remove entities
+- **Search**: Full-text or advanced search across entities
+
+#### Authentication Configuration
+
+Defines how users prove their identity:
+
+- **UsernamePassword**: Traditional email/password authentication
+- Extensible for future strategies (SSO, OAuth, etc.)
+
+#### Authorization Configuration
+
+Defines what authenticated users can do:
+
+- **RBAC (Role-Based Access Control)**: Users have roles, permissions granted to roles
+- Extensible for future strategies (PBAC - Permission-Based Access Control)
+
+#### Session Configuration
+
+Manages user session data:
+
+- **Properties**: Which User entity properties to include in session
+- **Transport**: How session data is transmitted (JWT tokens, cookies)
+- **Security**: Encryption, lifetime, and security settings
+
+### Business-First API Design
+
+The API modeling system follows the same business-first philosophy as data modeling:
+
+- **Semantic Awareness**: Uses semantic types to automatically configure security (e.g., Password properties are write-only)
+- **Standard Compliance**: Generates OpenAPI-compliant specifications
+- **Security by Default**: Requires explicit configuration for authentication, authorization, and sessions
+- **User-Friendly**: Clear error messages and validation feedback
+- **Production Ready**: Built-in support for rate limiting, access control, and monitoring
+
 ## Summary
 
-This data modeling system provides a flexible and powerful way to define complex data domains. It allows you to:
+This comprehensive modeling system provides both **Data Modeling** and **API Modeling** capabilities:
+
+**Data Modeling** allows you to:
+
+- **Organize**: Group related data into namespaces and models
+- **Structure**: Define entities with properties and relationships
+- **Reuse**: Inherit from other entities and reference foreign namespaces
+- **Translate**: Define bindings to map the model to different formats
+- **Validate**: Validate the data model definition
+- **Generate**: Generate AMF shapes and examples
+
+**API Modeling** extends this to:
 
-- **Organize**: Group related data into namespaces and models.
-- **Structure**: Define entities with properties and relationships.
-- **Reuse**: Inherit from other entities and reference foreign namespaces.
-- **Translate**: Define bindings to map the model to different formats.
-- **Validate**: Validate the data model definition.
-- **Generate**: Generate AMF shapes and examples.
+- **Expose**: Selectively expose Data Entities as API resources
+- **Secure**: Configure authentication, authorization, and session management
+- **Control**: Define fine-grained access rules and rate limiting
+- **Document**: Generate complete API documentation with business context
+- **Deploy**: Create production-ready APIs with proper security and monitoring

package/src/modeling/types.ts

@@ -428,25 +428,101 @@ export interface UsernamePasswordConfiguration extends AuthenticationConfigurati
  */
 export interface ExposedEntity {
   /**
-   * The key of the Data Entity from the Data Domain.
+   * The unique identifier for this exposure instance.
+   * In the exposure model, we need to uniquely identify each exposure instance, because
+   * an entity can be exposed multiple times in different contexts. Consider the following structure:
+   *
+   * ```
+   * /categories/{categoryId}
+   * /products/{productId}/categories
+   * /products/{productId}/categories/{categoryId}
+   * /promotions/{promotionId}/categories
+   * /promotions/{promotionId}/categories/{categoryId}
+   * ```
+   *
+   * The `category` entity would be exposed multiple times (as root and nested under products and promotions).
+   * We need a way to distinguish between these different exposure instances.
    */
   key: string
+  /**
+   * A pointer to a Data Entity from the Data Domain.
+   */
+  entity: AssociationTarget
+  /**
+   * The path segment for this exposure.
+   */
+  path: string
 
   /**
-   * Optional configuration for resource-wide rate limiting and throttling.
-   * Defines rules to protect the resource from overuse.
+   * Whether this exposure is a root exposure (top-level collection).
+   * If this is set then the `parent` reference must be populated.
    */
-  rateLimiting?: RateLimitingConfiguration
+  isRoot?: boolean
+
   /**
-   * Access control rules defining who can perform actions on this resource or collection.
-   * It override the top-level access rules defined in the API model.
+   * Parent reference when this exposure was created via following an association.
    */
-  accessRule?: AccessRule[]
+  parent?: ExposeParentRef
 
   /**
-   * The collection of API actions (e.g., List, Read, Create) enabled for this entity.
+   * Expose-time config used to create this exposure (persisted for auditing/UI).
+   * This is only populated for the root exposure. All children exposures inherit this config.
+   */
+  exposeOptions?: ExposeOptions
+
+  /**
+   * The list of enabled API actions for this exposure (List/Read/Create/etc.)
    */
   actions: ApiAction[]
+
+  /**
+   * Optional array of access rules that define the access control policies for this exposure.
+   */
+  accessRule?: AccessRule[]
+
+  /**
+   * Optional configuration for rate limiting for this exposure.
+   */
+  rateLimiting?: RateLimitingConfiguration
+
+  /**
+   * When true, generation for this exposure hit configured limits
+   */
+  truncated?: boolean
+}
+
+/**
+ * Parent reference stored on a nested exposure
+ */
+export interface ExposeParentRef {
+  /**
+   * The key of the parent exposed entity. This references the `ExposedEntity.key` property.
+   */
+  key: string
+  /**
+   * The association from the parent that produced this exposure.
+   * A sub-entity must always have a parent association.
+   */
+  association: AssociationTarget
+  /**
+   * The numeric depth from the root exposure (root = 0)
+   */
+  depth?: number
+}
+
+/**
+ * Options passed when creating a new exposure
+ */
+export interface ExposeOptions {
+  /**
+   * Whether to follow associations when creating the exposure.
+   * When not set, it only exposes the passed entity.
+   */
+  followAssociations?: boolean
+  /**
+   * The maximum depth to follow associations when creating the exposure.
+   */
+  maxDepth?: number
 }
 
 /**