@rebasepro/types 0.0.1-canary.0

package/src/types/entities.ts

@@ -0,0 +1,207 @@
+/**
+ * New or existing status
+ * @group Models
+ */
+export type EntityStatus = "new" | "existing" | "copy";
+
+/**
+ * Representation of an entity fetched from the datasource
+ * @group Models
+ */
+export interface Entity<M extends object = object> {
+
+    /**
+     * ID of the entity
+     */
+    id: string | number;
+
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    path: string;
+
+    /**
+     * Current values
+     */
+    values: EntityValues<M>;
+
+    /**
+     * Which datasource this entity belongs to (e.g., 'postgres', 'firestore').
+     * If not specified, the default datasource is assumed.
+     */
+    datasource?: string;
+
+    /**
+     * Which database within the datasource (e.g., for Firestore multi-database).
+     * If not specified, the default database of the datasource is used.
+     */
+    databaseId?: string;
+}
+
+/**
+ * This type represents a record of key value pairs as described in an
+ * entity collection.
+ * @group Models
+ */
+export type EntityValues<M extends object> = M;
+
+/**
+ * Props for creating an EntityReference
+ */
+export interface EntityReferenceProps {
+    /** ID of the entity */
+    id: string;
+    /** Path of the collection (relative to the root of the database) */
+    path: string;
+    /** Which datasource (e.g., 'postgres', 'firestore'). Defaults to "(default)" */
+    datasource?: string;
+    /** Which database within the datasource. Defaults to "(default)" */
+    databaseId?: string;
+}
+
+/**
+ * Class used to create a reference to an entity in a different path.
+ * 
+ * @example
+ * // Simple reference (most common case - single datasource, single db)
+ * new EntityReference({ id: "123", path: "users" })
+ * 
+ * // Reference to a different datasource (e.g., Firestore)
+ * new EntityReference({ id: "123", path: "analytics", datasource: "firestore" })
+ * 
+ * // Reference to a specific database within a datasource
+ * new EntityReference({ id: "123", path: "orders", datasource: "postgres", databaseId: "orders_db" })
+ */
+export class EntityReference {
+
+    readonly __type = "reference";
+    /**
+     * ID of the entity
+     */
+    readonly id: string;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    readonly path: string;
+
+    /**
+     * Which datasource (e.g., 'postgres', 'firestore').
+     * Defaults to "(default)" if not specified.
+     */
+    readonly datasource?: string;
+
+    /**
+     * Which database within the datasource.
+     * Defaults to "(default)" if not specified.
+     */
+    readonly databaseId?: string;
+
+    /**
+     * Create a reference to an entity.
+     * 
+     * @example
+     * // Simple reference (most common case)
+     * new EntityReference({ id: "123", path: "users" })
+     * 
+     * // With datasource
+     * new EntityReference({ id: "123", path: "analytics", datasource: "firestore" })
+     */
+    constructor(props: EntityReferenceProps) {
+        this.id = props.id;
+        this.path = props.path;
+        this.datasource = props.datasource;
+        this.databaseId = props.databaseId;
+    }
+
+    get pathWithId() {
+        return `${this.path}/${this.id}`;
+    }
+
+    /**
+     * Get the full path including datasource and database prefixes if specified.
+     * For the common case (single datasource, single db), this just returns pathWithId.
+     */
+    get fullPath() {
+        const parts: string[] = [];
+
+        // Add datasource prefix if not default
+        if (this.datasource && this.datasource !== "(default)") {
+            parts.push(this.datasource);
+        }
+
+        // Add database prefix if specified
+        if (this.databaseId && this.databaseId !== "(default)") {
+            parts.push(this.databaseId);
+        }
+
+        if (parts.length > 0) {
+            return `${parts.join(":")}:::${this.path}/${this.id}`;
+        }
+        return this.pathWithId;
+    }
+
+    isEntityReference() {
+        return true;
+    }
+}
+
+/**
+ * Class used to create a reference to an entity in a different path
+ */
+export class EntityRelation {
+
+    readonly __type = "relation";
+    /**
+     * ID of the entity
+     */
+    readonly id: string | number;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    readonly path: string;
+
+    constructor(id: string | number, path: string) {
+        this.id = id;
+        this.path = path;
+    }
+
+    get pathWithId() {
+        return `${this.path}/${this.id}`;
+    }
+
+    isEntityReference() {
+        return false;
+    }
+
+    isEntityRelation() {
+        return true;
+    }
+}
+
+export class GeoPoint {
+
+    /**
+     * The latitude of this GeoPoint instance.
+     */
+    readonly latitude: number;
+    /**
+     * The longitude of this GeoPoint instance.
+     */
+    readonly longitude: number;
+
+    constructor(latitude: number, longitude: number) {
+        this.latitude = latitude;
+        this.longitude = longitude;
+    }
+}
+
+export class Vector {
+    readonly value: number[];
+
+    constructor(value: number[]) {
+        this.value = value;
+    }
+}

