@bernierllc/database-adapter-postgresql 1.0.0

package/dist/rls/RLSPolicyGenerator.js

@@ -0,0 +1,212 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLSPolicyGenerator = void 0;
+/**
+ * RLS policy generator for Supabase
+ * Creates policies for multi-tenant security with Clerk integration
+ */
+class RLSPolicyGenerator {
+    /**
+     * Generate RLS policy for user-scoped access
+     */
+    static generateUserPolicy(table) {
+        return `
+      -- Enable RLS
+      ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;
+
+      -- Users can view own records
+      CREATE POLICY "Users can view own records"
+        ON ${table}
+        FOR SELECT
+        USING (
+          user_id = (
+            SELECT id FROM users
+            WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          )
+        );
+
+      -- Users can insert own records
+      CREATE POLICY "Users can insert own records"
+        ON ${table}
+        FOR INSERT
+        WITH CHECK (
+          user_id = (
+            SELECT id FROM users
+            WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          )
+        );
+
+      -- Users can update own records
+      CREATE POLICY "Users can update own records"
+        ON ${table}
+        FOR UPDATE
+        USING (
+          user_id = (
+            SELECT id FROM users
+            WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          )
+        );
+
+      -- Users can delete own records (soft delete only)
+      CREATE POLICY "Users can delete own records"
+        ON ${table}
+        FOR UPDATE
+        USING (
+          user_id = (
+            SELECT id FROM users
+            WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          )
+        )
+        WITH CHECK (deleted_at IS NOT NULL);
+    `;
+    }
+    /**
+     * Generate admin bypass policy
+     */
+    static generateAdminPolicy(table) {
+        return `
+      -- Admins can do anything
+      CREATE POLICY "Admins have full access"
+        ON ${table}
+        FOR ALL
+        USING (
+          (SELECT role FROM users
+           WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          ) = 'admin'
+        );
+    `;
+    }
+    /**
+     * Generate multi-tenant policy
+     */
+    static generateTenantPolicy(table) {
+        return `
+      -- Tenant isolation
+      CREATE POLICY "Tenant isolation"
+        ON ${table}
+        FOR ALL
+        USING (
+          tenant_id = current_setting('app.tenant_id', true)::uuid
+        );
+    `;
+    }
+    /**
+     * Generate read-only policy for public data
+     */
+    static generatePublicReadPolicy(table, condition) {
+        const whereClause = condition ? `AND ${condition}` : '';
+        return `
+      -- Public read access
+      CREATE POLICY "Public can view published records"
+        ON ${table}
+        FOR SELECT
+        USING (
+          status = 'published'
+          AND deleted_at IS NULL
+          ${whereClause}
+        );
+    `;
+    }
+    /**
+     * Generate policy for shared resources
+     */
+    static generateSharedResourcePolicy(table, sharingTable = 'shared_access') {
+        return `
+      -- Shared resource access
+      CREATE POLICY "Users can access shared resources"
+        ON ${table}
+        FOR SELECT
+        USING (
+          -- Owner access
+          user_id = (
+            SELECT id FROM users
+            WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          )
+          OR
+          -- Shared access
+          id IN (
+            SELECT resource_id FROM ${sharingTable}
+            WHERE shared_with_user_id = (
+              SELECT id FROM users
+              WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+            )
+          )
+        );
+    `;
+    }
+    /**
+     * Generate policy for role-based access
+     */
+    static generateRoleBasedPolicy(table, allowedRoles) {
+        const rolesArray = allowedRoles.map(r => `'${r}'`).join(', ');
+        return `
+      -- Role-based access
+      CREATE POLICY "Role-based access"
+        ON ${table}
+        FOR ALL
+        USING (
+          (SELECT role FROM users
+           WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+          ) IN (${rolesArray})
+        );
+    `;
+    }
+    /**
+     * Disable RLS on a table (use with caution)
+     */
+    static disableRLS(table) {
+        return `
+      -- Disable RLS (use with caution)
+      ALTER TABLE ${table} DISABLE ROW LEVEL SECURITY;
+
+      -- Drop all policies
+      DO $$
+      DECLARE
+        pol RECORD;
+      BEGIN
+        FOR pol IN
+          SELECT policyname
+          FROM pg_policies
+          WHERE tablename = '${table}'
+        LOOP
+          EXECUTE format('DROP POLICY IF EXISTS %I ON ${table}', pol.policyname);
+        END LOOP;
+      END $$;
+    `;
+    }
+    /**
+     * Generate policy for time-based access (e.g., scheduled content)
+     */
+    static generateTimeBasedPolicy(table) {
+        return `
+      -- Time-based access for scheduled content
+      CREATE POLICY "Scheduled content visibility"
+        ON ${table}
+        FOR SELECT
+        USING (
+          (
+            -- Owner can always see
+            user_id = (
+              SELECT id FROM users
+              WHERE clerk_id = current_setting('request.jwt.claims', true)::json->>'sub'
+            )
+          )
+          OR
+          (
+            -- Public can see if published and scheduled time has passed
+            status = 'published'
+            AND deleted_at IS NULL
+            AND (scheduled_for IS NULL OR scheduled_for <= NOW())
+          )
+        );
+    `;
+    }
+}
+exports.RLSPolicyGenerator = RLSPolicyGenerator;

