@rebasepro/types 0.13.0 → 0.13.1-canary.g249daa1

package/dist/types/admin_block.d.ts

@@ -29,7 +29,7 @@
  *
  * @group Models
  */
-export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort", "titleProperty"];
+export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "display", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromEntityViews", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort", "titleProperty"];
 /** A key of a collection's `admin` block. @group Models */
 export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
 /**

package/dist/types/backend.d.ts

@@ -162,6 +162,8 @@ export interface CollectionSubscriptionConfig {
     startAfter?: unknown;
     databaseId?: string;
     searchString?: string;
+    /** Ask each row which declared search field matched. */
+    searchExplain?: boolean;
 }
 /**
  * Configuration for subscribing to a single entity

package/dist/types/collections.d.ts

@@ -3,6 +3,7 @@ import type { Properties, PostgresProperties, FirebaseProperties, MongoPropertie
 import type { User } from "../users";
 import type { Relation } from "./relations";
 import type { SecurityRule } from "./security_rules";
+import type { SearchConfig } from "./search";
 /**
  * Base interface containing all driver-agnostic collection properties.
  * Use {@link PostgresCollectionConfig} or {@link FirebaseCollectionConfig} for
@@ -13,9 +14,27 @@ import type { SecurityRule } from "./security_rules";
  */
 export interface BaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
     /**
-     * You can set an alias that will be used internally instead of the collection name.
-     * The `slug` value will be used to determine the URL of the collection.
-     * Note that you can use this value in reference properties too.
+     * The collection's identity. Required, and the value nearly everything else
+     * keys on:
+     *
+     * - the REST path — `/api/data/<slug>`
+     * - the SDK accessor — `client.data.<slug>` / `client.data.collection("<slug>")`
+     * - the admin panel's URL
+     * - the target of a `reference` or `relation` property
+     *
+     * Conventionally kebab-case and plural (`blog-posts`). It is independent of
+     * {@link table}: the slug is what callers say, the table is where the rows
+     * live, and renaming one does not rename the other.
+     *
+     * Treat it as frozen once anything has shipped against it — changing a slug
+     * changes every URL and every generated accessor at once.
+     *
+     * @example
+     * defineCollection({
+     *     slug: "blog-posts",   // /api/data/blog-posts, client.data.blogPosts
+     *     table: "posts",
+     *     properties: { … }
+     * })
      */
     slug: string;
     /**
@@ -209,6 +228,20 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
      * @default false
      */
     disableDefaultPolicies?: boolean;
