@kysera/rls 0.7.3 → 0.7.4

package/src/errors.ts

@@ -2,13 +2,14 @@
  * RLS Error Classes
  *
  * This module provides specialized error classes for Row-Level Security operations.
- * All errors extend the base RLSError class and use unified error codes from @kysera/core
- * for consistency across the Kysera ecosystem.
+ * All errors extend base error classes from @kysera/core for consistency across
+ * the Kysera ecosystem.
  *
  * @module @kysera/rls/errors
  */
 
-import type { ErrorCode } from '@kysera/core';
+import { DatabaseError } from '@kysera/core'
+import type { ErrorCode } from '@kysera/core'
 
 // ============================================================================
 // RLS Error Codes
@@ -32,13 +33,13 @@ export const RLSErrorCodes = {
   /** RLS context validation failed */
   RLS_CONTEXT_INVALID: 'RLS_CONTEXT_INVALID' as ErrorCode,
   /** RLS policy evaluation threw an error */
-  RLS_POLICY_EVALUATION_ERROR: 'RLS_POLICY_EVALUATION_ERROR' as ErrorCode,
-} as const;
+  RLS_POLICY_EVALUATION_ERROR: 'RLS_POLICY_EVALUATION_ERROR' as ErrorCode
+} as const
 
 /**
  * Type for RLS error codes
  */
-export type RLSErrorCode = typeof RLSErrorCodes[keyof typeof RLSErrorCodes];
+export type RLSErrorCode = (typeof RLSErrorCodes)[keyof typeof RLSErrorCodes]
 
 // ============================================================================
 // Base RLS Error
@@ -47,6 +48,7 @@ export type RLSErrorCode = typeof RLSErrorCodes[keyof typeof RLSErrorCodes];
 /**
  * Base class for all RLS-related errors
  *
+ * Extends DatabaseError from @kysera/core for consistency with other Kysera packages.
  * Provides common error functionality including error codes and JSON serialization.
  *
  * @example
@@ -54,9 +56,7 @@ export type RLSErrorCode = typeof RLSErrorCodes[keyof typeof RLSErrorCodes];
  * throw new RLSError('Something went wrong', RLSErrorCodes.RLS_POLICY_INVALID);
  * ```
  */
