@rig-ts/electric 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,203 @@
+import * as _$_tanstack_db0 from "@tanstack/db";
+import * as _$_tanstack_electric_db_collection0 from "@tanstack/electric-db-collection";
+import { Row, ShapeStreamOptions } from "@electric-sql/client";
+import { Runtime } from "@rig-ts/client";
+
+//#region src/params.d.ts
+/** Query params the sync protocol accepts alongside its own. */
+type ShapeParams = NonNullable<ShapeStreamOptions["params"]>;
+/**
+ * The TypeScript types a declared shape param can take.
+ *
+ * UUID, Date, Time and Timestamp are all carried as strings, matching what the
+ * generated params types declare and what the server parses off the query
+ * string.
+ */
+type ParamValue = string | number | boolean;
+/**
+ * Serializes a shape's declared params into the query string the generated
+ * server parses.
+ *
+ * `undefined` values are dropped rather than sent empty — that is what makes an
+ * optional param absent, since the server treats an empty value as unset and an
+ * absent one as not asked for.
+ */
+declare function serializeParams(params: Readonly<Record<string, ParamValue | undefined>>): ShapeParams;
+/**
+ * A stable key for a param set, sorted so two callers passing the same params in
+ * a different literal order share one collection.
+ *
+ * Built on {@link serializeParams} and `URLSearchParams` rather than on a hand
+ * rolled `join("&")`, for the reason a hand rolled one cannot be right: a value
+ * containing the separators is indistinguishable from more params. `{a: "b&c=d"}`
+ * and `{a: "b", c: "d"}` produced the identical key, so two collections over
+ * different params shared one instance — and the rows one of them was asking for
+ * were never the rows it got. Percent-encoding is what removes the ambiguity.
+ *
+ * The sort is `URLSearchParams.sort`, which orders by code unit rather than by
+ * locale. Only stability matters here — nobody reads this key — and a key that
+ * depends on the reader's locale is the weaker of the two.
+ */
+declare function paramsCacheKey(params: Readonly<Record<string, ParamValue | undefined>>): string;
+//#endregion
+//#region src/create-collection.d.ts
+/** What a generated stream factory passes down. */
+type RigCollectionArgs<TRow extends Row> = {
+  /**
+   * The client the stream authenticates and resolves its URL through. Taking
+   * the whole runtime rather than a base URL is what lets a `Session` refresh
+   * before a long poll inherits a token about to expire.
+   */
+  runtime: Runtime;
+  /**
+   * The shape's route, emitted verbatim from `ir.ElectricEndpoint` — for
+   * example `/api/v1/todo/_stream`. It is the full route including the API's
+   * base path, because that is what the document says it is; nothing here
+   * recomposes one.
+   */
+  path: string; /** The params the endpoint declares. Absent ones are dropped, not sent empty. */
+  params?: Readonly<Record<string, ParamValue | undefined>>; /** The primary key accessor. TanStack DB keys must be a string or a number. */
+  getKey: (row: TRow) => string | number;
+};
+/**
+ * Builds a read-only collection over one of a rig application's shape endpoints.
+ *
+ * **No mutation handlers.** Writes go through the API and the sync service
+ * delivers the resulting rows, so there is no txid handshake to perform here. A
+ * collection that could be written to would be a second way to change a row, and
+ * one that skips every rule the server applies.
+ *
+ * **No schema.** TanStack DB validates only on optimistic mutations, so a schema
+ * here would never run; the row types come from the generated API types, which
+ * are the ones the server sends.
+ *
+ * Sync does not start when this is called. It begins when the first live query
+ * subscribes and pauses when the last one unsubscribes, so an instance held
+ * across a navigation resumes rather than re-syncing — which is what
+ * {@link createCollectionCache} exists to make possible.
+ */
+declare function createRigCollection<TRow extends Row>(args: RigCollectionArgs<TRow>): _$_tanstack_db0.Collection<TRow, string | number, _$_tanstack_electric_db_collection0.ElectricCollectionUtils<TRow>, never, TRow> & _$_tanstack_db0.NonSingleResult;
+//#endregion
+//#region src/collection-cache.d.ts
+/** The slice of a collection's surface the cache needs to observe. */
+type CacheableCollection = {
+  on: (event: "status:change", callback: (payload: {
+    status: string;
+  }) => void) => () => void;
+};
+/**
+ * Wraps a collection factory so each distinct client and param set maps to one
+ * long-lived instance.
+ *
+ * Collections are stateful and each one opens a stream, so an instance rebuilt
+ * per render or per navigation loses everything the library gives a retained
+ * one: data held for its collection time, sync that pauses at zero subscribers
+ * and resumes on the next one, and resume-from-offset instead of a full
+ * re-sync. Returning the same instance is what makes those pay off — and it is
+ * what lets a caller invoke a generated factory during render without a
+ * load-bearing `useMemo`.
+ *
+ * Entries remove themselves once their collection reaches `cleaned-up`, so the
+ * map is bounded by what is currently live rather than by everything ever asked
+ * for. There is no eviction policy to tune.
+ *
+ * On the server every call builds a fresh instance. The map would otherwise be
+ * module-global and leak one request's collections into the next, and nothing
+ * server-side should be syncing anyway.
+ *
+ * Two things the key deliberately leaves out. The **path** is not in it, because
+ * each generated factory wraps its own call to this and so has a map of its own
+ * — a caller wrapping two different routes in one cache would collide, which is
+ * why the generator does not. And the **credential** is not in it: a client that
+ * switches to a different tenant on the same origin keeps the collection it had.
+ * The rows it holds were scoped to the old session, so switching tenant should
+ * discard the collection rather than expect this to notice.
+ */
+declare function createCollectionCache<TParams extends Readonly<Record<string, ParamValue | undefined>>, TCollection extends CacheableCollection>(build: (runtime: Runtime, params: TParams) => TCollection): (runtime: Runtime, params: TParams) => TCollection;
+//#endregion
+//#region src/fetch-client.d.ts
+/**
+ * The fetch every stream goes out through.
+ *
+ * Two things it does that a bare `fetch` would not.
+ *
+ * **The credential.** rig authenticates with `Authorization: Bearer`, so a shape
+ * request carries the same credential every other call does — and a `Session`
+ * gets to refresh ahead of an expiry before a long poll inherits a token that
+ * will die halfway through it. This is the whole reason a collection takes a
+ * `Runtime` rather than a base URL.
+ *
+ * **`cache: "no-store"`.** Without it the browser serves a stale long-poll
+ * response back, and the subscription stops advancing while appearing to work.
+ *
+ * A cross-origin deployment pays for the header: `Authorization` is not
+ * CORS-safelisted, so the shape GET becomes a preflighted request, and whatever
+ * sits in front has to allow it *and* expose `electric-handle`,
+ * `electric-offset`, `electric-schema` and `electric-cursor` — the cursor the
+ * client resumes from. Same-origin, which is what rig serves by default, needs
+ * none of that.
+ */
+declare function rigFetchClient(runtime: Runtime): typeof fetch;
+//#endregion
+//#region src/on-error.d.ts
+type ErrorHandler = NonNullable<ShapeStreamOptions["onError"]>;
+/**
+ * Routes stream failures back into the client's own auth handling.
+ *
+ * The sync client has already exhausted its own retries for 5xx, network errors
+ * and 429 by the time this runs, so what reaches here is a failure it will not
+ * retry on its own. Returning an object retries with backoff; returning
+ * `undefined` stops the stream for good.
+ *
+ * A 401 asks the credential to refresh — once, and only a credential that can do
+ * something about it. This is the counterpart of what the REST path does on a
+ * 401, and it has to happen here because a long poll cannot be re-sent by the
+ * caller: an expired session mid-stream otherwise stalls silently, polling into
+ * a session that is not coming back.
+ *
+ * Any other 4xx is a decision the server already made, and retrying cannot
+ * change it. A shape refused for the caller's tenant is refused.
+ */
+declare function streamErrorHandler(runtime: Runtime): ErrorHandler;
+//#endregion
+//#region src/parsers.d.ts
+type Parser = NonNullable<ShapeStreamOptions["parser"]>;
+/**
+ * Wire-format corrections applied to every stream.
+ *
+ * The rule they all serve: a column reaching the client over REST and the same
+ * column reaching it over a stream must decode to the same value. One row
+ * arriving two ways and disagreeing with itself is the failure mode a generated
+ * client exists to prevent, and it is the one the sync protocol makes easy —
+ * REST answers with what Go's `encoding/json` wrote, and a stream answers with
+ * what Postgres printed.
+ *
+ * `date` and `time` deliberately have no entry: Postgres already writes them as
+ * `YYYY-MM-DD` and `HH:MM:SS`, which is what the REST path sends too. `numeric`
+ * likewise stays a string, because that is the only form that keeps its
+ * precision.
+ */
+declare const rigParsers: Parser;
+//#endregion
+//#region src/shape-url.d.ts
+/**
+ * The address one stream subscribes to.
+ *
+ * It exists because the sync client resolves nothing: it hands its `url` to
+ * `new URL()` with no base. So the relative origin `@rig-ts/client` documents as
+ * the ordinary same-origin case — `baseUrl: ""`, resolved against the page —
+ * arrives there as `/api/v1/todo/_stream` and throws `Invalid URL`. And because
+ * a TypeError is not a `FetchError`, the error handler reads it as a failure
+ * worth another go and the stream retries the same unusable address with
+ * backoff, silently, rather than reporting anything. Resolving it here is what
+ * makes the documented default work for a stream as well as for a REST call,
+ * where `fetch` does this much itself.
+ *
+ * Off a browser there is no page to resolve against, so a relative origin is
+ * left as it is. Nothing should be syncing during a server render, and a stream
+ * that starts anyway should fail naming the origin it was not given rather than
+ * one this invented for it.
+ */
+declare function shapeUrl(origin: string, path: string): string;
+//#endregion
+export { type ParamValue, type RigCollectionArgs, type ShapeParams, createCollectionCache, createRigCollection, paramsCacheKey, rigFetchClient, rigParsers, serializeParams, shapeUrl, streamErrorHandler };

