@rebasepro/types 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/types/policy.ts

@@ -32,7 +32,7 @@ export type PolicyExpression =
     | 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
@@ -40,7 +40,7 @@ export type PolicyExpression =
  * 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
@@ -58,7 +58,7 @@ export 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.
  *
@@ -117,7 +117,7 @@ export interface NotPolicyExpression {
 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 {
@@ -129,7 +129,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 {
@@ -139,7 +139,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 {
@@ -149,11 +149,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
@@ -168,8 +168,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
@@ -207,7 +207,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
@@ -272,14 +272,14 @@ export interface LiteralPolicyOperand {
     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/src/types/properties.ts

@@ -218,14 +218,21 @@ export interface BaseProperty<CustomProps = unknown> {
     validation?: PropertyValidationSchema;
 
     /**
-     * Never include this column in an API response.
+     * Never mention this column on the API surface, in either direction.
      *
      * For secrets the server must store and read but no client should ever
      * receive — password hashes, verification tokens. The value is still
      * written and queryable server-side; it is stripped from every row the API
-     * serves, for every caller, including admins and service keys.
+     * serves, for every caller, including admins and service keys, and it is
+     * absent from every generated description of the surface: the SDK's `Row`,
+     * `Insert` and `Update` types, and the OpenAPI schemas, filters and
+     * parameters.
      *
-     * This is a server-side guarantee, unlike `ui.hideFromCollection`, which
+     * The generated types are a *description*, not a second enforcement point:
+     * the server still accepts such a field on a write, because that is how the
+     * value gets written in the first place. Nothing generated offers it.
+     *
+     * 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.
      */
@@ -1035,6 +1042,18 @@ export interface ImageResize {
  */
 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
@@ -1084,8 +1103,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.
@@ -1101,14 +1122,19 @@ 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;
 
     // ═══════════════════════════════════════════════════════════════════════
     // VALIDATION CONDITIONS

package/src/types/rls-functions.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 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 const RLS_UID_SQL = `${REBASE_SCHEMA}.uid()`;
+
+/** The request's roles as a comma-separated string, for `string_to_array`. */
+export const RLS_ROLES_SQL = `${REBASE_SCHEMA}.roles()`;
+
+/** The request's JWT claims as `jsonb`, or `{}`. */
+export const RLS_JWT_SQL = `${REBASE_SCHEMA}.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 const LEGACY_RLS_SCHEMA = "auth";
+export const LEGACY_RLS_UID_SQL = `${LEGACY_RLS_SCHEMA}.uid()`;
+export const LEGACY_RLS_ROLES_SQL = `${LEGACY_RLS_SCHEMA}.roles()`;
+export const LEGACY_RLS_JWT_SQL = `${LEGACY_RLS_SCHEMA}.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 function rewriteLegacyRlsFunctions(sql: string): string {
+    return sql.replace(
+        /\bauth\.(uid|jwt|roles)\s*\(\s*\)/gi,
+        (_match, fn: string) => `${REBASE_SCHEMA}.${fn.toLowerCase()}()`
+    );
+}
+
+/** Whether a fragment of SQL still calls the pre-1.0 functions. */
+export function usesLegacyRlsFunctions(sql: string): boolean {
+    return /\bauth\.(uid|jwt|roles)\s*\(\s*\)/i.test(sql);
+}

package/src/types/search.ts

@@ -0,0 +1,247 @@
+/**
+ * Opt-in full-text search configuration.
+ *
+ * ## Why this is opt-in
+ *
+ * Without a `search` block, `.search()` behaves exactly as it always has: an
+ * `ILIKE '%term%'` OR-ed across the collection's top-level, non-enum `string`
+ * properties. That default is unchanged and will stay unchanged — declaring
+ * this block is the only way to get anything else.
+ *
+ * The default has three limits that no amount of tuning inside it can fix:
+ * it cannot reach inside `map` (JSONB) or `array` properties, it has no notion
+ * of relevance, and a leading `%` means it can never use an index. Collections
+ * that outgrow those limits declare what they want searched; collections that
+ * have not are left completely alone.
+ *
+ * ## What declaring it does
+ *
+ * One `tsvector` column, `GENERATED ALWAYS AS … STORED`, plus one GIN index on
+ * it. Postgres recomputes the column on every write of a source field, so it
+ * cannot drift from the row, and refuses any attempt to write it directly.
+ * `.search()` then compiles to `@@ websearch_to_tsquery(…)` against that
+ * column, which stems, drops stopwords, AND-es the terms, and ranks.
+ *
+ * These are stated consequences, not hidden ones: the column and the index
+ * appear in generated DDL, in `schema.generated.ts`, and in `rebase db push`
+ * output like any other declared object.
+ *
+ * @example
+ * ```ts
+ * const talents: PostgresCollectionConfig = {
+ *     slug: "talents",
+ *     table: "talents",
+ *     properties: { … },
+ *     search: {
+ *         language: "spanish",
+ *         unaccent: true,
+ *         fields: [
+ *             { path: "full_name", weight: "A" },
+ *             "location",
+ *             "questionnaire.certifications"   // into the JSONB
+ *         ]
+ *     }
+ * };
+ * ```
+ *
+ * @group Search
+ */
+export interface SearchConfig {
+    /**
+     * The fields to index, in the author's own words. Nothing is inferred: a
+     * field is searched if and only if it is named here.
+     *
+     * A bare string is shorthand for `{ path, weight: "B" }`.
+     *
+     * A path may address:
+     * - a top-level `string` property — `"full_name"`
+     * - a `string[]` property — `"tags"` (every element is indexed)
+     * - a path into a `map` property — `"questionnaire.certifications"`,
+     *   which indexes every string found at or below that point, including
+     *   nested objects and arrays of strings. JSON *keys* are never indexed,
+     *   only values.
+     *
+     * A path that does not resolve to one of those is a boot-time error, not
+     * a silent omission — a search field you believe is live and is not is the
+     * failure this whole block exists to prevent.
+     */
+    fields: readonly (string | SearchField)[];
+
+    /**
+     * The Postgres text search configuration, which decides stemming and
+     * stopwords. `"spanish"` stems `auditores` to `auditor` and drops `de`;
+     * `"simple"` does neither.
+     *
+     * Defaults to `"simple"`, which is the only choice that is never wrong:
+     * a stemmer applied to the wrong language silently mangles lexemes. Set it
+     * to your content's language to get stemming.
+     *
+     * @default "simple"
+     */
+    language?: string;
+
+    /**
+     * Fold accents before indexing, so `auditoria` matches `auditoría`.
+     *
+     * This is not cosmetic in accented languages. Postgres stems the two
+     * spellings to *different* lexemes — `to_tsvector('spanish', 'auditoría')`
+     * yields `auditor` while `'auditoria'` yields `auditori` — so without this
+     * a query typed without accents misses the rows that carry them, which is
+     * most queries most users type.
+     *
+     * Requires the `unaccent` extension. Boot fails with an explicit message if
+     * it is not installed and cannot be created, rather than quietly indexing
+     * accented text as-is.
+     *
+     * @default false
+     */
+    unaccent?: boolean;
+
+    /**
+     * Name of the generated column holding the `tsvector`.
+     *
+     * Only change this if `search_vector` collides with a column you already
+     * have. It is part of your schema once created: renaming it later is a
+     * column drop and recreate, which rewrites the table.
+     *
+     * @default "search_vector"
+     */
+    column?: string;
+
+    /**
+     * Also match on trigram similarity, so near-misses and typos still rank —
+     * `iso14000` reaching `ISO 14001`, which no amount of stemming will do
+     * because they are simply different lexemes.
+     *
+     * Adds a second generated `text` column and a GIN trigram index alongside
+     * the `tsvector`, and requires the `pg_trgm` extension. Costs write time
+     * and disk; buys the single most common class of failed search.
+     *
+     * Also changes what `_score` means: the trigram similarity is added to
+     * `ts_rank`. It has to be. A typo matches nothing on the exact path, so
+     * every row this finds has a `ts_rank` of zero — ranking by that alone
+     * would order the results arbitrarily, which is the failure `fuzzy` exists
+     * to fix.
+     *
+     * @default false
+     */
+    fuzzy?: boolean;
+
+    /**
+     * Similarity floor for {@link SearchConfig.fuzzy}, between 0 and 1. A row
+     * whose trigram similarity to the query falls below this never matches on
+     * the fuzzy path (it can still match on the exact one).
+     *
+     * Lower admits more typos and more noise. Ignored unless `fuzzy` is set.
+     *
+     * @default 0.3
+     */
+    fuzzyThreshold?: number;
+}
+
+/**
+ * One indexed field, with the weight it carries in the ranking.
+ *
+ * @group Search
+ */
+export interface SearchField {
+    /**
+     * Property name, or dotted path into a `map` property.
+     * @see SearchConfig.fields
+     */
+    path: string;
+
+    /**
+     * Postgres weight class. `ts_rank` scores an `A` hit far above a `D` hit,
+     * which is how a name outranks a passing mention in a long description.
+     *
+     * The four classes are Postgres's own and there are exactly four.
+     *
+     * @default "B"
+     */
+    weight?: SearchWeight;
+}
+
+/**
+ * Postgres tsvector weight classes, strongest to weakest.
+ *
+ * @group Search
+ */
+export type SearchWeight = "A" | "B" | "C" | "D";
+
+/** The column name used when {@link SearchConfig.column} is not given. */
+export const DEFAULT_SEARCH_COLUMN = "search_vector";
+
+/** The text search configuration used when {@link SearchConfig.language} is not given. */
+export const DEFAULT_SEARCH_LANGUAGE = "simple";
+
+/** The weight a field carries when it does not name one. */
+export const DEFAULT_SEARCH_WEIGHT: SearchWeight = "B";
+
+/** The similarity floor used when {@link SearchConfig.fuzzyThreshold} is not given. */
+export const DEFAULT_FUZZY_THRESHOLD = 0.3;
+
+/**
+ * Sort keys a query computes rather than reads from a column.
+ *
+ * `orderBy` is otherwise typed against the row — `keyof M` — which is exactly
+ * right for a column and exactly wrong for relevance: `_score` is produced by
+ * the query, so it appears in no generated row type and a project with a
+ * generated SDK could not name it. The runtime accepted it, the docs told
+ * people to use it, and the types rejected it.
+ *
+ * Kept as a named union rather than a loose `string` so the other half of the
+ * guarantee survives: a typo'd column is still a compile error, and remains a
+ * 400 at runtime rather than a silently unsorted list.
+ *
+ * `_distance` is deliberately not here. A vector search orders by distance on
+ * its own and overrides `orderBy` outright, so naming it would imply a choice
+ * the caller does not have.
+ *
+ * @group Search
+ */
+export type ComputedSortField = typeof RELEVANCE_SORT_FIELD;
+
+/**
+ * The relevance sort key. Valid only on a collection that declares a
+ * {@link SearchConfig} *and* on a query that carries a search string; anywhere
+ * else it is an unknown field and the request is refused.
+ */
+export const RELEVANCE_SORT_FIELD = "_score";
+
+/**
+ * One field that matched, and the text around the hit.
+ *
+ * Returned per row as `_matches` when a query asks for it — see the `explain`
+ * option on `.search()`. Answers the question a ranked list otherwise leaves
+ * open: *why is this row here?* A candidate surfacing for "iso 14001" because
+ * of a certification is a different result from one surfacing because the
+ * string appears in a paragraph about something else, and the score alone
+ * cannot tell them apart.
+ *
+ * @group Search
+ */
+export interface SearchMatch {
+    /**
+     * The declared field path that matched, exactly as written in
+     * {@link SearchConfig.fields} — e.g. `"questionnaire.certifications"`.
+     * Map it to a label for display; the path is stable, a label is yours.
+     */
+    field: string;
+
+    /**
+     * The matching text, with each hit wrapped in `<mark>…</mark>`.
+     *
+     * Built by Postgres's `ts_headline` over the same normalized text that was
+     * indexed. With {@link SearchConfig.unaccent} on that means the snippet
+     * reads with accents folded — `Auditoria` rather than `Auditoría`. That is
+     * deliberate: `ts_headline` over the *original* text cannot find a hit the
+     * unaccented query produced, so it returns the text with nothing marked at
+     * all. A readable snippet that highlights beats a prettier one that
+     * silently does not.
+     *
+     * Contains markup by construction. Render it as HTML or strip the tags —
+     * do not display it raw, and do not trust it as plain text.
+     */
+    snippet: string;
+}