singulio-postgres 1.1.0

package/src/rls.ts

@@ -0,0 +1,169 @@
+/**
+ * @singulio/postgres - Row-Level Security Helpers
+ * Multi-tenant isolation via PostgreSQL session GUCs
+ */
+
+import { sql } from 'bun';
+import type { RLSContext, QueryResult, QueryRow, Logger } from './types.js';
+
+/**
+ * Set RLS context variables for the current session
+ */
+export async function setRLSContext(context: RLSContext): Promise<void> {
+  // Set tenant reference (required for RLS policies)
+  await sql`SELECT set_config('app.tenant_ref', ${context.tenantId}, TRUE)`;
+
+  // Set admin flag (bypasses some policies)
+  await sql`SELECT set_config('app.is_admin', ${context.isAdmin ? 't' : 'f'}, TRUE)`;
+
+  // Set user ID if provided
+  if (context.userId) {
+    await sql`SELECT set_config('app.user_id', ${context.userId}, TRUE)`;
+  }
+
+  // Set any extra GUCs
+  if (context.extraGUCs) {
+    for (const [key, value] of Object.entries(context.extraGUCs)) {
+      await sql.unsafe(`SELECT set_config($1, $2, TRUE)`, [key, value]);
+    }
+  }
+}
+
+/**
+ * Clear RLS context variables
+ */
+export async function clearRLSContext(): Promise<void> {
+  await sql`SELECT set_config('app.tenant_ref', '', TRUE)`;
+  await sql`SELECT set_config('app.is_admin', 'f', TRUE)`;
+  await sql`SELECT set_config('app.user_id', '', TRUE)`;
+}
+
+/**
+ * Get current RLS context
+ */
+export async function getRLSContext(): Promise<RLSContext | null> {
+  const result = await sql`
+    SELECT
+      current_setting('app.tenant_ref', TRUE) as tenant_id,
+      current_setting('app.user_id', TRUE) as user_id,
+      current_setting('app.is_admin', TRUE) as is_admin
+  `;
+
+  const row = result[0];
+  if (!row || !row.tenant_id) return null;
+
+  return {
+    tenantId: row.tenant_id as string,
+    userId: (row.user_id as string) || undefined,
+    isAdmin: row.is_admin === 't',
+  };
+}
+
+/**
+ * Execute a function with RLS context, automatically cleaning up afterward
+ */
+export async function withTenant<T>(context: RLSContext, fn: () => Promise<T>): Promise<T> {
+  await setRLSContext(context);
+  try {
+    return await fn();
+  } finally {
+    await clearRLSContext();
+  }
+}
+
+/**
+ * Execute a query with RLS context
+ */
+export async function queryWithTenant<T = QueryRow>(
+  context: RLSContext,
+  queryText: string,
+  params?: unknown[]
+): Promise<QueryResult<T>> {
+  return withTenant(context, async () => {
+    const result = await sql.unsafe(queryText, params ?? []);
+    return {
+      rows: result as T[],
+      rowCount: result.length,
+    };
+  });
+}
+
+/**
+ * RLS-aware client wrapper
+ */
+export class RLSClient {
+  private logger?: Logger;
+
+  constructor(logger?: Logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Execute query with tenant context
+   */
+  async query<T = QueryRow>(
+    context: RLSContext,
+    queryText: string,
+    params?: unknown[]
+  ): Promise<QueryResult<T>> {
+    const start = performance.now();
+
+    try {
+      const result = await queryWithTenant<T>(context, queryText, params);
+
+      this.logger?.debug('RLS query executed', {
+        tenant: context.tenantId,
+        query: queryText.substring(0, 100),
+        rows: result.rowCount,
+        latencyMs: (performance.now() - start).toFixed(2),
+      });
+
+      return result;
+    } catch (error) {
+      this.logger?.error('RLS query failed', {
+        tenant: context.tenantId,
+        query: queryText.substring(0, 100),
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Execute with tenant context, return first row
+   */
+  async queryOne<T = QueryRow>(
+    context: RLSContext,
+    queryText: string,
+    params?: unknown[]
+  ): Promise<T | null> {
+    const result = await this.query<T>(context, queryText, params);
+    return result.rows[0] ?? null;
+  }
+
+  /**
+   * Execute with tenant context, return all rows
+   */
+  async queryAll<T = QueryRow>(
+    context: RLSContext,
+    queryText: string,
+    params?: unknown[]
+  ): Promise<T[]> {
+    const result = await this.query<T>(context, queryText, params);
+    return result.rows;
+  }
+
+  /**
+   * Wrap a function with RLS context
+   */
+  withTenant<T>(context: RLSContext, fn: () => Promise<T>): Promise<T> {
+    return withTenant(context, fn);
+  }
+}
+
+/**
+ * Create an RLS-aware client
+ */
+export function createRLSClient(logger?: Logger): RLSClient {
+  return new RLSClient(logger);
+}

package/src/transaction.ts

@@ -0,0 +1,207 @@
+/**
+ * @singulio/postgres - Transaction Helpers
+ * ACID transaction support with auto-rollback
+ */
+
+import { sql } from 'bun';
+import type { TransactionOptions, RLSContext, QueryResult, QueryRow, Logger } from './types.js';
+import { setRLSContext, clearRLSContext } from './rls.js';
+
+/**
+ * Build BEGIN statement with options
+ */
+function buildBeginStatement(options: TransactionOptions): string {
+  const parts = ['BEGIN'];
+
+  if (options.isolationLevel) {
+    parts.push(`ISOLATION LEVEL ${options.isolationLevel}`);
+  }
+
+  if (options.readOnly) {
+    parts.push('READ ONLY');
+  }
+
+  if (options.deferrable && options.readOnly && options.isolationLevel === 'SERIALIZABLE') {
+    parts.push('DEFERRABLE');
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Transaction query interface
+ */
+export interface TransactionQuery {
+  /**
+   * Execute a query within the transaction
+   */
+  query<T = QueryRow>(queryText: string, params?: unknown[]): Promise<QueryResult<T>>;
+
+  /**
+   * Execute and return first row
+   */
+  queryOne<T = QueryRow>(queryText: string, params?: unknown[]): Promise<T | null>;
+
+  /**
+   * Execute and return all rows
+   */
+  queryAll<T = QueryRow>(queryText: string, params?: unknown[]): Promise<T[]>;
+
+  /**
+   * Execute a command (INSERT/UPDATE/DELETE)
+   */
+  execute(queryText: string, params?: unknown[]): Promise<number>;
+}
+
+/**
+ * Execute a function within a transaction
+ * Auto-commits on success, auto-rollbacks on error
+ */
+export async function transaction<T>(
+  fn: (tx: TransactionQuery) => Promise<T>,
+  options: TransactionOptions = {},
+  logger?: Logger
+): Promise<T> {
+  const start = performance.now();
+
+  // Begin transaction
+  const beginStmt = buildBeginStatement(options);
+  await sql.unsafe(beginStmt);
+
+  // Set RLS context if provided
+  if (options.rlsContext) {
+    await setRLSContext(options.rlsContext);
+  }
+
+  // Create query interface
+  const tx: TransactionQuery = {
+    async query<T = QueryRow>(queryText: string, params?: unknown[]): Promise<QueryResult<T>> {
+      const result = await sql.unsafe(queryText, params ?? []);
+      return {
+        rows: result as T[],
+        rowCount: result.length,
+      };
+    },
+
+    async queryOne<T = QueryRow>(queryText: string, params?: unknown[]): Promise<T | null> {
+      const result = await tx.query<T>(queryText, params);
+      return result.rows[0] ?? null;
+    },
+
+    async queryAll<T = QueryRow>(queryText: string, params?: unknown[]): Promise<T[]> {
+      const result = await tx.query<T>(queryText, params);
+      return result.rows;
+    },
+
+    async execute(queryText: string, params?: unknown[]): Promise<number> {
+      const result = await tx.query(queryText, params);
+      return result.rowCount;
+    },
+  };
+
+  try {
+    const result = await fn(tx);
+
+    // Clear RLS context before commit
+    if (options.rlsContext) {
+      await clearRLSContext();
+    }
+
+    // Commit
+    await sql`COMMIT`;
+
+    const latency = performance.now() - start;
+    logger?.debug('Transaction committed', {
+      isolationLevel: options.isolationLevel ?? 'READ COMMITTED',
+      tenant: options.rlsContext?.tenantId,
+      latencyMs: latency.toFixed(2),
+    });
+
+    return result;
+  } catch (error) {
+    // Clear RLS context before rollback
+    if (options.rlsContext) {
+      try {
+        await clearRLSContext();
+      } catch {
+        // Ignore errors during cleanup
+      }
+    }
+
+    // Rollback
+    try {
+      await sql`ROLLBACK`;
+    } catch {
+      // Connection might be broken
+    }
+
+    const latency = performance.now() - start;
+    logger?.error('Transaction rolled back', {
+      isolationLevel: options.isolationLevel ?? 'READ COMMITTED',
+      tenant: options.rlsContext?.tenantId,
+      error: error instanceof Error ? error.message : String(error),
+      latencyMs: latency.toFixed(2),
+    });
+
+    throw error;
+  }
+}
+
+/**
+ * Execute a function within a serializable transaction
+ * Best for operations requiring strong consistency
+ */
+export async function serializableTransaction<T>(
+  fn: (tx: TransactionQuery) => Promise<T>,
+  rlsContext?: RLSContext,
+  logger?: Logger
+): Promise<T> {
+  return transaction(
+    fn,
+    {
+      isolationLevel: 'SERIALIZABLE',
+      rlsContext,
+    },
+    logger
+  );
+}
+
+/**
+ * Execute a function within a read-only transaction
+ * Best for reporting/analytics queries
+ */
+export async function readOnlyTransaction<T>(
+  fn: (tx: TransactionQuery) => Promise<T>,
+  rlsContext?: RLSContext,
+  logger?: Logger
+): Promise<T> {
+  return transaction(
+    fn,
+    {
+      readOnly: true,
+      rlsContext,
+    },
+    logger
+  );
+}
+
+/**
+ * Create a savepoint within a transaction
+ */
+export async function savepoint(name: string): Promise<void> {
+  await sql.unsafe(`SAVEPOINT ${name}`);
+}
+
+/**
+ * Rollback to a savepoint
+ */
+export async function rollbackToSavepoint(name: string): Promise<void> {
+  await sql.unsafe(`ROLLBACK TO SAVEPOINT ${name}`);
+}
+
+/**
+ * Release a savepoint
+ */
+export async function releaseSavepoint(name: string): Promise<void> {
+  await sql.unsafe(`RELEASE SAVEPOINT ${name}`);
+}

package/src/types.ts

@@ -0,0 +1,142 @@
+/**
+ * @singulio/postgres - Type Definitions
+ * PostgreSQL 18.x types for Bun native client
+ */
+
+/** Connection configuration */
+export interface PostgresConfig {
+  /** Connection string (postgres://user:pass@host:port/db) */
+  connectionString?: string;
+  /** Host (default: localhost) */
+  host?: string;
+  /** Port (default: 5432) */
+  port?: number;
+  /** Database name */
+  database?: string;
+  /** Username */
+  user?: string;
+  /** Password */
+  password?: string;
+  /** SSL mode */
+  ssl?: boolean | 'require' | 'prefer' | 'disable';
+  /** Application name for pg_stat_activity */
+  applicationName?: string;
+}
+
+/** Pool configuration */
+export interface PoolConfig extends PostgresConfig {
+  /** Minimum connections (default: 2) */
+  min?: number;
+  /** Maximum connections (default: 20) */
+  max?: number;
+  /** Idle timeout in ms (default: 30000) */
+  idleTimeout?: number;
+  /** Connection timeout in ms (default: 10000) */
+  connectionTimeout?: number;
+  /** Max lifetime per connection in ms (default: 3600000 = 1 hour) */
+  maxLifetime?: number;
+}
+
+/** RLS context for multi-tenant isolation */
+export interface RLSContext {
+  /** Tenant reference ID */
+  tenantId: string;
+  /** User ID (optional) */
+  userId?: string;
+  /** Is admin user (bypasses some RLS) */
+  isAdmin?: boolean;
+  /** Additional session GUCs */
+  extraGUCs?: Record<string, string>;
+}
+
+/** Query result row */
+export type QueryRow = Record<string, unknown>;
+
+/** Query result */
+export interface QueryResult<T = QueryRow> {
+  /** Result rows */
+  rows: T[];
+  /** Number of affected rows */
+  rowCount: number;
+  /** Field metadata */
+  fields?: FieldInfo[];
+}
+
+/** Field metadata */
+export interface FieldInfo {
+  name: string;
+  dataTypeID: number;
+  tableID?: number;
+  columnID?: number;
+}
+
+/** Transaction isolation levels */
+export type IsolationLevel =
+  | 'READ UNCOMMITTED'
+  | 'READ COMMITTED'
+  | 'REPEATABLE READ'
+  | 'SERIALIZABLE';
+
+/** Transaction options */
+export interface TransactionOptions {
+  /** Isolation level (default: READ COMMITTED) */
+  isolationLevel?: IsolationLevel;
+  /** Read-only transaction */
+  readOnly?: boolean;
+  /** Deferrable (only with SERIALIZABLE + readOnly) */
+  deferrable?: boolean;
+  /** RLS context to apply */
+  rlsContext?: RLSContext;
+}
+
+/** Health check result */
+export interface HealthCheckResult {
+  healthy: boolean;
+  latencyMs: number;
+  poolStats?: PoolStats;
+  error?: string;
+}
+
+/** Pool statistics */
+export interface PoolStats {
+  /** Total connections in pool */
+  total: number;
+  /** Idle connections */
+  idle: number;
+  /** Active connections */
+  active: number;
+  /** Pending connection requests */
+  pending: number;
+}
+
+/** Vector distance operators for pgvector */
+export type VectorDistanceOperator =
+  | '<->' // L2 distance (Euclidean)
+  | '<=>' // Cosine distance
+  | '<#>' // Inner product (negative)
+  | '<+>'; // L1 distance (Manhattan)
+
+/** Vector index types */
+export type VectorIndexType = 'hnsw' | 'ivfflat';
+
+/** Vector search options */
+export interface VectorSearchOptions {
+  /** Distance operator (default: <->) */
+  operator?: VectorDistanceOperator;
+  /** Maximum results (default: 10) */
+  limit?: number;
+  /** Minimum similarity threshold (optional) */
+  threshold?: number;
+  /** Additional WHERE clause */
+  filter?: string;
+  /** Filter parameters */
+  filterParams?: unknown[];
+}
+
+/** Logger interface (matches @singulio/logger) */
+export interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}