Skip to content

Cache Behavior

Both Component and Thunder reads support server-side caching. You control how fresh the response needs to be by passing a cacheTTL value (seconds) in your request.

cacheTTL value Behaviour
> 0 Return a cached response if it is no older than cacheTTL seconds
0 (or omitted) Always fetch fresh from the database

Components

Pass cacheTTL in the options argument of find(), findOne(), or paginate():

import { Component } from '@ptkl/sdk/beta'

const products = new Component('products')

// Serve a cached result up to 60 seconds old.
const list = await products.find(
  { currentPage: 0, perPage: 20 },
  { cacheTTL: 60 }
)

// Force a fresh read — bypass the cache entirely.
const fresh = await products.find(
  { currentPage: 0, perPage: 20 },
  { cacheTTL: 0 }
)

// findOne respects cacheTTL the same way.
const item = await products.findOne(
  { $adv: { slug: 'my-product' } },
  { cacheTTL: 60 }
)

You can also limit which fields are returned with only:

const result = await products.find(
  { currentPage: 0, perPage: 20, only: ['name', 'price'] },
  { cacheTTL: 60 }
)

Note: only is supported on V4 component reads. V3 component reads do not support field projection.

Thunder

Thunder reads support cacheTTL and field projection with only (v0.10+):

import { Thunder } from '@ptkl/sdk/beta'

const thunder = new Thunder()

const flags = await thunder.find('feature_flags', {}, { cacheTTL: 60, only: ['key', 'enabled'] })

const one = await thunder.findOne('feature_flags', { key: 'dark_mode' }, { cacheTTL: 60 })

const settings = await thunder.paginate(
  'user_settings',
  { user_id: 2 },
  { cacheTTL: 120, only: ['theme', 'language'] }
)

Choosing a TTL

TTL range Good for
5–30 s Data that changes often but can tolerate brief staleness (live feeds, counters)
60–300 s Reference data that rarely changes during a session (catalogues, settings)
0 Any read that must reflect the latest write (immediately after a mutation)

Restrictions

cacheTTL is silently ignored when:

  • The request includes unmaskPasswords: true — responses with plaintext credentials are never cached.
  • The call is made from the Protokol Dashboard — operators always see live data.

Direct API Usage

If you are calling the API without the SDK, pass X-Cache-Ttl as an HTTP header:

POST /v4/system/component/products/models HTTP/1.1
X-Cache-Ttl: 60
Content-Type: application/json

POST /v3/system/thunder HTTP/1.1
X-Cache-Ttl: 120
Content-Type: application/json

If both the options.cacheTTL body field and the X-Cache-Ttl header are present, the body value wins.