-export class RLSError extends Error {
-  public readonly code: RLSErrorCode;
-
+export class RLSError extends DatabaseError {
   /**
    * Creates a new RLS error
    *
@@ -64,22 +64,8 @@ export class RLSError extends Error {
    * @param code - RLS error code
    */
   constructor(message: string, code: RLSErrorCode) {
-    super(message);
-    this.name = 'RLSError';
-    this.code = code;
-  }
-
-  /**
-   * Serializes the error to JSON
-   *
-   * @returns JSON representation of the error
-   */
-  toJSON(): Record<string, unknown> {
-    return {
-      name: this.name,
-      message: this.message,
-      code: this.code,
-    };
+    super(message, code)
+    this.name = 'RLSError'
   }
 }
 
@@ -110,15 +96,17 @@ export class RLSContextError extends RLSError {
    *
    * @param message - Error message (defaults to standard message)
    */
-  constructor(message: string = 'No RLS context found. Ensure code runs within withRLSContext()') {
-    super(message, RLSErrorCodes.RLS_CONTEXT_MISSING);
-    this.name = 'RLSContextError';
+  constructor(message = 'No RLS context found. Ensure code runs within withRLSContext()') {
+    super(message, RLSErrorCodes.RLS_CONTEXT_MISSING)
+    this.name = 'RLSContextError'
   }
 }
 
 /**
  * Error thrown when RLS context validation fails
  *
+ * Extends RLSError as context validation failures are RLS-specific errors.
+ *
  * This error occurs when the provided RLS context is invalid or missing
  * required fields.
  *
@@ -138,7 +126,7 @@ export class RLSContextError extends RLSError {
  * ```
  */
 export class RLSContextValidationError extends RLSError {
-  public readonly field: string;
+  public readonly field: string
 
   /**
    * Creates a new context validation error
@@ -147,16 +135,16 @@ export class RLSContextValidationError extends RLSError {
    * @param field - Field that failed validation
    */
   constructor(message: string, field: string) {
-    super(message, RLSErrorCodes.RLS_CONTEXT_INVALID);
-    this.name = 'RLSContextValidationError';
-    this.field = field;
+    super(message, RLSErrorCodes.RLS_CONTEXT_INVALID)
+    this.name = 'RLSContextValidationError'
+    this.field = field
   }
 
   override toJSON(): Record<string, unknown> {
     return {
       ...super.toJSON(),
-      field: this.field,
-    };
+      field: this.field
+    }
   }
 }
 
@@ -183,10 +171,10 @@ export class RLSContextValidationError extends RLSError {
  * ```
  */
 export class RLSPolicyViolation extends RLSError {
-  public readonly operation: string;
-  public readonly table: string;
-  public readonly reason: string;
-  public readonly policyName?: string;
+  public readonly operation: string
+  public readonly table: string
+  public readonly reason: string
+  public readonly policyName?: string
 
   /**
    * Creates a new policy violation error
@@ -196,22 +184,17 @@ export class RLSPolicyViolation extends RLSError {
    * @param reason - Reason for the policy violation
    * @param policyName - Name of the policy that denied access (optional)
    */
-  constructor(
-    operation: string,
-    table: string,
-    reason: string,
-    policyName?: string
-  ) {
+  constructor(operation: string, table: string, reason: string, policyName?: string) {
     super(
       `RLS policy violation: ${operation} on ${table} - ${reason}`,
       RLSErrorCodes.RLS_POLICY_VIOLATION
-    );
-    this.name = 'RLSPolicyViolation';
-    this.operation = operation;
-    this.table = table;
-    this.reason = reason;
+    )
+    this.name = 'RLSPolicyViolation'
+    this.operation = operation
+    this.table = table
+    this.reason = reason
     if (policyName !== undefined) {
-      this.policyName = policyName;
+      this.policyName = policyName
     }
   }
 
@@ -220,12 +203,12 @@ export class RLSPolicyViolation extends RLSError {
       ...super.toJSON(),
       operation: this.operation,
       table: this.table,
-      reason: this.reason,
-    };
+      reason: this.reason
+    }
     if (this.policyName !== undefined) {
-      json['policyName'] = this.policyName;
+      json['policyName'] = this.policyName
     }
-    return json;
+    return json
   }
 }
 
@@ -250,10 +233,10 @@ export class RLSPolicyViolation extends RLSError {
  * ```
  */
 export class RLSPolicyEvaluationError extends RLSError {
-  public readonly operation: string;
-  public readonly table: string;
-  public readonly policyName?: string;
-  public readonly originalError?: Error;
+  public readonly operation: string
+  public readonly table: string
+  public readonly policyName?: string
+  public readonly originalError?: Error
 
   /**
    * Creates a new policy evaluation error
@@ -274,18 +257,18 @@ export class RLSPolicyEvaluationError extends RLSError {
     super(
       `RLS policy evaluation error during ${operation} on ${table}: ${message}`,
       RLSErrorCodes.RLS_POLICY_EVALUATION_ERROR
-    );
-    this.name = 'RLSPolicyEvaluationError';
-    this.operation = operation;
-    this.table = table;
+    )
+    this.name = 'RLSPolicyEvaluationError'
+    this.operation = operation
+    this.table = table
     if (policyName !== undefined) {
-      this.policyName = policyName;
+      this.policyName = policyName
     }
     if (originalError !== undefined) {
-      this.originalError = originalError;
+      this.originalError = originalError
       // Preserve the original stack trace for debugging
       if (originalError.stack) {
-        this.stack = `${this.stack}\n\nCaused by:\n${originalError.stack}`;
+        this.stack = `${this.stack}\n\nCaused by:\n${originalError.stack}`
       }
     }
   }
@@ -294,18 +277,18 @@ export class RLSPolicyEvaluationError extends RLSError {
     const json: Record<string, unknown> = {
       ...super.toJSON(),
       operation: this.operation,
-      table: this.table,
-    };
+      table: this.table
+    }
     if (this.policyName !== undefined) {
-      json['policyName'] = this.policyName;
+      json['policyName'] = this.policyName
     }
     if (this.originalError !== undefined) {
       json['originalError'] = {
         name: this.originalError.name,
-        message: this.originalError.message,
-      };
+        message: this.originalError.message
+      }
     }
-    return json;
+    return json
   }
 }
 
@@ -316,6 +299,8 @@ export class RLSPolicyEvaluationError extends RLSError {
 /**
  * Error thrown when RLS schema validation fails
  *
+ * Extends RLSError as schema validation failures are RLS-specific errors.
+ *
  * This error occurs when the RLS schema definition is invalid or contains
  * configuration errors.
  *
@@ -339,7 +324,7 @@ export class RLSPolicyEvaluationError extends RLSError {
  * ```
  */
 export class RLSSchemaError extends RLSError {
-  public readonly details: Record<string, unknown>;
+  public readonly details: Record<string, unknown>
 
   /**
    * Creates a new schema validation error
@@ -348,15 +333,15 @@ export class RLSSchemaError extends RLSError {
    * @param details - Additional details about the validation failure
    */
   constructor(message: string, details: Record<string, unknown> = {}) {
-    super(message, RLSErrorCodes.RLS_SCHEMA_INVALID);
-    this.name = 'RLSSchemaError';
-    this.details = details;
+    super(message, RLSErrorCodes.RLS_SCHEMA_INVALID)
+    this.name = 'RLSSchemaError'
+    this.details = details
   }
 
   override toJSON(): Record<string, unknown> {
     return {
       ...super.toJSON(),
-      details: this.details,
-    };
+      details: this.details
+    }
   }
 }

package/src/index.ts

@@ -12,20 +12,20 @@
 // ============================================================================
 
 // Schema definition
-export { defineRLSSchema, mergeRLSSchemas } from './policy/schema.js';
+export { defineRLSSchema, mergeRLSSchemas } from './policy/schema.js'
 
 // Policy builders
-export { allow, deny, filter, validate, type PolicyOptions } from './policy/builder.js';
+export { allow, deny, filter, validate, type PolicyOptions } from './policy/builder.js'
 
 // Policy registry (for advanced use cases)
-export { PolicyRegistry } from './policy/registry.js';
+export { PolicyRegistry } from './policy/registry.js'
 
 // ============================================================================
 // Plugin
 // ============================================================================
 
-export { rlsPlugin } from './plugin.js';
-export type { RLSPluginOptions } from './plugin.js';
+export { rlsPlugin, RLSPluginOptionsSchema } from './plugin.js'
+export type { RLSPluginOptions } from './plugin.js'
 
 // ============================================================================
 // Context Management
@@ -36,8 +36,8 @@ export {
   createRLSContext,
   withRLSContext,
   withRLSContextAsync,
-  type CreateRLSContextOptions,
-} from './context/index.js';
+  type CreateRLSContextOptions
+} from './context/index.js'
 
 // ============================================================================
 // Types
@@ -64,8 +64,8 @@ export type {
   // Evaluation types
   PolicyEvaluationContext,
   CompiledPolicy,
-  CompiledFilterPolicy,
-} from './policy/types.js';
+  CompiledFilterPolicy
+} from './policy/types.js'
 
 // ============================================================================
 // Errors