+    /**
+     * Opt in to Postgres full-text search for this collection.
+     *
+     * Omit it and `.search()` keeps its existing behaviour exactly — an
+     * `ILIKE '%term%'` across top-level string properties. Declare it and the
+     * collection gains one generated `tsvector` column and a GIN index, and
+     * `.search()` compiles to a ranked `@@ websearch_to_tsquery` against them.
+     *
+     * Postgres-only, like {@link VectorProperty}: the block is rejected at boot
+     * on other engines rather than silently ignored.
+     *
+     * @see SearchConfig
+     */
+    search?: SearchConfig;
 }
 /**
  * A collection backed by Firebase / Firestore.

package/dist/types/cron.d.ts

@@ -1,4 +1,5 @@
-import type { RebaseClient } from "../controllers/client";
+import type { RebaseServerClient } from "../controllers/client";
+import type { RebaseSdkData } from "../controllers/data";
 /**
  * Cron Job type definitions for Rebase.
  *
@@ -75,16 +76,56 @@ export interface CronJobContext {
     /** A simple logger scoped to this job run. */
     log: (...args: unknown[]) => void;
     /**
-     * The server-side {@link RebaseClient}. This is the **same singleton**
-     * exposed as `rebase` (imported from `@rebasepro/server`) and as
-     * `context` in collection callbacks — it is only named `client` here.
+     * The server-side Rebase singleton — the **same object** `import { rebase }
+     * from "@rebasepro/server"` returns, and the same one `defineFunction`
+     * hands its callback. Spelled the same way here so that one thing has one
+     * name across every server-side authoring surface.
      *
-     * Its data plane (`client.data`) runs with **admin privileges and bypasses
-     * RLS** (`{ uid: "service", roles: ["admin"] }`). There is no per-request
-     * user in a cron, so treat every query as fully trusted and scope your own
-     * filters explicitly.
+     * Its data plane is {@link RebaseServerClient.dataAsAdmin}, which runs with
+     * **admin privileges and bypasses RLS** (`{ uid: "service", roles:
+     * ["admin"] }`). A cron has no per-request user, so there is no user-scoped
+     * alternative here and no policy to fall back on: scope every query's
+     * filters yourself.
+     *
+     * @example
+     * export default defineCron({
+     *     name: "Nightly cleanup",
+     *     schedule: "0 3 * * *",
+     *     async handler({ rebase, log }) {
+     *         const expired = await rebase.dataAsAdmin.sessions.findAll({
+     *             where: { expired: ["==", true] }
+     *         });
+     *         for (const session of expired) {
+     *             await rebase.dataAsAdmin.sessions.delete(session.id as string);
+     *         }
+     *         log(`Deleted ${expired.length} expired sessions`);
+     *     }
+     * });
+     */
+    rebase: RebaseServerClient;
+    /**
+     * The same object as {@link rebase}, under the name this context used
+     * before.
+     *
+     * @deprecated Use `rebase` instead. Two things made the old name a problem,
+     * and neither was cosmetic. It contradicted every other server surface,
+     * where the singleton is `rebase` — the previous docstring had to end with
+     * *"it is only named `client` here"*. And typing it as `RebaseClient`
+     * re-exposed `client.data`, the alias that {@link RebaseServerClient}
+     * deliberately `Omit`s so the RLS-bypassing plane has exactly one name and
+     * the privilege is visible at the call site. A reader who learned
+     * `client.data` here carried it to a collection callback, where
+     * `context.data` is the *user-scoped* plane — same spelling, opposite
+     * privilege.
+     *
+     * Still the full server client at runtime, and `data` still resolves, so
+     * existing cron files keep working and keep compiling. It will be removed
+     * in the next major.
      */
-    client: RebaseClient;
+    client: RebaseServerClient & {
+        /** @deprecated Use `rebase.dataAsAdmin` — the name states the privilege. */
+        data: RebaseSdkData;
+    };
 }
 export type CronJobRunState = "idle" | "running" | "success" | "error" | "disabled";
 /**

package/dist/types/entities.d.ts

@@ -1,3 +1,4 @@
+import type { SearchMatch } from "./search";
 /**
  * New or existing status
  * @group Models
@@ -21,6 +22,16 @@ export interface Entity<M extends Record<string, unknown> = Record<string, unkno
      * Current values
      */
     values: EntityValues<M>;
