@kysera/rls 0.7.2 → 0.7.4

package/src/utils/helpers.ts

@@ -2,87 +2,96 @@
  * Utility helper functions for RLS
  */
 
-import type {
-  RLSContext,
-  PolicyEvaluationContext,
-  Operation,
-} from '../policy/types.js';
+import type { RLSContext, PolicyEvaluationContext, Operation } from '../policy/types.js'
 
 /**
  * Create a policy evaluation context from RLS context
  */
-export function createEvaluationContext<
-  TRow = unknown,
-  TData = unknown
->(
+export function createEvaluationContext<TRow = unknown, TData = unknown>(
   rlsCtx: RLSContext,
   options?: {
-    row?: TRow;
-    data?: TData;
+    row?: TRow
+    data?: TData
   }
 ): PolicyEvaluationContext<unknown, TRow, TData> {
   const ctx: PolicyEvaluationContext<unknown, TRow, TData> = {
-    auth: rlsCtx.auth,
-  };
+    auth: rlsCtx.auth
+  }
 
   if (options?.row !== undefined) {
-    ctx.row = options.row;
+    ctx.row = options.row
   }
 
   if (options?.data !== undefined) {
-    ctx.data = options.data;
+    ctx.data = options.data
   }
 
   if (rlsCtx.request !== undefined) {
-    ctx.request = rlsCtx.request;
+    ctx.request = rlsCtx.request
   }
 
   if (rlsCtx.meta !== undefined) {
-    ctx.meta = rlsCtx.meta as Record<string, unknown>;
+    ctx.meta = rlsCtx.meta as Record<string, unknown>
   }
 
-  return ctx;
+  return ctx
 }
 
 /**
  * Check if a condition function is async
+ *
+ * NOTE: This function checks both constructor.name (for native async functions)
+ * and return type (for transpiled code that returns Promise).
+ * Transpilers often convert async functions to regular functions that return Promise.
  */
 export function isAsyncFunction(fn: unknown): fn is (...args: unknown[]) => Promise<unknown> {
-  return fn instanceof Function && fn.constructor.name === 'AsyncFunction';
+  if (!(fn instanceof Function)) {
+    return false
+  }
+
+  // Check constructor name for native async functions
+  if (fn.constructor.name === 'AsyncFunction') {
+    return true
+  }
+
+  // For transpiled code: call the function with empty args and check if it returns a Promise
+  // This is safe because policy conditions should be pure functions
+  try {
+    const result = (fn as Function)()
+    return result instanceof Promise
+  } catch {
+    // If calling with no args throws, assume it's not async
+    // (async functions that require args should be wrapped in the policy definition)
+    return false
+  }
 }
 
 /**
  * Safely evaluate a policy condition
  */
-export async function safeEvaluate<T>(
-  fn: () => T | Promise<T>,
-  defaultValue: T
-): Promise<T> {
+export async function safeEvaluate<T>(fn: () => T | Promise<T>, defaultValue: T): Promise<T> {
   try {
-    const result = fn();
+    const result = fn()
     if (result instanceof Promise) {
-      return await result;
+      return await result
     }
-    return result;
-  } catch (error) {
+    return result
+  } catch (_error) {
     // Expected failure during policy evaluation - return default value
     // Logger not available in this utility function, error is handled gracefully
-    return defaultValue;
+    return defaultValue
   }
 }
 
 /**
  * Deep merge two objects
  */
-export function deepMerge<T extends Record<string, unknown>>(
-  target: T,
-  source: Partial<T>
-): T {
-  const result = { ...target };
+export function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+  const result = { ...target }
 
   for (const key of Object.keys(source) as (keyof T)[]) {
-    const sourceValue = source[key];
-    const targetValue = result[key];
+    const sourceValue = source[key]
+    const targetValue = result[key]
 
     if (
       sourceValue !== undefined &&
@@ -96,44 +105,42 @@ export function deepMerge<T extends Record<string, unknown>>(
       result[key] = deepMerge(
         targetValue as Record<string, unknown>,
         sourceValue as Record<string, unknown>
-      ) as T[keyof T];
+      ) as T[keyof T]
     } else if (sourceValue !== undefined) {
-      result[key] = sourceValue as T[keyof T];
+      result[key] = sourceValue as T[keyof T]
     }
   }
 
-  return result;
+  return result
 }
 
 /**
  * Create a simple hash for cache keys
  */
 export function hashString(str: string): string {
-  let hash = 0;
+  let hash = 0
   for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = ((hash << 5) - hash) + char;
-    hash = hash & hash; // Convert to 32bit integer
+    const char = str.charCodeAt(i)
+    hash = (hash << 5) - hash + char
+    hash = hash & hash // Convert to 32bit integer
   }
-  return hash.toString(36);
+  return hash.toString(36)
 }
 
 /**
  * Normalize operations to array format
  */
