@api-client/core 0.19.19 → 0.19.20

package/src/modeling/types.ts

@@ -223,41 +223,35 @@ export interface ProblemDetails {
 }
 
 /**
- * The set of supported filter operators for the List action.
+ * The set of supported filter operators for the List and search action.
  * These are used in query parameters, e.g., ?price[gte]=100
  *
  * - eq: Equal
- * - nq: Not Equal
+ * - neq: Not Equal
+ * - in: Value is one of the elements in the provided array
+ * - nin: Value is not one of the elements in the provided array
  * - lt: Less Than
  * - lte: Less Than or Equal
  * - gt: Greater Than
  * - gte: Greater Than or Equal
- * - ex: Checks if the field exists
- * - re: Regular expression match
- * - bf: Date before a specific value
- * - af: Date after a specific value
- * - cn: String contains substring / Array contains element
- * - st: String starts with
- * - end: String ends with
- * - in: Value is one of the elements in the provided array
- * - nin: Value is not one of the elements in the provided array
+ * - exists: Checks if the field exists
+ *
+ * Search filters only:
+ * - contains: String contains substring / Array contains element (Substring Match)
+ * - match: Lexical Match, multi-word queries against long text.
  */
 export type ResourceFilterOperator =
   | 'eq' // Equal
-  | 'nq' // Not equal
+  | 'neq' // Not equal
+  | 'in' // Value is one of the elements in the provided array
+  | 'nin' // Value is not one of the elements in the provided array
   | 'lt' // Less than
   | 'lte' // Less than or equal
   | 'gt' // Greater than
   | 'gte' // Greater than or equal
-  | 'ex' // Checks if the field exists
-  | 're' // Regular expression match
-  | 'bf' // Date before a specific value
-  | 'af' // Date after a specific value
-  | 'cn' // String contains substring / Array contains element
-  | 'st' // String starts with
-  | 'end' // String ends with
-  | 'in' // Value is one of the elements in the provided array
-  | 'nin' // Value is not one of the elements in the provided array
+  | 'exists' // Checks if the field exists
+  | 'contains' // String contains substring / Array contains element (Substring Match)
+  | 'match' // Lexical Match, multi-word queries against long text.
 
 /**
  * The session transport configuration interface.
@@ -384,6 +378,8 @@ export interface RolesBasedAccessControl extends AuthorizationConfiguration {
   roleKey: string
 }
 
+export type AuthorizationStrategy = RolesBasedAccessControl
+
 /**
  * Configures the strategy for authenticating end-users.
  * An API can only support one authentication strategy at a time.
@@ -412,6 +408,8 @@ export interface UsernamePasswordConfiguration extends AuthenticationConfigurati
   passwordKey?: string
 }
 
+export type AuthenticationStrategy = UsernamePasswordConfiguration
+
 /**
  * Represents a Data Entity from the Data Domain that the API will expose and operate upon.
  */
@@ -492,6 +490,10 @@ export interface ExposedEntitySchema {
    * When true, generation for this exposure hit configured limits
    */
   truncated?: boolean
+  /**
+   * Pagination contract for this exposure.
+   */
+  paginationContract?: PaginationContract
 }
 
 /**
@@ -542,7 +544,13 @@ export interface PaginationStrategy {
    * The default page size for the pagination strategy.
    * This is the number of items returned per page when no specific page size is requested.
    */
