@rebasepro/types 0.21.2-canary.g1ea48be → 0.22.0

package/dist/types/backend.d.ts

@@ -1,4 +1,5 @@
 import type { CollectionConfig, FilterValues, WhereFilterOp } from "./collections.js";
+import type { CollectionCallbacks } from "./entity_callbacks.js";
 import type { OrderByTuple } from "./filter-operators.js";
 import type { LogicalCondition } from "../controllers/data.js";
 import type { AuthAdapter } from "./auth_adapter.js";
@@ -88,7 +89,14 @@ export interface ConditionBuilder<T = unknown> {
      */
     buildFilterConditions<M extends Record<string, unknown>>(filter: FilterValues<Extract<keyof M, string>>, collectionPath: string, ...args: unknown[]): T[];
     /**
-     * Build search conditions for text search
+     * Build search conditions for text search.
+     *
+     * At most one condition comes back, already complete: callers OR what they
+     * get, and OR is right across the searchable *fields* but wrong across the
+     * *terms* of the search string — a person typing two words means both, and
+     * the two halves of a name are two different fields. The empty array still
+     * means "nothing here can be searched", which every caller reads as "no
+     * rows".
      */
     buildSearchConditions(searchString: string, properties: Record<string, unknown>, ...args: unknown[]): T[];
     /**
@@ -307,6 +315,17 @@ export interface CollectionRegistryInterface {
      * Get the currently registered global callbacks, if any.
      */
     getGlobalCallbacks(): any | undefined;
+    /**
+     * Take the global callbacks declared on `initializeRebaseBackend({ callbacks })`.
+     *
+     * A driver resolves callbacks from the registry it builds for itself, so
+     * this is how the backend's global ones reach it: the coordinator hands
+     * them over after `initializeDriver` returns. Optional so a registry for a
+     * driver that runs no callbacks still type-checks, but a project that
+     * declares global callbacks over a registry without it is refused at boot
+     * — hooks that never run look exactly like hooks that passed.
+     */
+    setGlobalCallbacks?(callbacks: CollectionCallbacks): void;
 }
 /**
  * Abstract data transformer interface.

package/dist/types/entity_callbacks.d.ts

@@ -1,7 +1,9 @@
-import type { CollectionConfig } from "./collections.js";
+import type { CollectionConfig, FilterValues } from "./collections.js";
+import type { OrderByTuple } from "./filter-operators.js";
 import type { EntityStatus, EntityValues } from "./entities.js";
 import type { User } from "../users/index.js";
 import type { RebaseCallContext } from "../call_context.js";
+import type { LogicalCondition } from "../controllers/data.js";
 /**
  * Lifecycle callbacks for entity CRUD operations.
  *
@@ -25,6 +27,78 @@ export type CollectionCallbacks<M extends Record<string, unknown> = Record<strin
      * @param props
      */
     afterRead?(props: AfterReadProps<M, USER>): Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Callback used **before** a read is compiled, to narrow which rows it asks
