0
# Type Definitions
1

2
Complete type definitions and interfaces for the sqlite package, providing TypeScript support for database operations, migrations, and configuration.
3

4
## Core Configuration Types
5

6
```typescript { .api }
7
namespace ISqlite {
8
  /** Database configuration interface for opening connections */
9
  interface Config {
10
    /** 
11
     * Database filename, ":memory:" for anonymous in-memory database,
12
     * or empty string for anonymous disk-based database
13
     */
14
    filename: string;
15
    /** 
16
     * One or more of sqlite3.OPEN_READONLY, sqlite3.OPEN_READWRITE, sqlite3.OPEN_CREATE
17
     * Default: OPEN_READWRITE | OPEN_CREATE
18
     */
19
    mode?: number;
20
    /** 
21
     * Database driver instance (e.g., sqlite3.Database or sqlite3.cached.Database)
22
     * Must conform to sqlite3 API
23
     */
24
    driver: any;
25
  }
26

27
  /** Database configuration options for configure() method */
28
  type ConfigureOption = 'trace' | 'profile' | 'busyTimeout';
29
}
30
```
31

32
## Query and Result Types
33

34
```typescript { .api }
35
namespace ISqlite {
36
  /** Internal SQL object structure used by utility functions */
37
  interface SqlObj {
38
    sql: string;
39
    params?: any[];
40
  }
41

42
  /** SQL template string structure (for sql-template-strings compatibility) */
43
  interface SQLStatement {
44
    sql: string;
45
    values?: any[];
46
  }
47

48
  /** Union type accepting SQL strings or template string objects */
49
  type SqlType = SQLStatement | string;
50

51
  /** Result object returned by run() operations */
52
  interface RunResult<Stmt extends sqlite3.Statement = sqlite3.Statement> {
53
    /** 
54
     * Statement object (automatically finalized after Database.run())
55
     * Not possible to run again after Database.run() execution
56
     */
57
    stmt: Statement<Stmt>;
58
    /** 
59
     * Row ID of the inserted row
60
     * Only valid for successful INSERT statements
61
     */
62
    lastID?: number;
63
    /** 
64
     * Number of rows changed
65
     * Only valid for successful UPDATE or DELETE statements
66
     */
67
    changes?: number;
68
  }
69
}
70
```
71

72
## Migration System Types
73

74
```typescript { .api }
75
namespace IMigrate {
76
  /** Configuration parameters for database migrations */
77
  interface MigrationParams {
78
    /** 
79
     * Force rollback and re-apply the latest migration on each launch
80
     * Useful during development
81
     */
82
    force?: boolean;
83
    /** 
84
     * Migration table name for tracking applied migrations
85
     * Default: 'migrations'
86
     */
87
    table?: string;
88
    /** 
89
     * Path to the migrations folder
90
     * Default: path.join(process.cwd(), 'migrations')
91
     */
92
    migrationsPath?: string;
93
    /** 
94
     * Migration data read from files or provided programmatically
95
     * If provided, migrationsPath will be ignored
96
     */
97
    migrations?: readonly MigrationData[];
98
  }
99

100
  /** Represents a migration file with extracted metadata */
101
  interface MigrationFile {
102
    /** Migration ID extracted from filename */
103
    id: number;
104
    /** Migration name extracted from filename */
105
    name: string;
106
    /** Full filename including extension */
107
    filename: string;
108
  }
109

110
  /** Complete migration data including SQL content */
111
  interface MigrationData {
112
    /** Unique migration ID (must be sequential) */
113
    id: number;
114
    /** Descriptive migration name */
115
    name: string;
116
    /** SQL statements for applying the migration */
117
    up: string;
118
    /** SQL statements for rolling back the migration */
119
    down: string;
120
  }
121
}
122
```
123

124
## Class Type Definitions
125

126
```typescript { .api }
127
/** 
128
 * Main database class providing promise-based SQLite operations
129
 * Generic types allow specification of underlying driver types
130
 */
131
class Database<
132
  Driver extends sqlite3.Database = sqlite3.Database,
133
  Stmt extends sqlite3.Statement = sqlite3.Statement
134
> {
135
  /** Database configuration used during initialization */
136
  config: ISqlite.Config;
137
  /** Underlying sqlite3 database instance */
138
  db: Driver;
139

140
  constructor(config: ISqlite.Config);
141
}
142

143
/** 
144
 * Prepared statement wrapper providing promise-based operations
145
 * Generic type allows specification of underlying statement type
146
 */
147
class Statement<S extends sqlite3.Statement = sqlite3.Statement> {
148
  /** Underlying sqlite3 statement instance */
149
  stmt: S;
150

151
  constructor(stmt: S);
152
}
153
```
154

