@pg-prime/events 0.0.0 → 0.2.0

package/dist/log/topic.d.ts

@@ -0,0 +1,48 @@
+import type { Queryable, Subscription } from 'pg-prime';
+import type { TopicDef } from '../define.js';
+import type { Core } from '../events.js';
+import type { EntryRow } from './sql.js';
+export interface Entry<T> {
+    readonly id: bigint;
+    readonly topic: string;
+    readonly type: string | null;
+    readonly key: string | null;
+    readonly payload: T;
+    readonly headers: Record<string, string> | null;
+    readonly at: Date;
+    /** The opaque cursor state right after this entry: the only valid resume handle. */
+    readonly cursor: string;
+}
+export interface PublishOptions {
+    tx?: Queryable<any>;
+    type?: string;
+    key?: string;
+    headers?: Record<string, string>;
+}
+export interface TopicHandle<T> {
+    publish(payload: T, opts?: PublishOptions): Promise<{
+        id: bigint;
+    }>;
+    publishMany(items: readonly ({
+        payload: T;
+    } & Omit<PublishOptions, 'tx'>)[], opts?: {
+        tx?: Queryable<any>;
+    }): Promise<{
+        id: bigint;
+    }[]>;
+    tail(handler: (e: Entry<T>) => void, opts?: {
+        from?: 'now' | {
+            after: string;
+        };
+        signal?: AbortSignal;
+        pollMs?: number;
+    }): Promise<Subscription>;
+    /** Browse by id for admin tools; not a resume handle. */
+    read(opts?: {
+        afterId?: bigint;
+        limit?: number;
+    }): Promise<Omit<Entry<T>, 'cursor'>[]>;
+}
+export declare function entryOf<T>(def: TopicDef<T>, r: EntryRow): Promise<Omit<Entry<T>, 'cursor'>>;
+export declare function topicHandle<T>(core: Core, def: TopicDef<T>): TopicHandle<T>;
+//# sourceMappingURL=topic.d.ts.map

package/dist/log/topic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.d.ts","sourceRoot":"","sources":["../../src/log/topic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAKxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC/C,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACnE,WAAW,CACT,KAAK,EAAE,SAAS,CAAC;QAAE,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,EAAE,EAC/D,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAA;IAC5B,IAAI,CACF,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,EAC9B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,KAAK,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACjF,OAAO,CAAC,YAAY,CAAC,CAAA;IACxB,yDAAyD;IACzD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAA;CACvF;AAED,wBAAsB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAUjG;AAID,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAiG3E"}

package/dist/log/topic.js