+     * for.
+     *
+     * {@link CollectionCallbacks.afterRead} sees rows that have already been
+     * fetched, so nothing in userland could influence *which* rows a read
+     * requests — a tenant scope, a visibility window, a per-role row filter all
+     * had to be either pushed into every call site or written as an RLS policy.
+     * This is the hook for that.
+     *
+     * Return conditions to **add**. They are AND-ed into the query the caller
+     * sent, alongside its own `filter`, its `logical` group, the soft-delete
+     * condition and the relation scope of a nested path.
+     *
+     * ### Additive by construction
+     *
+     * The return type cannot express a removal, a replacement or an `OR` with
+     * the caller's own conditions: it is a filter to AND in, and `AND(q, c)` is
+     * a subset of `q` for every `c`. That is deliberate and it is the reason
+     * the hook is shaped this way rather than as `(query) => query`. A hook
+     * handed the parsed query and asked to return one could drop a condition,
+     * and on an RLS data plane a dropped condition is a widened read — the same
+     * reasoning that makes `UnknownFilterFieldsMode` in
+     * `@rebasepro/server-postgres` default to `"error"` rather than to dropping
+     * what it cannot compile.
+     *
+     * For the same reason the returned filter is compiled with unknown fields
+     * **always** fatal, whatever the process-wide mode is: a scoping condition
+     * on a renamed column must refuse the request, never run without it.
+     *
+     * ### Every read path, no bypass
+     *
+     * It fires on the listing, the single get, the count, the aggregate, the
+     * search, the vector read, the nested-path listing, the realtime refetch
+     * that builds subscription frames, and on the rows loaded for a relation or
+     * an `include` — where it is the **target** collection's hook that applies,
+     * because those are the target's rows. A hook honoured by the listing and
+     * not by the count is a page that says "1 of 4 results".
+     *
+     * Two reads are deliberately not narrowed, and both would be wrong to
+     * narrow:
+     *
+     * - **`checkUniqueField`.** It asks whether a value exists *anywhere* in
+     *   the table. Narrowed, it would answer "unique" for a value a row the
+     *   caller cannot see already holds, and the insert would then fail on the
+     *   constraint instead.
+     * - **A write's own pre-read** is narrowed, not exempt: an update or delete
+     *   addressed at a row this hook excludes answers "not found", which is the
+     *   same answer the read gives.
+     *
+     * ### Postgres only, for now
+     *
+     * Implemented by `@rebasepro/server-postgres`. A collection served by
+     * another engine that declares one is **refused at boot** rather than
+     * served with the hook silently inert — see `assertBeforeQueryIsPostgresOnly`.
+     * That is the same treatment a `search` block gets on a non-Postgres
+     * collection, and for the same reason: a security-shaped hook that does
+     * nothing is worse than one that is absent.
+     *
+     * @example
+     * ```ts
+     * callbacks: {
+     *     beforeQuery: ({ context }) => {
+     *         if (context.user?.roles?.includes("admin")) return;
+     *         return { filter: { owner_id: ["==", context.user?.uid ?? null] } };
+     *     }
+     * }
+     * ```
+     *
+     * @param props
+     */
+    beforeQuery?(props: BeforeQueryProps<M, USER>): Promise<QueryNarrowing<M> | void> | QueryNarrowing<M> | void;
     /**
      * Callback used before saving, you need to return the values that will get
      * saved. If you throw an error in this method the process stops, and an
@@ -83,6 +157,126 @@ export interface AfterReadProps<M extends Record<string, unknown> = Record<strin
      */
     context: RebaseCallContext<USER>;
 }
