@api-client/core 0.19.9 → 0.19.10

package/src/modeling/validation/api_model_validation_rules.md

@@ -0,0 +1,58 @@
+# ApiModel Validation Rules
+
+This document outlines the validation rules for the `ApiModel` schema. These rules ensure that an API model is structurally sound, secure, and ready for use or publication.
+
+Validations are evaluated with one of three severity levels:
+- **Error**: A blocker that makes the model invalid and must be resolved (e.g., missing required configurations or broken references).
+- **Warning**: A non-blocker, typically indicating missing optional but recommended properties, or non-optimal configurations.
+- **Info**: Informational messages about the model's status or suggestions for improvement.
+
+## 1. Core Properties
+- **`kind`** [Error]: Must be exactly the value defined by `ApiModelKind`.
+- **`key`** [Error]: Must be a defined, non-empty string.
+- **`info.name`** [Error]: The `info` property must be a valid structure with at least a `name` defined.
+- **`info.description`** [Warning]: It is highly recommended to provide a description for the API model.
+
+## 2. Domain Dependency
+- **Domain Attachment** [Error]: The API model must have an attached `DataDomain`.
+- **Domain Versioning** [Error]: The attached Data Domain must have a `version` defined (`domain.info.version`).
+
+## 3. Security & Access Control
+- **Authentication** [Error]: The `authentication` configuration is required.
+  - If the strategy is `UsernamePassword`, the `passwordKey` must be defined.
+- **Authorization** [Error]: The `authorization` configuration is required.
+  - If the strategy is `RBAC`, the `roleKey` must be defined.
+- **Session Configuration** [Error]: The `session` configuration is required and must meet the following criteria:
+  - **Secret**: A session encryption token (`secret`) is required.
+  - **Properties**: The `session.properties` array must have at least one property set (e.g. to identify the User ID).
+  - **RBAC Role Property**: If the authorization strategy is `RBAC`, the `session.properties` must also map the role property into the session payload.
+  - **Transports**: At least one session transport (such as `cookie` or `jwt`) must be configured and marked as `enabled`.
+- **User Entity** [Error]: A designated `user` entity reference is required. This reference must point to a Data Entity that is appropriately annotated with the `User` semantic.
+- **Action Access Rules** [Error]: Each configured operation (Action) must have at least one access rule defined that applies to it. This can be inherited from the API Model level, the Exposed Entity level, any parent Exposed Entity, or explicitly defined on the Action itself. 
+
+## 4. Exposures
+- **Path Integrity** [Error]:
+  - If an exposure `hasCollection` is true, it MUST have a `collectionPath` defined.
+  - The `collectionPath` (if present) must contain exactly one segment starting with `/`.
+  - The `resourcePath` MUST be defined. If it has a collection, the resource path must be exactly the collection path plus a single parameter segment (e.g., `/products/{productId}`). If it does not have a collection, it must be exactly two segments (e.g. `/profile/{id}`).
+- **Path Collisions** [Error]: For root exposures (`isRoot: true`), the `collectionPath` (if present) and `resourcePath` must be unique across the API model to prevent routing conflicts.
+- **Valid Entity Reference** [Error]: Each exposed entity must reference a valid entity `key` that exists within the attached `DataDomain`.
+- **Exposures Exist** [Warning]: If no entities are exposed, the API model will not generate any endpoints.
+
+## 5. API Actions
+- **Minimum Actions** [Error]: Each exposed entity must have at least one action added to it in the `actions` array.
+- **Rate Limiting** [Warning]: It is recommended to set up rate limiting for exposed entities and individual actions to protect the API.
+- **List Action** [Error/Warning]: 
+  - **Pagination** [Error]: The `List` action strictly requires a pagination definition (`pagination.kind` must be defined as `offset` or `cursor`).
+  - **Filtering/Sorting** [Warning]: It is recommended to define `filterableFields` and `sortableFields`, but it is up to the user.
+- **Search Action** [Error]: The `Search` action requires the user to define at least one indexable field in the `fields` array to perform the search on.
+- **Delete Action** [Error/Info]: 
+  - **Strategy** [Error]: The `Delete` action must define a deletion strategy (`soft` or `hard`).
+  - **Hard Delete Warning** [Info]: When the `hard` delete strategy is selected, print an info message that there will be no way to restore data.
+- **Update Action** [Error]: The `Update` action must have at least one update method chosen in the `allowedMethods` array (e.g., `PUT` or `PATCH`).
+
+## 6. Metadata
+- **Contact Email** [Error]: If `contact.email` is provided, it MUST be in the format of a valid email address.
+- **Contact URL** [Error]: If `contact.url` is provided, it MUST be in the format of a valid URL.
+- **License URL** [Error]: If `license.url` is provided, it MUST be in the format of a valid URL.
+- **Terms of Service / Contact / License info** [Info]: It's good practice to provide contact information, a license, and terms of service for a published API.