@@ -79,8 +79,8 @@ export {
   RLSSchemaError,
   RLSContextValidationError,
   RLSErrorCodes,
-  type RLSErrorCode,
-} from './errors.js';
+  type RLSErrorCode
+} from './errors.js'
 
 // ============================================================================
 // Utilities
@@ -92,5 +92,5 @@ export {
   isAsyncFunction,
   safeEvaluate,
   deepMerge,
-  hashString,
-} from './utils/index.js';
+  hashString
+} from './utils/index.js'

package/src/native/README.md

@@ -14,14 +14,14 @@ This module provides native PostgreSQL Row-Level Security (RLS) policy generatio
 ### 1. Define RLS Schema with Native PostgreSQL Support
 
 ```typescript
-import type { RLSSchema } from '@kysera/rls';
+import type { RLSSchema } from '@kysera/rls'
 
 interface Database {
   users: {
-    id: number;
-    email: string;
-    tenant_id: string;
-  };
+    id: number
+    email: string
+    tenant_id: string
+  }
 }
 
 const rlsSchema: RLSSchema<Database> = {
@@ -33,59 +33,59 @@ const rlsSchema: RLSSchema<Database> = {
         name: 'users_read_own',
         condition: () => true, // ORM-side condition
         using: 'id = rls_current_user_id()::integer', // Native PostgreSQL
-        role: 'authenticated',
-      },
-    ],
-  },
-};
+        role: 'authenticated'
+      }
+    ]
+  }
+}
 ```
 
 ### 2. Generate PostgreSQL Statements
 
 ```typescript
-import { PostgresRLSGenerator } from '@kysera/rls/native';
+import { PostgresRLSGenerator } from '@kysera/rls/native'
 
-const generator = new PostgresRLSGenerator();
+const generator = new PostgresRLSGenerator()
 
 // Generate RLS policies
 const statements = generator.generateStatements(rlsSchema, {
   schemaName: 'public',
   policyPrefix: 'app_rls',
-  force: true, // Force RLS on table owners
-});
+  force: true // Force RLS on table owners
+})
 
 // Generate context functions
-const contextFunctions = generator.generateContextFunctions();
+const contextFunctions = generator.generateContextFunctions()
 
 // Generate cleanup statements
 const dropStatements = generator.generateDropStatements(rlsSchema, {
   schemaName: 'public',
-  policyPrefix: 'app_rls',
-});
+  policyPrefix: 'app_rls'
+})
 ```
 
 ### 3. Generate Kysely Migration
 
 ```typescript
-import { RLSMigrationGenerator } from '@kysera/rls/native';
+import { RLSMigrationGenerator } from '@kysera/rls/native'
 
-const migrationGenerator = new RLSMigrationGenerator();
+const migrationGenerator = new RLSMigrationGenerator()
 
 const migrationContent = migrationGenerator.generateMigration(rlsSchema, {
   name: 'setup_rls',
   schemaName: 'public',
   policyPrefix: 'app_rls',
   includeContextFunctions: true,
-  force: true,
-});
+  force: true
+})
 
 // Get suggested filename with timestamp
-const filename = migrationGenerator.generateFilename('setup_rls');
+const filename = migrationGenerator.generateFilename('setup_rls')
 // Example: 20231208_123456_setup_rls.ts
 
 // Write to migrations directory
-import fs from 'fs';
-fs.writeFileSync(`migrations/${filename}`, migrationContent);
+import fs from 'fs'
+fs.writeFileSync(`migrations/${filename}`, migrationContent)
 ```
 
 ### 4. Sync Context to PostgreSQL Session
