@rebasepro/types 0.7.0 → 0.8.0

package/src/types/properties.ts

@@ -75,6 +75,20 @@ export type FirebaseProperties = {
     [key: string]: FirebaseProperty;
 };
 
+// MongoDB is a document store: it uses references (stored pointers), not
+// SQL-style relations/joins. Same gating as Firestore.
+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.
@@ -190,10 +204,9 @@ export interface BaseProperty<CustomProps = unknown> {
      */
     validation?: PropertyValidationSchema;
 
-    /**
-     * This value will be set by default for new entities.
-     */
-    defaultValue?: unknown;
+    // NOTE: `defaultValue` is intentionally NOT on BaseProperty.
+    // Each concrete property type (StringProperty, NumberProperty, etc.)
+    // defines its own typed `defaultValue` for compile-time safety.
 
     /**
      * Use this to define dynamic properties that change based on certain conditions
@@ -235,16 +248,37 @@ 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.
@@ -279,18 +313,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.
@@ -301,33 +323,16 @@ 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;
 }
 
 /**
@@ -340,6 +345,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`.
@@ -375,6 +384,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
      */
@@ -391,6 +404,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;
 }
@@ -400,6 +417,10 @@ 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;
 }
 
@@ -407,12 +428,19 @@ export interface BinaryProperty extends BaseProperty {
  * @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.
      */
@@ -438,10 +466,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;
 }
 
 /**
@@ -450,6 +474,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
      */
