@rebasepro/types 0.7.0 → 0.9.0

package/src/types/filter-operators.ts

@@ -0,0 +1,240 @@
+/**
+ * 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        │
+ * │ "like"               │ "like"        │ SQL LIKE (case-sensitive)    │
+ * │ "ilike"              │ "ilike"       │ SQL ILIKE (case-insensitive) │
+ * │ "not-like"           │ "nlike"       │ NOT LIKE (case-sensitive)    │
+ * │ "not-ilike"          │ "nilike"      │ NOT ILIKE (case-insensitive) │
+ * │ "is-null"            │ "isnull"      │ Field IS NULL                │
+ * │ "is-not-null"        │ "notnull"     │ Field IS NOT NULL            │
+ * └──────────────────────┴───────────────┴──────────────────────────────┘
+ *
+ * Pattern matching (`like`/`ilike`) uses SQL wildcard syntax: `%` matches any
+ * sequence of characters, `_` matches a single character. On MongoDB these are
+ * translated to anchored regular expressions; Firestore has no native pattern
+ * matching and rejects these operators (use `searchString` instead).
+ *
+ * @module
+ */
+
+/**
+ * Canonical sort representation: `[fieldName, direction]`.
+ *
+ * Used in `FindParams.orderBy`, `collection.sort`, and `FilterPreset.sort`.
+ * The colon-string form (`"field:direction"`) exists only at the HTTP wire
+ * boundary, handled by `serializeOrderBy` / `deserializeOrderBy` in
+ * `@rebasepro/common`.
+ *
+ * Design note: the natural extension for multi-column sort is
+ * `OrderByTuple[]` — not implemented yet (server consumes only the first).
+ *
+ * @group Models
+ */
+export type OrderByTuple<Key extends string = string> = [Key, "asc" | "desc"];
+
+/**
+ * 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"
+    | "like"
+    | "ilike"
+    | "not-like"
+    | "not-ilike"
+    | "is-null"
+    | "is-not-null";
+
+/**
+ * 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"] }
+ *
+ * // Pattern matching (SQL wildcards: % and _)
+ * { name: ["ilike", "%john%"] }
+ * { slug: ["like", "post-%"] }
+ *
+ * // Null checks (the value is ignored; `null` is conventional)
+ * { deleted_at: ["is-null", null] }
+ * { published_at: ["is-not-null", null] }
+ *
+ * @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?: OrderByTuple<Key>;
+}
+
+/**
+ * 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"
+    | "like" | "ilike"
+    | "nlike" | "nilike"
+    | "isnull" | "notnull";
+
+/** 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",
+    "like": "like",
+    "ilike": "ilike",
+    "not-like": "nlike",
+    "not-ilike": "nilike",
+    "is-null": "isnull",
+    "is-not-null": "notnull"
+};
+
+/** 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",
+    "like": "like",
+    "ilike": "ilike",
+    "nlike": "not-like",
+    "nilike": "not-ilike",
+    "isnull": "is-null",
+    "notnull": "is-not-null"
+};
+
+/**
+ * Operators that test for null/not-null and therefore ignore their value.
+ * Codecs normalize the value of these conditions to `null`.
+ */
+export const NULL_OPS: ReadonlySet<WhereFilterOp> = new Set<WhereFilterOp>([
+    "is-null", "is-not-null"
+]);
+
+/**
+ * Every canonical operator, in a stable order. Useful for engine capability
+ * declarations ({@link DataSourceCapabilities.filterOperators}) and for
+ * building operator subsets.
+ * @group Models
+ */
+export const ALL_WHERE_FILTER_OPS: readonly WhereFilterOp[] = [
+    "<", "<=", "==", "!=", ">=", ">",
+    "in", "not-in",
+    "array-contains", "array-contains-any",
+    "like", "ilike", "not-like", "not-ilike",
+    "is-null", "is-not-null"
+];
+
+/** All canonical operator strings for runtime validation. */
+const CANONICAL_OPS: ReadonlySet<string> = new Set<WhereFilterOp>(ALL_WHERE_FILTER_OPS);
+
+/**
+ * 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/modify_collections.tsx

@@ -1,6 +1,6 @@
-import { EntityCollection } from "./collections";
+import { CollectionConfig } from "./collections";
 
 export type ModifyCollectionProps = {
-    collection: EntityCollection,
+    collection: CollectionConfig,
     parentPaths: string[],
 };

package/src/types/plugins.tsx

@@ -1,6 +1,6 @@
 import React, { PropsWithChildren } from "react";
 
-import type { EntityCollection, CollectionActionsProps, EntityTableController, SelectionController } from "./collections";
+import type { CollectionConfig, CollectionActionsProps, EntityTableController, SelectionController } from "./collections";
 import type { EntityStatus } from "./entities";
 import type { InferPropertyType, Property } from "./properties";
 import type { FormContext } from "./entity_views";
@@ -181,19 +181,19 @@ export interface PluginHooks {
     /**
      * Modify a single collection before it is rendered (synchronous).
      */
-    modifyCollection?: (collection: EntityCollection) => EntityCollection;
+    modifyCollection?: (collection: CollectionConfig) => CollectionConfig;
 
     /**
      * Async version of modifyCollection — supports fetching remote config.
      * Runs during navigation resolution. If provided alongside `modifyCollection`,
      * the sync version runs first, then the async version.
      */
-    modifyCollectionAsync?: (collection: EntityCollection) => Promise<EntityCollection>;
+    modifyCollectionAsync?: (collection: CollectionConfig) => Promise<CollectionConfig>;
 
     /**
      * Modify, add or remove collections.
      */
