Thunder

Thunder is a key-value store for unstructured data. It is optimised for fast reads and infrequent writes, which makes it a good fit for data that does not change often — configuration, feature flags, user preferences, or any data that does not belong in a typed component schema.

Each record belongs to a named collection (the first argument to every method). Collections are created implicitly on first write.

SDK Usage

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

const thunder = new Thunder()

Read Methods

`find(name, filters, options?)`

Returns all records in the collection that match the filters.

const flags = await thunder.find('feature_flags', { enabled: true })

With field projection and cache:

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

`findOne(name, filters, options?)`

Returns the first record that matches the filters, or null.

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

`paginate(name, filters, options?)`

Returns a paginated result set. Pass page and perPage inside filters.

const page = await thunder.paginate(
  'audit_log',
  { user_id: 42, page: 0, perPage: 20 },
  { cacheTTL: 30 }
)

Read Options

All read methods accept an optional options object as the last argument.

Option	Type	Description
`cacheTTL`	`number`	Max age (seconds) of a cached response to accept. `0` or omitted forces a fresh read.
`only`	`string[]`	Limit which fields are returned.

Write Methods

`insertOne(name, data)`

Inserts a new record.

await thunder.insertOne('feature_flags', { key: 'dark_mode', enabled: false })

`updateOne(name, filters, data)`

Updates the first record that matches the filters.

await thunder.updateOne('feature_flags', { key: 'dark_mode' }, { enabled: true })

`upsert(name, filters, data)`

Updates a matching record or creates one if none exists.

await thunder.upsert('user_settings', { user_id: 42 }, { theme: 'dark', language: 'en' })

`operation(name, filters, data)`

Runs a custom server-side operation on matching records.

await thunder.operation('counters', { key: 'page_views' }, { $inc: { count: 1 } })

`delete(name, filters)`

Deletes all records matching the filters.

await thunder.delete('feature_flags', { key: 'old_flag' })