@rsc-kit/core 0.25.0 → 0.27.0

package/dist/changed.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Names: a name for data a page depends on, so whatever changes it can say so
+ * from anywhere - a webhook, a job, another visitor's action - and every open
+ * tab showing it refreshes.
+ *
+ *     // a section says what it depends on
+ *     export default section('repos', Repos, { refreshOn: ({ params }) => [`team:${params.team}:repos`] })
+ *
+ *     // and whatever changes it says so
+ *     changed(`team:${team}:repos`)           // here, from a route.ts or an action
+ *     rsckit.Changed(ctx, "team:1:repos")     // or the backend, from its webhook
+ *     Rsc::changed("team:$team:repos");       // Laravel
+ *
+ * A name has a version: a number that moves whenever something says the name
+ * changed. Nothing else - not what changed, not the data. A page learns the
+ * versions at render; one stream per open tab watches them; when one moves,
+ * the sections carrying that name ask for themselves again, the way refresh()
+ * does. Data is never pushed, which is what keeps this working on a host that
+ * cannot hold state: a version is a read.
+ *
+ * Where versions live is the source's business. Without a backend they are in
+ * this process, which is one instance. With one, the backend keeps them - in
+ * its cache or a table, shared by every instance it runs - and answers
+ * `__rsc.changed`: given the versions a watcher holds, the ones that differ now.
+ * A backend that can wait holds the call until one does; one that cannot
+ * answers at once, and the watcher asks again on its interval. The protocol
+ * is the same either way, and so is the page.
+ */
+/** The reserved name a backend answers name versions on. */
+export declare const CHANGED_FUNCTION = "__rsc.changed";
+/** What `__rsc.changed` is asked. */
+export interface ChangedQuery {
+    /** The versions the asker holds. A name never changed is 0; -1 asks for every current version. */
+    since: Record<string, number>;
+    /** How long the backend may hold the call waiting for one to differ, in ms. It may answer at once. */
+    wait?: number;
+}
+/** What `__rsc.changed` answers: the versions among `since` that differ now. */
+export interface ChangedAnswer {
+    versions: Record<string, number>;
+}
+/**
+ * Where name versions are read from, and - when they live here - bumped.
+ *
+ * `changed` answers the versions among `since` that differ now, and may wait
+ * up to `wait` ms for one to. Nothing else is required of it, which is why a
+ * backend's cache, a table, this process's memory, or a pub/sub that answers
+ * the moment a name moves all fit behind it.
+ */
+export interface VersionSource {
+    changed(since: Record<string, number>, wait: number): Promise<Record<string, number>>;
+    /** Say these names changed. Only a source that holds its own versions can. */
+    bump(names: string[]): void | Promise<void>;
+}
+/** Versions kept in this process: the source without a backend, and the one tests use. */
+export declare function memoryVersions(): VersionSource;
+type HostFn = (name: string, ...args: unknown[]) => Promise<unknown>;
+/**
+ * Versions kept by the backend, read through `__rsc.changed`.
+ *
+ * A backend that has not got the function - an adapter from before names, or
+ * a host of plain rpc functions - is answered from this process instead,
+ * found out on the first ask and remembered, so a page with names still works
+ * on it: one instance, versions bumped by `changed()` here.
+ */
+export declare function backendVersions(call: HostFn): VersionSource;
+/** Runs one statement with positional parameters and resolves to its rows. */
+export type SqlQuery = (text: string, params: unknown[]) => Promise<readonly Record<string, unknown>[]>;
+export interface SqlVersionsOptions {
+    /**
+     * Your driver, as a function of SQL text and parameters:
+     *
+     *     query: (text, params) => sql.unsafe(text, params)            // postgres.js, Bun.sql
+     *     query: async (text, params) => (await pool.query(text, params)).rows   // node-postgres
+     */
+    query: SqlQuery;
+    /** The table: `CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL)`. */
+    table?: string;
+    /** How the n-th parameter is written (1-based). Default `?`; Postgres is `(n) => '$' + n`. */
+    placeholder?: (n: number) => string;
+    /**
+     * Called once with a function that wakes every waiting ask, for a database
+     * that can say the moment a version moved - Postgres's LISTEN:
+     *
+     *     listen: (wake) => sql.listen('rsc_versions', wake)
+     *
+     * Without it, a waiting ask reads the table every `poll` ms.
+     */
+    listen?: (wake: () => void) => unknown;
+    /**
+     * Run after every bump, to tell the other instances - Postgres's NOTIFY:
+     *
+     *     notify: () => sql.notify('rsc_versions', '')
+     */
+    notify?: () => unknown;
+    /** How often a waiting ask reads the table. Default 1000ms. */
+    poll?: number;
+}
+/**
+ * Versions in a table every instance shares: the web servers, and the worker
+ * that finishes a job and says so. The same table and columns Go's
+ * `SQLVersions` uses, so a Go service and a JavaScript worker can share one.
+ *
+ *     installVersionSource(sqlVersions({
+ *       query: (text, params) => sql.unsafe(text, params),
+ *       placeholder: (n) => '$' + n,
+ *       listen: (wake) => sql.listen('rsc_versions', wake),
+ *       notify: () => sql.notify('rsc_versions', ''),
+ *     }))
+ *
+ * Written with an UPDATE and, the first time, an INSERT - two statements any
+ * SQL dialect has - rather than an upsert each spells differently. Takes the
+ * app's own driver, so the engine has no database dependency of its own.
+ */
+export declare function sqlVersions(options: SqlVersionsOptions): VersionSource;
+/**
+ * Where versions are kept, as the app writes it for its own database: the
+ * three things rsc-kit cannot know about your storage, and nothing else.
+ * `createVersions` does the rest - comparing, waiting, waking.
+ *
+ *     // Drizzle
+ *     read: async (names) => Object.fromEntries(
+ *       (await db.select().from(rscVersions).where(inArray(rscVersions.name, names)))
+ *         .map((r) => [r.name, Number(r.version)])),
+ *     bump: async (names) => { for (const name of names) await db.insert(rscVersions)
+ *       .values({ name, version: 1 })
+ *       .onConflictDoUpdate({ target: rscVersions.name, set: { version: sql`${rscVersions.version} + 1` } }) },
+ *
+ *     // Redis
+ *     read: async (names) => Object.fromEntries((await redis.mget(names.map(k)))
+ *       .map((v, i) => [names[i], Number(v ?? 0)])),
+ *     bump: async (names) => { await Promise.all(names.map((n) => redis.incr(k(n)))) },
+ */
+export interface VersionStore {
+    /** The current version of each name asked for. A name it has never seen may be left out: it is 0. */
+    read(names: string[]): Promise<Record<string, number>>;
+    /** Move each name's version - by one, or to anything new: watchers compare, they do not count. */
+    bump(names: string[]): Promise<void>;
+    /**
+     * Called once with a function that wakes every waiting ask, when the store
+     * can say the moment a version moved - Postgres LISTEN, Redis SUBSCRIBE.
+     * Without it a waiting ask reads again every `poll` ms.
+     */
+    listen?(wake: () => void): unknown;
+    /** Run after a bump, to tell the other instances listening: Postgres NOTIFY, Redis PUBLISH. */
+    notify?(): unknown;
+}
+/**
+ * A version source over any store: SQL through any driver or ORM - Drizzle,
+ * Prisma, Kysely, Knex - or Redis, or anything with a read and an increment.
+ *
+ *     installVersionSource(createVersions({ read, bump, listen, notify }))
+ *
+ * rsc-kit owns the rest: an ask waits up to the time it was given for a
+ * version to differ, reading every `poll` ms (1000 by default) or the moment
+ * `listen` wakes it, and a bump in this process wakes this process's asks at
+ * once whatever the store.
+ */
+export declare function createVersions(store: VersionStore, options?: {
+    poll?: number;
+}): VersionSource;
+/** The parts of a Postgres client `postgresVersions` uses: postgres.js and `Bun.sql` both have them. */
+export interface PostgresClient {
+    unsafe(text: string, params?: unknown[]): PromiseLike<readonly Record<string, unknown>[]>;
+    /** postgres.js has it; with it, a waiting ask hears another instance at once. */
+    listen?(channel: string, onNotify: () => void): unknown;
+    notify?(channel: string, payload: string): unknown;
+}
+/**
+ * Versions in Postgres, from the client the app already has:
+ *
+ *     installVersionSource(postgresVersions(sql))
+ *
+ * `sqlVersions` with Postgres's placeholders, and - when the client can
+ * LISTEN, as postgres.js can - a change on one instance wakes the waiting asks
+ * on every other at once, rather than on their next read of the table.
+ * Without it (`Bun.sql`), the table is read once a second while an ask waits.
+ *
+ *     CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL)
+ */
+export declare function postgresVersions(sql: PostgresClient, options?: {
+    table?: string;
+    channel?: string;
+    poll?: number;
+}): VersionSource;
+/**
+ * Install where versions are read from - a table, Redis, any store - for this
+ * process; `null` takes it out again.
+ *
+ * The app's choice wins over the backend's: with a Go or Laravel backend that
+ * writes its versions to a store this process can read too, reading it here
+ * means watching costs the backend nothing.
+ */
+export declare function installVersionSource(source: VersionSource | null): void;
+/** The engine's, when a backend is installed: its versions, read through it. Not for apps. */
+export declare function installBackendVersionSource(source: VersionSource | null): void;
+/** The source in use: the app's, else the backend's, else this process's own. */
+export declare function versionSource(): VersionSource;
+/**
+ * Say these names changed, so every open tab showing them refreshes.
+ *
+ *     export async function POST(request: Request) {   // a webhook, in a route.ts
+ *       const { team } = await request.json()
+ *       changed(`team:${team}:repos`)
+ *       return new Response(null, { status: 204 })
+ *     }
+ *
+ * For an app that keeps its versions here. With a backend the versions are
+ * its, and so is the call: `rsckit.Changed`, `Rsc::changed`.
+ */
+export declare function changed(...names: string[]): Promise<void>;
+/** Thrown when a production server has no key to sign names with. */
+export declare class MissingSigningSecret extends Error {
+    constructor();
+}
+/**
+ * The secret names are signed with, when it does not come from the
+ * environment. Normally it does: `RSC_SIGNING_SECRET`, the same on every
+ * instance, or a tab served by one is refused by another.
+ *
+ * Its own secret, not the backend's host-call secret: that one authorises
+ * calls between the renderer and a backend, and an app with no backend has
+ * no reason to have it. Two jobs, two keys - one leaking does not hand out
+ * the other.
+ */
+export declare function configureChanged(options: {
+    secret?: string | null;
+}): void;
+/**
+ * Refuse, in production, to sign with a key nobody else has.
+ *
+ * A random key is right for one process - a dev server - and silently wrong
+ * for two: every tab served by one instance is refused by the next, and never
+ * refreshes. The server calls this on its first request when the app uses
+ * refreshOn, so the misconfiguration is an error at once rather than a page
+ * that quietly stops updating.
+ */
+export declare function assertSigningSecret(): void;
+/** A name's signature: the first 16 bytes of an HMAC, base64url, which is what rides in a url. */
+export declare function sign(name: string): Promise<string>;
+/** What a page hands the client for one name: its version at render, and its signature. */
+export type SignedName = [version: number, signature: string];
+/** How often the source is asked, when it answered at once. */
+export declare const CHANGES_INTERVAL_MS = 2000;
+/** How long the source may hold one ask. Bounds how long a new tab waits to join the shared ask. */
+export declare const CHANGES_WAIT_MS = 5000;
+/**
+ * The stream a tab watches its names on: `GET /_rsc/changes?w=[[name, version, signature], …]`.
+ *
+ * One `data:` line per version that moved, `{ name, version }`, from the moment
+ * the stream opens - a name that moved between the render and now is reported
+ * at once, so nothing that happened in the gap is missed. Keepalives as an
+ * events() route sends them; ends when the browser goes away.
+ */
+export declare function changes(request: Request): Promise<Response>;
+/** For tests: forget every stream and version this process has seen. */
+export declare function resetChanges(): void;
+/** The url a tab opens to watch, for the client. */
+export declare const CHANGES_PATH: "/_rsc/changes";
+export {};