package/dist/search/FullTextSearchManager.d.ts

@@ -0,0 +1,61 @@
+import { PostgreSQLAdapter } from '../PostgreSQLAdapter';
+/**
+ * Search result with similarity scores
+ */
+export interface SearchResult {
+    id: string;
+    title: string;
+    excerpt?: string;
+    body?: string;
+    titleSimilarity: number;
+    bodySimilarity: number;
+    totalSimilarity: number;
+    [key: string]: unknown;
+}
+/**
+ * Search options
+ */
+export interface SearchOptions {
+    limit?: number;
+    offset?: number;
+    minSimilarity?: number;
+    fields?: string[];
+    orderBy?: 'relevance' | 'date' | 'title';
+}
+/**
+ * PostgreSQL full-text search with pg_trgm
+ * Enables fuzzy matching and typo-tolerance
+ */
+export declare class FullTextSearchManager {
+    private adapter;
+    private logger?;
+    constructor(adapter: PostgreSQLAdapter);
+    /**
+     * Search content with full-text search and fuzzy matching
+     */
+    searchContent(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search using PostgreSQL full-text search vectors (ts_vector)
+     */
+    searchWithTsVector(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Combined search using both pg_trgm fuzzy matching and ts_vector
+     */
+    searchCombined(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Create full-text search indexes
+     */
+    createIndexes(): Promise<void>;
+    /**
+     * Drop full-text search indexes
+     */
+    dropIndexes(): Promise<void>;
+    /**
+     * Get search statistics
+     */
+    getSearchStats(): Promise<{
+        indexesExist: boolean;
+        extensionEnabled: boolean;
+        searchVectorExists: boolean;
+    }>;
+}

package/dist/search/FullTextSearchManager.js

@@ -0,0 +1,265 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FullTextSearchManager = void 0;
+/**
+ * PostgreSQL full-text search with pg_trgm
+ * Enables fuzzy matching and typo-tolerance
+ */
+class FullTextSearchManager {
+    constructor(adapter) {
+        this.adapter = adapter;
+        // Access logger from adapter (it's a public property but typed generically)
+        this.logger = adapter.logger;
+    }
+    /**
+     * Search content with full-text search and fuzzy matching
+     */
+    async searchContent(query, options = {}) {
+        const { limit = 20, offset = 0, minSimilarity = 0.3, fields = ['title', 'body', 'excerpt'], orderBy = 'relevance' } = options;
+        if (this.logger) {
+            this.logger.debug('Performing full-text search', {
+                query,
+                limit,
+                offset,
+                minSimilarity,
+                orderBy
+            });
+        }
+        // Build field similarity calculations
+        const titleSimilarity = fields.includes('title')
+            ? 'similarity(title, $1)'
+            : '0';
+        const bodySimilarity = fields.includes('body')
+            ? 'similarity(body, $1)'
+            : '0';
+        const excerptSimilarity = fields.includes('excerpt')
+            ? 'similarity(excerpt, $1)'
+            : '0';
+        // Calculate total similarity with weights (title > excerpt > body)
+        const totalSimilarity = `(
+      (${titleSimilarity} * 3) +
+      (${excerptSimilarity} * 2) +
+      (${bodySimilarity} * 1)
+    ) / 6`;
+        // Build WHERE clause
+        const whereConditions = [];
+        if (fields.includes('title')) {
+            whereConditions.push(`${titleSimilarity} > $2`);
+        }
+        if (fields.includes('body')) {
+            whereConditions.push(`${bodySimilarity} > $2`);
+        }
+        if (fields.includes('excerpt')) {
+            whereConditions.push(`${excerptSimilarity} > $2`);
+        }
+        const whereClause = whereConditions.length > 0
+            ? `WHERE (${whereConditions.join(' OR ')})`
+            : '';
+        // Build ORDER BY clause
+        let orderByClause = '';
+        switch (orderBy) {
+            case 'relevance':
+                orderByClause = 'ORDER BY total_similarity DESC';
+                break;
+            case 'date':
+                orderByClause = 'ORDER BY created_at DESC';
+                break;
+            case 'title':
+                orderByClause = 'ORDER BY title ASC';
+                break;
+        }
+        const sql = `
+      SELECT
+        id,
+        title,
+        excerpt,
+        ${titleSimilarity} as title_similarity,
+        ${bodySimilarity} as body_similarity,
+        ${totalSimilarity} as total_similarity,
+        created_at,
+        updated_at
+      FROM content
+      ${whereClause}
+      ${orderByClause}
+      LIMIT $3 OFFSET $4
+    `;
+        const result = await this.adapter.query(sql, [query, minSimilarity, limit, offset]);
+        if (this.logger) {
+            this.logger.debug('Full-text search completed', {
+                query,
+                resultsCount: result.rowCount
+            });
+        }
+        return result.rows;
+    }
+    /**
+     * Search using PostgreSQL full-text search vectors (ts_vector)
+     */
+    async searchWithTsVector(query, options = {}) {
+        const { limit = 20, offset = 0 } = options;
+        if (this.logger) {
+            this.logger.debug('Performing ts_vector search', { query, limit, offset });
+        }
+        const sql = `
+      SELECT
+        id,
+        title,
+        excerpt,
+        ts_rank(search_vector, plainto_tsquery('english', $1)) as rank
+      FROM content
+      WHERE search_vector @@ plainto_tsquery('english', $1)
+        AND deleted_at IS NULL
+      ORDER BY rank DESC
+      LIMIT $2 OFFSET $3
+    `;
+        const result = await this.adapter.query(sql, [query, limit, offset]);
+        if (this.logger) {
+            this.logger.debug('ts_vector search completed', {
+                query,
+                resultsCount: result.rowCount
+            });
+        }
+        return result.rows;
+    }
+    /**
+     * Combined search using both pg_trgm fuzzy matching and ts_vector
+     */
+    async searchCombined(query, options = {}) {
+        const { limit = 20, offset = 0, minSimilarity = 0.2 } = options;
+        if (this.logger) {
+            this.logger.debug('Performing combined search', { query, limit, offset });
+        }
+        const sql = `
+      SELECT DISTINCT
+        id,
+        title,
+        excerpt,
+        similarity(title, $1) as title_similarity,
+        similarity(body, $1) as body_similarity,
+        COALESCE(ts_rank(search_vector, plainto_tsquery('english', $1)), 0) as ts_rank,
+        (
+          (similarity(title, $1) * 3) +
+          (similarity(body, $1) * 1) +
+          (COALESCE(ts_rank(search_vector, plainto_tsquery('english', $1)), 0) * 2)
+        ) / 6 as total_similarity,
+        created_at,
+        updated_at
+      FROM content
+      WHERE
+        (
+          similarity(title, $1) > $2
+          OR similarity(body, $1) > $2
+          OR search_vector @@ plainto_tsquery('english', $1)
+        )
+        AND deleted_at IS NULL
+      ORDER BY total_similarity DESC
+      LIMIT $3 OFFSET $4
+    `;
+        const result = await this.adapter.query(sql, [query, minSimilarity, limit, offset]);
+        if (this.logger) {
+            this.logger.debug('Combined search completed', {
+                query,
+                resultsCount: result.rowCount
+            });
+        }
+        return result.rows;
+    }
+    /**
+     * Create full-text search indexes
+     */
+    async createIndexes() {
+        if (this.logger) {
+            this.logger.info('Creating full-text search indexes');
+        }
+        await this.adapter.query(`
+      -- Enable pg_trgm extension
+      CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+      -- Create GIN indexes for fuzzy matching
+      CREATE INDEX IF NOT EXISTS idx_content_title_trgm
+        ON content USING gin (title gin_trgm_ops);
+
+      CREATE INDEX IF NOT EXISTS idx_content_body_trgm
+        ON content USING gin (body gin_trgm_ops);
+
+      CREATE INDEX IF NOT EXISTS idx_content_excerpt_trgm
+        ON content USING gin (excerpt gin_trgm_ops);
+
+      -- Create full-text search vector if not exists
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'content' AND column_name = 'search_vector'
+        ) THEN
+          ALTER TABLE content ADD COLUMN search_vector tsvector
+            GENERATED ALWAYS AS (
+              setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
+              setweight(to_tsvector('english', coalesce(excerpt, '')), 'B') ||
+              setweight(to_tsvector('english', coalesce(body, '')), 'C')
+            ) STORED;
+        END IF;
+      END $$;
+
+      -- Create GIN index on search vector
+      CREATE INDEX IF NOT EXISTS idx_content_search_vector
+        ON content USING gin (search_vector);
+    `);
+        if (this.logger) {
+            this.logger.info('Full-text search indexes created successfully');
+        }
+    }
+    /**
+     * Drop full-text search indexes
+     */
+    async dropIndexes() {
+        if (this.logger) {
+            this.logger.info('Dropping full-text search indexes');
+        }
+        await this.adapter.query(`
+      DROP INDEX IF EXISTS idx_content_title_trgm;
+      DROP INDEX IF EXISTS idx_content_body_trgm;
+      DROP INDEX IF EXISTS idx_content_excerpt_trgm;
+      DROP INDEX IF EXISTS idx_content_search_vector;
+
+      -- Drop search_vector column
+      ALTER TABLE content DROP COLUMN IF EXISTS search_vector;
+    `);
+        if (this.logger) {
+            this.logger.info('Full-text search indexes dropped successfully');
+        }
+    }
+    /**
+     * Get search statistics
+     */
+    async getSearchStats() {
+        const result = await this.adapter.query(`
+      SELECT
+        EXISTS (
+          SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm'
+        ) as extension_enabled,
+        EXISTS (
+          SELECT 1 FROM pg_indexes
+          WHERE indexname IN ('idx_content_title_trgm', 'idx_content_search_vector')
+        ) as indexes_exist,
+        EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'content' AND column_name = 'search_vector'
+        ) as search_vector_exists
+    `);
+        const row = result.rows[0];
+        return {
+            extensionEnabled: row.extension_enabled,
+            indexesExist: row.indexes_exist,
+            searchVectorExists: row.search_vector_exists
+        };
+    }
+}
+exports.FullTextSearchManager = FullTextSearchManager;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@bernierllc/database-adapter-postgresql",
+  "version": "1.0.0",
+  "description": "PostgreSQL/Supabase Database Adapter Implementation with RLS, real-time subscriptions, and full-text search",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "postgresql",
+    "supabase",
+    "database",
+    "adapter",
+    "rls",
+    "realtime",
+    "clerk",
+    "connection-pooling"
+  ],
+  "author": "Bernier LLC",
+  "license": "SEE LICENSE IN LICENSE",
+  "dependencies": {
+    "pg": "^8.11.0",
+    "@supabase/supabase-js": "^2.38.0",
+    "@bernierllc/database-adapter-core": "1.0.0",
+    "@bernierllc/logger": "1.0.3",
+    "@bernierllc/crypto-utils": "1.0.2",
+    "@bernierllc/retry-policy": "0.1.6"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.10.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "testcontainers": "^10.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bernierllc": {
+    "category": "core",
+    "integration": {
+      "logger": "required",
+      "docs-suite": "ready",
+      "neverhub": "optional"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:run": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix"
+  }
+}