-  pageSize?: number
+  defaultLimit?: number
+  /**
+   * The maximum page size for the pagination strategy.
+   * This is the maximum number of items that can be returned per page.
+   * The API runtime defined the upper limit to prevent abuse.
+   */
+  maxLimit?: number
 }
 
 /**
@@ -559,6 +567,31 @@ export interface OffsetPaginationStrategy extends PaginationStrategy {
   kind: 'offset'
 }
 
+/**
+ * Represents the contract for pagination. Defines which fields can be used for filtering, sorting,
+ * and searching.
+ */
+export interface PaginationContract {
+  /**
+   * The list of fields (property keys) that can be used for filtering.
+   */
+  filterableFields: string[]
+  /**
+   * The list of fields (property keys) that can be used for sorting.
+   */
+  sortableFields: string[]
+  /**
+   * The list of fields (property keys) that can be used for searching.
+   * Note that these properties must be of type string or array of strings.
+   */
+  searchableFields: string[]
+  /**
+   * The default sort order for the pagination strategy.
+   * This is the sort order that will be used when no sort order is specified.
+   */
+  defaultSort?: { field: string; direction: 'asc' | 'desc' }[]
+}
+
 export type DomainImpactKinds =
   | typeof DomainNamespaceKind
   | typeof DomainEntityKind

package/src/modeling/validation/api_model_rules.ts

@@ -348,49 +348,62 @@ export function validateApiModelMetadata(model: ApiModel): ApiModelValidationIte
   return issues
 }
 
-export function validateAction(action: Action, parent: ExposedEntity, apiModelKey: string): ApiModelValidationItem[] {
+export function validateApiPagination(model: ApiModel): ApiModelValidationItem[] {
   const issues: ApiModelValidationItem[] = []
   const context: ApiModelValidationContext = {
-    apiModelKey,
-    kind: 'Action',
-    key: action.kind, // Actions lack nanoids, kind represents its type
-    parentExposedEntityKey: parent.key,
+    apiModelKey: model.key,
+    kind: ApiModelKind,
+    key: model.key,
   }
-
-  if (ListAction.isListAction(action)) {
-    if (!action.pagination || !action.pagination.kind) {
+  // We only need pagination when the API contains at least one List or Search action
+  let validate = false
+  for (const exposure of model.exposes.values()) {
+    if (exposure.actions.some((action) => ListAction.isListAction(action) || SearchAction.isSearchAction(action))) {
+      validate = true
+      break
+    }
+  }
+  if (!validate) {
+    return issues
+  }
+  if (!model.pagination || !model.pagination.kind) {
+    issues.push({
+      code: createCode('API', 'MISSING_PAGINATION'),
+      message: 'The API must have a defined pagination strategy when it exposes List or Search actions.',
+      suggestion: 'Configure how results are loaded (e.g. by page or by a continuous cursor).',
+      severity: 'error',
+      context: { ...context, property: 'pagination' },
+    })
+  } else {
+    if (model.pagination.defaultLimit === undefined) {
       issues.push({
-        code: createCode('ACTION', 'LIST_MISSING_PAGINATION'),
-        message: 'A List action must have a defined pagination strategy.',
-        suggestion: 'Configure how results are loaded (e.g. by page or by a continuous cursor).',
-        severity: 'error',
-        context: { ...context, property: 'pagination' },
+        code: createCode('API', 'MISSING_PAGINATION_DEFAULT_LIMIT'),
+        message: "The API doesn't have a defined default page limit when it exposes List or Search actions.",
+        suggestion: 'Set a default page limit for the pagination otherwise the API will use its default limit.',
+        severity: 'info',
+        context: { ...context, property: 'pagination.defaultLimit' },
       })
     }
-    if (
-      (!action.filterableFields || action.filterableFields.length === 0) &&
-      (!action.sortableFields || action.sortableFields.length === 0)
-    ) {
+    if (model.pagination.maxLimit === undefined) {
       issues.push({
-        code: createCode('ACTION', 'LIST_MISSING_FILTERS'),
-        message: 'Listing all elements without filters or sorting could be overwhelming for large tables.',
-        suggestion: 'Select a few important fields to allow sorting and searching by.',
-        severity: 'warning',
-        context,
+        code: createCode('API', 'MISSING_PAGINATION_MAX_LIMIT'),
+        message: "The API doesn't have a defined page size max limit when it exposes List or Search actions.",
+        suggestion: 'Set a max page size limit for the pagination otherwise the API will use its default max limit.',
+        severity: 'info',
+        context: { ...context, property: 'pagination.maxLimit' },
       })
     }
   }
+  return issues
+}
 
-  if (SearchAction.isSearchAction(action)) {
-    if (!action.fields || action.fields.length === 0) {
-      issues.push({
-        code: createCode('ACTION', 'SEARCH_MISSING_FIELDS'),
-        message: 'A Search action needs to know which fields to look in.',
-        suggestion: 'Select the properties (like names or emails) that the search will run on.',
-        severity: 'error',
-        context: { ...context, property: 'fields' },
-      })
-    }
+export function validateAction(action: Action, parent: ExposedEntity, apiModelKey: string): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey,
+    kind: 'Action',
+    key: action.kind, // Actions lack nanoids, kind represents its type
+    parentExposedEntityKey: parent.key,
   }
 
   if (DeleteAction.isDeleteAction(action)) {
@@ -573,9 +586,14 @@ export function validateExposedEntity(entity: ExposedEntity, apiModel: ApiModel)
       context: { ...context, property: 'actions' },
     })
   } else {
+    let hasSearch = false
+    let hasList = false
     for (const action of entity.actions) {
       issues.push(...validateAction(action, entity, apiModel.key))
 
+      if (SearchAction.isSearchAction(action)) hasSearch = true
+      if (ListAction.isListAction(action)) hasList = true
+
       // Check inheritance of access rules
       // For a rule to exist, it might be on the action, the exposure, any parent, or the apiModel.
       let hasAuth = false
@@ -605,6 +623,59 @@ export function validateExposedEntity(entity: ExposedEntity, apiModel: ApiModel)
         })
       }
     }
