@rebasepro/common 0.6.1 → 0.8.0

package/dist/table-classification.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Table Classification
+ *
+ * Shared constants and pure functions for classifying database tables.
+ * Used by both the server-side PostgresBackendDriver and the Studio RLS editor.
+ */
+/** Possible categories a database table can belong to. */
+export type TableCategory = "rebase-internal" | "junction" | "user";
+/** Schemas that are always considered Rebase-internal. */
+export declare const REBASE_INTERNAL_SCHEMAS: readonly string[];
+/** Table-name prefixes that mark a table as Rebase-internal regardless of schema. */
+export declare const REBASE_INTERNAL_PREFIXES: readonly string[];
+/**
+ * Synchronously classify a table based on naming conventions.
+ *
+ * @param tableName  - The unqualified name of the table.
+ * @param schemaName - The schema the table belongs to (e.g. `"public"`, `"rebase"`).
+ * @returns `"rebase-internal"` when the table belongs to a reserved schema or
+ *          carries a reserved prefix; `"user"` otherwise.
+ *
+ * @remarks
+ * Junction-table detection requires an async database query and is therefore
+ * **not** handled by this function. Use {@link detectJunctionTables} to obtain
+ * the set of junction tables, then reclassify as needed.
+ */
+export declare function classifyTable(tableName: string, schemaName: string): TableCategory;
+/**
+ * Convenience predicate that checks whether a table is Rebase-internal.
+ *
+ * @param tableName  - The unqualified name of the table.
+ * @param schemaName - The schema the table belongs to.
+ * @returns `true` if the table is classified as `"rebase-internal"`.
+ */
+export declare function isRebaseInternalTable(tableName: string, schemaName: string): boolean;
+/** SQL query that detects junction tables in the `public` schema. */
+export declare const JUNCTION_TABLES_SQL = "\n  SELECT t.table_name\n  FROM information_schema.tables t\n  WHERE t.table_schema = 'public'\n    AND t.table_type = 'BASE TABLE'\n    AND NOT EXISTS (\n      SELECT 1\n      FROM information_schema.columns c\n      WHERE c.table_schema = t.table_schema\n        AND c.table_name = t.table_name\n        AND c.column_name NOT IN (\n          SELECT kcu.column_name\n          FROM information_schema.key_column_usage kcu\n          JOIN information_schema.table_constraints tc\n            ON tc.constraint_name = kcu.constraint_name\n            AND tc.table_schema = kcu.table_schema\n          WHERE tc.constraint_type = 'FOREIGN KEY'\n            AND kcu.table_schema = t.table_schema\n            AND kcu.table_name = t.table_name\n        )\n    )\n";
+/**
+ * Asynchronously detect junction (link) tables in the `public` schema.
+ *
+ * A junction table is defined as a table where **every** column participates in
+ * at least one foreign-key constraint.
+ *
+ * @param executeSql - A callback that executes a raw SQL string and returns the
+ *                     resulting rows.
+ * @returns A `Set` containing the names of all detected junction tables.
+ */
+export declare function detectJunctionTables(executeSql: (sql: string) => Promise<Record<string, unknown>[]>): Promise<Set<string>>;

package/dist/util/builders.d.ts

@@ -1,4 +1,4 @@
-import { AdditionalFieldDelegate, ArrayProperty, BooleanProperty, DateProperty, EntityCallbacks, EntityCollection, EnumValueConfig, EnumValues, GeopointProperty, MapProperty, NumberProperty, Properties, Property, ReferenceProperty, StringProperty, User } from "@rebasepro/types";
+import { AdditionalFieldDelegate, ArrayProperty, BooleanProperty, DateProperty, EntityCallbacks, EntityCollection, EnumValueConfig, EnumValues, FirebaseCollection, FirebaseProperties, GeopointProperty, InferEntityType, MapProperty, MongoDBCollection, MongoProperties, NumberProperty, PostgresCollection, PostgresProperties, Properties, Property, ReferenceProperty, StringProperty, User } from "@rebasepro/types";
 /**
  * Identity function we use to defeat the type system of Typescript and build
  * collection views with all its properties
@@ -6,6 +6,53 @@ import { AdditionalFieldDelegate, ArrayProperty, BooleanProperty, DateProperty,
  * @group Builder
  */
 export declare function buildCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: EntityCollection<M, USER>): EntityCollection<M, USER>;
