@rebasepro/types 0.7.0 → 0.8.0

package/dist/types/policy.d.ts

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

package/dist/types/properties.d.ts

@@ -44,6 +44,16 @@ export type FirebaseProperty = Exclude<Property, RelationProperty>;
 export type FirebaseProperties = {
     [key: string]: FirebaseProperty;
 };
+export type MongoProperty = Exclude<Property, RelationProperty>;
+export type MongoProperties = {
+    [key: string]: MongoProperty;
+};
+/**
+ * Union of all engine-specific property maps. Use this at engine-agnostic
+ * boundaries (collection editor, normalization) where the concrete engine is
+ * unknown but the narrowed property constraint must be satisfied.
+ */
+export type EngineProperties = PostgresProperties | FirebaseProperties | MongoProperties;
 /**
  * A helper type to infer the underlying data type from a Property definition.
  * This is the core of the type inference system.
@@ -140,10 +150,6 @@ export interface BaseProperty<CustomProps = unknown> {
      * Rules for validating this property
      */
     validation?: PropertyValidationSchema;
-    /**
-     * This value will be set by default for new entities.
-     */
-    defaultValue?: unknown;
     /**
      * Use this to define dynamic properties that change based on certain conditions
      * or on the entity's values. For example, you can make a field read-only if
@@ -179,15 +185,36 @@ export interface BaseProperty<CustomProps = unknown> {
  * @group Entity properties
  */
 export interface StringUIConfig extends BaseUIConfig {
+    /**
+     * Is this string property long enough so it should be displayed in
+     * a multiple line field. Defaults to false. If set to true,
+     * the number of lines adapts to the content
+     */
     multiline?: boolean;
+    /**
+     * Should this string property be displayed as a markdown field. If true,
+     * the field is rendered as a text editor that supports markdown highlight
+     * syntax. It also includes a preview of the result.
+     */
     markdown?: boolean;
+    /**
+     * Should this string be rendered as a tag instead of just text.
+     */
     previewAsTag?: boolean;
     clearable?: boolean;
+    /**
+     * If the value of this property is a URL, you can set this flag to true
+     * to add a link, or one of the supported media types to render a preview
+     */
     url?: boolean | PreviewType;
 }
 export interface StringProperty extends BaseProperty {
     ui?: StringUIConfig;
     type: "string";
+    /**
+     * Default value for new entities. Must be a string.
+     */
+    defaultValue?: string;
     /**
      * Optional database column type. If not set, it defaults to `varchar` or `uuid` depending on `isId` configuration.
      * Use `text` for strings with unbound length, `char` for fixed-length strings, or `varchar` for variable-length strings with a limit.
@@ -222,18 +249,6 @@ export interface StringProperty extends BaseProperty {
      *
      */
     enum?: EnumValues;
-    /**
-     * Is this string property long enough so it should be displayed in
-     * a multiple line field. Defaults to false. If set to true,
-     * the number of lines adapts to the content
-     */
-    multiline?: boolean;
-    /**
-     * Should this string property be displayed as a markdown field. If true,
-     * the field is rendered as a text editors that supports markdown highlight
-     * syntax. It also includes a preview of the result.
-     */
-    markdown?: boolean;
     /**
      * You can specify a `Storage` configuration. It is used to
      * indicate that this string refers to a path in your storage provider.
@@ -243,31 +258,15 @@ export interface StringProperty extends BaseProperty {
      * This property is used to indicate that the string is a user ID, and
      * it will be rendered as a user picker.
      * Note that the user ID needs to be the one used in your authentication
-     * provider, e.g. Firebase Auth.
+     * provider (e.g. the ID in your `users` table).
      * You can also use a property builder to specify the user path dynamically
      * based on other values of the entity.
      */
     userSelect?: boolean;
-    /**
-     * If the value of this property is a URL, you can set this flag to true
-     * to add a link, or one of the supported media types to render a preview
-     */
-    url?: boolean | PreviewType;
     /**
      * Does this field include an email
      */
     email?: boolean;
-    /**
-     * Should this string be rendered as a tag instead of just text.
-     */
-    previewAsTag?: boolean;
-    /**
-     * You can use this property (a string) to behave as a reference to another
-     * collection. The stored value is the ID of the entity in the
-     * collection, and the `path` prop is used to
-     * define the collection this reference points to.
-     */
-    reference?: ReferenceProperty;
 }
 /**
  * @group Entity properties
@@ -278,6 +277,10 @@ export interface NumberUIConfig extends BaseUIConfig {
 export interface NumberProperty extends BaseProperty {
     ui?: NumberUIConfig;
     type: "number";
+    /**
+     * Default value for new entities. Must be a number.
+     */
+    defaultValue?: number;
     /**
      * Optional database column type. Allows specifying exact database numeric types.
      * If not provided, integer fields (where validation.integer is true or isId is true) default to `integer`, others to `numeric`.
@@ -311,6 +314,10 @@ export interface NumberProperty extends BaseProperty {
 export interface BooleanProperty extends BaseProperty {
     ui?: BaseUIConfig;
     type: "boolean";
+    /**
+     * Default value for new entities. Must be a boolean.
+     */
+    defaultValue?: boolean;
     /**
      * Rules for validating this property
      */
