npm - @rebasepro/client - Versions diffs - 0.13.1-canary.gf57a27e → 0.14.0 - Mend

@rebasepro/client 0.13.1-canary.gf57a27e → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/dist/index.es.js +169 -11
package/dist/index.es.js.map +1 -1
package/dist/offline-connectivity.d.ts +12 -0
package/dist/offline-query.d.ts +41 -0
package/dist/query-contract.types.d.ts +61 -1
package/dist/sdk_query_builder.d.ts +2 -2
package/dist/websocket.d.ts +5 -3
package/package.json +4 -4
package/src/collection.ts +2 -2
package/src/index.ts +2 -2
package/src/offline-connectivity.test.ts +35 -1
package/src/offline-connectivity.ts +35 -3
package/src/offline-query.test.ts +88 -0
package/src/offline-query.ts +83 -0
package/src/offline.test.ts +66 -1
package/src/offline.ts +48 -6
package/src/query-contract.types.ts +93 -1
package/src/realtime-error-surfacing.test.ts +105 -0
package/src/sdk_query_builder.ts +2 -2
package/src/transport.ts +45 -2
package/src/websocket.ts +21 -3

package/dist/index.es.js CHANGED Viewed

@@ -177,6 +177,23 @@ function createTransport(config, environment) {
 			...init?.headers || {}
 		};
 	}
+	/**
+	* The refusal for a success status carrying a body this client cannot read.
+	*
+	* The first 120 characters go in the message because they identify the
+	* sender at a glance: `<!doctype html>` says "you are talking to a web
+	* server, not to this API" faster than any wording here could.
+	*
+	* One function for both the first attempt and the post-refresh retry — the
+	* retry is a second copy of this whole response-reading path, and copies
+	* are how one of them ends up fixed and the other not.
+	*/
+	function unreadableResponse(status, text) {
+		return new RebaseApiError$1(`The server answered ${status} with a body that is not JSON, so there is nothing to return. This usually means the request reached something other than the Rebase API — a single-page-app fallback serving index.html, or a proxy error page — so check the API URL configuration (e.g. VITE_API_URL). The body began: ${JSON.stringify(text.slice(0, 120))}`, {
+			status,
+			code: "INVALID_JSON_RESPONSE"
+		});
+	}
 	async function request(path, init) {
 		const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 		let activeToken = token;
@@ -194,9 +211,27 @@ function createTransport(config, environment) {
 		if (res.status === 204) return void 0;
 		const text = await res.text().catch(() => "");
 		let body = {};
+		/**
+		* Whether the body was there and could not be read as JSON.
+		*
+		* On an error status this does not matter — the status is the answer
+		* and the message falls back to `statusText`. On a *success* status it
+		* is the whole answer, and `{}` was being returned as though the server
+		* had sent it: `find()` answered `{}` instead of an array, `getOne()`
+		* an empty object, with nothing thrown.
+		*
+		* The case that produces it is not exotic. Point `VITE_API_URL` at the
+		* frontend's own host and `/api/data/posts` lands on the SPA fallback,
+		* which answers `200` with `index.html` — so the misconfiguration the
+		* 404 branch below spends four lines explaining reaches the caller, in
+		* its most common form, as an empty success.
+		*/
+		let unreadableBody = false;
 		if (text) try {
 			body = JSON.parse(text, rebaseReviver);
-		} catch (e) {}
+		} catch (e) {
+			unreadableBody = true;
+		}
 		const getErrorField = (obj, field) => {
 			const err = obj?.error;
 			if (err && typeof err === "object" && err !== null) return err[field];
@@ -216,9 +251,12 @@ function createTransport(config, environment) {
 				if (retryRes.status === 204) return void 0;
 				const retryText = await retryRes.text().catch(() => "");
 				let retryBody = {};
+				let retryUnreadable = false;
 				if (retryText) try {
 					retryBody = JSON.parse(retryText, rebaseReviver);
-				} catch (e) {}
+				} catch (e) {
+					retryUnreadable = true;
+				}
 				if (!retryRes.ok) {
 					let fallbackMessage = retryRes.statusText;
 					if (retryRes.status === 404 && !fallbackMessage) fallbackMessage = `Endpoint not found (${init?.method || "GET"} ${path}). This usually means the collection is not registered on the backend, or the frontend API URL configuration (e.g. VITE_API_URL) is missing or pointing to the wrong host.`;
@@ -228,6 +266,7 @@ function createTransport(config, environment) {
 						details: getErrorField(retryBody, "details")
 					});
 				}
+				if (retryUnreadable) throw unreadableResponse(retryRes.status, retryText);
 				return retryBody;
 			}
 		}
@@ -240,6 +279,7 @@ function createTransport(config, environment) {
 				details: getErrorField(body, "details")
 			});
 		}