+
+    if (hasList || hasSearch) {
+      const contract = entity.paginationContract
+      if (!contract) {
+        issues.push({
+          code: createCode('EXPOSURE', 'MISSING_PAGINATION_CONTRACT'),
+          message: 'The List or Search action needs a pagination contract.',
+          suggestion: 'Add a pagination contract to the exposed entity.',
+          severity: 'error',
+          context,
+        })
+      } else {
+        if (hasList) {
+          if (!contract.filterableFields || contract.filterableFields.length === 0) {
+            issues.push({
+              code: createCode('EXPOSURE', 'LIST_MISSING_FILTERS'),
+              message: 'Listing all elements without filters could be overwhelming for large tables.',
+              suggestion: 'Select a few important fields to allow filtering.',
+              severity: 'warning',
+              context,
+            })
+          }
+          if (!contract.sortableFields || contract.sortableFields.length === 0) {
+            issues.push({
+              code: createCode('EXPOSURE', 'LIST_MISSING_SORTING'),
+              message: 'Listing all elements without sorting could be overwhelming for large tables.',
+              suggestion: 'Select a few important fields to allow sorting.',
+              severity: 'warning',
+              context,
+            })
+          }
+        }
+        if (hasSearch) {
+          // Search and technically be used for filtering.
+          const all: string[] = []
+          if (Array.isArray(contract.searchableFields)) {
+            all.push(...contract.searchableFields)
+          }
+          if (Array.isArray(contract.filterableFields)) {
+            all.push(...contract.filterableFields)
+          }
+          if (!all.length) {
+            issues.push({
+              code: createCode('EXPOSURE', 'SEARCH_MISSING_FIELDS'),
+              message: 'Search action needs to know which fields to look in.',
+              suggestion: 'Select a few important fields to allow searching or full-text search.',
+              severity: 'warning',
+              context,
+            })
+          }
+        }
+      }
+    }
   }
 
   return issues

package/src/models/ProjectRequest.ts

@@ -315,10 +315,6 @@ export class ProjectRequest extends Request implements ProjectDefinitionProperty
     if (!environment) {
       return undefined
     }
-    let parent = this.getParent()
-    if (parent === project) {
-      parent = undefined
-    }
     return project.findEnvironment(environment)
   }
 

package/src/models/transformers/ArcDexieTransformer.ts