+/**
+ * Which read a {@link CollectionCallbacks.beforeQuery} hook is narrowing.
+ *
+ * Named rather than inferred because the four are not interchangeable to a
+ * hook that logs, measures or short-circuits: `"count"` and `"aggregate"` serve
+ * a total rather than rows, and `"relation"` is the target collection's own
+ * hook firing over rows reached from a parent.
+ *
+ * @group Models
+ */
+export type ReadOperation = "list" | "get" | "count" | "aggregate" | "relation";
+/**
+ * The parsed read, as a {@link CollectionCallbacks.beforeQuery} hook sees it.
+ *
+ * Read-only throughout, and that is the point rather than a courtesy: a hook
+ * that could edit this object would be able to *widen* the read, which is the
+ * one thing this hook is built not to permit. Mutating it is a compile error;
+ * narrowing is what the return value is for.
+ *
+ * Fields are present exactly when the caller sent them. An absent `filter` is
+ * a query with no filter, not an empty one.
+ *
+ * @group Models
+ */
+export interface ReadQuery<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** The caller's own field filter. */
+    readonly filter?: Readonly<FilterValues<Extract<keyof M, string>>>;
+    /** The caller's `or(...)` / `and(...)` group, if any. */
+    readonly logical?: Readonly<LogicalCondition>;
+    /** The text typed into a search box, if this is a search. */
+    readonly searchString?: string;
+    /** Page size, when the caller asked for one. */
+    readonly limit?: number;
+    /** Offset pagination, when the caller asked for one. */
+    readonly offset?: number;
+    /**
+     * Sort keys, normalized to tuples — one entry per key, in order of
+     * significance, whichever of the several authoring forms the caller used.
+     */
+    readonly orderBy?: readonly Readonly<OrderByTuple>[];
+    /** Column projection, when the caller narrowed it with `fields`. */
+    readonly fields?: readonly string[];
+    /**
+     * The parent this read hangs off, for `operation: "relation"` and for a
+     * nested path like `authors/1/posts`.
+     *
+     * A hook that scopes by tenant usually ignores it. A hook that needs to
+     * know it is looking at *someone's* rows rather than all of them does not.
+     */
+    readonly relatedTo?: {
+        readonly parentSlug: string;
+        readonly parentId?: string | number;
+        readonly relationName: string;
+    };
+}
+/**
+ * What a {@link CollectionCallbacks.beforeQuery} hook returns: conditions to
+ * AND into the read.
+ *
+ * Returning nothing (`undefined`, or no `return` at all) adds nothing and
+ * leaves the compiled SQL byte-identical to what it would have been.
+ *
+ * Both fields are the same declarative language a caller's own query uses, so
+ * a relation path (`author.tenant_id`), a JSON path (`meta->>tier`) and every
+ * `WhereFilterOp` works here too. There is no raw-SQL member, and that is
+ * deliberate: raw SQL could be `OR`-ed against the caller's conditions and so
+ * could widen the read.
+ *
+ * @group Models
+ */
+export interface QueryNarrowing<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * A field filter to AND in.
+     *
+     * Compiled with unknown fields fatal, always: a scope condition that names
+     * a column the table does not have refuses the request rather than running
+     * without it.
+     */
+    filter?: FilterValues<Extract<keyof M, string>>;
+    /**
+     * An `or(...)` / `and(...)` group to AND in, for a scope that is a
+     * disjunction — "mine, or shared with me", say.
+     *
+     * Still additive: the group is AND-ed into the query as a whole, so an
+     * `or` inside it can only ever choose between rows the rest of the query
+     * already admits.
+     */
+    logical?: LogicalCondition;
+}
+/**
+ * Parameters passed to a {@link CollectionCallbacks.beforeQuery} hook.
+ *
+ * @group Models
+ */
+export interface BeforeQueryProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+    /**
+     * Collection being read. For `operation: "relation"` this is the
+     * **target** collection — the one the rows belong to.
+     */
+    collection: CollectionConfig<M>;
+    /**
+     * Full path being read. Might contain unresolved aliases, and for a nested
+     * read it is the target collection's own path rather than the nested one —
+     * the nested parent is on {@link ReadQuery.relatedTo}.
+     */
+    path: string;
+    /** Which read this is. */
+    operation: ReadOperation;
+    /** The parsed read, read-only. */
+    query: ReadQuery<M>;
+    /**
+     * Context of the app status.
+     *
+     * `context.data` is the caller's own plane, so a lookup made here is
+     * itself RLS-scoped — and it is a read issued from inside a read, on the
+     * same connection. Keep it to something cheap and cacheable, or read it
+     * once per request outside the hook.
+     */
+    context: RebaseCallContext<USER>;
+}
 /**
  * Parameters passed to hooks before a entity is saved
  * @group Models

package/dist/types/search.d.ts

@@ -3,10 +3,11 @@
  *
  * ## 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.
+ * Without a `search` block, `.search()` is `ILIKE '%term%'` per whitespace-
+ * separated term, OR-ed across the collection's top-level, non-enum `string`
+ * properties and AND-ed across the terms — so two typed words may be found in
+ * two different columns, as they are here. Declaring this block is the only way
+ * to get anything more than that.
  *
  * 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
@@ -66,6 +67,53 @@ export interface SearchConfig {
      * failure this whole block exists to prevent.
      */
     fields: readonly (string | SearchField)[];