@@ -0,0 +1,111 @@
+import { decodePayload, encodePayload } from '../payload.js';
+import { ASYNC_DISPOSE, emitAll } from '../util.js';
+import { waker } from '../waker.js';
+import { advance, advanceTo, decodeCursor, encodeCursor, seed } from './cursor.js';
+export async function entryOf(def, r) {
+    return {
+        id: r.id,
+        topic: def.name,
+        type: r.type,
+        key: r.key,
+        payload: await decodePayload(def.payload, r.payload),
+        headers: r.headers,
+        at: r.at,
+    };
+}
+const TAIL_BATCH = 500;
+export function topicHandle(core, def) {
+    const channel = core.topicChannel(def.name);
+    const handle = {
+        async publish(payload, opts = {}) {
+            const { tx, ...item } = opts;
+            const [r] = await handle.publishMany([{ payload, ...item }], tx === undefined ? {} : { tx });
+            return r;
+        },
+        async publishMany(items, opts = {}) {
+            if (opts.tx === undefined)
+                await core.ready(def);
+            else
+                core.assertStarted('publish');
+            if (items.length === 0)
+                return [];
+            const rows = await Promise.all(items.map(async (i) => ({
+                type: i.type ?? null,
+                key: i.key ?? null,
+                headers: i.headers ?? null,
+                payload: await encodePayload(def.payload, i.payload),
+            })));
+            const ids = await core.sql.publish(opts.tx ?? core.db, def.name, channel, rows);
+            core.hooks.emit('onPublish', {
+                topic: def.name,
+                count: ids.length,
+                inTx: opts.tx !== undefined,
+            });
+            return ids.map((id) => ({ id }));
+        },
+        async tail(handler, opts = {}) {
+            await core.ready(def);
+            const from = opts.from ?? 'now';
+            let cursor = from === 'now'
+                ? await core.sql.seedNow(core.db).then((s) => seed(s.xmax, s.xip))
+                : decodeCursor(from.after);
+            const errors = new Set();
+            const fail = (e) => emitAll(errors, e);
+            const stop = new AbortController();
+            opts.signal?.addEventListener('abort', () => stop.abort(), { once: true });
+            if (opts.signal?.aborted === true)
+                stop.abort();
+            const wake = waker(core.db, channel, {
+                pollMs: opts.pollMs ?? 5000,
+                signal: stop.signal,
+                onInternal: (e) => core.hooks.emit('onInternal', e),
+            });
+            const loop = (async () => {
+                do {
+                    try {
+                        while (!stop.signal.aborted) {
+                            const { view, rows } = await core.sql.read(core.db, def.name, cursor, TAIL_BATCH, null);
+                            for (const r of rows) {
+                                cursor = advance(cursor, view, r);
+                                try {
+                                    handler({ ...(await entryOf(def, r)), cursor: encodeCursor(cursor) });
+                                }
+                                catch (e) {
+                                    fail(e);
+                                }
+                            }
+                            cursor = advanceTo(cursor, view);
+                            if (view.pos === null && view.late === null)
+                                break;
+                        }
+                    }
+                    catch (e) {
+                        fail(e);
+                    }
+                } while ((await wake.wait()) !== undefined);
+            })();
+            const close = async () => {
+                stop.abort();
+                await loop;
+                core.running.delete(sub);
+            };
+            // Tails heal gaps from the log, so only 'error' ever fires.
+            const on = (event, h) => {
+                if (event !== 'error')
+                    return () => { };
+                errors.add(h);
+                return () => void errors.delete(h);
+            };
+            const sub = { channel, close, [ASYNC_DISPOSE]: close, on };
+            core.running.add(sub);
+            return sub;
+        },
+        async read(opts = {}) {
+            await core.ready(def);
+            const rows = await core.sql.browse(core.db, def.name, opts.afterId ?? 0n, opts.limit ?? 100);
+            return Promise.all(rows.map((r) => entryOf(def, r)));
+        },
+    };
+    return handle;
+}
+//# sourceMappingURL=topic.js.map

package/dist/log/topic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.js","sourceRoot":"","sources":["../../src/log/topic.ts"],"names":[],"mappings":"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"}

package/dist/payload.d.ts

@@ -0,0 +1,40 @@
+/** The Standard Schema v1 interface (standardschema.dev), copied as a type: no dependency. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1.Result<Output> | Promise<StandardSchemaV1.Result<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+export declare namespace StandardSchemaV1 {
+    type Result<Output> = {
+        readonly value: Output;
+        readonly issues?: undefined;
+    } | {
+        readonly issues: readonly Issue[];
+    };
+    interface Issue {
+        readonly message: string;
+        readonly path?: readonly (PropertyKey | {
+            readonly key: PropertyKey;
+        })[] | undefined;
+    }
+}
+export interface PayloadOptions<T> {
+    /** Validates on both sides: before encoding and after decoding. */
+    schema?: StandardSchemaV1<unknown, T>;
+    /** Maps the value to and from its JSON form. */
+    codec?: {
+        encode(v: T): unknown;
+        decode(v: unknown): T;
+    };
+}
+/** Validates, encodes and serializes a payload; refuses NUL characters and oversize documents. */
+export declare function encodePayload<T>(opts: PayloadOptions<T>, value: T, maxBytes?: number): Promise<string>;
+/** Decodes a JSON value read back from the database and validates it. */
+export declare function decodePayload<T>(opts: PayloadOptions<T>, wire: unknown): Promise<T>;
+//# sourceMappingURL=payload.d.ts.map