@@ -235,10 +235,6 @@ export class ArcDexieTransformer extends BaseTransformer {
 
   parseSavedItem(item: DexieRequest): RequestProcessItem {
     const requestName = item.name || item._name
-    let keyName = requestName
-    if (keyName && keyName[0] === '_') {
-      keyName = keyName.substr(1)
-    }
     const obj: ExportArcSavedRequest = {
       name: requestName || '',
       method: item.method,

package/src/models/transformers/ImportUtils.ts

@@ -118,7 +118,7 @@ export function prepareImportObject(data: Record<string, unknown> | string): unk
       data = JSON.parse(data)
     } catch (e) {
       const err = e as Error
-      throw new Error(`Unable to read the file. Not a JSON: ${err.message}`)
+      throw new Error(`Unable to read the file. Not a JSON: ${err.message}`, { cause: e })
     }
   }
   return data

package/src/models/transformers/PostmanBackupTransformer.ts

@@ -213,11 +213,6 @@ export class PostmanBackupTransformer extends PostmanTransformer {
     let headers = request.headers || ''
     headers = this.ensureVariablesSyntax(headers) as string
 
-    let createdTime = Number(request.time)
-    if (Number.isNaN(createdTime)) {
-      createdTime = Date.now()
-    }
-
     const created = current.addRequest(url)
     created.info.name = name
     if (request.description) {

package/src/runtime/constants.ts

@@ -0,0 +1,9 @@
+// This is shared in the web and node.
+
+export const OFFSET_PAGINATION_DEFAULT_LIMIT = 20
+export const OFFSET_PAGINATION_MAX_LIMIT = 100
+export const OFFSET_PAGINATION_MIN_LIMIT = 1
+
+export const CURSOR_PAGINATION_DEFAULT_LIMIT = 20
+export const CURSOR_PAGINATION_MAX_LIMIT = 100
+export const CURSOR_PAGINATION_MIN_LIMIT = 1

package/src/runtime/http-engine/ntlm/Des.ts

@@ -128,6 +128,7 @@ export class Des {
       cbcleft =
         (iv!.charCodeAt(m++) << 24) | (iv!.charCodeAt(m++) << 16) | (iv!.charCodeAt(m++) << 8) | iv!.charCodeAt(m++)
       cbcright =
+        // eslint-disable-next-line no-useless-assignment
         (iv!.charCodeAt(m++) << 24) | (iv!.charCodeAt(m++) << 16) | (iv!.charCodeAt(m++) << 8) | iv!.charCodeAt(m++)
       m = 0
     }

package/src/runtime/variables/EvalFunctions.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-extraneous-class */
 import { find, store } from './Cache.js'
 
 // eslint-disable-next-line no-restricted-globals

package/tests/test-utils.ts

@@ -111,11 +111,15 @@ export const TestUtils = {
       if (expectedMessage) {
         if (typeof expectedMessage === 'string') {
           if (!typedError.message.includes(expectedMessage)) {
-            throw new Error(`Expected error message to include "${expectedMessage}", got "${typedError.message}"`)
+            throw new Error(`Expected error message to include "${expectedMessage}", got "${typedError.message}"`, {
+              cause: error,
+            })
           }
         } else if (expectedMessage instanceof RegExp) {
           if (!expectedMessage.test(typedError.message)) {
-            throw new Error(`Expected error message to match ${expectedMessage}, got "${typedError.message}"`)
+            throw new Error(`Expected error message to match ${expectedMessage}, got "${typedError.message}"`, {
+              cause: error,
+            })
           }
         }
       }

package/tests/unit/decorators/observed.spec.ts

@@ -13,7 +13,6 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed() accessor testProperty: any
     }
 
@@ -41,7 +40,6 @@ test.group('observed decorator', () => {
         instanceNotifyCallCount++
       }
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed() accessor testProperty: any
     }
 
@@ -92,7 +90,6 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor nestedData: any
     }
 
@@ -119,7 +116,6 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor primitiveValue: any
     }
 
@@ -146,7 +142,6 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed() accessor nullableValue: any
     }
 