+/**
+ * Define a PostgreSQL-backed collection with full type inference.
+ *
+ * The `const P` generic captures literal property types from your
+ * `properties` object, which enables autocomplete on `titleProperty`,
+ * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
+ *
+ * @example
+ * ```ts
+ * const products = defineCollection({
+ *     name: "Products",
+ *     slug: "products",
+ *     table: "products",
+ *     properties: {
+ *         name: { name: "Name", type: "string", validation: { required: true } },
+ *         price: { name: "Price", type: "number" },
+ *     },
+ *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     sort: ["price", "asc"], // ✅ autocomplete on first element
+ * });
+ * ```
+ *
+ * @group Builder
+ */
+export declare function defineCollection<const P extends PostgresProperties, USER extends User = User>(collection: Omit<PostgresCollection<InferEntityType<P>, USER>, "properties"> & {
+    properties: P;
+}): PostgresCollection<InferEntityType<P>, USER> & {
+    properties: P;
+};
+/**
+ * Define a Firestore-backed collection with full type inference.
+ * @group Builder
+ */
+export declare function defineCollection<const P extends FirebaseProperties, USER extends User = User>(collection: Omit<FirebaseCollection<InferEntityType<P>, USER>, "properties"> & {
+    properties: P;
+}): FirebaseCollection<InferEntityType<P>, USER> & {
+    properties: P;
+};
+/**
+ * Define a MongoDB-backed collection with full type inference.
+ * @group Builder
+ */
+export declare function defineCollection<const P extends MongoProperties, USER extends User = User>(collection: Omit<MongoDBCollection<InferEntityType<P>, USER>, "properties"> & {
+    properties: P;
+}): MongoDBCollection<InferEntityType<P>, USER> & {
+    properties: P;
+};
 /**
  * Identity function we use to defeat the type system of Typescript and preserve
  * the property keys.

package/dist/util/callbacks.d.ts

@@ -1,4 +1,9 @@
-import { EntityCallbacks, Properties } from "@rebasepro/types";
+import { EntityCallbacks, Properties, RebaseCallContext } from "@rebasepro/types";
+/**
+ * Context passed to entity lifecycle callbacks.
+ * @group Models
+ */
+export type EntityCallbackContext = RebaseCallContext;
 /**
  * Helper function to extract field-level PropertyCallbacks from a properties schema
  * and wrap them into an EntityCallbacks object recursively.

package/dist/util/index.d.ts

@@ -4,6 +4,7 @@ export * from "./entities";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
+export * from "./policy";
 export * from "./permissions";
 export * from "./references";
 export * from "./navigation_from_path";

package/dist/util/permissions.d.ts

@@ -1,4 +1,4 @@
-import { Entity, EntityCollection, User } from "@rebasepro/types";
+import { Entity, EntityCollection, SecurityOperation, User } from "@rebasepro/types";
 /**
  * Minimal auth context for permission checking.
  * Only requires the user object — avoids forcing callers to construct
@@ -7,7 +7,31 @@ import { Entity, EntityCollection, User } from "@rebasepro/types";
 export interface AuthContext<USER extends User = User> {
     user: USER | null;
 }
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+/**
+ * How to resolve a policy result that cannot be decided client-side (a raw-SQL
+ * escape-hatch rule, or a row-column reference with no row in hand).
+ *
+ * - `"allow"` (default): optimistic — used for admin-UI gating, where Postgres
+ *   remains the authoritative gate and hiding a working action is worse than
+ *   showing one the server may reject.
+ * - `"deny"`: fail-closed — used by real enforcement callers (e.g. a driver
+ *   applying policies in-process), so an undecidable rule never silently allows.
+ */
+export type UnknownResolution = "allow" | "deny";
+export interface CheckOperationOptions {
+    onUnknown?: UnknownResolution;
+}
+/**
+ * Decide whether an operation is permitted for a user on a (possibly null) row,
+ * by evaluating the collection's security rules with the shared policy model —
+ * the same model compiled to Postgres RLS DDL, so the decision matches database
+ * enforcement for every non-raw rule.
+ *
+ * @param options.onUnknown how to treat rules that cannot be decided
+ *   client-side (raw SQL, or row predicates with no row). Defaults to `"allow"`
+ *   for optimistic UI gating; enforcement callers should pass `"deny"`.
+ */
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: SecurityOperation, options?: CheckOperationOptions): boolean;
 export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
 export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
 export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;