package/dist/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../src/payload.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;QAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAA;KAChF,CAAA;CACF;AAED,MAAM,CAAC,OAAO,WAAW,gBAAgB,CAAC;IACxC,KAAK,MAAM,CAAC,MAAM,IACd;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,GACvD;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;KAAE,CAAA;IACzC,UAAU,KAAK;QACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG;YAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;SAAE,CAAC,EAAE,GAAG,SAAS,CAAA;KACrF;CACF;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,mEAAmE;IACnE,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IACrC,gDAAgD;IAChD,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;QAAC,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAA;KAAE,CAAA;CACzD;AAID,kGAAkG;AAClG,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,KAAK,EAAE,CAAC,EACR,QAAQ,GAAE,MAAkB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnF"}

package/dist/payload.js

@@ -0,0 +1,53 @@
+import { PayloadError } from './errors.js';
+const MAX_BYTES = 1024 * 1024;
+/** Validates, encodes and serializes a payload; refuses NUL characters and oversize documents. */
+export async function encodePayload(opts, value, maxBytes = MAX_BYTES) {
+    const v = await validate(opts, value);
+    const wire = opts.codec === undefined ? v : opts.codec.encode(v);
+    const json = JSON.stringify(wire);
+    if (json === undefined)
+        throw new PayloadError('@pg-prime/events: a payload must be JSON.');
+    const path = nulPath(wire, []);
+    if (path !== undefined) {
+        throw new PayloadError(`@pg-prime/events: the payload has a NUL character at ${fmt(path)}; jsonb cannot store it.`, path);
+    }
+    const bytes = new TextEncoder().encode(json).length;
+    if (bytes > maxBytes) {
+        throw new PayloadError(`@pg-prime/events: the payload is ${bytes} bytes; the limit is ${maxBytes}. Store the ` +
+            `document in a table and publish its id.`);
+    }
+    return json;
+}
+/** Decodes a JSON value read back from the database and validates it. */
+export function decodePayload(opts, wire) {
+    return validate(opts, opts.codec === undefined ? wire : opts.codec.decode(wire));
+}
+async function validate(opts, value) {
+    if (opts.schema === undefined)
+        return value;
+    const r = await opts.schema['~standard'].validate(value);
+    if (r.issues === undefined)
+        return r.value;
+    const issue = r.issues[0];
+    const path = (issue?.path ?? []).map((p) => (typeof p === 'object' ? p.key : p));
+    throw new PayloadError(`@pg-prime/events: the payload failed its schema at ${fmt(path)}: ${issue?.message ?? 'invalid'}`, path);
+}
+function nulPath(v, path) {
+    if (typeof v === 'string')
+        return v.includes('\0') ? path : undefined;
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    for (const [k, x] of Object.entries(v)) {
+        const key = Array.isArray(v) ? Number(k) : k;
+        if (k.includes('\0'))
+            return [...path, key];
+        const p = nulPath(x, [...path, key]);
+        if (p !== undefined)
+            return p;
+    }
+    return undefined;
+}
+function fmt(path) {
+    return path.length === 0 ? '(root)' : path.map(String).join('.');
+}
+//# sourceMappingURL=payload.js.map

package/dist/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../src/payload.ts"],"names":[],"mappings":"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"}

package/dist/unsupported-typescript.d.ts

