better-supabase 0.12.0 → 0.13.0

package/dist/list-query-Dx5cAqG6.d.ts

@@ -0,0 +1,223 @@
+import { D as ValidationIssue, t as AsyncResult } from "./result-mijqfoJN.js";
+import { B as TableKey, N as Row, a as AnyModels, i as AnyFunctions } from "./types-DmshMaXz.js";
+import { l as CountMode } from "./executor-C29668fO.js";
+import { Et as SelectArg, St as Payload, a as CursorPageArgs, bt as OrderByArg, h as OffsetPageArgs, i as CursorPage, kt as WhereInput, m as OffsetPage, pt as IncludeArg, t as BetterSupabase, u as FindExt, w as RepositoryOf } from "./define-D0LSXmUP.js";
+import { c as FilterFieldLabels, h as FilterQuery, o as FilterField, r as FilterClock, s as FilterFieldInfo, v as ListFilterConfig } from "./filter-query-C7qgRYYv.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#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>];
+/** `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 per facet that
+   * runs next to the page: one wave. Needs PostgREST aggregates.
+   */
+  readonly facetCounts?: C;
+  /**
+   * How the page total is counted. Defaults to `'planned'`, the planner's
+   * estimate.
+   */
+  readonly count?: CountMode;
+  /** Text columns matched case-insensitively (OR), or a full-text column. */
+  readonly search?: readonly TextColumn<M, T>[] | {
+    readonly fts: Column<M, T>;
+    readonly config?: string;
+  };
+  /**
+   * Filterable columns by URL key. Values are validated against enums and CHECK
+   * unions.
+   */
+  readonly facets?: { readonly [K in F]: Column<M, T>; };
+  /**
+   * Fields a filter tree (ReUI Filters' `FilterQuery`) may name, by field id.
+   * Each has a type and, optionally, the subset of its operators to allow.
+   */
+  readonly filters?: Readonly<Record<string, ListFilterConfig<Column<M, T>>>>;
+  /** Most nested group levels in a filter tree, the root included. Defaults to 4. */
+  readonly maxFilterDepth?: number;
+  /** Most rules in a filter tree. Defaults to 50. */
+  readonly maxFilterRules?: number;
+  /** 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 `cursor`; `offset`
+   * takes `page` and returns `total` and `pageCount`.
+   */
+  readonly pagination?: P;
+  /** Defaults to 50. */
+  readonly pageSize?: number;
+  /** Defaults to 200. */
+  readonly maxPageSize?: number;
+  /** Defaults to 200 characters. */
+  readonly maxSearchLength?: number;
+  /**
+   * Most values counted per facet; a facet with more lists its key in
+   * `facetCountsTruncated`. Defaults to 100.
+   */
+  readonly facetLimit?: number;
+}
+interface ListQuery<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort: S;
+  /** 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[]; };
+  /** The checked filter tree, without unfinished rules and empty groups. */
+  readonly filter?: FilterQuery;
+  /** The IANA time zone date filters resolve in, from `parse`'s options. */
+  readonly timeZone?: string;
+}
+/** Typed input (JSON APIs, actions, MCP tools). Everything is optional. */
+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[]; };
+  readonly filter?: FilterQuery;
+}
+/** URL input: `URLSearchParams` or a Next.js `searchParams` record. */
+type ListSearchParams = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+type ListParseResult<S extends string, F extends string> = {
+  readonly ok: true;
+  readonly value: ListQuery<S, F>;
+  readonly issues?: undefined;
+} | {
+  readonly ok: false;
+  readonly value?: undefined;
+  readonly issues: readonly ValidationIssue[];
+};
+interface ParserSpec<V> {
+  parse(value: string): V | null;
+  serialize(value: V): string;
+  /** Equality for object values, which nuqs uses to skip URL updates. */
+  eq?(a: V, b: V): boolean;
+}
+interface OpenApiParameter {
+  readonly name: string;
+  readonly in: "query";
+  readonly required: false;
+  readonly description: string;
+  readonly schema: Readonly<Record<string, unknown>>;
+  readonly style?: "form";
+  readonly explode?: boolean;
+}
+interface ListParseOptions {
+  /**
+   * IANA time zone that date filters resolve in, such as the request's.
+   * Defaults to `UTC`.
+   */
+  readonly timeZone?: string;
+}
+interface FacetInfo {
+  readonly key: string;
+  readonly column: string;
+  readonly nullable: boolean;
+  /** Allowed values when the column is an enum or CHECK union. */
+  readonly values?: readonly string[];
+}
+/** 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, P extends ListPagination = "cursor"> = ([P] extends ["cursor"] ? CursorPage<R> : OffsetPage<R>) & ([C] extends [true] ? FacetCountFields<F> : [C] extends [false] ? unknown : Partial<FacetCountFields<F>>);
+/** The facet fields of a page with `facetCounts: true`. */
+interface FacetCountFields<F extends string> {
+  readonly facetCounts: FacetCounts<F>;
+  /** Facets with more values than `facetLimit`, whose counts are cut. */
+  readonly facetCountsTruncated: readonly F[];
+}
+interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extends string, F extends string, C extends boolean = false, P extends ListPagination = "cursor"> {
+  readonly table: T;
+  readonly pagination: P;
+  readonly defaults: ListQuery<S, F>;
+  readonly facets: readonly FacetInfo[];
+  /** The checked `filters` config. */
+  readonly filters: readonly FilterFieldInfo[];
+  /** Validates typed input or URL params. Also a Standard Schema (`schema`). */
+  parse(input: ListQueryInput<S, F> | ListSearchParams | undefined, options?: ListParseOptions): ListParseResult<S, F>;
+  /** `FilterField` objects for ReUI Filters, with labels you can translate. */
+  filterFields(labels?: FilterFieldLabels): FilterField[];
+  /**
+   * The repository `where` of the query's filter tree; relative dates resolve
+   * against `clock.now`.
+   */
+  filterWhere(query: ListQuery<S, F>, clock?: Pick<FilterClock, "now">): WhereInput<M, T> | undefined;
+  readonly schema: StandardSchemaV1<ListQueryInput<S, F> | ListSearchParams | undefined, ListQuery<S, F>>;
+  /** URL params, leaving out defaults. */
+  toSearchParams(query: Partial<ListQuery<S, F>>): URLSearchParams;
+  /**
+   * `{ 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`, `size`, and `page` and `count` or
+   * `after`.
+   */
+  args(query: ListQuery<S, F>, clock?: Pick<FilterClock, "now">): [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 per facet 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, P>>;
+  /** OpenAPI 3.1 query parameters. */
+  readonly openapi: readonly OpenApiParameter[];
+  /** JSON Schema of the typed input, e.g. for MCP tool arguments. */
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+interface ListExtra<M extends AnyModels, T extends keyof M> {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  readonly where?: WhereInput<M, T>;
+  /** Overrides the config's `count` for this run. */
+  readonly count?: CountMode;
+}
+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>;
+  /**
+   * The filter tree as base64url JSON, when the list has `filters`; `parse`
+   * checks it.
+   */
+  readonly filter?: ParserSpec<FilterQuery>;
+} & { readonly [K in F]: ParserSpec<readonly string[]>; };
+/**
+ * A reusable list endpoint for one table: search, facets, sorts and pagination,
+ * validated from URL params or typed input, with URL parsers, OpenAPI
+ * parameters and a JSON Schema derived from the same definition.
+ *
+ * ```ts
+ * export const customerList = defineListQuery(
+ *   betterSupabase,
+ *   "customers",
+ *   {
+ *     search: ["name", "kvk"],
+ *     facets: { status: "status" },
+ *     sorts: {
+ *       name: { name: "asc" },
+ *       newest: [{ createdAt: "desc" }, { id: "asc" }],
+ *     },
+ *     defaultSort: "newest",
+ *   },
+ * );
+ * ```
+ */
+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 = "cursor">(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 { UNSET as _, ListExtra as a, ListParseOptions as c, ListQuery as d, ListQueryConfig as f, ParserSpec as g, OpenApiParameter as h, ListDefinition as i, ListParseResult as l, ListSearchParams as m, FacetCounts as n, ListPage as o, ListQueryInput as p, FacetInfo as r, ListPagination as s, FacetCountFields as t, ListParsers as u, defineListQuery as v };

package/dist/live-CZtRMh62.js

@@ -0,0 +1,246 @@
+import { t as refreshRealtimeAuth } from "./auth-DyF_LRxd.js";
+import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
+//#region src/realtime/live.ts
+/**
+* Topic a `realtime-tables` trigger broadcasts on:
+* `bs:t:<schema>.<table>[:<tenant>]`, or `bs:t:<schema>.<table>:u:<user>` for a
+* `realtime.users` table.
+*/
+function liveTopic(meta, table, tenant, user) {
+	const found = meta.tables[table];
+	if (!found) throw new TypeError(`better-supabase: unknown table "${table}"`);
+	const base = `bs:t:${found.schema}.${found.name}`;
+	if (meta.realtime?.[table]?.user) {
+		if (user === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per user; pass \`user\` to watch it`);
+		return `${base}:u:${user}`;
+	}
+	if (!meta.realtime?.[table]?.tenant) return base;
+	if (tenant === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per tenant; pass \`tenant\` to watch it`);
+	return `${base}:${tenant}`;
+}
+const channels = /* @__PURE__ */ new WeakMap();
+function join(client, topic, listener, onStatus) {
+	let byTopic = channels.get(client);
+	if (!byTopic) {
+		byTopic = /* @__PURE__ */ new Map();
+		channels.set(client, byTopic);
+	}
+	let shared = byTopic.get(topic);
+	if (!shared) {
+		const channel = client.channel(topic, { config: { private: true } });
+		const listeners = /* @__PURE__ */ new Set();
+		const statuses = /* @__PURE__ */ new Set();
+		channel.on("broadcast", { event: "change" }, () => {
+			for (const notify of listeners) notify();
+		});
+		let joined = false;
+		const evict = () => {
+			if (byTopic.get(topic) !== entry) return;
+			byTopic.delete(topic);
+			client.removeChannel(channel);
+		};
+		const ready = (async () => {
+			await refreshRealtimeAuth(client);
+			await new Promise((resolve, reject) => {
+				channel.subscribe((status, error) => {
+					switch (status) {
+						case REALTIME_SUBSCRIBE_STATES.SUBSCRIBED:
+							if (joined) {
+								for (const notify of listeners) notify();
+								for (const notify of statuses) notify("subscribed");
+							}
+							joined = true;
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CLOSED:
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR:
+						case REALTIME_SUBSCRIBE_STATES.TIMED_OUT: {
+							const failure = error ?? /* @__PURE__ */ new Error(`Realtime ${status.toLowerCase()} on ${topic}`);
+							if (joined) for (const notify of statuses) notify("error", failure);
+							reject(failure);
+							if (!joined) evict();
+							return;
+						}
+						default: reject(/* @__PURE__ */ new Error(`Unknown realtime status ${String(status)}`));
+					}
+				});
+			});
+		})();
+		ready.catch(() => void 0);
+		const entry = {
+			channel,
+			listeners,
+			statuses,
+			ready
+		};
+		shared = entry;
+		byTopic.set(topic, entry);
+	}
+	const current = shared;
+	current.listeners.add(listener);
+	if (onStatus) current.statuses.add(onStatus);
+	let left = false;
+	return {
+		ready: current.ready,
+		leave: async () => {
+			if (left) return;
+			left = true;
+			current.listeners.delete(listener);
+			if (onStatus) current.statuses.delete(onStatus);
+			if (current.listeners.size > 0) return;
+			await new Promise((resolve) => {
+				setTimeout(resolve, 0);
+			});
+			if (current.listeners.size > 0 || byTopic.get(topic) !== current) return;
+			byTopic.delete(topic);
+			await client.removeChannel(current.channel);
+		}
+	};
+}
+/**
+* Calls `onChange` when a table the spec reads changes, so you can refetch.
+* Needs the `realtime-tables` SQL module and the tables in `realtime.tables`.
+* Live queries on the same client share one channel per table, so any number of
+* them can run at once.
+*
+* ```ts
+* using live = liveQuery(betterSupabase, supabase, spec, {
+*   onChange: () => refetch(),
+* });
+* ```
+*/
+function liveQuery(betterSupabase, client, spec, options) {
+	const touched = Array.isArray(spec) ? spec : betterSupabase.tablesOf(spec);
+	const tables = touched.filter((table) => betterSupabase.meta.realtime?.[table]);
+	const unwatched = touched.filter((table) => !betterSupabase.meta.realtime?.[table]);
+	const debounceMs = options.debounceMs ?? 100;
+	const changed = /* @__PURE__ */ new Set();
+	let timer;
+	let closed = false;
+	const flush = () => {
+		timer = void 0;
+		if (closed || changed.size === 0) return;
+		const batch = [...changed];
+		changed.clear();
+		options.onChange(batch);
+	};
+	const onTableChange = (table) => () => {
+		changed.add(table);
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(flush, debounceMs);
+	};
+	const failed = /* @__PURE__ */ new Set();
+	const onChannelStatus = (topic) => (status, error) => {
+		if (closed) return;
+		if (status === "error") failed.add(topic);
+		else failed.delete(topic);
+		if (status === "error") options.onStatus?.("error", error);
+		else if (failed.size === 0) options.onStatus?.("subscribed");
+	};
+	const topics = tables.map((table) => ({
+		table,
+		topic: liveTopic(betterSupabase.meta, table, options.tenant, options.user)
+	}));
+	const joinAll = () => topics.map(({ table, topic }) => join(client, topic, onTableChange(table), onChannelStatus(topic)));
+	let memberships = joinAll();
+	let retryTimer;
+	let delay = 1e3;
+	const settle = (attempt) => Promise.all(attempt.map((member) => member.ready)).then(() => {
+		if (!closed && tables.length > 0) options.onStatus?.("subscribed");
+	}, (cause) => {
+		const error = cause instanceof Error ? cause : new Error(String(cause));
+		if (!closed) {
+			options.onStatus?.("error", error);
+			if (options.retry !== false) scheduleRetry(attempt);
+		}
+		throw error;
+	});
+	const scheduleRetry = (attempt) => {
+		retryTimer = setTimeout(() => {
+			retryTimer = void 0;
+			if (closed || attempt !== memberships) return;
+			Promise.all(attempt.map((member) => member.leave()));
+			memberships = joinAll();
+			options.onStatus?.("joining");
+			settle(memberships).then(() => {
+				if (closed) return;
+				for (const table of tables) changed.add(table);
+				flush();
+			}, () => void 0);
+		}, delay);
+		delay = Math.min(delay * 2, 3e4);
+	};
+	options.onStatus?.(tables.length === 0 ? "closed" : "joining");
+	const ready = settle(memberships);
+	ready.catch(() => void 0);
+	const unsubscribe = async () => {
+		if (closed) return;
+		closed = true;
+		if (timer !== void 0) clearTimeout(timer);
+		if (retryTimer !== void 0) clearTimeout(retryTimer);
+		await Promise.all(memberships.map((member) => member.leave()));
+		options.onStatus?.("closed");
+	};
+	return {
+		tables,
+		unwatched,
+		ready,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+/**
+* Keeps a count current: runs the `count` spec (a HEAD request) now, after each
+* debounced change to a table it reads, and after the channel rejoins.
+* Responses that arrive out of order are dropped.
+*
+* ```ts
+* using live = liveCount(
+*   betterSupabase,
+*   supabase,
+*   db,
+*   betterSupabase.spec.notes.count(),
+*   { onCount: (count) => render(count) },
+* );
+* ```
+*/
+function liveCount(betterSupabase, client, db, spec, options) {
+	let latest = 0;
+	let closed = false;
+	const refetch = () => {
+		latest += 1;
+		const call = latest;
+		Promise.resolve(db.$run(spec)).then((result) => {
+			if (closed || call !== latest) return;
+			if (result.ok) options.onCount(result.data);
+			else options.onError?.(result.error);
+		});
+	};
+	const live = liveQuery(betterSupabase, client, spec, {
+		onChange: refetch,
+		...options.tenant === void 0 ? {} : { tenant: options.tenant },
+		...options.user === void 0 ? {} : { user: options.user },
+		...options.debounceMs === void 0 ? {} : { debounceMs: options.debounceMs },
+		...options.onStatus ? { onStatus: options.onStatus } : {}
+	});
+	if (options.immediate ?? true) refetch();
+	const since = options.since;
+	if (since !== void 0) live.ready.then(() => {
+		if (!closed && Date.now() - since > 1e3) refetch();
+	}, () => void 0);
+	const unsubscribe = async () => {
+		closed = true;
+		await live.unsubscribe();
+	};
+	return {
+		...live,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+//#endregion
+export { liveQuery as n, liveTopic as r, liveCount as t };

package/dist/management-wtecfrNf.d.ts

@@ -0,0 +1,57 @@
+//#region src/create/supabase/management.d.ts
+declare const SMART_REGIONS: readonly ["americas", "emea", "apac"];
+type SmartRegion = (typeof SMART_REGIONS)[number];
+/** A Supabase project ref: lowercase letters and digits, never a path. */
+declare function isProjectRef(value: string): boolean;
+interface SupabaseOrganization {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+}
+interface SupabaseProject {
+  readonly ref: string;
+  readonly name: string;
+  readonly organization_slug: string;
+  readonly region: string;
+  readonly status: string;
+}
+interface SupabaseLint {
+  readonly name: string;
+  readonly title: string;
+  readonly level: "ERROR" | "WARN" | "INFO";
+  readonly detail?: string | undefined;
+  readonly remediation?: string | undefined;
+}
+/**
+ * A Management API call that failed; `status` is the HTTP status, 0 for a bad
+ * response.
+ */
+declare class ManagementError extends Error {
+  override readonly name = "ManagementError";
+  readonly status: number;
+  constructor(message: string, status: number);
+}
+/** The Management API calls the deploy flow makes. */
+interface ManagementClient {
+  organizations(): Promise<SupabaseOrganization[]>;
+  projects(): Promise<SupabaseProject[]>;
+  createProject(input: {
+    name: string;
+    organizationSlug: string;
+    region: SmartRegion;
+    dbPass: string;
+  }): Promise<SupabaseProject>;
+  project(ref: string): Promise<SupabaseProject>;
+  databaseHealthy(ref: string): Promise<boolean>;
+  publicTableCount(ref: string): Promise<number>;
+  applyMigration(ref: string, name: string, query: string): Promise<void>;
+  securityLints(ref: string): Promise<readonly SupabaseLint[]>;
+}
+/**
+ * The Management API calls the deploy dialog makes, with the user's OAuth
+ * access token. Responses are parsed, and every failure is a
+ * `ManagementError`.
+ */
+declare function managementClient(accessToken: string, fetchImpl?: typeof fetch): ManagementClient;
+//#endregion
+export { SupabaseLint as a, isProjectRef as c, SmartRegion as i, managementClient as l, ManagementError as n, SupabaseOrganization as o, SMART_REGIONS as r, SupabaseProject as s, ManagementClient as t };