@ogygia/postrender

This page is generated from the package’s own .d.ts files on every build, so the signatures, descriptions and examples below always match the source.

import { … } from '@ogygia/postrender';

Exports akamai · cloudflare · cloudflareKv · cloudfront · cloudfront · memory_store · upstash · valkey · postrender · AkamaiConfig · CloudflareConfig · CloudfrontConfig · EdgeAdapter · KvNamespaceLike · PostrenderHandleOptions · PostrenderMeta · PostrenderPutOptions · PostrenderStore · UpstashConfig · ValkeyLike · PostrenderEntry

akamai

function

function akamai(config: AkamaiConfig): EdgeAdapter;

cloudflare

function

function cloudflare(config: CloudflareConfig): EdgeAdapter;

cloudflareKv

function

function cloudflareKv(kv: KvNamespaceLike): PostrenderStore;

cloudfront

function

function cloudfront(config: CloudfrontConfig): EdgeAdapter;

cloudfront

function

function cloudfront(config: CloudfrontConfig): EdgeAdapter;

memory_store

function

function memory_store(max_entries?: number, max_bytes?: number): PostrenderStore;

upstash

function

function upstash(config: UpstashConfig): PostrenderStore;

valkey

function

function valkey(client: ValkeyLike): PostrenderStore;

postrender

const

const postrender: {
  handle: typeof handle;
  invalidate: typeof invalidate;
  invalidateWhere: typeof invalidateWhere;
}

AkamaiConfig

interface

interface AkamaiConfig {/*…*/}

AkamaiConfig.host

The EdgeGrid host, e.g. akab-xxxx.purge.akamaiapis.net.

host: string;

AkamaiConfig.clientToken

clientToken: string;

AkamaiConfig.clientSecret

clientSecret: string;

AkamaiConfig.accessToken

accessToken: string;

AkamaiConfig.site

The public site origin purged URLs are absolute against, e.g. https://www.example.com.

site: string;

AkamaiConfig.network

Fast Purge network (default production).

network?: "production" | "staging";

AkamaiConfig.baseUrl

Harness override: send API calls here instead of https://<host> (the edge emulator).

baseUrl?: string;

AkamaiConfig.maxAge

The s-maxage this edge is granted (defaults to the policy TTL in headers(meta)).

maxAge?: number;

CloudflareConfig

interface

interface CloudflareConfig {/*…*/}

CloudflareConfig.zoneId

zoneId: string;

CloudflareConfig.apiToken

An API token with Zone.Cache Purge permission (authorization: Bearer <token>).

apiToken: string;

CloudflareConfig.site

The public site origin purged URLs are absolute against, e.g. https://www.example.com.

site: string;

CloudflareConfig.baseUrl

Harness override: send API calls here instead of https://api.cloudflare.com.

baseUrl?: string;

CloudflareConfig.maxAge

The s-maxage this edge is granted (defaults to the policy TTL in headers(meta)).

maxAge?: number;

CloudfrontConfig

interface

interface CloudfrontConfig {/*…*/}

CloudfrontConfig.distributionId

distributionId: string;

CloudfrontConfig.accessKeyId

accessKeyId: string;

CloudfrontConfig.secretAccessKey

secretAccessKey: string;

CloudfrontConfig.baseUrl

Harness override: send API calls here instead of the real AWS endpoint.

baseUrl?: string;

EdgeAdapter

interface

The edge contract. headers(meta) returns extra response headers the CDN stores by — Akamai stamps depth-capped PREFIX tags (p:/fr, p:/fr/fr, …) since Fast Purge can't take an arbitrary prefix; CloudFront needs none (path wildcards are native). purgeUrl/purgeWhere speak the CDN's REAL purge API. Adapters never fan out — ogygia calls every edge with allSettled (one edge down ≠ publish down).

interface EdgeAdapter {/*…*/}

EdgeAdapter.name

Adapter name for logs/harness assertions ("akamai", "cloudfront").

name: string;

EdgeAdapter.headers

headers(meta: PostrenderMeta): Record<string, string>;

EdgeAdapter.purgeUrl

purgeUrl(url: string): Promise<void>;

EdgeAdapter.purgeWhere

purgeWhere(filter: {
    prefix: string;
  }): Promise<void>;

KvNamespaceLike

interface

The minimal Workers KV binding surface (KVNamespace, structurally).

interface KvNamespaceLike {/*…*/}

KvNamespaceLike.get

get(key: string, type: "text"): Promise<string | null>;

KvNamespaceLike.put

put(key: string, value: string, options?: {
    expirationTtl?: number;
  }): Promise<void>;

KvNamespaceLike.delete

delete(key: string): Promise<void>;

