@rebasepro/types 0.7.0 → 0.9.0

package/dist/types/filter-operators.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 declare const CANONICAL_TO_REST: Readonly<Record<WhereFilterOp, RestFilterOp>>;
+/** Maps REST short-code operators to their canonical equivalents. */
+export declare const REST_TO_CANONICAL: Readonly<Record<RestFilterOp, WhereFilterOp>>;
+/**
+ * Operators that test for null/not-null and therefore ignore their value.
+ * Codecs normalize the value of these conditions to `null`.
+ */
+export declare const NULL_OPS: ReadonlySet<WhereFilterOp>;
+/**
+ * Every canonical operator, in a stable order. Useful for engine capability
+ * declarations ({@link DataSourceCapabilities.filterOperators}) and for
+ * building operator subsets.
+ * @group Models
+ */
+export declare const ALL_WHERE_FILTER_OPS: readonly WhereFilterOp[];
+/**
+ * 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 declare function toCanonicalOp(op: string): WhereFilterOp | undefined;

package/dist/types/index.d.ts

@@ -1,13 +1,14 @@
 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";
@@ -21,8 +22,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/dist/types/modify_collections.d.ts

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

package/dist/types/plugins.d.ts

@@ -1,5 +1,5 @@
 import React, { PropsWithChildren } from "react";
-import type { EntityCollection } from "./collections";
+import type { CollectionConfig } from "./collections";
 import type { EntityStatus } from "./entities";
 import type { InferPropertyType, Property } from "./properties";
 import type { FormContext } from "./entity_views";
@@ -136,17 +136,17 @@ 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.
      */
@@ -154,7 +154,7 @@ export interface PluginHooks {
         fullPath: string;
         parentCollectionSlugs: string[];
         parentEntityIds: string[];
-        collection: EntityCollection;
+        collection: CollectionConfig;
         newPropertiesOrder: string[];
     }) => void;
     /**
@@ -164,7 +164,7 @@ export interface PluginHooks {
         fullPath: string;
         parentCollectionSlugs: string[];
         parentEntityIds: string[];
-        collection: EntityCollection;
+        collection: CollectionConfig;
         kanbanColumnProperty: string;
         newColumnsOrder: string[];
     }) => void;
@@ -226,7 +226,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>;
@@ -235,7 +235,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[];
@@ -251,7 +251,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/dist/types/policy.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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";
+}
+/** @group Models */
+export declare const policy: {
+    true: () => TruePolicyExpression;
+    false: () => FalsePolicyExpression;
+    and: (...operands: readonly PolicyExpression[]) => AndPolicyExpression;
+    or: (...operands: readonly PolicyExpression[]) => OrPolicyExpression;
+    not: (operand: PolicyExpression) => NotPolicyExpression;
+    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand) => ComparePolicyExpression;
+    rolesOverlap: (roles: readonly string[]) => RolesOverlapPolicyExpression;
+    rolesContain: (roles: readonly string[]) => RolesContainPolicyExpression;
+    authenticated: () => AuthenticatedPolicyExpression;
+    existsIn: (args: {
+        collection: string;
+        where: PolicyExpression;
+    }) => ExistsInPolicyExpression;
+    raw: (sql: string) => RawPolicyExpression;
+    field: (name: string) => FieldPolicyOperand;
+    outerField: (name: string) => OuterFieldPolicyOperand;
+    literal: (value: string | number | boolean | null) => LiteralPolicyOperand;
+    authUid: () => AuthUidPolicyOperand;
+    authRoles: () => AuthRolesPolicyOperand;
+};