155
## Generic Type Usage Examples
156

157
The library provides extensive generic type support for type-safe database operations:
158

159
```typescript
160
// Specify database and statement types
161
import sqlite3 from "sqlite3";
162

163
const db = await open<sqlite3.Database, sqlite3.Statement>({
164
  filename: ":memory:",
165
  driver: sqlite3.Database
166
});
167

168
// Type-safe query results
169
interface User {
170
  id: number;
171
  name: string;
172
  email: string;
173
  active: boolean;
174
}
175

176
// get() with typed result
177
const user = await db.get<User>(
178
  "SELECT id, name, email, active FROM users WHERE id = ?",
179
  1
180
);
181
// user is typed as User | undefined
182

183
// all() with typed result array
184
const users = await db.all<User[]>(
185
  "SELECT id, name, email, active FROM users ORDER BY name"
186
);
187
// users is typed as User[]
188

189
// run() with typed RunResult
190
const result = await db.run(
191
  "INSERT INTO users (name, email, active) VALUES (?, ?, ?)",
192
  "Alice",
193
  "alice@example.com",
194
  true
195
);
196
// result.lastID is number | undefined
197
// result.changes is number | undefined
198

199
// Prepared statements with types
200
const stmt = await db.prepare<sqlite3.Statement>(
201
  "SELECT * FROM users WHERE active = ?"
202
);
203

204
const activeUsers = await stmt.all<User[]>(true);
205
await stmt.finalize();
206
```
207

208
## Error Types
209

210
```typescript { .api }
211
/** 
212
 * Error objects are formatted consistently through the formatError utility
213
 * All database errors are converted to standard Error instances with preserved properties
214
 */
215
interface FormattedError extends Error {
216
  /** Original error message */
217
  message: string;
218
  /** Additional error properties from underlying sqlite3 errors */
219
  [key: string]: any;
220
}
221
```
222

223
## Driver Compatibility Types
224

225
The library is designed to work with any sqlite3-compatible driver:
226

227
```typescript { .api }
228
/** Example driver interfaces the library expects */
229
interface DriverInterface {
230
  /** Database constructor */
231
  new (filename: string, callback?: (err: Error | null) => void): DatabaseInstance;
232
  new (filename: string, mode?: number, callback?: (err: Error | null) => void): DatabaseInstance;
233
}
234

235
interface DatabaseInstance {
236
  /** Core database methods that must be implemented */
237
  run(sql: string, ...params: any[]): this;
238
  get(sql: string, ...params: any[]): this;
239
  all(sql: string, ...params: any[]): this;
240
  each(sql: string, ...params: any[]): this;
241
  exec(sql: string, callback?: (err: Error | null) => void): this;
242
  prepare(sql: string, ...params: any[]): StatementInstance;
243
  close(callback?: (err: Error | null) => void): void;
244
  
245
  /** Event emitter methods */
246
  on(event: string, listener: (...args: any[]) => void): this;
247
  
248
  /** Configuration methods */
249
  configure(option: string, value: any): void;
250
  loadExtension(path: string, callback?: (err: Error | null) => void): this;
251
}
252

253
interface StatementInstance {
254
  /** Statement methods that must be implemented */
255
  bind(...params: any[]): this;
256
  reset(callback?: () => void): this;
257
  finalize(callback?: (err: Error) => void): DatabaseInstance;
258
  run(...params: any[]): this;
259
  get(...params: any[]): this;
260
  all(...params: any[]): this;
261
  each(...params: any[]): this;
262
}
263
```
264

265
## Utility Type Functions
266

267
```typescript { .api }
268
/** 
269
 * Convert various SQL input formats to standardized SqlObj format
270
 * Supports both plain strings and sql-template-strings objects
271
 */
272
function toSqlParams(
273
  sql: ISqlite.SqlType,
274
  params?: any[]
275
): ISqlite.SqlObj;
276

277
/** 
278
 * Format error objects to ensure consistent Error instance types
279
 * Preserves all error properties while ensuring Error prototype
280
 */
281
function formatError(err: any): Error;
282
```
283

284
These utility functions handle internal type conversions and error formatting to provide a consistent API experience regardless of input format or underlying driver implementation.