@rebasepro/types 0.7.0 → 0.8.0

package/src/types/entity_callbacks.ts

@@ -4,15 +4,25 @@ import type { User } from "../users";
 import type { RebaseCallContext } from "../rebase_context";
 
 /**
- * This interface defines all the callbacks that can be used when an entity
- * is being created, updated or deleted.
- * Useful for adding your own logic or blocking the execution of the operation.
+ * Lifecycle callbacks for entity CRUD operations.
+ *
+ * Register per-collection on the collection's `callbacks` field, or globally
+ * via `initBackend({ callbacks })`. Fires on **every** data path — REST API,
+ * WebSocket / realtime subscriptions, and server-side `rebase.data`.
+ *
+ * When both global and per-collection callbacks are registered, execution
+ * order is: **global → collection → property callbacks**.
+ *
  * @group Models
  */
 export type EntityCallbacks<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
 
     /**
-     * Callback used after fetching data
+     * Callback used after fetching data.
+     *
+     * Fires on every read path. Use this for security-critical redaction
+     * (PII masking, row filtering) — no read path bypasses it.
+     *
      * @param props
      */
     afterRead?(props: EntityAfterReadProps<M, USER>)
@@ -24,13 +34,15 @@ export type EntityCallbacks<M extends Record<string, unknown> = Record<string, u
      * saved. If you throw an error in this method the process stops, and an
      * error snackbar gets displayed.
      * This runs after schema validation.
+     *
      * @param props
      */
     beforeSave?(props: EntityBeforeSaveProps<M, USER>)
         : Promise<Partial<EntityValues<M>>> | Partial<EntityValues<M>>;
 
     /**
-     * Callback used when save is successful
+     * Callback used when save is successful.
+     *
      * @param props
      */
     afterSave?(props: EntityAfterSaveProps<M, USER>)
@@ -57,7 +69,7 @@ export type EntityCallbacks<M extends Record<string, unknown> = Record<string, u
      *
      * @param props
      */
-    afterDelete?(props: EntityAfterDeleteProps<M, USER>): void;
+    afterDelete?(props: EntityAfterDeleteProps<M, USER>): Promise<void> | void;
 
 }
 
@@ -214,4 +226,3 @@ export interface EntityAfterDeleteProps<M extends Record<string, unknown> = Reco
      */
     context: RebaseCallContext<USER>;
 }
-

package/src/types/filter-operators.ts

