better-supabase 0.12.0 → 0.14.0

package/dist/field-errors-vshYTVKr.d.ts

@@ -0,0 +1,166 @@
+import { b as DbError, f as Result } from "./result-C6jDfedy.js";
+import { o as EventHub } from "./events-DbLjvxDX.js";
+import { o as BlockTenant } from "./block-helpers-BaugZlJV.js";
+import { J as QuerySpec } from "./define-Dw7pRO4h.js";
+import { $ as TemplateValues } from "./bucket-TkB7_xv8.js";
+import { cn as GeneratedBlocks } from "./define-block-COpcS6aT.js";
+import { _ as TopicMessage, c as RealtimeClient, d as SubscribeOptions, i as PresenceOptions, s as PresenceSubscription } from "./topic-D9j8G2dw.js";
+import { t as ClientPorts } from "./ports-DsJicwI2.js";
+import { a as ClientAuth } from "./bind-Dz8y3T5T.js";
+import { a as LiveSource, r as LiveCountSeed } from "./index-eTY4kJzo.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { QueryClient } from "@tanstack/query-core";
+//#region src/bindings/client.d.ts
+/** The parts of `createClient()` the bindings need. */
+interface ClientLike {
+  readonly betterSupabase: LiveSource;
+  readonly supabase: SupabaseClient;
+  readonly auth: ClientAuth;
+  readonly db: object;
+  readonly queries: object;
+  /** The platform services block controllers use; see `ClientPorts`. */
+  readonly ports?: ClientPorts;
+  /** `blockConfig` from `blocks.generated.ts`, for the block hooks. */
+  readonly blocks?: GeneratedBlocks;
+  /** The tenant block hooks act in; default the session's tenant claim. */
+  readonly tenant?: BlockTenant;
+}
+/** What a `bs.action()` Server Action or server function resolves to. */
+type ActionResultOf<T> = {
+  readonly ok: true;
+  readonly data: T;
+  readonly error: null;
+} | {
+  readonly ok: false;
+  readonly data: null;
+  readonly error: DbError;
+};
+/**
+ * The input `useAction` passes: a `bs.action()` with an `input` schema also
+ * accepts `FormData`, which belongs to `useActionForm`.
+ */
+type ActionInputOf<I> = [Exclude<I, FormData>] extends [never] ? I : Exclude<I, FormData>;
+interface UseActionOptions<I, T> {
+  readonly onSuccess?: (data: T, input: I) => void;
+  readonly onError?: (error: DbError, input: I) => void;
+}
+interface BroadcastOptions extends Omit<SubscribeOptions, "onStatus"> {
+  /**
+   * A supabase-js client to subscribe with, for apps without the provider. It
+   * resubscribes when the client's user changes. Defaults to the provider's
+   * client.
+   */
+  readonly client?: SupabaseClient;
+  /** The query client `invalidate` refetches with. Defaults to the provider's. */
+  readonly queryClient?: QueryClient;
+  /**
+   * Refetch after each message: table keys (every query that read one of them),
+   * or a function returning query keys. Needs a `queryClient`, here or on the
+   * provider.
+   */
+  readonly invalidate?: readonly string[] | ((message: TopicMessage) => readonly (readonly unknown[])[]);
+}
+interface LiveQueryHookOptions {
+  /**
+   * Tenant for tenant-scoped tables. Defaults to the `config.claims.tenant`
+   * claim (`tenant_id`, top-level or in `app_metadata`).
+   */
+  readonly tenant?: string;
+  /** Defaults to 100 ms. */
+  readonly debounceMs?: number;
+}
+interface LiveCountHookOptions extends LiveQueryHookOptions {
+  /** The count to show before the first fetch, e.g. from the server. */
+  readonly initial?: number;
+}
+interface PresenceHookOptions<I> {
+  /**
+   * The state this client shares while joined. It is tracked after the join and
+   * tracked again when its JSON changes; `null` stays untracked.
+   */
+  readonly state?: I | null;
+  /** A supabase-js client for apps without the provider. */
+  readonly client?: SupabaseClient;
+}
+/** The parts of a `defineTopic(..., { presence })` topic the bindings use. */
+interface PresenceTopic<P extends string, I, O> {
+  topic(values: TemplateValues<P>): string;
+  match(topic: string): TemplateValues<P> | null;
+  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: Readonly<Record<string, never>>, options?: SubscribeOptions & PresenceOptions<O>): PresenceSubscription<I, O>;
+}
+/** Who a subscription runs as. */
+/**
+ * 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 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;
+/** A count spec or a `bs.liveCount()` seed. */
+type LiveCountSource = QuerySpec<string, "count", number> | LiveCountSeed | null | undefined;
+interface ActionState<I, T> {
+  /** True while a run is in flight. */
+  readonly pending: boolean;
+  /** The inputs of the runs in flight, e.g. to dim one table row. */
+  readonly pendingInputs: readonly I[];
+  /** The input of the latest run in flight. */
+  readonly pendingInput: I | undefined;
+  /** The data of the last successful run. */
+  readonly data: T | undefined;
+  /** The error of the last run, until the next one starts. */
+  readonly error: DbError | undefined;
+}
+//#endregion
+//#region src/blocks/block-controller.d.ts
+/** A block read's state: the last data stays while it loads again. */
+interface BlockQueryState<T> {
+  readonly status: "idle" | "loading" | "success" | "error";
+  readonly data: T | undefined;
+  readonly error: DbError | undefined;
+}
+interface BlockQueryActions {
+  /** Calls the method again. */
+  readonly refetch: () => void;
+}
+/** Where a block read hears the events that make it stale. */
+interface BlockRefetchOn {
+  readonly source: {
+    readonly events: EventHub;
+  };
+  /** The event types, such as `blockEvents.types` from `blocks.generated.ts`. */
+  readonly types: readonly string[];
+}
+interface BlockQueryOptions {
+  /** Calls the method again when one of these block events arrives. */
+  readonly refetchOn?: BlockRefetchOn;
+}
+/** A block write's state. */
+interface BlockMutationState<T> {
+  readonly status: "idle" | "pending" | "success" | "error";
+  readonly data: T | undefined;
+  readonly error: DbError | undefined;
+}
+interface BlockMutationActions<A extends readonly unknown[], T> {
+  /** Calls the method; the `Result` resolves when it settles. */
+  readonly mutate: (...args: A) => Promise<Result<T>>;
+  /** Back to `idle`. */
+  readonly reset: () => void;
+}
+/** What `useBlockEvent` listens to: the client's `betterSupabase`. */
+interface BlockEventSource {
+  readonly events: EventHub;
+}
+//#endregion
+//#region src/bindings/field-errors.d.ts
+/** The first message per top-level field of a `validation` error. */
+declare function fieldErrorsOf(error: DbError | undefined): Readonly<Partial<Record<string, string>>>;
+//#endregion
+export { LiveQueryHookOptions as _, BlockQueryActions as a, ProfileOf as b, BlockRefetchOn as c, ActionState as d, BroadcastOptions as f, LiveCountSource as g, LiveCountHookOptions as h, BlockMutationState as i, ActionInputOf as l, ClientLike as m, BlockEventSource as n, BlockQueryOptions as o, ClaimsOf as p, BlockMutationActions as r, BlockQueryState as s, fieldErrorsOf as t, ActionResultOf as u, PresenceHookOptions as v, UseActionOptions as x, PresenceTopic as y };

