@api-client/core 0.19.21 → 0.19.22

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.19.21",
+  "version": "0.19.22",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/modeling/ExposedEntity.ts

@@ -474,4 +474,41 @@ export class ExposedEntity extends EventTarget {
     this.actions.push(action)
     return action
   }
+
+  /**
+   * Scans for the indexed and search properties in the `DomainEntity`
+   * and recreates the `paginationContract` with all indexed/searched fields.
+   *
+   * Note, this is a destructive action designed as a helper function when creating
+   * an exposed entity to fill up default values. Should not be used if the user
+   * didn't request that.
+   */
+  createPaginationContract(): void {
+    const entity = this.api.domain?.findEntity(this.entity.key, this.entity.domain)
+    if (!entity) {
+      throw new Error(`Entity "${this.entity.key}" not found"`)
+    }
+    if (!this.paginationContract) {
+      this.paginationContract = {
+        filterableFields: [],
+        searchableFields: [],
+        sortableFields: [],
+      }
+    } else {
+      this.paginationContract.filterableFields = []
+      this.paginationContract.searchableFields = []
+      this.paginationContract.sortableFields = []
+    }
+    for (const prop of entity.properties) {
+      // indexed properties allow sorting and filtering in the List action.
+      if (prop.index) {
+        this.paginationContract.filterableFields.push(prop.key)
+        this.paginationContract.sortableFields.push(prop.key)
+      }
+      // search properties allow full-text search in the Search action.
+      if (prop.search) {
+        this.paginationContract.searchableFields.push(prop.key)
+      }
+    }
+  }
 }

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

@@ -1,5 +1,5 @@
 import { test } from '@japa/runner'
-import { ApiModel, ExposedEntity, type ExposedEntitySchema } from '../../../src/index.js'
+import { ApiModel, DataDomain, ExposedEntity, type ExposedEntitySchema } from '../../../src/index.js'
 import { AccessRule, RateLimitingConfiguration } from '../../../src/modeling/index.js'
 import { ExposedEntityKind } from '../../../src/models/kinds.js'
 
@@ -417,3 +417,146 @@ test.group('ExposedEntity', () => {
     assert.equal(childRules[3].rate, 20)
   }).tags(['@modeling', '@exposed-entity', '@rate-limiting'])
 })
