@api-client/core 0.18.57 → 0.18.58

package/src/modeling/types.ts

@@ -15,6 +15,9 @@ import type {
   ExposedEntityKind,
 } from '../models/kinds.js'
 import type { DataDomain } from './DataDomain.js'
+import { AccessRuleSchema } from './rules/AccessRule.js'
+import { RateLimitingConfigurationSchema } from './rules/RateLimitingConfiguration.js'
+import { ActionSchema } from './actions/Action.js'
 
 export interface DataDomainRemoveOptions {
   /**
@@ -488,17 +491,17 @@ export interface ExposedEntitySchema {
   /**
    * The list of enabled API actions for this exposure (List/Read/Create/etc.)
    */
-  actions: ApiAction[]
+  actions: ActionSchema[]
 
   /**
    * Optional array of access rules that define the access control policies for this exposure.
    */
-  accessRule?: AccessRule[]
+  accessRule?: AccessRuleSchema[]
 
   /**
    * Optional configuration for rate limiting for this exposure.
    */
-  rateLimiting?: RateLimitingConfiguration
+  rateLimiting?: RateLimitingConfigurationSchema
 
   /**
    * When true, generation for this exposure hit configured limits
@@ -540,40 +543,6 @@ export interface ExposeOptions {
   maxDepth?: number
 }
 
-/**
- * Represents a specific, configurable API operation applied to a Data Entity.
- * Corresponds to common RESTful interactions.
- */
-export type ApiAction = ListAction | ReadAction | CreateAction | UpdateAction | DeleteAction | SearchAction
-
-/**
- * A base interface for common properties across all actions.
- */
-interface Action {
-  /**
-   * The specific kind of action (e.g., 'List', 'Read', etc.)
-   */
-  kind: string
-  /**
-   * Access control rules defining who can perform this action. It is only applied if the
-   * authorization strategy is set to 'RBAC'.
-   * If no rules grant access, it's denied by default making it essentially private.
-   *
-   * Note, the API can defined top level access rules that apply to all actions. If this property is set,
-   * it overrides the top level access rules for this specific action.
-   *
-   * It is an ordered list, meaning the first rule that matches the user will be applied.
-   * If multiple rules match, the first one in the list takes precedence.
-   * If no rules match, the action is denied.
-   */
-  accessRule?: AccessRule[]
-  /**
-   * Optional configuration for action-wide rate limiting and throttling.
-   * Defines rules to protect the action from overuse.
-   */
-  rateLimiting?: RateLimitingConfiguration
-}
-
 /**
  * Represents a pagination strategy for API actions that return collections of resources.
  * This is a base interface that can be extended for different pagination strategies.
@@ -605,245 +574,6 @@ export interface OffsetPaginationStrategy extends PaginationStrategy {
   kind: 'offset'
 }
 
-/**
- * Enables retrieving a collection of resources.
- * Endpoint: GET /[entity-collection-name]
- */
-export interface ListAction extends Action {
-  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'.
-   */
-  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[]
-}
-
-/**
- * Enables retrieving a single resource by its ID.
- * Endpoint: GET /[entity-collection-name]/{id}
- */
-export interface ReadAction extends Action {
-  kind: 'read'
-  // Association handling (Link IDs vs. Embed) is defined on the
-  // data association itself in the Data Modeler.
-}
-
-/**
- * Enables adding a new resource to a collection.
- * Endpoint: POST /[entity-collection-name]
- */
-export interface CreateAction extends Action {
-  kind: 'create'
-}
-
-/**
- * Enables modifying an existing resource.
- * Endpoints: PUT or PATCH /[entity-collection-name]/{id}
- */
-export interface UpdateAction extends Action {
-  kind: 'update'
-  /**
-   * The allowed HTTP methods for updates. Default: PATCH only.
-   *
-   * These two methods represent the two common ways to update a resource:
-   * - PUT: Replaces the entire resource with the provided data.
-   * - PATCH: Applies a partial update to the resource, allowing for specific fields to be modified.
-   */
-  allowedMethods: ('PUT' | 'PATCH')[]
-}
-
-/**
- * Enables removing an existing resource.
- * Endpoint: DELETE /[entity-collection-name]/{id}
- */
-export interface DeleteAction extends Action {
-  kind: 'delete'
-  /**
-   * The strategy for deletion. Default: Soft Delete.
-   *
-   * @default 'soft'
-   */
-  strategy?: 'soft' | 'hard'
-  /**
-   * The data retention period (in days) for soft-deleted resources.
-   * This defines how long the data should be kept before it is permanently deleted.
-   *
-   * @default 30
-   */
-  retentionPeriod?: number
-}
-
-/**
- * Enables keyword-based search across specified fields.
- * Endpoint: GET /[entity-collection-name]/search
- */
-export interface SearchAction extends Action {
-  kind: 'search'
-  /**
-   * The fields within the entity to be included in the search scope.
-   * Must be "indexable" and typically text-based.
-   */
-  fields: string[]
-}
-
-/**
- * Defines the access control policy for a specific API action.
- * Based on the predefined rule types for session-based authentication.
- */
-export type AccessRule =
-  | AllowPublicAccessRule
-  | AllowAuthenticatedAccessRule
-  | MatchResourceOwnerAccessRule
-  | MatchUserRoleAccessRule
-  | MatchUserPropertyAccessRule
-  | MatchEmailDomainAccessRule
-
-export interface BaseAccessRule {
-  /**
-   * The unique identifier for the access rule.
-   * This is used to reference the rule in the API configuration.
-   */
-  type: string
-}
-
-/**
- * The action is allowed for all users, including unauthenticated ones.
- * This is typically used for public APIs or resources that do not require authentication.
- * It is the most permissive rule and should be used with caution.
- */
-export interface AllowPublicAccessRule extends BaseAccessRule {
-  type: 'public'
-}
-/**
- * The action is allowed for any authenticated user.
- * This rule does not impose any additional restrictions based on user properties or resource ownership.
- * It is used for resources that should be accessible to all logged-in users.
- */
-export interface AllowAuthenticatedAccessRule extends BaseAccessRule {
-  type: 'authenticated'
-}
-/**
- * The action is allowed if the authenticated user's ID matches a specific property on the resource.
- * This is typically used to restrict access to resources owned by the user.
- * For example, a user can only access their own profile or documents.
- */
-export interface MatchResourceOwnerAccessRule extends BaseAccessRule {
-  type: 'resourceOwner'
-  /**
-   * The property on the resource that should match the authenticated user's ID.
-   * This is typically the ID of the user who owns the resource.
-   *
-   * The domain model should annotate this property with the "ResourceOwnerIdentifier" semantic
-   * to indicate that it is used for ownership checks.
-   */
-  property: string
-}
-
-/**
- * The action is allowed if the authenticated user has a specific role.
- * This is used to enforce role-based access control (RBAC).
- * For example, only users with the "admin" role can perform certain actions.
- */
-export interface MatchUserRoleAccessRule extends BaseAccessRule {
-  type: 'matchUserRole'
-  /**
-   * The role that the authenticated user must have to access the resource.
-   * This is typically a property on the user entity that defines their role.
-   *
-   * The domain model should annotate this property with the "UserRole" semantic
-   * to indicate that it is used for role-based access control.
-   */
-  role: string[]
-}
-/**
- * The action is allowed if a specific property on the authenticated user matches an expected value.
- * This is used to enforce other user-specific restrictions.
- */
-export interface MatchUserPropertyAccessRule extends BaseAccessRule {
-  type: 'matchUserProperty'
-  /**
-   * The property on the authenticated user that should match the expected value.
-   */
-  property: string
-  /**
-   * The expected value for the user property.
-   */
-  value: string
-}
-/**
- * The action is allowed if the authenticated user's email domain matches a specific domain.
- * This is used to restrict access based on the user's email address.
- * For example, only users with an email address from "my-company.com" can access certain resources.
- */
-export interface MatchEmailDomainAccessRule extends BaseAccessRule {
-  type: 'matchEmailDomain'
-  /**
-   * The email domains that the authenticated user's email must match.
-   */
-  domains: string[]
-}
-
-/**
- * Defines the rate limiting and throttling policies for the entire API.
- */
-export interface RateLimitingConfiguration {
-  /**
-   * An ordered list of rules. The first rule that matches an incoming
-   * request will be applied.
-   */
-  rules: RateLimitRule[]
-}
-
-/**
- * Represents a single rate limiting rule that applies to a specific
- * type of client, using a token bucket algorithm.
- */
-export interface RateLimitRule {
-  /**
-   * A human-readable description of what this rule is for.
-   * e.g., "Limit anonymous users to 60 requests per hour."
-   */
-  description?: string
-
-  /**
-   * Defines how to group requests for rate limiting. This determines
-   * who the limit applies to.
-   *
-   * - 'ip': Keys on the client's IP address. Best for anonymous traffic.
-   * - 'userId': Keys on the authenticated user's ID. Best for logged-in users.
-   * - 'role': Applies a shared limit to all users of a specific role.
-   */
-  key: { type: 'ip' } | { type: 'userId' } | { type: 'role'; value: string }
-
-  /**
-   * The number of requests allowed over the defined interval.
-   * This is the rate at which tokens are added to the bucket.
-   */
-  rate: number
-
-  /**
-   * The time interval for the rate.
-   */
-  interval: 'second' | 'minute' | 'hour' | 'day'
-
-  /**
-   * The maximum number of requests that can be made in a burst.
-   * This represents the "bucket size." A larger burst allows for
-   * more requests to be made in a short period before throttling begins.
-   */
-  burst: number
-}
-
 export type DomainImpactKinds =
   | typeof DomainNamespaceKind
   | typeof DomainEntityKind

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

@@ -0,0 +1,109 @@
+import { test } from '@japa/runner'
+import { Action, AccessRule, RateLimitingConfiguration } from '../../../../src/modeling/index.js'
+import { type ActionSchema } from '../../../../src/modeling/actions/Action.js'
+
+test.group('Action', () => {
+  test('initializes with default values', ({ assert }) => {
+    const action = new Action()
+    assert.equal(action.kind, '')
+    assert.deepEqual(action.accessRule, [])
+    assert.isUndefined(action.rateLimiting)
+  }).tags(['@modeling', '@action'])
+
+  test('initializes with provided values', ({ assert }) => {
+    const schema: ActionSchema = {
+      kind: 'read',
+      accessRule: [{ type: 'public' }],
+      rateLimiting: { rules: [] },
+    }
+    const action = new Action(schema)
+    assert.equal(action.kind, 'read')
+    assert.lengthOf(action.accessRule, 1)
+    assert.instanceOf(action.accessRule[0], AccessRule)
+    assert.equal(action.accessRule[0].type, 'public')
+    assert.instanceOf(action.rateLimiting, RateLimitingConfiguration)
+  }).tags(['@modeling', '@action'])
+
+  test('serializes to JSON', ({ assert }) => {
+    const action = new Action({
+      kind: 'write',
+      accessRule: [{ type: 'admin' }],
+      rateLimiting: { rules: [] },
+    })
+    const json = action.toJSON()
+
+    assert.equal(json.kind, 'write')
+    assert.deepEqual(json.accessRule, [{ type: 'admin' }])
+    assert.deepEqual(json.rateLimiting, { rules: [] })
+  }).tags(['@modeling', '@action'])
+
+  test('notifies change when kind changes', async ({ assert }) => {
+    const action = new Action({ kind: 'read' })
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.kind = 'write'
+    // allow microtask to process the change
+    await Promise.resolve()
+
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@observed'])
+
+  test('notifies change when accessRule array is replaced', async ({ assert }) => {
+    const action = new Action()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.accessRule = [new AccessRule({ type: 'public' })]
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@observed'])
+
+  test('notifies change when rateLimiting is replaced', async ({ assert }) => {
+    const action = new Action()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.rateLimiting = new RateLimitingConfiguration()
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@observed'])
+
+  test('constructor copies accessRule array (immutability)', ({ assert }) => {
+    const rules = [{ type: 'public' }]
+    const action = new Action({ kind: 'read', accessRule: rules })
+
+    // Modify original array
+    rules.push({ type: 'admin' })
+    rules[0].type = 'changed'
+
+    assert.lengthOf(action.accessRule, 1)
+    assert.equal(action.accessRule[0].type, 'public')
+  }).tags(['@modeling', '@action', '@immutability'])
+
+  test('toJSON returns safe copy', ({ assert }) => {
+    const action = new Action({
+      kind: 'read',
+      accessRule: [{ type: 'public' }],
+      rateLimiting: { rules: [] },
+    })
+    const json = action.toJSON()
+
+    // Modify JSON
+    json.kind = 'write'
+    if (json.accessRule) {
+      json.accessRule[0].type = 'changed'
+      json.accessRule.push({ type: 'new' })
+    }
+
+    assert.equal(action.kind, 'read')
+    assert.lengthOf(action.accessRule, 1)
+    assert.equal(action.accessRule[0].type, 'public')
+  }).tags(['@modeling', '@action', '@immutability'])
+})

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

@@ -0,0 +1,65 @@
+import { test } from '@japa/runner'
+import { CreateAction } from '../../../../src/modeling/actions/CreateAction.js'
+import { AccessRule } from '../../../../src/modeling/rules/index.js'
+
+test.group('CreateAction', () => {
+  test('initializes with default values', ({ assert }) => {
+    const action = new CreateAction()
+    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({
+      accessRule: [{ type: 'public' }],
+    })
+
+    assert.equal(action.kind, 'create')
+    assert.lengthOf(action.accessRule, 1)
+    assert.equal(action.accessRule[0].type, 'public')
+  }).tags(['@modeling', '@action', '@create-action'])
+
+  test('constructor copies arrays (immutability)', ({ assert }) => {
+    const rules = [{ type: 'public' }]
+
+    const action = new CreateAction({
+      accessRule: rules,
+    })
+
+    // Modify original source
+    rules.push({ type: 'admin' })
+    rules[0].type = 'changed'
+
+    assert.lengthOf(action.accessRule, 1)
+    assert.equal(action.accessRule[0].type, 'public')
+  }).tags(['@modeling', '@action', '@create-action', '@immutability'])
+
+  test('toJSON returns valid schema', ({ assert }) => {
+    const action = new CreateAction({
+      accessRule: [{ type: 'public' }],
+    })
+
+    const json = action.toJSON()
+
+    assert.equal(json.kind, 'create')
+    if (json.accessRule) {
+      assert.lengthOf(json.accessRule, 1)
+      assert.equal(json.accessRule[0].type, 'public')
+    } else {
+      assert.fail('accessRule should be present in JSON')
+    }
+  }).tags(['@modeling', '@action', '@create-action', '@serialization'])
+
+  test('notifies change when inherited property changes', async ({ assert }) => {
+    const action = new CreateAction()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    // Modify inherited property
+    action.accessRule = [new AccessRule({ type: 'admin' })]
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@create-action', '@observed'])
+})

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

@@ -0,0 +1,78 @@
+import { test } from '@japa/runner'
+import { DeleteAction } from '../../../../src/modeling/actions/DeleteAction.js'
+
+test.group('DeleteAction', () => {
+  test('initializes with default values', ({ assert }) => {
+    const action = new DeleteAction()
+    assert.equal(action.kind, 'delete')
+    assert.equal(action.strategy, 'soft')
+    assert.equal(action.retentionPeriod, 30)
+    assert.isEmpty(action.accessRule) // Inherited from Action
+  }).tags(['@modeling', '@action', '@delete-action'])
+
+  test('initializes with provided values', ({ assert }) => {
+    const action = new DeleteAction({
+      strategy: 'hard',
+      retentionPeriod: 0,
+      accessRule: [{ type: 'admin' }],
+    })
+
+    assert.equal(action.kind, 'delete')
+    assert.equal(action.strategy, 'hard')
+    assert.equal(action.retentionPeriod, 0)
+    assert.lengthOf(action.accessRule, 1)
+    assert.equal(action.accessRule[0].type, 'admin')
+  }).tags(['@modeling', '@action', '@delete-action'])
+
+  test('constructor copies arrays (immutability)', ({ assert }) => {
+    const rules = [{ type: 'public' }]
+
+    const action = new DeleteAction({
+      accessRule: rules,
+    })
+
+    // Modify original source
+    rules.push({ type: 'admin' })
+    rules[0].type = 'changed'
+
+    assert.lengthOf(action.accessRule, 1)
+    assert.equal(action.accessRule[0].type, 'public')
+  }).tags(['@modeling', '@action', '@delete-action', '@immutability'])
+
+  test('toJSON returns valid schema', ({ assert }) => {
+    const action = new DeleteAction({
+      strategy: 'hard',
+      retentionPeriod: 0,
+    })
+
+    const json = action.toJSON()
+
+    assert.equal(json.kind, 'delete')
+    assert.equal(json.strategy, 'hard')
+    assert.equal(json.retentionPeriod, 0)
+  }).tags(['@modeling', '@action', '@delete-action', '@serialization'])
+
+  test('notifies change when strategy changes', async ({ assert }) => {
+    const action = new DeleteAction()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.strategy = 'hard'
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@delete-action', '@observed'])
+
+  test('notifies change when retentionPeriod changes', async ({ assert }) => {
+    const action = new DeleteAction()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.retentionPeriod = 60
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@delete-action', '@observed'])
+})

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

@@ -0,0 +1,106 @@
+import { test } from '@japa/runner'
+import { ListAction } from '../../../../src/modeling/actions/ListAction.js'
+import { PaginationStrategy } from '../../../../src/modeling/types.js'
+
+test.group('ListAction', () => {
+  test('initializes with default values', ({ assert }) => {
+    const action = new ListAction()
+    assert.equal(action.kind, 'list')
+    assert.deepEqual(action.pagination, { kind: 'offset' })
+    assert.deepEqual(action.filterableFields, [])
+    assert.deepEqual(action.sortableFields, [])
+    assert.isEmpty(action.accessRule) // Inherited from Action
+  }).tags(['@modeling', '@action', '@list-action'])
+
+  test('initializes with provided values', ({ assert }) => {
+    const pagination: PaginationStrategy = { kind: 'cursor' }
+    const filterableFields = ['name', 'status']
+    const sortableFields = ['createdAt']
+
+    const action = new ListAction({
+      pagination,
+      filterableFields,
+      sortableFields,
+    })
+
+    assert.deepEqual(action.pagination, pagination)
+    assert.deepEqual(action.filterableFields, filterableFields)
+    assert.deepEqual(action.sortableFields, sortableFields)
+  }).tags(['@modeling', '@action', '@list-action'])
+
+  test('constructor copies arrays and objects (immutability)', ({ assert }) => {
+    const pagination: PaginationStrategy = { kind: 'offset' }
+    const filterableFields = ['name']
+    const sortableFields = ['name']
+
+    const action = new ListAction({
+      pagination,
+      filterableFields,
+      sortableFields,
+    })
+
+    // Modify original sources
+    pagination.kind = 'cursor'
+    filterableFields.push('age')
+    sortableFields.push('age')
+
+    assert.deepEqual(action.pagination, { kind: 'offset' })
+    assert.deepEqual(action.filterableFields, ['name'])
+    assert.deepEqual(action.sortableFields, ['name'])
+  }).tags(['@modeling', '@action', '@list-action', '@immutability'])
+
+  test('toJSON returns safe copy', ({ assert }) => {
+    const action = new ListAction({
+      pagination: { kind: 'offset' },
+      filterableFields: ['name'],
+      sortableFields: ['name'],
+    })
+
+    const json = action.toJSON()
+
+    // Modify JSON
+    json.pagination.kind = 'cursor'
+    json.filterableFields.push('new')
+    json.sortableFields.push('new')
+
+    assert.deepEqual(action.pagination, { kind: 'offset' })
+    assert.deepEqual(action.filterableFields, ['name'])
+    assert.deepEqual(action.sortableFields, ['name'])
+  }).tags(['@modeling', '@action', '@list-action', '@immutability'])
+
+  test('notifies change when pagination changes', async ({ assert }) => {
+    const action = new ListAction()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.pagination = { kind: 'cursor' }
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@list-action', '@observed'])
+
+  test('notifies change when filterableFields changes', async ({ assert }) => {
+    const action = new ListAction()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.filterableFields = ['name']
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@list-action', '@observed'])
+
+  test('notifies change when sortableFields changes', async ({ assert }) => {
+    const action = new ListAction()
+    let notified = false
+    action.addEventListener('change', () => {
+      notified = true
+    })
+
+    action.sortableFields = ['name']
+    await Promise.resolve()
+    assert.isTrue(notified)
+  }).tags(['@modeling', '@action', '@list-action', '@observed'])
+})