@@ -0,0 +1,70 @@
+// GENERATED by tools/api-snapshot.mjs — do not edit by hand.
+//
+// The `types@<5.9` gate of design/08 §2.2, first in every condition object of every subpath in
+// package.json. A consumer on TypeScript < 5.9 resolves `@pg-prime/events` to THIS file instead of the
+// real declarations, so every name still exists and every USE of one lands the message in the
+// error text. Verified against TypeScript 5.8.3 by tools/pack-smoke.mjs on every run:
+//
+//   consumer.ts(12,15): error TS2349: This expression is not callable.
+//     Type '{ ERROR: "@pg-prime/events requires TypeScript >= 5.9 — see https://pg-prime.dev/ts"; }' has no call signatures.
+//
+// Naming the key `ERROR` rather than a `__dunder__` is §2.2's own refinement over Kysely's
+// version: it reads first in a truncated hover.
+//
+// ## `Unsupported<M = …> = M` is an identity alias ON PURPOSE — do not "simplify" it
+//
+// Written the obvious way, `type Unsupported = { ERROR: '…' }`, TypeScript prints the ALIAS NAME
+// in the diagnostic — "Type 'Unsupported' has no call signatures" — and the message never
+// reaches the user, which defeats the entire file. A generic alias whose body is just its own
+// parameter has no alias symbol to print, so the checker falls back to the structural form and
+// the sentence appears. Measured, both shapes, on 5.9.3 and 5.8.3.
+//
+// The lists are the root entry's value and type exports, taken from tools/api-snapshot/*.json.
+// `node tools/api-snapshot.mjs --check` fails if this file and that golden disagree, which is
+// what stops the stub from silently rotting into "this package has no exported member 'x'".
+// The type parameters are optional and are only as many as the real declaration has, so that a
+// generic use resolves to the brand instead of erroring with "is not generic".
+
+type Unsupported<Message = { ERROR: '@pg-prime/events requires TypeScript >= 5.9 — see https://pg-prime.dev/ts' }> = Message
+
+export declare const EventsLeaseLostError: Unsupported
+export declare const NotStartedError: Unsupported
+export declare const PayloadError: Unsupported
+export declare const SchemaVersionError: Unsupported
+export declare const defineChannel: Unsupported
+export declare const defineSubscription: Unsupported
+export declare const defineTopic: Unsupported
+export declare const engineChannel: Unsupported
+export declare const engineChannelSql: Unsupported
+export declare const pgEvents: Unsupported
+export declare const waker: Unsupported
+
+export type BatchHandler<T0 = any> = Unsupported
+export type ChannelDef<T0 = any> = Unsupported
+export type ChannelHandle<T0 = any> = Unsupported
+export type Entry<T0 = any> = Unsupported
+export type EntryHandler<T0 = any> = Unsupported
+export type Events<T0 = any> = Unsupported
+export type EventsConfig<T0 = any> = Unsupported
+export type EventsDefinitions = Unsupported
+export type EventsHooks = Unsupported
+export type EventsLeaseLostError = Unsupported
+export type InternalKind = Unsupported
+export type NotStartedError = Unsupported
+export type PayloadError = Unsupported
+export type PayloadOf<T0 = any> = Unsupported
+export type PayloadOptions<T0 = any> = Unsupported
+export type PublishOptions = Unsupported
+export type ReadContext = Unsupported
+export type Reader = Unsupported
+export type RetryOptions = Unsupported
+export type RunOptions = Unsupported
+export type SchemaVersionError = Unsupported
+export type StandardSchemaV1<T0 = any, T1 = any> = Unsupported
+export type SubscriptionDef<T0 = any> = Unsupported
+export type SubscriptionHandle<T0 = any> = Unsupported
+export type TopicDef<T0 = any> = Unsupported
+export type TopicHandle<T0 = any> = Unsupported
+export type WakeReason = Unsupported
+export type Waker = Unsupported
+export type WakerOptions = Unsupported

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+export declare const ASYNC_DISPOSE: symbol;
+/** Calls every observer; a throwing one neither stops the rest nor escapes. */
+export declare function emitAll(observers: Iterable<(e: unknown) => void>, e: unknown): void;
+/** Resolves after `ms`, or early when `signal` aborts. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function backoffMs(p: {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: 'full' | 'equal' | 'none';
+}, attempt: number, random?: () => number): number;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,EAAE,MAC6D,CAAA;AAEzF,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,IAAI,CAMnF;AAED,0DAA0D;AAC1D,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrE;AAED,wBAAgB,SAAS,CACvB,CAAC,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;CAAE,EACjF,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAIR"}

package/dist/util.js

@@ -0,0 +1,31 @@
+export const ASYNC_DISPOSE = Symbol.asyncDispose ?? Symbol.for('Symbol.asyncDispose');
+/** Calls every observer; a throwing one neither stops the rest nor escapes. */
+export function emitAll(observers, e) {
+    for (const h of observers) {
+        try {
+            h(e);
+        }
+        catch { }
+    }
+}
+/** Resolves after `ms`, or early when `signal` aborts. */
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted === true)
+            return resolve();
+        const done = () => {
+            clearTimeout(t);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const t = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+export function backoffMs(p, attempt, random = Math.random) {
+    const ceiling = Math.min(p.maxDelayMs, p.baseDelayMs * 2 ** Math.max(0, attempt - 1));
+    if (p.jitter === 'none')
+        return ceiling;
+    return p.jitter === 'equal' ? ceiling / 2 + random() * (ceiling / 2) : random() * ceiling;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GACvB,MAAoC,CAAC,YAAY,IAAI,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAA;AAEzF,+EAA+E;AAC/E,MAAM,UAAU,OAAO,CAAC,SAAyC,EAAE,CAAU;IAC3E,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,CAAC,CAAC,CAAC,CAAC,CAAA;QACN,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACZ,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI;YAAE,OAAO,OAAO,EAAE,CAAA;QAC9C,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,YAAY,CAAC,CAAC,CAAC,CAAA;YACf,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAC1C,OAAO,EAAE,CAAA;QACX,CAAC,CAAA;QACD,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAC9B,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IACzD,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,CAAiF,EACjF,OAAe,EACf,MAAM,GAAiB,IAAI,CAAC,MAAM;IAElC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;IACrF,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,OAAO,CAAA;IACvC,OAAO,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,OAAO,CAAA;AAC3F,CAAC"}

package/dist/waker.d.ts

@@ -0,0 +1,22 @@
+import type { Db } from 'pg-prime';
+import type { EventsHooks } from './hooks.js';
+export type WakeReason = 'notify' | 'gap' | 'poll';
+export interface WakerOptions {
+    pollMs: number;
+    signal?: AbortSignal;
+    /** Receives `listen-unavailable` when the waker falls back to polling. */
+    onInternal?: EventsHooks['onInternal'];
+}
+/** A single-use async iterable of wake reasons, plus `wait(ms)` for loops with their own timers. */
+export interface Waker extends AsyncIterable<WakeReason> {
+    /** The next reason, waiting at most `ms` (default `pollMs`; a timeout is `'poll'`); `undefined` once closed. */
+    wait(ms?: number): Promise<WakeReason | undefined>;
+    close(): Promise<void>;
+}
+/**
+ * Wakes on a NOTIFY on `channel`, a LISTEN `gap`, or `pollMs` of silence. LISTEN starts here; once
+ * it is established the first reason is `'gap'`, since anything sent before it was missed. Behind
+ * a transaction pooler without `directConnection` it only polls.
+ */
+export declare function waker(db: Db, channel: string, opts: WakerOptions): Waker;
+//# sourceMappingURL=waker.d.ts.map

package/dist/waker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waker.d.ts","sourceRoot":"","sources":["../src/waker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAgB,MAAM,UAAU,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;AAElD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAA;CACvC;AAED,oGAAoG;AACpG,MAAM,WAAW,KAAM,SAAQ,aAAa,CAAC,UAAU,CAAC;IACtD,gHAAgH;IAChH,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,KAAK,CA0ExE"}

package/dist/waker.js

@@ -0,0 +1,86 @@
+import { UnsupportedInPoolerModeError } from 'pg-prime';
+/**
+ * Wakes on a NOTIFY on `channel`, a LISTEN `gap`, or `pollMs` of silence. LISTEN starts here; once
+ * it is established the first reason is `'gap'`, since anything sent before it was missed. Behind
+ * a transaction pooler without `directConnection` it only polls.
+ */
+export function waker(db, channel, opts) {
+    let sub;
+    let listening;
+    let unsupported = false;
+    let reported = false;
+    let flag;
+    let wake;
+    let closed = opts.signal?.aborted === true;
+    const raise = (kind) => {
+        if (kind === 'gap' || flag === undefined)
+            flag = kind;
+        wake?.();
+    };
+    const listen = async () => {
+        try {
+            const s = await db.listen(channel, () => raise('notify'));
+            if (closed)
+                return void (await s.close());
+            s.on('gap', () => raise('gap'));
+            sub = s;
+            reported = false;
+            raise('gap');
+        }
+        catch (e) {
+            unsupported = e instanceof UnsupportedInPoolerModeError;
+            if (reported)
+                return;
+            reported = true;
+            opts.onInternal?.({
+                kind: 'listen-unavailable',
+                message: `@pg-prime/events: cannot LISTEN on ${channel}; polling every ${opts.pollMs} ms.`,
+                cause: e,
+            });
+        }
+    };
+    const close = async () => {
+        closed = true;
+        wake?.();
+        const s = sub;
+        sub = undefined;
+        await s?.close();
+    };
+    const wait = async (ms = opts.pollMs) => {
+        if (sub === undefined && !unsupported && !closed) {
+            listening ??= listen();
+            await listening;
+            listening = undefined;
+        }
+        if (flag === undefined && !closed) {
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, ms);
+                wake = () => {
+                    clearTimeout(t);
+                    resolve();
+                };
+            });
+            wake = undefined;
+        }
+        if (closed)
+            return undefined;
+        const reason = flag ?? 'poll';
+        flag = undefined;
+        return reason;
+    };
+    opts.signal?.addEventListener('abort', () => void close(), { once: true });
+    if (!closed)
+        listening = listen();
+    const it = {
+        next: async () => {
+            const value = await wait();
+            return value === undefined ? { done: true, value: undefined } : { done: false, value };
+        },
+        return: async () => {
+            await close();
+            return { done: true, value: undefined };
+        },
+    };
+    return { wait, close, [Symbol.asyncIterator]: () => it };
+}
+//# sourceMappingURL=waker.js.map

