better-supabase 0.2.0 → 0.4.0

package/dist/events/index.js

@@ -1,2 +1,140 @@
-import { a as isCloudEvent, i as httpSink, n as forwardMutations, o as toCloudEvents, r as fromHttp, s as toHttp, t as ROW_EVENT_TYPES } from "../events-BuzTgn2D.js";
+import { n as nowInstant } from "../temporal-BwshQk0W.js";
+//#region src/events/index.ts
+const ROW_EVENT_TYPES = {
+	insert: "dev.better-supabase.row.created",
+	upsert: "dev.better-supabase.row.upserted",
+	update: "dev.better-supabase.row.updated",
+	delete: "dev.better-supabase.row.deleted"
+};
+function subjectOf(meta, table, row) {
+	const key = meta?.tables[table]?.primaryKey;
+	if (!key || key.length === 0) return void 0;
+	const values = key.map((column) => row[column]);
+	if (values.some((value) => value === void 0 || value === null)) return void 0;
+	return `${table}/${values.map((value) => encodeURIComponent(String(value))).join(",")}`;
+}
+/**
+* One CloudEvent per mutated row: `dev.better-supabase.row.created` with the
+* app-cased row as `data`, the primary key as `subject`, the tenant as
+* `partitionkey` and the actor as `actorid`.
+*/
+function toCloudEvents(notice, options) {
+	const type = options.typePrefix ? `${options.typePrefix}.row.${ROW_EVENT_TYPES[notice.kind].split(".").at(-1)}` : ROW_EVENT_TYPES[notice.kind];
+	const time = (options.now ?? nowInstant)().toString();
+	return notice.rows.map((row) => {
+		const subject = subjectOf(options.meta, notice.table, row);
+		return {
+			specversion: "1.0",
+			id: options.id?.() ?? crypto.randomUUID(),
+			source: options.source,
+			type,
+			...subject ? { subject } : {},
+			time,
+			datacontenttype: "application/json",
+			data: {
+				table: notice.table,
+				row
+			},
+			...notice.context.tenant ? { partitionkey: notice.context.tenant } : {},
+			...notice.context.actor?.id ? { actorid: notice.context.actor.id } : {}
+		};
+	});
+}
+/**
+* Sends a CloudEvent for every mutation to `sink`. Returns a function that
+* stops forwarding. Use an outbox (SQL kit) when events must not be lost.
+*/
+function forwardMutations(betterSupabase, sink, options) {
+	return betterSupabase.events.on("mutation", (notice) => {
+		if (options.filter && !options.filter(notice)) return;
+		const events = toCloudEvents(notice, {
+			...options,
+			meta: betterSupabase.meta
+		});
+		if (events.length === 0) return;
+		const report = (error) => {
+			(options.onError ?? ((cause) => {
+				betterSupabase.events.logger.error("event sink failed", { cause });
+			}))(error, events);
+		};
+		try {
+			Promise.resolve(sink.send(events)).catch(report);
+		} catch (error) {
+			report(error);
+		}
+	});
+}
+const STRUCTURED = "application/cloudevents+json";
+const BATCH = "application/cloudevents-batch+json";
+/** The HTTP protocol binding: headers and body for one event (or a batch). */
+function toHttp(events, mode = "structured") {
+	const list = Array.isArray(events) ? events : [events];
+	switch (mode) {
+		case "batch": return [{
+			headers: { "content-type": BATCH },
+			body: JSON.stringify(list)
+		}];
+		case "structured": return list.map((event) => ({
+			headers: { "content-type": STRUCTURED },
+			body: JSON.stringify(event)
+		}));
+		case "binary": return list.map((event) => {
+			const headers = {};
+			for (const [key, value] of Object.entries(event)) {
+				if (key === "data" || key === "datacontenttype" || value === void 0) continue;
+				headers[`ce-${key}`] = encodeURIComponent(String(value)).replaceAll("%20", " ");
+			}
+			headers["content-type"] = event.datacontenttype ?? "application/json";
+			return {
+				headers,
+				body: event.data === void 0 ? "" : JSON.stringify(event.data)
+			};
+		});
+		default: throw new TypeError(`Unknown CloudEvents mode ${String(mode)}`);
+	}
+}
+function isCloudEvent(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const event = value;
+	return event["specversion"] === "1.0" && typeof event["id"] === "string" && typeof event["source"] === "string" && typeof event["type"] === "string";
+}
+/** Reads CloudEvents from a request in any of the three HTTP modes. */
+async function fromHttp(request) {
+	const contentType = request.headers.get("content-type") ?? "";
+	const text = await request.text();
+	if (contentType.startsWith(BATCH)) {
+		const parsed = JSON.parse(text);
+		if (!Array.isArray(parsed) || !parsed.every(isCloudEvent)) throw new TypeError("Invalid CloudEvents batch");
+		return parsed;
+	}
+	if (contentType.startsWith(STRUCTURED)) {
+		const parsed = JSON.parse(text);
+		if (!isCloudEvent(parsed)) throw new TypeError("Invalid CloudEvent");
+		return [parsed];
+	}
+	const event = {};
+	for (const [key, value] of request.headers) if (key.startsWith("ce-")) event[key.slice(3)] = decodeURIComponent(value);
+	if (contentType) event["datacontenttype"] = contentType;
+	if (text) event["data"] = contentType.includes("json") ? JSON.parse(text) : text;
+	if (!isCloudEvent(event)) throw new TypeError("Request is not a CloudEvent");
+	return [event];
+}
+/** POSTs events to `url`. Non-2xx responses reject. */
+function httpSink(url, options = {}) {
+	const send = options.fetch ?? fetch;
+	return { async send(events) {
+		for (const message of toHttp(events, options.mode ?? "batch")) {
+			const response = await send(url, {
+				method: "POST",
+				headers: {
+					...options.headers,
+					...message.headers
+				},
+				body: message.body
+			});
+			if (!response.ok) throw new Error(`Event sink responded ${String(response.status)}`);
+		}
+	} };
+}
+//#endregion
 export { ROW_EVENT_TYPES, forwardMutations, fromHttp, httpSink, isCloudEvent, toCloudEvents, toHttp };