+    /**
+     * Why this entity is in a search result: which declared fields matched, and
+     * the text around each hit.
+     *
+     * Present only on rows returned by a search that asked for it. A sibling of
+     * `values` rather than a key inside it, because it describes the *query*,
+     * not the record — nothing in the collection declares it, no form edits it,
+     * and a record fetched by id never has one.
+     */
+    searchMatches?: SearchMatch[];
     /**
      * Which driver this entity belongs to (e.g., 'postgres', 'firestore').
      * If not specified, the default driver is assumed.

package/dist/types/entity_callbacks.d.ts

@@ -7,7 +7,8 @@ import type { RebaseCallContext } from "../call_context";
  *
  * Register per-collection on the collection's `callbacks` field, or globally
  * via `initializeRebaseBackend({ callbacks })`. Fires on **every** data path — REST API,
- * WebSocket / realtime subscriptions, and server-side `rebase.data`.
+ * WebSocket / realtime subscriptions, and server-side writes through
+ * `rebase.dataAsAdmin`.
  *
  * When both global and per-collection callbacks are registered, execution
  * order is: **global → collection → property callbacks**.

package/dist/types/index.d.ts

@@ -4,8 +4,10 @@ export * from "./chips";
 export * from "./properties";
 export * from "./admin_block";
 export * from "./collections";
+export * from "./search";
 export * from "./relations";
 export * from "./policy";
+export * from "./rls-functions";
 export * from "./security_rules";
 export * from "./entity_callbacks";
 export * from "./websockets";

package/dist/types/policy.d.ts

@@ -19,7 +19,7 @@
  */
 export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | AndPolicyExpression | OrPolicyExpression | NotPolicyExpression | ComparePolicyExpression | RolesOverlapPolicyExpression | RolesContainPolicyExpression | AuthenticatedPolicyExpression | ServerContextPolicyExpression | ExistsInPolicyExpression | RawPolicyExpression;
 /**
- * The id a request without a logged-in user reports as `auth.uid()`.
+ * The id a request without a logged-in user reports as `rebase.uid()`.
  *
  * A user-context request always sets `app.uid`: blank would read back as
  * `NULL`, and `NULL` is how the trusted server context is recognised, so an
@@ -27,7 +27,7 @@ export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | An
  * therefore substitutes this sentinel at the single chokepoint where the GUC
  * is set.
  *
- * The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a
+ * The consequence for policy authors is that **`rebase.uid() IS NOT NULL` is a
  * tautology on the user path** — it is true for anonymous visitors too. Use
  * {@link policy.authenticated} to mean "signed in", and
  * {@link policy.serverContext} to mean "the trusted server context". Do not
@@ -44,7 +44,7 @@ export declare const ANONYMOUS_USER_ID = "anonymous";
  * JavaScript evaluator and the linter were all built on
  * {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated
  * callers as `'anon'` — so `policy.authenticated()`, which compiled to
- * `auth.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
+ * `rebase.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
  * sanctioned way to write "signed in" granted to everyone, and the linter
  * flagged the spelling that actually worked as a foreign convention.
  *
@@ -93,7 +93,7 @@ export interface NotPolicyExpression {
 /** Comparison operators available to {@link ComparePolicyExpression}. @group Models */
 export type PolicyCompareOperator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
 /**
- * Compares two operands, e.g. `owner_id = auth.uid()`.
+ * Compares two operands, e.g. `owner_id = rebase.uid()`.
  * @group Models
  */
 export interface ComparePolicyExpression {
@@ -104,7 +104,7 @@ export interface ComparePolicyExpression {
 }
 /**
  * True when the user holds *at least one* of the given application roles.
- * Compiles to `string_to_array(auth.roles(), ',') && ARRAY[...]`.
+ * Compiles to `string_to_array(rebase.roles(), ',') && ARRAY[...]`.
  * @group Models
  */
 export interface RolesOverlapPolicyExpression {
@@ -113,7 +113,7 @@ export interface RolesOverlapPolicyExpression {
 }
 /**
  * True when the user holds *all* of the given application roles.
- * Compiles to `string_to_array(auth.roles(), ',') @> ARRAY[...]`.
+ * Compiles to `string_to_array(rebase.roles(), ',') @> ARRAY[...]`.
  * @group Models
  */
 export interface RolesContainPolicyExpression {
@@ -122,11 +122,11 @@ export interface RolesContainPolicyExpression {
 }
 /**
  * True when a signed-in user is making the request. Compiles to
- * `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'`.
+ * `rebase.uid() IS NOT NULL AND rebase.uid() <> 'anonymous'`.
  *
  * Both halves are load-bearing. `IS NOT NULL` excludes the server context;
  * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who
- * *do* carry a non-null `auth.uid()`. Checking only `IS NOT NULL` grants to
+ * *do* carry a non-null `rebase.uid()`. Checking only `IS NOT NULL` grants to
  * everyone — see {@link ANONYMOUS_USER_ID}.
  *
  * `policy.not(policy.authenticated())` therefore means "anonymous visitor or
@@ -140,8 +140,8 @@ export interface AuthenticatedPolicyExpression {
 /**
  * True only in the trusted **server context** — the built-in flows that run
  * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so
- * `auth.uid()` is `NULL` for them and only for them. Compiles to
- * `auth.uid() IS NULL`.
+ * `rebase.uid()` is `NULL` for them and only for them. Compiles to
+ * `rebase.uid() IS NULL`.
  *
  * This is what lets the owner connection satisfy a policy even under FORCE RLS.
  * It is deliberately a primitive rather than `not(authenticated())`: the two
@@ -178,7 +178,7 @@ export interface ServerContextPolicyExpression {
  *   ),
  * })
  * // → EXISTS (SELECT 1 FROM team_members _ex0
- * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = auth.uid())
+ * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = rebase.uid())
  * ```
  *
  * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript
@@ -232,13 +232,13 @@ export interface LiteralPolicyOperand {
     kind: "literal";
     value: string | number | boolean | null;
 }
-/** The current user's id — compiles to `auth.uid()`. @group Models */
+/** The current user's id — compiles to `rebase.uid()`. @group Models */
 export interface AuthUidPolicyOperand {
     kind: "authUid";
 }
 /**
  * The current user's roles as an array — compiles to
- * `string_to_array(auth.roles(), ',')`.
+ * `string_to_array(rebase.roles(), ',')`.
  * @group Models
  */
 export interface AuthRolesPolicyOperand {

package/dist/types/properties.d.ts

@@ -166,7 +166,7 @@ export interface BaseProperty<CustomProps = unknown> {
      * written and queryable server-side; it is stripped from every row the API
      * serves, for every caller, including admins and service keys.
      *
-     * This is a server-side guarantee, unlike `ui.hideFromCollection`, which
+     * This is a server-side guarantee, unlike `admin.hideFromCollection`, which
      * only stops the admin panel from *rendering* a field and leaves it in the
      * JSON payload.
      */
@@ -904,6 +904,17 @@ export interface ImageResize {
  * @group Entity properties
  */
 export type JsonLogicRule = Record<string, any>;
+/**
+ * A condition that is either a JSON Logic rule or a literal answer.
+ *
+ * The unconditional case is the common one — "this field is never editable",
+ * "this field is never shown" — and with only a rule accepted it had to be
+ * spelled `{ "==": [1, 1] }`, which reads as a puzzle at the call site. A plain
+ * `true` says the same thing.
+ *
+ * @group Entity properties
+ */
+export type ConditionRule = JsonLogicRule | boolean;
 /**
  * Conditions for individual enum values within a property.
  * @group Entity properties
@@ -945,8 +956,10 @@ export interface PropertyConditions {
      * \`\`\`json
      * { "==": [{ "var": "values.status" }, "archived"] }
      * \`\`\`
+     *
+     * A literal `true` disables it unconditionally.
      */
-    disabled?: JsonLogicRule;
+    disabled?: ConditionRule;
     /**
      * Message to display when the field is disabled by a condition.
      */
@@ -959,13 +972,18 @@ export interface PropertyConditions {
     /**
      * Hide the field completely when this condition evaluates to true.
      * The field is removed from the form (not just visually hidden).
+     *
+     * A literal `true` hides it unconditionally. This is the way to keep a
+     * property out of the form without keeping it out of the collection.
      */
-    hidden?: JsonLogicRule;
+    hidden?: ConditionRule;
     /**
      * Make the field read-only when this condition evaluates to true.
      * Renders as a preview instead of an input.
+     *
+     * A literal `true` makes it read-only unconditionally.
      */
-    readOnly?: JsonLogicRule;
+    readOnly?: ConditionRule;
     /**
      * Make the field required when this condition evaluates to true.
      * Overrides the static `validation.required` setting.

package/dist/types/rls-functions.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The SQL helper functions RLS policies call, and the schema they live in.
+ *
+ * ## One schema, and it is ours
+ *
+ * Rebase creates exactly one schema in a project's database: `rebase`. These
+ * three functions live in it alongside the framework's own tables, and that is
+ * the whole contract — a reader can look at a database and know precisely which
+ * namespace belongs to the framework and that nothing else was touched.
+ *
+ * It used to be two. `uid()`, `jwt()` and `roles()` sat in a schema called
+ * `auth`, which is Supabase's name, chosen so that a developer who had written
+ * Supabase RLS would recognise `auth.uid()`. The familiarity was real but the
+ * name was not Rebase's to take, and taking it had a concrete cost: pointing
+ * Rebase at a database that already had a Supabase `auth` schema meant
+ * `CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` against Supabase's
+ * `RETURNS uuid`, which Postgres rejects outright —
+ *
+ *     ERROR:  cannot change return type of existing function
+ *     HINT:   Use DROP FUNCTION auth.uid() first.
+ *
+ * — and the failure landed inside a catch-all that logged a warning and carried
+ * on, leaving a database with auth tables, no helper functions, and policies
+ * calling functions that did not exist. Under `rebase db migrate` the same
+ * statements aborted the migration instead.
+ *
+ * `rebase.uid()` collides with nobody. A Supabase database keeps its `auth`
+ * schema untouched and gains a `rebase` one, which is what a gradual migration
+ * needs.
+ *
+ * ## Why functions at all, rather than inlining `current_setting`
+ *
+ * Because the indirection has already been spent once. `uid()` resolves
+ * `app.uid` and falls back to the pre-rename `app.user_id`, so that during a
+ * rolling deploy — old and new pods serving one database — both eras resolve
+ * the principal. That was a single `CREATE OR REPLACE`. Inlined into policy
+ * bodies it would have been a rewrite of every policy on every table.
+ *
+ * ## Why the name is not configurable
+ *
+ * A policy body is stored SQL: Postgres parses `USING (…)` once and keeps it, so
+ * these strings are written into every policy in every database Rebase has
+ * provisioned. Everything that reads policies back — the SQL-to-policy parser
+ * behind the admin UI, the drift checker, `rls-check` — would have to know the
+ * configured value to recognise its own output. One frozen name is the feature.
+ */
+/** The schema Rebase owns. The only schema Rebase creates. */
+export declare const REBASE_SCHEMA = "rebase";
+/**
+ * The principal of the current request, as text, or NULL in the server context.
+ *
+ * Never NULL for a user request — an anonymous one carries
+ * {@link ANONYMOUS_USER_ID} — which is what makes `IS NULL` a reliable test for
+ * the trusted server plane and `IS NOT NULL` a tautology.
+ */
+export declare const RLS_UID_SQL = "rebase.uid()";
+/** The request's roles as a comma-separated string, for `string_to_array`. */
+export declare const RLS_ROLES_SQL = "rebase.roles()";
+/** The request's JWT claims as `jsonb`, or `{}`. */
+export declare const RLS_JWT_SQL = "rebase.jwt()";
+/**
+ * The pre-1.0 spellings, for recognising policies and hand-written SQL that
+ * predate the move.
+ *
+ * Kept because policies outlive the server that wrote them: a database migrated
+ * by an older release still holds `auth.uid()` in its policy bodies until the
+ * next push or boot recompiles them, and anything that reads policies back has
+ * to recognise both eras or report the framework's own output as foreign drift.
+ * Also used to give a project whose `securityRules` contain raw `auth.uid()` a
+ * message naming the replacement, instead of a parse failure.
+ */
+export declare const LEGACY_RLS_SCHEMA = "auth";
+export declare const LEGACY_RLS_UID_SQL = "auth.uid()";
+export declare const LEGACY_RLS_ROLES_SQL = "auth.roles()";
+export declare const LEGACY_RLS_JWT_SQL = "auth.jwt()";
+/**
+ * Rewrites the pre-1.0 function calls in a fragment of policy SQL.
+ *
+ * Deliberately anchored on a word boundary and the schema qualifier, so a column
+ * called `auth_uid` or a table named `auth` is left alone.
+ */
+export declare function rewriteLegacyRlsFunctions(sql: string): string;
+/** Whether a fragment of SQL still calls the pre-1.0 functions. */
+export declare function usesLegacyRlsFunctions(sql: string): boolean;