package/dist/util/policy/evaluatePolicy.d.ts

@@ -0,0 +1,31 @@
+import { Entity, PolicyExpression } from "@rebasepro/types";
+/**
+ * Result of evaluating a policy client-side. `"unknown"` means the expression
+ * could not be decided without more information — either a raw-SQL escape-hatch
+ * node (which the client deliberately never guesses) or a row-column reference
+ * with no entity in hand (e.g. list-level gating). Callers decide how to resolve
+ * `"unknown"`: fail-closed for an enforcement decision, optimistic for pure
+ * visibility gating.
+ */
+export type TriState = boolean | "unknown";
+/**
+ * Context for {@link evaluatePolicy}: the acting user (or none) and the row
+ * being evaluated (or none, for collection-level gating).
+ */
+export interface PolicyEvalContext {
+    /** The current user's id, or null/undefined when unauthenticated. */
+    uid?: string | null;
+    /** The current user's application roles. */
+    roles?: string[];
+    /** The row being evaluated, or null when no specific row is available. */
+    entity: Entity | null;
+}
+/**
+ * Evaluates a {@link PolicyExpression} against a user + row, using three-valued
+ * (Kleene) logic so that `"unknown"` sub-results propagate soundly.
+ *
+ * This is the JavaScript twin of {@link policyToPostgres}: both derive from the
+ * same expression, so the admin UI matches database enforcement by construction
+ * for every non-raw rule.
+ */
+export declare function evaluatePolicy(expr: PolicyExpression, ctx: PolicyEvalContext): TriState;

package/dist/util/policy/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./securityRuleToConditions";
+export * from "./policyToPostgres";
+export * from "./evaluatePolicy";

package/dist/util/policy/policyToPostgres.d.ts

@@ -0,0 +1,10 @@
+import { EntityCollection, PolicyExpression } from "@rebasepro/types";
+/**
+ * Compiles a {@link PolicyExpression} to a PostgreSQL boolean SQL string,
+ * suitable for a `USING (...)` / `WITH CHECK (...)` clause.
+ *
+ * This is one of the two consumers of the shared policy model (the other being
+ * {@link evaluatePolicy}); the Postgres schema generators call it so that DDL
+ * and the admin UI derive from the exact same expression.
+ */
+export declare function policyToPostgres(expr: PolicyExpression, collection?: EntityCollection): string;

package/dist/util/policy/securityRuleToConditions.d.ts