package/dist/field-formats-C6QKA3UR.js

@@ -0,0 +1,102 @@
+//#region src/core/contracts/field-formats.ts
+const FIELD_FORMAT_NAMES = [
+	"email",
+	"url",
+	"phone",
+	"long_text",
+	"color",
+	"rating",
+	"percent",
+	"currency"
+];
+/** The stars a `rating` takes, for a column and for a custom field. */
+const RATING_BOUNDS = [1, 5];
+const EMAIL = String.raw`^[^@\s]+@[^@\s]+\.[^@\s]+$`;
+const URL = String.raw`^https?://\S+$`;
+/**
+* Money is a `currency` `bigint` of minor units next to a `text` column of 3
+* characters for the code (ADR 0037).
+*/
+const FIELD_FORMATS = {
+	email: {
+		types: ["text"],
+		pattern: EMAIL,
+		input: "email",
+		formType: "email"
+	},
+	url: {
+		types: ["text"],
+		pattern: URL,
+		input: "url",
+		formType: "url"
+	},
+	phone: {
+		types: ["text"],
+		input: "tel",
+		formType: "text"
+	},
+	long_text: {
+		types: ["text"],
+		input: "textarea",
+		formType: "textarea"
+	},
+	color: {
+		types: ["text"],
+		input: "color",
+		formType: "text"
+	},
+	rating: {
+		types: ["integer", "bigint"],
+		bounds: RATING_BOUNDS,
+		input: "number",
+		formType: "integer"
+	},
+	percent: {
+		types: ["integer", "numeric"],
+		bounds: [0, 100],
+		input: "number",
+		formType: "number"
+	},
+	currency: {
+		types: ["bigint"],
+		input: "number",
+		formType: "integer"
+	}
+};
+/**
+* The types of a custom field definition. A value is stored as text either way;
+* the type tells the form and the UI what it holds. `user` holds a user id,
+* `currency` an integer of minor units, and `multi_option` a JSON array of
+* option values.
+*/
+const CUSTOM_FIELD_TYPES = [
+	"text",
+	"number",
+	"date",
+	"bool",
+	"option",
+	"json",
+	"email",
+	"url",
+	"multi_option",
+	"user",
+	"rating",
+	"currency"
+];
+/** The forms block field type that answers each custom field type. */
+const CUSTOM_FIELD_FORM_TYPES = {
+	text: "text",
+	number: "number",
+	date: "date",
+	bool: "bool",
+	option: "option",
+	json: "json",
+	email: FIELD_FORMATS.email.formType,
+	url: FIELD_FORMATS.url.formType,
+	multi_option: "multi",
+	user: "text",
+	rating: FIELD_FORMATS.rating.formType,
+	currency: FIELD_FORMATS.currency.formType
+};
+//#endregion
+export { RATING_BOUNDS as a, FIELD_FORMAT_NAMES as i, CUSTOM_FIELD_TYPES as n, FIELD_FORMATS as r, CUSTOM_FIELD_FORM_TYPES as t };

