@protobase/client 0.23.3 → 0.23.4

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { FilterInput, ListParams, MapParams } from "./query-string.js";
 import { ClientOptions } from "./transport.js";
 import { UploadProgress } from "./upload-request.js";
+import { LiveHandlers } from "./live.js";
 import { Aggregate, AggregateParams, BatchOp, BatchResult, CommentPage, Facet, FormChallenge, FormProof, Histogram, HistoryPage, ListPage, MapResult, MentionableUser, MetaResult, PublicForm, RecordComment, RecordOf, ResourceRef, Series, SeriesParams, Stored } from "./types.js";
 import { KeyValue } from "@protobase/schema";
 //#region src/client.d.ts
@@ -93,6 +94,7 @@ export declare const createClient: (options?: ClientOptions) => {
   form: (name: string) => Promise<PublicForm>;
   formChallenge: (name: string) => Promise<FormChallenge>;
   submitForm: (name: string, values: Record<string, unknown>, proof: FormProof) => Promise<void>;
+  live: (handlers: LiveHandlers) => () => void;
 };
 export type Client = ReturnType<typeof createClient>;
 //#endregion

package/dist/client.js

@@ -2,6 +2,7 @@ import { filterText, labelEntries, listWire, photosWire, queryString } from "./q
 import { originOf, photosWithOrigin, withFileOrigin } from "./file-urls.js";
 import { createTransport } from "./transport.js";
 import { fetchWithProgress } from "./upload-request.js";
+import { followLive } from "./live.js";
 import { encodeKey } from "@protobase/schema/internal";
 //#region src/client.ts
 const nameOf = (resource) => typeof resource === "string" ? resource : resource.toModel().name;
@@ -404,6 +405,11 @@ const createClient = (options = {}) => {
 			system: true
 		});
 	};
+	/**
+	* Hears which records of the `.live()` resources the caller may read change, as they do, until the returned function
+	* is called (`GET /api/live`); it connects again by itself.
+	*/
+	const live = (handlers) => followLive(send, handlers);
 	return {
 		list,
 		search,
@@ -430,7 +436,8 @@ const createClient = (options = {}) => {
 		upload,
 		form,
 		formChallenge,
-		submitForm
+		submitForm,
+		live
 	};
 };
 //#endregion

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { FilterInput, ListParams, MapParams, filterText, listWire } from "./query-string.js";
 import { ClientOptions } from "./transport.js";
 import { UploadProgress } from "./upload-request.js";
+import { LiveChange, LiveHandlers } from "./live.js";
 import { Aggregate, AggregateGroup, AggregateParams, AggregateSplitTotal, BatchOp, BatchRef, BatchResult, CommentPage, CommentPerson, Facet, FormChallenge, FormProof, Histogram, HistogramBucket, HistoryChange, HistoryPage, ListPage, MapBounds, MapBucket, MapLayerModel, MapResult, MentionableUser, Meta, MetaResult, PluginRef, PublicForm, RecordComment, RecordOf, RecordPermissions, RecordPhotos, RelatedLabels, ResourcePermissions, ResourceRef, Series, SeriesParams, SeriesPoint, SourceRef, Stored, StoredFile, StoredFileVariant } from "./types.js";
 import { Client, InvokeOptions, UploadOptions, UploadResult, createClient } from "./client.js";
 import { ApiError, PreconditionFailedError, ProblemDetails, ProblemError, isApiError } from "./problem.js";
@@ -19,4 +20,4 @@ import { AuthSession, AuthSessionOptions, createAuthSession, tokenExpiry } from
 import { createStaticSession } from "./static-session.js";
 import { AssistantClient, AssistantClientOptions, AssistantConnection, createAssistantClient } from "./assistant.js";
 import { RuntimeClient, RuntimeClientOptions, RuntimeLastUpdate, RuntimePolicy, RuntimeStatus, RuntimeUpdateStage, createRuntimeClient } from "./runtime.js";
