@rebasepro/common 0.7.0 → 0.9.0

package/src/collections/CollectionRegistry.ts

@@ -1,48 +1,78 @@
 import {
     ArrayProperty,
-    CollectionWithRelations,
-    CollectionWithSubcollections,
-    EntityCollection,
+    CollectionCallbacks,
+    EngineProperties,
+    CollectionConfig,
+    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 { resolveDataSource, DataSourceRegistry } from "../data/resolveDataSource";
+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 → behaviour keys off `driver` as before.
+     * 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?: CollectionCallbacks;
+
+    /**
+     * Set global lifecycle callbacks that apply to every collection.
+     * Typically called once during backend initialization.
+     */
+    setGlobalCallbacks(callbacks: CollectionCallbacks): void {
+        this._globalCallbacks = callbacks;
+    }
+
+    /**
+     * Get the currently registered global callbacks, if any.
+     */
+    getGlobalCallbacks(): CollectionCallbacks | undefined {
+        return this._globalCallbacks;
+    }
+
     // Normalized runtime layer (used by Data Grid / UI)
-    private collectionsByTableName = new Map<string, EntityCollection>();
-    private collectionsBySlug = new Map<string, EntityCollection>();
-    private rootCollections: EntityCollection[] = [];
-    private cachedCollectionsList: EntityCollection[] | null = null;
+    private collectionsByTableName = new Map<string, CollectionConfig>();
+    private collectionsBySlug = new Map<string, CollectionConfig>();
+    private rootCollections: CollectionConfig[] = [];
+    private cachedCollectionsList: CollectionConfig[] | null = null;
 
     // Raw configuration layer (used by Collection Editor AST generator)
-    private rawCollectionsByTableName = new Map<string, EntityCollection>();
-    private rawCollectionsBySlug = new Map<string, EntityCollection>();
-    private rawRootCollections: EntityCollection[] = [];
-    private cachedRawCollectionsList: EntityCollection[] | null = null;
+    private rawCollectionsByTableName = new Map<string, CollectionConfig>();
+    private rawCollectionsBySlug = new Map<string, CollectionConfig>();
+    private rawRootCollections: CollectionConfig[] = [];
+    private cachedRawCollectionsList: CollectionConfig[] | null = null;
 
-    // Snapshot of raw input for idempotency check — compared BEFORE normalization
+    // Entity of raw input for idempotency check — compared BEFORE normalization
     // to avoid the issue where normalization creates new objects that always fail equality.
-    private lastRawInputSnapshot: ReturnType<typeof removeFunctions>[] | null = null;
+    private lastRawInputEntity: ReturnType<typeof removeFunctions>[] | null = null;
 
-    constructor(collections?: EntityCollection[], dataSources?: DataSourceRegistry) {
+    constructor(collections?: CollectionConfig[], dataSources?: DataSourceRegistry) {
         if (dataSources) this.dataSources = dataSources;
         if (collections) {
             this.registerMultiple(collections);
@@ -77,15 +107,15 @@ export class CollectionRegistry {
      * 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 {
+    registerMultiple(collections: CollectionConfig[]): boolean {
         // Compare raw input BEFORE normalization to detect actual changes.
         // This avoids the old issue where normalization creates new objects
         // that always fail deep-equal even when the source data is identical.
-        const rawSnapshot = collections.map(c => removeFunctions(c));
-        if (this.lastRawInputSnapshot && deepEqual(this.lastRawInputSnapshot, rawSnapshot)) {
+        const rawEntity = collections.map(c => removeFunctions(c));
+        if (this.lastRawInputEntity && deepEqual(this.lastRawInputEntity, rawEntity)) {
             return false;
         }
 
@@ -133,13 +163,13 @@ export class CollectionRegistry {
             }
         });
 
-        // Store the snapshot for future comparisons
-        this.lastRawInputSnapshot = rawSnapshot;
+        // Store the entity for future comparisons
+        this.lastRawInputEntity = rawEntity;
 
         return true;
     }
 
-    register(collection: EntityCollection, rawCollection?: EntityCollection) {
+    register(collection: CollectionConfig, rawCollection?: CollectionConfig) {
         const raw = rawCollection ? deepClone(rawCollection) : deepClone(collection);
 
         this.rootCollections.push(collection);
@@ -148,7 +178,7 @@ export class CollectionRegistry {
         this._registerRecursively(collection, raw);
     }
 
-    private _registerRecursively(collection: EntityCollection, rawCollection: EntityCollection) {
+    private _registerRecursively(collection: CollectionConfig, rawCollection: CollectionConfig) {
         if (this.collectionsByTableName.has(getTableName(collection))) {
             return;
         }
@@ -177,31 +207,30 @@ export class CollectionRegistry {
         }
     }
 
-    public normalizeCollection(collection: EntityCollection): EntityCollection {
+    public normalizeCollection(collection: CollectionConfig): CollectionConfig {
         // Work on a shallow copy to avoid mutating the caller's reference.
         // This is critical for idempotency (the raw input must not be changed)
         // 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;
+        const result = { ...collection } as CollectionConfig;
+
+        // 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;
@@ -227,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));
@@ -244,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) => {
@@ -347,7 +378,7 @@ export class CollectionRegistry {
         return newProperty;
     }
 
-    get(path: string): EntityCollection | undefined {
+    get(path: string): CollectionConfig | undefined {
         // First try slug lookup
         const bySlug = this.collectionsBySlug.get(path);
         if (bySlug) return bySlug;
@@ -367,7 +398,7 @@ export class CollectionRegistry {
      * 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 {
         const bySlug = this.rawCollectionsBySlug.get(path);
         if (bySlug) return bySlug;
 
@@ -385,7 +416,7 @@ export class CollectionRegistry {
      * Get collection by resolving multi-segment paths through relations
      * e.g., "authors/70/posts" resolves to the posts collection
      */
-    getCollectionByPath(collectionPath: string): EntityCollection | undefined {
+    getCollectionByPath(collectionPath: string): CollectionConfig | undefined {
         // Handle simple single collection path
         if (!collectionPath.includes("/")) {
             return this.get(collectionPath);
@@ -411,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);
@@ -436,14 +467,14 @@ export class CollectionRegistry {
         return currentCollection;
     }
 
-    getCollections(): EntityCollection[] {
+    getCollections(): CollectionConfig[] {
         if (!this.cachedCollectionsList) {
             this.cachedCollectionsList = Array.from(this.collectionsByTableName.values());
         }
         return this.cachedCollectionsList;
     }
 
-    getRawCollections(): EntityCollection[] {
+    getRawCollections(): CollectionConfig[] {
         if (!this.cachedRawCollectionsList) {
             this.cachedRawCollectionsList = Array.from(this.rawCollectionsByTableName.values());
         }
@@ -455,9 +486,9 @@ export class CollectionRegistry {
      * information about the collections and entity IDs along the path
      */
     resolvePathToCollections(path: string): {
-        collections: EntityCollection[],
+        collections: CollectionConfig[],
         entityIds: (string | number)[],
-        finalCollection: EntityCollection
+        finalCollection: CollectionConfig
     } {
         const pathSegments = path.split("/").filter(p => p);
 
@@ -469,7 +500,7 @@ export class CollectionRegistry {
             throw new Error(`Invalid collection path: ${path}. It must have an odd number of segments.`);
         }
 
-        const collections: EntityCollection[] = [];
+        const collections: CollectionConfig[] = [];
         const entityIds: (string | number)[] = [];
 
         // Start with the first collection
@@ -488,12 +519,12 @@ export class CollectionRegistry {
 
             if (i + 1 < pathSegments.length) {
                 const subcollectionSlug = pathSegments[i + 1];
-                const subcollections: EntityCollection[] | undefined = getSubcollections(currentCollection);
+                const subcollections: CollectionConfig[] | undefined = getSubcollections(currentCollection);
                 if (!subcollections || subcollections.length === 0) {
                     throw new Error(`No subcollections found for ${currentCollection.slug} in path: ${path}`);
                 }
 
-                const subcollection: EntityCollection | undefined = subcollections.find(c => c.slug === subcollectionSlug);
+                const subcollection: CollectionConfig | undefined = subcollections.find(c => c.slug === subcollectionSlug);
                 if (!subcollection) {
                     throw new Error(`Subcollection '${subcollectionSlug}' not found in ${currentCollection.slug}`);
                 }

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"]
-};
+});