better-supabase 0.0.0 → 0.1.0

package/dist/index-DRid0qIv.d.ts

@@ -0,0 +1,76 @@
+import { E as SchemaMeta } from "./types-C2fslP1z.js";
+import { f as OpenApiParameter } from "./index-JXHBuS53.js";
+//#region src/openapi/index.d.ts
+type Json = Record<string, unknown>;
+type ResourceOperation = "list" | "get" | "create" | "update" | "delete";
+interface ResourceOptions {
+  /** Defaults to every operation for tables, `list` and `get` for views. */
+  readonly operations?: readonly ResourceOperation[];
+  /** Parameters for `list`, from `defineListQuery`. */
+  readonly list?: {
+    readonly openapi: readonly OpenApiParameter[];
+  };
+  /** Path of the collection. Defaults to `/<table>`. */
+  readonly path?: string;
+  readonly tag?: string;
+  readonly description?: string;
+}
+interface OpenApiOptions {
+  readonly info: {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+  };
+  readonly servers?: readonly {
+    readonly url: string;
+    readonly description?: string;
+  }[];
+  /** Prefix for every path, e.g. `/api`. */
+  readonly basePath?: string;
+  /** Tables to publish, by app key. */
+  readonly resources: Readonly<Record<string, ResourceOptions | true>>;
+  /**
+   * Security schemes. `bearer` is a Supabase access token; `oauth2` uses the
+   * Supabase OAuth server and needs `supabaseUrl`. Defaults to `['bearer']`.
+   */
+  readonly security?: readonly ("bearer" | "oauth2")[];
+  readonly supabaseUrl?: string;
+  /** Tables with a JSON column typed in `better-supabase.config.ts`. */
+  readonly json?: Readonly<Record<string, unknown>>;
+}
+interface OpenApiDocument {
+  readonly openapi: string;
+  readonly info: OpenApiOptions["info"];
+  readonly jsonSchemaDialect: string;
+  readonly servers?: OpenApiOptions["servers"];
+  readonly tags: readonly {
+    readonly name: string;
+    readonly description?: string;
+  }[];
+  readonly paths: Readonly<Record<string, Json>>;
+  readonly components: {
+    readonly schemas: Readonly<Record<string, Json>>;
+    readonly responses: Readonly<Record<string, Json>>;
+    readonly securitySchemes: Readonly<Record<string, Json>>;
+  };
+  readonly security: readonly Readonly<Record<string, readonly string[]>>[];
+}
+/** JSON Schema for RFC 9457 Problem Details as better-supabase sends them. */
+declare const PROBLEM_SCHEMA: Json;
+/**
+ * An OpenAPI 3.1 document for REST resources over your tables, with schemas
+ * from the generated metadata, list-query parameters, Supabase security
+ * schemes and Problem Details errors.
+ *
+ * ```ts
+ * const doc = createOpenApi(sb, {
+ *   info: { title: 'CRM API', version: '1.0.0' },
+ *   resources: { customers: { list: customerList }, notes: { operations: ['list', 'get'] } },
+ * });
+ * ```
+ */
+declare function createOpenApi(sb: {
+  readonly meta: SchemaMeta;
+}, options: OpenApiOptions): OpenApiDocument;
+//#endregion
+export { ResourceOptions as a, ResourceOperation as i, OpenApiOptions as n, createOpenApi as o, PROBLEM_SCHEMA as r, OpenApiDocument as t };

package/dist/index-Dup-nSe9.d.ts

