@rebasepro/server-postgresql 0.0.1-canary.4d4fb3e

package/dist/server-postgresql/src/schema/generate-drizzle-schema-logic.d.ts

@@ -0,0 +1,2 @@
+import { EntityCollection } from "@rebasepro/types";
+export declare const generateSchema: (collections: EntityCollection[]) => Promise<string>;

package/dist/server-postgresql/src/schema/generate-drizzle-schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server-postgresql/src/services/BranchService.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BranchService
+ *
+ * Manages database branching by creating/deleting PostgreSQL databases
+ * using `CREATE DATABASE ... TEMPLATE`. Branch metadata is stored in the
+ * `rebase.branches` table in the default (main) database, following the
+ * same `rebase` schema convention used by entity_history, auth, etc.
+ */
+import { BranchInfo } from "@rebasepro/types";
+import { DrizzleClient } from "../interfaces";
+import { DatabasePoolManager } from "../databasePoolManager";
+export declare class BranchService {
+    private db;
+    private poolManager;
+    constructor(db: DrizzleClient, poolManager: DatabasePoolManager);
+    /**
+     * Ensure the `rebase.branches` metadata table exists in the default database.
+     * Idempotent — safe to call on every startup.
+     */
+    ensureBranchMetadataTable(): Promise<void>;
+    /**
+     * Create a new branch database by templating the source database.
+     *
+     * Uses `CREATE DATABASE ... TEMPLATE` for an instant, full-fidelity copy
+     * of both schema and data.
+     *
+     * @param name   User-facing branch name (e.g., "feature_auth")
+     * @param options.source  Source database to clone; defaults to the main database.
+     */
+    createBranch(name: string, options?: {
+        source?: string;
+    }): Promise<BranchInfo>;
+    /**
+     * Delete a branch database and remove its metadata.
+     * Cannot delete the main/default database.
+     */
+    deleteBranch(name: string): Promise<void>;
+    /**
+     * List all branches recorded in the metadata table.
+     * Optionally fetches database sizes from pg_database.
+     */
+    listBranches(): Promise<BranchInfo[]>;
+    /**
+     * Get info about a specific branch.
+     */
+    getBranchInfo(name: string): Promise<BranchInfo | undefined>;
+}

package/dist/server-postgresql/src/services/EntityFetchService.d.ts