-    injectCollections?: (collections: EntityCollection[]) => EntityCollection[];
+    injectCollections?: (collections: CollectionConfig[]) => CollectionConfig[];
 
     /**
      * Callback called when columns are reordered via drag and drop.
@@ -202,7 +202,7 @@ export interface PluginHooks {
         fullPath: string;
         parentCollectionSlugs: string[];
         parentEntityIds: string[];
-        collection: EntityCollection;
+        collection: CollectionConfig;
         newPropertiesOrder: string[];
     }) => void;
 
@@ -213,7 +213,7 @@ export interface PluginHooks {
         fullPath: string;
         parentCollectionSlugs: string[];
         parentEntityIds: string[];
-        collection: EntityCollection;
+        collection: CollectionConfig;
         kanbanColumnProperty: string;
         newColumnsOrder: string[];
     }) => void;
@@ -291,7 +291,7 @@ export interface FieldBuilderConfig {
  * Props passed to home page collection card action components.
  * @group Models
  */
-export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
+export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User, EC extends CollectionConfig<M> = CollectionConfig<M>> {
     slug: string;
     collection: EC;
     context: RebaseContext<USER>;
@@ -301,7 +301,7 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
  * Props passed to form action components in entity edit/form views.
  * @group Models
  */
-export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
+export interface PluginFormActionProps<USER extends User = User, EC extends CollectionConfig = CollectionConfig> {
     entityId?: string | number;
     path: string;
     parentCollectionSlugs: string[];
@@ -318,7 +318,7 @@ export interface PluginFormActionProps<USER extends User = User, EC extends Enti
  * Parameters passed to the field builder wrap function.
  * @group Models
  */
-export type PluginFieldBuilderParams<M extends Record<string, unknown> = Record<string, unknown>, EC extends EntityCollection<M> = EntityCollection<M>> = {
+export type PluginFieldBuilderParams<M extends Record<string, unknown> = Record<string, unknown>, EC extends CollectionConfig<M> = CollectionConfig<M>> = {
     fieldConfigId: string;
     propertyKey: string;
     property: Property;

package/src/types/policy.ts

@@ -0,0 +1,229 @@
+/**
+ * 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
+    | ExistsInPolicyExpression
+    | 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: readonly PolicyExpression[];
+}
+
+/** Logical OR — at least one operand must pass. @group Models */
+export interface OrPolicyExpression {
+    kind: "or";
+    operands: readonly 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: readonly 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: readonly string[];
+}
+
+/**
+ * True when there is an authenticated user (`auth.uid() IS NOT NULL`).
+ * @group Models
+ */
+export interface AuthenticatedPolicyExpression {
+    kind: "authenticated";
+}
+
+/**
+ * Membership / relational access: true when at least one row exists in another
+ * collection (a join/membership table) matching `where`. This is what lets you
+ * scope reads to "rows whose team the caller belongs to" without an N+1
+ * per-row lookup — it compiles to a single correlated `EXISTS` subquery.
+ *
+ * Inside `where`, {@link FieldPolicyOperand} (`policy.field`) references a column
+ * of the joined collection, while {@link OuterFieldPolicyOperand}
+ * (`policy.outerField`) references a column of the row being checked (the outer
+ * table under RLS). Combine with {@link AuthUidPolicyOperand} to correlate to
+ * the caller.
+ *
+ * @example
+ * ```ts
+ * // documents visible only to members of the document's team:
+ * policy.existsIn({
+ *   collection: "team_members",
+ *   where: policy.and(
+ *     policy.compare(policy.field("team_id"), "eq", policy.outerField("team_id")),
+ *     policy.compare(policy.field("user_id"), "eq", policy.authUid()),
+ *   ),
+ * })
+ * // → EXISTS (SELECT 1 FROM team_members _ex0
+ * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = auth.uid())
+ * ```
+ *
+ * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript
+ * evaluator treats it as *unknown* (it cannot run a subquery client-side), so
+ * enforcement is always the database's.
+ * @group Models
+ */
+export interface ExistsInPolicyExpression {
+    kind: "existsIn";
+    /** Slug of the collection to search (the join / membership table). */
+    collection: string;
+    /** Condition evaluated against the joined collection's rows. */
+    where: PolicyExpression;
+}
+
+/**
+ * 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
+    | OuterFieldPolicyOperand
+    | 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 column value on the *outer* row when used inside {@link ExistsInPolicyExpression}
+ * — i.e. the row the RLS policy is being evaluated for, referenced from within the
+ * subquery. Outside an `existsIn` it is equivalent to {@link FieldPolicyOperand}.
+ * @group Models
+ */
+export interface OuterFieldPolicyOperand {
+    kind: "outerField";
+    /** The property/column name on the outer collection. */
+    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: readonly PolicyExpression[]): AndPolicyExpression => ({ kind: "and", operands: operands as PolicyExpression[] }),
+    or: (...operands: readonly PolicyExpression[]): OrPolicyExpression => ({ kind: "or", operands: operands as PolicyExpression[] }),
+    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: "not", operand }),
+    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>
+        ({ kind: "compare", op, left, right }),
+    rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: "rolesOverlap", roles: roles as string[] }),
+    rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: "rolesContain", roles: roles as string[] }),
+    authenticated: (): AuthenticatedPolicyExpression => ({ kind: "authenticated" }),
+    existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>
+        ({ kind: "existsIn", collection: args.collection, where: args.where }),
+    raw: (sql: string): RawPolicyExpression => ({ kind: "raw", sql }),
+    field: (name: string): FieldPolicyOperand => ({ kind: "field", name }),
+    outerField: (name: string): OuterFieldPolicyOperand => ({ kind: "outerField", name }),
+    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: "literal", value }),
+    authUid: (): AuthUidPolicyOperand => ({ kind: "authUid" }),
+    authRoles: (): AuthRolesPolicyOperand => ({ kind: "authRoles" })
+};