@api-client/core 0.18.27 → 0.18.29

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
 }
 
 /**
@@ -665,7 +741,7 @@ export interface MatchUserRoleAccessRule extends BaseAccessRule {
    * The domain model should annotate this property with the "UserRole" semantic
    * to indicate that it is used for role-based access control.
    */
-  role: string
+  role: string[]
 }
 /**
  * The action is allowed if a specific property on the authenticated user matches an expected value.

package/tests/unit/modeling/api_model.spec.ts

@@ -10,10 +10,7 @@ import {
   type ApiLicense,
 } from '../../../src/index.js'
 
-test.group('ApiModel.createSchema()', (g) => {
-  g.tests.forEach((test) => {
-    test.tags(['@modeling', '@api', '@schema'])
-  })
+test.group('ApiModel.createSchema()', () => {
   test('creates a schema with default values', ({ assert }) => {
     const schema = ApiModel.createSchema()
     assert.equal(schema.kind, ApiModelKind)
@@ -31,13 +28,13 @@ test.group('ApiModel.createSchema()', (g) => {
     assert.isUndefined(schema.termsOfService)
     assert.isUndefined(schema.contact)
     assert.isUndefined(schema.license)
-  })
+  }).tags(['@modeling', '@api', '@schema'])
 
   test('creates a schema with provided values', ({ assert }) => {
     const input: Partial<ApiModelSchema> = {
       key: 'test-api',
       info: { name: 'Test API', description: 'A test API' },
-      exposes: [{ key: 'entity1', actions: [] }],
+      exposes: [{ key: 'entity1', actions: [], path: '', entity: { key: 'entity1' } }],
       user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
@@ -54,7 +51,7 @@ test.group('ApiModel.createSchema()', (g) => {
     assert.equal(schema.kind, ApiModelKind)
     assert.equal(schema.key, 'test-api')
     assert.deepInclude(schema.info, { name: 'Test API', description: 'A test API' })
-    assert.deepEqual(schema.exposes, [{ key: 'entity1', actions: [] }])
+    assert.deepEqual(schema.exposes, [{ key: 'entity1', actions: [], path: '', entity: { key: 'entity1' } }])
     assert.deepEqual(schema.user, { key: 'user-entity' })
     assert.deepEqual(schema.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(schema.authentication, { strategy: 'UsernamePassword' })
@@ -65,24 +62,20 @@ test.group('ApiModel.createSchema()', (g) => {
     assert.equal(schema.termsOfService, 'https://example.com/terms')
     assert.deepEqual(schema.contact, { name: 'John Doe', email: 'john.doe@example.com' })
     assert.deepEqual(schema.license, { name: 'MIT', url: 'https://opensource.org/licenses/MIT' })
-  })
+  }).tags(['@modeling', '@api', '@schema'])
 
   test('creates a schema with partial info', ({ assert }) => {
     const schema = ApiModel.createSchema({ info: { name: 'Partial API' } })
     assert.deepInclude(schema.info, { name: 'Partial API' })
-  })
+  }).tags(['@modeling', '@api', '@schema'])
 
   test('creates a schema with empty info', ({ assert }) => {
     const schema = ApiModel.createSchema({ info: {} })
     assert.deepInclude(schema.info, { name: 'Unnamed API' })
-  })
+  }).tags(['@modeling', '@api', '@schema'])
 })
 
-test.group('ApiModel.constructor()', (g) => {
-  g.tests.forEach((test) => {
-    test.tags(['@modeling', '@api', '@creation'])
-  })
-
+test.group('ApiModel.constructor()', () => {
   test('creates an instance with default values', ({ assert }) => {
     const model = new ApiModel()
     assert.equal(model.kind, ApiModelKind)
@@ -100,14 +93,14 @@ test.group('ApiModel.constructor()', (g) => {
     assert.isUndefined(model.contact)
     assert.isUndefined(model.license)
     assert.deepEqual(model.dependencyList, [])
-  })
+  }).tags(['@modeling', '@api', '@creation'])
 
   test('creates an instance with provided schema values', ({ assert }) => {
     const schema: ApiModelSchema = {
       kind: ApiModelKind,
       key: 'test-api',
       info: { name: 'Test API', description: 'A test API' },
-      exposes: [{ key: 'entity1', actions: [] }],
+      exposes: [{ key: 'entity1', actions: [], path: '', entity: { key: 'entity1' } }],
       user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
@@ -123,7 +116,7 @@ test.group('ApiModel.constructor()', (g) => {
 
     assert.equal(model.key, 'test-api')
     assert.equal(model.info.name, 'Test API')
-    assert.deepEqual(model.exposes, [{ key: 'entity1', actions: [] }])
+    assert.deepEqual(model.exposes, [{ key: 'entity1', actions: [], path: '', entity: { key: 'entity1' } }])
     assert.deepEqual(model.user, { key: 'user-entity' })
     assert.deepEqual(model.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(model.authentication, { strategy: 'UsernamePassword' })
@@ -134,7 +127,7 @@ test.group('ApiModel.constructor()', (g) => {
     assert.equal(model.termsOfService, 'https://example.com/terms')
     assert.deepEqual(model.contact, { name: 'John Doe', email: 'john.doe@example.com' })
     assert.deepEqual(model.license, { name: 'MIT', url: 'https://opensource.org/licenses/MIT' })
-  })
+  }).tags(['@modeling', '@api', '@creation'])
 
   test('creates an instance with a DataDomain', ({ assert }) => {
     const domainSchema = DataDomain.createSchema({ key: 'my-domain' })
@@ -146,7 +139,7 @@ test.group('ApiModel.constructor()', (g) => {
     assert.isDefined(model.domain)
     assert.instanceOf(model.domain, DataDomain)
     assert.equal(model.domain!.key, 'my-domain')
-  })
+  }).tags(['@modeling', '@api', '@creation'])
 
   test('notifies change when info is modified', async ({ assert }) => {
     const model = new ApiModel()
@@ -157,13 +150,10 @@ test.group('ApiModel.constructor()', (g) => {
     model.info.name = 'New Name'
     await Promise.resolve() // Allow microtask to run
     assert.isTrue(notified)
-  })
+  }).tags(['@modeling', '@api', '@creation'])
 })
 
-test.group('ApiModel.toJSON()', (g) => {
-  g.tests.forEach((test) => {
-    test.tags(['@modeling', '@api', '@serialization'])
-  })
+test.group('ApiModel.toJSON()', () => {
   test('serializes default values', ({ assert }) => {
     const model = new ApiModel()
     const json = model.toJSON()
@@ -182,14 +172,14 @@ test.group('ApiModel.toJSON()', (g) => {
     assert.isUndefined(json.termsOfService)
     assert.isUndefined(json.contact)
     assert.isUndefined(json.license)
-  })
+  }).tags(['@modeling', '@api', '@serialization'])
 
   test('serializes all provided values', ({ assert }) => {
     const schema: ApiModelSchema = {
       kind: ApiModelKind,
       key: 'test-api',
       info: { name: 'Test API', description: 'A test API' },
-      exposes: [{ key: 'entity1', actions: [] }],
+      exposes: [{ key: 'entity1', actions: [], path: '', entity: { key: 'entity1' } }],
       user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
@@ -206,7 +196,7 @@ test.group('ApiModel.toJSON()', (g) => {
 
     assert.equal(json.key, 'test-api')
     assert.deepInclude(json.info, { name: 'Test API', description: 'A test API' })
-    assert.deepEqual(json.exposes, [{ key: 'entity1', actions: [] }])
+    assert.deepEqual(json.exposes, [{ key: 'entity1', actions: [], path: '', entity: { key: 'entity1' } }])
     assert.deepEqual(json.user, { key: 'user-entity' })
     assert.deepEqual(json.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(json.authentication, { strategy: 'UsernamePassword' })
@@ -217,125 +207,23 @@ test.group('ApiModel.toJSON()', (g) => {
     assert.equal(json.termsOfService, 'https://example.com/terms')
     assert.deepEqual(json.contact, { name: 'John Doe', email: 'john.doe@example.com' })
     assert.deepEqual(json.license, { name: 'MIT', url: 'https://opensource.org/licenses/MIT' })
-  })
-})
-
-test.group('ApiModel.exposeEntity()', (g) => {
-  g.tests.forEach((test) => {
-    test.tags(['@modeling', '@api'])
-  })
-  test('exposes a new entity', ({ assert }) => {
-    const model = new ApiModel()
-    const entityKey = 'new-entity'
-    const exposedEntity = model.exposeEntity(entityKey)
-
-    assert.isDefined(exposedEntity)
-    assert.equal(exposedEntity.key, entityKey)
-    assert.deepEqual(exposedEntity.actions, [])
-    assert.includeDeepMembers(model.exposes, [exposedEntity])
-  })
-
-  test('returns an existing entity if already exposed', ({ assert }) => {
-    const model = new ApiModel()
-    const entityKey = 'existing-entity'
-    const initialExposedEntity = model.exposeEntity(entityKey)
-    const retrievedExposedEntity = model.exposeEntity(entityKey)
-
-    assert.strictEqual(retrievedExposedEntity, initialExposedEntity)
-    assert.lengthOf(model.exposes, 1)
-  })
-
-  test('notifies change when a new entity is exposed', async ({ assert }) => {
-    const model = new ApiModel()
-    let notified = false
-    model.addEventListener('change', () => {
-      notified = true
-    })
-    model.exposeEntity('notify-entity')
-    await Promise.resolve() // Allow microtask to run
-    assert.isTrue(notified)
-  })
-
-  test('does not notify change if entity already exposed', async ({ assert }) => {
-    const model = new ApiModel()
-    model.exposeEntity('no-notify-entity') // First exposure
-    await Promise.resolve() // Allow microtask to run
-    let notified = false
-    model.addEventListener('change', () => {
-      notified = true
-    })
-    model.exposeEntity('no-notify-entity') // Second exposure
-    await Promise.resolve() // Allow microtask to run
-    assert.isFalse(notified)
-  })
-})
-
-test.group('ApiModel.removeEntity()', (g) => {
-  g.tests.forEach((test) => {
-    test.tags(['@modeling', '@api'])
-  })
-  test('removes an existing entity', ({ assert }) => {
-    const model = new ApiModel()
-    const entityKey = 'entity-to-remove'
-    model.exposeEntity(entityKey)
-    assert.lengthOf(model.exposes, 1)
-
-    model.removeEntity(entityKey)
-    assert.lengthOf(model.exposes, 0)
-  })
-
-  test('does nothing if entity does not exist', ({ assert }) => {
-    const model = new ApiModel()
-    model.exposeEntity('existing-entity')
-    const initialExposes = [...model.exposes]
-
-    model.removeEntity('non-existing-entity')
-    assert.deepEqual(model.exposes, initialExposes)
-  })
-
-  test('notifies change when an entity is removed', async ({ assert }) => {
-    const model = new ApiModel()
-    const entityKey = 'notify-remove-entity'
-    model.exposeEntity(entityKey)
-
-    let notified = false
-    model.addEventListener('change', () => {
-      notified = true
-    })
-    model.removeEntity(entityKey)
-    await Promise.resolve() // Allow microtask to run
-    assert.isTrue(notified)
-  })
-
-  test('does not notify change if entity to remove does not exist', async ({ assert }) => {
-    const model = new ApiModel()
-    let notified = false
-    model.addEventListener('change', () => {
-      notified = true
-    })
-    model.removeEntity('no-notify-remove-entity')
-    await Promise.resolve() // Allow microtask to run
-    assert.isFalse(notified)
-  })
+  }).tags(['@modeling', '@api', '@serialization'])
 })
 
-test.group('ApiModel.getExposedEntity()', (g) => {
-  g.tests.forEach((test) => {
-    test.tags(['@modeling', '@api'])
-  })
+test.group('ApiModel.getExposedEntity()', () => {
   test('returns an existing exposed entity', ({ assert }) => {
     const model = new ApiModel()
     const entityKey = 'get-entity'
-    const exposed: ExposedEntity = { key: entityKey, actions: [] }
+    const exposed: ExposedEntity = { key: entityKey, actions: [], path: '', entity: { key: entityKey } }
     model.exposes.push(exposed)
 
-    const retrievedEntity = model.getExposedEntity(entityKey)
+    const retrievedEntity = model.getExposedEntity({ key: entityKey })
     assert.deepEqual(retrievedEntity, exposed)
-  })
+  }).tags(['@modeling', '@api'])
 
   test('returns undefined if entity is not exposed', ({ assert }) => {
     const model = new ApiModel()
-    const retrievedEntity = model.getExposedEntity('non-exposed-entity')
+    const retrievedEntity = model.getExposedEntity({ key: 'non-exposed-entity' })
     assert.isUndefined(retrievedEntity)
-  })
+  }).tags(['@modeling', '@api'])
 })

package/tests/unit/modeling/api_model_expose_entity.spec.ts

@@ -0,0 +1,190 @@
+import { test } from '@japa/runner'
+import { ApiModel, DataDomain } from '../../../src/index.js'
+
+test.group('ApiModel.exposeEntity()', () => {
+  test('exposes a new entity', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    const exposedEntity = model.exposeEntity({ key: e1.key })
+
+    assert.isDefined(exposedEntity)
+    assert.typeOf(exposedEntity.key, 'string')
+    assert.deepEqual(exposedEntity.entity, { key: e1.key })
+    assert.deepEqual(exposedEntity.actions, [])
+    assert.includeDeepMembers(model.exposes, [exposedEntity])
+  }).tags(['@modeling', '@api'])
+
+  test('returns an existing entity if already exposed', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    const initialExposedEntity = model.exposeEntity({ key: e1.key })
+    const retrievedExposedEntity = model.exposeEntity({ key: e1.key })
+
+    assert.strictEqual(retrievedExposedEntity, initialExposedEntity)
+    assert.lengthOf(model.exposes, 1)
+  }).tags(['@modeling', '@api'])
+
+  test('notifies change when a new entity is exposed', async ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.exposeEntity({ key: e1.key })
+    await Promise.resolve() // Allow microtask to run
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@api'])
+
+  test('does not notify change if entity already exposed', async ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: e1.key }) // First exposure
+    await Promise.resolve() // Allow microtask to run
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.exposeEntity({ key: e1.key }) // Second exposure
+    await Promise.resolve() // Allow microtask to run
+    assert.isFalse(notified)
+  }).tags(['@modeling', '@api'])
+
+  test('exposes nested entities through associations', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    const eB = dm.addEntity({ info: { name: 'B' } })
+    // Add association from A to B
+    eA.addAssociation({ key: eB.key }, { info: { name: 'entityB' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    const exposedA = model.exposeEntity({ key: eA.key }, { followAssociations: true })
+    // Find nested exposure for B
+    const nestedB = model.exposes.find((e) => !e.isRoot && e.entity.key === eB.key)
+    assert.isDefined(nestedB)
+    assert.deepEqual(nestedB?.parent?.key, exposedA.key)
+    assert.strictEqual(nestedB?.path, 'entitybs')
+  })
+
+  test('does not infinitely expose circular associations', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    const eB = dm.addEntity({ info: { name: 'B' } })
+    // A -> B, B -> A
+    eA.addAssociation({ key: eB.key }, { info: { name: 'assocAB' } })
+    eB.addAssociation({ key: eA.key }, { info: { name: 'assocBA' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: eA.key }, { followAssociations: true, maxDepth: 4 })
+
+    assert.lengthOf(model.exposes, 2, 'has only 2 exposures')
+    // Should expose A (root), B (nested under A), but not infinitely nest
+    const exposedA = model.exposes.find((e) => e.isRoot && e.entity.key === eA.key)
+    const nestedB = model.exposes.find((e) => !e.isRoot && e.entity.key === eB.key)
+    // There should be only one nested exposure for B under A
+    assert.isDefined(exposedA)
+    assert.isDefined(nestedB)
+    // There should NOT be a nested exposure for A under B
+    const circularA = model.exposes.find((e) => !e.isRoot && e.entity.key === eA.key && e.parent?.key === nestedB?.key)
+    assert.isUndefined(circularA)
+  })
+
+  test('does not expose self-association as nested entity', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    // A -> A (self-association)
+    eA.addAssociation({ key: eA.key }, { info: { name: 'assocAA' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: eA.key }, { followAssociations: true })
+    // Should only expose A as root, not as nested
+    const exposedA = model.exposes.find((e) => e.isRoot && e.entity.key === eA.key)
+    const nestedA = model.exposes.find((e) => !e.isRoot && e.entity.key === eA.key)
+    assert.isDefined(exposedA)
+    assert.isUndefined(nestedA)
+  })
+
+  test('exposes multi-level associations (A -> B -> C)', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    const eB = dm.addEntity({ info: { name: 'B' } })
+    const eC = dm.addEntity({ info: { name: 'C' } })
+    eA.addAssociation({ key: eB.key }, { info: { name: 'toB' } })
+    eB.addAssociation({ key: eC.key }, { info: { name: 'toC' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: eA.key }, { followAssociations: true })
+    const nestedB = model.exposes.find((e) => !e.isRoot && e.entity.key === eB.key)
+    const nestedC = model.exposes.find((e) => !e.isRoot && e.entity.key === eC.key)
+    assert.isDefined(nestedB)
+    assert.isDefined(nestedC)
+    assert.deepEqual(nestedB?.parent?.key, model.exposes.find((e) => e.isRoot && e.entity.key === eA.key)?.key)
+    assert.deepEqual(nestedC?.parent?.key, nestedB?.key)
+  })
+
+  test('exposes multiple associations from one entity (A -> B, A -> C)', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    const eB = dm.addEntity({ info: { name: 'B' } })
+    const eC = dm.addEntity({ info: { name: 'C' } })
+    eA.addAssociation({ key: eB.key }, { info: { name: 'toB' } })
+    eA.addAssociation({ key: eC.key }, { info: { name: 'toC' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: eA.key }, { followAssociations: true })
+    const nestedB = model.exposes.find((e) => !e.isRoot && e.entity.key === eB.key)
+    const nestedC = model.exposes.find((e) => !e.isRoot && e.entity.key === eC.key)
+    assert.isDefined(nestedB)
+    assert.isDefined(nestedC)
+    assert.deepEqual(nestedB?.parent?.key, model.exposes.find((e) => e.isRoot && e.entity.key === eA.key)?.key)
+    assert.deepEqual(nestedC?.parent?.key, model.exposes.find((e) => e.isRoot && e.entity.key === eA.key)?.key)
+  })
+
+  test('respects maxDepth option (A -> B -> C -> D, maxDepth=2)', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    const eB = dm.addEntity({ info: { name: 'B' } })
+    const eC = dm.addEntity({ info: { name: 'C' } })
+    const eD = dm.addEntity({ info: { name: 'D' } })
+    eA.addAssociation({ key: eB.key }, { info: { name: 'toB' } })
+    eB.addAssociation({ key: eC.key }, { info: { name: 'toC' } })
+    eC.addAssociation({ key: eD.key }, { info: { name: 'toD' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: eA.key }, { followAssociations: true, maxDepth: 2 })
+    const nestedB = model.exposes.find((e) => !e.isRoot && e.entity.key === eB.key)
+    const nestedC = model.exposes.find((e) => !e.isRoot && e.entity.key === eC.key)
+    const nestedD = model.exposes.find((e) => !e.isRoot && e.entity.key === eD.key)
+    assert.isDefined(nestedB)
+    assert.isDefined(nestedC)
+    assert.isUndefined(nestedD)
+  })
+})

package/tests/unit/modeling/api_model_remove_entity.spec.ts

@@ -0,0 +1,82 @@
+import { test } from '@japa/runner'
+import { ApiModel, DataDomain } from '../../../src/index.js'
+
+test.group('ApiModel.removeEntity()', () => {
+  test('removes an existing entity', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: e1.key })
+    assert.lengthOf(model.exposes, 1)
+
+    model.removeEntity({ key: e1.key })
+    assert.lengthOf(model.exposes, 0)
+  }).tags(['@modeling', '@api'])
+
+  test('removes an entity and its nested children', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const eA = dm.addEntity({ info: { name: 'A' } })
+    const eB = dm.addEntity({ info: { name: 'B' } })
+    // A -> B
+    eA.addAssociation({ key: eB.key }, { info: { name: 'toB' } })
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: eA.key }, { followAssociations: true })
+    // Ensure nested exposure for B was created
+    const nestedB = model.exposes.find((e) => !e.isRoot && e.entity.key === eB.key)
+    assert.isDefined(nestedB)
+    assert.isAbove(model.exposes.length, 1)
+
+    // Remove root entity A and expect children to be removed as well
+    model.removeEntity({ key: eA.key })
+    assert.lengthOf(model.exposes, 0)
+  }).tags(['@modeling', '@api'])
+
+  test('does nothing if entity does not exist', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: e1.key })
+    const initialExposes = [...model.exposes]
+
+    model.removeEntity({ key: 'non-existing-entity' })
+    assert.deepEqual(model.exposes, initialExposes)
+  }).tags(['@modeling', '@api'])
+
+  test('notifies change when an entity is removed', async ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const e1 = dm.addEntity()
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+    model.exposeEntity({ key: e1.key })
+
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.removeEntity({ key: e1.key })
+    await Promise.resolve() // Allow microtask to run
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@api'])
+
+  test('does not notify change if entity to remove does not exist', async ({ assert }) => {
+    const model = new ApiModel()
+    let notified = false
+    model.addEventListener('change', () => {
+      notified = true
+    })
+    model.removeEntity({ key: 'no-notify-remove-entity' })
+    await Promise.resolve() // Allow microtask to run
+    assert.isFalse(notified)
+  }).tags(['@modeling', '@api'])
+})