@@ -0,0 +1,195 @@
+import { SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import { Entity, FilterValues } from "@rebasepro/types";
+import { RelationService } from "./RelationService";
+import { DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Service for handling all entity read operations.
+ * Handles fetching, searching, counting, and filtering entities.
+ */
+export declare class EntityFetchService {
+    private db;
+    private registry;
+    private relationService;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * Get the relational query builder for a given table name.
+     * Safely narrows the DrizzleClient union type to access db.query[tableName].
+     */
+    private getQueryBuilder;
+    /**
+     * Build filter conditions from FilterValues
+     * Delegates to DrizzleConditionBuilder.buildFilterConditions
+     */
+    buildFilterConditions<M extends Record<string, any>>(filter: FilterValues<Extract<keyof M, string>>, table: PgTable<any>, collectionPath: string): SQL[];
+    /**
+     * Build the `with` config for Drizzle's relational query API.
+     * Converts collection relations to a Drizzle-compatible `with` object.
+     *
+     * When `include` is provided, only those relations are loaded.
+     * When `include` is absent, ALL relations are loaded (CMS path).
+     *
+     * Automatically detects many-to-many junction tables and nests
+     * the target relation so actual entity data is returned.
+     */
+    private buildWithConfig;
+    /**
+     * Detect if a many-to-many relation uses a junction table in the Drizzle schema.
+     */
+    private isJunctionRelation;
+    /**
+     * Get the Drizzle relation name on the junction table that points to the actual target entity.
+     * For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
+     */
+    private getJunctionTargetRelationName;
+    /**
+     * Convert a db.query result row (with nested relation objects) to an Entity<M>.
+     * Handles:
+     * - The { id, path, values } wrapping
+     * - Type normalization (dates, numbers, NaN) via normalizeDbValues
+     * - Converting nested relation objects to { id, path, __type: "relation" } for CMS
+     * - Flattening junction-table many-to-many results
+     */
+    private drizzleResultToEntity;
+    /**
+     * Post-fetch joinPath relations for a single entity.
+     * joinPath relations cannot be expressed via Drizzle's `with` config,
+     * so they must be loaded separately after the primary query.
+     */
+    private resolveJoinPathRelations;
+    /**
+     * Post-fetch joinPath relations for a batch of entities.
+     * Uses batch fetching to avoid N+1 queries for list views.
+     */
+    private resolveJoinPathRelationsBatch;
+    /**
+     * Convert a db.query result row to a flat REST-style object with populated relations.
+     */
+    private drizzleResultToRestRow;
+    /**
+     * Build db.query-compatible options from standard fetch options.
+     * Handles filter, search, orderBy, limit, and cursor-based pagination.
+     */
+    private buildDrizzleQueryOptions;
+    /**
+     * Extract cursor pagination conditions from startAfter options.
+     */
+    private buildCursorConditions;
+    /**
+     * Fetch a single entity by ID
+     */
+    fetchEntity<M extends Record<string, any>>(collectionPath: string, entityId: string | number, databaseId?: string): Promise<Entity<M> | undefined>;
+    /**
+     * Unified method to fetch entities with optional search functionality
+     */
+    fetchEntitiesWithConditions<M extends Record<string, any>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Fallback path used when db.query is unavailable.
+     * The primary path uses drizzleResultToEntity which handles relation
+     * mapping without N+1 queries.
+     *
+     * Process raw database results into Entity objects with relations.
+     */
+    private processEntityResults;
+    /**
+     * Fetch a collection of entities
+     */
+    fetchCollection<M extends Record<string, any>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Search entities by text
+     */
+    searchEntities<M extends Record<string, any>>(collectionPath: string, searchString: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Fetch collection from multi-segment path
+     */
+    private fetchCollectionFromPath;
+    /**
+     * Count entities in a collection
+     */
+    countEntities<M extends Record<string, any>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        databaseId?: string;
+    }): Promise<number>;
+    /**
+     * Count entities from multi-segment path
+     */
+    private countEntitiesFromPath;
+    /**
+     * Check if a field value is unique
+     */
+    checkUniqueField(collectionPath: string, fieldName: string, value: unknown, excludeEntityId?: string, _databaseId?: string): Promise<boolean>;
+    /**
+     * Get the RelationService instance for external use
+     */
+    getRelationService(): RelationService;
+    /**
+     * Fetch a collection of entities with optional relation includes.
+     * When `include` is provided, only the specified relations are populated
+     * with full entity data (not just { id, path, __type }).
+     * When `include` is absent, no relation queries are made (fast path).
+     *
+     * @param include - Array of relation keys to populate, or ["*"] for all
+     */
+    fetchCollectionForRest<M extends Record<string, any>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }, include?: string[]): Promise<Record<string, unknown>[]>;
+    /**
+     * Fetch a single entity with optional relation includes for REST API.
+     */
+    fetchEntityForRest<M extends Record<string, any>>(collectionPath: string, entityId: string | number, include?: string[], databaseId?: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Fetch raw rows without any relation processing (for REST fast path)
+     */
+    private fetchEntitiesWithConditionsRaw;
+    /**
+     * Check if the Drizzle instance has the relational query API available
+     * for a given collection path.
+     * Note: Primary path now uses inline `getQueryBuilder()` checks.
+     */
+    private hasDrizzleQueryAPI;
+    /**
+     * Attempt to use Drizzle's relational query API (db.query.<table>.findMany)
+     * for efficient JOIN-based relation loading.
+     * Returns null if the API is not available or the query fails.
+     * Note: Primary path now uses `buildWithConfig` + `buildDrizzleQueryOptions`.
+     */
+    private fetchWithDrizzleQuery;
+    /**
+     * Fallback path used when db.query is unavailable.
+     * The primary path uses db.query.findMany with `with` config, which
+     * loads all relations in a single query.
+     *
+     * Batch fetch many-to-many related entities for multiple parent IDs.
+     * Groups results by parent ID to avoid N+1.
+     */
+    private batchFetchManyRelatedEntities;
+}

package/dist/server-postgresql/src/services/EntityPersistService.d.ts