package/dist/field-formats-DbjaDXoZ.d.ts

@@ -0,0 +1,39 @@
+import { s as FormFieldType } from "./form-definition-BjEtH8BT.js";
+//#region src/core/contracts/field-formats.d.ts
+/**
+ * The one field vocabulary: the formats an app table column takes and the types
+ * a custom field takes. App tables render each format's check from here,
+ * `scaffold screens` picks the input, and the forms block answers a custom
+ * field with the form field type it maps to.
+ */
+/** The Postgres column types a format fits. */
+type FieldFormatColumnType = "text" | "integer" | "bigint" | "numeric";
+/** The HTML input a format edits with. */
+type FieldFormatInput = "email" | "url" | "tel" | "textarea" | "color" | "number";
+interface FieldFormat {
+  readonly types: readonly FieldFormatColumnType[];
+  /** A POSIX regular expression the value matches, ignoring case. */
+  readonly pattern?: string;
+  /** The bounds when the column sets no `min` or `max`. */
+  readonly bounds?: readonly [min: number, max: number];
+  readonly input: FieldFormatInput;
+  /** The forms block field type that collects the value. */
+  readonly formType: FormFieldType;
+}
+declare const FIELD_FORMAT_NAMES: readonly ["email", "url", "phone", "long_text", "color", "rating", "percent", "currency"];
+type FieldFormatName = (typeof FIELD_FORMAT_NAMES)[number];
+/**
+ * Money is a `currency` `bigint` of minor units next to a `text` column of 3
+ * characters for the code (ADR 0037).
+ */
+declare const FIELD_FORMATS: Readonly<Record<FieldFormatName, FieldFormat>>;
+/**
+ * The types of a custom field definition. A value is stored as text either way;
+ * the type tells the form and the UI what it holds. `user` holds a user id,
+ * `currency` an integer of minor units, and `multi_option` a JSON array of
+ * option values.
+ */
+declare const CUSTOM_FIELD_TYPES: readonly ["text", "number", "date", "bool", "option", "json", "email", "url", "multi_option", "user", "rating", "currency"];
+type CustomFieldType = (typeof CUSTOM_FIELD_TYPES)[number];
+//#endregion
+export { FieldFormat as a, FIELD_FORMAT_NAMES as i, CustomFieldType as n, FieldFormatInput as o, FIELD_FORMATS as r, FieldFormatName as s, CUSTOM_FIELD_TYPES as t };

package/dist/fields-CanaxA0U.d.ts