-export { type AccountSecurity, type AccountSignIn, type ActiveRole, type Aggregate, type AggregateGroup, type AggregateParams, type AggregateSplitTotal, ApiError, type AppUser, type AssistantClient, type AssistantClientOptions, type AssistantConnection, AuthError, type AuthSession, type AuthSessionOptions, type AuthUser, type AuthenticatorSetup, type BatchOp, type BatchRef, type BatchResult, type Client, type ClientOptions, type CommentPage, type CommentPerson, type CurrentOrganization, type Facet, type FilterInput, type FormChallenge, type FormProof, type Histogram, type HistogramBucket, type HistoryChange, type HistoryPage, type InvitationPreview, type InvitationSent, type InvokeOptions, type ListPage, type ListParams, type MapBounds, type MapBucket, type MapLayerModel, type MapParams, type MapResult, type MentionableUser, type Meta, type MetaResult, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationRole, type OrganizationsClient, type OrganizationsFound, type Passkey, type PlatformSignIn, type PluginRef, PreconditionFailedError, type ProblemDetails, type ProblemError, type PublicForm, type RecordComment, type RecordOf, type RecordPermissions, type RecordPhotos, type RelatedLabels, type RequiredSetup, type ResourcePermissions, type ResourceRef, type RoleLabel, type RoleOption, type RolesClient, type RuntimeClient, type RuntimeClientOptions, type RuntimeLastUpdate, type RuntimePolicy, type RuntimeStatus, type RuntimeUpdateStage, type SamlSignIn, type Series, type SeriesParams, type SeriesPoint, type SetupStatus, type SignInMethod, type SignInPolicy, type SignInPolicyClient, type SignInPolicyState, type SignInResult, type SignInRule, type SourceMeta, type SourceRef, type StaffAccessRule, type StaffSignIn, type StaffSignInClient, type Stored, type StoredFile, type StoredFileVariant, type TwoFactorMethod, type UploadOptions, type UploadProgress, type UploadResult, type UserInvitation, type UserInvitationSent, type UsersClient, type UsersFound, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, fileUrl, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };
+export { type AccountSecurity, type AccountSignIn, type ActiveRole, type Aggregate, type AggregateGroup, type AggregateParams, type AggregateSplitTotal, ApiError, type AppUser, type AssistantClient, type AssistantClientOptions, type AssistantConnection, AuthError, type AuthSession, type AuthSessionOptions, type AuthUser, type AuthenticatorSetup, type BatchOp, type BatchRef, type BatchResult, type Client, type ClientOptions, type CommentPage, type CommentPerson, type CurrentOrganization, type Facet, type FilterInput, type FormChallenge, type FormProof, type Histogram, type HistogramBucket, type HistoryChange, type HistoryPage, type InvitationPreview, type InvitationSent, type InvokeOptions, type ListPage, type ListParams, type LiveChange, type LiveHandlers, type MapBounds, type MapBucket, type MapLayerModel, type MapParams, type MapResult, type MentionableUser, type Meta, type MetaResult, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationRole, type OrganizationsClient, type OrganizationsFound, type Passkey, type PlatformSignIn, type PluginRef, PreconditionFailedError, type ProblemDetails, type ProblemError, type PublicForm, type RecordComment, type RecordOf, type RecordPermissions, type RecordPhotos, type RelatedLabels, type RequiredSetup, type ResourcePermissions, type ResourceRef, type RoleLabel, type RoleOption, type RolesClient, type RuntimeClient, type RuntimeClientOptions, type RuntimeLastUpdate, type RuntimePolicy, type RuntimeStatus, type RuntimeUpdateStage, type SamlSignIn, type Series, type SeriesParams, type SeriesPoint, type SetupStatus, type SignInMethod, type SignInPolicy, type SignInPolicyClient, type SignInPolicyState, type SignInResult, type SignInRule, type SourceMeta, type SourceRef, type StaffAccessRule, type StaffSignIn, type StaffSignInClient, type Stored, type StoredFile, type StoredFileVariant, type TwoFactorMethod, type UploadOptions, type UploadProgress, type UploadResult, type UserInvitation, type UserInvitationSent, type UsersClient, type UsersFound, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, fileUrl, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };

package/dist/live.d.ts