package/dist/index.mjs

@@ -0,0 +1,273 @@
+import { createCollection } from "@tanstack/db";
+import { electricCollectionOptions } from "@tanstack/electric-db-collection";
+import { FetchError } from "@electric-sql/client";
+import { isReauthorizer } from "@rig-ts/client";
+//#region src/fetch-client.ts
+/**
+* The fetch every stream goes out through.
+*
+* Two things it does that a bare `fetch` would not.
+*
+* **The credential.** rig authenticates with `Authorization: Bearer`, so a shape
+* request carries the same credential every other call does — and a `Session`
+* gets to refresh ahead of an expiry before a long poll inherits a token that
+* will die halfway through it. This is the whole reason a collection takes a
+* `Runtime` rather than a base URL.
+*
+* **`cache: "no-store"`.** Without it the browser serves a stale long-poll
+* response back, and the subscription stops advancing while appearing to work.
+*
+* A cross-origin deployment pays for the header: `Authorization` is not
+* CORS-safelisted, so the shape GET becomes a preflighted request, and whatever
+* sits in front has to allow it *and* expose `electric-handle`,
+* `electric-offset`, `electric-schema` and `electric-cursor` — the cursor the
+* client resumes from. Same-origin, which is what rig serves by default, needs
+* none of that.
+*/
+function rigFetchClient(runtime) {
+	return async (input, init) => {
+		const headers = new Headers(init?.headers);
+		await runtime.getCredential()?.apply(headers);
+		return await runtime.fetch(input, {
+			...init,
+			headers,
+			cache: "no-store"
+		});
+	};
+}
+//#endregion
+//#region src/on-error.ts
+/**
+* Routes stream failures back into the client's own auth handling.
+*
+* The sync client has already exhausted its own retries for 5xx, network errors
+* and 429 by the time this runs, so what reaches here is a failure it will not
+* retry on its own. Returning an object retries with backoff; returning
+* `undefined` stops the stream for good.
+*
+* A 401 asks the credential to refresh — once, and only a credential that can do
+* something about it. This is the counterpart of what the REST path does on a
+* 401, and it has to happen here because a long poll cannot be re-sent by the
+* caller: an expired session mid-stream otherwise stalls silently, polling into
+* a session that is not coming back.
+*
+* Any other 4xx is a decision the server already made, and retrying cannot
+* change it. A shape refused for the caller's tenant is refused.
+*/
+function streamErrorHandler(runtime) {
+	let refreshed = false;
+	return async (error) => {
+		if (typeof window === "undefined") return void 0;
+		if (!(error instanceof FetchError)) return {};
+		if (error.status === 401 && !refreshed) {
+			refreshed = true;
+			const credential = runtime.getCredential();
+			if (isReauthorizer(credential) && await credential.reauthorize()) return {};
+			return;
+		}
+		if (error.status >= 400 && error.status < 500) return void 0;
+		return {};
+	};
+}
+//#endregion
+//#region src/params.ts
+/**
+* Serializes a shape's declared params into the query string the generated
+* server parses.
+*
+* `undefined` values are dropped rather than sent empty — that is what makes an
+* optional param absent, since the server treats an empty value as unset and an
+* absent one as not asked for.
+*/
+function serializeParams(params) {
+	const out = {};
+	for (const [name, value] of Object.entries(params)) {
+		if (value === void 0) continue;
+		out[name] = String(value);
+	}
+	return out;
+}
+/**
+* A stable key for a param set, sorted so two callers passing the same params in
+* a different literal order share one collection.
+*
+* Built on {@link serializeParams} and `URLSearchParams` rather than on a hand
+* rolled `join("&")`, for the reason a hand rolled one cannot be right: a value
+* containing the separators is indistinguishable from more params. `{a: "b&c=d"}`
+* and `{a: "b", c: "d"}` produced the identical key, so two collections over
+* different params shared one instance — and the rows one of them was asking for
+* were never the rows it got. Percent-encoding is what removes the ambiguity.
+*
+* The sort is `URLSearchParams.sort`, which orders by code unit rather than by
+* locale. Only stability matters here — nobody reads this key — and a key that
+* depends on the reader's locale is the weaker of the two.
+*/
+function paramsCacheKey(params) {
+	const q = new URLSearchParams(Object.entries(serializeParams(params)).map(([name, value]) => [name, String(value)]));
+	q.sort();
+	return q.toString();
+}
+//#endregion
+//#region src/parsers.ts
+/**
+* Wire-format corrections applied to every stream.
+*
+* The rule they all serve: a column reaching the client over REST and the same
+* column reaching it over a stream must decode to the same value. One row
+* arriving two ways and disagreeing with itself is the failure mode a generated
+* client exists to prevent, and it is the one the sync protocol makes easy —
+* REST answers with what Go's `encoding/json` wrote, and a stream answers with
+* what Postgres printed.
+*
+* `date` and `time` deliberately have no entry: Postgres already writes them as
+* `YYYY-MM-DD` and `HH:MM:SS`, which is what the REST path sends too. `numeric`
+* likewise stays a string, because that is the only form that keeps its
+* precision.
+*/
+const rigParsers = {
+	int8: parseInt8,
+	timestamptz: toRFC3339,
+	timestamp: toRFC3339
+};
+/**
+* Converts a Postgres timestamp to the RFC 3339 the REST path sends.
+*
+* Two corrections, and both matter. Postgres separates the date and the time
+* with a space, which no ISO parser accepts. And it writes a zone offset as
+* `+00` where RFC 3339 wants `Z` or `+00:00` — the shorter form parses nowhere
+* reliably, and `Date.parse` reading it as local time would shift the value by
+* the viewer's offset without failing.
+*
+* A `timestamp` — the wall-clock type, with no zone at all — is given `Z`. That
+* asserts the column is UTC, which is the same assertion the REST path already
+* makes: pgx reads a zone-less timestamp into a `time.Time` in UTC, and Go
+* marshals that with the suffix. rig's own columns are `timestamptz` by
+* convention, so this covers a hand-written column rather than anything rig
+* generates.
+*/
+function toRFC3339(value) {
+	const isoish = value.replace(" ", "T");
+	const shortOffset = /([+-]\d{2})$/.exec(isoish);
+	if (shortOffset !== null) return (shortOffset[1] ?? "") === "+00" ? `${isoish.slice(0, -3)}Z` : `${isoish}:00`;
+	if (/([+-]\d{2}:\d{2}|Z)$/.test(isoish)) return isoish;
+	return `${isoish}Z`;
+}
+/**
+* Converts an `int8` to the `number` the generated row types declare.
+*
+* Electric's default parser answers with a BigInt, which throws the moment it
+* meets a number in arithmetic — and the row types say `number`, because that is
+* what `JSON.parse` produces on the REST path.
+*
+* Warns rather than throws above the safe-integer range: the REST path loses the
+* same precision silently, so failing here would kill a stream over data the
+* rest of the application accepts. The warning makes the loss visible instead.
+*/
+function parseInt8(value) {
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed)) console.warn(`[rig] int8 value ${value} is outside the safe integer range and lost precision`);
+	return parsed;
+}
+//#endregion
+//#region src/shape-url.ts
+/**
+* The address one stream subscribes to.
+*
+* It exists because the sync client resolves nothing: it hands its `url` to
+* `new URL()` with no base. So the relative origin `@rig-ts/client` documents as
+* the ordinary same-origin case — `baseUrl: ""`, resolved against the page —
+* arrives there as `/api/v1/todo/_stream` and throws `Invalid URL`. And because
+* a TypeError is not a `FetchError`, the error handler reads it as a failure
+* worth another go and the stream retries the same unusable address with
+* backoff, silently, rather than reporting anything. Resolving it here is what
+* makes the documented default work for a stream as well as for a REST call,
+* where `fetch` does this much itself.
+*
+* Off a browser there is no page to resolve against, so a relative origin is
+* left as it is. Nothing should be syncing during a server render, and a stream
+* that starts anyway should fail naming the origin it was not given rather than
+* one this invented for it.
+*/
+function shapeUrl(origin, path) {
+	const url = `${origin}${path}`;
+	if (typeof window === "undefined") return url;
+	return new URL(url, window.location.href).toString();
+}
+//#endregion
+//#region src/create-collection.ts
+/**
+* Builds a read-only collection over one of a rig application's shape endpoints.
+*
+* **No mutation handlers.** Writes go through the API and the sync service
+* delivers the resulting rows, so there is no txid handshake to perform here. A
+* collection that could be written to would be a second way to change a row, and
+* one that skips every rule the server applies.
+*
+* **No schema.** TanStack DB validates only on optimistic mutations, so a schema
+* here would never run; the row types come from the generated API types, which
+* are the ones the server sends.
+*
+* Sync does not start when this is called. It begins when the first live query
+* subscribes and pauses when the last one unsubscribes, so an instance held
+* across a navigation resumes rather than re-syncing — which is what
+* {@link createCollectionCache} exists to make possible.
+*/
+function createRigCollection(args) {
+	return createCollection(electricCollectionOptions({
+		shapeOptions: {
+			url: shapeUrl(args.runtime.origin, args.path),
+			params: serializeParams(args.params ?? {}),
+			parser: rigParsers,
+			fetchClient: rigFetchClient(args.runtime),
+			onError: streamErrorHandler(args.runtime)
+		},
+		getKey: args.getKey
+	}));
+}
+//#endregion
+//#region src/collection-cache.ts
+/**
+* Wraps a collection factory so each distinct client and param set maps to one
+* long-lived instance.
+*
+* Collections are stateful and each one opens a stream, so an instance rebuilt
+* per render or per navigation loses everything the library gives a retained
+* one: data held for its collection time, sync that pauses at zero subscribers
+* and resumes on the next one, and resume-from-offset instead of a full
+* re-sync. Returning the same instance is what makes those pay off — and it is
+* what lets a caller invoke a generated factory during render without a
+* load-bearing `useMemo`.
+*
+* Entries remove themselves once their collection reaches `cleaned-up`, so the
+* map is bounded by what is currently live rather than by everything ever asked
+* for. There is no eviction policy to tune.
+*
+* On the server every call builds a fresh instance. The map would otherwise be
+* module-global and leak one request's collections into the next, and nothing
+* server-side should be syncing anyway.
+*
+* Two things the key deliberately leaves out. The **path** is not in it, because
+* each generated factory wraps its own call to this and so has a map of its own
+* — a caller wrapping two different routes in one cache would collide, which is
+* why the generator does not. And the **credential** is not in it: a client that
+* switches to a different tenant on the same origin keeps the collection it had.
+* The rows it holds were scoped to the old session, so switching tenant should
+* discard the collection rather than expect this to notice.
+*/
+function createCollectionCache(build) {
+	const collections = /* @__PURE__ */ new Map();
+	return (runtime, params) => {
+		if (typeof window === "undefined") return build(runtime, params);
+		const key = `${runtime.origin}|${paramsCacheKey(params)}`;
+		const cached = collections.get(key);
+		if (cached !== void 0) return cached;
+		const collection = build(runtime, params);
+		collection.on("status:change", ({ status }) => {
+			if (status === "cleaned-up") collections.delete(key);
+		});
+		collections.set(key, collection);
+		return collection;
+	};
+}
+//#endregion
+export { createCollectionCache, createRigCollection, paramsCacheKey, rigFetchClient, rigParsers, serializeParams, shapeUrl, streamErrorHandler };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@rig-ts/electric",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Live-sync collections over a rig application's shape endpoints",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@electric-sql/client": "1.5.24",
+    "@tanstack/db": "0.6.17",
+    "@tanstack/electric-db-collection": "0.3.15"
+  },
+  "peerDependencies": {
+    "@rig-ts/client": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "0.21.10",
+    "typescript": "5.9.3",
+    "@rig-ts/client": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simonjanss/rig.git",
+    "directory": "ts/packages/electric"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}