@@ -0,0 +1,167 @@
+/**
+ * Canonical filter operators and REST wire-format mappings.
+ *
+ * `WhereFilterOp` is THE operator type used at every layer — from React
+ * components through the SDK, server, and down to the database driver.
+ *
+ * PostgREST short-codes (`eq`, `gt`, `cs`, …) exist **only** at the
+ * HTTP wire boundary, handled by `serializeFilter` / `deserializeFilter`
+ * in `@rebasepro/common`.
+ *
+ * ┌──────────────────┬───────────────┬──────────────────────────┐
+ * │ Canonical        │ REST short    │ Meaning                  │
+ * ├──────────────────┼───────────────┼──────────────────────────┤
+ * │ "=="             │ "eq"          │ Equal                    │
+ * │ "!="             │ "neq"         │ Not equal                │
+ * │ ">"              │ "gt"          │ Greater than             │
+ * │ ">="             │ "gte"         │ Greater than or equal    │
+ * │ "<"              │ "lt"          │ Less than                │
+ * │ "<="             │ "lte"         │ Less than or equal       │
+ * │ "in"             │ "in"          │ Value in list            │
+ * │ "not-in"         │ "nin"         │ Value not in list        │
+ * │ "array-contains" │ "cs"          │ Array contains element   │
+ * │ "array-contains-any" │ "csa"     │ Array contains any of    │
+ * └──────────────────┴───────────────┴──────────────────────────┘
+ *
+ * @module
+ */
+
+/**
+ * Canonical filter operators supported across all database backends.
+ * Each DB driver translates these to its native query format.
+ *
+ * @group Models
+ */
+export type WhereFilterOp =
+    | "<"
+    | "<="
+    | "=="
+    | "!="
+    | ">="
+    | ">"
+    | "array-contains"
+    | "in"
+    | "not-in"
+    | "array-contains-any";
+
+/**
+ * Used to define filters applied in collections.
+ *
+ * A single condition is a tuple `[operator, value]`.
+ * Multiple conditions on the same field use an array of tuples.
+ *
+ * @example
+ * // Single condition per field
+ * { status: ["==", "active"], price: [">=", 9.99] }
+ *
+ * // Multiple conditions on one field
+ * { age: [[">=", 18], ["<", 65]] }
+ *
+ * // Array operators
+ * { role: ["in", ["admin", "editor"]] }
+ * { tags: ["array-contains", "featured"] }
+ *
+ * @group Models
+ */
+export type FilterValues<Key extends string> =
+    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][]>>;
+
+/**
+ * Relaxed filter type that also accepts pre-serialized PostgREST strings.
+ * **Internal only** — used at the wire-format boundary
+ * (`serializeFilter` / `deserializeFilter` in `@rebasepro/common`).
+ *
+ * Application code, UI components, and SDK consumers should use
+ * {@link FilterValues} instead.
+ *
+ * @internal
+ */
+export type WireFilterValues<Key extends string> =
+    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][] | string>>;
+
+/**
+ * A pre-defined filter preset for quick access in the collection toolbar.
+ * Users can select a preset to instantly apply a set of filters and
+ * optionally a sort order.
+ *
+ * @group Models
+ */
+export interface FilterPreset<Key extends string = string> {
+    /**
+     * Display label shown in the preset menu.
+     * If omitted, a summary is auto-generated from the filter keys.
+     */
+    label?: string;
+
+    /**
+     * The filter values to apply when this preset is selected.
+     */
+    filterValues: FilterValues<Key>;
+
+    /**
+     * Optional sort override to apply alongside the filter values.
+     */
+    sort?: [Key, "asc" | "desc"];
+}
+
+/**
+ * PostgREST short-code operators. Wire format only — these never appear
+ * in application code. Used by `serializeFilter`/`deserializeFilter`
+ * in `@rebasepro/common`.
+ */
+export type RestFilterOp =
+    | "eq" | "neq"
+    | "gt" | "gte"
+    | "lt" | "lte"
+    | "in" | "nin"
+    | "cs" | "csa";
+
+/** Maps canonical operators to their REST short-code equivalents. */
+export const CANONICAL_TO_REST: Readonly<Record<WhereFilterOp, RestFilterOp>> = {
+    "==": "eq",
+    "!=": "neq",
+    ">": "gt",
+    ">=": "gte",
+    "<": "lt",
+    "<=": "lte",
+    "in": "in",
+    "not-in": "nin",
+    "array-contains": "cs",
+    "array-contains-any": "csa"
+};
+
+/** Maps REST short-code operators to their canonical equivalents. */
+export const REST_TO_CANONICAL: Readonly<Record<RestFilterOp, WhereFilterOp>> = {
+    "eq": "==",
+    "neq": "!=",
+    "gt": ">",
+    "gte": ">=",
+    "lt": "<",
+    "lte": "<=",
+    "in": "in",
+    "nin": "not-in",
+    "cs": "array-contains",
+    "csa": "array-contains-any"
+};
+
+/** All canonical operator strings for runtime validation. */
+const CANONICAL_OPS: ReadonlySet<string> = new Set<WhereFilterOp>([
+    "<", "<=", "==", "!=", ">=", ">",
+    "in", "not-in",
+    "array-contains", "array-contains-any"
+]);
+
+/**
+ * Resolve any operator string (canonical or REST short-code) to its
+ * canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.
+ *
+ * @example
+ * toCanonicalOp("==")   // "=="
+ * toCanonicalOp("eq")   // "=="
+ * toCanonicalOp("cs")   // "array-contains"
+ * toCanonicalOp("xyz")  // undefined
+ */
+export function toCanonicalOp(op: string): WhereFilterOp | undefined {
+    if (CANONICAL_OPS.has(op)) return op as WhereFilterOp;
+    return (REST_TO_CANONICAL as Record<string, WhereFilterOp | undefined>)[op];
+}

package/src/types/index.ts

@@ -1,15 +1,16 @@
 export * from "./entities";
+export * from "./filter-operators";
 export * from "./chips";
 
 export * from "./properties";
 export * from "./collections";
 export * from "./relations";
+export * from "./policy";
 
 export * from "./locales";
 export * from "./entity_link_builder";
 export * from "./user_management_delegate";
 export * from "./entity_callbacks";
-export * from "./entity_overrides";
 export * from "./export_import";
 export * from "./modify_collections";
 export * from "./formex";
@@ -23,8 +24,8 @@ export * from "./entity_actions";
 export * from "./property_config";
 export * from "./entity_views";
 export * from "./data_source";
+export * from "./storage_source";
 export * from "./cron";
-export * from "./backend_hooks";
 export * from "./component_ref";
 export * from "./auth_adapter";
 export * from "./database_adapter";

package/src/types/policy.ts