package/dist/waker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waker.js","sourceRoot":"","sources":["../src/waker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,56 @@
 {
   "name": "@pg-prime/events",
-  "version": "0.0.0",
-  "description": "Typed LISTEN/NOTIFY channels, a durable event log with subscriptions, and tails for pg-prime. Pre-alpha — the API will change. Placeholder; the first real release follows.",
+  "version": "0.2.0",
+  "description": "Typed LISTEN/NOTIFY channels, a durable event log with subscriptions, and tails for pg-prime. Pre-alpha — the API will change.",
+  "keywords": [
+    "event-log",
+    "events",
+    "listen-notify",
+    "pg-prime",
+    "postgres",
+    "postgresql",
+    "pubsub"
+  ],
   "license": "MPL-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pg-prime/pg-prime.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types@<5.9": "./dist/unsupported-typescript.d.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "fast-check": "^4.10.2",
+    "vitest": "^4.1.10",
+    "@pg-prime/testing": "0.1.1",
+    "pg-prime": "0.2.0"
+  },
+  "peerDependencies": {
+    "pg-prime": ">=0.2.0"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "node ../../tools/build-package.mjs",
+    "clean": "node ../../tools/build-package.mjs --clean",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --project unit",
+    "test:live": "vitest run --project unit --project live",
+    "test:pg": "vitest run"
   }
-}
+}