package/src/modeling/validation/association_validation.ts

@@ -86,9 +86,7 @@ export class AssociationValidation {
       return results
     }
     for (const target of association.targets) {
-      const entity = target.domain
-        ? this.domain.findForeignEntity(target.key, target.domain)
-        : this.domain.findEntity(target.key)
+      const entity = this.domain.findEntity(target.key, target.domain)
       if (!entity) {
         const message = `The "${label}" association has an invalid target "${target.key}".`
         const help = `The target must be defined in the domain.`

package/tests/unit/modeling/actions/Action.spec.ts

@@ -1,10 +1,11 @@
 import { test } from '@japa/runner'
 import { Action, AccessRule, RateLimitingConfiguration } from '../../../../src/modeling/index.js'
 import { type ActionSchema } from '../../../../src/modeling/actions/Action.js'
+import { type ExposedEntity } from '../../../../src/modeling/ExposedEntity.js'
 
 test.group('Action', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new Action()
+    const action = new Action({} as unknown as ExposedEntity)
     assert.equal(action.kind, '')
     assert.deepEqual(action.accessRule, [])
     assert.isUndefined(action.rateLimiting)
@@ -16,7 +17,7 @@ test.group('Action', () => {
       accessRule: [{ type: 'allowPublic' }],
       rateLimiting: { rules: [] },
     }
-    const action = new Action(schema)
+    const action = new Action({} as unknown as ExposedEntity, schema)
     assert.equal(action.kind, 'read')
     assert.lengthOf(action.accessRule, 1)
     assert.instanceOf(action.accessRule[0], AccessRule)
@@ -25,7 +26,7 @@ test.group('Action', () => {
   }).tags(['@modeling', '@action'])
 
   test('serializes to JSON', ({ assert }) => {
-    const action = new Action({
+    const action = new Action({} as unknown as ExposedEntity, {
       kind: 'write',
       accessRule: [{ type: 'allowPublic' }],
       rateLimiting: { rules: [] },
@@ -38,7 +39,7 @@ test.group('Action', () => {
   }).tags(['@modeling', '@action'])
 
   test('notifies change when kind changes', async ({ assert }) => {
-    const action = new Action({ kind: 'read' })
+    const action = new Action({} as unknown as ExposedEntity, { kind: 'read' })
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -52,7 +53,7 @@ test.group('Action', () => {
   }).tags(['@modeling', '@action', '@observed'])
 
   test('notifies change when accessRule array is replaced', async ({ assert }) => {
-    const action = new Action()
+    const action = new Action({} as unknown as ExposedEntity)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -64,7 +65,7 @@ test.group('Action', () => {
   }).tags(['@modeling', '@action', '@observed'])
 
   test('notifies change when rateLimiting is replaced', async ({ assert }) => {
-    const action = new Action()
+    const action = new Action({} as unknown as ExposedEntity)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -77,7 +78,7 @@ test.group('Action', () => {
 
   test('constructor copies accessRule array (immutability)', ({ assert }) => {
     const rules = [{ type: 'allowPublic' }]
-    const action = new Action({ kind: 'read', accessRule: rules })
+    const action = new Action({} as unknown as ExposedEntity, { kind: 'read', accessRule: rules })
 
     // Modify original array
     rules.push({ type: 'other' })
@@ -88,7 +89,7 @@ test.group('Action', () => {
   }).tags(['@modeling', '@action', '@immutability'])
 
   test('toJSON returns safe copy', ({ assert }) => {
-    const action = new Action({
+    const action = new Action({} as unknown as ExposedEntity, {
       kind: 'read',
       accessRule: [{ type: 'allowPublic' }],
       rateLimiting: { rules: [] },
@@ -106,4 +107,35 @@ test.group('Action', () => {
     assert.lengthOf(action.accessRule, 1)
     assert.equal(action.accessRule[0].type, 'allowPublic')
   }).tags(['@modeling', '@action', '@immutability'])
+
+  test('getAllRules() aggregates rules from action and parent', ({ assert }) => {
+    const parent = {
+      getAllRules: () => [new AccessRule({ type: 'allowPublic' })],
+    } as unknown as ExposedEntity
+
+    const action = new Action(parent, {
+      accessRule: [{ type: 'allowAuthenticated' }],
+    })
+
+    const rules = action.getAllRules()
+    assert.lengthOf(rules, 2)
+    assert.equal(rules[0].type, 'allowPublic')
+    assert.equal(rules[1].type, 'allowAuthenticated')
+  }).tags(['@modeling', '@action', '@rules'])
+
+  test('getAllRateLimiters() aggregates rate limiters from action and parent', ({ assert }) => {
+    const parentLimiter = new RateLimitingConfiguration({ rules: [{ rate: 10, interval: 'second' }] })
+    const parent = {
+      getAllRateLimiters: () => [parentLimiter],
+    } as unknown as ExposedEntity
+
+    const action = new Action(parent, {
+      rateLimiting: { rules: [{ rate: 20, interval: 'minute' }] },
+    })
+
+    const limiters = action.getAllRateLimiters()
+    assert.lengthOf(limiters, 2)
+    assert.equal(limiters[0].rules[0].rate, 10)
+    assert.equal(limiters[1].rules[0].rate, 20)
+  }).tags(['@modeling', '@action', '@rate-limiting'])
 })

package/tests/unit/modeling/actions/CreateAction.spec.ts

@@ -4,13 +4,13 @@ import { AccessRule } from '../../../../src/modeling/rules/index.js'
 
 test.group('CreateAction', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new CreateAction()
+    const action = new CreateAction({} as any)
     assert.equal(action.kind, 'create')
     assert.isEmpty(action.accessRule) // Inherited from Action
   }).tags(['@modeling', '@action', '@create-action'])
 
   test('initializes with inherited values', ({ assert }) => {
-    const action = new CreateAction({
+    const action = new CreateAction({} as any, {
       accessRule: [{ type: 'allowPublic' }],
     })
 
@@ -22,7 +22,7 @@ test.group('CreateAction', () => {
   test('constructor copies arrays (immutability)', ({ assert }) => {
     const rules = [{ type: 'allowPublic' }]
 
-    const action = new CreateAction({
+    const action = new CreateAction({} as any, {
       accessRule: rules,
     })
 
@@ -35,7 +35,7 @@ test.group('CreateAction', () => {
   }).tags(['@modeling', '@action', '@create-action', '@immutability'])
 
   test('toJSON returns valid schema', ({ assert }) => {
-    const action = new CreateAction({
+    const action = new CreateAction({} as any, {
       accessRule: [{ type: 'allowPublic' }],
     })
 
@@ -51,7 +51,7 @@ test.group('CreateAction', () => {
   }).tags(['@modeling', '@action', '@create-action', '@serialization'])
 
   test('notifies change when inherited property changes', async ({ assert }) => {
-    const action = new CreateAction()
+    const action = new CreateAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true

package/tests/unit/modeling/actions/DeleteAction.spec.ts

@@ -3,7 +3,7 @@ import { DeleteAction } from '../../../../src/modeling/actions/DeleteAction.js'
 
 test.group('DeleteAction', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new DeleteAction()
+    const action = new DeleteAction({} as any)
     assert.equal(action.kind, 'delete')
     assert.equal(action.strategy, 'soft')
     assert.equal(action.retentionPeriod, 30)
@@ -11,7 +11,7 @@ test.group('DeleteAction', () => {
   }).tags(['@modeling', '@action', '@delete-action'])
 
   test('initializes with provided values', ({ assert }) => {
-    const action = new DeleteAction({
+    const action = new DeleteAction({} as any, {
       strategy: 'hard',
       retentionPeriod: 0,
       accessRule: [{ type: 'allowPublic' }],
@@ -27,7 +27,7 @@ test.group('DeleteAction', () => {
   test('constructor copies arrays (immutability)', ({ assert }) => {
     const rules = [{ type: 'allowPublic' }]
 
-    const action = new DeleteAction({
+    const action = new DeleteAction({} as any, {
       accessRule: rules,
     })
 
@@ -40,7 +40,7 @@ test.group('DeleteAction', () => {
   }).tags(['@modeling', '@action', '@delete-action', '@immutability'])
 
   test('toJSON returns valid schema', ({ assert }) => {
-    const action = new DeleteAction({
+    const action = new DeleteAction({} as any, {
       strategy: 'hard',
       retentionPeriod: 0,
     })
@@ -53,7 +53,7 @@ test.group('DeleteAction', () => {
   }).tags(['@modeling', '@action', '@delete-action', '@serialization'])
 
   test('notifies change when strategy changes', async ({ assert }) => {
-    const action = new DeleteAction()
+    const action = new DeleteAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -65,7 +65,7 @@ test.group('DeleteAction', () => {
   }).tags(['@modeling', '@action', '@delete-action', '@observed'])
 
   test('notifies change when retentionPeriod changes', async ({ assert }) => {
-    const action = new DeleteAction()
+    const action = new DeleteAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true

package/tests/unit/modeling/actions/ListAction.spec.ts

@@ -4,7 +4,7 @@ import { PaginationStrategy } from '../../../../src/modeling/types.js'
 
 test.group('ListAction', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new ListAction()
+    const action = new ListAction({} as any)
     assert.equal(action.kind, 'list')
     assert.deepEqual(action.pagination, { kind: 'offset' })
     assert.deepEqual(action.filterableFields, [])
@@ -17,7 +17,7 @@ test.group('ListAction', () => {
     const filterableFields = ['name', 'status']
     const sortableFields = ['createdAt']
 
-    const action = new ListAction({
+    const action = new ListAction({} as any, {
       pagination,
       filterableFields,
       sortableFields,
@@ -33,7 +33,7 @@ test.group('ListAction', () => {
     const filterableFields = ['name']
     const sortableFields = ['name']
 
-    const action = new ListAction({
+    const action = new ListAction({} as any, {
       pagination,
       filterableFields,
       sortableFields,
@@ -50,7 +50,7 @@ test.group('ListAction', () => {
   }).tags(['@modeling', '@action', '@list-action', '@immutability'])
 
   test('toJSON returns safe copy', ({ assert }) => {
-    const action = new ListAction({
+    const action = new ListAction({} as any, {
       pagination: { kind: 'offset' },
       filterableFields: ['name'],
       sortableFields: ['name'],
@@ -69,7 +69,7 @@ test.group('ListAction', () => {
   }).tags(['@modeling', '@action', '@list-action', '@immutability'])
 
   test('notifies change when pagination changes', async ({ assert }) => {
-    const action = new ListAction()
+    const action = new ListAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -81,7 +81,7 @@ test.group('ListAction', () => {
   }).tags(['@modeling', '@action', '@list-action', '@observed'])
 
   test('notifies change when filterableFields changes', async ({ assert }) => {
-    const action = new ListAction()
+    const action = new ListAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -93,7 +93,7 @@ test.group('ListAction', () => {
   }).tags(['@modeling', '@action', '@list-action', '@observed'])
 
   test('notifies change when sortableFields changes', async ({ assert }) => {
-    const action = new ListAction()
+    const action = new ListAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true

package/tests/unit/modeling/actions/ReadAction.spec.ts

@@ -4,13 +4,13 @@ import { AccessRule } from '../../../../src/modeling/rules/index.js'
 
 test.group('ReadAction', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new ReadAction()
+    const action = new ReadAction({} as any)
     assert.equal(action.kind, 'read')
     assert.isEmpty(action.accessRule) // Inherited from Action
   }).tags(['@modeling', '@action', '@read-action'])
 
   test('initializes with inherited values', ({ assert }) => {
-    const action = new ReadAction({
+    const action = new ReadAction({} as any, {
       accessRule: [{ type: 'allowPublic' }],
     })
 
@@ -22,7 +22,7 @@ test.group('ReadAction', () => {
   test('constructor copies arrays (immutability)', ({ assert }) => {
     const rules = [{ type: 'allowPublic' }]
 
-    const action = new ReadAction({
+    const action = new ReadAction({} as any, {
       accessRule: rules,
     })
 
@@ -35,7 +35,7 @@ test.group('ReadAction', () => {
   }).tags(['@modeling', '@action', '@read-action', '@immutability'])
 
   test('toJSON returns valid schema', ({ assert }) => {
-    const action = new ReadAction({
+    const action = new ReadAction({} as any, {
       accessRule: [{ type: 'allowPublic' }],
     })
 
@@ -51,7 +51,7 @@ test.group('ReadAction', () => {
   }).tags(['@modeling', '@action', '@read-action', '@serialization'])
 
   test('notifies change when inherited property changes', async ({ assert }) => {
-    const action = new ReadAction()
+    const action = new ReadAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -64,7 +64,7 @@ test.group('ReadAction', () => {
   }).tags(['@modeling', '@action', '@read-action', '@observed'])
 
   test('notifies change when accessRule value change', async ({ assert }) => {
-    const action = new ReadAction()
+    const action = new ReadAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true

package/tests/unit/modeling/actions/SearchAction.spec.ts

@@ -3,7 +3,7 @@ import { SearchAction } from '../../../../src/modeling/actions/SearchAction.js'
 
 test.group('SearchAction', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new SearchAction()
+    const action = new SearchAction({} as any)
     assert.equal(action.kind, 'search')
     assert.deepEqual(action.fields, [])
     assert.isEmpty(action.accessRule)
@@ -11,7 +11,7 @@ test.group('SearchAction', () => {
 
   test('initializes with provided values', ({ assert }) => {
     const fields = ['name', 'description']
-    const action = new SearchAction({
+    const action = new SearchAction({} as any, {
       fields,
     })
 
@@ -22,7 +22,7 @@ test.group('SearchAction', () => {
   test('constructor copies arrays (immutability)', ({ assert }) => {
     const fields = ['name']
 
-    const action = new SearchAction({
+    const action = new SearchAction({} as any, {
       fields,
     })
 
@@ -33,7 +33,7 @@ test.group('SearchAction', () => {
   }).tags(['@modeling', '@action', '@search-action', '@immutability'])
 
   test('toJSON returns valid schema', ({ assert }) => {
-    const action = new SearchAction({
+    const action = new SearchAction({} as any, {
       fields: ['name'],
     })
 
@@ -48,7 +48,7 @@ test.group('SearchAction', () => {
   }).tags(['@modeling', '@action', '@search-action', '@serialization', '@immutability'])
 
   test('notifies change when fields changes', async ({ assert }) => {
-    const action = new SearchAction()
+    const action = new SearchAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -60,7 +60,7 @@ test.group('SearchAction', () => {
   }).tags(['@modeling', '@action', '@search-action', '@observed'])
 
   test('notifies change when fields value change', async ({ assert }) => {
-    const action = new SearchAction()
+    const action = new SearchAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true

package/tests/unit/modeling/actions/UpdateAction.spec.ts

@@ -3,7 +3,7 @@ import { UpdateAction } from '../../../../src/modeling/actions/UpdateAction.js'
 
 test.group('UpdateAction', () => {
   test('initializes with default values', ({ assert }) => {
-    const action = new UpdateAction()
+    const action = new UpdateAction({} as any)
     assert.equal(action.kind, 'update')
     assert.deepEqual(action.allowedMethods, ['PATCH'])
     assert.isEmpty(action.accessRule)
@@ -11,7 +11,7 @@ test.group('UpdateAction', () => {
 
   test('initializes with provided values', ({ assert }) => {
     const methods: ('PUT' | 'PATCH')[] = ['PUT', 'PATCH']
-    const action = new UpdateAction({
+    const action = new UpdateAction({} as any, {
       allowedMethods: methods,
     })
 
@@ -22,7 +22,7 @@ test.group('UpdateAction', () => {
   test('constructor copies arrays (immutability)', ({ assert }) => {
     const methods: ('PUT' | 'PATCH')[] = ['PUT']
 
-    const action = new UpdateAction({
+    const action = new UpdateAction({} as any, {
       allowedMethods: methods,
     })
 
@@ -33,7 +33,7 @@ test.group('UpdateAction', () => {
   }).tags(['@modeling', '@action', '@update-action', '@immutability'])
 
   test('toJSON returns valid schema', ({ assert }) => {
-    const action = new UpdateAction({
+    const action = new UpdateAction({} as any, {
       allowedMethods: ['PUT'],
     })
 
@@ -48,7 +48,7 @@ test.group('UpdateAction', () => {
   }).tags(['@modeling', '@action', '@update-action', '@serialization', '@immutability'])
 
   test('notifies change when allowedMethods changes', async ({ assert }) => {
-    const action = new UpdateAction()
+    const action = new UpdateAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true
@@ -60,7 +60,7 @@ test.group('UpdateAction', () => {
   }).tags(['@modeling', '@action', '@update-action', '@observed'])
 
   test('notifies change when allowedMethods value change', async ({ assert }) => {
-    const action = new UpdateAction()
+    const action = new UpdateAction({} as any)
     let notified = false
     action.addEventListener('change', () => {
       notified = true