@@ -0,0 +1,173 @@
+/**
+ * Structured, engine-agnostic policy expressions.
+ *
+ * A {@link PolicyExpression} is the single source of truth for a row-level
+ * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL
+ * (authoritative enforcement) and independently evaluated in JavaScript (to
+ * drive the admin UI, and — in future — to enforce on engines without native
+ * RLS such as MongoDB). Because both the SQL and the JS decision derive from
+ * the *same* expression, the UI matches database enforcement by construction —
+ * no drift between two hand-written implementations.
+ *
+ * The only escape hatch that cannot be evaluated client-side is the
+ * {@link RawPolicyExpression} node (`{ kind: "raw" }`): it preserves full
+ * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the
+ * JavaScript evaluator (never silently allowed) and reflected exactly in the UI
+ * via server-computed capability flags.
+ *
+ * @group Models
+ */
+export type PolicyExpression =
+    | TruePolicyExpression
+    | FalsePolicyExpression
+    | AndPolicyExpression
+    | OrPolicyExpression
+    | NotPolicyExpression
+    | ComparePolicyExpression
+    | RolesOverlapPolicyExpression
+    | RolesContainPolicyExpression
+    | AuthenticatedPolicyExpression
+    | RawPolicyExpression;
+
+/** Always allows. Compiles to `true`. @group Models */
+export interface TruePolicyExpression {
+    kind: "true";
+}
+
+/** Always denies. Compiles to `false`. @group Models */
+export interface FalsePolicyExpression {
+    kind: "false";
+}
+
+/** Logical AND — every operand must pass. @group Models */
+export interface AndPolicyExpression {
+    kind: "and";
+    operands: PolicyExpression[];
+}
+
+/** Logical OR — at least one operand must pass. @group Models */
+export interface OrPolicyExpression {
+    kind: "or";
+    operands: PolicyExpression[];
+}
+
+/** Logical negation. @group Models */
+export interface NotPolicyExpression {
+    kind: "not";
+    operand: PolicyExpression;
+}
+
+/** 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()`.
+ * @group Models
+ */
+export interface ComparePolicyExpression {
+    kind: "compare";
+    op: PolicyCompareOperator;
+    left: PolicyOperand;
+    right: PolicyOperand;
+}
+
+/**
+ * True when the user holds *at least one* of the given application roles.
+ * Compiles to `string_to_array(auth.roles(), ',') && ARRAY[...]`.
+ * @group Models
+ */
+export interface RolesOverlapPolicyExpression {
+    kind: "rolesOverlap";
+    roles: string[];
+}
+
+/**
+ * True when the user holds *all* of the given application roles.
+ * Compiles to `string_to_array(auth.roles(), ',') @> ARRAY[...]`.
+ * @group Models
+ */
+export interface RolesContainPolicyExpression {
+    kind: "rolesContain";
+    roles: string[];
+}
+
+/**
+ * True when there is an authenticated user (`auth.uid() IS NOT NULL`).
+ * @group Models
+ */
+export interface AuthenticatedPolicyExpression {
+    kind: "authenticated";
+}
+
+/**
+ * A raw PostgreSQL boolean expression — the full-power escape hatch.
+ *
+ * Columns can be referenced as `{column_name}`. This is Postgres-only and
+ * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary
+ * SQL, so it treats this node as *unknown* rather than guessing.
+ * @group Models
+ */
+export interface RawPolicyExpression {
+    kind: "raw";
+    sql: string;
+}
+
+/**
+ * An operand referenced by a {@link ComparePolicyExpression}.
+ * @group Models
+ */
+export type PolicyOperand =
+    | FieldPolicyOperand
+    | LiteralPolicyOperand
+    | AuthUidPolicyOperand
+    | AuthRolesPolicyOperand;
+
+/** A column value on the row being evaluated. @group Models */
+export interface FieldPolicyOperand {
+    kind: "field";
+    /** The property/column name (resolved to its DB column when compiled). */
+    name: string;
+}
+
+/** A constant value. @group Models */
+export interface LiteralPolicyOperand {
+    kind: "literal";
+    value: string | number | boolean | null;
+}
+
+/** The current user's id — compiles to `auth.uid()`. @group Models */
+export interface AuthUidPolicyOperand {
+    kind: "authUid";
+}
+
+/**
+ * The current user's roles as an array — compiles to
+ * `string_to_array(auth.roles(), ',')`.
+ * @group Models
+ */
+export interface AuthRolesPolicyOperand {
+    kind: "authRoles";
+}
+
+// ── Constructor helpers ──────────────────────────────────────────────
+// Small, dependency-free builders so callers (and the desugaring in
+// `@rebasepro/common`) can assemble expressions without object-literal noise.
+
+/** @group Models */
+export const policy = {
+    true: (): TruePolicyExpression => ({ kind: "true" }),
+    false: (): FalsePolicyExpression => ({ kind: "false" }),
+    and: (...operands: PolicyExpression[]): AndPolicyExpression => ({ kind: "and", operands }),
+    or: (...operands: PolicyExpression[]): OrPolicyExpression => ({ kind: "or", operands }),
+    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: "not", operand }),
+    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>
+        ({ kind: "compare", op, left, right }),
+    rolesOverlap: (roles: string[]): RolesOverlapPolicyExpression => ({ kind: "rolesOverlap", roles }),
+    rolesContain: (roles: string[]): RolesContainPolicyExpression => ({ kind: "rolesContain", roles }),
+    authenticated: (): AuthenticatedPolicyExpression => ({ kind: "authenticated" }),
+    raw: (sql: string): RawPolicyExpression => ({ kind: "raw", sql }),
+    field: (name: string): FieldPolicyOperand => ({ kind: "field", name }),
+    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: "literal", value }),
+    authUid: (): AuthUidPolicyOperand => ({ kind: "authUid" }),
+    authRoles: (): AuthRolesPolicyOperand => ({ kind: "authRoles" })
+};