@isomorph.ai/app-sdk 1.32.0 → 1.33.0

package/README.md

@@ -473,6 +473,32 @@ Without `onProgress` the call is unchanged and `ctx.progress` does nothing. At
 most 256 steps of up to 1 KiB each reach the page; further steps are dropped.
 The action still has the 300 s action budget. (Unreleased)
 
+## Watching a query: `data.watch`
+
+Progress, status and export screens re-read one query on a timer:
+
+```ts
+const stop = isomorph.data.watch(
+  () => isomorph.data.from('imports').select('*').eq('id', importId).single(),
+  ({ data }) => setImport(data),
+  { every: 3000, maxEvery: 15000 },   // the defaults
+);
+// on unmount
+stop();
+```
+
+`build()` runs at once and then every `every` ms (3 s). While the tab is
+hidden no read is made (where there is no `document`, as in Node, nothing is
+skipped). While the answer is unchanged the interval doubles up to `maxEvery`
+(15 s) and goes back to `every` on the first change; every result, changed or
+not, reaches `onResult`. A read that fails (a 401, the network) reaches it
+too, as `{ data: null, error }` with the error `await`ing the query would
+have thrown, and the timer keeps running. There is no new transport or route: each tick is an ordinary
+`QueryBuilder.execute()`, so it counts as app activity and is billed and
+authorized like any read. Watch the job row, not the data table. Use
+`realtime.channel` only when several people edit the same rows and sub-second
+updates matter. (1.32.0)
+
 ## Running on Lambda
 
 On a serverless cell Harbour runs an app's server code as Lambda functions, from a `runtime.zip` Kit Build makes; nothing in the app changes. The Web Function starts `dist/lambda-entry.js` (the zip's `index.js` is `import "@isomorph.ai/app-sdk/dist/lambda-entry.js"`), which serves actions on the port in `AWS_LAMBDA_HTTP_ENDPOINT` and stops on SIGTERM. The Event Function's handler is `node_modules/@isomorph.ai/app-sdk/dist/lambda-events-entry.handler`: `{"job": "<name>"}` runs that job once, as `--run-job <name>` does, and SQS records work queued runs until none are left.

package/dist/index.d.ts

@@ -39,6 +39,15 @@ export interface IsomorphResult<T> {
     data: T;
     count?: number;
 }
+/** `data.watch` timing: `every` ms between reads (default 3000), backing off to `maxEvery` (default 15000) while the answer does not change. */
+export interface WatchOptions {
+    every?: number;
+    maxEvery?: number;
+}
+/** What `data.watch` delivers: the read's result, or `{ data: null, error }` when the read failed (the error `await`ing the query would have thrown). */
+export type WatchResult = IsomorphResult<any> & {
+    error?: Error;
+};
 /** How Slack renders a message's `text`: plain text, or Slack mrkdwn (`*bold*`, `<url|label>`, `<@U123>`); plain when absent. */
 export type SlackTextFormat = 'plain' | 'mrkdwn';
 /**
@@ -1895,6 +1904,7 @@ export declare function createClient(options?: ClientOptions): {
     data: {
         from: <T = Record<string, unknown>>(table: string) => QueryBuilder<T, T[]>;
         rpc: <T = unknown>(name: string, args?: Record<string, unknown>) => Promise<T>;
+        watch: <T = Record<string, unknown>>(build: () => QueryBuilder<T, any>, onResult: (result: WatchResult) => void, options?: WatchOptions) => (() => void);
     };
     files: {
         createUpload: (input: {

package/dist/index.js

@@ -707,6 +707,45 @@ export function createClient(options = {}) {
         data: {
             from: (table) => new QueryBuilder(transport, table),
             rpc: (name, args = {}) => transport.json(`/_harbour/data/rpc/${encodeURIComponent(name)}`, { method: 'POST', body: JSON.stringify(args) }),
+            // A query on a timer: QueryBuilder.execute() now and every `every` ms,
+            // no read while the tab is hidden, the interval doubling up to
+            // `maxEvery` while the answer is unchanged. No new transport or route;
+            // each read is an ordinary read (it counts as app activity), so watch
+            // the job row, not the data table. A failed read is delivered as
+            // { data: null, error } and the timer keeps going.
+            watch: (build, onResult, options = {}) => {
+                const every = options.every ?? 3_000;
+                const maxEvery = options.maxEvery ?? 15_000;
+                let delay = every;
+                let previous;
+                let stopped = false;
+                let timer;
+                const schedule = () => { if (!stopped)
+                    timer = setTimer(tick, delay); };
+                const tick = async () => {
+                    if (typeof document !== 'undefined' && document.hidden) {
+                        schedule();
+                        return;
+                    }
+                    let result;
+                    try {
+                        result = await build().execute();
+                    }
+                    catch (error) {
+                        result = { data: null, error: error instanceof Error ? error : new Error(String(error)) };
+                    }
+                    if (stopped)
+                        return;
+                    const json = JSON.stringify({ ...result, error: result.error?.message });
+                    delay = json === previous ? Math.min(delay * 2, maxEvery) : every;
+                    previous = json;
+                    onResult(result);
+                    schedule();
+                };
+                void tick();
+                return () => { stopped = true; if (timer !== undefined)
+                    clearTimer(timer); };
+            },
         },
         files: {
             createUpload: (input) => transport.json('/_harbour/files/uploads', { method: 'POST', body: JSON.stringify(input) }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "type": "module",
   "repository": {
     "type": "git",