package/dist/{events-DOt3nSO-.d.ts → events-B21UOhvP.d.ts}

@@ -1,6 +1,6 @@
-import { g as Operation } from "./executor-CGdNQ27g.js";
-import { p as DbError } from "./result-CTkCZ6JA.js";
-import { h as RequestContext, l as MutationKind } from "./plugin-C4TR9J0Z.js";
+import { g as Operation } from "./executor-B5IoUxLE.js";
+import { p as DbError } from "./result-CqEsbgYs.js";
+import { h as RequestContext, l as MutationKind } from "./plugin-bNhvJwRh.js";
 //#region src/core/logger.d.ts
 type LogFields = Readonly<Record<string, unknown>>;
 /**
@@ -37,7 +37,7 @@ interface MutationNotice {
   readonly rows: readonly Readonly<Record<string, unknown>>[];
   readonly context: RequestContext;
 }
-/** A successful RPC registered with `sb.defineRpc(name, { invalidates })`. */
+/** A successful RPC registered with `betterSupabase.defineRpc(name, { invalidates })`. */
 interface RpcNotice {
   readonly name: string;
   /** App keys of the tables the function changes. */

package/dist/{executor-CGdNQ27g.d.ts → executor-B5IoUxLE.d.ts}

@@ -1,5 +1,5 @@
-import { P as TableMeta, T as RelationMeta, c as Codec } from "./types-C83v5SQz.js";
-import { o as Result, v as ErrorMapper } from "./result-CTkCZ6JA.js";
+import { P as TableMeta, T as RelationMeta, c as Codec } from "./types-DONv9SHN.js";
+import { o as Result, v as ErrorMapper } from "./result-CqEsbgYs.js";
 //#region src/ir/types.d.ts
 /**
  * The query IR. Every repository call becomes one of these operations; the

package/dist/{executor-DeppvirK.js → executor-CVt6dD0B.js}

@@ -1,6 +1,6 @@
-import { c as mapDbError, n as dbError } from "./errors-Bl3rkOzo.js";
-import { i as ok, n as err, o as toDbError } from "./result-DWXatkd6.js";
-import { t as compileSql } from "./sql-DTjA1LPj.js";
+import { c as mapDbError, n as dbError } from "./errors-L0xK41y_.js";
+import { i as ok, n as err, o as toDbError } from "./result-Bj6yt33D.js";
+import { t as compileSql } from "./sql-B34HU2DI.js";
 //#region src/postgres/executor.ts
 function isPgError(value) {
 	return typeof value === "object" && value !== null && typeof value.code === "string";
@@ -25,6 +25,11 @@ async function run(client, plan, op) {
 		const [first] = await client.queryRaw(plan.count.text, [...plan.count.params]);
 		count = first?.count ?? 0;
 	} else if (op.kind !== "select") count = rows.length;
+	for (const next of plan.chunks ?? []) {
+		const more = await run(client, next, op);
+		rows.push(...more.rows);
+		count = (count ?? 0) + (more.count ?? 0);
+	}
 	return {
 		rows,
 		count
@@ -74,7 +79,7 @@ async function executeOn(client, op, context) {
 	if (context.signal?.aborted) return err(dbError("aborted", "The request was aborted"));
 	let result;
 	try {
-		result = await run(client, plan, op);
+		result = plan.chunks && client.transaction ? await client.transaction((scoped) => run(scoped, plan, op)) : await run(client, plan, op);
 	} catch (cause) {
 		const raw = fromPgError(cause);
 		return err(raw ? mapDbError(raw, context.errorMappers) : toDbError(cause));

package/dist/{executor-BYXQ9AGn.d.ts → executor-CZ7ImRiD.d.ts}

@@ -1,5 +1,5 @@
-import { r as Executor } from "./executor-CGdNQ27g.js";
-import { y as RawDbError } from "./result-CTkCZ6JA.js";
+import { r as Executor } from "./executor-B5IoUxLE.js";
+import { y as RawDbError } from "./result-CqEsbgYs.js";
 //#region src/postgres/executor.d.ts
 /**
  * Anything that runs parameterized SQL: `ctx.postgres` from

package/dist/hono/index.d.ts

@@ -1,45 +1,38 @@
-import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-C83v5SQz.js";
-import { t as BetterSupabase } from "../define-e3zI4_4g.js";
-import { r as AuthState } from "../resolve-CjHILk2w.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-Dne1ARSa.js";
-import { i as ResourceRouteOptions } from "../resource-CgZa3YG_.js";
+import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
+import { t as BetterSupabase } from "../define-CRS2MRV3.js";
+import { r as AuthState } from "../resolve-BAqQcwMW.js";
+import { f as ServerContext, n as GuardOptions, p as ServerOptions, r as MiddlewareOptions, u as BetterServer } from "../respond-DgIbdrt8.js";
+import { a as ResourceRouteOptions } from "../resource-BJcaIfxi.js";
 import { Context, ErrorHandler, Hono, MiddlewareHandler } from "hono";
 //#region src/hono/index.d.ts
 /** Hono `Env` with the request's better-supabase context in `c.var`. */
-export interface BetterEnv<M extends AnyModels, F extends AnyFunctions, E> {
+export interface HonoEnv<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
   Variables: {
-    readonly bs: ServerContext<M, F, E>;
-    readonly db: ServerContext<M, F, E>["db"];
-    readonly auth: AuthState;
+    readonly bs: ServerContext<M, F, E, C, P>;
+    readonly db: ServerContext<M, F, E, C, P>["db"];
+    readonly auth: AuthState<C, P>;
   };
 }
 export interface HonoOptions extends ServerOptions {
   /** Include error details in problem responses. Defaults to `NODE_ENV === 'development'`. */
   readonly exposeErrors?: boolean;
 }
-export interface MiddlewareOptions extends GuardOptions {
-  /**
-   * Refresh an expired cookie session and send the new cookies. Only for
-   * routes browsers call with cookies; bearer tokens never refresh.
-   */
-  readonly refresh?: boolean;
-}
-export interface BetterHono<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+export interface BetterHono<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /** Resolves the caller, enforces `allow` and sets `c.var.bs`, `c.var.db`, `c.var.auth`. */
-  middleware(options?: MiddlewareOptions): MiddlewareHandler<BetterEnv<M, F, E>>;
+  middleware(options?: MiddlewareOptions): MiddlewareHandler<HonoEnv<M, F, E, C, P>>;
   /** Wraps a handler: `Result`s become JSON or Problem Details, `undefined` becomes 204. */
-  handle(handler: (c: Context<BetterEnv<M, F, E>>, ctx: ServerContext<M, F, E>) => unknown, options?: {
+  handler(fn: (c: Context<HonoEnv<M, F, E, C, P>>, ctx: ServerContext<M, F, E, C, P>) => unknown, options?: {
     readonly status?: number;
-  }): (c: Context<BetterEnv<M, F, E>>) => Promise<Response>;
+  }): (c: Context<HonoEnv<M, F, E, C, P>>) => Promise<Response>;
   /** `app.onError(bs.onError)`: `DbException`s (and errors caused by a `DbError`) become Problem Details, others a 500. */
-  readonly onError: ErrorHandler<BetterEnv<M, F, E>>;
+  readonly onError: ErrorHandler<HonoEnv<M, F, E, C, P>>;
   /**
    * REST routes for a table matching `createOpenApi`. Mount with
    * `app.route('/customers', bs.resource('customers'))` behind `middleware()`.
    */
-  resource<T extends TableKey<M>>(table: T, options?: ResourceRouteOptions<M, T>): Hono<BetterEnv<M, F, E>>;
+  resource<T extends TableKey<M>>(table: T, options?: ResourceRouteOptions<M, T>): Hono<HonoEnv<M, F, E, C, P>>;
 }
 /** Hono integration: a server plus middleware, handlers and REST resources. */