@@ -0,0 +1,75 @@
+import { D as ValidationIssue } from "./result-C6jDfedy.js";
+import { c as FilterFieldLabels, d as FilterLimits, h as FilterQuery, l as FilterFieldType, o as FilterField, s as FilterFieldInfo } from "./filter-query-o3b_GuyC.js";
+//#region src/blocks/rules/fields.d.ts
+/** One field of `defineRuleFields`: a value rules on the subject type may test. */
+interface RuleFieldDefinition {
+  readonly type: FilterFieldType;
+  readonly label?: string;
+  readonly description?: string;
+  /**
+   * The subject record key the value is read from, dotted for a nested value.
+   * Defaults to the field id.
+   */
+  readonly column?: string;
+  /**
+   * The Postgres type, which decides how dates compare: `date`, `timestamp` or
+   * `timestamptz` (the default for date fields).
+   */
+  readonly columnType?: string;
+  /**
+   * Whether the value may be missing, so "is not" also matches it. Default
+   * `true`.
+   */
+  readonly nullable?: boolean;
+  /** Allowed values for `select` and `multiselect`. */
+  readonly options?: readonly (string | {
+    readonly value: string;
+    readonly label?: string;
+  })[];
+  /** A subset of the type's operators. */
+  readonly operators?: readonly string[];
+}
+/** A catalog field as `rule_fields_list` returns it. */
+interface RuleField {
+  readonly subjectType: string;
+  readonly id: string;
+  readonly label: string;
+  readonly description: string | undefined;
+  readonly type: FilterFieldType;
+  readonly column: string;
+  readonly columnType: string;
+  readonly nullable: boolean;
+  readonly options: readonly {
+    readonly value: string;
+    readonly label: string;
+  }[] | undefined;
+  readonly operators: readonly string[] | undefined;
+}
+/** The fields of one subject type, for `RulesAdmin.syncFields` and the editor. */
+interface RuleFieldCatalog<S extends string = string> {
+  readonly subjectType: S;
+  readonly fields: readonly RuleField[];
+}
+/**
+ * Declares the fields rules on `subjectType` may test. Sync the catalog with
+ * `createRulesAdmin(...).syncFields(catalog)` so the database checks and
+ * evaluates trees against the same fields.
+ */
+declare function defineRuleFields<const S extends string>(subjectType: S, fields: Readonly<Record<string, RuleFieldDefinition>>): RuleFieldCatalog<S>;
+/**
+ * Catalog fields as list filter fields, for `evaluateFilterQuery` and
+ * `checkFilterQuery`.
+ */
+declare function ruleFilterFieldInfo(fields: readonly RuleField[]): FilterFieldInfo[];
+/** The `fields` prop of ReUI's Filters for a rule editor. */
+declare function ruleFilterFields(fields: readonly RuleField[], labels?: FilterFieldLabels): FilterField[];
+/** The defaults of `blocks.rules.options`. */
+declare const RULE_LIMITS: FilterLimits;
+/**
+ * The problems `save` would report for a tree, checked in the browser: an empty
+ * list when the database will accept it. Unfinished conditions are allowed;
+ * they take no part until they have an operator.
+ */
+declare function checkRuleConditions(conditions: FilterQuery, fields: readonly RuleField[], limits?: FilterLimits): readonly ValidationIssue[];
+//#endregion
+export { checkRuleConditions as a, ruleFilterFields as c, RuleFieldDefinition as i, RuleField as n, defineRuleFields as o, RuleFieldCatalog as r, ruleFilterFieldInfo as s, RULE_LIMITS as t };

package/dist/fields-DK30XCgc.js