@@ -325,6 +332,10 @@ export interface VectorUIConfig extends BaseUIConfig {
 export interface VectorProperty extends BaseProperty {
     ui?: VectorUIConfig;
     type: "vector";
+    /**
+     * Default value for new entities.
+     */
+    defaultValue?: Vector;
     dimensions: number;
     validation?: PropertyValidationSchema;
 }
@@ -333,17 +344,28 @@ export interface VectorProperty extends BaseProperty {
  */
 export interface BinaryProperty extends BaseProperty {
     type: "binary";
+    /**
+     * Default value for new entities. Must be a base64-encoded string.
+     */
+    defaultValue?: string;
     validation?: PropertyValidationSchema;
 }
 /**
  * @group Entity properties
  */
 export interface DateUIConfig extends BaseUIConfig {
+    /**
+     * Add an icon to clear the value and set it to `null`. Defaults to `false`
+     */
     clearable?: boolean;
 }
 export interface DateProperty extends BaseProperty {
     ui?: DateUIConfig;
     type: "date";
+    /**
+     * Default value for new entities. Must be a Date.
+     */
+    defaultValue?: Date;
     /**
      * Optional database column type. If not set, defaults to `timestamp` with timezone.
      */
@@ -369,10 +391,6 @@ export interface DateProperty extends BaseProperty {
      * `updated_on` fields
      */
     autoValue?: "on_create" | "on_update";
-    /**
-     * Add an icon to clear the value and set it to `null`. Defaults to `false`
-     */
-    clearable?: boolean;
 }
 /**
  * @group Entity properties
@@ -380,6 +398,10 @@ export interface DateProperty extends BaseProperty {
 export interface GeopointProperty extends BaseProperty {
     ui?: BaseUIConfig;
     type: "geopoint";
+    /**
+     * Default value for new entities. Must be a GeoPoint.
+     */
+    defaultValue?: GeoPoint;
     /**
      * Rules for validating this property
      */
@@ -391,9 +413,29 @@ export interface GeopointProperty extends BaseProperty {
 export interface ReferenceUIConfig extends BaseUIConfig {
     previewProperties?: string[];
 }
+/**
+ * A pointer to an entity, stored **as a value** on the row (id + path, and
+ * optionally a `driver`/`databaseId` for cross-datasource pointers).
+ *
+ * This is the native primitive of **document databases** — it maps 1:1 to a
+ * Firestore `DocumentReference`, and is persisted by the MongoDB driver as a
+ * tagged sub-document. It carries no schema-level relationship (no foreign key,
+ * no join, no cascade) and is resolved on demand.
+ *
+ * **Which to use:**
+ * - Firestore / MongoDB collection → use `reference`.
+ * - Postgres collection → use {@link RelationProperty} (`type: "relation"`),
+ *   which models a real foreign key / join with prefetch and cascade.
+ *
+ * @group Entity properties
+ */
 export interface ReferenceProperty extends BaseProperty {
     ui?: ReferenceUIConfig;
     type: "reference";
+    /**
+     * Default value for new entities. Must be an EntityReference.
+     */
+    defaultValue?: EntityReference;
     /**
      * Marks this field as a Primary Key / Unique Identifier.
      * Framework behavior: Auto-maps to `collection.primaryKeys` internally if not explicitly set.
@@ -432,9 +474,29 @@ export interface RelationUIConfig extends BaseUIConfig {
     previewProperties?: string[];
     widget?: "select" | "dialog";
 }
+/**
+ * A schema-level relationship between collections **within a single
+ * datasource** — backed by a foreign key, junction table, or explicit join
+ * path. The resolved value (an `EntityRelation`) can carry a prefetched entity
+ * payload to eliminate N+1 queries, and supports `onUpdate`/`onDelete` cascade.
+ *
+ * This is the native primitive of **relational databases** (Postgres). It is
+ * the SQL counterpart to {@link ReferenceProperty}.
+ *
+ * **Which to use:**
+ * - Postgres collection → use `relation`.
+ * - Firestore / MongoDB collection → use {@link ReferenceProperty}
+ *   (`type: "reference"`), a stored pointer with no join engine.
+ *
+ * @group Entity properties
+ */
 export interface RelationProperty extends BaseProperty {
     ui?: RelationUIConfig;
     type: "relation";
+    /**
+     * Default value for new entities. Must be an EntityRelation or array of EntityRelation.
+     */
+    defaultValue?: EntityRelation | EntityRelation[];
     /**
      * Marks this field as a Primary Key / Unique Identifier.
      * Framework behavior: Auto-maps to `collection.primaryKeys` internally if not explicitly set.
@@ -547,6 +609,10 @@ export interface ArrayUIConfig extends BaseUIConfig {
 export interface ArrayProperty extends BaseProperty {
     ui?: ArrayUIConfig;
     type: "array";
+    /**
+     * Default value for new entities. Must be an array.
+     */
+    defaultValue?: unknown[];
     /**
      * Optional database column type. By default, maps to a native Postgres array
      * (e.g. `text[]`, `integer[]`/`numeric[]`, `boolean[]`) if the element type
@@ -624,6 +690,10 @@ export interface MapUIConfig extends BaseUIConfig {
 export interface MapProperty extends BaseProperty {
     ui?: MapUIConfig;
     type: "map";
+    /**
+     * Default value for new entities. Must be a record/object.
+     */
+    defaultValue?: Record<string, unknown>;
     /**
      * Optional database column type. Defaults to `jsonb`.
      */
@@ -801,6 +871,14 @@ export interface ArrayPropertyValidationSchema extends PropertyValidationSchema
  * @group Entity properties
  */
 export type StorageConfig = {
+    /**
+     * Key referencing a named storage backend from the StorageRegistry.
+     * Must match a `StorageSourceDefinition.key` or a key registered
+     * in `initializeRebaseBackend({ storage: { ... } })`.
+     *
+     * When omitted, the default storage source is used.
+     */
+    storageSource?: string;
     /**
      * File MIME types that can be uploaded to this reference. Don't specify for
      * all.

package/dist/types/property_config.d.ts

@@ -70,5 +70,5 @@ export type PropertyConfig = {
      */
     description?: string;
 };
-export type PropertyConfigId = "text_field" | "multiline" | "markdown" | "url" | "email" | "user_select" | "select" | "multi_select" | "number_input" | "number_select" | "multi_number_select" | "file_upload" | "multi_file_upload" | "group" | "key_value" | "reference" | "reference_as_string" | "multi_references" | "relation" | "switch" | "date_time" | "repeat" | "custom_array" | "block" | "vector_input";
+export type PropertyConfigId = "text_field" | "multiline" | "markdown" | "url" | "email" | "user_select" | "select" | "multi_select" | "number_input" | "number_select" | "multi_number_select" | "file_upload" | "multi_file_upload" | "group" | "key_value" | "reference" | "multi_references" | "relation" | "switch" | "date_time" | "repeat" | "custom_array" | "block" | "vector_input";
 export {};

package/dist/types/storage_source.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Describes a named storage backend — a place files live.
+ *
+ * Declared once and shared front + back: the frontend uses it to decide
+ * transport (HTTP proxy vs direct SDK), the backend uses the same `key`
+ * to resolve a StorageController, and collection properties reference
+ * a definition by its `key` via `StorageConfig.storageSource`.
+ *
+ * This mirrors the {@link DataSourceDefinition} pattern used for databases.
+ *
+ * @group Models
+ */
+/**
+ * The default storage source key, used when a property does not specify
+ * a `storageSource`. Shared by the frontend and backend registries so
+ * both agree on "the default storage backend".
+ * @group Models
+ */
+export declare const DEFAULT_STORAGE_SOURCE_KEY = "(default)";
+/**
+ * How the *frontend* reaches a storage backend.
+ *
+ * - `"server"` — through the Rebase backend REST API (`/api/storage`).
+ *   The backend holds the actual `StorageController` and routes by
+ *   storage-source key. This is the default and covers Local, S3, GCS,
+ *   and any other server-mediated engine.
+ * - `"direct"` — straight from the client to the external backend via
+ *   its own SDK (e.g. Firebase Storage via `@firebase/storage`).
+ *   The Rebase backend is **not** in the upload/download path.
+ *
+ * @group Models
+ */
+export type StorageSourceTransport = "server" | "direct";
+/**
+ * Declarative definition of a storage source — a named place files live.
+ *
+ * Declared once and shared front and back: the frontend uses it to decide
+ * transport (client HTTP proxy vs direct provider SDK), the backend uses
+ * the same `key` to resolve a `StorageController`, and collection
+ * properties reference a definition by its `key` via
+ * `StorageConfig.storageSource`.
+ *
+ * @group Models
+ */
+export interface StorageSourceDefinition {
+    /**
+     * Unique identifier for this storage source. Collection properties
+     * point at it via `StorageConfig.storageSource`.
+     * Defaults to {@link DEFAULT_STORAGE_SOURCE_KEY}.
+     */
+    key: string;
+    /**
+     * The engine backing this storage source (e.g. `"local"`, `"s3"`,
+     * `"gcs"`, `"firebase"`, `"azure"`, or a custom id).
+     */
+    engine: string;
+    /**
+     * How the frontend reaches this storage. Defaults to `"server"`.
+     *
+     * When `"direct"`, the client uses a provider-specific SDK
+     * (e.g. `@firebase/storage`) and the backend does not proxy
+     * upload/download traffic for this source.
+     */
+    transport: StorageSourceTransport;
+    /** Human-readable label for the UI (e.g. "Firebase Storage", "S3 Media"). */
+    label?: string;
+}
+/**
+ * A resolved storage source: the single source of truth that the frontend
+ * router and backend registry both derive from.
+ *
+ * @group Models
+ */
+export interface ResolvedStorageSource {
+    /** Storage source key (routing key, shared front + back). */
+    key: string;
+    /** Engine backing the source. */
+    engine: string;
+    /** Frontend transport. */
+    transport: StorageSourceTransport;
+    /** Human-readable label. */
+    label?: string;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/controllers/client.ts

@@ -4,6 +4,7 @@ import type { EmailService } from "./email";
 import type { StorageSource } from "./storage";
 import type { CronJobStatus, CronJobLogEntry } from "../types/cron";
 import type { ApiKeysAPI } from "../types/api_keys";
+import type { StorageSourceDefinition } from "../types/storage_source";
 
 
 /**
@@ -157,9 +158,30 @@ export interface RebaseClient<DB = unknown> {
     /** Unified Authentication layer */
     auth: AuthClient;
 
-    /** Unified Storage layer */
+    /** Unified Storage layer (default storage source, backward-compatible) */
     storage?: StorageSource;
 
+    /** Registry of all named storage sources for multi-backend support */
+    storageRegistry?: StorageSourceRegistry;
+
+    /**
+     * Build a server-backed {@link StorageSource} for a named storage source.
+     * The returned source forwards `storageId` to the backend so requests are
+     * routed to the matching `StorageController`. Used to lazily wire
+     * `transport: "server"` sources on the frontend.
+     */
+    createStorageSource?(storageId: string): StorageSource;
+
+    /**
+     * Discover the storage sources declared on the backend via
+     * `GET /api/storage/sources`. Server-transport sources are auto-registered
+     * into {@link storageRegistry}; `direct` sources are returned so the app
+     * can supply the live {@link StorageSource} instance. The result is cached
+     * (a failed call is retryable). This makes the backend the single source of
+     * truth for storage-source configuration.
+     */
+    fetchStorageSources?(): Promise<StorageSourceDefinition[]>;
+
     /**
      * Server-side email service.
      * Available when SMTP or a custom `sendEmail` function is configured.
@@ -207,3 +229,41 @@ export interface RebaseClient<DB = unknown> {
     sql?(query: string, options?: { database?: string; role?: string }): Promise<Record<string, unknown>[]>;
 }
 
+/**
+ * Client-side registry for managing multiple storage sources.
+ *
+ * Mirrors the server-side `StorageRegistry` pattern. Allows collection
+ * properties to reference a named storage backend via
+ * `StorageConfig.storageSource`.
+ *
+ * @group Models
+ */
+export interface StorageSourceRegistry {
+    /**
+     * Get a storage source by key.
+     * @param key - Storage source key, or undefined/null for default
+     * @returns The StorageSource, or undefined if not found
+     */
+    get(key: string | undefined | null): StorageSource | undefined;
+
+    /**
+     * Get the default storage source (key = "(default)").
+     * @throws Error if no default storage is registered
+     */
+    getDefault(): StorageSource;
+
+    /**
+     * Get a storage source by key, with fallback to default.
+     * @param key - Storage source key, or undefined/null for default
+     * @returns The StorageSource (falls back to default if key not found)
+     * @throws Error if neither the specified nor default storage exists
+     */
+    getOrDefault(key: string | undefined | null): StorageSource;
+
+    /** Check if a storage source with the given key exists */
+    has(key: string): boolean;
+
+    /** List all registered storage source keys */
+    list(): string[];
+}
+