@@ -0,0 +1,24 @@
+import { PolicyExpression, SecurityRule } from "@rebasepro/types";
+/**
+ * The normalized `USING` / `WITH CHECK` conditions for a single security rule,
+ * expressed in the engine-agnostic {@link PolicyExpression} model.
+ *
+ * A `null` clause means "this rule contributes no condition for that clause";
+ * consumers apply the default (Postgres denies with `false`).
+ */
+export interface RuleConditions {
+    usingExpr: PolicyExpression | null;
+    withCheckExpr: PolicyExpression | null;
+}
+/**
+ * Desugars a {@link SecurityRule} — its `access`/`ownerField`/`roles` shortcuts,
+ * structured `condition`/`check`, and raw `using`/`withCheck` — into a single
+ * normalized {@link PolicyExpression} pair.
+ *
+ * **This is the linchpin against drift:** both the Postgres DDL generators and
+ * the client-side evaluator consume this one function, so there is exactly one
+ * definition of what a rule means. In particular, application `roles` are folded
+ * into the expression here (AND'd with the base condition, matching how Postgres
+ * generates the clause) rather than being handled separately by each consumer.
+ */
+export declare function securityRuleToConditions(rule: SecurityRule): RuleConditions;

package/dist/util/policy/sqlToPolicy.d.ts

@@ -0,0 +1,20 @@
+import { PolicyExpression } from "@rebasepro/types";
+/**
+ * A tiny, regex-based SQL "parser" for security rules.
+ *
+ * This is NOT a full SQL parser. It is designed to handle the subset of SQL
+ * commonly used in `USING` and `WITH CHECK` clauses, enough to drive the
+ * optimistic client-side UI decision.
+ *
+ * It handles:
+ * - `field = 'literal'`
+ * - `field != 'literal'`
+ * - `field = current_setting('app.user_id')`
+ * - `A AND B`
+ * - `true`
+ * - `IN (...)` (as optimistic true)
+ *
+ * For anything it doesn't understand, it returns a `raw` expression, which
+ * the evaluator treats as "unknown" (and usually optimistic true).
+ */
+export declare function sqlToPolicy(sql: string): PolicyExpression;

package/dist/util/storage.d.ts

