Glacier - Predictive caching for the web.

predict() wraps an async function so Glacier can cache its results, learn its access patterns, and prefetch it ahead of demand. It's the primary way you tell Glacier about your data.

Signature

glacier.predict<T>(
  key: string,
  loader: (...args: any[]) => Promise<T>,
  options?: PredictOptions,
): (...args: any[]) => Promise<T>

It returns a wrapped function with the same call signature as your loader. Calling it reads from cache when warm and falls back to the loader when cold.

Parameters

key — a stable namespace for this query. Arguments are appended to form the full cache key, so getUser(1) and getUser(2) are cached separately under user.
loader — the async function that actually fetches the data. Glacier calls it on a miss.
options — optional per-query overrides.

Options

ttl — override the client default time-to-live for this query.
strategy — 'predictive' or 'lazy' for this query specifically.
tags — array of tags used for grouped invalidation.

Example

import { glacier } from '../glacier.config'

const getUser = glacier.predict(
  'user',
  (id) => api.fetchUser(id),
  { ttl: '10m', tags: ['user'] },
)

const user = await getUser(42)

After a few calls, Glacier begins prefetching the users it expects to be requested next based on observed patterns.

Keep keys stable

Use a small set of stable string keys rather than dynamic ones. The key is how Glacier groups access patterns — changing it on every call prevents it from learning anything useful.

Return value

The wrapped function resolves with your loader's return type. A warm read resolves without calling the loader; a cold read awaits the loader and warms the entry for next time.