Interface IKosServiceRequestParams<Paths, Path, Method, Response, TransformedResponse>

API path to request

Example

path: '/api/kos/ingredients'
path: `/api/devices/${PROP_DEVICE_ID}/status` // with PropKey
Copy

HTTP method

Default

'get'
Copy

When to execute this request during model lifecycle

If omitted, the request executes when the decorated method is called (method-driven). If specified, the request executes automatically during the given lifecycle phase (lifecycle-driven).

Example

// Lifecycle-driven (auto-execute during LOAD phase)
lifecycle: DependencyLifecycle.LOAD
Copy

Example

// Method-driven (execute when method is called)
lifecycle: undefined  // or omit entirely
Copy

Path parameters to expand in the URL Strongly typed from OpenAPI schema Can be static values or PropKey references

Example

// Static value
pathParams: { deviceId: 'device-123' }
Copy

Example

// PropKey reference (use PROP_ prefix)
pathParams: { deviceId: PROP_DEVICE_ID }
Copy

Example

// Dynamic from method arguments
pathParams: (model, deviceId, status) => ({ deviceId })
Copy

Query parameters Strongly typed from OpenAPI schema

Example

// Static
queryParams: { includeMetadata: true, format: 'json' }
Copy

Example

// Dynamic from method arguments
queryParams: (model, deviceId, debug) => ({ debug })
Copy

Request body (for POST/PUT/PATCH) Strongly typed from OpenAPI schema

Example

// Static body
body: { action: 'start' }
Copy

Example

// Dynamic from method arguments
body: (model, vehicleType, speed) => ({ vehicleType, speed })
Copy

JSON path to iterate over in response Creates models for each item in the array

Example

iterateOver: 'data.ingredients' // Iterates response.data.ingredients array
Copy

Model registration object for creating instances from array items Used with iterateOver to create child models using the builder pattern

Example

modelFactory: IngredientModel  // The registration object itself

deprecated The old curried function signature is deprecated:
modelFactory?: (id: string) => (options: any) => IKosDataModel
Copy

Function to extract the model ID from response data items Required when using modelFactory if items don't have an 'id' field

Example

idExtractor: (item) => item.ingredientId
idExtractor: (item) => `${item.type}-${item.index}`
Copy

Field mappings for data transformation Same format as

Kos Topic Handler

mappings

Example

mappings: [
  { from: 'id', to: 'id' },
  { from: 'ingredientId', to: 'ingredientId' },
  { from: 'metadata.calories', to: 'calories', transform: 'number' }
]
Copy

Extension points to execute during transformation

Example

extensions: [
  { type: 'data-mapper', extension: ExtensionType.IngredientMapper }
]
Copy

Transformation function for response data Applied before mappings

Example

transform: (response) => response.data
Copy

Condition to determine if request should execute

Example

condition: (model) => model.isInitialized
Copy

Error handling strategy

Example

errorHandler: {
  strategy: 'default',
  defaultValue: [],
  onError: (error, model) => model.logger.error('Failed to load', error)
}
Copy

Response caching configuration Controls how long responses are stored and when they're cleaned up

Default

{ retention: ResponseRetention.SINGLE }
Copy

Example

// No caching - clear immediately after handler
cache: { retention: ResponseRetention.IMMEDIATE }
Copy

Example

// Cache for 5 minutes
cache: { retention: ResponseRetention.TTL, ttl: 5 * 60 * 1000 }
Copy

Example

// Keep for model lifetime
cache: { retention: ResponseRetention.PERMANENT }
Copy

Request options for controlling fetch behavior These are merged with runtime options passed to ctx.$request() Runtime options take precedence over decorator options

Example

// Set default timeout and destination for all requests
requestOptions: {
  destinationAddress: 'device-123',
  timeout: 10000
}
Copy

Example

// Dynamic from method arguments
requestOptions: (model, ...args) => ({
  destinationAddress: model.deviceId,
  headers: { 'X-Session': model.sessionId }
})
Copy