@@ -141,13 +141,13 @@ Extend your Kysera policy definitions with native PostgreSQL support:
 
 ### Operations
 
-| Kysera | PostgreSQL |
-|--------|------------|
-| `read` | `SELECT` |
-| `create` | `INSERT` |
-| `update` | `UPDATE` |
-| `delete` | `DELETE` |
-| `all` | `ALL` |
+| Kysera   | PostgreSQL |
+| -------- | ---------- |
+| `read`   | `SELECT`   |
+| `create` | `INSERT`   |
+| `update` | `UPDATE`   |
+| `delete` | `DELETE`   |
+| `all`    | `ALL`      |
 
 ## Context Functions
 
@@ -192,20 +192,21 @@ const rlsSchema: RLSSchema<Database> = {
         name: 'posts_read_tenant',
         condition: () => true,
         using: 'tenant_id = rls_current_tenant_id()',
-        role: 'authenticated',
+        role: 'authenticated'
       },
       {
         type: 'allow',
         operation: 'create',
         name: 'posts_create_own',
         condition: () => true,
-        withCheck: 'user_id = rls_current_user_id()::integer AND tenant_id = rls_current_tenant_id()',
-        role: 'authenticated',
-      },
+        withCheck:
+          'user_id = rls_current_user_id()::integer AND tenant_id = rls_current_tenant_id()',
+        role: 'authenticated'
+      }
     ],
-    defaultDeny: true,
-  },
-};
+    defaultDeny: true
+  }
+}
 ```
 
 ### Role-Based Access Control
@@ -219,21 +220,21 @@ const rlsSchema: RLSSchema<Database> = {
         operation: 'all',
         name: 'admin_full_access',
         condition: () => true,
-        using: 'rls_has_role(\'admin\')',
-        role: 'authenticated',
+        using: "rls_has_role('admin')",
+        role: 'authenticated'
       },
       {
         type: 'deny',
         operation: 'all',
         name: 'deny_non_admin',
         condition: () => true,
-        using: 'NOT rls_has_role(\'admin\')',
-        role: 'authenticated',
-      },
+        using: "NOT rls_has_role('admin')",
+        role: 'authenticated'
+      }
     ],
-    defaultDeny: true,
-  },
-};
+    defaultDeny: true
+  }
+}
 ```
 
 ### System Bypass
@@ -267,6 +268,7 @@ CREATE INDEX idx_posts_user ON posts(user_id);
 ## Migration Workflow
 
 1. **Generate Migration**:
+
    ```bash
    npx tsx -e "import { RLSMigrationGenerator } from './src/native'; ..."
    ```
@@ -274,6 +276,7 @@ CREATE INDEX idx_posts_user ON posts(user_id);
 2. **Review Generated SQL**: Check migration file before applying
 
 3. **Run Migration**:
+
    ```bash
    npx kysely migrate:latest
    ```

package/src/native/index.ts

@@ -2,10 +2,7 @@ export {
   PostgresRLSGenerator,
   syncContextToPostgres,
   clearPostgresContext,
-  type PostgresRLSOptions,
-} from './postgres.js';
+  type PostgresRLSOptions
+} from './postgres.js'
 