@@ -0,0 +1,117 @@
+import { N as UniqueWhere, P as Update, h as Insert, k as TableKey, n as AnyModels, t as AnyFunctions, y as PrimaryKeyValue } from "./types-C2fslP1z.js";
+import { _ as DbException } from "./result-CTkCZ6JA.js";
+import { C as FindExt, Ct as WhereInput, M as UpsertArgs, N as WriteArgs, S as DeleteExt, T as OffsetPageArgs, X as InferResult, Z as QuerySpec, _ as CursorPage, it as AggregateResult, j as UpdateArgs, k as Returned, l as CacheAdapter, lt as FindFirstArgs, rt as AggregateArgs, st as CountArgs, t as BetterSupabase, ut as FindManyArgs, v as CursorPageArgs, vt as Payload, w as OffsetPage, x as DeleteArgs, y as Db, yt as ReadArgs } from "./define-CTfWw-SS.js";
+import { DataTag, InfiniteData, QueryClient, SkipToken } from "@tanstack/query-core";
+//#region src/query/invalidate.d.ts
+/** Carried by every better-supabase query: the tables whose changes make it stale. */
+interface BetterQueryMeta {
+  readonly bsTables: readonly string[];
+  readonly [key: string]: unknown;
+}
+/**
+ * Invalidates every query that read one of `tables`: better-supabase queries
+ * by their `meta.bsTables`, and other `['bs', table, ...]` keys by prefix.
+ */
+declare function invalidateTables(client: QueryClient, tables: readonly string[]): Promise<void>;
+//#endregion
+//#region src/query/index.d.ts
+type QueryKeyOf<T> = DataTag<readonly unknown[], T, DbException>;
+type QueryFnOf<T> = ((context: {
+  readonly signal: AbortSignal;
+}) => Promise<T>) | SkipToken;
+/** Options for `useQuery`, `createQuery`, `injectQuery`, `queryClient.fetchQuery` and `prefetchQuery`. */
+interface QueryOptionsOf<T> {
+  readonly queryKey: QueryKeyOf<T>;
+  readonly queryFn: QueryFnOf<T>;
+  readonly meta: BetterQueryMeta;
+  readonly staleTime?: number;
+}
+/** Options for infinite queries over cursor (`string | null`) or offset (`number`) pages. */
+interface InfiniteOptionsOf<P, Param> {
+  readonly queryKey: DataTag<readonly unknown[], InfiniteData<P>, DbException>;
+  readonly queryFn: (context: {
+    readonly signal: AbortSignal;
+    readonly pageParam: Param;
+  }) => Promise<P>;
+  readonly initialPageParam: Param;
+  readonly getNextPageParam: (last: P) => Param | undefined;
+  readonly meta: BetterQueryMeta;
+  readonly staleTime?: number;
+}
+/** Options for `useMutation`. Invalidates every query that read a changed table. */
+interface MutationOptionsOf<V, R> {
+  readonly mutationKey: readonly unknown[];
+  readonly mutationFn: (variables: V) => Promise<R>;
+  readonly onSuccess: (data: R, variables: V, onMutateResult: unknown, context: {
+    readonly client: QueryClient;
+  }) => Promise<void>;
+}
+interface TableQueries<M extends AnyModels, T extends TableKey<M>, E> {
+  /** Prefix of every key for this table's own queries. */
+  readonly key: readonly ["bs", T];
+  findMany<const A extends FindManyArgs<M, T> & FindExt<E, M, T>>(args?: A | SkipToken): QueryOptionsOf<Payload<M, T, A>[]>;
+  findFirst<const A extends FindFirstArgs<M, T> & FindExt<E, M, T>>(args?: A | SkipToken): QueryOptionsOf<Payload<M, T, A> | null>;
+  findUnique<const A extends ReadArgs<M, T> & {
+    readonly where: UniqueWhere<M, T>;
+  } & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<Payload<M, T, A> | null>;
+  findById<const A extends ReadArgs<M, T> & FindExt<E, M, T>>(id: PrimaryKeyValue<M, T> | SkipToken, args?: A): QueryOptionsOf<Payload<M, T, A>>;
+  count(args?: (CountArgs<M, T> & FindExt<E, M, T>) | SkipToken): QueryOptionsOf<number>;
+  aggregate<const A extends AggregateArgs<M, T> & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<AggregateResult<M, T, A>>;
+  exists(args?: ({
+    readonly where?: WhereInput<M, T>;
+  } & FindExt<E, M, T>) | SkipToken): QueryOptionsOf<boolean>;
+  paginate<const A extends OffsetPageArgs<M, T> & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<OffsetPage<Payload<M, T, A>>>;
+  /** Cursor pages for `useInfiniteQuery`. */
+  infinite<const A extends Omit<CursorPageArgs<M, T>, "after"> & FindExt<E, M, T>>(args: A): InfiniteOptionsOf<CursorPage<Payload<M, T, A>>, string | null>;
+  /** Numbered pages for `useInfiniteQuery`, starting at `args.page` (default 1). */
+  infinitePages<const A extends OffsetPageArgs<M, T> & FindExt<E, M, T>>(args: A): InfiniteOptionsOf<OffsetPage<Payload<M, T, A>>, number>;
+  create<const A extends WriteArgs<M, T> = {}>(args?: A): MutationOptionsOf<Insert<M, T>, Returned<M, T, A>>;
+  update<const A extends UpdateArgs<M, T> = {}>(args?: A): MutationOptionsOf<{
+    readonly id: PrimaryKeyValue<M, T>;
+    readonly patch: Update<M, T>;
+  }, Returned<M, T, A>>;
+  upsert<const A extends UpsertArgs<M, T> = {}>(args?: A): MutationOptionsOf<Insert<M, T>, Returned<M, T, A>>;
+  delete(args?: DeleteArgs & DeleteExt<E, M, T>): MutationOptionsOf<PrimaryKeyValue<M, T>, void>;
+}
+type RpcArgsOf<F extends AnyFunctions, N extends keyof F> = F[N]["Args"];
+interface QueryHelpers<M extends AnyModels, F extends AnyFunctions> {
+  /** Prefix of every better-supabase key. */
+  readonly key: readonly ["bs"];
+  /** Query options for a `QuerySpec`, for example one sent from a Server Component. */
+  $spec<S extends QuerySpec<TableKey<M>>>(spec: S | SkipToken): QueryOptionsOf<InferResult<S>>;
+  /** Fetches a spec into `queryClient` for server rendering and hydration. */
+  $prefetch(queryClient: QueryClient, spec: QuerySpec<TableKey<M>>): Promise<void>;
+  /** Query options for a database function. `tables` lists what it reads, for invalidation. */
+  $rpc<N extends Extract<keyof F, string>>(name: N, args?: RpcArgsOf<F, N> | SkipToken, options?: {
+    readonly tables?: readonly TableKey<M>[];
+  }): QueryOptionsOf<F[N]["Returns"]>;
+  /** Mutation options for a database function; invalidates what `sb.defineRpc` declared. */
+  $rpcMutation<N extends Extract<keyof F, string>>(name: N): MutationOptionsOf<RpcArgsOf<F, N>, F[N]["Returns"]>;
+}
+type Queries<M extends AnyModels, E, F extends AnyFunctions = AnyFunctions> = { readonly [T in TableKey<M>]: TableQueries<M, T, E>; } & QueryHelpers<M, F>;
+interface CreateQueriesOptions {
+  /**
+   * `staleTime` for every query option. Set it above zero when rendering on
+   * the server so hydrated data isn't refetched on mount.
+   */
+  readonly staleTime?: number;
+}
+/**
+ * TanStack Query option factories for every table, framework-neutral: pass
+ * them to `useQuery` (React), `createQuery` (Svelte, Solid), `useQuery`
+ * (Vue) or `injectQuery` (Angular). Payload types flow into the cache, errors
+ * are `DbException`s, and mutations invalidate every query that read a
+ * changed table.
+ *
+ * ```ts
+ * const q = createQueries(sb, () => browser.db);
+ * const { data } = useQuery(q.customers.findMany({ select: ['id', 'name'] }));
+ * ```
+ */
+declare function createQueries<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, db: Db<M, F, E, unknown> | (() => Db<M, F, E, unknown>), options?: CreateQueriesOptions): Queries<M, E, F>;
+/** Invalidates every query that read a table in the target. */
+declare function queryCache(client: QueryClient): CacheAdapter;
+/** Invalidates affected queries for every mutation and declared RPC `sb` performs in this runtime. */
+declare function invalidateOnMutation<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, client: QueryClient): () => void;
+//#endregion
+export { QueryHelpers as a, TableQueries as c, queryCache as d, BetterQueryMeta as f, Queries as i, createQueries as l, InfiniteOptionsOf as n, QueryKeyOf as o, invalidateTables as p, MutationOptionsOf as r, QueryOptionsOf as s, CreateQueriesOptions as t, invalidateOnMutation as u };