-export declare function createHono<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options?: HonoOptions): BetterHono<M, F, E>;
+export declare function createHono<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: HonoOptions): BetterHono<M, F, E, C, P>;
 //#endregion
-export type { GuardOptions, ResourceRouteOptions };
+export type { GuardOptions, MiddlewareOptions, ResourceRouteOptions };

package/dist/hono/index.js

@@ -1,7 +1,7 @@
-import { n as dbError, r as dbErrorOf } from "../errors-Bl3rkOzo.js";
-import { a as problemResponse } from "../problem-BTkTtRV9.js";
-import { i as respond, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-DMcbQwfN.js";
-import { t as defineResource } from "../resource-BHEWmQJK.js";
+import { n as dbError, r as dbErrorOf } from "../errors-L0xK41y_.js";
+import { a as problemResponse } from "../problem-BihjPR0t.js";
+import { a as guard, i as defaultExpose, n as extendServer, s as respond, t as createServer } from "../server-BA75B0mT.js";
+import { t as defineResource } from "../resource-My_y-Syh.js";
 import { Hono } from "hono";
 //#region src/hono/index.ts
 function contextOf(c) {
@@ -10,8 +10,8 @@ function contextOf(c) {
 	return ctx;
 }
 /** Hono integration: a server plus middleware, handlers and REST resources. */
-function createHono(sb, options = {}) {
-	const server = createServer(sb, options);
+function createHono(betterSupabase, options = {}) {
+	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
 	const onError = (cause, c) => {
 		const instance = new URL(c.req.url).pathname;
@@ -31,7 +31,7 @@ function createHono(sb, options = {}) {
 		middleware(middlewareOptions = {}) {
 			return async (c, next) => {
 				const ctx = await server.context(c.req.raw, { refresh: middlewareOptions.refresh ?? false });
-				const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal);
+				const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal, middlewareOptions.scopes);
 				if (denied) return ctx.resolution.apply(problemResponse(denied, {
 					instance: new URL(c.req.url).pathname,
 					expose
@@ -43,18 +43,18 @@ function createHono(sb, options = {}) {
 				c.res = ctx.resolution.apply(c.res);
 			};
 		},
-		handle(handler, handleOptions = {}) {
+		handler(fn, handlerOptions = {}) {
 			return (c) => {
 				const ctx = contextOf(c);
-				return respond(() => handler(c, ctx), {
+				return respond(() => fn(c, ctx), {
 					instance: new URL(c.req.url).pathname,
 					expose,
-					...handleOptions
+					...handlerOptions
 				});
 			};
 		},
 		resource(table, resourceOptions) {
-			const resource = defineResource(sb, table, resourceOptions);
+			const resource = defineResource(betterSupabase, table, resourceOptions);
 			const app = new Hono();
 			const serve = (item) => (c) => resource.handle(c.req.raw, contextOf(c).db, item ? c.req.param("id") : void 0, {
 				instance: new URL(c.req.url).pathname,

package/dist/{index-DuP14VHo.d.ts → index-528Ugmyp.d.ts}

@@ -1,9 +1,11 @@
-import { b as PermdockBucketPolicy, i as BucketPolicyName } from "./types-C83v5SQz.js";
-import { p as DbError, t as AsyncResult } from "./result-CTkCZ6JA.js";
+/// <reference lib="esnext.temporal" />
+import { b as PermdockBucketPolicy, i as BucketPolicyName } from "./types-DONv9SHN.js";
+import { p as DbError, t as AsyncResult } from "./result-CqEsbgYs.js";
 import { n as StoragePath, t as PathIn } from "./path-Cv__-OTj.js";
+import { t as PermdockCatalog } from "./permdock-sql-DImJULY-.js";
 import { n as TemplateValues, t as TemplateParams } from "./template-mbvlysOo.js";
 import { SupabaseClient } from "@supabase/supabase-js";
-//#region src/storage/index.d.ts
+//#region src/storage/bucket.d.ts
 type BucketPolicy = BucketPolicyName | PermdockBucketPolicy;
 interface BucketConfig<P extends string = string, Id extends string = string> {
   /** Bucket id, e.g. `customer-logos`. */
@@ -20,10 +22,16 @@ interface BucketConfig<P extends string = string, Id extends string = string> {
    * The helpers check role and scope only. Use `permdock` just for
    * permissions whose grants have no row conditions beyond the scope: for a
    * permission with row conditions (e.g. `ownerId = principal.id`) the bucket
-   * grants every object in the scope. Leave those to the policies
-   * `permdock rls generate` writes.
+   * would grant every object in the scope. Pass `catalog` to refuse those
+   * keys here; `better-supabase doctor` (BS214) refuses them from the
+   * catalog file.
    */
   readonly policy?: BucketPolicy;
+  /**
+   * PermDock's `permissions.catalog.json`. With it, a `permdock` policy
+   * naming a permission with `rowConditions: true` throws.
+   */
+  readonly catalog?: PermdockCatalog;
   /** `'5MiB'`, `'500KB'` or bytes. */
   readonly fileSizeLimit?: string | number;
   /** `['image/png', 'image/*']`. */
@@ -105,14 +113,17 @@ interface ReplaceResult<Id extends string = string> {
 interface SweepOptions<P extends string> {
   /** Only look under the path prefix these values fill. */
   readonly within?: Partial<TemplateValues<P>>;
-  /** Minimum age in milliseconds, or a cutoff date. */
-  readonly olderThan: number | Date;
+  /**
+   * A cutoff instant, or a minimum age. A duration counts a day as 24 hours
+   * and cannot use months or years.
+   */
+  readonly olderThan: Temporal.Instant | Temporal.Duration;
   /** Returns which of `paths` are still referenced. */
   readonly referenced: (paths: readonly string[]) => PromiseLike<Iterable<string>> | Iterable<string>;
   readonly dryRun?: boolean;
   readonly batchSize?: number;
   readonly signal?: AbortSignal;
-  readonly now?: () => number;
+  readonly now?: () => Temporal.Instant;
 }
 interface SweepResult {
   readonly scanned: number;
@@ -191,7 +202,16 @@ interface Bucket<P extends string, Id extends string = string> {
   /** A `[storage.buckets.<id>]` section for `supabase/config.toml`. */
   toml(): string;
   drift(actual: ActualBucket | undefined): readonly BucketDrift[];
-  connect(client: StorageClient): BucketClient<P, Id>;
+  connect(client: StorageClient, options?: BucketConnectOptions): BucketClient<P, Id>;
+}
+interface BucketConnectOptions {
+  /**
+   * Reuse a signed URL for the same path, `ttl`, `transform` and `download`
+   * until shortly before it expires (a tenth of the `ttl`, at most a minute).
+   * The cache belongs to this connection; connect once per request so URLs
+   * never cross users.
+   */
+  readonly cacheSignedUrls?: boolean;
 }
 declare function parseSize(value: string | number): number;
 /** Maps a Storage error (`StorageApiError`, fetch failures) to a `DbError`. */
@@ -213,4 +233,4 @@ declare function fromStorageError(raw: unknown, table?: string): DbError;
  */
 declare function defineBucket<const P extends string, const Id extends string = string>(config: BucketConfig<P, Id>): Bucket<P, Id>;
 //#endregion
-export { parseSize as C, fromStorageError as S, TtlPreset as _, BucketDrift as a, UrlOptions as b, ReplaceOptions as c, StorageClient as d, StoredObject as f, TransformOptions as g, TTL as h, BucketConfig as i, ReplaceResult as l, SweepResult as m, Bucket as n, BucketPolicy as o, SweepOptions as p, BucketClient as r, ObjectTarget as s, ActualBucket as t, Reservation as u, UploadBody as v, defineBucket as x, UploadOptions as y };
+export { fromStorageError as C, defineBucket as S, TransformOptions as _, BucketConnectOptions as a, UploadOptions as b, ObjectTarget as c, Reservation as d, StorageClient as f, TTL as g, SweepResult as h, BucketConfig as i, ReplaceOptions as l, SweepOptions as m, Bucket as n, BucketDrift as o, StoredObject as p, BucketClient as r, BucketPolicy as s, ActualBucket as t, ReplaceResult as u, TtlPreset as v, parseSize as w, UrlOptions as x, UploadBody as y };

package/dist/{index-Bw1bwtC0.d.ts → index-BAy4tsAP.d.ts}

@@ -1,14 +1,16 @@
-import { N as TableKey, O as Row, n as AnyModels, t as AnyFunctions } from "./types-C83v5SQz.js";
-import { l as CountMode } from "./executor-CGdNQ27g.js";
-import { b as ValidationIssue, t as AsyncResult } from "./result-CTkCZ6JA.js";
-import { C as FindExt, Ct as WhereInput, O as RepositoryOf, T as OffsetPageArgs, dt as IncludeArg, gt as OrderByArg, t as BetterSupabase, vt as Payload, w as OffsetPage, xt as SelectArg } from "./define-e3zI4_4g.js";
+import { N as TableKey, O as Row, n as AnyModels, t as AnyFunctions } from "./types-DONv9SHN.js";
+import { l as CountMode } from "./executor-B5IoUxLE.js";
+import { b as ValidationIssue, t as AsyncResult } from "./result-CqEsbgYs.js";
+import { C as FindExt, Ct as WhereInput, O as RepositoryOf, T as OffsetPageArgs, _ as CursorPage, dt as IncludeArg, gt as OrderByArg, t as BetterSupabase, v as CursorPageArgs, vt as Payload, w as OffsetPage, xt as SelectArg } from "./define-CRS2MRV3.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/list/index.d.ts
+//#region src/list/list-query.d.ts
 /** Facet value meaning "not set": filters with `is null`. */
 declare const UNSET = "__unset__";
 type Column<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string>;
 type TextColumn<M extends AnyModels, T extends keyof M> = { [K in Column<M, T>]: [NonNullable<Row<M, T>[K]>] extends [string] ? K : never; }[Column<M, T>];
-interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends string, F extends string, C extends boolean = boolean> {
+/** `offset` pages by number; `cursor` continues after the last row (keyset). */
+type ListPagination = "offset" | "cursor";
+interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends string, F extends string, C extends boolean = boolean, P extends ListPagination = ListPagination> {
   /**
    * Also count rows per facet value, with one grouped aggregate that runs
    * next to the page: 2 calls, 1 wave. Needs PostgREST aggregates.
@@ -26,6 +28,12 @@ interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends stri
   /** Named orderings. Add a unique column last for stable pages. */
   readonly sorts: { readonly [K in S]: OrderByArg<M, T>; };
   readonly defaultSort: NoInfer<S>;
+  /**
+   * `cursor` takes an `after` cursor instead of `page` and returns
+   * `nextCursor`: the cost of a page stays the same however deep it is, and
+   * rows inserted meanwhile don't shift it. Defaults to `offset`.
+   */
+  readonly pagination?: P;
   /** Defaults to 50. */
   readonly pageSize?: number;
   /** Defaults to 200. */
@@ -36,8 +44,10 @@ interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends stri
 interface ListQuery<S extends string, F extends string> {
   readonly q?: string;
   readonly sort: S;
-  /** 1-based. */
+  /** 1-based. Always 1 with cursor pagination. */
   readonly page: number;
+  /** Cursor pagination: the `nextCursor` of the previous page. */
+  readonly after?: string;
   readonly size: number;
   readonly facets: { readonly [K in F]?: readonly string[]; };
 }
@@ -46,6 +56,7 @@ interface ListQueryInput<S extends string, F extends string> {
   readonly q?: string;
   readonly sort?: S;
   readonly page?: number;
+  readonly after?: string;
   readonly size?: number;
   readonly facets?: { readonly [K in F]?: readonly string[]; };
 }
@@ -83,13 +94,14 @@ interface FacetInfo {
 /** Rows per facet value, keyed by facet and then by value (`UNSET` for empty). */
 type FacetCounts<F extends string> = { readonly [K in F]: Readonly<Record<string, number>>; };
 /** A page of a list; with `facetCounts: true`, also the counts per facet value. */
-type ListPage<R, F extends string, C extends boolean> = OffsetPage<R> & ([C] extends [true] ? {
+type ListPage<R, F extends string, C extends boolean, P extends ListPagination = "offset"> = ([P] extends ["cursor"] ? CursorPage<R> : OffsetPage<R>) & ([C] extends [true] ? {
   readonly facetCounts: FacetCounts<F>;
 } : [C] extends [false] ? unknown : {
   readonly facetCounts?: FacetCounts<F>;
 });
-interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extends string, F extends string, C extends boolean = false> {
+interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extends string, F extends string, C extends boolean = false, P extends ListPagination = "offset"> {
   readonly table: T;
+  readonly pagination: P;
   readonly defaults: ListQuery<S, F>;
   readonly facets: readonly FacetInfo[];
   /** Validates typed input or URL params. Also a Standard Schema (`schema`). */
@@ -100,13 +112,13 @@ interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extend
   /** `{ parse, serialize }` per URL key, for routers and nuqs (`list.nuqs(createParser)`). */
   readonly parsers: ListParsers<S, F>;
   nuqs<P>(createParser: (spec: ParserSpec<unknown>) => P): { readonly [K in keyof ListParsers<S, F>]: P; };
-  /** Repository arguments: `where`, `orderBy`, `page`, `size`, `count`. */
-  args(query: ListQuery<S, F>): OffsetPageArgs<M, T>;
+  /** Repository arguments: `where`, `orderBy`, `size`, and `page` and `count` or `after`. */
+  args(query: ListQuery<S, F>): [P] extends ["cursor"] ? CursorPageArgs<M, T> : OffsetPageArgs<M, T>;
   /**
    * Runs the list against a table, merging your `select`, `include`, `where`
    * and `count`. One request, plus one for `facetCounts`, always one wave.
    */
-  run<const A extends ListExtra<M, T> & FindExt<E, M, T>>(db: { readonly [K in T]: RepositoryOf<M, K, E>; }, query: ListQuery<S, F>, extra?: A): AsyncResult<ListPage<Payload<M, T, A>, F, C>>;
+  run<const A extends ListExtra<M, T> & FindExt<E, M, T>>(db: { readonly [K in T]: RepositoryOf<M, K, E>; }, query: ListQuery<S, F>, extra?: A): AsyncResult<ListPage<Payload<M, T, A>, F, C, P>>;
   /** OpenAPI 3.1 query parameters. */
   readonly openapi: readonly OpenApiParameter[];
   /** JSON Schema of the typed input, e.g. for MCP tool arguments. */
@@ -123,6 +135,7 @@ type ListParsers<S extends string, F extends string> = {
   readonly q: ParserSpec<string>;
   readonly sort: ParserSpec<S>;
   readonly page: ParserSpec<number>;
+  readonly after: ParserSpec<string>;
   readonly size: ParserSpec<number>;
 } & { readonly [K in F]: ParserSpec<readonly string[]>; };
 /**
@@ -131,7 +144,7 @@ type ListParsers<S extends string, F extends string> = {
  * OpenAPI parameters and a JSON Schema derived from the same definition.
  *
  * ```ts
- * export const customerList = defineListQuery(sb, 'customers', {
+ * export const customerList = defineListQuery(betterSupabase, 'customers', {
  *   search: ['name', 'kvk'],
  *   facets: { status: 'status' },
  *   sorts: { name: { name: 'asc' }, newest: [{ createdAt: 'desc' }, { id: 'asc' }] },
@@ -139,6 +152,6 @@ type ListParsers<S extends string, F extends string> = {
  * });
  * ```
  */
-declare function defineListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>, const S extends string, const F extends string = never, const C extends boolean = false>(sb: BetterSupabase<M, D, Fn, E>, table: T, config: ListQueryConfig<M, T, S, F, C>): ListDefinition<M, T, E, S, F, C>;
+declare function defineListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>, const S extends string, const F extends string = never, const C extends boolean = false, const P extends ListPagination = "offset">(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, config: ListQueryConfig<M, T, S, F, C, P>): ListDefinition<M, T, E, S, F, C, P>;
 //#endregion
-export { ListPage as a, ListQuery as c, ListSearchParams as d, OpenApiParameter as f, defineListQuery as h, ListExtra as i, ListQueryConfig as l, UNSET as m, FacetInfo as n, ListParseResult as o, ParserSpec as p, ListDefinition as r, ListParsers as s, FacetCounts as t, ListQueryInput as u };
+export { ListPage as a, ListParsers as c, ListQueryInput as d, ListSearchParams as f, defineListQuery as g, UNSET as h, ListExtra as i, ListQuery as l, ParserSpec as m, FacetInfo as n, ListPagination as o, OpenApiParameter as p, ListDefinition as r, ListParseResult as s, FacetCounts as t, ListQueryConfig as u };

package/dist/{index-CBDufH1M.d.ts → index-BBdvo-5d.d.ts}

@@ -1,61 +1,59 @@
-import { p as DbError } from "./result-CTkCZ6JA.js";
-import { Z as QuerySpec } from "./define-e3zI4_4g.js";
-import { i as BrowserAuth, t as AuthSnapshot } from "./index-D4v7sncu.js";
+import { p as DbError } from "./result-CqEsbgYs.js";
+import { Z as QuerySpec } from "./define-CRS2MRV3.js";
+import { i as ClientAuth, t as AuthSnapshot } from "./index-RlLXd8dL.js";
 import { n as TemplateValues } from "./template-mbvlysOo.js";
-import { t as AuthSession } from "./view-D1s0wa0T.js";
-import { a as LiveSource, g as Topic, h as SubscriptionStatus, p as SubscribeOptions, r as LiveCountSeed, u as EventSchemas, v as TopicHandlers, y as TopicMessage } from "./live-DJyZMD6w.js";
-import "./entitlements-Dng-ctuT.js";
-import "./session-C3LxnQ0e.js";
+import { t as AuthSession } from "./view-B64o81wp.js";
+import { a as LiveSource, g as Topic, h as SubscriptionStatus, p as SubscribeOptions, r as LiveCountSeed, u as EventSchemas, v as TopicHandlers, y as TopicMessage } from "./live-BHakSWWo.js";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { ReactNode } from "react";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 import { QueryClient } from "@tanstack/query-core";
-//#region src/react/index.d.ts
-/** The parts of `createBrowser()` the provider needs. */
-interface BrowserLike {
-  readonly sb: LiveSource;
+//#region src/react/hooks.d.ts
+/** The parts of `createClient()` the provider needs. */
+interface ClientLike {
+  readonly betterSupabase: LiveSource;
   readonly supabase: SupabaseClient;
-  readonly auth: BrowserAuth;
+  readonly auth: ClientAuth;
   readonly db: object;
   readonly queries: object;
 }
 interface BetterSupabaseProviderProps {
-  readonly browser: BrowserLike;
+  readonly client: ClientLike;
   /** better-supabase queries are removed when the user signs out or changes. */
   readonly queryClient?: QueryClient;
   readonly children?: ReactNode;
 }
-/** Provides the browser client to the hooks. */
+/** Provides the better-supabase client to the hooks. */
 declare function BetterSupabaseProvider(props: BetterSupabaseProviderProps): ReactNode;
 /** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
 declare function useAuth(): AuthSnapshot;
 declare function useSupabase(): SupabaseClient;
-interface BetterHooks<B extends BrowserLike> {
+interface BetterHooks<B extends ClientLike> {
   /** Repositories bound to the current session. Re-renders when the user changes. */
   readonly useDb: () => B["db"];
   /** TanStack Query option factories: `useQuery(useQueries().customers.findMany())`. */
   readonly useQueries: () => B["queries"];
   readonly useSupabase: () => SupabaseClient;
   readonly useAuth: () => AuthSnapshot;
-  /** `useSession()` typed by the browser's `sb.claims(schema)` and `sb.userMetadata(schema)`. */
+  /** `useSession()` typed by the client's `betterSupabase.claims(schema)` and `betterSupabase.userMetadata(schema)`. */
   readonly useSession: () => AuthSession<ClaimsOf<B>, ProfileOf<B>>;
 }
-/** The claims type of a browser's `sb.claims(schema)`, `unknown` without one. */
-type ClaimsOf<B extends BrowserLike> = B["sb"] extends {
+/** The claims type of a client's `betterSupabase.claims(schema)`, `unknown` without one. */
+type ClaimsOf<B extends ClientLike> = B["betterSupabase"] extends {
   readonly claimsSchema: StandardSchemaV1<unknown, infer C> | undefined;
 } ? C : unknown;
-/** The profile type of a browser's `sb.userMetadata(schema)`, `unknown` without one. */
-type ProfileOf<B extends BrowserLike> = B["sb"] extends {
+/** The profile type of a client's `betterSupabase.userMetadata(schema)`, `unknown` without one. */
+type ProfileOf<B extends ClientLike> = B["betterSupabase"] extends {
   readonly userMetadataSchema: StandardSchemaV1<unknown, infer P> | undefined;
 } ? P : unknown;
 /**
  * Hooks typed for your schema.
  *
  * ```ts
- * export const { useDb, useQueries, useAuth } = createHooks<typeof browser>();
+ * export const { useDb, useQueries, useAuth } = createHooks<typeof bs>();
  * ```
  */
-declare function createHooks<B extends BrowserLike>(): BetterHooks<B>;
+declare function createHooks<B extends ClientLike>(): BetterHooks<B>;
 interface BroadcastOptions extends Omit<SubscribeOptions, "onStatus"> {
   /**
    * Refetch after each message: table keys (every query that read one of
@@ -88,7 +86,7 @@ interface LiveQueryHookOptions {
  * resubscribes when the spec, tenant or user changes.
  *
  * ```ts
- * const spec = sb.spec.customers.findMany({ include: { notes: true } });
+ * const spec = betterSupabase.spec.customers.findMany({ include: { notes: true } });
  * const { data } = useQuery(q.$spec(spec));
  * useLiveQuery(spec);
  * ```
@@ -108,13 +106,13 @@ interface LiveCount {
 /**
  * A count that stays current: refetches only the `count` spec (a HEAD
  * request) after each debounced change to a table it reads, and after the
- * channel rejoins. Takes a spec or a `next.liveCount()` seed; pass `null` to
+ * channel rejoins. Takes a spec or a `bs.liveCount()` seed; pass `null` to
  * pause. Doesn't need a `QueryClient`.
  *
  * ```tsx
- * const { count } = useLiveCount(seed); // seed = await next.liveCount(spec)
+ * const { count } = useLiveCount(seed); // seed = await bs.liveCount(spec)
  * ```
  */
 declare function useLiveCount(source: QuerySpec<string, "count", number> | LiveCountSeed | null | undefined, options?: LiveCountHookOptions): LiveCount;
 //#endregion
-export { BrowserLike as a, LiveCountHookOptions as c, createHooks as d, useAuth as f, useSupabase as g, useLiveQuery as h, BroadcastOptions as i, LiveQueryHookOptions as l, useLiveCount as m, BetterSupabaseProvider as n, ClaimsOf as o, useBroadcast as p, BetterSupabaseProviderProps as r, LiveCount as s, BetterHooks as t, ProfileOf as u };
+export { ClaimsOf as a, LiveCountHookOptions as c, createHooks as d, useAuth as f, useSupabase as g, useLiveQuery as h, BroadcastOptions as i, LiveQueryHookOptions as l, useLiveCount as m, BetterSupabaseProvider as n, ClientLike as o, useBroadcast as p, BetterSupabaseProviderProps as r, LiveCount as s, BetterHooks as t, ProfileOf as u };