what-isr 0.12.3 → 0.12.4

package/index.d.ts

@@ -20,12 +20,30 @@ export interface PageCacheConfig {
    */
   vary?: string[] | string;
   fallback?: 'blocking' | boolean;
-  onMiss?: 'blocking' | string;
-  /** Background regeneration interval, in seconds. */
-  pollInterval?: number;
+  /** 'stale-if-error' serves an expired entry rather than failing when a cold render throws. */
+  onMiss?: 'stale-if-error' | 'blocking' | string;
 }
+// `pollInterval` was declared on the config above and read by nothing, here or
+// in what-server: setting it produced no error and no regeneration. Poll
+// regeneration itself is real, but it is driven explicitly, because it only
+// means anything in a long-lived process. Build a scheduler, register the routes
+// worth keeping warm, and hand it to the Node adapter, which starts and stops
+// it with the server:
+//
+//   const scheduler = createScheduler(engine);
+//   scheduler.register({ path: '/', query: {}, params: {}, config: page, route }, { intervalMs: 300_000 });
+//   createServer({ routes, cache: engine, scheduler });
+//
+// Declaring the key again is only honest once something resolves it into that
+// register() call for every route that sets it.
 
 // --- Stores ---
+// The time fields are the ones makeEntry() writes and isFresh() /
+// isServableStale() / the Redis TTL read. They were declared as
+// `createdAt` + `revalidate` + `swr`, none of which exist on a real entry: a
+// hand-built entry following that shape has no `expiresAt`, so isFresh()
+// compares against undefined, every read is a miss, and the cache silently
+// never serves. Build entries with makeEntry() rather than by hand.
 export interface CacheEntry {
   html: string;
   head?: string;
@@ -33,21 +51,28 @@ export interface CacheEntry {
   status?: number;
   tags?: string[];
   path?: string;
+  /** A partial render (skeleton/streamed shell). */
+  partial?: boolean;
   /** Per-user render: never stored, never served from a shared cache. */
   private?: boolean;
-  /** Epoch ms when the entry was created. */
-  createdAt: number;
-  /** Seconds-to-stale snapshot from the page config. */
-  revalidate?: number;
-  swr?: number;
+  /** Epoch ms when the entry was rendered. */
+  renderedAt: number;
+  /** Seconds until stale. 0 means "always revalidate" when `revalidate: 0` was declared. */
+  maxAge: number;
+  /** Extra seconds the entry may be served stale while it regenerates. */
+  swrWindow: number;
+  /** Epoch ms the entry goes stale, or Infinity for a durable static entry. */
+  expiresAt: number;
 }
 
 export interface CacheStore {
   get(key: string): Promise<CacheEntry | undefined>;
   set(key: string, entry: CacheEntry): Promise<void>;
   delete(key: string): Promise<boolean>;
+  /** Both delete-by helpers return the keys they removed. */
   deleteByTag(tag: string): Promise<string[]>;
-  deleteByPath?(path: string): Promise<string[]>;
+  /** Not optional: revalidatePath() calls this unconditionally, so a store without it throws on the first purge. */
+  deleteByPath(path: string): Promise<string[]>;
   clear(): Promise<void>;
   keys(): Promise<string[]>;
 }
@@ -56,7 +81,18 @@ export function createMemoryStore(options?: { max?: number }): CacheStore;
 export function createFilesystemStore(options: { dir: string; shards?: number }): CacheStore;
 export function createRedisStore(options: { client: unknown; prefix?: string }): CacheStore;
 
-export function makeEntry(out: Partial<CacheEntry>, config?: PageCacheConfig, now?: number): CacheEntry;
+/** Fill an entry's time fields from a render result plus the route config. */
+export function makeEntry(
+  out: Partial<RenderResult> & {
+    path?: string;
+    partial?: boolean;
+    private?: boolean;
+    /** A render that read request headers is per-user, so it stores as `private`. */
+    usedRequestHeaders?: boolean;
+  },
+  config?: PageCacheConfig,
+  now?: number,
+): CacheEntry;
 export function isFresh(entry: CacheEntry, now?: number): boolean;
 export function isServableStale(entry: CacheEntry, now?: number): boolean;
 
@@ -95,10 +131,20 @@ export function createFastlyCDN(options: { serviceId: string; apiToken: string;
 export function createVercelCDN(options: { projectId: string; token: string; teamId?: string }): CDNAdapter;
 
 // --- Headers ---
-export interface CacheHeaderOptions {
-  cdn?: boolean;
-}
-export function buildCacheHeaders(entry?: CacheEntry, status?: 'HIT' | 'STALE' | 'MISS', options?: CacheHeaderOptions): Record<string, string>;
+export type CacheStatus = 'HIT' | 'STALE' | 'MISS' | 'BYPASS';
+/**
+ * Build the Cache-Control / X-What-Cache / Cache-Tag headers for a response.
+ * The second argument is the ROUTE CONFIG, not the cache status: the previous
+ * declaration ((entry, status, { cdn })) described a function that does not
+ * exist, so a caller who followed it passed the status where the config goes.
+ */
+export function buildCacheHeaders(
+  entry?: Partial<CacheEntry>,
+  config?: PageCacheConfig,
+  cacheStatus?: CacheStatus,
+  /** The declared vary the cache key used. Falls back to `config.vary`. */
+  vary?: string[],
+): Record<string, string>;
 
 // --- Static paths ---
 export interface StaticPathEntry {
@@ -132,14 +178,17 @@ export interface RenderResult {
   status?: number;
   tags?: string[];
 }
-export type RenderFn = (routeMatch: RouteMatch) => RenderResult | Promise<RenderResult>;
+/** The engine calls render(routeMatch, ctx); `ctx` is reserved and currently `{}`. */
+export type RenderFn = (routeMatch: RouteMatch, ctx?: Record<string, unknown>) => RenderResult | Promise<RenderResult>;
 
 // --- ISR engine ---
 export interface ServeResult {
   html: string;
+  head?: string;
+  state?: unknown;
   status: number;
   headers: Record<string, string>;
-  cacheStatus: 'HIT' | 'STALE' | 'MISS';
+  cacheStatus: CacheStatus;
 }
 export interface RevalidateOptions {
   regenerate?: boolean;
@@ -147,8 +196,13 @@ export interface RevalidateOptions {
 }
 export interface CacheEngine {
   handle(routeMatch: RouteMatch, renderOverride?: RenderFn): Promise<ServeResult>;
-  revalidatePath(path: string, options?: RevalidateOptions): Promise<void>;
-  revalidateTag(tag: string, options?: RevalidateOptions): Promise<void>;
+  /** Render and re-store one route now. What the poll scheduler calls per tick. */
+  regenerate(routeMatch: RouteMatch): Promise<CacheEntry>;
+  /** Both purges resolve to the cache keys they deleted, not to void. */
+  revalidatePath(path: string, options?: RevalidateOptions): Promise<string[]>;
+  revalidateTag(tag: string, options?: RevalidateOptions): Promise<string[]>;
+  /** The cache key for a route match. Throws when the route declares `vary` and no headers were supplied. */
+  keyFor(routeMatch: RouteMatch): string;
   store: CacheStore;
 }
 export function createCacheEngine(options?: {
@@ -174,9 +228,24 @@ export function createRevalidateWebhook(
 ): (req: WebhookRequest) => Promise<WebhookResponse>;
 
 // --- Poll scheduler ---
+// Register the routes to keep warm, then start it (or hand it to what-server's
+// createServer, which starts it and stops it on SIGTERM/SIGINT). Every method
+// returns the scheduler so registration can chain.
 export interface Scheduler {
-  register(route: RouteMatch, options: { intervalMs: number }): void;
-  start(): void;
-  stop(): void;
+  register(route: RouteMatch, options: { intervalMs: number }): Scheduler;
+  start(): Scheduler;
+  stop(): Scheduler;
+}
+// The runtime reads maxConcurrent/random/setTimer/clearTimer/logger. The
+// `concurrency` and `jitter` declared before were read by nothing, so a caller
+// capping concurrency got the default 4 and no warning.
+export interface SchedulerOptions {
+  /** Regenerations allowed in flight at once. Default 4. */
+  maxConcurrent?: number;
+  /** Jitter source (0..1), injectable for deterministic tests. Intervals are spread by up to +10%. */
+  random?: () => number;
+  setTimer?: (fn: () => void, ms: number) => any;
+  clearTimer?: (timer: any) => void;
+  logger?: Pick<Console, 'error' | 'warn' | 'log'>;
 }
-export function createScheduler(engine: CacheEngine, options?: { concurrency?: number; jitter?: number }): Scheduler;
+export function createScheduler(engine: CacheEngine, options?: SchedulerOptions): Scheduler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-isr",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "What Framework - Origin-first ISR cache engine: stale-while-revalidate, on-demand & poll regeneration, no CDN required",
   "type": "module",
   "main": "src/index.js",
@@ -30,7 +30,7 @@
   "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",
   "peerDependencies": {
-    "what-server": "^0.12.3"
+    "what-server": "^0.12.4"
   },
   "peerDependenciesMeta": {
     "what-server": {