package/src/types/entity_actions.tsx

@@ -0,0 +1,118 @@
+import React from "react";
+import { Entity } from "./entities";
+import { EntityCollection, SelectionController } from "./collections";
+import { FormContext } from "./fields";
+import { User } from "../users";
+import { RebaseContext } from "../rebase_context";
+import { SideEntityController } from "../controllers";
+
+/**
+ * An entity action is a custom action that can be performed on an entity.
+ * They are displayed in the entity view and in the collection view.
+ */
+export type EntityAction<M extends object = any, USER extends User = User> = {
+    /**
+     * Title of the action
+     */
+    name: string;
+
+    /**
+     * Key of the action. You only need to provide this if you want to
+     * override the default actions, or if you are not passing the action
+     * directly to the `entityActions` prop of a collection.
+     * You can define your actions at the app level, in which case you
+     * must provide a key.
+     * The default actions are:
+     * - edit
+     * - delete
+     * - copy
+     */
+    key?: string;
+
+    /**
+     * Icon of the action
+     */
+    icon?: React.ReactElement;
+
+    /**
+     * Callback when the action is clicked
+     * @param props
+     */
+    onClick: (props: EntityActionClickProps<M, USER>) => Promise<void> | void;
+
+    /**
+     * Optional callback in case you want to disable the action
+     * @param props
+     */
+    isEnabled?: (props: EntityActionClickProps<M, USER>) => boolean;
+
+    /**
+     * Show this action collapsed in the menu of the collection view.
+     * Defaults to true
+     * If false, the action will be shown in the menu
+     */
+    collapsed?: boolean;
+
+    /**
+     * Show this action in the form, defaults to true
+     */
+    includeInForm?: boolean;
+
+}
+
+export type EntityActionClickProps<M extends object, USER extends User = User> = {
+    entity?: Entity<M>;
+    context: RebaseContext<USER>;
+
+    path?: string;
+    collection?: EntityCollection<M>;
+
+    /**
+     * Optional form context, present if the action is being called from a form.
+     * This allows you to access the form state and methods, including modifying the form values.
+     */
+    formContext?: FormContext;
+
+    /**
+     * Present if this actions is being called from a side dialog only
+     */
+    sideEntityController?: SideEntityController;
+
+    /**
+     * Is the action being called from the collection view or from the entity form view?
+     */
+    view: "collection" | "form";
+
+    /**
+     * If the action is rendered in the form, is it open in a side panel or full screen?
+     */
+    openEntityMode: "side_panel" | "full_screen";
+
+    /**
+     * Optional selection controller, present if the action is being called from a collection view
+     */
+    selectionController?: SelectionController;
+
+    /**
+     * Optional highlight function to highlight the entity in the collection view
+     * @param entity
+     */
+    highlightEntity?: (entity: Entity<Record<string, unknown>>) => void;
+
+    /**
+     * Optional unhighlight function to remove the highlight from the entity in the collection view
+     * @param entity
+     */
+    unhighlightEntity?: (entity: Entity<Record<string, unknown>>) => void;
+
+    /**
+     * Optional function to navigate back (e.g. when deleting an entity or navigating from a form)
+     */
+    navigateBack?: () => void;
+
+    /**
+     * Callback to be called when the collection changes, e.g. after an entity is deleted or created.
+     */
+    onCollectionChange?: () => void;
+
+};

package/src/types/entity_callbacks.ts