@@ -463,9 +491,29 @@ 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.
@@ -507,9 +555,29 @@ export interface RelationUIConfig extends BaseUIConfig {
     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.
@@ -649,6 +717,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
@@ -729,6 +801,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`.
      */
@@ -921,6 +997,15 @@ 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/src/types/property_config.tsx

@@ -85,7 +85,6 @@ export type PropertyConfigId =
     "group" |
     "key_value" |
     "reference" |
-    "reference_as_string" |
     "multi_references" |
     "relation" |
     "switch" |

package/src/types/storage_source.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 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/dist/types/backend_hooks.d.ts

@@ -1,109 +0,0 @@
-/**
- * Context passed to every backend hook.
- * Provides information about the request that triggered the hook.
- * @group Backend Hooks
- */
-export interface BackendHookContext {
-    /** The currently authenticated user making the request (if any) */
-    requestUser?: {
-        userId: string;
-        roles: string[];
-    };
-    /** The HTTP method of the request */
-    method: "GET" | "POST" | "PUT" | "DELETE";
-}
-/**
- * Hooks for intercepting collection entity data at the REST API boundary.
- *
- * These run **after** per-collection `EntityCallbacks` (which execute inside
- * the DataDriver) and provide a single cross-cutting interception point for
- * ALL collections flowing through the REST API.
- *
- * Every callback receives the collection `slug` so you can target specific
- * collections or apply logic globally.
- *
- * @group Backend Hooks
- */
-export interface DataHooks {
-    /**
-     * Transform an entity after it's read from the database,
-     * before it's returned to the client.
-     *
-     * Runs for both list (GET /:slug) and single (GET /:slug/:id) fetches.
-     * Return the modified entity, or `null` to filter it out.
-     *
-     * @param slug - The collection slug (e.g. "orders", "products")
-     * @param entity - The flattened entity object (id + values merged)
-     * @param context - Request context (authenticated user, HTTP method)
-     */
-    afterRead?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
-    /**
-     * Transform entity values before they are written to the database.
-     * Runs on POST (create) and PUT (update).
-     *
-     * Return the (possibly modified) values. Throw to abort the save.
-     *
-     * @param slug - The collection slug
-     * @param values - The raw request body values
-     * @param entityId - The entity ID (only present on updates)
-     * @param context - Request context
-     */
-    beforeSave?(slug: string, values: Record<string, unknown>, entityId: string | undefined, context: BackendHookContext): Record<string, unknown> | Promise<Record<string, unknown>>;
-    /**
-     * Called after an entity is successfully saved (created or updated).
-     * Useful for side-effects like syncing to external systems.
-     *
-     * @param slug - The collection slug
-     * @param entity - The saved entity (flattened)
-     * @param context - Request context
-     */
-    afterSave?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): void | Promise<void>;
-    /**
-     * Called before an entity is deleted. Throw to prevent deletion.
-     *
-     * @param slug - The collection slug
-     * @param entityId - The entity ID being deleted
-     * @param context - Request context
-     */
-    beforeDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
-    /**
-     * Called after an entity is successfully deleted.
-     *
-     * @param slug - The collection slug
-     * @param entityId - The deleted entity ID
-     * @param context - Request context
-     */
-    afterDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
-}
-/**
- * Backend-level hooks for intercepting data at the API boundary.
- *
- * These hooks run server-side after database operations complete and before
- * API responses are sent.
- *
- * `data` hooks complement per-collection `EntityCallbacks`. Entity callbacks
- * run inside the DataDriver (close to the DB); data hooks run at the HTTP
- * boundary (close to the client). Use data hooks for cross-cutting concerns
- * like audit logging, response enrichment, or field masking.
- *
- * @example
- * ```typescript
- * const hooks: BackendHooks = {
- *     data: {
- *         afterRead(slug, entity, ctx) {
- *             // Mask PII for non-admin users across all collections
- *             if (!ctx.requestUser?.roles.includes("admin") && entity.email) {
- *                 return { ...entity, email: "***" };
- *             }
- *             return entity;
- *         }
- *     }
- * };
- * ```
- *
- * @group Backend Hooks
- */
-export interface BackendHooks {
-    /** Hooks for intercepting ALL collection entity data via the REST API */
-    data?: DataHooks;
-}

package/dist/types/entity_overrides.d.ts

@@ -1,10 +0,0 @@
-import type { DataDriver } from "../controllers/data_driver";
-import type { StorageSource } from "../controllers/storage";
-export type EntityOverrides = {
-    /**
-     * Internal driver override for this collection.
-     * Used by the CMS engine to route data operations.
-     */
-    driver?: DataDriver;
-    storageSource?: StorageSource;
-};

package/src/types/backend_hooks.ts

@@ -1,114 +0,0 @@
-
-/**
- * Context passed to every backend hook.
- * Provides information about the request that triggered the hook.
- * @group Backend Hooks
- */
-export interface BackendHookContext {
-    /** The currently authenticated user making the request (if any) */
-    requestUser?: { userId: string; roles: string[] };
-    /** The HTTP method of the request */
-    method: "GET" | "POST" | "PUT" | "DELETE";
-}
-
-
-/**
- * Hooks for intercepting collection entity data at the REST API boundary.
- *
- * These run **after** per-collection `EntityCallbacks` (which execute inside
- * the DataDriver) and provide a single cross-cutting interception point for
- * ALL collections flowing through the REST API.
- *
- * Every callback receives the collection `slug` so you can target specific
- * collections or apply logic globally.
- *
- * @group Backend Hooks
- */
-export interface DataHooks {
-    /**
-     * Transform an entity after it's read from the database,
-     * before it's returned to the client.
-     *
-     * Runs for both list (GET /:slug) and single (GET /:slug/:id) fetches.
-     * Return the modified entity, or `null` to filter it out.
-     *
-     * @param slug - The collection slug (e.g. "orders", "products")
-     * @param entity - The flattened entity object (id + values merged)
-     * @param context - Request context (authenticated user, HTTP method)
-     */
-    afterRead?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
-
-    /**
-     * Transform entity values before they are written to the database.
-     * Runs on POST (create) and PUT (update).
-     *
-     * Return the (possibly modified) values. Throw to abort the save.
-     *
-     * @param slug - The collection slug
-     * @param values - The raw request body values
-     * @param entityId - The entity ID (only present on updates)
-     * @param context - Request context
-     */
-    beforeSave?(slug: string, values: Record<string, unknown>, entityId: string | undefined, context: BackendHookContext): Record<string, unknown> | Promise<Record<string, unknown>>;
-
-    /**
-     * Called after an entity is successfully saved (created or updated).
-     * Useful for side-effects like syncing to external systems.
-     *
-     * @param slug - The collection slug
-     * @param entity - The saved entity (flattened)
-     * @param context - Request context
-     */
-    afterSave?(slug: string, entity: Record<string, unknown>, context: BackendHookContext): void | Promise<void>;
-
-    /**
-     * Called before an entity is deleted. Throw to prevent deletion.
-     *
-     * @param slug - The collection slug
-     * @param entityId - The entity ID being deleted
-     * @param context - Request context
-     */
-    beforeDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
-
-    /**
-     * Called after an entity is successfully deleted.
-     *
-     * @param slug - The collection slug
-     * @param entityId - The deleted entity ID
-     * @param context - Request context
-     */
-    afterDelete?(slug: string, entityId: string, context: BackendHookContext): void | Promise<void>;
-}
-
-/**
- * Backend-level hooks for intercepting data at the API boundary.
- *
- * These hooks run server-side after database operations complete and before
- * API responses are sent.
- *
- * `data` hooks complement per-collection `EntityCallbacks`. Entity callbacks
- * run inside the DataDriver (close to the DB); data hooks run at the HTTP
- * boundary (close to the client). Use data hooks for cross-cutting concerns
- * like audit logging, response enrichment, or field masking.
- *
- * @example
- * ```typescript
- * const hooks: BackendHooks = {
- *     data: {
- *         afterRead(slug, entity, ctx) {
- *             // Mask PII for non-admin users across all collections
- *             if (!ctx.requestUser?.roles.includes("admin") && entity.email) {
- *                 return { ...entity, email: "***" };
- *             }
- *             return entity;
- *         }
- *     }
- * };
- * ```
- *
- * @group Backend Hooks
- */
-export interface BackendHooks {
-    /** Hooks for intercepting ALL collection entity data via the REST API */
-    data?: DataHooks;
-}

package/src/types/entity_overrides.tsx

@@ -1,11 +0,0 @@
-import type { DataDriver } from "../controllers/data_driver";
-import type { StorageSource } from "../controllers/storage";
-
-export type EntityOverrides = {
-    /**
-     * Internal driver override for this collection.
-     * Used by the CMS engine to route data operations.
-     */
-    driver?: DataDriver;
-    storageSource?: StorageSource;
-};