palgres 0.3.1 → 0.3.2

package/types/palgres/src/dsl/policy.d.ts

@@ -15,9 +15,28 @@ import { type ColumnMap, type TableHandle } from './schema.js';
  *   .to("authenticated")
  *   .using("owner = (select auth.uid())");
  */
+/**
+ * A structured policy expression, as plain data: one node of the tree that a
+ * `USING`, `WITH CHECK` or CHECK expression is made of.
+ *
+ * You do not write these nodes by hand. Build them with the context passed to a
+ * table's `policies` (or `checks`) callback: `p.col(...)`, `p.auth.uid()`,
+ * `p.existsIn(...)` and the methods of {@link PolicyExprRef}. Unlike a raw SQL
+ * string, a structured expression has its column names checked at compile time,
+ * and `auth.uid()` is always written as `(SELECT auth.uid())`.
+ */
 export type PolicyExpr = {
     kind: "col";
     name: string;
+    /**
+     * Which table the column belongs to. When absent, the column is one of
+     * the policy's own table. When set, it is the alias of the table inside
+     * an `existsIn` subquery.
+     *
+     * This is what keeps a correlated subquery correct: without it,
+     * `team_id = team_id` would compare a column with itself, be true for
+     * every row, and the policy would let every row through.
+     */
     alias?: string;
 } | {
     kind: "authUid";
@@ -43,13 +62,51 @@ export type PolicyExpr = {
     expr: PolicyExpr;
     negated: boolean;
 } | {
+    /**
+     * A correlated `EXISTS (SELECT 1 FROM <table> <alias> WHERE <predicate>)`
+     * subquery.
+     *
+     * The subquery is written directly into the policy, not wrapped in a
+     * `SECURITY DEFINER` function, so the row-level security of the table it
+     * reads still applies inside it: it cannot reveal rows the caller could
+     * not read anyway.
+     */
     kind: "exists";
     table: string;
     alias: string;
+    /**
+     * The name of the policy's own table. The correlation needs it.
+     *
+     * Inside the subquery, Postgres resolves an unqualified column name to
+     * the inner table. A column of the policy's own table is therefore
+     * written qualified with this name (for example
+     * `"public"."documents"."team_id"`).
+     * Left unqualified, it would compare the inner column with itself
+     * (`pb_e1.team_id = pb_e1.team_id`), be true for every row, and every
+     * user would see every row.
+     */
     outer: string;
     predicate: PolicyExpr;
 };
+/**
+ * The comparison operators of a policy expression: `eq` (`=`), `neq` (`<>`),
+ * `gt` (`>`), `gte` (`>=`), `lt` (`<`) and `lte` (`<=`). `in` takes a list on
+ * its right-hand side; no builder method produces it, and neither `check()` nor
+ * `policySQL()` accepts it.
+ */
 export type PolicyBinOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in";
+/**
+ * A policy expression you can keep building on.
+ *
+ * You get one from the policy context (`p.col("owner")`, `p.auth.uid()`,
+ * `p.existsIn(...)`) and chain comparisons and logic onto it: `.eq()`,
+ * `.isNull()`, `.and()`, `.not()` and the rest. Every method returns a new
+ * `PolicyExprRef`; the expression itself stays plain data in `expr`. Pass the
+ * result to `.using()`, `.withCheck()` or `check()`.
+ *
+ * @example
+ * p.col("owner").eq(p.auth.uid()).and(p.col("deleted_at").isNull())
+ */
 export declare class PolicyExprRef {
     readonly expr: PolicyExpr;
     constructor(expr: PolicyExpr);
@@ -60,47 +117,216 @@ export declare class PolicyExprRef {
     gte(other: PolicyOperand): PolicyExprRef;
     lt(other: PolicyOperand): PolicyExprRef;
     lte(other: PolicyOperand): PolicyExprRef;
+    /**
+     * `IS NULL`, or `IS NOT NULL` when `negated` is `true`.
+     *
+     * Use this rather than `.eq(null)`: in SQL, `= NULL` is never true, it is
+     * always unknown. A common use is a partial index or policy condition such as
+     * `deleted_at IS NULL`.
+     *
+     * @param negated `true` for `IS NOT NULL`. Default `false`.
+     */
     isNull(negated?: boolean): PolicyExprRef;
     and(...others: PolicyExprRef[]): PolicyExprRef;
     or(...others: PolicyExprRef[]): PolicyExprRef;
     not(): PolicyExprRef;
 }
+/**
+ * A type annotation for a table used in `existsIn`, for when two table
+ * declarations refer to each other.
+ *
+ * Example: `memberships.household_id` references `households.id`, and the
+ * policy of `households` uses `existsIn(memberships, ...)`. Each `const` then
+ * needs the other to be initialized, and TypeScript gives up on both with
+ * error TS7022 and types them as `any`. That is worse than an error message:
+ * with `m.col(...)` typed as `any`, a misspelled column name in the policy
+ * compiles silently, and a row-level-security rule fails open. Only a type
+ * annotation on one of the two declarations breaks the cycle.
+ *
+ * `TableRef` is that annotation. It is the table-level counterpart of
+ * `references((): AnyColumn => y.id)`, but unlike `AnyColumn` it keeps the
+ * column names:
+ *
+ * ```ts
+ * const memberships: TableRef<"id" | "household_id" | "user_id", "memberships"> =
+ *   defineTable("memberships", {
+ *     columns: {
+ *       id: uuid().primaryKey(),
+ *       household_id: uuid().references(() => households.id),
+ *       user_id: text().notNull(),
+ *     },
+ *   });
+ * ```
+ *
+ * Because the names stay in `Cols`, `m.col("user")` still does not compile, and
+ * because `N` is given, the table keeps its key inside `defineSchema`. There is
+ * deliberately no looser `AnyTable` type that drops the column names: it would
+ * silence the cycle and quietly turn off column checking in your policies.
+ *
+ * @typeParam Cols The table's column names.
+ * @typeParam N The table's name.
+ */
 export type TableRef<Cols extends string, N extends string = string> = TableHandle<Record<Cols, ColumnMap[string]>, N>;
+/**
+ * The right-hand side of a comparison such as `.eq()`: another expression or a
+ * plain value.
+ *
+ * A plain value is always a literal, never a column: `.eq("owner")` compares
+ * with the string `'owner'`, not with the `owner` column. To compare with a
+ * column, write `.eq(p.col("owner"))`.
+ */
 export type PolicyOperand = PolicyExprRef | string | number | boolean | null;
+/**
+ * The context for writing an expression over one table's columns. A table's
+ * `policies`, `checks`, `indexes` and `foreignKeys` callbacks receive it.
+ *
+ * Column names are limited to the table's own columns, so a misspelled column
+ * is a compile error. This works because those options are callbacks, not
+ * plain arrays: TypeScript knows the table's columns when it types the
+ * callback, while a bare `policy("x")` could not know which table it is on.
+ *
+ * @typeParam Cols The table's column names.
+ */
 export interface PolicyExprCtx<Cols extends string = string> {
-    /** Bu tablonun bir kolonu. Bilinmeyen ad DERLENMEZ. */
+    /** A column of this table. An unknown column name does not compile. */
     col(name: Cols): PolicyExprRef;
+    /**
+     * "Does this row belong to a team I am a member of?": membership-based
+     * multi-tenancy, as a correlated `EXISTS` subquery on another table.
+     *
+     * ```ts
+     * policies: (p) => [
+     *   policy("team_read").for("select").using(
+     *     p.existsIn(teamMembers, (m) =>
+     *       m.col("team_id").eq(p.col("team_id"))
+     *        .and(m.col("user_id").eq(p.auth.uid()))),
+     *   ),
+     * ]
+     * ```
+     *
+     * `m` gives the columns of the membership table, `p` those of this table.
+     * Both are typed, and they are qualified differently in SQL. If they were
+     * mixed up, `team_id = team_id` would compare a column with itself and the
+     * policy would let every row through.
+     *
+     * Tables that refer to each other: if the membership table references this
+     * table and this table uses `existsIn` on it, annotate one declaration with
+     * {@link TableRef}. Otherwise TypeScript types both as `any` (error TS7022)
+     * and `m.col(...)` silently accepts any name.
+     *
+     * Recursion: the membership table's own policy must not use `existsIn` back
+     * into this table; give it the simple rule `user_id = auth.uid()`. If two
+     * tables' policies query each other, Postgres fails at query time with
+     * `infinite recursion detected in policy for relation ...`. Keep it one-way:
+     * the membership table has the simple policy, and every other table
+     * subqueries into it.
+     *
+     * @param table The table to look in, for example the membership table.
+     * @param predicate Builds the `WHERE` condition of the subquery from that
+     *                  table's columns (`m`) and this table's (`p`).
+     */
     existsIn<C extends ColumnMap, N extends string>(table: TableHandle<C, N>, predicate: (row: PolicyExprCtx<Extract<keyof C, string>>) => PolicyExprRef): PolicyExprRef;
+    /**
+     * The caller. `p.auth.uid()` is the signed-in user's id. It is written into
+     * SQL as `(SELECT auth.uid())`, so Postgres evaluates it once per statement
+     * rather than once per row. Not allowed in a CHECK constraint.
+     */
     auth: {
         uid(): PolicyExprRef;
     };
+    /** A plain value, for saying explicitly that one side of a comparison is a literal. */
     lit(v: string | number | boolean | null): PolicyExprRef;
     and(...parts: PolicyExprRef[]): PolicyExprRef;
     or(...parts: PolicyExprRef[]): PolicyExprRef;
     not(part: PolicyExprRef): PolicyExprRef;
 }
+/**
+ * Builds an expression context ({@link PolicyExprCtx}) by hand.
+ *
+ * `defineTable` builds one for you, with the table's own column names, and
+ * passes it to the `policies`, `checks`, `indexes` and `foreignKeys`
+ * callbacks. Call this yourself only to write an expression outside a table
+ * definition.
+ *
+ * @param _columns The table's column names. Only their type is used: it limits
+ *                 `col()` to these names.
+ * @param depth How deep inside `existsIn` subqueries this context is: `0` for
+ *              the policy's own table. Leave it at the default.
+ * @param ownTable The name of the policy's own table, needed for `existsIn`.
+ */
 export declare function exprCtx<Cols extends string = string>(_columns?: readonly Cols[], depth?: number, 
+/**
+ * The name of the policy's own table. It stays the same at every nesting
+ * depth.
+ *
+ * Inside a subquery, a column without an alias belongs to the policy's own
+ * table and is written qualified with this name. That holds for `existsIn`
+ * nested inside `existsIn` too, so the policy's own columns can be used at
+ * any depth. Without it, an expression that uses `existsIn` cannot be turned
+ * into SQL.
+ */
 ownTable?: string): PolicyExprCtx<Cols>;
 /** The SQL command a policy applies to. `"all"` covers SELECT/INSERT/UPDATE/DELETE. */
 export type PolicyCommand = "all" | "select" | "insert" | "update" | "delete";
 /** Whether a policy is permissive (OR-combined, the default) or restrictive
  * (AND-combined). Mirrors Postgres `CREATE POLICY ... AS PERMISSIVE|RESTRICTIVE`. */
 export type PolicyMode = "permissive" | "restrictive";
+/**
+ * A finished row-level-security policy, as plain serializable data. `policy()`
+ * builds one (it is the builder's `_def`); a table's `policies` callback may
+ * also return one directly.
+ *
+ * - `name`: the policy name, unique per table.
+ * - `command`: the SQL command it applies to (`FOR` clause).
+ * - `roles`: the database roles it applies to (`TO` clause). An empty array
+ *   means the policy applies to PUBLIC (all roles), the Postgres default.
+ * - `using`: the `USING (...)` row-visibility expression, or `null` when none.
+ * - `withCheck`: the `WITH CHECK (...)` write-validation expression, or `null`.
+ * - `permissive`: `true` for `AS PERMISSIVE` (default), `false` for restrictive.
+ */
 export interface PolicyDef {
     name: string;
     command: PolicyCommand;
     roles: string[];
+    /** A structured expression (preferred) or a raw SQL string, or `null` for none. */
     using: string | PolicyExpr | null;
     withCheck: string | PolicyExpr | null;
     permissive: boolean;
     /** false: the columns it reads get no index of their own from it (withoutIndexes()). */
     indexes?: false;
 }
+/**
+ * The Postgres roles a policy can apply to, passed to `.to(...)`.
+ *
+ * The roles Palbase creates are named literally, so a typo such as
+ * `"authenitcated"` is a compile error instead of reaching a migration. Two
+ * more forms exist for a database Palbase took over, whose policies may name
+ * roles of its own: `"public"` (every role) and `` `role:${name}` `` (a role
+ * by its own name); `palgres pull` writes them.
+ *
+ * You do not need to name the `backend_*` roles: Palbase adds them for you.
+ * They are still accepted, so code that names them keeps compiling.
+ */
 export type PolicyRole = "anon" | "authenticated" | "service_role" | "backend_anon" | "backend_authenticated" | "backend_service_role"
 /** Every role (Postgres' PUBLIC): a database taken over may have a policy for it (palgres pull writes it). */
  | "public"
 /** A database role by its own name: what a database taken over has a policy for (palgres pull writes it). */
  | `role:${string}`;
+/**
+ * Fluent row-level-security policy builder, returned by {@link policy}.
+ *
+ * Defaults:
+ *  - `command`: `"all"`: applies to every SQL command unless `.for(...)` narrows it.
+ *  - `roles`: `["authenticated"]`: the common case is "this rule applies to
+ *    signed-in users". Call `.to(...)` to change it; `.to()` with no roles
+ *    targets PUBLIC (all roles).
+ *  - `using` / `withCheck`: `null`: no row filter and no write check until set.
+ *  - `permissive`: `true`: `AS PERMISSIVE` (permissive policies OR together).
+ *
+ * Each method changes the policy in place and returns the same builder, so
+ * calls chain. The finished {@link PolicyDef} is in `_def`; put the builder
+ * itself in a table's `policies` list.
+ */
 export declare class PolicyBuilder {
     readonly _def: PolicyDef;
     constructor(name: string);
@@ -116,6 +342,23 @@ export declare class PolicyBuilder {
      * policy("p").to() // PUBLIC
      */
     to(...roles: PolicyRole[]): this;
+    /**
+     * The `USING (...)` expression: which existing rows the policy lets the
+     * caller see (and update or delete).
+     *
+     * Prefer a structured expression, built with the context the `policies`
+     * callback receives. Its column names are checked at compile time:
+     *
+     * ```ts
+     * policies: (p) => [
+     *   policy("owner_read").for("select").using(p.col("owner").eq(p.auth.uid())),
+     * ]
+     * ```
+     *
+     * A raw SQL string is also accepted, as an escape hatch for what the
+     * structured form cannot express. A string gets no column-name checking: a
+     * mistake in it shows up only when Postgres runs `CREATE POLICY` at deploy.
+     */
     using(expr: string | PolicyExprRef): this;
     /**
      * "Rows of THIS table whose owner the caller is a member of" — the membership
@@ -145,6 +388,12 @@ export declare class PolicyBuilder {
         column?: string;
         userColumn?: string;
     }): this;
+    /**
+     * The `WITH CHECK (...)` expression: rows written by an `INSERT` or `UPDATE`
+     * must satisfy it, or the write is rejected. Takes the same two forms as
+     * `using()`: a structured expression (preferred, column names checked at
+     * compile time) or a raw SQL string.
+     */
     withCheck(expr: string | PolicyExprRef): this;
     /**
      * The columns this policy reads get no index of their own from it (Palbase
@@ -166,10 +415,50 @@ export declare class PolicyBuilder {
  *             `(table, name)`, so names must be unique per table.
  */
 export declare function policy(name: string): PolicyBuilder;
+/**
+ * A named CHECK constraint on a table: its name and its SQL expression.
+ *
+ * `check()` returns one, with the typed expression already compiled to SQL. A
+ * table's `checks` may also be a plain array of these, with `expr` written as
+ * raw SQL. Both forms end up the same. A deploy matches CHECKs by name and
+ * compares `expr` as written (ignoring leading and trailing spaces): the same
+ * text is left alone, and changed text replaces the constraint — `n > 0` and
+ * `(n > 0)` count as a change.
+ */
 export interface CheckDef {
     name: string;
+    /** The SQL expression. `check()` compiles it for you; in a plain `checks` array you write it yourself. */
     expr: string;
 }
+/**
+ * `check("<name>", <expression>)`: a typed CHECK constraint.
+ *
+ * The expression is written with the same builder as a policy expression; this
+ * DSL has one expression language, not two. Column names come from the context
+ * the table's `checks` callback receives, so a misspelled name does not
+ * compile. With a raw SQL string, the same mistake shows up only when Postgres
+ * runs `ALTER TABLE ... ADD CONSTRAINT` at deploy.
+ *
+ * A CHECK may only read the current row's columns: `existsIn(...)`,
+ * `auth.uid()` and the `in` operator are rejected with an error when the table
+ * is declared.
+ *
+ * ```ts
+ * defineTable("payments", {
+ *   columns: { amount: integer().notNull(), currency: text().notNull() },
+ *   checks: (c) => [
+ *     check("payments_amount_pos", c.col("amount").gt(0)),
+ *     check("payments_currency_set", c.col("currency").isNull(true)),
+ *   ],
+ * })
+ * ```
+ *
+ * @param name The constraint name; it must not be empty. Palbase matches CHECK
+ *             constraints by name (a changed expression means DROP and ADD),
+ *             so the name must be unique per table.
+ * @param expr The condition every row must satisfy.
+ * @returns The constraint, with its expression compiled to SQL.
+ */
 export declare function check(name: string, expr: PolicyExprRef): CheckDef;
 /**
  * The SQL of a policy expression: a raw string as it is, a structure rendered.

package/types/palgres/src/dsl/raw.d.ts

@@ -1,3 +1,37 @@
+/**
+ * A named raw-SQL DDL object declared in a schema file (`db/public.ts`,
+ * `db/billing.ts`, …) for what the typed DSL cannot express: an index method
+ * other than btree (`gin`, `gist`, `brin`, `hash`), an opclass, `EXCLUDE`
+ * constraints, views, and PL/pgSQL functions.
+ *
+ * REACH FOR THE TYPED FIELD FIRST. These are declarative and should not come
+ * through here:
+ *   - a CHECK constraint      → `checks: [{ name, expr }]`, or the typed
+ *                               `checks: (c) => [check(name, c.col("n").gt(0))]`
+ *   - a partial index         → `index(n).on(…).where(…)`
+ *   - an expression index     → `index(n).onExpression("lower(email)")`
+ *   - a covering index        → `index(n).on(…).include([…])`
+ *   - a UNIQUE or PARTIAL UNIQUE index → `index(n).unique().where(…)`
+ *   - a composite FOREIGN KEY → `foreignKeys: (c) => [foreignKey(n).on(…).references(…)]`
+ * Those are diffed, validated against the live database before the push, and
+ * their mistakes answer you where you write them. A `raw()` is none of that.
+ *
+ * The deploy runs `up` verbatim on the privileged DDL connection — the same
+ * trust as `policy().using()`. It is matched by `name` across deploys:
+ *   - the same text (leading and trailing spaces aside) → nothing happens;
+ *   - an index whose text changes under the same name → refused: an index is
+ *     built `CONCURRENTLY` next to the one serving, so give the new one its own
+ *     name, and the old one goes at complete;
+ *   - anything else whose text changes → applied again (after its old `drop`,
+ *     unless the new text says `CREATE OR REPLACE`).
+ * A raw index removed from the schema is dropped at complete.
+ *
+ * There is no teardown option on the TABLE-level form: a `drop` belongs to a
+ * schema-level unit (`RawUnitDef`, below), whose deploy runs it, and
+ * `defineTable` refuses a table-level `raw()` that carries one. A trigger, a
+ * rule or a view needs a `drop` — a rollback has to be able to take it back —
+ * so declare it as a schema-level unit.
+ */
 export interface RawConstraintDef {
     name: string;
     up: string;
@@ -36,6 +70,28 @@ export interface RawUnitDef extends RawConstraintDef {
      */
     before?: boolean;
 }
+/**
+ * Declares a named raw-SQL unit, for what the typed DSL cannot express.
+ *
+ * With two arguments it is the table-level form ({@link RawConstraintDef}),
+ * for `defineTable`'s `raw: [...]`. With an `options` argument it is the
+ * schema-level form ({@link RawUnitDef}), for
+ * `defineSchema(name, { tables, raw: [...] })`: `drop` is the SQL that tears
+ * the unit down, and `before: true` makes it before the schema's tables.
+ *
+ * @param name The unit's name. It identifies the unit from one deploy to the
+ *             next, so two units in one schema cannot share it.
+ * @param up The SQL the deploy runs, verbatim, to create the unit.
+ * @param options Schema-level units only: `drop` and `before`.
+ * @returns The unit, to place in a `raw: [...]` list.
+ *
+ * @example
+ * ```ts
+ * raw("monthly_totals",
+ *   `CREATE MATERIALIZED VIEW public.monthly_totals AS SELECT … FROM public.entries GROUP BY …`,
+ *   { drop: "DROP MATERIALIZED VIEW public.monthly_totals" })
+ * ```
+ */
 export declare function raw(name: string, up: string): RawConstraintDef;
 export declare function raw(name: string, up: string, options: {
     drop?: string;