@@ -0,0 +1,217 @@
+import { EntityCollection } from "./collections";
+import { Entity, EntityStatus, EntityValues, } from "./entities";
+import { User } from "../users";
+import { 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.
+ * @group Models
+ */
+export type EntityCallbacks<M extends Record<string, any> = any, USER extends User = User> = {
+
+    /**
+     * Callback used after fetching data
+     * @param props
+     */
+    afterRead?(props: EntityAfterReadProps<M, USER>)
+        : Promise<Entity<M>> | Entity<M>;
+
+
+    /**
+     * Callback used before saving, you need to return the values that will get
+     * 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
+     * @param props
+     */
+    afterSave?(props: EntityAfterSaveProps<M, USER>)
+        : Promise<void> | void;
+
+    /**
+     * Callback used when saving fails
+     * @param props
+     */
+    afterSaveError?(props: EntityAfterSaveErrorProps<M, USER>)
+        : Promise<void> | void;
+
+    /**
+     * Callback used before the entity is deleted.
+     * If you throw an error in this method the process stops, and an
+     * error snackbar gets displayed.
+     *
+     * @param props
+     */
+    beforeDelete?(props: EntityBeforeDeleteProps<M, USER>): void;
+
+    /**
+     * Callback used after the entity is deleted.
+     *
+     * @param props
+     */
+    afterDelete?(props: EntityAfterDeleteProps<M, USER>): void;
+
+}
+
+/**
+ * Parameters passed to hooks when an entity is fetched
+ * @group Models
+ */
+export interface EntityAfterReadProps<M extends Record<string, any> = any, USER extends User = User> {
+
+    /**
+     * Collection of the entity
+     */
+    collection: EntityCollection<M, USER>;
+
+    /**
+     * Full path of the CMS where this collection is being fetched.
+     * Might contain unresolved aliases.
+     */
+    path: string;
+
+    /**
+     * Fetched entity
+     */
+    entity: Entity<M>
+
+    /**
+     * Context of the app status
+     */
+    context: RebaseCallContext<USER>;
+}
+
+/**
+ * Parameters passed to hooks before an entity is saved
+ * @group Models
+ */
+export type EntityBeforeSaveProps<M extends Record<string, any> = any, USER extends User = User> =
+    Omit<EntityAfterSaveProps<M, USER>, "entityId">
+    & {
+        entityId?: string | number;
+    }
+/**
+ * Parameters passed to hooks before an entity is saved
+ * @group Models
+ */
+export type EntityAfterSaveErrorProps<M extends Record<string, any> = any, USER extends User = User> =
+    Omit<EntityAfterSaveProps<M, USER>, "entityId">
+    & {
+        entityId?: string | number;
+    }
+
+/**
+ * Parameters passed to hooks when an entity is saved
+ * @group Models
+ */
+export interface EntityAfterSaveProps<M extends Record<string, any> = any, USER extends User = User> {
+
+    /**
+     * Resolved collection of the entity
+     */
+    collection: EntityCollection<M>;
+
+    /**
+     * Full path of the CMS where this entity is being saved.
+     * Might contain unresolved aliases.
+     */
+    path: string;
+
+    /**
+     * ID of the entity
+     */
+    entityId: string | number;
+
+    /**
+     * Values being saved
+     */
+    values: Partial<EntityValues<M>>;
+
+    /**
+     * Previous values
+     */
+    previousValues?: Partial<EntityValues<M>>;
+
+    /**
+     * New or existing entity
+     */
+    status: EntityStatus;
+
+    /**
+     * Context of the app status
+     */
+    context: RebaseCallContext<USER>;
+}
+
+/**
+ * Parameters passed to hooks when an entity is deleted
+ * @group Models
+ */
+export interface EntityBeforeDeleteProps<M extends Record<string, any> = any, USER extends User = User> {
+
+    /**
+     * collection of the entity being deleted
+     */
+    collection: EntityCollection<M>;
+
+    /**
+     * Path of the parent collection
+     */
+    path: string;
+
+    /**
+     * Deleted entity id
+     */
+    entityId: string | number;
+
+    /**
+     * Deleted entity
+     */
+    entity: Entity<M>;
+
+    /**
+     * Context of the app status
+     */
+    context: RebaseCallContext<USER>;
+}
+
+/**
+ * Parameters passed to hooks after an entity is deleted
+ * @group Models
+ */
+export interface EntityAfterDeleteProps<M extends Record<string, any> = any, USER extends User = User> {
+
+    /**
+     * collection of the entity being deleted
+     */
+    collection: EntityCollection<M>;
+
+    /**
+     * Path of the parent collection
+     */
+    path: string;
+
+    /**
+     * Deleted entity id
+     */
+    entityId: string | number;
+
+    /**
+     * Deleted entity
+     */
+    entity: Entity<M>;
+
+    /**
+     * Context of the app status
+     */
+    context: RebaseCallContext<USER>;
+}
+

package/src/types/entity_link_builder.ts

@@ -0,0 +1,8 @@
+import { Entity } from "./entities";
+
+/**
+ * @group Models
+ */
+export type EntityLinkBuilder<M extends Record<string, any> = any> = ({ entity }: {
+    entity: Entity<M>
+}) => string;

package/src/types/entity_overrides.tsx

@@ -0,0 +1,6 @@
+import { DataSource, StorageSource } from "../controllers";
+
+export type EntityOverrides = {
+    dataSource?: DataSource;
+    storageSource?: StorageSource;
+};

package/src/types/export_import.ts

@@ -0,0 +1,26 @@
+import { Entity } from "./entities";
+import { User } from "../users";
+import { RebaseContext } from "../rebase_context";
+
+/**
+ * You can use this configuration to add additional fields to the data
+ * exports
+ * @group Models
+ */
+export interface ExportConfig<USER extends User = User> {
+    additionalFields: ExportMappingFunction<USER>[];
+}
+
+/**
+ * @group Models
+ */
+export interface ExportMappingFunction<USER extends User = User> {
+    key: string;
+    builder: ({
+        entity,
+        context
+    }: {
+        entity: Entity<any>,
+        context: RebaseContext<USER>
+    }) => Promise<string> | string;
+}