package/dist/index-Dy6kuF0P.d.ts

@@ -0,0 +1,71 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { SupabaseEnv } from "@supabase/server";
+//#region src/env/index.d.ts
+/** Validated Supabase settings. Only `publicEnv()` of it is safe to ship to a browser. */
+interface BetterSupabaseEnv {
+  readonly url: string;
+  readonly publishableKey: string;
+  readonly secretKey?: string;
+  /** Named secret keys from `SUPABASE_SECRET_KEYS`, including `default` when `secretKey` is set. */
+  readonly secretKeys?: Readonly<Record<string, string>>;
+  /** `SUPABASE_JWKS_URL`, or `<url>/auth/v1/.well-known/jwks.json`. */
+  readonly jwksUrl: URL;
+  /** Direct Postgres connection string (`SUPABASE_DB_URL` / `DATABASE_URL`). */
+  readonly dbUrl?: string;
+  /** Project ref for hosted projects (`<ref>.supabase.co`). */
+  readonly projectRef?: string;
+  /** `SUPABASE_READ_URL`: a read replica or the `<ref>-all` load balancer, for reads. */
+  readonly readUrl?: string;
+}
+interface PublicEnv {
+  readonly url: string;
+  readonly publishableKey: string;
+}
+type EnvSource = Readonly<Record<string, string | undefined>>;
+interface EnvIssue {
+  /** The variable names that were checked, first one preferred. */
+  readonly variables: readonly string[];
+  readonly message: string;
+}
+interface EnvOptions {
+  /** Settings that must be present. `url` and `publishableKey` always are. */
+  readonly require?: readonly ("secretKey" | "dbUrl")[];
+}
+type EnvResult = {
+  readonly ok: true;
+  readonly env: BetterSupabaseEnv;
+  readonly issues?: undefined;
+} | {
+  readonly ok: false;
+  readonly env?: undefined;
+  readonly issues: readonly EnvIssue[];
+};
+declare const ENV_VARIABLES: {
+  readonly url: readonly string[];
+  readonly publishableKey: readonly string[];
+  readonly secretKey: readonly string[];
+  readonly dbUrl: readonly string[];
+  readonly jwksUrl: readonly string[];
+  readonly readUrl: readonly string[];
+};
+declare class EnvValidationError extends Error {
+  override readonly name = "EnvValidationError";
+  readonly issues: readonly EnvIssue[];
+  constructor(issues: readonly EnvIssue[]);
+}
+/**
+ * Reads and validates Supabase settings. Accepts the `SUPABASE_`,
+ * `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, `EXPO_PUBLIC_` and `NUXT_PUBLIC_`
+ * spellings. Issues name variables, never values.
+ */
+declare function parseEnv(source: EnvSource, options?: EnvOptions): EnvResult;
+/** Like `parseEnv`, but throws `EnvValidationError`. Reads `process.env` by default. */
+declare function loadEnv(source?: EnvSource, options?: EnvOptions): BetterSupabaseEnv;
+/** The env validator as a Standard Schema, for t3-env, framework config or any validator slot. */
+declare function envSchema(options?: EnvOptions): StandardSchemaV1<EnvSource, BetterSupabaseEnv>;
+/** The parts that are safe in client bundles. */
+declare function publicEnv(env: BetterSupabaseEnv): PublicEnv;
+/** Converts to `@supabase/server`'s `SupabaseEnv` (the `env` option of `withSupabase`). */
+declare function toServerEnv(env: BetterSupabaseEnv): SupabaseEnv;
+//#endregion
+export { EnvResult as a, PublicEnv as c, parseEnv as d, publicEnv as f, EnvOptions as i, envSchema as l, ENV_VARIABLES as n, EnvSource as o, toServerEnv as p, EnvIssue as r, EnvValidationError as s, BetterSupabaseEnv as t, loadEnv as u };