@@ -0,0 +1,107 @@
+import { d as toFilterFields, i as checkFilterQuery, t as FILTER_OPERATORS } from "./filter-query-D4ZSwbcJ.js";
+//#region src/blocks/rules/fields.ts
+const DEFAULT_COLUMN_TYPE = {
+	text: "text",
+	number: "numeric",
+	date: "timestamptz",
+	select: "text",
+	multiselect: "jsonb",
+	boolean: "boolean",
+	relation: "uuid"
+};
+const DATE_TYPES = /* @__PURE__ */ new Set([
+	"date",
+	"timestamp",
+	"timestamptz"
+]);
+const SUBJECT_TYPE = /^[a-z][a-z0-9_]{0,62}$/;
+const FIELD_ID = /^[A-Za-z_][A-Za-z0-9_]*(?:[.][A-Za-z_][A-Za-z0-9_]*)*$/;
+function labelOf(id) {
+	const words = id.replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2").replaceAll(/[_.-]+/g, " ").trim().toLowerCase();
+	return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/**
+* Declares the fields rules on `subjectType` may test. Sync the catalog with
+* `createRulesAdmin(...).syncFields(catalog)` so the database checks and
+* evaluates trees against the same fields.
+*/
+function defineRuleFields(subjectType, fields) {
+	if (!SUBJECT_TYPE.test(subjectType)) throw new TypeError(`defineRuleFields: "${subjectType}" is not a subject type (lowercase letters, digits and underscores)`);
+	return {
+		subjectType,
+		fields: Object.entries(fields).map(([id, field]) => {
+			const column = field.column ?? id;
+			if (!FIELD_ID.test(id) || !FIELD_ID.test(column)) throw new TypeError(`defineRuleFields(${subjectType}): "${id}" needs an id and column of dotted identifiers`);
+			const allowed = new Set(FILTER_OPERATORS[field.type].map((entry) => entry.value));
+			const unknown = field.operators?.find((name) => !allowed.has(name));
+			if (unknown !== void 0) throw new TypeError(`defineRuleFields(${subjectType}.${id}): "${unknown}" is not a ${field.type} operator`);
+			const columnType = field.columnType ?? DEFAULT_COLUMN_TYPE[field.type];
+			if (field.type === "date" && !DATE_TYPES.has(columnType)) throw new TypeError(`defineRuleFields(${subjectType}.${id}): a date field's columnType is date, timestamp or timestamptz`);
+			return {
+				subjectType,
+				id,
+				label: field.label ?? labelOf(id),
+				description: field.description,
+				type: field.type,
+				column,
+				columnType,
+				nullable: field.nullable ?? true,
+				options: field.options?.map((option) => typeof option === "string" ? {
+					value: option,
+					label: labelOf(option)
+				} : {
+					value: option.value,
+					label: option.label ?? labelOf(option.value)
+				}),
+				operators: field.operators
+			};
+		})
+	};
+}
+/**
+* Catalog fields as list filter fields, for `evaluateFilterQuery` and
+* `checkFilterQuery`.
+*/
+function ruleFilterFieldInfo(fields) {
+	return fields.map((field) => {
+		const allowed = field.operators;
+		return {
+			id: field.id,
+			type: field.type,
+			column: field.column,
+			columnMeta: {
+				db: field.column,
+				type: field.columnType,
+				nullable: field.nullable,
+				hasDefault: false
+			},
+			label: field.label,
+			...field.description === void 0 ? {} : { description: field.description },
+			operators: FILTER_OPERATORS[field.type].filter((entry) => allowed === void 0 || allowed.includes(entry.value)),
+			...field.options === void 0 ? {} : { options: field.options }
+		};
+	});
+}
+/** The `fields` prop of ReUI's Filters for a rule editor. */
+function ruleFilterFields(fields, labels) {
+	return toFilterFields(ruleFilterFieldInfo(fields), labels);
+}
+/** The defaults of `blocks.rules.options`. */
+const RULE_LIMITS = {
+	maxDepth: 4,
+	maxRules: 50,
+	maxValueLength: 1e4,
+	maxValues: 100
+};
+/**
+* The problems `save` would report for a tree, checked in the browser: an empty
+* list when the database will accept it. Unfinished conditions are allowed;
+* they take no part until they have an operator.
+*/
+function checkRuleConditions(conditions, fields, limits = RULE_LIMITS) {
+	const issues = [];
+	checkFilterQuery(conditions, ruleFilterFieldInfo(fields), limits, issues);
+	return issues;
+}
+//#endregion
+export { ruleFilterFields as a, ruleFilterFieldInfo as i, checkRuleConditions as n, defineRuleFields as r, RULE_LIMITS as t };

package/dist/filter-evaluate-C3i2bGfk.d.ts

@@ -0,0 +1,37 @@
+import { h as FilterQuery, l as FilterFieldType, r as FilterClock } from "./filter-query-o3b_GuyC.js";
+//#region src/list/filter-evaluate.d.ts
+/**
+ * A field a filter tree can test on a plain record. `FilterFieldInfo` from a
+ * list definition fits; the rules block builds these from its field catalog.
+ */
+interface FilterRecordField {
+  readonly id: string;
+  readonly type: FilterFieldType;
+  /** The record key the value is read from, dotted for a nested value. */
+  readonly column: string;
+  readonly columnMeta: {
+    /**
+     * The Postgres type: `date`, `timestamp` and `timestamptz` pick how dates
+     * compare.
+     */
+    readonly type: string;
+    readonly nullable: boolean;
+  };
+}
+/**
+ * The outcome of a tree on one record. `results` holds every rule and group
+ * that took part, by node id: `null` when a comparison met a missing value,
+ * which SQL treats as unknown and a match treats as false.
+ */
+interface FilterEvaluation {
+  readonly matched: boolean;
+  readonly results: Readonly<Record<string, boolean | null>>;
+}
+/**
+ * Tests a checked filter tree on one record, with the same operators and null
+ * handling as `filterWhere` compiles to SQL. Unfinished rules, unknown fields
+ * and empty groups take no part, and a tree with nothing left matches.
+ */
+declare function evaluateFilterQuery(query: FilterQuery, record: unknown, fields: readonly FilterRecordField[], clock?: FilterClock): FilterEvaluation;
+//#endregion
+export { FilterRecordField as n, evaluateFilterQuery as r, FilterEvaluation as t };