@rebasepro/common 0.6.0 → 0.7.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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,6 +29,14 @@
     "headless cms",
     "content manager"
   ],
+  "scripts": {
+    "watch": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "test:lint": "eslint \"src/**\" --quiet",
+    "test": "jest --passWithNoTests",
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
+    "generateIcons": "ts-node --esm src/icons/generateIcons.ts"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,10 +47,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@rebasepro/types": "workspace:*",
+    "@rebasepro/utils": "workspace:*",
     "fast-equals": "6.0.0",
-    "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.6.0",
-    "@rebasepro/utils": "0.6.0"
+    "json-logic-js": "^2.0.5"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -97,13 +105,5 @@
       "^@rebasepro/types$": "<rootDir>/../types/src/index.ts",
       "^@rebasepro/utils$": "<rootDir>/../utils/src/index.ts"
     }
-  },
-  "scripts": {
-    "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
-    "test:lint": "eslint \"src/**\" --quiet",
-    "test": "jest --passWithNoTests",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
-    "generateIcons": "ts-node --esm src/icons/generateIcons.ts"
   }
-}
+}

package/src/collections/CollectionRegistry.ts

@@ -15,9 +15,17 @@ import { deepEqual } from "fast-equals";
 
 import { enumToObjectEntries, getSubcollections, getTableName, resolveCollectionRelations, findRelation, sanitizeRelation } from "../util";
 import { removeFunctions, mergeDeep, deepClone } from "@rebasepro/utils";
+import { resolveDataSource, DataSourceRegistry } 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 → behaviour keys off `driver` as before.
+     */
+    private dataSources: DataSourceRegistry = {};
+
     // Normalized runtime layer (used by Data Grid / UI)
     private collectionsByTableName = new Map<string, EntityCollection>();
     private collectionsBySlug = new Map<string, EntityCollection>();