KvNamespaceLike.list

list(options: {
    prefix: string;
    cursor?: string;
  }): Promise<{
    keys: {
      name: string;
    }[];
    list_complete: boolean;
    cursor?: string;
  }>;

PostrenderHandleOptions

interface

postrender.handle({ … }) — the live objects (clients, creds) a server keeps its pages with.

interface PostrenderHandleOptions {/*…*/}

PostrenderHandleOptions.store

Where pages are kept (default: an in-process memory store).

store?: PostrenderStore;

PostrenderHandleOptions.edge

The CDNs in front of the app, purged on every invalidation.

edge?: EdgeAdapter[];

PostrenderMeta

interface

What EdgeAdapter.headers receives — enough to write the edge's storage instructions.

interface PostrenderMeta {/*…*/}

PostrenderMeta.url

Request pathname (the store key).

url: string;

PostrenderMeta.ttl

The policy TTL in seconds (the s-maxage the verdict grants).

ttl: number;

PostrenderPutOptions

interface

Options put receives beyond the entry.

interface PostrenderPutOptions {/*…*/}

PostrenderPutOptions.ttl

How long to keep the entry, in seconds: for a page, the TTL backstop (≤ 86400); for the build marker the deploy thaw keeps (a NUL-prefixed key), years. A store with native expiry (valkey EX) uses it directly. Either way postrender also ages a page on read against entry.created, so a page from a store without expiry is a miss once it is older than the TTL.

ttl: number;

PostrenderPutOptions.tags

Source receipts recorded during the render (s:<id>:<fp> from import.meta.og.source wrappers) — the REVERSE INDEX feeding evictByTag. Empty/omitted = no receipts.

tags?: string[];

PostrenderStore

interface

The store contract — four calls. Implementations MUST pass the shared contract spec (test/postrender.test.ts): tier-1 memory ships built-in; valkey rides REDIS_URL infra. Keys are URL pathnames, so evictWhere({ prefix }) is a key-prefix scan by construction.

interface PostrenderStore {/*…*/}

PostrenderStore.get

get(key: string): Promise<PostrenderEntry | null>;

PostrenderStore.put

put(key: string, entry: PostrenderEntry, options: PostrenderPutOptions): Promise<void>;

PostrenderStore.evict

evict(key: string): Promise<void>;

PostrenderStore.evictWhere

evictWhere(filter: {
    prefix: string;
  }): Promise<void>;

PostrenderStore.evictByTag

The reverse index (og.source precision): evict every key whose receipts carry tag and RETURN those keys — ogygia fans the returned URLs out to the edge adapters' purgeUrl. Optional: a store without it degrades invalidate(fn, args) to a warning.

evictByTag?(tag: string): Promise<string[]>;

PostrenderStore.size

Optional introspection for harnesses/devtools: number of live entries.

size?(): Promise<number>;

UpstashConfig

interface

interface UpstashConfig {/*…*/}

UpstashConfig.url

The REST endpoint, e.g. https://usw1-xxxx.upstash.io.

url: string;

UpstashConfig.token

token: string;

ValkeyLike

interface

The minimal client surface — ioredis (lowercase) and node-redis v4 (camelCase) both satisfy it structurally; the camelCase variants are probed at call time.

interface ValkeyLike {/*…*/}

ValkeyLike.get

get(key: string): Promise<string | null>;

ValkeyLike.set

ioredis-style positional EX; node-redis v4 accepts (key, value, { EX }) — both supported.

set(key: string, value: string, ...args: unknown[]): Promise<unknown>;

ValkeyLike.del

del(...keys: string[]): Promise<unknown>;

ValkeyLike.scan

scan(cursor: string | number, ...args: unknown[]): Promise<unknown>;

ValkeyLike.sadd

sadd?(key: string, ...members: string[]): Promise<unknown>;

ValkeyLike.sAdd

sAdd?(key: string, members: string | string[]): Promise<unknown>;

ValkeyLike.smembers

smembers?(key: string): Promise<string[]>;

ValkeyLike.sMembers

sMembers?(key: string): Promise<string[]>;

ValkeyLike.expire

expire?(key: string, seconds: number): Promise<unknown>;

ValkeyLike.ttl

ttl?(key: string): Promise<number>;

ValkeyLike.TTL

TTL?(key: string): Promise<number>;

PostrenderEntry

type

A stored page: a finished page response, or a permanent redirect.

type PostrenderEntry = {
  kind: "page";
  html: string;
  head_end?: number;
  headers: Record<string, string>;
  created: number;
  stitch?: boolean;
} | {
  kind: "redirect";
  status: 301 | 308;
  location: string;
  created: number;
};