driftsql 1.0.12 → 1.0.14

package/README.md

@@ -1,187 +1,272 @@
 # DriftSQL
 
-<!-- automd:badges color=yellow -->
-
 [![npm version](https://img.shields.io/npm/v/driftsql?color=yellow)](https://npmjs.com/package/driftsql)
 [![npm downloads](https://img.shields.io/npm/dm/driftsql?color=yellow)](https://npm.chart.dev/driftsql)
 
-<!-- /automd -->
-
-A lightweight SQL client for TypeScript, supporting multiple databases like PostgreSQL, LibSQL, and HTTP-based database services. DriftSQL provides a unified, type-safe interface for database operations across different database drivers.
+A lightweight, type-safe SQL client for TypeScript that supports multiple database drivers. Import only what you need.
 
 ## Features
 
-- 🔐 Type-safe database operations with TypeScript generics
-- 🛡️ SQL injection protection with parameterized queries
-- 🚀 Multiple driver support (PostgreSQL, LibSQL, HTTP)
-- 📝 Auto-completion support for database schema types
-- ⚡ Built-in error handling and connection management
-- 🔄 Unified API across different database types
+- 🔐 **Type-safe** - Full TypeScript support with generics
+- 🚀 **Modular** - Import only the drivers you need
+- 🛡️ **SQL injection protection** - Parameterized queries by default
+- 🔄 **Unified API** - Same interface across all drivers
+- ⚡ **Multiple drivers** - PostgreSQL, LibSQL, MySQL, SQLite
+- 🎯 **Custom drivers** - Easy to implement your own drivers
 
-## Supported Drivers
+## Installation
 
-- **PostgreSQL** - Native PostgreSQL driver via `pg`
-- **LibSQL** - SQLite-compatible databases via `@libsql/client`
-- **HTTP** - HTTP-based database services
+```sh
+npm install driftsql
+```
 
-## Usage
+## Basic Usage
 
-Install the package:
+### Import Individual Drivers
 
-```sh
-# ✨ Auto-detect (supports npm, yarn, pnpm, deno and bun)
-npx nypm install driftsql
-```
+```typescript
+import { PostgresDriver, LibSQLDriver, MySQLDriver, SqliteDriver, SQLClient } from 'driftsql'
 
-Import and use:
+// Use PostgreSQL
+const postgresDriver = new PostgresDriver({
+  connectionString: 'postgresql://user:password@localhost:5432/mydb'
+})
 
-<!-- automd:jsimport cdn name="driftsql" -->
+// Use LibSQL/Turso
+const libsqlDriver = new LibSQLDriver({
+  url: 'libsql://your-database.turso.io',
+  authToken: 'your-auth-token'
+})
 
-**ESM** (Node.js, Bun, Deno)
+// Use MySQL
+const mysqlDriver = new MySQLDriver({
+  connectionString: 'mysql://user:password@localhost:3306/mydb'
+})
 
-```js
-import { DriftSQLClient } from 'driftsql'
+// Use SQLite
+const sqliteDriver = new SqliteDriver({
+  filename: './database.db'
+})
+
+// Create a client with any driver
+const client = new SQLClient({ driver: postgresDriver })
 ```
 
-<!-- /automd -->
+### Factory Functions
 
-## Quick Start
+```typescript
+import { createPostgresClient, createLibSQLClient, createMySQLClient, createSqliteClient } from 'driftsql'
 
-### Define Your Database Schema
+// Quick setup
+const postgresClient = createPostgresClient({
+  connectionString: 'postgresql://user:password@localhost:5432/mydb'
+})
 
-```typescript
-import { DriftSQLClient } from 'driftsql'
+const libsqlClient = createLibSQLClient({
+  url: 'file:local.db'
+})
+
+const mysqlClient = createMySQLClient({
+  connectionString: 'mysql://user:password@localhost:3306/mydb'
+})
 
-// Define your database schema types
+const sqliteClient = createSqliteClient({
+  filename: './database.db'
+})
+```
+
+## Database Operations
+
+### Raw Queries
+
+```typescript
+// Type-safe queries
 interface User {
   id: number
   name: string
   email: string
-  created_at: string
 }
 
-interface Post {
-  id: number
-  title: string
-  content: string | null
-  user_id: number | null
-  published: boolean
-  created_at: Date
-  updated_at: Date
-}
+const result = await client.query<User>('SELECT * FROM users WHERE id = $1', [1])
+console.log(result.rows) // User[]
+console.log(result.rowCount) // number
+```
+
+### Helper Methods
 
+```typescript
 // Define your database schema
 interface MyDatabase {
   users: User
   posts: Post
 }
+
+const client = new SQLClient<MyDatabase>({ driver: postgresDriver })
+
+// Find operations
+const user = await client.findFirst('users', { email: 'user@example.com' })
+const users = await client.findMany('users', { 
+  where: { active: true },
+  limit: 10 
+})
+
+// Insert
+const newUser = await client.insert('users', {
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+
+// Update
+const updatedUser = await client.update('users', 
+  { name: 'Jane Doe' }, 
+  { id: 1 }
+)
+
+// Delete
+const deletedCount = await client.delete('users', { id: 1 })
+```
+
+## Transactions
+
+```typescript
+// Check if driver supports transactions
+if (client.supportsTransactions()) {
+  await client.transaction(async (txClient) => {
+    await txClient.insert('users', { name: 'User 1', email: 'user1@example.com' })
+    await txClient.insert('users', { name: 'User 2', email: 'user2@example.com' })
+    // Both inserts will be committed together
+  })
+}
 ```
 
-### Initialize with PostgreSQL
+## Custom Drivers
+
+Implement your own database driver:
 
 ```typescript
-const db = new DriftSQLClient<MyDatabase>({
-  drivers: {
-    postgres: {
-      connectionString: 'postgresql://user:password@localhost:5432/mydb',
-      // or individual options:
-      // host: 'localhost',
-      // port: 5432,
-      // database: 'mydb',
-      // user: 'user',
-      // password: 'password'
-    },
-  },
-})
+import type { DatabaseDriver, QueryResult } from 'driftsql'
+
+class MyCustomDriver implements DatabaseDriver {
+  async query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>> {
+    // Your implementation here
+    return {
+      rows: [], // T[]
+      rowCount: 0,
+      command: 'SELECT'
+    }
+  }
+
+  async close(): Promise<void> {
+    // Cleanup logic
+  }
+}
+
+// Use your custom driver
+const client = new SQLClient({ driver: new MyCustomDriver() })
 ```
 
-### Initialize with LibSQL
+## Driver-Specific Features
+
+### PostgreSQL HTTP Support
 
 ```typescript
-const db = new DriftSQLClient<MyDatabase>({
-  drivers: {
-    libsql: {
-      url: 'file:local.db',
-      // or for remote:
-      // url: 'libsql://your-database.turso.io',
-      // authToken: 'your-auth-token'
-    },
-  },
+const postgresDriver = new PostgresDriver({
+  experimental: {
+    http: {
+      url: 'https://your-postgres-http-api.com',
+      apiKey: 'your-api-key'
+    }
+  }
 })
 ```
 
-### Initialize with HTTP
+### LibSQL with Turso Serverless
 
 ```typescript
-const db = new DriftSQLClient<MyDatabase>({
-  url: 'https://your-database-api.com',
-  password: 'your-bearer-token',
-  options: {
-    defaultTimeout: 5000, // optional, defaults to 5000ms
-  },
+const libsqlDriver = new LibSQLDriver({
+  url: 'libsql://your-database.turso.io',
+  authToken: 'your-auth-token',
+  useTursoServerlessDriver: true
 })
 ```
 
-### Database Operations
+### SQLite with Prepared Statements
 
 ```typescript
-// Raw SQL queries
-const users = await db.query<User>('SELECT * FROM users WHERE active = $1', [true])
-console.log(users.rows)
+const sqliteDriver = new SqliteDriver({ filename: './db.sqlite' })
+const client = new SQLClient({ driver: sqliteDriver })
 
-// Find operations
-const user = await db.findFirst('users', { email: 'user@example.com' })
-const activeUsers = await db.findMany('users', { active: true })
+if (client.supportsPreparedStatements()) {
+  const stmt = await client.prepare('SELECT * FROM users WHERE id = ?')
+  const result = await stmt.execute([1])
+  await stmt.finalize()
+}
+```
 
-// Insert operations
-const newUser = await db.insert('users', {
-  name: 'John Doe',
-  email: 'john@example.com',
-})
+## Error Handling
 
-// Update operations
-const updatedUser = await db.update('users', { name: 'Jane Doe' }, { id: 1 })
+```typescript
+import { DatabaseError, QueryError, ConnectionError } from 'driftsql'
+
+try {
+  await client.query('SELECT * FROM users')
+} catch (error) {
+  if (error instanceof QueryError) {
+    console.log('Query failed:', error.message)
+    console.log('Driver:', error.driverType)
+  } else if (error instanceof ConnectionError) {
+    console.log('Connection failed:', error.message)
+  }
+}
+```
 
-// Delete operations
-const deleted = await db.delete('users', { id: 1 })
+## Fallback Drivers
 
-// Check server status (HTTP only)
-const status = await db.status()
-console.log(`Database OK: ${status.ok}, Ping: ${status.ping}ms`)
+```typescript
+// Use multiple drivers with automatic fallback
+const client = new SQLClient({
+  driver: primaryDriver,
+  fallbackDrivers: [backupDriver1, backupDriver2]
+})
 
-// Clean up connections
-await db.close()
+// Will try drivers in order until one succeeds
+const result = await client.query('SELECT 1')
 ```
 
-### Constructor Options
+## API Reference
+
+### DatabaseDriver Interface
 
 ```typescript
-interface ClientOptions {
-  url?: string // HTTP server URL (for HTTP driver)
-  password?: string // Bearer token for HTTP authentication
-  drivers?: {
-    libsql?: LibsqlClientConfig // LibSQL configuration
-    postgres?: PoolConfig // PostgreSQL configuration
-    postgresNeonHTTP?: {
-      // Neon configuration (experimental)
-      connectionString: string
-    }
-  }
-  options?: {
-    defaultTimeout?: number // Request timeout in milliseconds
-  }
+interface DatabaseDriver {
+  query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>
+  close(): Promise<void>
 }
 ```
 
-</details>
+### SQLClient
 
-## License
+```typescript
+class SQLClient<DT = any> {
+  constructor(options: { driver: DatabaseDriver; fallbackDrivers?: DatabaseDriver[] })
+  
+  query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>
+  findFirst<K extends keyof DT>(table: K, where?: Partial<DT[K]>): Promise<DT[K] | null>
+  findMany<K extends keyof DT>(table: K, options?: FindManyOptions<DT[K]>): Promise<DT[K][]>
+  insert<K extends keyof DT>(table: K, data: Partial<DT[K]>): Promise<DT[K]>
+  update<K extends keyof DT>(table: K, data: Partial<DT[K]>, where: Partial<DT[K]>): Promise<DT[K] | null>
+  delete<K extends keyof DT>(table: K, where: Partial<DT[K]>): Promise<number>
+  
+  transaction<T>(callback: (client: SQLClient<DT>) => Promise<T>): Promise<T>
+  prepare(sql: string): Promise<PreparedStatement>
+  
+  getDriver(): DatabaseDriver
+  supportsTransactions(): boolean
+  supportsPreparedStatements(): boolean
+  close(): Promise<void>
+}
+```
 
-<!-- automd:contributors license=MIT -->
+## License
 
-Published under the [MIT](https://github.com/lassejlv/driftsql/blob/main/LICENSE) license.
-Made by [community](https://github.com/lassejlv/driftsql/graphs/contributors) 💛
-<br><br>
-<a href="https://github.com/lassejlv/driftsql/graphs/contributors">
-<img src="https://contrib.rocks/image?repo=lassejlv/driftsql" />
-</a>
+Published under the [MIT](https://github.com/lassejlv/driftsql/blob/main/LICENSE) license.

package/dist/index.d.mts

@@ -1,74 +1,160 @@
-type DriverOptions<T = object> = T & {
-    experimental?: Record<string, any>;
-};
+interface QueryResult<T = any> {
+    rows: T[];
+    rowCount: number;
+    command?: string;
+    fields?: QueryField[];
+}
+interface QueryField {
+    name: string;
+    dataTypeID: number;
+}
+interface DatabaseDriver {
+    query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+    close(): Promise<void>;
+}
+interface TransactionCapable {
+    transaction<T>(callback: (driver: DatabaseDriver) => Promise<T>): Promise<T>;
+}
+interface PreparedStatementCapable {
+    prepare(sql: string): Promise<PreparedStatement>;
+}
+interface PreparedStatement {
+    execute<T = any>(params?: any[]): Promise<QueryResult<T>>;
+    finalize(): Promise<void>;
+}
 
 interface PostgresConfig {
     connectionString?: string;
-    options?: DriverOptions<{
-        experimental?: {
-            /**
-             * Enable experimental postgres http support. Using github.com/lassejlv/postgres_http
-             */
-            http?: {
-                url: string;
-                apiKey?: string;
-            };
+    experimental?: {
+        http?: {
+            url: string;
+            apiKey?: string;
         };
-    }>;
+    };
+}
+declare class PostgresDriver implements DatabaseDriver, TransactionCapable {
+    private client;
+    constructor(config: PostgresConfig);
+    query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+    transaction<T>(callback: (driver: DatabaseDriver) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
 }
 
 interface LibSQLConfig {
     url: string;
     authToken?: string;
-    options?: DriverOptions<{
-        experimental?: {
-            useTursoServerlessDriver?: boolean;
-        };
-    }>;
+    useTursoServerlessDriver?: boolean;
+}
+declare class LibSQLDriver implements DatabaseDriver, TransactionCapable {
+    private client;
+    constructor(config: LibSQLConfig);
+    query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+    transaction<T>(callback: (driver: DatabaseDriver) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    private convertLibsqlResult;
 }
 
 interface MySQLConfig {
     connectionString: string;
 }
+declare class MySQLDriver implements DatabaseDriver, TransactionCapable {
+    private client;
+    constructor(config: MySQLConfig);
+    query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+    transaction<T>(callback: (driver: DatabaseDriver) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
 
-type Drivers = ClientOptions['drivers'];
-declare const inspectDB: (drivers: Drivers) => Promise<never>;
+interface SqliteConfig {
+    filename: string;
+    readonly?: boolean;
+}
+declare class SqliteDriver implements DatabaseDriver, TransactionCapable, PreparedStatementCapable {
+    private client;
+    constructor(config: SqliteConfig);
+    query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+    transaction<T>(callback: (driver: DatabaseDriver) => Promise<T>): Promise<T>;
+    prepare(sql: string): Promise<PreparedStatement>;
+    close(): Promise<void>;
+    exec(sql: string): void;
+    backup(filename: string): Promise<void>;
+    pragma(pragma: string): any;
+}
 
-type UnifiedQueryResult<T extends Record<string, any>> = {
-    rows: T[];
-    rowCount: number;
-    command?: string;
-    fields?: Array<{
-        name: string;
-        dataTypeID: number;
-    }>;
-};
-interface ClientOptions {
-    drivers: {
-        libsql?: LibSQLConfig;
-        postgres?: PostgresConfig;
-        mysql?: MySQLConfig;
+interface InspectOptions {
+    driver: DatabaseDriver;
+    outputFile?: string;
+}
+declare const inspectDB: (options: InspectOptions) => Promise<void>;
+declare const inspectPostgres: (config: {
+    connectionString?: string;
+    experimental?: {
+        http?: {
+            url: string;
+            apiKey?: string;
+        };
     };
+}, outputFile?: string) => Promise<void>;
+declare const inspectLibSQL: (config: {
+    url: string;
+    authToken?: string;
+    useTursoServerlessDriver?: boolean;
+}, outputFile?: string) => Promise<void>;
+declare const inspectMySQL: (config: {
+    connectionString: string;
+}, outputFile?: string) => Promise<void>;
+declare const inspectSQLite: (config: {
+    filename: string;
+    readonly?: boolean;
+}, outputFile?: string) => Promise<void>;
+
+interface ClientOptions<T extends DatabaseDriver = DatabaseDriver> {
+    driver: T;
+    fallbackDrivers?: DatabaseDriver[];
 }
-declare class DriftSQLClient<DT> {
-    private postgres?;
-    private libsql?;
-    private mysql?;
-    private drivers;
+declare class SQLClient<DT = any> {
+    private primaryDriver;
+    private fallbackDrivers;
     constructor(options: ClientOptions);
-    readonly inspect: () => Promise<void>;
-    query<T extends Record<string, any>>(query: string, args?: (string | number | boolean | null)[]): Promise<UnifiedQueryResult<T>>;
+    query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+    transaction<T>(callback: (client: SQLClient<DT>) => Promise<T>): Promise<T>;
+    prepare(sql: string): Promise<PreparedStatement>;
     findFirst<K extends keyof DT>(table: K, where?: Partial<DT[K]>): Promise<DT[K] | null>;
     findMany<K extends keyof DT>(table: K, options?: {
         where?: Partial<DT[K]>;
         limit?: number;
+        offset?: number;
     }): Promise<DT[K][]>;
     insert<K extends keyof DT>(table: K, data: Partial<DT[K]>): Promise<DT[K]>;
     update<K extends keyof DT>(table: K, data: Partial<DT[K]>, where: Partial<DT[K]>): Promise<DT[K] | null>;
-    delete<K extends keyof DT>(table: K, where: Partial<DT[K]>): Promise<boolean>;
-    deleteFirst<K extends keyof DT>(table: K, where: Partial<DT[K]>): Promise<boolean>;
+    delete<K extends keyof DT>(table: K, where: Partial<DT[K]>): Promise<number>;
+    getDriver(): DatabaseDriver;
+    supportsTransactions(): boolean;
+    supportsPreparedStatements(): boolean;
     close(): Promise<void>;
 }
+declare function createPostgresClient<DT = any>(config: {
+    connectionString?: string;
+    experimental?: {
+        http?: {
+            url: string;
+            apiKey?: string;
+        };
+    };
+}): SQLClient<DT>;
+declare function createLibSQLClient<DT = any>(config: {
+    url: string;
+    authToken?: string;
+    useTursoServerlessDriver?: boolean;
+}): SQLClient<DT>;
+declare function createMySQLClient<DT = any>(config: {
+    connectionString: string;
+}): SQLClient<DT>;
+declare function createSqliteClient<DT = any>(config: {
+    filename: string;
+    readonly?: boolean;
+}): SQLClient<DT>;
+declare const DriftSQLClient: typeof SQLClient;
 
-export { DriftSQLClient, inspectDB };
-export type { ClientOptions, UnifiedQueryResult };
+export { DriftSQLClient, LibSQLDriver, MySQLDriver, PostgresDriver, SQLClient, SqliteDriver, createLibSQLClient, createMySQLClient, createPostgresClient, createSqliteClient, inspectDB, inspectLibSQL, inspectMySQL, inspectPostgres, inspectSQLite };
+export type { ClientOptions, DatabaseDriver, QueryResult };