@rebasepro/client 0.19.1 → 0.19.2-canary.g09316f6

package/dist/index.es.js

@@ -1,5 +1,5 @@
-import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, RebaseClientError as RebaseClientError$1, SCHEMA_VERSION_HEADER, Vector, isPublicStoragePath, isUnsupported, parseRelationAggregateSort, sortKeyToString, toCanonicalOp, unsupportedMethod } from "@rebasepro/types";
-import { COMPOSITE_ID_SEPARATOR, QueryBuilder, RebasePaginationError, and, buildCompositeId, collectAllPages, cond, normalizeOrderBy, or, paginateFind, resolveFindWindow, serializeFilter, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
+import { DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, GeoPoint, PUBLIC_STORAGE_PREFIX, RebaseApiError, RebaseApiError as RebaseApiError$1, RebaseClientError, RebaseClientError as RebaseClientError$1, SCHEMA_VERSION_HEADER, Vector, hasFieldOperation, isPublicStoragePath, isUnsupported, parseRelationAggregateSort, sortKeyToString, toCanonicalOp, unsupportedMethod } from "@rebasepro/types";
+import { COMPOSITE_ID_SEPARATOR, QueryBuilder, RebasePaginationError, and, buildCompositeId, collectAllPages, cond, mergeIncludeSpecs, normalizeOrderBy, not, or, paginateFind, resolveFindWindow, serializeFilter, serializeInclude, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
 import { toSnakeCase } from "@rebasepro/utils";
 //#region src/reviver.ts
 function rebaseReviver(_key, value) {
@@ -93,6 +93,7 @@ function buildQueryString(params) {
 	if (params.limit != null) parts.push(`limit=${params.limit}`);
 	if (params.offset != null) parts.push(`offset=${params.offset}`);
 	if (params.page != null) parts.push(`page=${params.page}`);
+	if (params.after) parts.push(`after=${encodeURIComponent(params.after)}`);
 	if (params.orderBy) {
 		const wire = serializeOrderBy(params.orderBy);
 		if (wire) parts.push(`orderBy=${encodeURIComponent(wire)}`);
@@ -108,7 +109,10 @@ function buildQueryString(params) {
 		if (vs.distance) parts.push(`vector_distance=${encodeURIComponent(vs.distance)}`);
 		if (vs.threshold !== void 0) parts.push(`vector_threshold=${encodeURIComponent(String(vs.threshold))}`);
 	}
-	if (params.include && params.include.length > 0) parts.push(`include=${encodeURIComponent(params.include.join(","))}`);
+	const include = serializeInclude(params.include);
+	if (include) parts.push(`include=${encodeURIComponent(include)}`);
+	if (params.fields && params.fields.length > 0) parts.push(`fields=${encodeURIComponent(params.fields.join(","))}`);
+	if (params.distinct) parts.push("distinct=true");
 	if (params.logical) {
 		const root = params.logical;
 		const serialized = (root.conditions ?? []).map(serializeLogicalCondition).join(",");
@@ -123,6 +127,39 @@ function buildQueryString(params) {
 	return parts.length > 0 ? "?" + parts.join("&") : "";
 }
 /**
+* The query string for `GET /<collection>/aggregate`.
+*
+* `?select=sum(total),count()` is SQL's spelling, because whoever writes an
+* aggregate is thinking in SQL and any other spelling has to be learned first —
+* and because it is what the route already parses. The filters are serialised
+* by exactly the same code a `find()` uses, so "revenue by status, this month"
+* narrows the same rows whichever call is asking.
+*
+* `orderBy`, `include` and the page are deliberately not here: an aggregate has
+* no rows to sort, no relations to load and no page to continue. `limit` is,
+* and bounds the number of *groups*.
+*/
+function buildAggregateQueryString(params) {
+	const parts = [];
+	const select = params.select.map((entry) => `${entry.fn}(${entry.field ?? ""})`).join(",");
+	parts.push(`select=${encodeURIComponent(select)}`);
+	if (params.groupBy && params.groupBy.length > 0) parts.push(`groupBy=${encodeURIComponent(params.groupBy.join(","))}`);
+	if (params.limit != null) parts.push(`limit=${params.limit}`);
+	if (params.searchString) parts.push(`searchString=${encodeURIComponent(params.searchString)}`);
+	if (params.logical) {
+		const root = params.logical;
+		const serialized = (root.conditions ?? []).map(serializeLogicalCondition).join(",");
+		parts.push(`${root.type}=${encodeURIComponent(`(${serialized})`)}`);
+	}
+	if (params.where) {
+		assertNoUndefinedFilterValues(params.where);
+		const serialized = serializeFilter(params.where);
+		for (const [field, value] of Object.entries(serialized)) if (Array.isArray(value)) for (const v of value) parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(v)}`);
+		else parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(value)}`);
+	}
+	return "?" + parts.join("&");
+}
+/**
 * The base every request and every caller-built URL resolves against.
 *
 * `baseUrl` is optional because the common production shape is a Rebase
@@ -284,7 +321,7 @@ function createTransport(config, environment) {
 			})()
 		});
 	}
-	async function request(path, init) {
+	async function request(path, init, meta) {
 		const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 		let activeToken = token;
 		if (tokenGetter) try {
@@ -298,6 +335,10 @@ function createTransport(config, environment) {
 			...init,
 			headers
 		});
+		if (meta) {
+			meta.status = res.status;
+			meta.etag = res.headers?.get?.("ETag") ?? void 0;
+		}
 		if (res.status === 204) return void 0;
 		const text = await res.text().catch(() => "");
 		let body = {};
@@ -334,6 +375,10 @@ function createTransport(config, environment) {
 					...init,
 					headers: retryHeaders
 				});
+				if (meta) {
+					meta.status = retryRes.status;
+					meta.etag = retryRes.headers?.get?.("ETag") ?? void 0;
+				}
 				if (retryRes.status === 204) return void 0;
 				const retryText = await retryRes.text().catch(() => "");
 				let retryBody = {};
@@ -1543,9 +1588,14 @@ var SDKQueryBuilder = class {
 	* `.orderBy("roles").orderBy("created_at", "desc")` sorts by role and
 	* shows the newest first within each one.
 	*/
-	orderBy(column, direction = "asc") {
+	orderBy(column, direction = "asc", nulls) {
 		const existing = normalizeOrderBy(this.params.orderBy) ?? [];
-		this.params.orderBy = [...existing, [sortKeyToString(column), direction]];
+		const key = sortKeyToString(column);
+		this.params.orderBy = [...existing, nulls ? [
+			key,
+			direction,
+			nulls
+		] : [key, direction]];
 		return this;
 	}
 	/**
@@ -1616,15 +1666,74 @@ var SDKQueryBuilder = class {
 		return this;
 	}
 	/**
-	* Include related entities in the response.
-	* Relations will be populated with full data instead of just IDs.
+	* Load related rows into the response, in place of their foreign keys.
 	*
-	* @param relations - Relation names to include, or "*" for all.
-	* @example
-	* client.data.posts.include("tags", "author").find()
+	* Three spellings, all the same request:
+	*
+	* ```ts
+	* client.data.posts.include("tags", "author")            // names
+	* client.data.posts.include("comments.author")           // a dotted path
+	* client.data.posts.include({                            // parametrised
+	*     comments: {
+	*         limit: 5,
+	*         where: { published: ["==", true] },
+	*         orderBy: ["created_at", "desc"],
+	*         include: { author: true }
+	*     }
+	* })
+	* ```
+	*
+	* Up to three hops deep, and `"*"` still loads every relation one hop
+	* deep. A name that is not a relation of the collection is a 400
+	* `UNKNOWN_RELATION` — it used to be ignored, which answers 200 with the
+	* field missing and reads exactly like a row that has no related row.
+	*
+	* Repeated calls **merge**: `.include("author").include("tags")` asks for
+	* both. Assigning here — which is what it used to do — meant the second
+	* call silently discarded the first.
 	*/
 	include(...relations) {
-		this.params.include = relations;
+		this.params.include = mergeIncludeSpecs(this.params.include, relations);
+		return this;
+	}
+	/**
+	* Return only these columns.
+	*
+	* A projection at the database, not a trim of the response: a query that
+	* needs two fields of a wide row reads two columns. The primary key always
+	* comes back regardless — a row that cannot be addressed cannot be
+	* updated, deleted or paged past — and `excludeFromApi` columns stay
+	* hidden whether or not they are named.
+	*/
+	fields(...columns) {
+		this.params.fields = [...this.params.fields ?? [], ...columns];
+		return this;
+	}
+	/**
+	* Collapse rows that are identical over the columns being returned.
+	*
+	* Only meaningful alongside {@link fields}: the primary key is always in
+	* the projection, so without narrowing it every row is already distinct.
+	*
+	* ```ts
+	* client.data.posts.fields("status").distinct().find()   // the statuses in use
+	* ```
+	*/
+	distinct(enabled = true) {
+		this.params.distinct = enabled;
+		return this;
+	}
+	/**
+	* Continue after a previous page's `meta.nextCursor` — keyset paging.
+	*
+	* Unlike `offset`, a row inserted or deleted before the cursor cannot
+	* shift the window, so a walk neither repeats nor skips rows. Keep
+	* `orderBy` identical across pages: a cursor only continues the listing it
+	* came from, and one used against a different sort is refused rather than
+	* seeked in an order nobody asked for.
+	*/
+	after(cursor) {
+		this.params.after = cursor;
 		return this;
 	}
 	/**
@@ -1634,6 +1743,29 @@ var SDKQueryBuilder = class {
 		return this.collection.find(this.params);
 	}
 	/**
+	* Aggregate the rows this query matches instead of returning them.
+	*
+	* The builder's `where`/`logical`/`search` narrow which rows are
+	* aggregated; its `orderBy`, `include` and window do not apply — an
+	* aggregate has no rows to sort, no relations to load and no page to
+	* continue.
+	*
+	* ```ts
+	* await client.data.orders
+	*     .where("created_at", ">=", startOfMonth)
+	*     .aggregate({ select: [{ fn: "sum", field: "total" }], groupBy: ["status"] });
+	* // [{ status: "paid", sum_total: 41822.5 }, …]
+	* ```
+	*/
+	async aggregate(params) {
+		return this.collection.aggregate({
+			...params,
+			where: this.params.where,
+			logical: this.params.logical,
+			searchString: this.params.searchString
+		});
+	}
+	/**
 	* Page through everything this query matches, one row at a time.
 	*
 	* `.limit()` on the builder becomes the page size, so the ceiling on a
@@ -1709,6 +1841,67 @@ function inflightCountsFor(transport) {
 	}
 	return map;
 }
+/**
+* Where a fetched row's version is kept.
+*
+* Non-enumerable, so it does not appear in `Object.keys`, in `JSON.stringify`,
+* in a spread into an update body, or in the generated `Row` type — a row's
+* version is a fact about the *response*, not a column, and putting it in the
+* row proper would mean the server having to strip it back off every write.
+*
+* A string key rather than a symbol so it survives the structured clone an
+* offline store or a worker boundary does… which it does not, and that is the
+* honest position: an etag is per-read, and a row that has been through a cache
+* has not been read from the server. `etagOf` answers `undefined` there, and a
+* conditional write without a tag is an unconditional one.
+*/
+var ETAG_KEY = "__etag";
+/**
+* The version of a row, when it came straight from a read that reported one.
+*
+* ```ts
+* const post = await client.data.posts.get(1);
+* await client.data.posts.update(1, { title: "New" }, { ifMatch: etagOf(post) });
+* ```
+*
+* `undefined` for a row from `find()` (a list response carries one ETag at
+* most, and it would not be this row's), from the offline cache, or from a
+* server that does not send them. Passing `undefined` as `ifMatch` sends no
+* precondition, so the call above degrades to an ordinary update rather than
+* failing — which is the right default, and the reason to read this at the call
+* site where the choice is visible.
+*/
+function etagOf(row) {
+	if (!row || typeof row !== "object") return void 0;
+	const value = row[ETAG_KEY];
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* The headers a write's options ask for.
+*
+* One function rather than a spread at each call site: the three headers are
+* easy to add to one method and forget on the next, which is exactly how single
+* `PATCH` and `DELETE` came to send an `Idempotency-Key` the server never read
+* and `delete()` came to have no options at all.
+*/
+function writeHeaders(options) {
+	const headers = {};
+	if (options?.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+	if (options?.ifMatch) headers["If-Match"] = options.ifMatch;
+	if (options?.returning === false) headers["Prefer"] = "return=minimal";
+	return Object.keys(headers).length > 0 ? { headers } : void 0;
+}
+/** Attach a version to a row without making it part of the row. */
+function withETag(row, etag) {
+	if (!etag || !row || typeof row !== "object") return row;
+	Object.defineProperty(row, ETAG_KEY, {
+		value: etag,
+		enumerable: false,
+		configurable: true,
+		writable: true
+	});
+	return row;
+}
 function createCollectionClient(transport, slug, ws) {
 	const basePath = `/data/${slug}`;
 	const client = {
@@ -1728,9 +1921,10 @@ function createCollectionClient(transport, slug, ws) {
 		},
 		async findById(id) {
 			try {
-				const raw = await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, { method: "GET" });
+				const meta = {};
+				const raw = await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, { method: "GET" }, meta);
 				if (!raw) return void 0;
-				return raw;
+				return withETag(raw, meta.etag);
 			} catch (err) {
 				if (err instanceof RebaseApiError && err.status === 404) return;
 				throw err;
@@ -1750,20 +1944,38 @@ function createCollectionClient(transport, slug, ws) {
 			return await transport.request(basePath, {
 				method: "POST",
 				body: JSON.stringify(body),
-				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
+				...writeHeaders(options)
+			});
+		},
+		/**
+		* Insert, or replace the row already occupying the conflict target.
+		*
+		* One statement server-side (`INSERT ... ON CONFLICT DO UPDATE`), so
+		* unlike a `findById` followed by `create`-or-`update` it cannot lose
+		* the race between the two.
+		*/
+		async upsert(data, options) {
+			const query = options?.onConflict?.length ? `?on_conflict=${encodeURIComponent(options.onConflict.join(","))}` : "";
+			return await transport.request(`${basePath}${query}`, {
+				method: "POST",
+				body: JSON.stringify(data),
+				...writeHeaders(options)
 			});
 		},
 		async createMany(data, options) {
 			if (!Array.isArray(data)) throw new TypeError("createMany expects an array of records.");
 			if (data.length === 0) return [];
-			return (await transport.request(`${basePath}/bulk`, {
+			const raw = await transport.request(`${basePath}/bulk`, {
 				method: "POST",
 				body: JSON.stringify({
 					rows: data,
-					...options?.upsert ? { upsert: true } : {}
+					...options?.upsert ? { upsert: true } : {},
+					...options?.onConflict?.length ? { onConflict: options.onConflict } : {}
 				}),
-				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
-			})).data || [];
+				...writeHeaders(options)
+			});
+			if (options?.returning === false) return [];
+			return raw.data || [];
 		},
 		/**
 		* `PATCH`, the verb for a merge — `update(id, data: Partial<M>)` sends
@@ -1778,20 +1990,25 @@ function createCollectionClient(transport, slug, ws) {
 			return await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, {
 				method: "PATCH",
 				body: JSON.stringify(data),
-				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
+				...writeHeaders(options)
 			});
 		},
 		async updateMany(updates, options) {
 			if (!Array.isArray(updates)) throw new TypeError("updateMany expects an array of { id, data } entries.");
 			if (updates.length === 0) return [];
-			return (await transport.request(`${basePath}/bulk`, {
+			const raw = await transport.request(`${basePath}/bulk`, {
 				method: "PATCH",
 				body: JSON.stringify({ updates }),
-				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
-			})).data || [];
+				...writeHeaders(options)
+			});
+			if (options?.returning === false) return [];
+			return raw.data || [];
 		},
-		async delete(id) {
-			await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, { method: "DELETE" });
+		async delete(id, options) {
+			await transport.request(`${basePath}/${encodeURIComponent(String(id))}`, {
+				method: "DELETE",
+				...writeHeaders(options)
+			});
 		},
 		/**
 		* `POST .../bulk/delete`, not `DELETE .../bulk`.
@@ -1810,7 +2027,7 @@ function createCollectionClient(transport, slug, ws) {
 			await transport.request(`${basePath}/bulk/delete`, {
 				method: "POST",
 				body: JSON.stringify({ ids }),
-				...options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
+				...writeHeaders(options)
 			});
 		},
 		async count(params) {
@@ -1889,8 +2106,8 @@ function createCollectionClient(transport, slug, ws) {
 			if (typeof columnOrCondition === "object") return builder.where(columnOrCondition);
 			return builder.where(columnOrCondition, operator, value);
 		},
-		orderBy(column, direction) {
-			return new SDKQueryBuilder(client).orderBy(column, direction);
+		orderBy(column, direction, nulls) {
+			return new SDKQueryBuilder(client).orderBy(column, direction, nulls);
 		},
 		limit(count) {
 			return new SDKQueryBuilder(client).limit(count);
@@ -1907,6 +2124,28 @@ function createCollectionClient(transport, slug, ws) {
 		include(...relations) {
 			return new SDKQueryBuilder(client).include(...relations);
 		},
+		fields(...columns) {
+			return new SDKQueryBuilder(client).fields(...columns);
+		},
+		distinct(enabled) {
+			return new SDKQueryBuilder(client).distinct(enabled);
+		},
+		after(cursor) {
+			return new SDKQueryBuilder(client).after(cursor);
+		},
+		/**
+		* `count`/`sum`/`avg`/`min`/`max` over the matching rows, optionally
+		* grouped — `GET /<collection>/aggregate`.
+		*
+		* The REST route has served this since aggregates landed and the SDK
+		* had no method for it, so the only way to reach it from a typed client
+		* was to hand-build the URL. `findAll()` and a reduce is the thing this
+		* exists to replace: wrong under a `limit`, unaffordable without one.
+		*/
+		async aggregate(params) {
+			const qs = buildAggregateQueryString(params);
+			return (await transport.request(`${basePath}/aggregate${qs}`, { method: "GET" })).data || [];
+		},
 		listen: unsupportedMethod(NO_SOCKET),
 		listenById: unsupportedMethod(NO_SOCKET)
 	};
@@ -1922,36 +2161,46 @@ function createCollectionClient(transport, slug, ws) {
 				logical: params?.logical,
 				limit: params?.limit,
 				offset: window.driverOffset,
+				page: params?.page,
+				include: params?.include,
+				fields: params?.fields,
+				distinct: params?.distinct,
 				orderBy: normalizeOrderBy(params?.orderBy),
 				searchString: params?.searchString,
 				searchExplain: params?.searchExplain,
 				vectorSearch: params?.vectorSearch
-			}, (incomingRows) => {
+			}, (incomingRows, frameMeta) => {
 				const currentUpdateId = ++lastUpdateId;
 				const requestedLimit = window.limit;
 				const offset = window.offset;
 				const rows = incomingRows;
-				const emit = (total, hasMore) => {
+				const emit = (total, hasMore, nextCursor) => {
 					if (!active || currentUpdateId !== lastUpdateId) return;
 					onUpdate({
 						data: rows,
 						meta: {
 							total,
-							limit: requestedLimit,
-							offset,
-							hasMore
+							limit: frameMeta?.limit ?? requestedLimit,
+							offset: frameMeta?.offset ?? offset,
+							hasMore,
+							...nextCursor && { nextCursor }
 						}
 					});
 				};
+				if (frameMeta && frameMeta.total !== void 0) {
+					lastKnownTotal = frameMeta.total;
+					emit(frameMeta.total, frameMeta.hasMore, frameMeta.nextCursor);
+					return;
+				}
+				if (lastKnownTotal !== void 0) {
+					emit(lastKnownTotal, offset + rows.length < lastKnownTotal, frameMeta?.nextCursor);
+					return;
+				}
 				client.count(params).then((total) => {
 					lastKnownTotal = total;
-					emit(total, offset + rows.length < total);
+					emit(total, offset + rows.length < total, frameMeta?.nextCursor);
 				}).catch(() => {
-					if (lastKnownTotal !== void 0) {
-						emit(lastKnownTotal, offset + rows.length < lastKnownTotal);
-						return;
-					}
-					emit(offset + rows.length, rows.length >= requestedLimit);
+					emit(offset + rows.length, rows.length >= requestedLimit, frameMeta?.nextCursor);
 				});
 			}, onError);
 			return () => {
@@ -2044,9 +2293,13 @@ function createStorage(transport, storageId) {
 		if (!storageId) return path;
 		return `${path}${path.includes("?") ? "&" : "?"}storageId=${encodeURIComponent(storageId)}`;
 	};
-	async function putObject({ file, key, metadata, bucket, public: isPublic }) {
+	async function putObject({ file, key, metadata, bucket, public: isPublic, context }) {
 		const formData = new FormData();
 		formData.append("file", file);
+		if (context?.collection && context?.property) {
+			formData.append("collection", context.collection);
+			formData.append("property", context.property);
+		}
 		let effectiveKey = key;
 		if (isPublic && effectiveKey && !isPublicStoragePath(effectiveKey)) effectiveKey = `${PUBLIC_STORAGE_PREFIX}${effectiveKey.replace(/^\/+/, "")}`;
 		if (effectiveKey) formData.append("key", effectiveKey);
@@ -2628,6 +2881,8 @@ var RebaseWebSocketClient = class {
 					const incomingRows = message.rows || [];
 					const updatePks = message.pks;
 					if (updatePks) collectionSub.pks = updatePks;
+					const updateMeta = message.meta;
+					if (updateMeta) collectionSub.latestMeta = updateMeta;
 					const rows = this.mergeRows(collectionSub.latestData, incomingRows, collectionSub.pks);
 					collectionSub.latestData = rows;
 					collectionSub.lastUpdated = Date.now();
@@ -2637,7 +2892,7 @@ var RebaseWebSocketClient = class {
 					collectionSub.subscribeInFlight = false;
 					collectionSub.callbacks.forEach((callback) => {
 						try {
-							callback.onUpdate(rows);
+							callback.onUpdate(rows, collectionSub.latestMeta);
 						} catch (error) {
 							console.error("Error in collection subscription callback:", error);
 							if (callback.onError) callback.onError(error instanceof Error ? error : new Error(String(error)));
@@ -3043,7 +3298,7 @@ var RebaseWebSocketClient = class {
 				onError
 			});
 			if (existingSubscription.latestData !== void 0 && existingSubscription.isInitialDataReceived) try {
-				onUpdate(existingSubscription.latestData);
+				onUpdate(existingSubscription.latestData, existingSubscription.latestMeta);
 			} catch (error) {
 				console.error("Error in collection subscription callback:", error);
 				if (onError) onError(error instanceof Error ? error : new Error(String(error)));
@@ -4565,9 +4820,22 @@ function logicalOrders(condition, depth = 0) {
 * separate answer, because a sort changes which rows come first and not which
 * rows match. See {@link isLocallySortable}.
 */
+/**
+* Whether an `include` asks for anything, in any of its spellings.
+*
+* `include` is a list of names, a list of dotted paths, or a tree — and only
+* the first two have a `length`. A `.length > 0` test read the tree form as
+* "no relations", which is the answer that makes the local cache claim it can
+* evaluate a relational query exactly.
+*/
+function hasAnyInclude(include) {
+	if (!include) return false;
+	if (Array.isArray(include)) return include.length > 0;
+	return Object.keys(include).length > 0;
+}
 function isExactlyEvaluable(params) {
 	if (!params) return true;
-	if (params.include && params.include.length > 0) return false;
+	if (hasAnyInclude(params.include)) return false;
 	if (params.searchString) return false;
 	if (params.vectorSearch) return false;
 	if (whereOrders(params.where)) return false;
@@ -4980,6 +5248,47 @@ var OfflineManager = class {
 				this.notifyCollection(slug);
 				return rows;
 			},
+			/**
+			* Upsert, with the one case that cannot be resolved without the
+			* server refused rather than guessed.
+			*
+			* On the primary key an upsert is create-or-replace, which the
+			* local store can do and the queue already carries (`createMany`
+			* with `upsert`). On a natural key it is not: deciding whether a
+			* row with that email exists means an index this store does not
+			* keep, and inventing an id would insert a duplicate the moment the
+			* queue drains — the exact outcome upsert exists to prevent.
+			*/
+			upsert: async (data, options) => {
+				await this.ensureCollection(slug);
+				if (this.connectivity.shouldAttempt()) try {
+					const row = await inner.upsert(data, options);
+					this.connectivity.markSuccess();
+					await this.ingest(slug, [row]);
+					this.notifyCollection(slug);
+					this.scheduleRefresh(slug);
+					return row;
+				} catch (error) {
+					if (!isNetworkError(error)) throw error;
+					this.connectivity.markFailure();
+				}
+				const rowId = data.id;
+				if (options?.onConflict?.length || rowId === void 0) throw new RebaseClientError(`Cannot upsert into "${slug}" while offline: the row it would replace can only be found by the server. Upserting on the primary key, with the key in the row, is queued; upserting on a natural key is not.`, { code: "OFFLINE_UPSERT_UNSUPPORTED" });
+				const row = {
+					...data,
+					id: rowId
+				};
+				await this.enqueue({
+					collection: slug,
+					type: "createMany",
+					data: [row],
+					upsert: true,
+					rollback: { rows: { [String(rowId)]: this.rawLocalRow(slug, rowId) ?? null } }
+				});
+				this.setLocalRow(slug, rowId, row);
+				this.notifyCollection(slug);
+				return row;
+			},
 			updateMany: async (updates, options) => {
 				await this.ensureCollection(slug);
 				if (!Array.isArray(updates)) throw new TypeError("updateMany expects an array of { id, data } entries.");
@@ -5046,10 +5355,10 @@ var OfflineManager = class {
 				for (const id of ids) this.removeLocalRow(slug, id, false);
 				this.notifyCollection(slug);
 			},
-			update: async (id, data) => {
+			update: async (id, data, options) => {
 				await this.ensureCollection(slug);
 				if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) try {
-					const row = await inner.update(id, data);
+					const row = await inner.update(id, data, options);
 					this.connectivity.markSuccess();
 					await this.ingest(slug, [row]);
 					this.notifyCollection(slug);
@@ -5058,6 +5367,7 @@ var OfflineManager = class {
 					if (!isNetworkError(error)) throw error;
 					this.connectivity.markFailure();
 				}
+				if (hasFieldOperation(data)) throw new RebaseClientError(`Cannot apply a field operation to "${slug}" while offline: it is evaluated against the stored value, which this device does not have a current copy of. Send the value itself, or retry when the connection is back.`, { code: "OFFLINE_FIELD_OP_UNSUPPORTED" });
 				const base = this.rawLocalRow(slug, id);
 				await this.enqueue({
 					collection: slug,
@@ -5075,10 +5385,10 @@ var OfflineManager = class {
 				this.notifyCollection(slug);
 				return optimistic;
 			},
-			delete: async (id) => {
+			delete: async (id, options) => {
 				await this.ensureCollection(slug);
 				if (this.connectivity.shouldAttempt() && !this.hasPending(slug, id)) try {
-					await inner.delete(id);
+					await inner.delete(id, options);
 					this.connectivity.markSuccess();
 					this.removeLocalRow(slug, id, true);
 					this.notifyCollection(slug);
@@ -5121,12 +5431,16 @@ var OfflineManager = class {
 				if (typeof columnOrCondition === "object") return builder.where(columnOrCondition);
 				return builder.where(columnOrCondition, operator, value);
 			},
-			orderBy: (column, direction) => new SDKQueryBuilder(wrapped).orderBy(column, direction),
+			orderBy: (column, direction, nulls) => new SDKQueryBuilder(wrapped).orderBy(column, direction, nulls),
 			limit: (count) => new SDKQueryBuilder(wrapped).limit(count),
 			offset: (count) => new SDKQueryBuilder(wrapped).offset(count),
 			search: (searchString, options) => new SDKQueryBuilder(wrapped).search(searchString, options),
 			vectorSearch: (property, vector, options) => new SDKQueryBuilder(wrapped).vectorSearch(property, vector, options),
 			include: (...relations) => new SDKQueryBuilder(wrapped).include(...relations),
+			fields: (...columns) => new SDKQueryBuilder(wrapped).fields(...columns),
+			distinct: (enabled) => new SDKQueryBuilder(wrapped).distinct(enabled),
+			after: (cursor) => new SDKQueryBuilder(wrapped).after(cursor),
+			aggregate: inner.aggregate,
 			listen: inner.listen,
 			listenById: inner.listenById
 		};
@@ -6274,11 +6588,26 @@ channel: (name, options) => {
 				body: payload ? JSON.stringify(payload) : void 0
 			});
 		},
+		batch: async (operations, options) => {
+			if (!Array.isArray(operations)) throw new TypeError("batch expects an array of operations.");
+			if (operations.length === 0) return {
+				data: [],
+				meta: { operations: 0 }
+			};
+			const headers = {};
+			if (options?.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+			if (options?.returning === false) headers.Prefer = "return=minimal";
+			return transport.request("/data/_batch", {
+				method: "POST",
+				body: JSON.stringify({ operations }),
+				...Object.keys(headers).length > 0 ? { headers } : {}
+			});
+		},
 		data: dataProxy,
 		...offlineManager ? { offline: offlineManager.api } : {}
 	};
 }
 //#endregion
-export { MemoryOfflineStore, QueryBuilder, RebaseApiError, RebaseClientError, RebasePaginationError, RebaseRealtimeChannel, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, isOfflineError, or };
+export { MemoryOfflineStore, QueryBuilder, RebaseApiError, RebaseClientError, RebasePaginationError, RebaseRealtimeChannel, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, etagOf, isOfflineError, not, or };
 
 //# sourceMappingURL=index.es.js.map