@rebasepro/client-postgresql 0.4.0 → 0.5.0

package/README.md

@@ -1,106 +1,74 @@
-# @rebasepro/postgresql
+# @rebasepro/client-postgresql
 
-PostgreSQL data source client for Rebase with real-time WebSocket connectivity.
-
-This package provides a complete client-side implementation for connecting Rebase applications to PostgreSQL backends, featuring real-time synchronization via WebSockets.
+PostgreSQL data source client for Rebase — connects the Rebase admin panel to a PostgreSQL backend via WebSocket.
 
 ## Installation
 
 ```bash
-npm install @rebasepro/postgresql @rebasepro/core
+pnpm add @rebasepro/client-postgresql
 ```
 
-## Usage
+**Peer dependencies:** `react >= 19.0.0`, `react-dom >= 19.0.0`
 
-### Basic Setup with React Hook
+## What This Package Does
 
-```typescript
-import { usePostgresDataSource } from "@rebasepro/postgresql";
-import { Rebase } from "@rebasepro/core";
+This package provides a `DataDriver` implementation that bridges Rebase's data layer to a PostgreSQL backend through `@rebasepro/client`'s WebSocket client. It supports full CRUD, realtime collection/entity listeners, unique field validation, entity counting, and admin operations (SQL execution, branch management, table introspection).
 
-function App() {
-    const dataSource = usePostgresDataSource({
-        baseUrl: "http://localhost:3001",
-        websocketUrl: "ws://localhost:3001", // Optional, will be inferred from baseUrl
-        headers: { // Optional
-            "Authorization": "Bearer your-token"
-        }
-    });
+## Key Exports
 
-    return (
-        <Rebase
-            dataSource={dataSource}
-            collections={collections}
-            // ... other props
-        />
-    );
-}
-```
+| Export | Type | Description |
+|---|---|---|
+| `usePostgresClientDriver` | Hook | Creates a `PostgresDataDriver` from a `RebaseWebSocketClient` |
+| `PostgresDataDriverConfig` | Type | Config object: `{ wsClient: RebaseWebSocketClient }` |
+| `PostgresDataDriver` | Type | Extends `DataDriver` with a `client` reference and `admin` methods |
 
-### Creating Data Source Directly
+### `PostgresDataDriver` Methods
 
-```typescript
-import { createPostgresDataSource } from "@rebasepro/postgresql";
+| Method | Description |
+|---|---|
+| `fetchCollection(props)` | Fetch a list of entities with filtering, sorting, pagination, and search |
+| `fetchEntity(props)` | Fetch a single entity by path and ID |
+| `saveEntity(props)` | Create or update an entity |
+| `deleteEntity(props)` | Delete an entity |
+| `checkUniqueField(path, name, value, entityId?, collection?)` | Check if a field value is unique |
+| `countEntities(props)` | Count entities matching filter criteria |
+| `listenCollection(props)` | Subscribe to realtime collection updates. Returns an unsubscribe function |
+| `listenEntity(props)` | Subscribe to realtime entity updates. Returns an unsubscribe function |
+| `isFilterCombinationValid()` | Always returns `true` — PostgreSQL supports complex filter combinations |
 
-const dataSource = createPostgresDataSource({
-    baseUrl: "http://localhost:3001",
-    websocketUrl: "ws://localhost:3001"
-});
-```
+### Admin Methods (`driver.admin`)
 
-## Features
+| Method | Description |
+|---|---|
+| `executeSql(sql, options?)` | Execute raw SQL. Options: `{ database?, role? }` |
+| `fetchAvailableDatabases()` | List available databases |
+| `fetchAvailableRoles()` | List available roles |
+| `fetchCurrentDatabase()` | Get the current database name |
+| `fetchUnmappedTables(mappedPaths?)` | Find tables not yet mapped to collections |
+| `fetchTableMetadata(tableName)` | Get column/constraint metadata for a table |
+| `createBranch(name, options?)` | Create a database branch. Options: `{ source? }` |
+| `deleteBranch(name)` | Delete a database branch |
+| `listBranches()` | List all branches |
 
-- **Real-time Synchronization**: WebSocket-based real-time updates for collections and entities
-- **Automatic Reconnection**: Built-in reconnection logic with exponential backoff
-- **Type Safety**: Full TypeScript support with Rebase core types
-- **Error Handling**: Comprehensive error handling with custom error types
-- **Connection Management**: Connection status monitoring and queue management
+## Quick Start
 