@@ -0,0 +1,16 @@
+//#region src/live.d.ts
+/** A record of a `.live()` resource that changed: its key, never its values. */
+export type LiveChange = {
+  resource: string;
+  key: string;
+  operation: 'create' | 'update' | 'delete' | 'undelete';
+};
+export type LiveHandlers = {
+  /** The records that changed, in commit order, of the live resources the caller may read. */
+  onChanges: (changes: LiveChange[]) => void;
+  /** Changes went by while the connection was down for longer than the server keeps them: read everything shown again. */
+  onResync: () => void;
+  /** The stream failed, with why, or ended (`undefined`); it is followed again after a pause. */
+  onRetry?: (error: unknown) => void;
+};
+//#endregion

package/dist/live.js

@@ -0,0 +1,50 @@
+import { queryString } from "./query-string.js";
+import { readEventStream } from "@protobase/schema/internal";
+//#region src/live.ts
+const backoff = (attempt) => Math.min(3e4, 1e3 * 2 ** attempt);
+const pause = (ms, signal) => new Promise((resolve) => {
+	const timer = setTimeout(resolve, ms);
+	signal.addEventListener("abort", () => {
+		clearTimeout(timer);
+		resolve();
+	}, { once: true });
+});
+/**
+* Follows `GET /api/live` until the returned function is called: a stream that ends or fails is followed again, after
+* a pause that grows with each failure, from the last event it had, so nothing in between is missed.
+*/
+const followLive = (send, handlers, retryDelay = backoff) => {
+	const controller = new AbortController();
+	const { signal } = controller;
+	let cursor;
+	let failures = 0;
+	const onEvent = (event) => {
+		failures = 0;
+		cursor = event.cursor;
+		if (event.type === "resync") handlers.onResync();
+		if (event.type === "changes") handlers.onChanges(event.changes);
+	};
+	const follow = async () => {
+		const response = await send({
+			method: "GET",
+			path: "/live",
+			query: queryString({ after: cursor }),
+			headers: { accept: "text/event-stream" },
+			system: true,
+			signal
+		});
+		if (!response.body) throw new Error("The server answered the live stream without a body");
+		await readEventStream(response.body, (data) => onEvent(JSON.parse(data)), signal);
+	};
+	(async () => {
+		while (!signal.aborted) {
+			const error = await follow().then(() => void 0, (reason) => reason);
+			if (signal.aborted) return;
+			handlers.onRetry?.(error);
+			await pause(retryDelay(failures++), signal);
+		}
+	})();
+	return () => controller.abort();
+};
+//#endregion
+export { followLive };

package/dist/routed-client.d.ts

@@ -2,8 +2,8 @@ import { Client } from "./client.js";
 //#region src/routed-client.d.ts
 /**
  * One client over the app's own API and the sources it draws resources from: a call about a resource goes to the API
- * that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta`, `invoke` and the
- * public forms go to the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
+ * that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta`, `invoke`, the
+ * public forms and `live` go to the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
  * refused before anything is sent.
  */
 export declare const routedClient: (own: Client, sourceOf: (resource: string) => Client | undefined) => Client;

package/dist/routed-client.js

@@ -2,8 +2,8 @@
 const nameOf = (resource) => typeof resource === "string" ? resource : resource.toModel().name;
 /**
 * One client over the app's own API and the sources it draws resources from: a call about a resource goes to the API
-* that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta`, `invoke` and the
-* public forms go to the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
+* that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta`, `invoke`, the
+* public forms and `live` go to the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
 * refused before anything is sent.
 */
 const routedClient = (own, sourceOf) => {
@@ -38,7 +38,8 @@ const routedClient = (own, sourceOf) => {
 		upload: (resource, field, file, options) => to(resource).upload(resource, field, file, options),
 		form: (name) => own.form(name),
 		formChallenge: (name) => own.formChallenge(name),
-		submitForm: (name, values, proof) => own.submitForm(name, values, proof)
+		submitForm: (name, values, proof) => own.submitForm(name, values, proof),
+		live: (handlers) => own.live(handlers)
 	};
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/client",
-  "version": "0.23.3",
+  "version": "0.23.4",
   "description": "Typed fetch client for the Protobase REST API.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.23.3",
-    "@protobase/schema": "0.23.3",
+    "@protobase/layout": "0.23.4",
+    "@protobase/schema": "0.23.4",
     "@simplewebauthn/browser": "^13.3.0",
     "better-auth": "^1.7.7"
   }