@@ -0,0 +1,41 @@
+import { Entity } from "@rebasepro/types";
+import { RelationService } from "./RelationService";
+import { EntityFetchService } from "./EntityFetchService";
+import { DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Service for handling all entity write operations.
+ * Handles saving, deleting, and updating entities.
+ */
+export declare class EntityPersistService {
+    private db;
+    private registry;
+    private relationService;
+    private fetchService;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * Delete an entity by ID
+     */
+    deleteEntity(collectionPath: string, entityId: string | number, _databaseId?: string): Promise<void>;
+    /**
+     * Save an entity (create or update)
+     */
+    saveEntity<M extends Record<string, any>>(collectionPath: string, values: Partial<M>, entityId?: string | number, databaseId?: string): Promise<Entity<M>>;
+    /**
+     * Get the RelationService instance for external use
+     */
+    getRelationService(): RelationService;
+    /**
+     * Get the FetchService instance for external use
+     */
+    getFetchService(): EntityFetchService;
+    /**
+     * Translate raw PostgreSQL / Drizzle errors into user-friendly messages.
+     */
+    private toUserFriendlyError;
+    /**
+     * Extract the underlying PostgreSQL error from a Drizzle wrapper.
+     * Drizzle wraps PG errors in a `cause` property.
+     */
+    private extractPgError;
+}

package/dist/server-postgresql/src/services/RelationService.d.ts

@@ -0,0 +1,92 @@
+import { DrizzleClient } from "../interfaces";
+import { Entity, EntityCollection, FilterValues, Relation } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Service for handling all relation-related operations.
+ * Handles fetching, updating, and managing entity relations.
+ */
+export declare class RelationService {
+    private db;
+    private registry;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * Fetch entities related to a parent entity through a specific relation
+     */
+    fetchRelatedEntities<M extends Record<string, any>>(parentCollectionPath: string, parentEntityId: string | number, relationKey: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Fetch entities using join paths for complex relations
+     */
+    fetchEntitiesUsingJoins<M extends Record<string, any>>(parentCollection: EntityCollection, parentEntityId: string | number, relation: Relation, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Count related entities for a parent entity
+     */
+    countRelatedEntities<M extends Record<string, any>>(parentCollectionPath: string, parentEntityId: string | number, relationKey: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        databaseId?: string;
+    }): Promise<number>;
+    /**
+     * Batch fetch related entities for multiple parent entities to avoid N+1 queries
+     */
+    batchFetchRelatedEntities(parentCollectionPath: string, parentEntityIds: (string | number)[], _relationKey: string, relation: Relation): Promise<Map<string | number, Entity<Record<string, unknown>>>>;
+    /**
+     * Update many-to-many and junction relations
+     */
+    updateRelationsUsingJoins<M extends Record<string, any>>(tx: DrizzleClient, collection: EntityCollection, entityId: string | number, relationValues: Partial<M>): Promise<void>;
+    /**
+     * Update inverse relations (where FK is on the target table)
+     */
+    updateInverseRelations(tx: DrizzleClient, sourceCollection: EntityCollection, sourceEntityId: string | number, inverseRelationUpdates: Array<{
+        relationKey: string;
+        relation: Relation;
+        newValue: unknown;
+        currentEntityId?: string | number;
+    }>): Promise<void>;
+    /**
+     * Handle inverse relations with joinPath
+     */
+    private updateInverseJoinPathRelation;
+    /**
+     * Handle many-to-many inverse relation updates using junction tables
+     */
+    private updateManyToManyInverseRelation;
+    /**
+     * Update one-to-one relations that use joinPath
+     */
+    updateJoinPathOneToOneRelations(tx: DrizzleClient, parentCollection: EntityCollection, parentEntityId: string | number, updates: Array<{
+        relationKey: string;
+        relation: Relation;
+        newTargetId: string | number | null;
+    }>): Promise<void>;
+    /**
+     * Resolve joinPath write mapping for one-to-one relations
+     */
+    resolveJoinPathWriteMapping(parentCollection: EntityCollection, relation: Relation): {
+        targetFKColName: string;
+        parentSourceColName: string;
+    };
+    /**
+     * Handle junction table creation for many-to-many path-based saves
+     */
+    handleJunctionTableCreation(tx: DrizzleClient, newEntityId: string | number, junctionTableInfo: {
+        parentCollection: EntityCollection;
+        parentId: string | number;
+        relation: Relation;
+        relationKey: string;
+    }): Promise<void>;
+}

package/dist/server-postgresql/src/services/entity-helpers.d.ts

@@ -0,0 +1,24 @@
+import { PgTable } from "drizzle-orm/pg-core";
+import { EntityCollection } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Shared helper functions for entity operations.
+ * These are used by EntityFetchService, EntityPersistService, and RelationService.
+ *
+ * All functions that need collection/table lookups require an explicit
+ * `PostgresCollectionRegistry` instance — there is no global singleton.
+ */
+export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): EntityCollection;
+export declare function getTableForCollection(collection: EntityCollection, registry: PostgresCollectionRegistry): PgTable<any>;
+export declare function getPrimaryKeys(collection: EntityCollection, registry: PostgresCollectionRegistry): {
+    fieldName: string;
+    type: "string" | "number";
+}[];
+export declare function parseIdValues(idValue: string | number, primaryKeys: {
+    fieldName: string;
+    type: "string" | "number";
+}[]): Record<string, string | number>;
+export declare function buildCompositeId(values: Record<string, any>, primaryKeys: {
+    fieldName: string;
+    type: "string" | "number";
+}[]): string;

package/dist/server-postgresql/src/services/entityService.d.ts

@@ -0,0 +1,102 @@
+import { Entity, FilterValues } from "@rebasepro/types";
+import { EntityFetchService } from "./EntityFetchService";
+import { EntityPersistService } from "./EntityPersistService";
+import { RelationService } from "./RelationService";
+import { EntityRepository, DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+export { sanitizeAndConvertDates, serializeDataToServer, parseDataFromServer } from "../data-transformer";
+export { EntityFetchService } from "./EntityFetchService";
+export { EntityPersistService } from "./EntityPersistService";
+export { RelationService } from "./RelationService";
+export * from "../interfaces";
+/**
+ * EntityService - Facade for entity operations.
+ *
+ * This class provides a unified API for entity CRUD operations by delegating
+ * to specialized services:
+ * - EntityFetchService: Read operations (fetch, search, count)
+ * - EntityPersistService: Write operations (save, delete)
+ * - RelationService: Relation operations (fetch related, update relations)
+ *
+ * Implements the EntityRepository interface for database abstraction.
+ */
+export declare class EntityService implements EntityRepository {
+    private db;
+    private registry;
+    private fetchService;
+    private persistService;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * Fetch a single entity by ID
+     */
+    fetchEntity<M extends Record<string, any>>(collectionPath: string, entityId: string | number, databaseId?: string): Promise<Entity<M> | undefined>;
+    /**
+     * Fetch a collection of entities with optional filtering, ordering, and pagination
+     */
+    fetchCollection<M extends Record<string, any>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Search entities by text
+     */
+    searchEntities<M extends Record<string, any>>(collectionPath: string, searchString: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Count entities in a collection
+     */
+    countEntities<M extends Record<string, any>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        databaseId?: string;
+    }): Promise<number>;
+    /**
+     * Check if a field value is unique in a collection
+     */
+    checkUniqueField(collectionPath: string, fieldName: string, value: unknown, excludeEntityId?: string, databaseId?: string): Promise<boolean>;
+    /**
+     * Fetch entities related to a parent entity
+     */
+    fetchRelatedEntities<M extends Record<string, any>>(parentCollectionPath: string, parentEntityId: string | number, relationKey: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Save an entity (create or update)
+     */
+    saveEntity<M extends Record<string, any>>(collectionPath: string, values: Partial<M>, entityId?: string | number, databaseId?: string): Promise<Entity<M>>;
+    /**
+     * Delete an entity by ID
+     */
+    deleteEntity(collectionPath: string, entityId: string | number, databaseId?: string): Promise<void>;
+    /**
+     * Execute raw SQL
+     */
+    executeSql(sqlText: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Get the underlying EntityFetchService for advanced use
+     */
+    getFetchService(): EntityFetchService;
+    /**
+     * Get the underlying EntityPersistService for advanced use
+     */
+    getPersistService(): EntityPersistService;
+    /**
+     * Get the underlying RelationService for advanced use
+     */
+    getRelationService(): RelationService;
+}

package/dist/server-postgresql/src/services/index.d.ts

@@ -0,0 +1,4 @@
+export { EntityFetchService } from "./EntityFetchService";
+export { EntityPersistService } from "./EntityPersistService";
+export { RelationService } from "./RelationService";
+export { getCollectionByPath, getTableForCollection, getPrimaryKeys, parseIdValues, buildCompositeId } from "./entity-helpers";