1// Definitions copied from `@types/websql` as we want
2// to expose a custom version of the API that:
3// - uses primitive `string` instead of `String`
4// - excludes some methods that are not exposed by our API.
5//
6// Original definitions by: TeamworkGuy2 <https://github.com/TeamworkGuy2>
7
8// @docsMissing
9export interface Window {
10  openDatabase?: (
11    name: string,
12    version: string,
13    displayName: string,
14    estimatedSize: number,
15    creationCallback?: DatabaseCallback
16  ) => Database;
17}
18
19// @docsMissing
20export type DatabaseCallback = (database: Database) => void;
21
22// @needsAudit @docsMissing
23/**
24 * `Database` objects are returned by calls to `SQLite.openDatabase()`. Such an object represents a
25 * connection to a database on your device.
26 */
27export interface Database {
28  version: string;
29
30  /**
31   * Execute a database transaction.
32   * @param callback A function representing the transaction to perform. Takes a Transaction
33   * (see below) as its only parameter, on which it can add SQL statements to execute.
34   * @param errorCallback Called if an error occurred processing this transaction. Takes a single
35   * parameter describing the error.
36   * @param successCallback Called when the transaction has completed executing on the database.
37   */
38  transaction(
39    callback: SQLTransactionCallback,
40    errorCallback?: SQLTransactionErrorCallback,
41    successCallback?: () => void
42  ): void;
43
44  readTransaction(
45    callback: SQLTransactionCallback,
46    errorCallback?: SQLTransactionErrorCallback,
47    successCallback?: () => void
48  ): void;
49}
50
51// @docsMissing
52export type SQLTransactionCallback = (transaction: SQLTransaction) => void;
53
54// @docsMissing
55export type SQLTransactionErrorCallback = (error: SQLError) => void;
56
57// @needsAudit
58/**
59 * A `SQLTransaction` object is passed in as a parameter to the `callback` parameter for the
60 * `db.transaction()` method on a `Database` (see above). It allows enqueuing SQL statements to
61 * perform in a database transaction.
62 */
63export interface SQLTransaction {
64  /**
65   * Enqueue a SQL statement to execute in the transaction. Authors are strongly recommended to make
66   * use of the `?` placeholder feature of the method to avoid against SQL injection attacks, and to
67   * never construct SQL statements on the fly.
68   * @param sqlStatement A string containing a database query to execute expressed as SQL. The string
69   * may contain `?` placeholders, with values to be substituted listed in the `arguments` parameter.
70   * @param args An array of values (numbers, strings or nulls) to substitute for `?` placeholders in the
71   * SQL statement.
72   * @param callback Called when the query is successfully completed during the transaction. Takes
73   * two parameters: the transaction itself, and a `ResultSet` object (see below) with the results
74   * of the query.
75   * @param errorCallback Called if an error occurred executing this particular query in the
76   * transaction. Takes two parameters: the transaction itself, and the error object.
77   */
78  executeSql(
79    sqlStatement: string,
80    args?: (number | string | null)[],
81    callback?: SQLStatementCallback,
82    errorCallback?: SQLStatementErrorCallback
83  ): void;
84}
85
86// @docsMissing
87export type SQLStatementCallback = (transaction: SQLTransaction, resultSet: SQLResultSet) => void;
88
89// @docsMissing
90export type SQLStatementErrorCallback = (transaction: SQLTransaction, error: SQLError) => boolean;
91
92// @needsAudit
93export type SQLResultSet = {
94  /**
95   * The row ID of the row that the SQL statement inserted into the database, if a row was inserted.
96   */
97  insertId?: number;
98  /**
99   * The number of rows that were changed by the SQL statement.
100   */
101  rowsAffected: number;
102  rows: SQLResultSetRowList;
103};
104
105// @needsAudit
106export interface SQLResultSetRowList {
107  /**
108   * The number of rows returned by the query.
109   */
110  length: number;
111  /**
112   * Returns the row with the given `index`. If there is no such row, returns `null`.
113   * @param index Index of row to get.
114   */
115  item(index: number): any;
116  /**
117   * The actual array of rows returned by the query. Can be used directly instead of
118   * getting rows through rows.item().
119   */
120  _array: any[];
121}
122
123// @docsMissing
124export declare class SQLError {
125  static UNKNOWN_ERR: number;
126  static DATABASE_ERR: number;
127  static VERSION_ERR: number;
128  static TOO_LARGE_ERR: number;
129  static QUOTA_ERR: number;
130  static SYNTAX_ERR: number;
131  static CONSTRAINT_ERR: number;
132  static TIMEOUT_ERR: number;
133
134  code: number;
135  message: string;
136}
137
138// @docsMissing
139export interface WebSQLDatabase extends Database {
140  exec(queries: Query[], readOnly: boolean, callback: SQLiteCallback): void;
141
142  /**
143   * Close the database.
144   */
145  closeAsync(): void;
146
147  /**
148   * Delete the database file.
149   * > The database has to be closed prior to deletion.
150   */
151  deleteAsync(): Promise<void>;
152}
153
154// @docsMissing
155export type Query = { sql: string; args: unknown[] };
156
157// @docsMissing
158export type ResultSetError = {
159  error: Error;
160};
161
162// @needsAudit
163/**
164 * `ResultSet` objects are returned through second parameter of the `success` callback for the
165 * `tx.executeSql()` method on a `SQLTransaction` (see above).
166 */
167export type ResultSet = {
168  /**
169   * The row ID of the row that the SQL statement inserted into the database, if a row was inserted.
170   */
171  insertId?: number;
172  /**
173   * The number of rows that were changed by the SQL statement.
174   */
175  rowsAffected: number;
176  rows: { [column: string]: any }[];
177};
178
179// @docsMissing
180export type SQLiteCallback = (
181  error?: Error | null,
182  resultSet?: (ResultSetError | ResultSet)[]
183) => void;
184