-export {
-  RLSMigrationGenerator,
-  type MigrationOptions,
-} from './migration.js';
+export { RLSMigrationGenerator, type MigrationOptions } from './migration.js'

package/src/native/migration.ts

@@ -1,14 +1,14 @@
-import type { RLSSchema } from '../policy/types.js';
-import { PostgresRLSGenerator, type PostgresRLSOptions } from './postgres.js';
+import type { RLSSchema } from '../policy/types.js'
+import { PostgresRLSGenerator, type PostgresRLSOptions } from './postgres.js'
 
 /**
  * Options for migration generation
  */
 export interface MigrationOptions extends PostgresRLSOptions {
   /** Migration name */
-  name?: string;
+  name?: string
   /** Include context functions in migration */
-  includeContextFunctions?: boolean;
+  includeContextFunctions?: boolean
 }
 
 /**
@@ -16,27 +16,20 @@ export interface MigrationOptions extends PostgresRLSOptions {
  * Generates Kysely migration files for RLS policies
  */
 export class RLSMigrationGenerator {
-  private generator = new PostgresRLSGenerator();
+  private generator = new PostgresRLSGenerator()
 
   /**
    * Generate migration file content
    */
-  generateMigration<DB>(
-    schema: RLSSchema<DB>,
-    options: MigrationOptions = {}
-  ): string {
-    const {
-      name = 'rls_policies',
-      includeContextFunctions = true,
-      ...generatorOptions
-    } = options;
+  generateMigration<DB>(schema: RLSSchema<DB>, options: MigrationOptions = {}): string {
+    const { name = 'rls_policies', includeContextFunctions = true, ...generatorOptions } = options
 
-    const upStatements = this.generator.generateStatements(schema, generatorOptions);
-    const downStatements = this.generator.generateDropStatements(schema, generatorOptions);
+    const upStatements = this.generator.generateStatements(schema, generatorOptions)
+    const downStatements = this.generator.generateDropStatements(schema, generatorOptions)
 
     const contextFunctions = includeContextFunctions
       ? this.generator.generateContextFunctions()
-      : '';
+      : ''
 
     return `import { Kysely, sql } from 'kysely';
 
@@ -48,16 +41,22 @@ export class RLSMigrationGenerator {
  */
 
 export async function up(db: Kysely<any>): Promise<void> {
-${includeContextFunctions ? `  // Create RLS context functions
+${
+  includeContextFunctions
+    ? `  // Create RLS context functions
   await sql.raw(\`${this.escapeTemplate(contextFunctions)}\`).execute(db);
 
-` : ''}  // Enable RLS and create policies
+`
+    : ''
+}  // Enable RLS and create policies
 ${upStatements.map(s => `  await sql.raw(\`${this.escapeTemplate(s)}\`).execute(db);`).join('\n')}
 }
 
 export async function down(db: Kysely<any>): Promise<void> {
 ${downStatements.map(s => `  await sql.raw(\`${this.escapeTemplate(s)}\`).execute(db);`).join('\n')}
-${includeContextFunctions ? `
+${
+  includeContextFunctions
+    ? `
   // Drop RLS context functions
   await sql.raw(\`
     DROP FUNCTION IF EXISTS rls_current_user_id();
@@ -67,26 +66,29 @@ ${includeContextFunctions ? `
     DROP FUNCTION IF EXISTS rls_current_permissions();
     DROP FUNCTION IF EXISTS rls_has_permission(text);
     DROP FUNCTION IF EXISTS rls_is_system();
-  \`).execute(db);` : ''}
+  \`).execute(db);`
+    : ''
 }
-`;
+}
+`
   }
 
   /**
    * Escape template literal for embedding in string
    */
   private escapeTemplate(str: string): string {
-    return str.replace(/`/g, '\\`').replace(/\$/g, '\\$');
+    return str.replace(/`/g, '\\`').replace(/\$/g, '\\$')
   }
 
   /**
    * Generate migration filename with timestamp
    */
-  generateFilename(name: string = 'rls_policies'): string {
-    const timestamp = new Date().toISOString()
+  generateFilename(name = 'rls_policies'): string {
+    const timestamp = new Date()
+      .toISOString()
       .replace(/[-:]/g, '')
       .replace('T', '_')
-      .replace(/\..+/, '');
-    return `${timestamp}_${name}.ts`;
+      .replace(/\..+/, '')
+    return `${timestamp}_${name}.ts`
   }
 }