@rebasepro/common 0.0.1-canary.2 → 0.0.1-canary.4829d6e

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Rebase
+Copyright (c) 2026 Rebase
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,174 +1,95 @@
-<p align="center">
-    <img src="https://rebase.pro/img/dark_mode.webp" alt="Intro video" style="max-width: 100%;"/>
-</p>
-
-<p align="center">
-  <a href="https://rebase.pro">
-    <img src="https://rebase.pro/img/logo_small.png" width="240px" alt="Rebase logo" />
-  </a>
-</p>
-
-<h1 align="center">Rebase</h1>
-<h3 align="center">Awesome Firebase/MongoDB-based headless CMS</h3>
-<p align="center"><a href="https://demo.rebase.pro">Live demo</a></p>
-
-<br />
-
-
-[![NPM](https://img.shields.io/npm/v/rebase.svg)](https://www.npmjs.com/package/rebase) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
-
-Designed by developers for developers, Rebase is a headless CMS and admin panel
-that seamlessly integrates with **Firebase and Firestore** by default, but is
-also
-compatible with any backend.
-
-Effortlessly generate **CRUD views** based on your configuration. Rebase is
-simple
-to set up for standard cases and easy to extend and customize for more specific
-needs.
-
-Built to produce collection and form views that naturally align with the
-collection/document model, Rebase covers a wide range of basic and advanced use
-cases. With extensibility in mind, it's easy to create your own views or modify
-existing ones.
-
-Rebase does **not impose any data structure** restrictions, ensuring a smooth,
-out-of-the-box experience for any project.
-
-### Core technologies
-
-Rebase is based on this great technologies:
-
-- Typescript
-- Tailwind CSS
-- Firebase SDK 10
-- React + React Router 6
-
-### Quickstart
-
-The easiest way to get going is to check our quickstart guide! You will just
-need to follow some quick steps:
-
-https://rebase.pro/docs
-
-### Demo
-
-Check the demo with all the core functionalities.
-
-https://demo.rebase.pro
-
-> You can modify the data, but it gets periodically restored.
-
-### Changelog
-
-https://rebase.pro/docs/changelog
-
-## Features
-
-Rebase has been meticulously crafted to make it incredibly easy for developers
-to build a CMS/admin tool while offering an excellent data editing experience
-and a user-friendly interface for marketers and content managers.
-
-### 🏓 Exceptional Spreadsheet View
-
-We've developed a highly efficient windowed **spreadsheet view** for
-collections, allowing inline editing for most common fields, as well as popup
-views for other cases and your custom field implementations.
-
-Featuring **real-time** support, Rebase is perfect for apps that require
-constant updates. It also supports **text search** (through an external provider
-like Algolia, if using Firestore), **filtering and sorting**, and **exporting**
-data.
-
-### ✨ Robust Forms
-
-![fields](https://rebase.pro/img/form_editing.webp)
-
-When editing an entity, Rebase offers a nested system of side dialogs for
-navigating through **subcollections** and accessing custom views (such as custom
-forms or blog previews). This functionality can also be accessed
-programmatically using the `useSideEntityController` hook.
-
-Rebase includes **over 20 built-in fields** with numerous customization and
-validation options. The components have been carefully designed for an
-outstanding user experience, including advanced features like **references** to
-other collections, **markdown**, and **array reordering**.
-
-For unsupported use cases, create your own **custom field** as a React
-component.
-
-Rebase also supports **conditional fields** in forms, allowing you to define
-rules for active fields based on your logic.
-
-### 👮 Authentication, Permissions, and Role System
-
-Define which navigation views users can see and the operations (create, edit,
-delete) they can perform based on your role system. You can even configure this
-on a per-entity or collection level.
-
-By default, Rebase supports all Firebase authorization mechanisms, but you can
-implement your own.
-
-### 🏹 Relational Support
-
-Define references to entities in other collections and benefit from the
-integrated reference fields and shortcuts.
-
-You can also define subcollections at the entity level for nesting data in a
-collection/document/collection model.
-
-### 🆒 Real-Time Data
-
-Every view in the CMS supports real-time data, making it suitable for displaying
-constantly updated information.
-
-Forms also support this feature, with any modified value in the database being
-updated in any open form view as long as it hasn't been touched by the user.
-This enables advanced cases where a Cloud Function is triggered after saving an
-entity, modifying some values, and requiring real-time updates.
-
-### 🗂️ File Storage
-
-Rebase supports uploading files to Firebase Storage out of the box and provides
-specific fields for handling single and multiple file uploads, as well as
-reordering.
-
-You can replace the Firebase Storage implementation with your own.
-
-## Included example
-
-You can access the code for the demo project under
-[`example`](https://github.com/Rebaseco/rebase/tree/master/example). It includes
-every feature provided by this CMS.
-
-Keep in mind you need to update the dependencies in that project if you want to
-use it as it is, without linking it to the library source code. More details in
-its README
-
-## Contact and support
-
-If you need general support, you can open a GitHub issue.
-
-Do you need consulting setting up your Firestore-based CMS in no time? We are
-happy to help!
-`hello@rebase.pro`
-
-## Development
-
-If you would like to make changes to the source, feel free to submit a PR!
-
-When developing, the core library can be found under `lib`.
-There is an example project in the folder `example`.
-
-In order to run the project, you need to create a file
-called `firebase_config.ts`
-in `example/src`.
-
-That file needs to export a valid Firebase config, that you can get
-from your Firebase console when creating a webapp for your project.
-
-Then simply run `yarn` and `yarn dev`
-
-## License
-
-MIT © [Rebase](https://github.com/Rebaseco)
+# @rebasepro/common
+
+Shared utilities, collection registry, data driver adapter, and fluent query builder used across Rebase packages.
+
+## Installation
+
+```bash
+pnpm add @rebasepro/common
+```
+
+## What This Package Does
+
+`@rebasepro/common` is the lowest-level shared logic layer in the Rebase frontend stack. It provides:
+
+- **Collection utilities** — collection registry, default collection definitions, path resolution, navigation helpers
+- **Data driver adapter** — `buildRebaseData()` bridges any `DataDriver` implementation into a `RebaseData` proxy with typed collection accessors
+- **Query builder** — fluent `QueryBuilder` class plus `or()`, `and()`, `cond()` helpers for composing complex queries
+- **Snapshot/property utilities** — snapshot resolution, enum helpers, permission checks, reference/relation helpers, storage path utils, callback utilities
+
+This package has no React dependency — it's pure TypeScript and can be used in both client and server contexts.
+
+## Key Exports
+
+### Data
+
+| Export | Description |
+|---|---|
+| `buildRebaseData(driver)` | Wraps a `DataDriver` in a `Proxy`-based `RebaseData` object. Property access like `data.products` returns a `CollectionAccessor` for that collection slug (camelCase → snake_case). |
+| `QueryBuilder<M>` | Fluent query builder with `.where()`, `.orderBy()`, `.limit()`, `.offset()`, `.search()`, `.include()`, `.find()`, and `.listen()` |
+| `or(...conditions)` | Create an OR logical condition |
+| `and(...conditions)` | Create an AND logical condition |
+| `cond(column, op, value)` | Create a single filter condition |
+
+### Collections
+
+| Export | Description |
+|---|---|
+| `CollectionRegistry` | Registry for managing collection definitions |
+| Default collections | Pre-built collection configurations |
+
+### Utilities
+
+| Module | Contents |
+|---|---|
+| `collections` | Collection config helpers |
+| `common` | General-purpose utilities |
+| `snapshots` | Snapshot value resolution |
+| `enums` | Enum type helpers |
+| `paths` | Path parsing and manipulation |
+| `resolutions` | Property and collection resolution |
+| `permissions` | Permission evaluation |
+| `references` | Reference property helpers |
+| `relations` | Relation property helpers |
+| `navigation_from_path` | Build navigation tree from a path |
+| `parent_references_from_path` | Extract parent references |
+| `builders` | Collection/property builder utilities |
+| `storage` | Storage path utilities |
+| `callbacks` | Callback composition utilities |
+| `conditions` | Conditional logic helpers |
+| `navigation_utils` | Navigation tree utilities |
+
+## Quick Start
+
+```ts
+import { buildRebaseData, QueryBuilder, or, cond } from "@rebasepro/common";
+
+// Wrap a DataDriver into a proxy-based data accessor
+const data = buildRebaseData(myDriver);
+
+// Access collections by name (camelCase auto-converts to snake_case)
+const { data: products } = await data.products.find({ limit: 10 });
+const snapshot = await data.products.findById("abc-123");
+
+// Fluent query builder
+const { data: results } = await data.products
+    .where("status", "==", "published")
+    .orderBy("created_at", "desc")
+    .limit(20)
+    .find();
+
+// Complex logical queries
+const { data: filtered } = await data.products
+    .where(or(
+        cond("category", "==", "electronics"),
+        cond("price", ">=", 100)
+    ))
+    .find();
+```
+
+## Related Packages
+
+- [`@rebasepro/types`](../types) — `DataDriver`, `RebaseData`, `CollectionAccessor`, `Snapshot`, `FindResponse`, etc.
+- [`@rebasepro/utils`](../utils) — Low-level utilities (`toSnakeCase`, etc.)
+- [`@rebasepro/app`](../core) — Runtime layer that consumes `@rebasepro/common`
+- [`@rebasepro/client`](../client) — HTTP client that re-exports and extends the `QueryBuilder`

package/dist/collections/CollectionRegistry.d.ts

@@ -1,48 +1,84 @@
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionCallbacks, CollectionConfig } from "@rebasepro/types";
+import { DataSourceRegistry } from "../data/resolveDataSource";
 export declare class CollectionRegistry {
-    private collectionsByDbPath;
+    /**
+     * Declared data sources, used during normalization to resolve each
+     * collection's engine (so `dataSource`-only collections get the right
+     * capabilities). Empty by default.
+     */
+    private dataSources;
+    /**
+     * Global lifecycle callbacks applied to every collection.
+     * Runs on all data paths (REST, WebSocket, `rebase.data`).
+     * Execution order: global → collection → property callbacks.
+     */
+    private _globalCallbacks?;
+    /**
+     * Set global lifecycle callbacks that apply to every collection.
+     * Typically called once during backend initialization.
+     */
+    setGlobalCallbacks(callbacks: CollectionCallbacks): void;
+    /**
+     * Get the currently registered global callbacks, if any.
+     */
+    getGlobalCallbacks(): CollectionCallbacks | undefined;
+    private collectionsByTableName;
     private collectionsBySlug;
     private rootCollections;
-    private rawCollectionsByDbPath;
+    private cachedCollectionsList;
+    private rawCollectionsByTableName;
     private rawCollectionsBySlug;
     private rawRootCollections;
-    private lastRawInputSnapshot;
-    constructor(collections?: EntityCollection[]);
+    private cachedRawCollectionsList;
+    private lastRawInputEntity;
+    constructor(collections?: CollectionConfig[], dataSources?: DataSourceRegistry);
+    /**
+     * Provide the declared data sources used to resolve each collection's
+     * engine during normalization. Set this before registering collections.
+     * Returns true if the registry changed (callers may re-register).
+     */
+    setDataSources(dataSources: DataSourceRegistry): boolean;
     reset(): void;
     /**
      * Registers a collection and its subcollections recursively.
      * Returns true if the collections have changed, false otherwise.
      *
      * Idempotent: compares the raw input (before normalization) against a stored
-     * snapshot. Only re-normalizes and re-registers when the raw input actually changed.
+     * entity. Only re-normalizes and re-registers when the raw input actually changed.
      * @param collections
      */
-    registerMultiple(collections: EntityCollection[]): boolean;
-    register(collection: EntityCollection, rawCollection?: EntityCollection): void;
+    registerMultiple(collections: CollectionConfig[]): boolean;
+    register(collection: CollectionConfig, rawCollection?: CollectionConfig): void;
     private _registerRecursively;
-    normalizeCollection(collection: EntityCollection): EntityCollection;
+    normalizeCollection(collection: CollectionConfig): CollectionConfig;
+    /**
+     * Extract Relation[] from properties that have inline relation config (i.e. `target` is set).
+     * This allows developers to define relations directly on properties without a separate
+     * `relations[]` entry on the collection.
+     */
+    private extractRelationsFromProperties;
     private normalizeProperties;
     private normalizeProperty;
-    get(path: string): EntityCollection | undefined;
+    get(path: string): CollectionConfig | undefined;
     /**
      * Gets the pristine, un-normalized collection exactly as it was provided.
      * Useful for the AST editor so it doesn't accidentally serialize injected metadata back to disk.
      */
-    getRaw(path: string): EntityCollection | undefined;
+    getRaw(path: string): CollectionConfig | undefined;
     /**
      * Get collection by resolving multi-segment paths through relations
      * e.g., "authors/70/posts" resolves to the posts collection
      */
-    getCollectionByPath(collectionPath: string): EntityCollection | undefined;
-    getCollections(): EntityCollection[];
-    getRawCollections(): EntityCollection[];
+    getCollectionByPath(collectionPath: string): CollectionConfig | undefined;
+    getCollections(): CollectionConfig[];
+    getRawCollections(): CollectionConfig[];
     /**
      * Resolves a multi-segment path like "products/123/locales" and returns
      * information about the collections and entity IDs along the path
      */
     resolvePathToCollections(path: string): {
-        collections: EntityCollection[];
+        collections: CollectionConfig[];
         entityIds: (string | number)[];
-        finalCollection: EntityCollection;
+        finalCollection: CollectionConfig;
     };
 }

package/dist/collections/default-collections.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Default users collection.
+ *
+ * Prepended to the developer's collections array by the admin and server.
+ * Slug-based dedup (Map keyed by slug, last-write-wins) lets developers
+ * override by defining their own collection with `slug: "users"`.
+ */
+export declare const defaultUsersCollection: import("@rebasepro/types").PostgresCollectionConfig<import("@rebasepro/types").InferEntityType<{
+    readonly id: {
+        readonly name: "ID";
+        readonly type: "string";
+        readonly isId: "uuid";
+        readonly ui: {
+            readonly readOnly: true;
+        };
+    };
+    readonly email: {
+        readonly name: "Email";
+        readonly type: "string";
+        readonly validation: {
+            readonly required: true;
+            readonly unique: true;
+        };
+    };
+    readonly displayName: {
+        readonly name: "Name";
+        readonly type: "string";
+        readonly columnName: "display_name";
+        readonly validation: {
+            readonly required: true;
+        };
+    };
+    readonly photoURL: {
+        readonly name: "Photo URL";
+        readonly type: "string";
+        readonly columnName: "photo_url";
+        readonly ui: {
+            readonly url: "image";
+        };
+    };
+    readonly roles: {
+        readonly name: "Roles";
+        readonly type: "array";
+        readonly columnType: "text[]";
+        readonly of: {
+            readonly name: "Role";
+            readonly type: "string";
+            readonly enum: {
+                readonly admin: "Admin";
+                readonly editor: "Editor";
+                readonly viewer: "Viewer";
+            };
+        };
+    };
+    readonly passwordHash: {
+        readonly name: "Password Hash";
+        readonly type: "string";
+        readonly columnName: "password_hash";
+        readonly ui: {
+            readonly hideFromCollection: true;
+            readonly disabled: {
+                readonly hidden: true;
+            };
+        };
+    };
+    readonly emailVerified: {
+        readonly name: "Email Verified";
+        readonly type: "boolean";
+        readonly columnName: "email_verified";
+        readonly defaultValue: false;
+        readonly ui: {
+            readonly hideFromCollection: true;
+            readonly disabled: {
+                readonly hidden: true;
+            };
+        };
+    };
+    readonly emailVerificationToken: {
+        readonly name: "Email Verification Token";
+        readonly type: "string";
+        readonly columnName: "email_verification_token";
+        readonly ui: {
+            readonly hideFromCollection: true;
+            readonly disabled: {
+                readonly hidden: true;
+            };
+        };
+    };
+    readonly emailVerificationSentAt: {
+        readonly name: "Email Verification Sent At";
+        readonly type: "date";
+        readonly columnName: "email_verification_sent_at";
+        readonly ui: {
+            readonly hideFromCollection: true;
+            readonly disabled: {
+                readonly hidden: true;
+            };
+        };
+    };
+    readonly metadata: {
+        readonly name: "Metadata";
+        readonly type: "map";
+        readonly keyValue: true;
+        readonly properties: {};
+        readonly defaultValue: {};
+        readonly ui: {
+            readonly hideFromCollection: true;
+            readonly disabled: {
+                readonly hidden: true;
+            };
+        };
+    };
+    readonly createdAt: {
+        readonly name: "Created At";
+        readonly type: "date";
+        readonly columnName: "created_at";
+        readonly autoValue: "on_create";
+        readonly ui: {
+            readonly readOnly: true;
+        };
+    };
+    readonly updatedAt: {
+        readonly name: "Updated At";
+        readonly type: "date";
+        readonly columnName: "updated_at";
+        readonly autoValue: "on_update";
+        readonly ui: {
+            readonly hideFromCollection: true;
+            readonly disabled: {
+                readonly hidden: true;
+            };
+        };
+    };
+}>, import("@rebasepro/types").User> & {
+    properties: {
+        readonly id: {
+            readonly name: "ID";
+            readonly type: "string";
+            readonly isId: "uuid";
+            readonly ui: {
+                readonly readOnly: true;
+            };
+        };
+        readonly email: {
+            readonly name: "Email";
+            readonly type: "string";
+            readonly validation: {
+                readonly required: true;
+                readonly unique: true;
+            };
+        };
+        readonly displayName: {
+            readonly name: "Name";
+            readonly type: "string";
+            readonly columnName: "display_name";
+            readonly validation: {
+                readonly required: true;
+            };
+        };
+        readonly photoURL: {
+            readonly name: "Photo URL";
+            readonly type: "string";
+            readonly columnName: "photo_url";
+            readonly ui: {
+                readonly url: "image";
+            };
+        };
+        readonly roles: {
+            readonly name: "Roles";
+            readonly type: "array";
+            readonly columnType: "text[]";
+            readonly of: {
+                readonly name: "Role";
+                readonly type: "string";
+                readonly enum: {
+                    readonly admin: "Admin";
+                    readonly editor: "Editor";
+                    readonly viewer: "Viewer";
+                };
+            };
+        };
+        readonly passwordHash: {
+            readonly name: "Password Hash";
+            readonly type: "string";
+            readonly columnName: "password_hash";
+            readonly ui: {
+                readonly hideFromCollection: true;
+                readonly disabled: {
+                    readonly hidden: true;
+                };
+            };
+        };
+        readonly emailVerified: {
+            readonly name: "Email Verified";
+            readonly type: "boolean";
+            readonly columnName: "email_verified";
+            readonly defaultValue: false;
+            readonly ui: {
+                readonly hideFromCollection: true;
+                readonly disabled: {
+                    readonly hidden: true;
+                };
+            };
+        };
+        readonly emailVerificationToken: {
+            readonly name: "Email Verification Token";
+            readonly type: "string";
+            readonly columnName: "email_verification_token";
+            readonly ui: {
+                readonly hideFromCollection: true;
+                readonly disabled: {
+                    readonly hidden: true;
+                };
+            };
+        };
+        readonly emailVerificationSentAt: {
+            readonly name: "Email Verification Sent At";
+            readonly type: "date";
+            readonly columnName: "email_verification_sent_at";
+            readonly ui: {
+                readonly hideFromCollection: true;
+                readonly disabled: {
+                    readonly hidden: true;
+                };
+            };
+        };
+        readonly metadata: {
+            readonly name: "Metadata";
+            readonly type: "map";
+            readonly keyValue: true;
+            readonly properties: {};
+            readonly defaultValue: {};
+            readonly ui: {
+                readonly hideFromCollection: true;
+                readonly disabled: {
+                    readonly hidden: true;
+                };
+            };
+        };
+        readonly createdAt: {
+            readonly name: "Created At";
+            readonly type: "date";
+            readonly columnName: "created_at";
+            readonly autoValue: "on_create";
+            readonly ui: {
+                readonly readOnly: true;
+            };
+        };
+        readonly updatedAt: {
+            readonly name: "Updated At";
+            readonly type: "date";
+            readonly columnName: "updated_at";
+            readonly autoValue: "on_update";
+            readonly ui: {
+                readonly hideFromCollection: true;
+                readonly disabled: {
+                    readonly hidden: true;
+                };
+            };
+        };
+    };
+};

package/dist/collections/index.d.ts

@@ -1 +1,2 @@
 export * from "./CollectionRegistry";
+export * from "./default-collections";