-export function normalizeOperations(
-  operation: Operation | Operation[]
-): Operation[] {
+export function normalizeOperations(operation: Operation | Operation[]): Operation[] {
   if (Array.isArray(operation)) {
     if (operation.includes('all')) {
-      return ['read', 'create', 'update', 'delete'];
+      return ['read', 'create', 'update', 'delete']
     }
-    return operation;
+    return operation
   }
 
   if (operation === 'all') {
-    return ['read', 'create', 'update', 'delete'];
+    return ['read', 'create', 'update', 'delete']
   }
 
-  return [operation];
+  return [operation]
 }

package/src/utils/index.ts

@@ -8,5 +8,16 @@ export {
   safeEvaluate,
   deepMerge,
   hashString,
-  normalizeOperations,
-} from './helpers.js';
+  normalizeOperations
+} from './helpers.js'
+
+export {
+  createQualifiedColumn,
+  applyWhereCondition,
+  createRawCondition,
+  selectFromDynamicTable,
+  whereIdEquals,
+  transformQueryBuilder,
+  hasRawDb,
+  getRawDbSafe
+} from './type-utils.js'

package/src/utils/type-utils.ts

@@ -0,0 +1,155 @@
+/**
+ * Type utilities for RLS plugin
+ *
+ * These utilities provide type-safe wrappers around dynamic operations
+ * that require runtime flexibility beyond TypeScript's compile-time constraints.
+ *
+ * NOTE: This file intentionally uses `any` types to bridge the gap between
+ * Kysely's compile-time type system and RLS's runtime dynamic requirements.
+ * All `any` usage is documented and justified with runtime safety guarantees.
+ *
+ * @module @kysera/rls/utils/type-utils
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { SelectQueryBuilder, Kysely, RawBuilder } from 'kysely'
+import { sql } from 'kysely'
+
+/**
+ * Type-safe wrapper for dynamic column references in WHERE clauses
+ *
+ * Kysely's type system requires compile-time known column names, but RLS policies
+ * work with dynamic column names at runtime. This utility provides a type-safe
+ * boundary for this conversion.
+ *
+ * Type safety is maintained through:
+ * 1. Column names come from validated policy definitions (developer-controlled)
+ * 2. Values are type-checked by policy condition functions
+ * 3. Runtime validation during policy registration
+ *
+ * @param table - Table name (from validated policy schema)
+ * @param column - Column name (from validated policy definition)
+ * @returns Type-safe column reference for Kysely query builder
+ */
+export function createQualifiedColumn(table: string, column: string): string {
+  return `${table}.${column}`
+}
+
+/**
+ * Type-safe wrapper for applying WHERE conditions from RLS filters
+ *
+ * This function encapsulates the type boundary between runtime policy conditions
+ * and Kysely's compile-time type system.
+ *
+ * @param qb - Query builder to modify
+ * @param column - Qualified column name (table.column)
+ * @param operator - Comparison operator
+ * @param value - Value to compare against
+ * @returns Modified query builder
+ */
+export function applyWhereCondition<DB, TB extends keyof DB & string, O>(
+  qb: SelectQueryBuilder<DB, TB, O>,
+  column: string,
+  operator: 'is' | '=' | 'in',
+  value: unknown
+): SelectQueryBuilder<DB, TB, O> {
+  return qb.where(column as any, operator as any, value as any)
+}
+
+/**
+ * Type-safe wrapper for raw SQL expressions
+ *
+ * @param expression - SQL expression (e.g., 'FALSE' for impossible conditions)
+ * @returns Type-safe raw builder for WHERE clauses
+ */
+export function createRawCondition(expression: string): RawBuilder<boolean> {
+  return sql`${sql.raw(expression)}`
+}
+
+/**
+ * Type-safe wrapper for dynamic table queries (used in raw db queries)
+ *
+ * This is used by plugins to bypass RLS filtering when fetching existing rows
+ * for mutation validation. The table name comes from repository configuration
+ * and is validated during repository creation.
+ *
+ * @param db - Kysely database instance
+ * @param table - Table name (from repository config)
+ * @returns Query builder for the table
+ */
+export function selectFromDynamicTable<DB>(
+  db: Kysely<DB>,
+  table: string
+): SelectQueryBuilder<Record<string, unknown>, string, Record<string, unknown>> {
+  return db.selectFrom(table as any).selectAll() as any
+}
+
+/**
+ * Add WHERE clause for primary key equality.
+ * Supports custom primary key column names.
+ *
+ * @param qb - Select query builder
+ * @param id - Primary key value
+ * @param primaryKeyColumn - Primary key column name (default: 'id')
+ * @returns Query builder with ID filter
+ */
+export function whereIdEquals(
+  qb: SelectQueryBuilder<any, any, any>,
+  id: unknown,
+  primaryKeyColumn = 'id'
+): SelectQueryBuilder<any, any, any> {
+  return qb.where(primaryKeyColumn as any, '=', id as any)
+}
+
+/**
+ * Type-safe wrapper for transforming query builders in plugin interceptors
+ *
+ * Used when plugins need to transform a generic query builder (QB) to a specific
+ * type (e.g., SelectQueryBuilder) and back. This is necessary because the executor's
+ * interceptQuery hook receives unconstrained QB types to preserve type inference.
+ *
+ * @param qb - Generic query builder from interceptor
+ * @param operation - Operation type (for runtime validation)
+ * @param transform - Transformation function
+ * @returns Transformed query builder
+ */
+export function transformQueryBuilder<QB>(
+  qb: QB,
+  operation: string,
+  transform: (
+    qb: SelectQueryBuilder<Record<string, unknown>, string, Record<string, unknown>>
+  ) => SelectQueryBuilder<Record<string, unknown>, string, Record<string, unknown>>
+): QB {
+  if (operation !== 'select') {
+    return qb
+  }
+
+  const transformed = transform(qb as any)
+  return transformed as QB
+}
+
+/**
+ * Type guard to check if an executor has a raw db instance
+ *
+ * @param executor - Kysely executor (may have __rawDb property)
+ * @returns True if executor has __rawDb property
+ */
+export function hasRawDb<DB>(
+  executor: Kysely<DB>
+): executor is Kysely<DB> & { __rawDb: Kysely<DB> } {
+  return '__rawDb' in executor && (executor as any).__rawDb !== undefined
+}
+
+/**
+ * Type-safe wrapper to get raw db from executor
+ *
+ * @param executor - Kysely executor with optional __rawDb
+ * @returns Raw db instance or original executor
+ */
+export function getRawDbSafe<DB>(executor: Kysely<DB>): Kysely<DB> {
+  if (hasRawDb(executor)) {
+    return executor.__rawDb
+  }
+  return executor
+}

package/src/version.ts

@@ -0,0 +1,7 @@
+/**
+ * Package version - injected at build time by tsup
+ * Falls back to development version if not replaced
+ * @internal
+ */
+const RAW_VERSION = '__VERSION__'
+export const VERSION = RAW_VERSION.startsWith('__') ? '0.0.0-dev' : RAW_VERSION