@rebasepro/server-postgresql 0.0.1-canary.09e5ec5

package/dist/server-postgresql/src/schema/doctor-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server-postgresql/src/schema/doctor.d.ts

@@ -0,0 +1,43 @@
+import { EntityCollection, Property } from "@rebasepro/types";
+export type IssueSeverity = "error" | "warning" | "info";
+export interface DoctorIssue {
+    severity: IssueSeverity;
+    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key";
+    table?: string;
+    column?: string;
+    expected?: string;
+    actual?: string;
+    message: string;
+    fix: string;
+}
+export interface DoctorReport {
+    collectionsToSchema: {
+        passed: boolean;
+        issues: DoctorIssue[];
+    };
+    schemaToDatabase: {
+        passed: boolean;
+        issues: DoctorIssue[];
+    };
+    summary: {
+        passed: number;
+        warnings: number;
+        errors: number;
+    };
+}
+export declare function getExpectedColumnType(prop: Property): string | null;
+export declare function loadCollections(collectionsPath: string): Promise<EntityCollection[]>;
+export declare function checkCollectionsVsSchema(collections: EntityCollection[], schemaFilePath: string): Promise<{
+    passed: boolean;
+    issues: DoctorIssue[];
+}>;
+export declare function checkCollectionsVsDatabase(collections: EntityCollection[], databaseUrl: string): Promise<{
+    passed: boolean;
+    issues: DoctorIssue[];
+}>;
+export declare function renderReport(report: DoctorReport): void;
+export declare function runDoctor(options: {
+    collectionsPath: string;
+    schemaPath: string;
+    databaseUrl?: string;
+}): Promise<DoctorReport>;

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[], stripPolicies?: boolean) => Promise<string>;

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

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

package/dist/server-postgresql/src/schema/introspect-db-logic.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Introspection logic — pure functions and the pipeline that transforms
+ * raw PostgreSQL metadata into Rebase collection definition files.
+ *
+ * This module contains NO side-effects: no fs writes, no pg.Client creation,
+ * no process.exit.  It is imported by introspect-db.ts (the CLI entry-point)
+ * and consumed directly by tests.
+ */
+export interface TableRow {
+    table_name: string;
+}
+export interface TableColumn {
+    table_name: string;
+    column_name: string;
+    data_type: string;
+    udt_name: string;
+    is_nullable: string;
+    column_default: string | null;
+}
+export interface EnumValue {
+    enum_name: string;
+    enum_value: string;
+    sort_order: number;
+}
+export interface PrimaryKeyRow {
+    table_name: string;
+    column_name: string;
+}
+export interface ForeignKeyRow {
+    table_name: string;
+    column_name: string;
+    foreign_table_name: string;
+    foreign_column_name: string;
+}
+export interface TableMeta {
+    name: string;
+    columns: TableColumn[];
+    pks: string[];
+    fks: ForeignKeyRow[];
+}
+export declare function singularize(word: string): string;
+/**
+ * Convert a snake_case name to a human-readable Title Case label.
+ * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
+ */
+export declare function humanize(snakeName: string): string;
+/**
+ * Convert a snake_case table name to a camelCase + "Collection" variable name.
+ * e.g. "company_token" -> "companyTokenCollection"
+ */
+export declare function toCollectionVarName(tableName: string): string;
+export declare function getIconForTable(tableName: string): string;
+/**
+ * Map a PostgreSQL data type to a Rebase property type.
+ */
+export declare function mapPgType(dataType: string): string;
+export declare function buildEnumMap(enumValues: EnumValue[]): Map<string, string[]>;
+export declare function buildTablesMap(tables: TableRow[], columns: TableColumn[], pks: PrimaryKeyRow[], fks: ForeignKeyRow[]): Map<string, TableMeta>;
+export declare function identifyJoinTables(tablesMap: Map<string, TableMeta>): Set<string>;
+export interface GeneratedFile {
+    tableName: string;
+    fileName: string;
+    content: string;
+}
+/**
+ * Generate the full TypeScript file content for a single collection.
+ * Pure function — no I/O.
+ */
+export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>): string;
+/**
+ * Generate the content for an index.ts file that re-exports all collections.
+ */
+export declare function generateIndexContent(fileNames: string[]): string;
+/**
+ * Merge new exports into existing index.ts content.
+ * Returns the merged content string.
+ */
+export declare function mergeIndexContent(existingContent: string, newFileNames: string[]): string;
+/**
+ * Safely extract the host portion of a database URL for logging.
+ */
+export declare function safeHostFromUrl(url: string): string;

package/dist/server-postgresql/src/schema/introspect-db.d.ts

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

package/dist/server-postgresql/src/schema/test-schema.d.ts

@@ -0,0 +1,24 @@
+export declare const testTable: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "test";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "test";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

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,209 @@
+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, unknown>>(filter: FilterValues<Extract<keyof M, string>>, table: PgTable<any>, collectionPath: string): SQL[];
+    /**
+     * Resolves the correct Drizzle column for sorting.
+     * Automatically maps owning relation property keys to their underlying foreign key column.
+     */
+    private resolveOrderByField;
+    /**
+     * 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;
+    /**
+     * Resolves joinPath relations for raw REST rows and directly injects them.
+     * Uses RelationService to query the database and maps results back to the flattened objects.
+     */
+    private resolveJoinPathRelationsBatchRest;
+    /**
+     * 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, unknown>>(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, unknown>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        offset?: 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, unknown>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        offset?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Search entities by text
+     */
+    searchEntities<M extends Record<string, unknown>>(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, unknown>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        searchString?: 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, unknown>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        offset?: 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, unknown>>(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, unknown>>(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,98 @@
+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, unknown>>(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, unknown>>(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, unknown>>(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, Entity<Record<string, unknown>>>>;
+    /**
+     * Batch fetch many-cardinality related entities for multiple parent entities.
+     * Returns a Map<parentId, Entity[]> instead of Map<parentId, Entity>.
+     * Uses a single SQL query with IN clause to avoid N+1.
+     */
+    batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentEntityIds: (string | number)[], _relationKey: string, relation: Relation): Promise<Map<string, Entity<Record<string, unknown>>[]>>;
+    /**
+     * Update many-to-many and junction relations
+     */
+    updateRelationsUsingJoins<M extends Record<string, unknown>>(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,38 @@
+import { PgTable, AnyPgColumn } 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.
+ */
+/**
+ * Interface for Drizzle column metadata introspection.
+ * Replaces unsafe `as unknown as Record<string, unknown>` double-cast chains.
+ */
+export interface DrizzleColumnMeta {
+    columnType?: string;
+    dataType?: string;
+    primary?: boolean;
+}
+/** Safely extract Drizzle column metadata from a column object. */
+export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
+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";
+    isUUID?: boolean;
+}[];
+export declare function parseIdValues(idValue: string | number, primaryKeys: {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}[]): Record<string, string | number>;
+export declare function buildCompositeId(values: Record<string, unknown>, primaryKeys: {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}[]): string;