package/dist/index-Hf8PP9sP.d.ts

@@ -0,0 +1,116 @@
+import { p as DbError } from "./result-CTkCZ6JA.js";
+import { Z as QuerySpec } from "./define-CTfWw-SS.js";
+import { i as BrowserAuth, t as AuthSnapshot } from "./index-Sw43J8HG.js";
+import { n as TemplateValues } from "./template-mbvlysOo.js";
+import { t as AuthSession } from "./view-B0ltUmTi.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-6b9i72Ux.js";
+import "./entitlements-BBg61DQZ.js";
+import "./session-C3osL21k.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;
+  readonly supabase: SupabaseClient;
+  readonly auth: BrowserAuth;
+  readonly db: object;
+  readonly queries: object;
+}
+interface BetterSupabaseProviderProps {
+  readonly browser: BrowserLike;
+  /** 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. */
+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> {
+  /** 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()` with the claims typed by the browser's `sb.claims(schema)`. */
+  readonly useSession: () => AuthSession<ClaimsOf<B>>;
+}
+/** The claims type of a browser's `sb.claims(schema)`, `unknown` without one. */
+type ClaimsOf<B extends BrowserLike> = B["sb"] extends {
+  readonly claimsSchema: StandardSchemaV1<unknown, infer C> | undefined;
+} ? C : unknown;
+/**
+ * Hooks typed for your schema.
+ *
+ * ```ts
+ * export const { useDb, useQueries, useAuth } = createHooks<typeof browser>();
+ * ```
+ */
+declare function createHooks<B extends BrowserLike>(): BetterHooks<B>;
+interface BroadcastOptions extends Omit<SubscribeOptions, "onStatus"> {
+  /**
+   * Refetch after each message: table keys (every query that read one of
+   * them), or a function returning query keys. Needs `queryClient` on the
+   * provider.
+   */
+  readonly invalidate?: readonly string[] | ((message: TopicMessage) => readonly (readonly unknown[])[]);
+}
+/**
+ * Subscribes to a topic while mounted. Pass `null` values to pause. It
+ * resubscribes when the topic or the signed-in user changes.
+ *
+ * ```ts
+ * useBroadcast(customersTopic, orgId ? { orgId } : null, {}, { invalidate: ['customers'] });
+ * ```
+ */
+declare function useBroadcast<P extends string, E extends EventSchemas>(topic: Topic<P, E>, values: TemplateValues<P> | null | undefined, handlers?: TopicHandlers<E>, options?: BroadcastOptions): SubscriptionStatus;
+interface LiveQueryHookOptions {
+  /**
+   * Tenant for tenant-scoped tables. Defaults to the `org_id` claim
+   * (top-level or in `app_metadata`).
+   */
+  readonly tenant?: string;
+  /** Defaults to 100 ms. */
+  readonly debounceMs?: number;
+}
+/**
+ * Keeps a query fresh: invalidates every cached query that read a table the
+ * spec touches whenever one of them changes. Pass `null` to pause. It
+ * resubscribes when the spec, tenant or user changes.
+ *
+ * ```ts
+ * const spec = sb.spec.customers.findMany({ include: { notes: true } });
+ * const { data } = useQuery(q.$spec(spec));
+ * useLiveQuery(spec);
+ * ```
+ */
+declare function useLiveQuery(spec: QuerySpec | null | undefined, options?: LiveQueryHookOptions): SubscriptionStatus;
+interface LiveCountHookOptions extends LiveQueryHookOptions {
+  /** The count to show before the first fetch, e.g. from the server. */
+  readonly initial?: number;
+}
+interface LiveCount {
+  /** `undefined` until the first count arrives. */
+  readonly count: number | undefined;
+  readonly status: SubscriptionStatus;
+  /** The last failed refetch; the previous count stays. */
+  readonly error: DbError | undefined;
+}
+/**
+ * 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
+ * pause. Doesn't need a `QueryClient`.
+ *
+ * ```tsx
+ * const { count } = useLiveCount(seed); // seed = await next.liveCount(spec)
+ * ```
+ */
+declare function useLiveCount(source: QuerySpec<string, "count", number> | LiveCountSeed | null | undefined, options?: LiveCountHookOptions): LiveCount;
+//#endregion
+export { BrowserLike as a, LiveCountHookOptions as c, useAuth as d, useBroadcast as f, useSupabase as h, BroadcastOptions as i, LiveQueryHookOptions as l, useLiveQuery as m, BetterSupabaseProvider as n, ClaimsOf as o, useLiveCount as p, BetterSupabaseProviderProps as r, LiveCount as s, BetterHooks as t, createHooks as u };

package/dist/index-JXHBuS53.d.ts

@@ -0,0 +1,144 @@
+import { k as TableKey, n as AnyModels, t as AnyFunctions, w as Row } from "./types-C2fslP1z.js";
+import { l as CountMode } from "./executor-Bazhgsgq.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-CTfWw-SS.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/list/index.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> {
+  /**
+   * Also count rows per facet value, with one grouped aggregate that runs
+   * next to the page: 2 calls, 1 wave. Needs PostgREST aggregates.
+   */
+  readonly facetCounts?: C;
+  /** How the page total is counted. Defaults to `'exact'`. */
+  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>; };
+  /** Named orderings. Add a unique column last for stable pages. */
+  readonly sorts: { readonly [K in S]: OrderByArg<M, T>; };
+  readonly defaultSort: NoInfer<S>;
+  /** Defaults to 50. */
+  readonly pageSize?: number;
+  /** Defaults to 200. */
+  readonly maxPageSize?: number;
+  /** Defaults to 200 characters. */
+  readonly maxSearchLength?: number;
+}
+interface ListQuery<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort: S;
+  /** 1-based. */
+  readonly page: number;
+  readonly size: number;
+  readonly facets: { readonly [K in F]?: readonly 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 size?: number;
+  readonly facets?: { readonly [K in F]?: readonly string[]; };
+}
+/** 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;
+}
+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 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> = 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> {
+  readonly table: T;
+  readonly defaults: ListQuery<S, F>;
+  readonly facets: readonly FacetInfo[];
+  /** Validates typed input or URL params. Also a Standard Schema (`schema`). */
+  parse(input: ListQueryInput<S, F> | ListSearchParams | undefined): ListParseResult<S, F>;
+  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`, `page`, `size`, `count`. */
+  args(query: ListQuery<S, F>): 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>>;
+  /** 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 size: ParserSpec<number>;
+} & { 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(sb, '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>(sb: BetterSupabase<M, D, Fn, E>, table: T, config: ListQueryConfig<M, T, S, F, C>): ListDefinition<M, T, E, S, F, C>;
+//#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 };