better-supabase 0.7.1 → 0.9.0

package/dist/index-DunNRdnT.d.ts

@@ -1,300 +0,0 @@
-import { E as ValidationIssue, b as DbError, f as Result, t as AsyncResult } from "./result-D7y2fT87.js";
-import { L as TableKey, M as Row, P as SchemaMeta, a as AnyModels, i as AnyFunctions, r as AccessTopicPolicy } from "./types-6BdhkmZe.js";
-import { it as QuerySpec, t as BetterSupabase } from "./define-CJJkkr1-.js";
-import { n as TemplateValues, t as TemplateParams } from "./template-CwO38Do8.js";
-import { t as AuthorizationFunctions } from "./authorization-BFCqamMs.js";
-import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/realtime/topic.d.ts
-type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
-/** `true`, or a schema every tracked presence state is validated against. */
-type PresenceSchema = boolean | StandardSchemaV1;
-interface TopicOptions<E extends EventSchemas, R extends PresenceSchema = PresenceSchema> {
-  /** Name used for generated policies and functions. Defaults to the template's literal parts. */
-  readonly name?: string;
-  /** Payload schemas per event. Incoming and outgoing payloads are validated. */
-  readonly events?: E;
-  /** Private channels are authorized by `realtime.messages` policies. Defaults to `true`. */
-  readonly private?: boolean;
-  /**
-   * Tenant check for the generated policy. Defaults to `{organizationId}` against
-   * `tenant_id` / `app_metadata.tenant_id` when the template has `{organizationId}`.
-   */
-  readonly tenant?: false | {
-    readonly param?: string;
-    readonly claim?: string | readonly string[];
-    readonly sql?: string;
-  };
-  /** Owner check. Defaults to `{userId}` against `auth.uid()` when the template has `{userId}`. */
-  readonly owner?: false | {
-    readonly param?: string;
-  };
-  /**
-   * Authorize with the SQL modules' access contract instead of the tenant
-   * claim: `tenant_ids_with(receive)` on the tenant segment (or
-   * `is_platform` for `scope: 'platform'`), or the `sql` templates it is
-   * given, and `send` for broadcasting.
-   *
-   * The checks decide by role and scope only: for a permission with row
-   * conditions (e.g. `authorId = principal.id`) every member of the scope
-   * could join. `better-supabase doctor` (BS214) refuses keys the
-   * authorization provider doesn't mark `sqlComplete: true`.
-   */
-  readonly access?: AccessTopicPolicy;
-  /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
-  readonly send?: boolean;
-  /**
-   * Presence: authorizes it in the policies and adds `track` and
-   * `onPresence` to subscriptions. Pass a schema to validate the states
-   * this client tracks and the ones it receives. Defaults to `false`.
-   */
-  readonly presence?: R;
-}
-interface TopicMessage {
-  readonly event: string;
-  readonly payload: unknown;
-  readonly topic: string;
-}
-type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
-type Input<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> : unknown;
-type TopicHandlers<E extends EventSchemas> = [keyof E] extends [never] ? {
-  readonly [event: string]: ((payload: unknown, message: TopicMessage) => void) | undefined;
-} : { readonly [K in keyof E & string]?: (payload: Output<E[K]>, message: TopicMessage) => void; } & {
-  readonly "*"?: (payload: unknown, message: TopicMessage) => void;
-};
-type TopicEvent<E extends EventSchemas> = [keyof E] extends [never] ? string : keyof E & string;
-type TopicPayload<E extends EventSchemas, K extends string> = [keyof E] extends [never] ? unknown : Input<E[K]>;
-type SubscriptionStatus = "joining" | "subscribed" | "closed" | "error";
-interface SubscribeOptions {
-  /** Receive your own broadcasts. */
-  readonly self?: boolean;
-  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
-  /** Called when a payload fails its event schema. The handler is skipped. */
-  readonly onInvalid?: (message: TopicMessage, issues: readonly ValidationIssue[]) => void;
-}
-interface Subscription extends Disposable, AsyncDisposable {
-  readonly topic: string;
-  readonly channel: RealtimeChannel;
-  /** Resolves once joined; rejects if the join is refused or times out. */
-  readonly ready: Promise<void>;
-  unsubscribe(): Promise<void>;
-}
-/** One tracked state on a presence topic. */
-interface PresenceMember<S> {
-  /** The connection's presence key; a client tracking twice keeps one key. */
-  readonly key: string;
-  readonly state: S;
-}
-interface PresenceOptions<S> {
-  /**
-   * Called with everyone on the topic, this client included, after each
-   * presence sync. States that fail the presence schema are left out and
-   * passed to `onInvalid` as a `presence` message.
-   */
-  readonly onPresence?: (members: readonly PresenceMember<S>[]) => void;
-}
-interface PresenceSubscription<I, O> extends Subscription {
-  /**
-   * Validates the state, waits for the join and shares it with the topic.
-   * One state per client and topic: the last `track` wins, and leaving the
-   * topic removes it.
-   */
-  track(state: I): AsyncResult<void>;
-  /** Removes this client's state from the topic. */
-  untrack(): AsyncResult<void>;
-  /** Everyone from the last sync, as `onPresence` received them. */
-  members(): readonly PresenceMember<O>[];
-}
-type PresenceState = Readonly<Record<string, unknown>>;
-type PresenceInput<R> = R extends StandardSchemaV1 ? StandardSchemaV1.InferInput<R> : PresenceState;
-type PresenceOutput<R> = R extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R> : PresenceState;
-/** What `subscribe` returns: with `track` and `members` on presence topics. */
-type TopicSubscription<R> = [R] extends [false] ? Subscription : PresenceSubscription<PresenceInput<R>, PresenceOutput<R>>;
-/** `subscribe` options: with `onPresence` on presence topics. */
-type TopicSubscribeOptions<R> = [R] extends [false] ? SubscribeOptions : SubscribeOptions & PresenceOptions<PresenceOutput<R>>;
-type RealtimeClient = Pick<SupabaseClient, "channel" | "getChannels" | "removeChannel" | "realtime">;
-/**
- * A value read from another table: the `select` column of the `from` row
- * whose `key` (its primary key by default) equals `via`, a column of the
- * changed row or another lookup.
- */
-interface TriggerLookup<M extends AnyModels> {
-  readonly from: TableKey<M>;
-  readonly via: string | TriggerLookup<M>;
-  readonly select: string;
-  readonly key?: string;
-}
-/** A trigger value: a column of the changed row, or a lookup through it. */
-type TriggerValue<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string> | TriggerLookup<M>;
-type TriggerOperation = "insert" | "update" | "delete";
-interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends string> {
-  /**
-   * What fills each placeholder: a column of the changed row, or a lookup
-   * (`{ from, via, select }`) for a value on a parent row. A row whose
-   * topic comes out null is not sent.
-   */
-  readonly values: { readonly [K in TemplateParams<P>]: TriggerValue<M, T>; };
-  /** Defaults to all three. */
-  readonly events?: readonly TriggerOperation[];
-  /**
-   * The broadcast event name, or one per operation. Defaults to the
-   * operation (`INSERT`, `UPDATE`, `DELETE`).
-   */
-  readonly event?: string | { readonly [O in TriggerOperation]?: string; };
-  /**
-   * Send this payload with `realtime.send` instead of the row change from
-   * `realtime.broadcast_changes`: each key is a column, a lookup, or
-   * `{ sql }`, an expression on the row `{row}` (`tg_op` is the operation).
-   */
-  readonly payload?: Readonly<Record<string, TriggerValue<M, T> | {
-    readonly sql: string;
-  }>>;
-  /**
-   * Schema for the generated function. Defaults to `better_supabase`, which
-   * the Data API does not expose.
-   */
-  readonly functionSchema?: string;
-}
-interface RowChange<R> {
-  readonly operation: "INSERT" | "UPDATE" | "DELETE";
-  readonly table: string;
-  readonly record: R | null;
-  readonly oldRecord: Partial<R> | null;
-}
-/** Options for `topic.sql()`. */
-interface TopicSqlOptions {
-  /** The provider's templates, for an access policy with `sql: "provider"`. */
-  readonly functions?: AuthorizationFunctions;
-}
-interface Topic<P extends string, E extends EventSchemas, R extends PresenceSchema = false> {
-  readonly template: P;
-  readonly name: string;
-  readonly params: readonly TemplateParams<P>[];
-  readonly private: boolean;
-  /** Whether subscriptions get `track` and `onPresence`. */
-  readonly presence: boolean;
-  topic(values: TemplateValues<P>): string;
-  match(topic: string): TemplateValues<P> | null;
-  /**
-   * `realtime.messages` policies for this topic. Idempotent. An access
-   * policy with `sql: "provider"` needs the provider's templates in
-   * `options.functions`; `better-supabase sql sync` passes them.
-   */
-  sql(options?: TopicSqlOptions): string;
-  /** A trigger that broadcasts row changes (`realtime.broadcast_changes`) to this topic. */
-  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
-  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: TopicHandlers<E>, options?: TopicSubscribeOptions<R>): TopicSubscription<R>;
-  /** Sends over HTTP, without joining the channel. */
-  send<K extends TopicEvent<E>>(client: RealtimeClient, values: TemplateValues<P>, event: K, payload: TopicPayload<E, K>): AsyncResult<void>;
-}
-/**
- * A typed Realtime broadcast topic: names from a template, RLS policies for
- * private channels, row-change triggers, and disposable subscriptions.
- *
- * ```ts
- * export const notifications = defineTopic('organization:{organizationId}:notifications:{userId}', {
- *   events: { created: v.object({ id: v.string(), title: v.string() }) },
- * });
- * using sub = notifications.subscribe(supabase, { organizationId, userId }, { created: (n) => toast(n.title) });
- * ```
- */
-declare function defineTopic<const P extends string, const E extends EventSchemas = Record<never, never>, const R extends PresenceSchema = false>(template: P, options?: TopicOptions<E, R>): Topic<P, E, R>;
-/**
- * Reads a `realtime.broadcast_changes` message as an app-cased row change.
- * Returns `null` for messages about other tables.
- */
-declare function rowChange<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
-//#endregion
-//#region src/realtime/live.d.ts
-/** What `liveQuery` needs from `betterSupabase`: metadata and the tables a spec reads. */
-interface LiveSource {
-  readonly meta: SchemaMeta;
-  tablesOf(spec: QuerySpec): string[];
-}
-interface LiveQueryOptions {
-  /** Called once per burst of changes, with the app keys of the tables that changed. */
-  readonly onChange: (tables: readonly string[]) => void;
-  /** Tenant value for tables scoped by a tenant column (`realtime-tables` topics). */
-  readonly tenant?: string;
-  /** The signed-in user's id, for tables that broadcast per user (`realtime.users`). */
-  readonly user?: string;
-  /** Waits this long after the last change before calling `onChange`. Defaults to 100 ms. */
-  readonly debounceMs?: number;
-  /**
-   * Also reports a channel that errors after it joined (`error`) and its
-   * rejoin (`subscribed`), not only the first join.
-   */
-  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
-  /**
-   * Retries a first join that failed, after 1 s and then twice as long each
-   * time, up to 30 s. Pass `false` to stay in `error`. Defaults to `true`.
-   */
-  readonly retry?: boolean;
-}
-interface LiveSubscription extends Disposable, AsyncDisposable {
-  /** App keys of the watched tables. */
-  readonly tables: readonly string[];
-  /** Tables the query reads that don't broadcast changes (not in `realtime.tables`). */
-  readonly unwatched: readonly string[];
-  readonly ready: Promise<void>;
-  unsubscribe(): Promise<void>;
-}
-/**
- * A count from the server plus the spec to keep it live on the client:
- * `bs.liveCount(spec)` makes one, `useLiveCount(seed)` reads it. `count`
- * is `null` when the server read failed; the client then fetches it.
- */
-interface LiveCountSeed<T extends string = string> {
-  readonly spec: QuerySpec<T, "count", number>;
-  readonly count: number | null;
-  /** When the count was taken (epoch ms). `useLiveCount` counts again after joining when it is older than a second. */
-  readonly at?: number;
-}
-/**
- * Topic a `realtime-tables` trigger broadcasts on:
- * `bs:t:<schema>.<table>[:<tenant>]`, or `bs:t:<schema>.<table>:u:<user>`
- * for a `realtime.users` table.
- */
-declare function liveTopic(meta: SchemaMeta, table: string, tenant?: string, user?: string): string;
-/**
- * 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() });
- * ```
- */
-declare function liveQuery(betterSupabase: LiveSource, client: RealtimeClient, spec: QuerySpec | readonly string[], options: LiveQueryOptions): LiveSubscription;
-/** What `liveCount` runs the spec with: a `db` from `betterSupabase.connect()` or `createClient()`. */
-interface CountRunner {
-  $run(spec: QuerySpec): PromiseLike<Result<unknown>>;
-}
-interface LiveCountOptions extends Omit<LiveQueryOptions, "onChange"> {
-  readonly onCount: (count: number) => void;
-  /** A failed refetch; the previous count stays valid. */
-  readonly onError?: (error: DbError) => void;
-  /** Count right away. Defaults to `true`; pass `false` when you have a seed. */
-  readonly immediate?: boolean;
-  /**
-   * When the count you already have was taken (epoch ms). Counts again once
-   * the channel joins when that is more than a second ago, so a change made
-   * before the join is not lost.
-   */
-  readonly since?: number;
-}
-/**
- * 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),
- * });
- * ```
- */
-declare function liveCount(betterSupabase: LiveSource, client: RealtimeClient, db: CountRunner, spec: QuerySpec<string, "count", number>, options: LiveCountOptions): LiveSubscription;
-//#endregion
-export { TopicSubscription as A, TopicEvent as C, TopicPayload as D, TopicOptions as E, rowChange as F, TriggerOptions as M, TriggerValue as N, TopicSqlOptions as O, defineTopic as P, Topic as S, TopicMessage as T, RealtimeClient as _, LiveSource as a, Subscription as b, liveQuery as c, PresenceInput as d, PresenceMember as f, PresenceSubscription as g, PresenceSchema as h, LiveQueryOptions as i, TriggerLookup as j, TopicSubscribeOptions as k, liveTopic as l, PresenceOutput as m, LiveCountOptions as n, LiveSubscription as o, PresenceOptions as p, LiveCountSeed as r, liveCount as s, CountRunner as t, EventSchemas as u, RowChange as v, TopicHandlers as w, SubscriptionStatus as x, SubscribeOptions as y };