+    /**
+     * How a search string is matched against the indexed fields.
+     *
+     * - `"fts"` (default) — one `@@ websearch_to_tsquery` against the generated
+     *   `tsvector`. Stems, drops stopwords, reaches inside JSONB and arrays,
+     *   uses the GIN index, and ranks. It matches **whole lexemes**, so `seb`
+     *   does not find `sebastian` and `audit` does not find `Auditor`.
+     * - `"hybrid"` — that predicate `OR` a substring match over the same
+     *   declared fields, with accents folded on both sides. So one collection
+     *   gets accent folding *and* substring/prefix matching, which is what a
+     *   search box is: measured on five rows in `search-mode-matrix.test.ts`,
+     *   `munoz` finds `Sebastian Munoz`, `seb` finds both Sebastians, `audit`
+     *   finds the `ISO 14001 Lead Auditor`, and `iso 14001` does **not** drag
+     *   in the `ISO 9001` row the way a loose `fuzzy` threshold does.
+     *
+     * ### Why this is a mode rather than the default
+     *
+     * The substring half cannot use the GIN index — a leading `%` never can —
+     * so it is a scan over the declared fields' text, evaluated per row. The
+     * `@@` half still runs first and still uses the index; what the mode costs
+     * is the rows the index rejected, which the planner has to look at anyway
+     * to apply the `OR`. On a large table that is the difference between an
+     * index scan and a sequential one, and that is the author's call to make
+     * rather than this default's.
+     *
+     * ### Changing this on a live collection
+     *
+     * Safe, and deliberately so. `mode` is **query-side only**: it changes no
+     * generated column, no generation expression and no index, so it does not
+     * trip the boot-time refusal a changed `search` block otherwise gets
+     * (`searchDriftMessage` — rebuilding a STORED generated column rewrites the
+     * table under an ACCESS EXCLUSIVE lock). Turning `"hybrid"` on for a
+     * collection whose column already exists takes a deploy and nothing else.
+     *
+     * The accent folding on the substring half is likewise query-side and
+     * unconditional under `"hybrid"` — it does **not** require
+     * {@link SearchConfig.unaccent}, which is what makes the switch free. What
+     * `unaccent` still buys is folding on the `@@` half, where the lexemes are
+     * stored, and that one *is* a column rebuild.
+     *
+     * It does add the `unaccent` extension and one IMMUTABLE helper function to
+     * the database if they are not there already. Both are `IF NOT EXISTS` /
+     * `CREATE OR REPLACE`, so both are additive and idempotent.
+     *
+     * @default "fts"
+     */
+    mode?: SearchMode;
     /**
      * The Postgres text search configuration, which decides stemming and
      * stopwords. `"spanish"` stems `auditores` to `auditor` and drops `de`;
@@ -154,6 +202,12 @@ export interface SearchField {
      */
     weight?: SearchWeight;
 }
+/**
+ * How {@link SearchConfig.mode} matches a search string.
+ *
+ * @group Search
+ */
+export type SearchMode = "fts" | "hybrid";
 /**
  * Postgres tsvector weight classes, strongest to weakest.
  *
@@ -162,6 +216,8 @@ export interface SearchField {
 export type SearchWeight = "A" | "B" | "C" | "D";
 /** The column name used when {@link SearchConfig.column} is not given. */
 export declare const DEFAULT_SEARCH_COLUMN = "search_vector";
+/** The matching strategy used when {@link SearchConfig.mode} is not given. */
+export declare const DEFAULT_SEARCH_MODE: SearchMode;
 /** The text search configuration used when {@link SearchConfig.language} is not given. */
 export declare const DEFAULT_SEARCH_LANGUAGE = "simple";
 /** The weight a field carries when it does not name one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/types",
-  "version": "0.21.2-canary.g1ea48be",
+  "version": "0.22.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "keywords": [
     "rebase",