@api-client/core 0.18.32 → 0.18.34

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.32",
+  "version": "0.18.34",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/ApiModel.ts

@@ -170,7 +170,7 @@ export class ApiModel extends DependentModel {
    * The specific subset of Data Entities to be exposed by this API.
    * These are the entities that are included in the data domain schema.
    */
-  exposes: ExposedEntity[]
+  @observed({ deep: true }) accessor exposes: ExposedEntity[]
   /**
    * Optional array of access rules that define the access control policies
    * for the API. These rules are used to enforce security and permissions
@@ -411,8 +411,8 @@ export class ApiModel extends DependentModel {
       entity: { ...entity },
       actions: [],
       isRoot: true,
-      relativeCollectionPath,
-      relativeResourcePath,
+      collectionPath: relativeCollectionPath,
+      resourcePath: relativeResourcePath,
       hasCollection: true,
     }
     if (options) {
@@ -498,8 +498,8 @@ export class ApiModel extends DependentModel {
             entity: { ...target },
             actions: [],
             isRoot: false,
-            relativeCollectionPath,
-            relativeResourcePath,
+            collectionPath: relativeCollectionPath,
+            resourcePath: relativeResourcePath,
             hasCollection: isCollection,
             parent: {
               key: parentKey,

package/src/modeling/ExposedEntity.ts

@@ -1,3 +1,4 @@
+import { observed } from '../decorators/observed.js'
 import { ExposedEntityKind } from '../models/kinds.js'
 import { nanoid } from '../nanoid.js'
 import type { ApiModel } from './ApiModel.js'
@@ -32,61 +33,71 @@ export class ExposedEntity extends EventTarget {
   /**
    * A pointer to a Data Entity from the Data Domain.
    */
-  entity: AssociationTarget
+  @observed() accessor entity: AssociationTarget
 
   /**
    * Indicates whether this exposure has a collection endpoint.
    * A collection endpoint is optional for nested exposures where the association is 1:1
    * and the schema is embedded directly under the parent resource.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
    */
   hasCollection: boolean
 
   /**
-   * Relative path to the collection endpoint for this exposure.
+   * Path to the collection endpoint for this exposure.
    * Starts with '/'. Not set for 1:1 nested exposures where collection does not exist.
    */
-  relativeCollectionPath?: string
+  @observed() accessor collectionPath: string | undefined
 
   /**
-   * Relative path to the resource endpoint for this exposure.
+   * Path to the resource endpoint for this exposure.
    * Starts with '/'. For 1:1 nested exposures the resource path typically does not include an id segment.
    */
-  relativeResourcePath: string
+  @observed() accessor resourcePath: string
 
   /**
    * Whether this exposure is a root exposure (top-level collection).
    * If this is set then the `parent` reference must be populated.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
    */
   isRoot?: boolean
 
   /**
    * Parent reference when this exposure was created via following an association.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
    */
   parent?: ExposeParentRef
 
   /**
    * 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.
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
    */
   exposeOptions?: ExposeOptions
 
   /**
    * The list of enabled API actions for this exposure (List/Read/Create/etc.)
    */
-  actions: ApiAction[]
+  @observed({ deep: true }) accessor actions: ApiAction[]
 
   /**
    * Optional array of access rules that define the access control policies for this exposure.
    */
-  accessRule?: AccessRule[]
+  @observed({ deep: true }) accessor accessRule: AccessRule[] | undefined
 
   /**
    * Optional configuration for rate limiting for this exposure.
    */
-  rateLimiting?: RateLimitingConfiguration
+  @observed({ deep: true }) accessor rateLimiting: RateLimitingConfiguration | undefined
 
   /**
    * When true, generation for this exposure hit configured limits
+   *
+   * Note that this property is not observed for changes as it is immutable after creation.
    */
   truncated?: boolean
 
@@ -97,6 +108,11 @@ export class ExposedEntity extends EventTarget {
    * the current notification is sent.
    */
   #notifying = false
+  /**
+   * When the initializing flag is set to true,
+   * the domain is not notified of changes.
+   */
+  #initializing = true
   /**
    * A reference to the parent API Model instance.
    */
@@ -106,8 +122,8 @@ export class ExposedEntity extends EventTarget {
     const {
       key = nanoid(),
       entity = { key: '' },
-      relativeCollectionPath,
-      relativeResourcePath = '/',
+      collectionPath,
+      resourcePath = '/',
       hasCollection = true,
       isRoot,
       parent,
@@ -122,11 +138,11 @@ export class ExposedEntity extends EventTarget {
       key,
       entity: { ...entity },
       hasCollection,
-      relativeResourcePath,
+      resourcePath,
       actions: actions.map((a) => ({ ...a })),
     }
-    if (relativeCollectionPath !== undefined) {
-      result.relativeCollectionPath = relativeCollectionPath
+    if (collectionPath !== undefined) {
+      result.collectionPath = collectionPath
     }
     if (isRoot !== undefined) {
       result.isRoot = isRoot
@@ -157,8 +173,8 @@ export class ExposedEntity extends EventTarget {
     this.key = init.key
     this.entity = init.entity
     this.hasCollection = init.hasCollection
-    this.relativeCollectionPath = init.relativeCollectionPath
-    this.relativeResourcePath = init.relativeResourcePath
+    this.collectionPath = init.collectionPath
+    this.resourcePath = init.resourcePath
     this.isRoot = init.isRoot
     this.parent = init.parent
     this.exposeOptions = init.exposeOptions
@@ -166,10 +182,11 @@ export class ExposedEntity extends EventTarget {
     this.accessRule = init.accessRule
     this.rateLimiting = init.rateLimiting
     this.truncated = init.truncated
+    this.#initializing = false
   }
 
   notifyChange() {
-    if (this.#notifying) {
+    if (this.#notifying || this.#initializing) {
       return
     }
     this.#notifying = true
@@ -185,12 +202,12 @@ export class ExposedEntity extends EventTarget {
       kind: this.kind,
       key: this.key,
       entity: { ...this.entity },
-      relativeResourcePath: this.relativeResourcePath,
+      resourcePath: this.resourcePath,
       actions: this.actions.map((a) => ({ ...a })),
       hasCollection: this.hasCollection,
     }
-    if (this.relativeCollectionPath !== undefined) {
-      result.relativeCollectionPath = this.relativeCollectionPath
+    if (this.collectionPath !== undefined) {
+      result.collectionPath = this.collectionPath
     }
     if (this.isRoot !== undefined) {
       result.isRoot = this.isRoot
@@ -214,15 +231,15 @@ export class ExposedEntity extends EventTarget {
   }
 
   /**
-   * Sets a new relative collection path for this exposed entity.
+   * Sets a new collection path for this exposed entity.
    *
    * It:
-   * - updates the relativeCollectionPath property
+   * - updates the collectionPath property
    * - updates the absoluteCollectionPath property accordingly
-   * - updates the relativeResourcePath and absoluteResourcePath accordingly.
+   * - updates the resourcePath accordingly.
    * @param path The new path to set.
    */
-  setRelativeCollectionPath(path: string) {
+  setCollectionPath(path: string) {
     if (!this.hasCollection) {
       throw new Error(`Cannot set collection path on an exposure that does not have a collection`)
     }
@@ -235,22 +252,21 @@ export class ExposedEntity extends EventTarget {
     const normalizedCollection = `/${segments[0]}`
     // Preserve current parameter name if present, otherwise default to {id}
     let param = '{id}'
-    if (this.relativeResourcePath) {
-      const curSegments = this.relativeResourcePath.split('/').filter(Boolean)
+    if (this.resourcePath) {
+      const curSegments = this.resourcePath.split('/').filter(Boolean)
       const maybeParam = curSegments[1]
       if (maybeParam && /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(maybeParam)) {
         param = maybeParam
       }
     }
     const nextResource = `${normalizedCollection}/${param}`
-    const changed = this.relativeCollectionPath !== normalizedCollection || this.relativeResourcePath !== nextResource
-    this.relativeCollectionPath = normalizedCollection
-    this.relativeResourcePath = nextResource
-    if (changed) this.notifyChange()
+    this.collectionPath = normalizedCollection
+    this.resourcePath = nextResource
+    // rely on ApiModel.exposes deep observation to notify on property sets
   }
 
   /**
-   * Sets a new relative resource path for this exposed entity.
+   * Sets a new resource path for this exposed entity.
    *
    * Rules:
    * - Must start with '/'.
@@ -258,17 +274,17 @@ export class ExposedEntity extends EventTarget {
    *   parameter segment (e.g. `/products/{productId}`) and only the parameter name may vary.
    * - If this exposure does NOT have a collection, the path can be any two segments (e.g. `/profile/{id}` or `/a/b`).
    */
-  setRelativeResourcePath(path: string) {
+  setResourcePath(path: string) {
     const cleaned = ensureLeadingSlash(path)
     const segments = cleaned.split('/').filter(Boolean)
 
     if (this.hasCollection) {
-      if (!this.relativeCollectionPath) {
+      if (!this.collectionPath) {
         throw new Error('Cannot set resource path: missing collection path for this exposure')
       }
-      const colSegments = this.relativeCollectionPath.split('/').filter(Boolean)
+      const colSegments = this.collectionPath.split('/').filter(Boolean)
       if (colSegments.length !== 1) {
-        throw new Error(`Invalid stored collection path "${this.relativeCollectionPath}"`)
+        throw new Error(`Invalid stored collection path "${this.collectionPath}"`)
       }
       if (segments.length !== 2) {
         throw new Error(`Resource path must be exactly two segments (collection + parameter). Received: "${cleaned}"`)
@@ -281,9 +297,8 @@ export class ExposedEntity extends EventTarget {
       if (!/^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(s2)) {
         throw new Error(`The second segment must be a parameter in braces, e.g. {id}. Received: "${s2}"`)
       }
-      if (this.relativeResourcePath !== cleaned) {
-        this.relativeResourcePath = `/${s1}/${s2}`
-        this.notifyChange()
+      if (this.resourcePath !== cleaned) {
+        this.resourcePath = `/${s1}/${s2}`
       }
       return
     }
@@ -294,9 +309,8 @@ export class ExposedEntity extends EventTarget {
         `Resource path must contain exactly two segments when no collection is present. Received: "${cleaned}"`
       )
     }
-    if (this.relativeResourcePath !== cleaned) {
-      this.relativeResourcePath = `/${segments[0]}/${segments[1]}`
-      this.notifyChange()
+    if (this.resourcePath !== cleaned) {
+      this.resourcePath = `/${segments[0]}/${segments[1]}`
     }
   }
 
@@ -304,16 +318,16 @@ export class ExposedEntity extends EventTarget {
    * Computes the absolute path for this exposure's resource endpoint by
    * walking up the exposure tree using `parent.key` until reaching a root exposure.
    * The absolute path is composed by concatenating each ancestor's resource path
-   * with this exposure's relative resource path.
+   * with this exposure's resource path.
    */
   getAbsoluteResourcePath(): string {
-    let absolute = ensureLeadingSlash(this.relativeResourcePath)
+    let absolute = ensureLeadingSlash(this.resourcePath)
     // Traverse parents, always joining with the parent's resource path
     let parentKey = this.parent?.key
     while (parentKey) {
       const parent = this.api.exposes.find((e) => e.key === parentKey)
       if (!parent) break
-      const parentResource = ensureLeadingSlash(parent.relativeResourcePath)
+      const parentResource = ensureLeadingSlash(parent.resourcePath)
       absolute = joinPaths(parentResource, absolute)
       parentKey = parent.parent?.key
     }
@@ -324,18 +338,18 @@ export class ExposedEntity extends EventTarget {
    * Computes the absolute path for this exposure's collection endpoint (if any)
    * by walking up the exposure tree using `parent.key` until reaching a root exposure.
    * The absolute path is composed by concatenating each ancestor's resource path
-   * with this exposure's relative collection path.
+   * with this exposure's collection path.
    * Returns undefined if this exposure has no collection.
    */
   getAbsoluteCollectionPath(): string | undefined {
-    if (!this.hasCollection || !this.relativeCollectionPath) return undefined
-    let absolute = ensureLeadingSlash(this.relativeCollectionPath)
+    if (!this.hasCollection || !this.collectionPath) return undefined
+    let absolute = ensureLeadingSlash(this.collectionPath)
     // Traverse parents, always joining with the parent's resource path
     let parentKey = this.parent?.key
     while (parentKey) {
       const parent = this.api.exposes.find((e) => e.key === parentKey)
       if (!parent) break
-      const parentResource = ensureLeadingSlash(parent.relativeResourcePath)
+      const parentResource = ensureLeadingSlash(parent.resourcePath)
       absolute = joinPaths(parentResource, absolute)
       parentKey = parent.parent?.key
     }

package/src/modeling/types.ts

@@ -457,16 +457,16 @@ export interface ExposedEntitySchema {
    */
   hasCollection: boolean
   /**
-   * Relative path to the collection endpoint for this exposure.
+   * A path to the collection endpoint for this exposure.
    * Starts with '/'. Not set for 1:1 nested exposures where collection does not exist.
    */
-  relativeCollectionPath?: string
+  collectionPath?: string
 
   /**
-   * Relative path to the resource endpoint for this exposure.
+   * A path to the resource endpoint for this exposure.
    * Starts with '/'. For 1:1 nested exposures the resource path typically does not include an id segment.
    */
-  relativeResourcePath: string
+  resourcePath: string
 
   /**
    * Whether this exposure is a root exposure (top-level collection).
@@ -674,6 +674,13 @@ export interface DeleteAction extends Action {
    * @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
 }
 
 /**

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

@@ -42,7 +42,7 @@ test.group('ApiModel.createSchema()', () => {
           actions: [],
           hasCollection: true,
           kind: ExposedEntityKind,
-          relativeResourcePath: '/',
+          resourcePath: '/',
           entity: { key: 'entity1' },
         },
       ],
@@ -116,7 +116,7 @@ test.group('ApiModel.constructor()', () => {
         {
           key: 'entity1',
           actions: [],
-          relativeResourcePath: '/',
+          resourcePath: '/',
           entity: { key: 'entity1' },
           hasCollection: true,
           kind: ExposedEntityKind,
@@ -205,7 +205,7 @@ test.group('ApiModel.toJSON()', () => {
         {
           key: 'entity1',
           actions: [],
-          relativeResourcePath: '/',
+          resourcePath: '/',
           entity: { key: 'entity1' },
           hasCollection: true,
           kind: ExposedEntityKind,
@@ -251,7 +251,7 @@ test.group('ApiModel.getExposedEntity()', () => {
       actions: [],
       hasCollection: true,
       kind: ExposedEntityKind,
-      relativeResourcePath: '/',
+      resourcePath: '/',
       entity: { key: entityKey },
     }
     model.exposes.push(new ExposedEntity(model, exposed))

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

@@ -15,7 +15,6 @@ test.group('ApiModel.exposeEntity()', () => {
     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 }) => {
@@ -28,7 +27,7 @@ test.group('ApiModel.exposeEntity()', () => {
     const initialExposedEntity = model.exposeEntity({ key: e1.key })
     const retrievedExposedEntity = model.exposeEntity({ key: e1.key })
 
-    assert.strictEqual(retrievedExposedEntity, initialExposedEntity)
+    assert.deepEqual(retrievedExposedEntity.toJSON(), initialExposedEntity.toJSON())
     assert.lengthOf(model.exposes, 1)
   }).tags(['@modeling', '@api'])
 
@@ -81,7 +80,7 @@ test.group('ApiModel.exposeEntity()', () => {
     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?.relativeCollectionPath, '/entitybs')
+    assert.strictEqual(nestedB?.collectionPath, '/entitybs')
   })
 
   test('does not infinitely expose circular associations', ({ assert }) => {

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

@@ -45,10 +45,9 @@ test.group('ApiModel.removeEntity()', () => {
     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)
+    assert.lengthOf(model.exposes, 1, 'exposes count should remain unchanged')
   }).tags(['@modeling', '@api'])
 
   test('notifies change when an entity is removed', async ({ assert }) => {

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

@@ -1,80 +1,81 @@
 import { test } from '@japa/runner'
-import { ApiModel, ExposedEntity } from '../../../src/index.js'
+import { ApiModel, ExposedEntity, type ExposedEntitySchema } from '../../../src/index.js'
+import { ExposedEntityKind } from '../../../src/models/kinds.js'
 
 test.group('ExposedEntity', () => {
-  test('setRelativeCollectionPath normalizes and preserves resource param', ({ assert }) => {
+  test('setCollectionPath normalizes and preserves resource param', ({ assert }) => {
     const model = new ApiModel()
     const ex = new ExposedEntity(model, {
       hasCollection: true,
-      relativeCollectionPath: '/items',
-      relativeResourcePath: '/items/{customId}',
+      collectionPath: '/items',
+      resourcePath: '/items/{customId}',
     })
 
-    ex.setRelativeCollectionPath('products')
+    ex.setCollectionPath('products')
 
-    assert.equal(ex.relativeCollectionPath, '/products')
-    assert.equal(ex.relativeResourcePath, '/products/{customId}')
+    assert.equal(ex.collectionPath, '/products')
+    assert.equal(ex.resourcePath, '/products/{customId}')
   }).tags(['@modeling', '@exposed-entity'])
 
-  test('setRelativeResourcePath with collection allows only parameter name change', ({ assert }) => {
+  test('setResourcePath with collection allows only parameter name change', ({ assert }) => {
     const model = new ApiModel()
     const ex = new ExposedEntity(model, {
       hasCollection: true,
-      relativeCollectionPath: '/products',
-      relativeResourcePath: '/products/{id}',
+      collectionPath: '/products',
+      resourcePath: '/products/{id}',
     })
 
     // valid: same collection segment, different param name
-    ex.setRelativeResourcePath('/products/{productId}')
-    assert.equal(ex.relativeResourcePath, '/products/{productId}')
+    ex.setResourcePath('/products/{productId}')
+    assert.equal(ex.resourcePath, '/products/{productId}')
 
     // invalid: different first segment
-    assert.throws(() => ex.setRelativeResourcePath('/wrong/{id}'))
+    assert.throws(() => ex.setResourcePath('/wrong/{id}'))
 
     // invalid: second segment not a parameter
-    assert.throws(() => ex.setRelativeResourcePath('/products/notParam'))
+    assert.throws(() => ex.setResourcePath('/products/notParam'))
   }).tags(['@modeling', '@exposed-entity'])
 
-  test('setRelativeResourcePath without collection must have exactly two segments', ({ assert }) => {
+  test('setResourcePath without collection must have exactly two segments', ({ assert }) => {
     const model = new ApiModel()
     const ex = new ExposedEntity(model, {
       hasCollection: false,
-      relativeResourcePath: '/profile/{id}',
+      resourcePath: '/profile/{id}',
     })
 
-    ex.setRelativeResourcePath('settings/secret')
-    assert.equal(ex.relativeResourcePath, '/settings/secret')
+    ex.setResourcePath('settings/secret')
+    assert.equal(ex.resourcePath, '/settings/secret')
 
-    assert.throws(() => ex.setRelativeResourcePath('onlyone'))
+    assert.throws(() => ex.setResourcePath('onlyone'))
   }).tags(['@modeling', '@exposed-entity'])
 
   test('computes absolute resource and collection paths along parent chain', ({ assert }) => {
     const model = new ApiModel()
 
     // Build exposure schemas
-    const rootSchema = {
+    const rootSchema: Partial<ExposedEntitySchema> = {
       key: 'root',
       entity: { key: 'user' },
       hasCollection: true,
-      relativeCollectionPath: '/users',
-      relativeResourcePath: '/users/{userId}',
+      collectionPath: '/users',
+      resourcePath: '/users/{userId}',
       isRoot: true,
       actions: [],
     }
-    const childSchema = {
+    const childSchema: Partial<ExposedEntitySchema> = {
       key: 'child',
       entity: { key: 'post' },
       hasCollection: true,
-      relativeCollectionPath: '/posts',
-      relativeResourcePath: '/posts/{postId}',
+      collectionPath: '/posts',
+      resourcePath: '/posts/{postId}',
       parent: { key: 'root', association: { key: 'toPosts' } },
       actions: [],
     }
-    const grandSchema = {
+    const grandSchema: Partial<ExposedEntitySchema> = {
       key: 'grand',
       entity: { key: 'details' },
       hasCollection: false,
-      relativeResourcePath: '/details',
+      resourcePath: '/details',
       parent: { key: 'child', association: { key: 'toDetails' } },
       actions: [],
     }
@@ -97,4 +98,58 @@ test.group('ExposedEntity', () => {
     assert.isUndefined(grandEx.getAbsoluteCollectionPath())
     assert.equal(grandEx.getAbsoluteResourcePath(), '/users/{userId}/posts/{postId}/details')
   }).tags(['@modeling', '@exposed-entity'])
+
+  test('ApiModel notifies when nested ExposedEntity collection path changes', async ({ assert }) => {
+    const model = new ApiModel({
+      exposes: [
+        {
+          kind: ExposedEntityKind,
+          key: 'e1',
+          entity: { key: 'e1' },
+          hasCollection: true,
+          collectionPath: '/things',
+          resourcePath: '/things/{id}',
+          isRoot: true,
+          actions: [],
+        },
+      ],
+    })
+
+    let notified = 0
+    model.addEventListener('change', () => {
+      notified += 1
+    })
+
+    const ex = model.exposes[0]
+    ex.setCollectionPath('items')
+    await Promise.resolve() // allow ApiModel.notifyChange microtask to run
+    assert.isAtLeast(notified, 1)
+  }).tags(['@modeling', '@exposed-entity', '@observed'])
+
+  test('ApiModel notifies when nested ExposedEntity resource path changes', async ({ assert }) => {
+    const model = new ApiModel({
+      exposes: [
+        {
+          kind: ExposedEntityKind,
+          key: 'e1',
+          entity: { key: 'e1' },
+          hasCollection: true,
+          collectionPath: '/products',
+          resourcePath: '/products/{id}',
+          isRoot: true,
+          actions: [],
+        },
+      ],
+    })
+
+    let notified = 0
+    model.addEventListener('change', () => {
+      notified += 1
+    })
+
+    const ex = model.exposes[0]
+    ex.setResourcePath('/products/{productId}')
+    await Promise.resolve()
+    assert.isAtLeast(notified, 1)
+  }).tags(['@modeling', '@exposed-entity', '@observed'])
 })