@@ -34,12 +42,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,6 +183,19 @@ export class CollectionRegistry {
         // and for preventing mutation of module-level collection singletons.
         const result = { ...collection } as EntityCollection;
 
+        // 0. For `dataSource`-only collections (no explicit `driver`), resolve
+        //    the engine from the data-source registry and stamp it as `driver`
+        //    on the normalized copy, so downstream capability lookups (which
+        //    read `driver`) are correct. Surgical on purpose: collections that
+        //    already set `driver`, and plain default collections (no driver,
+        //    no dataSource), are left untouched. Only the normalized layer is
+        //    affected — the raw layer used by the collection editor keeps the
+        //    author's original fields.
+        if (result.dataSource && !result.driver) {
+            const engine = resolveDataSource(result, this.dataSources).engine;
+            if (engine) (result as { driver?: string }).driver = engine;
+        }
+
         // 1. Extract relations from properties that have inline config (target set)
         const extractedRelations = this.extractRelationsFromProperties(result.properties);
 

package/src/data/buildRoutedRebaseData.ts

@@ -0,0 +1,97 @@
+import { RebaseData, CollectionAccessor } from "@rebasepro/types";
+import { toSnakeCase } from "@rebasepro/utils";
+
+/**
+ * Parameters for {@link buildRoutedRebaseData}.
+ */
+export interface RoutedRebaseDataParams {
+    /**
+     * The default data source. Handles every collection that does not
+     * resolve to an entry in `sources` (i.e. server-transport collections,
+     * which ride the Rebase client).
+     */
+    defaultData: RebaseData;
+
+    /**
+     * Per-data-source {@link RebaseData} instances for direct and custom
+     * transports, keyed by data-source key (e.g. `"analytics"`). Server-
+     * mediated sources are not listed here — they fall through to
+     * `defaultData`.
+     */
+    sources: Record<string, RebaseData>;
+
+    /**
+     * Resolve the data-source key for a given collection slug or path.
+     * Typically backed by the collection registry + `resolveDataSource`
+     * (`resolveDataSource(registry.getCollection(path), defs).key`).
+     *
+     * Return `undefined` (or a key absent from `sources`) to route to the
+     * default data source.
+     */
+    resolveKey: (slugOrPath: string) => string | undefined;
+}
+
+/**
+ * Build a {@link RebaseData} that routes each collection to the right
+ * backend based on its resolved data source.
+ *
+ * `.collection(path)` (and dynamic `data.products`-style access) resolves the
+ * collection's data-source key via `resolveKey` and delegates to the matching
+ * entry in `sources`, falling back to `defaultData` when there is no match.
+ * Because routing keys off the *path being accessed*, a reference widget
+ * inside a Firestore form that points at a Postgres collection is still
+ * served by Postgres — routing follows the target, not the ancestor.
+ *
+ * When `sources` is empty this returns `defaultData` untouched, so the
+ * single-driver setup keeps identical behaviour and identity (important for
+ * effect dependencies that key off the data instance).
+ *
+ * @example
+ * const data = buildRoutedRebaseData({
+ *     defaultData: client.data,
+ *     sources: { analytics: buildRebaseData(firestoreDriver) },
+ *     resolveKey: (path) => resolveDataSource(registry.getCollection(path), defs).key
+ * });
+ * await data.products.find();        // → default (server / Postgres)
+ * await data.events.find();          // → Firestore, if `events.dataSource === "analytics"`
+ */
+export function buildRoutedRebaseData({
+    defaultData,
+    sources,
+    resolveKey
+}: RoutedRebaseDataParams): RebaseData {
+
+    // Fast path: nothing to route → return the default untouched (preserves
+    // referential identity for effect dependencies).
+    if (!sources || Object.keys(sources).length === 0) {
+        return defaultData;
+    }
+
+    function resolve(slugOrPath: string): RebaseData {
+        const key = resolveKey(slugOrPath);
+        if (key && sources[key]) return sources[key];
+        return defaultData;
+    }
+
+    function getAccessor(slugOrPath: string): CollectionAccessor {
+        return resolve(slugOrPath).collection(slugOrPath);
+    }
+
+    const target = {
+        collection: getAccessor
+    } as RebaseData;
+
+    return new Proxy(target, {
+        get(_target, prop: string | symbol) {
+            if (prop === "collection") return getAccessor;
+            // Ignore Symbol properties (e.g. Symbol.toPrimitive, Symbol.iterator)
+            if (typeof prop === "symbol") return undefined;
+            // Ignore internal JS properties
+            if (prop === "then" || prop === "toJSON" || prop === "$$typeof") return undefined;
+
+            // Convert camelCase property names to snake_case slugs, mirroring
+            // buildRebaseData so dynamic access routes consistently.
+            return getAccessor(toSnakeCase(prop));
+        }
+    });
+}

package/src/data/resolveDataSource.ts

@@ -0,0 +1,79 @@
+import {
+    DataSourceDefinition,
+    ResolvedDataSource,
+    DEFAULT_DATA_SOURCE_KEY,
+    getDataSourceCapabilities
+} from "@rebasepro/types";
+
+/**
+ * The subset of a collection needed to resolve its data source. Accepting a
+ * structural type (rather than the full `EntityCollection`) keeps this usable
+ * from anywhere — frontend router, backend registry, editor — without coupling
+ * to the collection union.
+ */
+export interface DataSourceResolvable {
+    /** Preferred routing key. */
+    dataSource?: string;
+    /** Legacy engine hint / fallback routing key. */
+    driver?: string;
+    /** Within-engine instance. */
+    databaseId?: string;
+}
+
+/** A lookup of data-source definitions by key. */
+export type DataSourceRegistry = Record<string, DataSourceDefinition>;
+
+/**
+ * Build a keyed registry from a list of {@link DataSourceDefinition}s.
+ * Later entries win on key collision.
+ */
+export function createDataSourceRegistry(definitions?: DataSourceDefinition[]): DataSourceRegistry {
+    const registry: DataSourceRegistry = {};
+    for (const def of definitions ?? []) {
+        registry[def.key] = def;
+    }
+    return registry;
+}
+
+/**
+ * Resolve the effective data source for a collection — the single source of
+ * truth shared by the frontend router, the backend driver registry, and the
+ * editor's capability lookups.
+ *
+ * Resolution order:
+ * 1. The routing **key** is `collection.dataSource`, else the legacy
+ *    `collection.driver`, else {@link DEFAULT_DATA_SOURCE_KEY}.
+ * 2. If a definition is registered for that key, it provides `engine`,
+ *    `transport`, and `databaseId`.
+ * 3. Otherwise values are synthesized for backward compatibility: `engine`
+ *    from the legacy `driver` (or the key, or `"postgres"`), `transport`
+ *    defaults to `"server"`, and `databaseId` from the collection.
+ *
+ * `capabilities` are always derived from the resolved `engine`, so two
+ * data sources sharing an engine share capabilities.
+ *
+ * @param collection the collection (or any object carrying the routing fields)
+ * @param registry   optional registry of declared data sources
+ */
+export function resolveDataSource(
+    collection: DataSourceResolvable | undefined,
+    registry?: DataSourceRegistry
+): ResolvedDataSource {
+    const key = collection?.dataSource ?? collection?.driver ?? DEFAULT_DATA_SOURCE_KEY;
+    const def = registry?.[key];
+
+    const engine = def?.engine
+        ?? collection?.driver
+        ?? (key !== DEFAULT_DATA_SOURCE_KEY ? key : "postgres");
+
+    const transport = def?.transport ?? "server";
+    const databaseId = collection?.databaseId ?? def?.databaseId;
+
+    return {
+        key,
+        engine,
+        transport,
+        databaseId,
+        capabilities: getDataSourceCapabilities(engine)
+    };
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export * from "./util";
 export * from "./collections";
 export * from "./data/buildRebaseData";
+export * from "./data/buildRoutedRebaseData";
+export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
-
+export * from "./table-classification";

package/src/table-classification.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 const REBASE_INTERNAL_SCHEMAS: readonly string[] = ["rebase", "auth"];
+
+/** Table-name prefixes that mark a table as Rebase-internal regardless of schema. */
+export const REBASE_INTERNAL_PREFIXES: readonly string[] = [
+  "_rebase_",
+  "_auth_",
+  "drizzle_",
+];
+
+/**
+ * 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 function classifyTable(
+  tableName: string,
+  schemaName: string,
+): TableCategory {
+  if (
+    REBASE_INTERNAL_SCHEMAS.includes(schemaName) ||
+    REBASE_INTERNAL_PREFIXES.some((prefix) => tableName.startsWith(prefix))
+  ) {
+    return "rebase-internal";
+  }
+
+  return "user";
+}
+
+/**
+ * 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 function isRebaseInternalTable(
+  tableName: string,
+  schemaName: string,
+): boolean {
+  return classifyTable(tableName, schemaName) === "rebase-internal";
+}
+
+/** SQL query that detects junction tables in the `public` schema. */
+export const JUNCTION_TABLES_SQL = `
+  SELECT t.table_name
+  FROM information_schema.tables t
+  WHERE t.table_schema = 'public'
+    AND t.table_type = 'BASE TABLE'
+    AND NOT EXISTS (
+      SELECT 1
+      FROM information_schema.columns c
+      WHERE c.table_schema = t.table_schema
+        AND c.table_name = t.table_name
+        AND c.column_name NOT IN (
+          SELECT kcu.column_name
+          FROM information_schema.key_column_usage kcu
+          JOIN information_schema.table_constraints tc
+            ON tc.constraint_name = kcu.constraint_name
+            AND tc.table_schema = kcu.table_schema
+          WHERE tc.constraint_type = 'FOREIGN KEY'
+            AND kcu.table_schema = t.table_schema
+            AND kcu.table_name = t.table_name
+        )
+    )
+`;
+
+/**
+ * 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 async function detectJunctionTables(
+  executeSql: (sql: string) => Promise<Record<string, unknown>[]>,
+): Promise<Set<string>> {
+  const rows = await executeSql(JUNCTION_TABLES_SQL);
+  const junctionTables = new Set<string>();
+
+  for (const row of rows) {
+    if (typeof row.table_name === "string") {
+      junctionTables.add(row.table_name);
+    }
+  }
+
+  return junctionTables;
+}