-## API
+```tsx
+import { usePostgresClientDriver } from "@rebasepro/client-postgresql";
+import { RebaseWebSocketClient } from "@rebasepro/client";
 
-### Configuration
+const wsClient = new RebaseWebSocketClient({ url: "ws://localhost:4100" });
 
-```typescript
-interface PostgresDataSourceConfig {
-    baseUrl: string;           // Backend server URL
-    websocketUrl?: string;     // WebSocket URL (optional)
-    headers?: Record<string, string>; // Custom headers (optional)
+function App() {
+    const driver = usePostgresClientDriver({ wsClient });
+
+    // Pass to your Rebase app as the data driver
+    return (
+        <Rebase driver={driver} /* ...other props */ />
+    );
 }
 ```
 
-### Methods
-
-The PostgreSQL data source implements all Rebase `DataSource` methods:
-
-- `fetchCollection<M>(props): Promise<Entity<M>[]>`
-- `fetchEntity<M>(props): Promise<Entity<M> | undefined>`
-- `saveEntity<M>(props): Promise<Entity<M>>`
-- `deleteEntity<M>(props): Promise<void>`
-- `checkUniqueField(...): Promise<boolean>`
-- `generateEntityId(...): string`
-- `countEntities<M>(props): Promise<number>`
-- `listenCollection<M>(props): () => void`
-- `listenEntity<M>(props): () => void`
-
-## Backend Requirements
-
-This client expects a WebSocket-enabled backend that handles the following message types:
-
-- `FETCH_COLLECTION`
-- `FETCH_ENTITY`
-- `SAVE_ENTITY`
-- `DELETE_ENTITY`
-- `CHECK_UNIQUE_FIELD`
-- `GENERATE_ENTITY_ID`
-- `COUNT_ENTITIES`
-- `subscribe_collection`
-- `subscribe_entity`
-- `unsubscribe`
-
-## Development
-
-This package is part of the Rebase monorepo. For development instructions, see the main repository README.
-
-## License
+## Related Packages
 
-MIT
+- `@rebasepro/client` — Provides `RebaseWebSocketClient` used for communication
+- `@rebasepro/types` — Shared types (`DataDriver`, `Entity`, `EntityCollection`, etc.)

package/dist/types/src/types/backend.d.ts

@@ -1,5 +1,6 @@
 import type { Entity } from "./entities";
 import type { EntityCollection, FilterValues, WhereFilterOp } from "./collections";
+import type { AuthAdapter } from "./auth_adapter";
 /**
  * Abstract database connection interface.
  * Represents a connection to any database system.
@@ -182,6 +183,24 @@ export interface RealtimeProvider {
      * Notify all relevant subscribers of an entity update
      */
     notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string): Promise<void>;
+    /**
+     * Called when the HTTP server is ready and listening.
+     * Useful for providers that need the server address for callbacks.
+     */
+    onServerReady?(serverInfo: {
+        port: number;
+        hostname?: string;
+    }): void;
+    /**
+     * Gracefully shut down the realtime provider.
+     * Called during server shutdown to clean up resources.
+     */
+    destroy?(): Promise<void>;
+    /**
+     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).
+     * Called during graceful shutdown before closing database connections.
+     */
+    stopListening?(): Promise<void>;
 }
 /**
  * Abstract collection registry interface.
@@ -464,6 +483,22 @@ export interface BackendBootstrapper {
      * (e.g., `"postgres"`, `"mongodb"`, `"mysql"`).
      */
     type: string;
+    /**
+     * Unique identifier for this bootstrapper instance.
+     * Used to register the driver in the driver registry.
+     * Defaults to `type` if not set.
+     */
+    id?: string;
+    /**
+     * Whether this bootstrapper provides the default driver.
+     * When true, the coordinator uses this driver as the primary one.
+     */
+    isDefault?: boolean;
+    /**
+     * Run database migrations for this driver.
+     * Called by the coordinator after all drivers are initialized.
+     */
+    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;
     /**
      * Create a DataDriver from the given config.
      * This is the only **required** method.
@@ -498,7 +533,7 @@ export interface BackendBootstrapper {
     /**
      * Initialize WebSocket server for realtime operations.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;
 }
 /**
  * Result of `BackendBootstrapper.initializeDriver()`.

package/dist/types/src/types/collections.d.ts

@@ -343,6 +343,23 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * Builder for the collection actions rendered in the toolbar
      */
     Actions?: ComponentRef<CollectionActionsProps>[];
+    /**
+     * The database table name for this collection.
+     * Automatically set for PostgreSQL collections.
+     * For non-SQL backends, this may be undefined.
+     */
+    table?: string;
+    /**
+     * Relations defined for this collection.
+     * Populated at normalization time from inline relation properties
+     * or explicit relation definitions.
+     */
+    relations?: Relation[];
+    /**
+     * Security rules for this collection (Row Level Security).
+     * When defined, the backend enforces access control policies.
+     */
+    securityRules?: SecurityRule[];
 }
 /**
  * A collection backed by PostgreSQL (or any SQL database).
@@ -436,7 +453,10 @@ export interface MongoDBCollection<M extends Record<string, unknown> = Record<st
  * @group Models
  */
 export type EntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = PostgresCollection<M, USER> | FirebaseCollection<M, USER> | MongoDBCollection<M, USER>;
-/** An EntityCollection that supports SQL-style relations (e.g. Postgres). */
+/**
+ * An EntityCollection that supports SQL-style relations (e.g. Postgres).
+ * @deprecated Use `EntityCollection` directly — `table`, `relations`, and `securityRules` are now on `BaseEntityCollection`.
+ */
 export type CollectionWithRelations<M extends Record<string, unknown> = Record<string, unknown>> = EntityCollection<M> & {
     table?: string;
     relations?: Relation[];

package/dist/types/src/types/properties.d.ts

@@ -641,14 +641,6 @@ export interface MapProperty extends BaseProperty {
      * Properties that are displayed when rendered as a preview
      */
     previewProperties?: string[];
-    /**
-     * Allow the user to add only some keys in this map.
-     * By default, all properties of the map have the corresponding field in
-     * the form view. Setting this flag to true allows to pick only some.
-     * Useful for map that can have a lot of sub-properties that may not be
-     * needed
-     */
-    pickOnlySomeKeys?: boolean;
     /**
      * Render this map as a key-value table that allows to use
      * arbitrary keys. You don't need to define the properties in this case.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client-postgresql",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "PostgreSQL data source client for Rebase",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -57,8 +57,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/client": "0.4.0",
-    "@rebasepro/types": "0.4.0"
+    "@rebasepro/client": "0.5.0",
+    "@rebasepro/types": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0",