@@ -168,7 +163,7 @@ test.group('observed decorator', () => {
   test('should throw error for unsupported decorator locations', ({ assert }) => {
     assert.throws(() => {
       const decorator = observed()
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       decorator({} as any, { kind: 'field' } as any)
     }, 'Unsupported decorator location: field')
   }).tags(['@decorators', '@observed', '@core', '@unit', '@fast'])
@@ -184,7 +179,6 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor complexData: any
     }
 
@@ -205,7 +199,7 @@ test.group('observed decorator', () => {
   test('should handle class without domain or notifyChange', ({ assert }) => {
     class TestClass {
       // @ts-expect-error It is for testing purposes
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       @observed() accessor testProperty: any
     }
 
@@ -229,9 +223,8 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed() accessor prop1: any
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       @observed() accessor prop2: any
     }
 
@@ -258,12 +251,11 @@ test.group('observed decorator', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor data: any
     }
 
     const instance = new TestClass()
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
     const obj: any = { name: 'test' }
     obj.self = obj // Create circular reference
 
@@ -316,7 +308,6 @@ test.group('retargetChange decorator', () => {
       domain = mockDomain
 
       @retargetChange()
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       accessor target: any
     }
 
@@ -344,7 +335,6 @@ test.group('retargetChange decorator', () => {
       domain = mockDomain
 
       @retargetChange()
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       accessor target: any
     }
 
@@ -369,17 +359,14 @@ test.group('retargetChange decorator', () => {
     }
 
     class TestClass {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       #target: any
       domain = mockDomain
 
       @retargetChange()
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       set target(value: any) {
         this.#target = value
       }
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       get target(): any {
         return this.#target
       }
@@ -400,7 +387,7 @@ test.group('retargetChange decorator', () => {
   test('should throw error for unsupported decorator locations', ({ assert }) => {
     assert.throws(() => {
       const decorator = retargetChange()
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       decorator({} as any, { kind: 'field' } as any)
     }, 'Unsupported decorator location: field')
   }).tags(['@decorators', '@retargetChange', '@core', '@unit', '@fast'])
@@ -417,7 +404,6 @@ test.group('toRaw function', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor data: any
     }
 
@@ -494,7 +480,7 @@ test.group('edge cases and error conditions', () => {
   test('should handle class without domain or notifyChange', ({ assert }) => {
     class TestClass {
       // @ts-expect-error It is for testing purposes
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       @observed() accessor testProperty: any
     }
 
@@ -518,9 +504,8 @@ test.group('edge cases and error conditions', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed() accessor prop1: any
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       @observed() accessor prop2: any
     }
 
@@ -547,12 +532,11 @@ test.group('edge cases and error conditions', () => {
     class TestClass {
       domain = mockDomain
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor data: any
     }
 
     const instance = new TestClass()
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
     const obj: any = { name: 'test' }
     obj.self = obj // Create circular reference
 

package/tests/unit/decorators/observed_recursive.spec.ts

@@ -10,7 +10,6 @@ test.group('toRaw recursive proxies', () => {
     }
     class TestClass {
       domain = mockDomain
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       @observed({ deep: true }) accessor data: any
     }
 

package/tests/unit/events/EventsTestHelpers.ts

@@ -1,7 +1,6 @@
 // The event names should be unique across all events in all modules.
 const names: string[] = []
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function ensureUnique(namespace: string, src: any): void {
   for (const [key, value] of Object.entries(src)) {
     const typedValue = value as string

package/tests/unit/events/events_polyfills.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 // Originally these tests were written for a browser environment.
 // They are now adapted to run in a Node.js environment with polyfills for browser APIs.
 

package/tests/unit/legacy-transformers/DataTestHelper.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
 import type { Assert } from '@japa/assert'
 
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class

package/tests/unit/legacy-transformers/LegacyExportProcessor.spec.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { test } from '@japa/runner'
 import {
   ExportArcHistoryRequest,