+
+// ---------------------------------------------------------------------------
+// Helper: build a DataDomain + ApiModel with a single entity already attached.
+// Returns the domain, api model, and the entity key so tests can add properties
+// and then call createPaginationContract() without repeating boilerplate.
+// ---------------------------------------------------------------------------
+function makeFixture() {
+  const domain = new DataDomain()
+  domain.info.version = '1.0.0'
+  const dm = domain.addModel()
+  const entity = domain.addEntity(dm.key)
+  const model = new ApiModel()
+  model.attachDataDomain(domain)
+  return { domain, model, entity }
+}
+
+test.group('ExposedEntity.createPaginationContract()', () => {
+  test('throws when no domain is attached to the API model', ({ assert }) => {
+    const model = new ApiModel() // no domain attached
+    const ex = new ExposedEntity(model, { entity: { key: 'some-entity' } })
+
+    assert.throws(() => ex.createPaginationContract(), 'Entity "some-entity" not found')
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('throws when the entity key does not exist in the domain', ({ assert }) => {
+    const { model } = makeFixture()
+    const ex = new ExposedEntity(model, { entity: { key: 'non-existent' } })
+
+    assert.throws(() => ex.createPaginationContract(), 'Entity "non-existent" not found')
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('creates a fresh paginationContract when one is not yet set', ({ assert }) => {
+    const { model, entity } = makeFixture()
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+
+    assert.isUndefined(ex.paginationContract)
+    ex.createPaginationContract()
+
+    assert.isDefined(ex.paginationContract)
+    assert.deepEqual(ex.paginationContract!.filterableFields, [])
+    assert.deepEqual(ex.paginationContract!.sortableFields, [])
+    assert.deepEqual(ex.paginationContract!.searchableFields, [])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('indexed props are added to filterableFields and sortableFields', ({ assert }) => {
+    const { domain, model, entity } = makeFixture()
+    domain.addProperty(entity.key, { key: 'status', index: true })
+    domain.addProperty(entity.key, { key: 'createdAt', index: true })
+
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+    ex.createPaginationContract()
+
+    assert.deepEqual(ex.paginationContract!.filterableFields, ['status', 'createdAt'])
+    assert.deepEqual(ex.paginationContract!.sortableFields, ['status', 'createdAt'])
+    assert.deepEqual(ex.paginationContract!.searchableFields, [])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('search props are added to searchableFields only', ({ assert }) => {
+    const { domain, model, entity } = makeFixture()
+    domain.addProperty(entity.key, { key: 'name', search: true })
+    domain.addProperty(entity.key, { key: 'description', search: true })
+
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+    ex.createPaginationContract()
+
+    assert.deepEqual(ex.paginationContract!.searchableFields, ['name', 'description'])
+    assert.deepEqual(ex.paginationContract!.filterableFields, [])
+    assert.deepEqual(ex.paginationContract!.sortableFields, [])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('a prop with both index and search appears in all three lists', ({ assert }) => {
+    const { domain, model, entity } = makeFixture()
+    domain.addProperty(entity.key, { key: 'email', index: true, search: true })
+
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+    ex.createPaginationContract()
+
+    assert.include(ex.paginationContract!.filterableFields, 'email')
+    assert.include(ex.paginationContract!.sortableFields, 'email')
+    assert.include(ex.paginationContract!.searchableFields, 'email')
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('props without index or search are not added to any list', ({ assert }) => {
+    const { domain, model, entity } = makeFixture()
+    domain.addProperty(entity.key, { key: 'bio' }) // no index, no search
+
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+    ex.createPaginationContract()
+
+    assert.deepEqual(ex.paginationContract!.filterableFields, [])
+    assert.deepEqual(ex.paginationContract!.sortableFields, [])
+    assert.deepEqual(ex.paginationContract!.searchableFields, [])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('resets existing contract arrays before repopulating (destructive)', ({ assert }) => {
+    const { domain, model, entity } = makeFixture()
+    domain.addProperty(entity.key, { key: 'title', index: true, search: true })
+
+    const ex = new ExposedEntity(model, {
+      entity: { key: entity.key },
+      paginationContract: {
+        filterableFields: ['stale-filter'],
+        sortableFields: ['stale-sort'],
+        searchableFields: ['stale-search'],
+      },
+    })
+
+    // Sanity check: pre-existing stale values are present
+    assert.include(ex.paginationContract!.filterableFields, 'stale-filter')
+
+    ex.createPaginationContract()
+
+    // Stale values are gone; only the freshly scanned fields remain
+    assert.deepEqual(ex.paginationContract!.filterableFields, ['title'])
+    assert.deepEqual(ex.paginationContract!.sortableFields, ['title'])
+    assert.deepEqual(ex.paginationContract!.searchableFields, ['title'])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('entity with no properties produces empty contract lists', ({ assert }) => {
+    const { model, entity } = makeFixture() // entity has no props
+
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+    ex.createPaginationContract()
+
+    assert.deepEqual(ex.paginationContract!.filterableFields, [])
+    assert.deepEqual(ex.paginationContract!.sortableFields, [])
+    assert.deepEqual(ex.paginationContract!.searchableFields, [])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+
+  test('mixed props: only the flagged ones appear in the relevant lists', ({ assert }) => {
+    const { domain, model, entity } = makeFixture()
+    domain.addProperty(entity.key, { key: 'id', index: true }) // filterable + sortable
+    domain.addProperty(entity.key, { key: 'body', search: true }) // searchable
+    domain.addProperty(entity.key, { key: 'metadata' }) // neither
+
+    const ex = new ExposedEntity(model, { entity: { key: entity.key } })
+    ex.createPaginationContract()
+
+    assert.deepEqual(ex.paginationContract!.filterableFields, ['id'])
+    assert.deepEqual(ex.paginationContract!.sortableFields, ['id'])
+    assert.deepEqual(ex.paginationContract!.searchableFields, ['body'])
+  }).tags(['@modeling', '@exposed-entity', '@pagination'])
+})