+		if (unreadableBody) throw unreadableResponse(res.status, text);
 		return body;
 	}
 	return {
@@ -1849,9 +1889,11 @@ var CHANNEL_MESSAGE_TYPES = /* @__PURE__ */ new Set([
 *
 * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
 * manages this internally (exposed as `client.ws`, typed by the minimal
-* `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
-* package root only because the `@rebasepro/client-postgres` driver
-* instantiates it directly; its surface may change without a major bump.
+* `RebaseWebSocket` contract in `@rebasepro/types`). It stays exported from the
+* package root for the same reason it always was — a data-source driver may
+* instantiate it directly — but nothing in this repo does since
+* `@rebasepro/client-postgres` was removed; its surface may change without a
+* major bump.
 */
 var RebaseWebSocketClient = class {
 	websocketUrl;
@@ -2361,6 +2403,11 @@ var RebaseWebSocketClient = class {
 					callback.onError(new RebaseApiError$1(errorMessage, { code: errorCode }));
 				}
 			} else callback.onUpdate(message);
+			return;
+		}
+		if (type === "ERROR" || type === "error" || message.error) {
+			const { errorMessage, errorCode } = extractMessageError(message);
+			console.warn(`[Rebase] Realtime error from the server${errorCode ? ` (${errorCode})` : ""}: ${errorMessage}`);
 		}
 	}
 	async ensureAuthenticated(retryCount = 3) {
@@ -3473,11 +3520,29 @@ var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
 	503,
 	504
 ]);
+/**
+* The server holds this key for a request it has not answered yet.
+*
+* It is a 409 like a duplicate row is a 409, and nothing but the code separates
+* them — one means "your write is already there", the other means "your write
+* may not have happened at all, ask again".
+*/
+var IDEMPOTENCY_IN_PROGRESS = "IDEMPOTENCY_KEY_IN_PROGRESS";
+/**
+* Is the server still answering an earlier attempt of this same write?
+*
+* The only correct response is to ask again — which is exactly what the
+* server's own message says, and exactly what this SDK used not to do.
+*/
+function isIdempotencyInProgressError(error) {
+	return error instanceof RebaseApiError && error.status === 409 && error.code === IDEMPOTENCY_IN_PROGRESS;
+}
 /** Is this failure worth another attempt later? */
 function isRetryableError(error) {
 	if (isNetworkError(error)) return true;
-	if (error instanceof RebaseApiError) return error.status !== void 0 && RETRYABLE_STATUSES.has(error.status);
-	return false;
+	if (!(error instanceof RebaseApiError)) return false;
+	if (isIdempotencyInProgressError(error)) return true;
+	return error.status !== void 0 && RETRYABLE_STATUSES.has(error.status);
 }
 /**
 * Did this write fail because the row is already there?
@@ -3489,10 +3554,16 @@ function isRetryableError(error) {
 * The queue uses this to recognise its own earlier attempt. A create whose
 * response was lost is replayed, and for a row carrying an id the SDK generated
 * the server can only be rejecting it because the first attempt actually landed.
+*
+* Which is why the status alone cannot decide it: `IDEMPOTENCY_KEY_IN_PROGRESS`
+* is a 409 that means the opposite — the row may not exist at all. Read as a
+* duplicate, the queue looked for a row that was never written, found nothing,
+* concluded there was nothing left to do and deleted the write from the queue.
 */
 function isDuplicateKeyError(error) {
 	if (!(error instanceof RebaseApiError)) return false;
-	return error.code === "23505" || error.status === 409;
+	if (error.code === "23505") return true;
+	return error.status === 409 && !isIdempotencyInProgressError(error);
 }
 var ConnectivityMonitor = class {
 	state = "online";
@@ -4066,6 +4137,25 @@ function resolvePagination(params) {
 		offset
 	};
 }
+/** `<`, `<=`, `>`, `>=` — the operators whose answer depends on a collation. */
+var ORDERING_OPS = /* @__PURE__ */ new Set([
+	"<",
+	"<=",
+	">",
+	">="
+]);
+/** Does any condition in this `where` clause order its operands? */
+function whereOrders(where) {
+	if (!where) return false;
+	for (const condition of Object.values(where)) if ((isTuple(condition) ? [condition] : condition.filter(isTuple)).some(([op]) => ORDERING_OPS.has(op))) return true;
+	return false;
+}
+/** The same question, through an `and(...)`/`or(...)` tree. */
+function logicalOrders(condition, depth = 0) {
+	if (!condition || depth > 32) return false;
+	if ("type" in condition) return (condition.conditions ?? []).some((c) => logicalOrders(c, depth + 1));
+	return ORDERING_OPS.has(condition.operator);
+}
 /**
 * Can a locally evaluated answer to `params` be trusted to match the server's,
 * assuming the cache holds every row of the collection?
@@ -4073,12 +4163,67 @@ function resolvePagination(params) {
 * `include` pulls in rows from other collections that this evaluator never
 * sees, and `searchString` is only approximated — both make the local answer a
 * best effort rather than an equivalent one.
+*
+* **Ordering comparisons are refused, and that is the interesting one.**
+* `compareValues` falls back to an `Intl.Collator` for operands it cannot read
+* as numbers or instants. PostgreSQL orders text by the *database's* collation,
+* which is a property of the server this process has never been told: under the
+* C collation `'apple' < 'Banana'` is false, under `en_US.UTF-8` it is true,
+* and the collator says true. So `["<", "Banana"]` selects a different set here
+* than it does there — silently, and in whichever direction the deployment
+* happens to have been created.
+*
+* The refusal covers *every* ordering comparison rather than only the ones with
+* a string operand, because the operand type does not settle it: a numeric
+* bound against a text column (`["<", 10]` on a `varchar`) also reaches the
+* collator, and nothing in `params` says what the column holds. Conservative on
+* purpose — the cost is that a query combining an ordering filter with
+* *unsynced local writes* stops placing those writes optimistically, which is a
+* degraded answer rather than a wrong one. Claiming exactness we do not have is
+* the other way round.
+*
+* This says nothing about ordering *results*; that is a separate claim with a
+* separate answer, because a sort changes which rows come first and not which
+* rows match. See {@link isLocallySortable}.
 */
 function isExactlyEvaluable(params) {
 	if (!params) return true;
 	if (params.include && params.include.length > 0) return false;
 	if (params.searchString) return false;
 	if (params.vectorSearch) return false;
+	if (whereOrders(params.where)) return false;
+	if (logicalOrders(params.logical)) return false;
+	return true;
+}
+/**
+* Would sorting `rows` locally reproduce the order the server would have sent?
+*
+* Asked of the rows rather than of the query, because unlike a filter this one
+* *is* decidable from the data in hand: {@link compareValues} reaches the
+* collator only when it cannot read both operands as numbers, and `toComparable`
+* has already turned dates and relations into numbers and ids by then. If every
+* value on the sort column normalises to a number, the collator is unreachable
+* and the local order is the server's order.
+*
+* A text column is therefore refused — see {@link isExactlyEvaluable} for why
+* the two cannot be made to agree — and so is a column this page happens to see
+* only as strings, which is the same thing from here.
+*
+* Nulls are fine either way: they are ordered by an explicit rule (last
+* ascending, first descending) that matches Postgres and never reaches the
+* comparator.
+*/
+function isLocallySortable(rows, orderBy) {
+	if (!orderBy) return true;
+	const [field] = orderBy;
+	for (const row of rows) {
+		const value = toComparable(row[field]);
+		if (isNullish(value)) continue;
+		if (typeof value === "number" || typeof value === "boolean") continue;
+		if (typeof value === "bigint") continue;
+		if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) continue;
+		return false;
+	}
 	return true;
 }
 /** Run a full query — filter, sort, paginate — over a set of rows. */
@@ -4114,6 +4259,17 @@ function generateOfflineId() {
 	return `off-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 var MISSING = "\0missing";
+/**
+* Replays to spend on a mutation whose idempotency key the server is still
+* holding, when the app has not asked for more.
+*
+* Retries double from a second and cap at the sync interval, so the default
+* budget of five covers about half a minute — less than the lease a server
+* gives a claim nobody came back for. This many outlast it with room for a slow
+* batch, and the count is what stops a server that never releases the key from
+* blocking the queue behind it indefinitely.
+*/
+var IN_PROGRESS_MIN_RETRIES = 12;
 var OfflineManager = class {
 	store;
 	maxCachedQueries;
@@ -4803,7 +4959,8 @@ var OfflineManager = class {
 			rows.push(entry.row);
 			added++;
 		}
-		if (params?.orderBy) sortRows(rows, params.orderBy);
+		const orderIsLocal = isLocallySortable(rows, params?.orderBy);
+		if (params?.orderBy && orderIsLocal) sortRows(rows, params.orderBy);
 		return {
 			data: rows,
 			meta: {
@@ -4814,7 +4971,7 @@ var OfflineManager = class {
 			},
 			fromCache,
 			hasPendingWrites: rows.some((row) => this.hasPending(slug, row.id)),
-			partial: !exact
+			partial: !exact || !orderIsLocal
 		};
 	}
 	localFind(slug, params) {
@@ -5129,7 +5286,8 @@ var OfflineManager = class {
 						}
 						op.attempts = (op.attempts ?? 0) + 1;
 						op.lastError = error?.message ?? String(error);
-						if (isRetryableError(error) && op.attempts < this.maxRetries) {
+						const limit = isIdempotencyInProgressError(error) ? Math.max(this.maxRetries, IN_PROGRESS_MIN_RETRIES) : this.maxRetries;
+						if (isRetryableError(error) && op.attempts < limit) {
 							await this.store.enqueue(this.queueKey(op), op).catch(() => void 0);
 							this.connectivity.deferRetry();
 							this.patchStatus({ lastError: op.lastError });