@rebasepro/server-postgres 0.11.1-canary.gfd39654 → 0.12.1-canary.g009ed95

package/dist/utils/drizzle-conditions.d.ts

@@ -1,7 +1,54 @@
 import { SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
-import { FilterValues, WhereFilterOp, LogicalCondition, FilterCondition, ResolvedRelation } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, WhereFilterOp, LogicalCondition, FilterCondition, ResolvedRelation, ResolvedForeignKeyOnTarget, ResolvedManyToMany } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * What to do with a filter field that resolves to no column at all.
+ *
+ *  - `"error"` (default) — reject the request. A filter that cannot be
+ *    compiled is *dropped*, and dropping a condition can only ever widen the
+ *    result set. On a data plane where row-level security is the last line of
+ *    defence, a typo'd or renamed filter key therefore runs the query without
+ *    that condition and returns everything RLS happens to allow.
+ *  - `"warn"` — the historical behaviour: log and silently drop the condition.
+ *    Only for a deployment that knowingly sends filter keys the table does not
+ *    have and has satisfied itself that widening is safe there.
+ */
+export type UnknownFilterFieldsMode = "error" | "warn";
+/** Set the process-wide behaviour for unresolvable filter fields. */
+export declare function configureUnknownFilterFields(mode: UnknownFilterFieldsMode): void;
+/** The process-wide behaviour for unresolvable filter fields. */
+export declare function getUnknownFilterFieldsMode(): UnknownFilterFieldsMode;
+/** Per-call context for compiling a filter into SQL. */
+export interface FilterCompilationOptions {
+    /**
+     * Overrides the process-wide {@link UnknownFilterFieldsMode} for this call.
+     */
+    unknownFields?: UnknownFilterFieldsMode;
+    /**
+     * The collection the filter is written against. Its resolved relations are
+     * what turn an owning-relation filter key into the foreign-key column it
+     * actually lives in; without it only the default key shapes can be guessed.
+     */
+    collection?: CollectionConfig;
+    /**
+     * The driver's registry, for relations whose link is not on this row at
+     * all. A `manyToMany` compiles to an `EXISTS` over its junction and a
+     * `hasMany`/`hasOne` to one over the target table — neither of which this
+     * builder can reach from the collection alone.
+     */
+    registry?: PostgresCollectionRegistry;
+    /**
+     * The key column of the table being filtered — what those `EXISTS`
+     * subqueries correlate back to.
+     *
+     * It has to be the Drizzle column object rather than a name: a column
+     * renders qualified with its own table, which is what binds it to the
+     * *outer* row instead of to the junction or target aliased inside the
+     * subquery. See {@link DrizzleConditionBuilder.buildRelationFilterCondition}.
+     */
+    sourceIdColumn?: AnyPgColumn;
+}
 /** Drizzle dynamic query builder — accepts innerJoin + where chaining */
 export interface DrizzleDynamicQuery {
     innerJoin(table: PgTable<any>, condition: SQL): this;
@@ -40,10 +87,11 @@ export declare class DrizzleConditionBuilder {
      */
     static buildRelationScopeCondition(relation: ResolvedRelation, 
     /**
-     * Lazy: only `via` and `belongsTo` need the parent's own table. A
-     * foreign key on the target and a junction are both expressible from
-     * the parent's *id* alone, and requiring the table for them would make
-     * a child listing fail on a parent whose table isn't registered.
+     * Lazy: `via`, `belongsTo`, and a foreign key that points at a
+     * `sourceKey` need the parent's own table. A junction and a plain
+     * foreign key are expressible from the parent's *id* alone, and
+     * requiring the table for them would make a child listing fail on a
+     * parent whose table isn't registered.
      */
     parent: () => {
         table: PgTable<any>;
@@ -59,14 +107,121 @@ export declare class DrizzleConditionBuilder {
      * that revisits a table (a self-referencing many-to-many) unambiguous.
      */
     private static buildJoinPathScopeCondition;
+    /**
+     * What a filter field names, or `undefined` if it names nothing.
+     *
+     * Three ways a field resolves. It may address its column directly; it may
+     * be an owning relation, whose foreign key is a column here; or it may be
+     * a relation whose link lives on another table entirely, which compiles to
+     * a subquery instead of a column. Only a field that resolves to *none* of
+     * them is an error, and by default it is one: see
+     * {@link UnknownFilterFieldsMode} for why silently dropping it is a
+     * data-exposure primitive rather than a convenience.
+     *
+     * For an owning relation the relation's own `localKey` is the authority,
+     * not `<field>_id`. The default local key is `generateForeignKeyName`,
+     * which snake-cases *and singularises* — `userProfile` → `user_profile_id`,
+     * `users` → `user_id` — and it can be overridden outright. Guessing
+     * `<field>_id` therefore misses perfectly ordinary owning relations, and
+     * with this resolution failing closed that miss is a 400 on a filter that
+     * has nothing wrong with it. The guesses stay, last, for callers that hand
+     * over no collection to resolve against.
+     *
+     * The subquery kinds need a registry and the source table's key column on
+     * top of the collection. A caller that supplies neither gets the behaviour
+     * it had before they were compilable — unresolvable, and so fail-closed —
+     * rather than a half-built condition.
+     */
+    private static resolveFilterTarget;
     /**
      * Build filter conditions from FilterValues
      */
-    static buildFilterConditions<M extends Record<string, unknown>>(filter: FilterValues<Extract<keyof M, string>>, table: PgTable<any>, collectionPath: string): SQL[];
+    static buildFilterConditions<M extends Record<string, unknown>>(filter: FilterValues<Extract<keyof M, string>>, table: PgTable<any>, collectionPath: string, options?: FilterCompilationOptions): SQL[];
     /**
      * Build logical conditions recursively from LogicalCondition or FilterCondition
      */
-    static buildLogicalConditions(cond: LogicalCondition | FilterCondition, table: PgTable<any>, collectionPath: string): SQL | null;
+    static buildLogicalConditions(cond: LogicalCondition | FilterCondition, table: PgTable<any>, collectionPath: string, options?: FilterCompilationOptions): SQL | null;
+    /** Dispatch a resolved filter field onto the shape it actually compiles to. */
+    private static compileFilterTarget;
+    /**
+     * A filter on a relation that owns no column on this row — `EXISTS` over
+     * the rows it reaches.
+     *
+     * `posts` filtered by `tags == <tagId>` is not a comparison on `posts`; it
+     * is a question about the junction:
+     *
+     *     EXISTS (SELECT 1 FROM posts_tags AS j
+     *             WHERE j.post_id = posts.id AND j.tag_id = <tagId>)
+     *
+     * which is {@link buildRelationScopeCondition}'s many-to-many shape with
+     * source and target swapped — there the junction's *target* column
+     * correlates and the source is pinned; here the *source* column correlates
+     * and the target is what the filter constrains.
+     *
+     * `hasMany`/`hasOne` are the same shape one table over: the target row
+     * carries the foreign key, so the correlation is on that key and the
+     * compared column is the target's own id.
+     *
+     * `EXISTS` and not a join, for the reason the scope condition gives: a join
+     * through a junction multiplies the outer rows by the number of matching
+     * links, which duplicates results and silently breaks `limit`/`offset`.
+     *
+     * Everything inside the subquery is referenced by identifier against a
+     * local alias, and only `sourceIdColumn` stays a Drizzle column object —
+     * again see {@link buildRelationScopeCondition}, which explains why a
+     * column object renders against whatever table the surrounding builder
+     * thinks is current and so cannot be used for the inner references. The
+     * alias is also what keeps a self-referential relation unambiguous
+     * (`categories.children`, or a many-to-many whose junction and target are
+     * the same table), where the subquery's table and the outer one coincide.
+     */
+    static buildRelationFilterCondition(relation: ResolvedForeignKeyOnTarget | ResolvedManyToMany, op: WhereFilterOp, value: unknown, sourceIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, field: string, collectionPath: string): SQL;
+    /**
+     * The inner predicate of a relation filter, and whether the `EXISTS`
+     * wrapping it is negated.
+     *
+     * Negation is `NOT EXISTS` of the *positive* predicate, never `EXISTS` of a
+     * negated one. On a many-valued relation the two are different questions:
+     * `EXISTS (… AND tag_id != X)` asks "does some tag differ from X", which is
+     * true of nearly every post with more than one tag and answers nothing
+     * anybody asked. `NOT EXISTS (… AND tag_id = X)` asks "is X absent", which
+     * is what unticking a value in a filter control means — and it makes `==`
+     * and `!=` partition the rows, the way a filter implies they do.
+     *
+     * `is-null`/`is-not-null` drop the predicate entirely: with nothing but the
+     * correlation left, they become "has no related row at all" and "has at
+     * least one", which is the only reading of null a link can have.
+     *
+     * Under RLS, "no related row" means *no row this reader can see*. A junction
+     * with row-level security but no `SELECT` policy for `rebase_user` is opaque
+     * to it, so every row comes back looking unlinked and `is-null` matches all
+     * of them. That is not a leak — the outer table's own policies still decide
+     * which rows exist at all, and the positive direction correctly returns
+     * nothing — but it over-reports, and the cause is a missing junction policy
+     * rather than anything here. Rebase derives one for a declared many-to-many;
+     * a hand-written schema has to supply it.
+     *
+     * `in`/`not-in` against a *null value* mean the same thing, rather than
+     * membership of an empty list. Membership against null is not a membership
+     * question, and the admin's "filter for null values" control emits the
+     * operator that happens to be selected — on a to-many relation that is
+     * always `in` or `not-in`, because those are the only ones the multi-select
+     * can produce. Reading `["in", null]` as an empty list would answer "posts
+     * with no tags" with no posts at all.
+     *
+     * An empty `in` list compiles to `FALSE` rather than being dropped. Dropped
+     * is what the column path does, and dropping a condition widens the result
+     * — the whole reason this resolution fails closed. `in []` matches nothing
+     * and `not-in []` matches everything, and `NOT EXISTS (… AND FALSE)` gives
+     * the second for free.
+     *
+     * Anything else is rejected. Returning `null` for an operator this cannot
+     * express would drop the condition, and the operators the admin offers for
+     * a relation are exactly the six below.
+     */
+    private static buildRelationFilterPredicate;
+    /** The column a table's rows are keyed by: its primary key, else `id`. */
+    private static primaryKeyColumn;
     /**
      * Build a single filter condition for a specific operator and value
      */

package/dist/utils/pg-error-utils.d.ts

@@ -28,6 +28,25 @@ export declare function extractPgError(error: unknown): PostgresError | null;
  * Walk the error cause chain and return the deepest meaningful message.
  */
 export declare function extractCauseMessage(error: unknown): string | null;
+export interface ConnectFailure {
+    /** True when retrying cannot help: the connection string itself is wrong. */
+    fatal: boolean;
+    /** The deepest message available — the Postgres one where there is one. */
+    reason: string;
+    /** The `SQLSTATE`, when the failure came from Postgres rather than the socket. */
+    code?: string;
+}
+/**
+ * Describe a failed connection attempt in terms a developer can act on.
+ *
+ * The error a caller catches is Drizzle's wrapper: its message is
+ * `Failed query: SELECT 1` and its stack runs through drizzle internals, while
+ * the sentence that says what is actually wrong — "password authentication
+ * failed for user …", "database … does not exist" — sits in `.cause`. Logging
+ * the wrapper, as the bootstrapper used to, tells a developer with a typo in
+ * their `DATABASE_URL` nothing at all.
+ */
+export declare function classifyConnectFailure(error: unknown): ConnectFailure;
 /**
  * Detect whether an error is specifically a role-switching permission failure
  * (e.g. "permission denied to set role" or "must be member of role"),
@@ -52,12 +71,15 @@ export declare function pgErrorToFriendlyMessage(pgError: PostgresError, context
 /**
  * Sanitize any error into a message safe and helpful for the client.
  *
- * Extracts the PG error from the Drizzle cause chain when possible;
- * falls back to a generic message that doesn't leak SQL.
+ * A deliberate 4xx (`ApiError`) passes through untouched — the server already
+ * decided what the client should read. Otherwise the PG error is extracted
+ * from the Drizzle cause chain, falling back to a generic message that
+ * doesn't leak SQL.
  *
  * @param error   - The raw caught error
  * @param context - A human-readable context string (e.g. collection path)
- * @returns An object with `message` (user-friendly) and optional `code` (PG code).
+ * @returns An object with `message` (user-friendly) and optional `code`
+ *          (the `ApiError` code, or the PG SQLSTATE).
  */
 export declare function sanitizeErrorForClient(error: unknown, context: string): {
     message: string;