@rebasepro/common 0.6.1 → 0.8.0

package/dist/collections/CollectionRegistry.d.ts

@@ -1,5 +1,27 @@
-import { EntityCollection } from "@rebasepro/types";
+import { EntityCallbacks, EntityCollection } from "@rebasepro/types";
+import { DataSourceRegistry } from "../data/resolveDataSource";
 export declare 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;
+    /**
+     * 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: EntityCallbacks): void;
+    /**
+     * Get the currently registered global callbacks, if any.
+     */
+    getGlobalCallbacks(): EntityCallbacks | undefined;
     private collectionsByTableName;
     private collectionsBySlug;
     private rootCollections;
@@ -9,7 +31,13 @@ export declare class CollectionRegistry {
     private rawRootCollections;
     private cachedRawCollectionsList;
     private lastRawInputSnapshot;
-    constructor(collections?: EntityCollection[]);
+    constructor(collections?: EntityCollection[], 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.

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

@@ -1,4 +1,3 @@
-import type { PostgresCollection } from "@rebasepro/types";
 /**
  * Default users collection.
  *
@@ -6,4 +5,258 @@ 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 declare const defaultUsersCollection: PostgresCollection;
+export declare const defaultUsersCollection: import("@rebasepro/types").PostgresCollection<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/data/buildRoutedRebaseData.d.ts

@@ -0,0 +1,53 @@
+import { RebaseData } from "@rebasepro/types";
+/**
+ * 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 declare function buildRoutedRebaseData({ defaultData, sources, resolveKey }: RoutedRebaseDataParams): RebaseData;

package/dist/data/filter-dialect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * REST wire-format adapter for the unified filter system.
+ *
+ * This module is the ONLY code in the entire codebase that knows about
+ * PostgREST-style dot-syntax strings (`eq.active`, `gt.18`, `in.(a,b)`).
+ * Everything else speaks `FilterValues` exclusively.
+ *
+ * @module
+ */
+import { FilterValues, LogicalCondition, FilterCondition } from "@rebasepro/types";
+/**
+ * Convert `FilterValues` to a PostgREST-style querystring record.
+ *
+ * - Single conditions produce a string value.
+ * - Multiple conditions on the same field produce a string array (repeated params).
+ *
+ * @example
+ * serializeFilter({ status: ["==", "active"] })
+ * // → { status: "eq.active" }
+ *
+ * serializeFilter({ age: [[">=", 18], ["<", 65]] })
+ * // → { age: ["gte.18", "lt.65"] }
+ */
+export declare function serializeFilter(filter: FilterValues<string> | Record<string, any>): Record<string, string | string[]>;
+/**
+ * Convert a PostgREST-style querystring record to `FilterValues`.
+ *
+ * - String values are parsed as single conditions.
+ * - String arrays (repeated query params) become multiple conditions on the same field.
+ *
+ * @example
+ * deserializeFilter({ status: "eq.active" })
+ * // → { status: ["==", "active"] }
+ *
+ * deserializeFilter({ age: ["gte.18", "lt.65"] })
+ * // → { age: [[">=", 18], ["<", 65]] }
+ */
+export declare function deserializeFilter(query: Record<string, any>): FilterValues<string>;
+/**
+ * Serialize a `LogicalCondition` or `FilterCondition` to its wire-format string.
+ *
+ * @example
+ * serializeLogicalCondition({ column: "status", operator: "==", value: "active" })
+ * // → "status.eq.active"
+ *
+ * serializeLogicalCondition({ type: "or", conditions: [...] })
+ * // → "or(status.eq.active,status.eq.pending)"
+ */
+export declare function serializeLogicalCondition(cond: LogicalCondition | FilterCondition): string;
+/**
+ * Parse a logical condition wire-format string back into a
+ * `LogicalCondition` or `FilterCondition`.
+ *
+ * @example
+ * deserializeLogicalCondition("status.eq.active")
+ * // → { column: "status", operator: "==", value: "active" }
+ *
+ * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
+ * // → { type: "or", conditions: [...] }
+ */
+export declare function deserializeLogicalCondition(str: string): LogicalCondition | FilterCondition;

package/dist/data/query_builder.d.ts

@@ -1,7 +1,7 @@
-import { FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+import { FindResponse, CollectionAccessor, QueryBuilderInterface, WhereFilterOp, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
 export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
-export declare function cond(column: string, operator: FilterOperator, value: unknown): FilterCondition;
+export declare function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition;
 export declare class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {
     private collection;
     private params;
@@ -11,14 +11,14 @@ export declare class QueryBuilder<M extends Record<string, unknown> = Record<str
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     /**
      * Order the results by a specific column.
      * @example
      * client.collection('users').orderBy('createdAt', 'desc').find()
      */
-    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): this;
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
     /**
      * Limit the number of results returned.
      */

package/dist/data/resolveDataSource.d.ts

@@ -0,0 +1,43 @@
+import { DataSourceDefinition, ResolvedDataSource } 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;
+    /** Engine type discriminant (set on variant collection types). */
+    engine?: 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 declare function createDataSourceRegistry(definitions?: DataSourceDefinition[]): DataSourceRegistry;
+/**
+ * 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
+ *    {@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: `engine` from `collection.engine`
+ *    (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 declare function resolveDataSource(collection: DataSourceResolvable | undefined, registry?: DataSourceRegistry): ResolvedDataSource;

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 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 "./data/filter-dialect";
+export * from "./table-classification";