pipework 0.250.0 → 0.251.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.251.0
+
+- **Added: `startPolling(ask, options?)` in `pipework/client`** (#890), for a job a person waits on in the browser. One ask at a time; waits back off from `firstMs` (3 s) by `backOff` (1.5) to `longestMs` (10 s); nothing is asked while the tab is hidden, and visible again asks at once; an ask may return `{ atLeastMs }` to wait longer; a throwing ask goes to `onError` and polling goes on. Returns `stop`.
+- **Added: `waitFromResponse(response)`** (#890) turns a 429 or 503 into `{ atLeastMs }` from `Retry-After` (seconds or HTTP date), or from the body's `error.retryAfterSeconds` when a cross-origin page cannot read the header.
+
 ## 0.250.0
 
 - **Added: `filter.arrayHas(arrayCol, col)` takes a column or SQL expression as the value** (#888). It renders `<col> = ANY(<arrayCol>)`, with no bind and no cast, so a join from rows holding an array of ids to the table they point at can use that table's index. `arrayAny(arr, el => eq(el, col))` renders `EXISTS (... unnest ...)`, which can't (subseam: 347 s against 37.8 s for the same rows). A JS value is bound and cast as before.

package/REFERENCE.md

@@ -2024,6 +2024,19 @@ window.addEventListener('unhandledrejection', e => send('rejection', String(e.re
 // server: server.registerHandlers(alerts.clientFaults(ops, { path: '/client-faults', apps: { web: { owner: 'web team', runbook: 'Check the release' } }, cors: { origin: ['https://app.example.com'], credentials: true } }))
 ```
 
+`startPolling(ask, options?)` from `pipework/client` asks again and again until the caller stops it, for a job a person waits on in the browser. The first ask is after `firstMs` (default 3000, the caller already has the enqueue's state); each wait is the last × `backOff` (default 1.5; 1 is a fixed interval) up to `longestMs` (default 10000). One ask at a time: the next wait starts when the ask settles. An ask that throws goes to `onError` and polling goes on. An ask may return `{ atLeastMs }`: the next wait is at least that, and the back-off carries on as if it had not. While the page is hidden nothing is asked (`pauseWhenHidden`, default true); visible again asks at once and the waits restart from `firstMs`. It returns `stop` (idempotent; an ask still in flight schedules nothing). Bad options throw. `waitFromResponse(response)` turns a 429 or 503 into `{ atLeastMs }` from `Retry-After` (seconds or HTTP date), or from `error.retryAfterSeconds` in the JSON body when the header is not readable; the response's body stays unread.
+
+```ts
+import { startPolling, waitFromResponse } from 'pipework/client'
+const stop = startPolling(async () => {
+  const res = await fetch(`/jobs/${id}`, { credentials: 'include' })
+  const wait = await waitFromResponse(res)
+  if (wait) return wait
+  const job = await res.json()
+  if (job.state === 'done') stop()
+}, { onError: e => console.warn(e) })
+```
+
 ## support — Support Tickets
 
 Mail to a support address becomes a ticket that an agent triages; nothing reaches a customer without a human's approval. Built on `mail` (send and receive) and the delivery of `alerts`.

package/dist/client/index.d.ts

@@ -1,3 +1,5 @@
 export { reportClientFault, pageLeaving, LEAVING_HOLD_MS, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js';
 export type { ClientFaultReport, ReportClientFaultOptions } from './report-fault.js';
+export { startPolling, waitFromResponse } from './poll.js';
+export type { PollingOptions, PollingPage, PollAnswer } from './poll.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AACrI,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AACrI,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AACpF,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC1D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA"}

package/dist/client/index.js

@@ -1,2 +1,3 @@
 export { reportClientFault, pageLeaving, LEAVING_HOLD_MS, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js';
+export { startPolling, waitFromResponse } from './poll.js';
 //# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAErI,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA"}

package/dist/client/poll.d.ts

@@ -0,0 +1,41 @@
+/** What an ask may return to slow the next one: the next wait is at least `atLeastMs`. */
+export type PollAnswer = {
+    atLeastMs: number;
+} | void;
+/** The part of `document` the poller uses. */
+export interface PollingPage {
+    readonly hidden: boolean;
+    addEventListener(type: 'visibilitychange', listener: () => void): void;
+    removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+export interface PollingOptions {
+    /** First wait in ms, before the first ask. Default 3000. */
+    firstMs?: number;
+    /** Each wait is the last times `backOff`, up to this. Default 10000. */
+    longestMs?: number;
+    /** At least 1; 1 is a fixed interval. Default 1.5. */
+    backOff?: number;
+    /** Default true: nothing is asked while the page is hidden; visible again asks at once and the waits restart from `firstMs`. */
+    pauseWhenHidden?: boolean;
+    /** An ask that throws or rejects stops nothing; the error is passed here and the next ask is scheduled. */
+    onError?: (error: unknown) => void;
+    /** Default `document` when there is one. */
+    page?: PollingPage;
+}
+/**
+ * Calls `ask` after `firstMs`, then again after each answer, waiting longer each time (`backOff`, up to `longestMs`).
+ * One ask at a time: the next wait starts when the last ask settled. An ask returning `{ atLeastMs }` makes the next
+ * wait at least that long; the back-off carries on as if it had not. While the page is hidden nothing is asked.
+ * Returns `stop`, which is idempotent; an ask still in flight when it is called schedules nothing and reports no error.
+ */
+export declare function startPolling(ask: () => Promise<PollAnswer>, options?: PollingOptions): () => void;
+/**
+ * For a 429 or 503: how long the server asked the client to wait, as `{ atLeastMs }` to return from an ask.
+ * Reads `Retry-After` (seconds or an HTTP date); when that is absent or unreadable (a cross-origin page cannot see it
+ * without CORS `exposedHeaders`), reads `error.retryAfterSeconds` from the JSON body. The response's own body stays unread.
+ * Any other status, or no wait found, gives undefined.
+ */
+export declare function waitFromResponse(response: Response): Promise<{
+    atLeastMs: number;
+} | undefined>;
+//# sourceMappingURL=poll.d.ts.map

package/dist/client/poll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll.d.ts","sourceRoot":"","sources":["../../src/client/poll.ts"],"names":[],"mappings":"AAEA,0FAA0F;AAC1F,MAAM,MAAM,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAA;AAErD,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IACtE,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC1E;AAED,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gIAAgI;IAChI,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,IAAI,CAgErG;AAUD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAYrG"}

package/dist/client/poll.js

@@ -0,0 +1,112 @@
+// Browser-safe: no node imports, no runtime dependencies.
+function check(name, ok, rule, value) {
+    if (!ok)
+        throw new Error(`[pipework] startPolling: ${name} must be ${rule}, got ${String(value)}.`);
+}
+/**
+ * Calls `ask` after `firstMs`, then again after each answer, waiting longer each time (`backOff`, up to `longestMs`).
+ * One ask at a time: the next wait starts when the last ask settled. An ask returning `{ atLeastMs }` makes the next
+ * wait at least that long; the back-off carries on as if it had not. While the page is hidden nothing is asked.
+ * Returns `stop`, which is idempotent; an ask still in flight when it is called schedules nothing and reports no error.
+ */
+export function startPolling(ask, options = {}) {
+    const firstMs = options.firstMs ?? 3000;
+    const longestMs = options.longestMs ?? 10_000;
+    const backOff = options.backOff ?? 1.5;
+    check('firstMs', Number.isFinite(firstMs) && firstMs >= 0, 'a non-negative finite number of ms', firstMs);
+    check('longestMs', Number.isFinite(longestMs) && longestMs >= 0, 'a non-negative finite number of ms', longestMs);
+    check('backOff', Number.isFinite(backOff) && backOff >= 1, 'a finite number of at least 1', backOff);
+    check('firstMs', firstMs <= longestMs, `at most longestMs (${longestMs})`, firstMs);
+    const page = options.page ?? globalThis.document;
+    const watched = options.pauseWhenHidden !== false ? page : undefined;
+    let stopped = false;
+    let inFlight = false;
+    let timer;
+    let base = firstMs;
+    const nextWait = () => {
+        const wait = base;
+        base = Math.min(base * backOff, longestMs);
+        return wait;
+    };
+    const clear = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    };
+    const schedule = (ms) => {
+        clear();
+        timer = setTimeout(due, ms);
+    };
+    const due = () => {
+        timer = undefined;
+        if (stopped || watched?.hidden === true)
+            return;
+        void run();
+    };
+    const run = async () => {
+        inFlight = true;
+        let answer;
+        try {
+            answer = (await ask()) ?? undefined;
+        }
+        catch (error) {
+            if (!stopped)
+                options.onError?.(error);
+        }
+        inFlight = false;
+        if (stopped)
+            return;
+        const atLeast = answer !== undefined && Number.isFinite(answer.atLeastMs) ? answer.atLeastMs : 0;
+        schedule(Math.max(nextWait(), atLeast));
+    };
+    const onVisibility = () => {
+        if (stopped || watched === undefined || watched.hidden)
+            return;
+        clear();
+        base = firstMs;
+        if (!inFlight)
+            void run();
+    };
+    watched?.addEventListener('visibilitychange', onVisibility);
+    schedule(nextWait());
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clear();
+        watched?.removeEventListener('visibilitychange', onVisibility);
+    };
+}
+function fromHeader(value) {
+    if (value === null)
+        return undefined;
+    const text = value.trim();
+    if (/^\d+$/.test(text))
+        return Number(text) * 1000;
+    const at = Date.parse(text);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}
+/**
+ * For a 429 or 503: how long the server asked the client to wait, as `{ atLeastMs }` to return from an ask.
+ * Reads `Retry-After` (seconds or an HTTP date); when that is absent or unreadable (a cross-origin page cannot see it
+ * without CORS `exposedHeaders`), reads `error.retryAfterSeconds` from the JSON body. The response's own body stays unread.
+ * Any other status, or no wait found, gives undefined.
+ */
+export async function waitFromResponse(response) {
+    if (response.status !== 429 && response.status !== 503)
+        return undefined;
+    const fromHead = fromHeader(response.headers.get('retry-after'));
+    if (fromHead !== undefined)
+        return { atLeastMs: fromHead };
+    try {
+        const body = (await response.clone().json());
+        const seconds = body?.error?.retryAfterSeconds;
+        if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds >= 0)
+            return { atLeastMs: seconds * 1000 };
+    }
+    catch {
+        // no readable body
+    }
+    return undefined;
+}
+//# sourceMappingURL=poll.js.map

package/dist/client/poll.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.250.0",
+  "version": "0.251.0",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",