@@ -1,4 +1,29 @@
-import { ArrayProperty, EntityValues, StorageConfig, StringProperty, UploadedFileContext } from "@rebasepro/types";
+import { ArrayProperty, EntityValues, StorageConfig, StorageSource, StorageSourceRegistry, StringProperty, UploadedFileContext } from "@rebasepro/types";
+/**
+ * Resolve the {@link StorageSource} to use for a property, given the key
+ * referenced by `StorageConfig.storageSource`.
+ *
+ * Resolution priority:
+ * 1. No `sourceKey` → the default source (backward compatible).
+ * 2. An explicit {@link StorageSourceRegistry} (e.g. `client.storageRegistry`).
+ * 3. A `sources` lookup map (e.g. the `StorageSourcesContext`).
+ * 4. Fall back to the default source.
+ *
+ * Shared by the upload hook, the markdown editor, and the read-only previews
+ * so the resolution logic lives in one place.
+ *
+ * @group Storage
+ */
+export declare function resolveStorageSource(params: {
+    /** Key from `StorageConfig.storageSource`. */
+    sourceKey?: string | null;
+    /** Built sources keyed by storage-source key (e.g. from context). */
+    sources?: Record<string, StorageSource>;
+    /** Optional explicit registry — takes precedence over `sources`. */
+    registry?: StorageSourceRegistry;
+    /** Default source, used when no key is set or the key cannot be resolved. */
+    defaultSource: StorageSource;
+}): StorageSource;
 interface ResolveFilenameStringParams<M extends Record<string, unknown>> {
     input: string | ((context: UploadedFileContext) => (Promise<string> | string));
     storage: StorageConfig;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -41,8 +41,8 @@
   "dependencies": {
     "fast-equals": "6.0.0",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.6.1",
-    "@rebasepro/utils": "0.6.1"
+    "@rebasepro/utils": "0.8.0",
+    "@rebasepro/types": "0.8.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/collections/CollectionRegistry.ts

@@ -1,23 +1,61 @@
 import {
     ArrayProperty,
-    CollectionWithRelations,
-    CollectionWithSubcollections,
+    EntityCallbacks,
+    EngineProperties,
     EntityCollection,
+    getDataSourceCapabilities,
+    getDeclaredSubcollections,
     NumberProperty,
     Properties,
     Property,
     Relation,
     RelationProperty,
-    StringProperty,
-    getDataSourceCapabilities
+    StringProperty
 } from "@rebasepro/types";
 import { deepEqual } from "fast-equals";
 
-import { enumToObjectEntries, getSubcollections, getTableName, resolveCollectionRelations, findRelation, sanitizeRelation } from "../util";
-import { removeFunctions, mergeDeep, deepClone } from "@rebasepro/utils";
+import {
+    enumToObjectEntries,
+    findRelation,
+    getSubcollections,
+    getTableName,
+    resolveCollectionRelations,
+    sanitizeRelation
+} from "../util";
+import { deepClone, mergeDeep, removeFunctions } from "@rebasepro/utils";
+import { DataSourceRegistry, resolveDataSource } from "../data/resolveDataSource";
 
 export class CollectionRegistry {
 
+    /**
+     * 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: DataSourceRegistry = {};
+
+    /**
+     * Global lifecycle callbacks applied to every collection.
+     * Runs on all data paths (REST, WebSocket, `rebase.data`).
+     * Execution order: global → collection → property callbacks.
+     */
+    private _globalCallbacks?: EntityCallbacks;
+
+    /**
+     * Set global lifecycle callbacks that apply to every collection.
+     * Typically called once during backend initialization.
+     */
+    setGlobalCallbacks(callbacks: EntityCallbacks): void {
+        this._globalCallbacks = callbacks;
+    }
+
+    /**
+     * Get the currently registered global callbacks, if any.
+     */
+    getGlobalCallbacks(): EntityCallbacks | undefined {
+        return this._globalCallbacks;
+    }
+
     // Normalized runtime layer (used by Data Grid / UI)
     private collectionsByTableName = new Map<string, EntityCollection>();
     private collectionsBySlug = new Map<string, EntityCollection>();
@@ -34,12 +72,24 @@ export class CollectionRegistry {
     // to avoid the issue where normalization creates new objects that always fail equality.
     private lastRawInputSnapshot: ReturnType<typeof removeFunctions>[] | null = null;
 
-    constructor(collections?: EntityCollection[]) {
+    constructor(collections?: EntityCollection[], dataSources?: DataSourceRegistry) {
+        if (dataSources) this.dataSources = dataSources;
         if (collections) {
             this.registerMultiple(collections);
         }
     }
 
+    /**
+     * 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 {
+        if (deepEqual(this.dataSources, dataSources)) return false;
+        this.dataSources = dataSources ?? {};
+        return true;
+    }
+
     reset() {
         this.collectionsByTableName.clear();
         this.collectionsBySlug.clear();
@@ -163,12 +213,24 @@ export class CollectionRegistry {
         // and for preventing mutation of module-level collection singletons.
         const result = { ...collection } as EntityCollection;
 
+        // 0. Resolve and stamp `dataSource` and `engine` on the normalized copy.
+        //    After this block every normalized collection has both fields set,
+        //    so downstream code can read them directly without calling
+        //    `resolveDataSource()`.  Only the normalized layer is affected —
+        //    the raw layer used by the collection editor keeps the author's
+        //    original fields.
+        {
+            const resolved = resolveDataSource(result, this.dataSources);
+            if (!result.dataSource) (result as { dataSource?: string }).dataSource = resolved.key;
+            if (!result.engine) (result as { engine?: string }).engine = resolved.engine;
+        }
+
         // 1. Extract relations from properties that have inline config (target set)
         const extractedRelations = this.extractRelationsFromProperties(result.properties);
 
         // 2. Merge with manual relations[] (manual entries win on name conflict)
-        const relResult = result as CollectionWithRelations;
-        const manualRelations = getDataSourceCapabilities(result.driver).supportsRelations ? (relResult.relations ?? []) : [];
+        const relResult = result;
+        const manualRelations = getDataSourceCapabilities(result.engine).supportsRelations ? (relResult.relations ?? []) : [];
         const mergedRelationsRaw = [...extractedRelations];
         for (const manual of manualRelations) {
             const name = manual.relationName;
@@ -194,7 +256,7 @@ export class CollectionRegistry {
         //     foreignKeyOnTarget, etc.) are populated. Without this the
         //     property.relation stamp is missing junction-table metadata and
         //     the backend cannot fetch many-to-many data.
-        if (getDataSourceCapabilities(result.driver).supportsRelations) {
+        if (getDataSourceCapabilities(result.engine).supportsRelations) {
             mergedRelations = mergedRelationsRaw.map(r => {
                 try {
                     return sanitizeRelation(r, result, (slug) => this.get(slug));
@@ -211,13 +273,15 @@ export class CollectionRegistry {
 
         // 4. Normalize properties (which stamps relation on each property)
         const properties: Properties = this.normalizeProperties(result.properties, mergedRelations);
-        result.properties = properties;
+        result.properties = properties as EngineProperties;
 
         // Populate childCollections from driver-specific fields
         if (!result.childCollections) {
-            if (getDataSourceCapabilities(result.driver).supportsSubcollections && (result as CollectionWithSubcollections).subcollections) {
-                result.childCollections = (result as CollectionWithSubcollections).subcollections;
-            } else if (getDataSourceCapabilities(result.driver).supportsRelations && relResult.relations) {
+            const capabilities = getDataSourceCapabilities(result.engine);
+            const declaredSubcollections = getDeclaredSubcollections(result);
+            if (capabilities.supportsSubcollections && declaredSubcollections) {
+                result.childCollections = declaredSubcollections;
+            } else if (capabilities.supportsRelations && relResult.relations) {
                 const manyRelations = relResult.relations.filter((r: Relation) => r.cardinality === "many");
                 if (manyRelations.length > 0) {
                     result.childCollections = () => manyRelations.map((r: Relation) => {
@@ -378,8 +442,8 @@ export class CollectionRegistry {
             const relationKey = pathSegments[i];
 
             // Get relations for current collection
-            if (!getDataSourceCapabilities(currentCollection.driver).supportsRelations) {
-                throw new Error(`Relation path navigation requires a collection that supports relations, but '${currentCollection.slug}' uses driver '${currentCollection.driver}'`);
+            if (!getDataSourceCapabilities(currentCollection.engine).supportsRelations) {
+                throw new Error(`Relation path navigation requires a collection that supports relations, but '${currentCollection.slug}' uses engine '${currentCollection.engine}'`);
             }
             const resolvedRelations = resolveCollectionRelations(currentCollection);
             const relation = findRelation(resolvedRelations, relationKey);

package/src/collections/default-collections.ts

@@ -1,4 +1,4 @@
-import type { PostgresCollection } from "@rebasepro/types";
+import { defineCollection } from "../util/builders";
 
 /**
  * Default users collection.
@@ -7,7 +7,7 @@ import type { PostgresCollection } from "@rebasepro/types";
  * Slug-based dedup (Map keyed by slug, last-write-wins) lets developers
  * override by defining their own collection with `slug: "users"`.
  */
-export const defaultUsersCollection: PostgresCollection = {
+export const defaultUsersCollection = defineCollection({
     name: "Users",
     singularName: "User",
     slug: "users",
@@ -48,7 +48,7 @@ unique: true }
             name: "Photo URL",
             type: "string",
             columnName: "photo_url",
-            url: "image"
+            ui: { url: "image" }
         },
         roles: {
             name: "Roles",
@@ -120,4 +120,4 @@ disabled: { hidden: true } }
     },
     listProperties: ["displayName", "email", "roles", "createdAt"],
     propertiesOrder: ["id", "email", "displayName", "roles", "createdAt"]
-};
+});