expo-sqlite 12.0.0 → 12.2.0

package/src/next/Statement.ts

@@ -5,12 +5,14 @@ import {
   NativeStatement,
   RunResult,
   VariadicBindParams,
+  type ColumnNames,
+  type ColumnValues,
 } from './NativeStatement';
 
 export { BindParams, BindValue, RunResult, VariadicBindParams };
 
 /**
- * A prepared statement returned by `Database.prepareAsync()` that can be binded with parameters and executed.
+ * A prepared statement returned by [`Database.prepareAsync()`](#prepareasyncsource) or [`Database.prepareSync()`](#preparesyncsource) that can be binded with parameters and executed.
  */
 export class Statement {
   constructor(
@@ -22,11 +24,13 @@ export class Statement {
 
   /**
    * Run the prepared statement and return the result.
-   *
-   * @param params @see `BindParams`
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public runAsync(...params: VariadicBindParams): Promise<RunResult>;
   public runAsync(params: BindParams): Promise<RunResult>;
+  /**
+   * @hidden
+   */
+  public runAsync(...params: VariadicBindParams): Promise<RunResult>;
   public async runAsync(...params: unknown[]): Promise<RunResult> {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
     if (shouldPassAsObject) {
@@ -38,64 +42,78 @@ export class Statement {
 
   /**
    * Iterate the prepared statement and return results as an async iterable.
-   *
-   * @param params @see `BindParams`
-   *
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    * @example
    * ```ts
    * const statement = await db.prepareAsync('SELECT * FROM test');
    * for await (const row of statement.eachAsync<any>()) {
    *   console.log(row);
    * }
+   * await statement.finalizeAsync();
    * ```
    */
-  public eachAsync<T>(...params: VariadicBindParams): AsyncIterableIterator<T>;
   public eachAsync<T>(params: BindParams): AsyncIterableIterator<T>;
+  /**
+   * @hidden
+   */
+  public eachAsync<T>(...params: VariadicBindParams): AsyncIterableIterator<T>;
   public async *eachAsync<T>(...params: unknown[]): AsyncIterableIterator<T> {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
     const func = shouldPassAsObject
       ? this.nativeStatement.objectGetAsync.bind(this.nativeStatement)
       : this.nativeStatement.arrayGetAsync.bind(this.nativeStatement);
 
-    let result: T | null = null;
+    const columnNames = await this.getColumnNamesAsync();
+    let result = null;
     do {
       result = await func(this.nativeDatabase, bindParams);
       if (result != null) {
-        yield result;
+        yield composeRow<T>(columnNames, result);
       }
     } while (result != null);
   }
 
   /**
    * Get one row from the prepared statement.
-   *
-   * @param params @see `BindParams`
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public getAsync<T>(...params: VariadicBindParams): Promise<T | null>;
   public getAsync<T>(params: BindParams): Promise<T | null>;
+  /**
+   * @hidden
+   */
+  public getAsync<T>(...params: VariadicBindParams): Promise<T | null>;
   public async getAsync<T>(...params: unknown[]): Promise<T | null> {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
-    if (shouldPassAsObject) {
-      return (await this.nativeStatement.objectGetAsync(this.nativeDatabase, bindParams)) ?? null;
-    } else {
-      return (await this.nativeStatement.arrayGetAsync(this.nativeDatabase, bindParams)) ?? null;
-    }
+    const columnNames = await this.getColumnNamesAsync();
+    const columnValues = shouldPassAsObject
+      ? await this.nativeStatement.objectGetAsync(this.nativeDatabase, bindParams)
+      : await this.nativeStatement.arrayGetAsync(this.nativeDatabase, bindParams);
+    return columnValues != null ? composeRow<T>(columnNames, columnValues) : null;
   }
 
   /**
    * Get all rows from the prepared statement.
-   *
-   * @param params @see `BindParams`
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public allAsync<T>(...params: VariadicBindParams): Promise<T[]>;
   public allAsync<T>(params: BindParams): Promise<T[]>;
+  /**
+   * @hidden
+   */
+  public allAsync<T>(...params: VariadicBindParams): Promise<T[]>;
   public async allAsync<T>(...params: unknown[]): Promise<T[]> {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
-    if (shouldPassAsObject) {
-      return await this.nativeStatement.objectGetAllAsync(this.nativeDatabase, bindParams);
-    } else {
-      return await this.nativeStatement.arrayGetAllAsync(this.nativeDatabase, bindParams);
-    }
+    const columnNames = await this.getColumnNamesAsync();
+    const columnValuesList = shouldPassAsObject
+      ? await this.nativeStatement.objectGetAllAsync(this.nativeDatabase, bindParams)
+      : await this.nativeStatement.arrayGetAllAsync(this.nativeDatabase, bindParams);
+    return composeRows<T>(columnNames, columnValuesList);
+  }
+
+  /**
+   * Get the column names of the prepared statement.
+   */
+  public getColumnNamesAsync(): Promise<string[]> {
+    return this.nativeStatement.getColumnNamesAsync();
   }
 
   /**
@@ -119,13 +137,14 @@ export class Statement {
 
   /**
    * Run the prepared statement and return the result.
-   *
-   * > **Note:** Running heavy tasks with this function can block the JavaScript thread, affecting performance.
-   *
-   * @param params @see `BindParams`
+   * > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance.
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public runSync(...params: VariadicBindParams): RunResult;
   public runSync(params: BindParams): RunResult;
+  /**
+   * @hidden
+   */
+  public runSync(...params: VariadicBindParams): RunResult;
   public runSync(...params: unknown[]): RunResult {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
     if (shouldPassAsObject) {
@@ -137,70 +156,73 @@ export class Statement {
 
   /**
    * Iterate the prepared statement and return results as an iterable.
-   *
-   * > **Note:** Running heavy tasks with this function can block the JavaScript thread, affecting performance.
-   *
-   * @param params @see `BindParams`
-   *
-   * @example
-   * ```ts
-   * const statement = await db.prepareSync('SELECT * FROM test');
-   * for (const row of statement.eachSync<any>()) {
-   *   console.log(row);
-   * }
-   * ```
+   * > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance.
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public eachSync<T>(...params: VariadicBindParams): IterableIterator<T>;
   public eachSync<T>(params: BindParams): IterableIterator<T>;
+  /**
+   * @hidden
+   */
+  public eachSync<T>(...params: VariadicBindParams): IterableIterator<T>;
   public *eachSync<T>(...params: unknown[]): IterableIterator<T> {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
     const func = shouldPassAsObject
       ? this.nativeStatement.objectGetSync.bind(this.nativeStatement)
       : this.nativeStatement.arrayGetSync.bind(this.nativeStatement);
 
-    let result: T | null = null;
+    const columnNames = this.getColumnNamesSync();
+    let result = null;
     do {
       result = func(this.nativeDatabase, bindParams);
       if (result != null) {
-        yield result;
+        yield composeRow<T>(columnNames, result);
       }
     } while (result != null);
   }
 
   /**
    * Get one row from the prepared statement.
-   *
-   * > **Note:** Running heavy tasks with this function can block the JavaScript thread, affecting performance.
-   *
-   * @param params @see `BindParams`
+   * > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance.
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public getSync<T>(...params: VariadicBindParams): T | null;
   public getSync<T>(params: BindParams): T | null;
+  /**
+   * @hidden
+   */
+  public getSync<T>(...params: VariadicBindParams): T | null;
   public getSync<T>(...params: unknown[]): T | null {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
-    if (shouldPassAsObject) {
-      return this.nativeStatement.objectGetSync(this.nativeDatabase, bindParams) ?? null;
-    } else {
-      return this.nativeStatement.arrayGetSync(this.nativeDatabase, bindParams) ?? null;
-    }
+    const columnNames = this.getColumnNamesSync();
+    const columnValues = shouldPassAsObject
+      ? this.nativeStatement.objectGetSync(this.nativeDatabase, bindParams)
+      : this.nativeStatement.arrayGetSync(this.nativeDatabase, bindParams);
+    return columnValues != null ? composeRow<T>(columnNames, columnValues) : null;
   }
 
   /**
    * Get all rows from the prepared statement.
-   *
-   * > **Note:** Running heavy tasks with this function can block the JavaScript thread, affecting performance.
-   *
-   * @param params @see `BindParams`
+   * > **Note:** Running heavy tasks with this function can block the JavaScript thread and affect performance.
+   * @param params The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See [`BindValue`](#bindvalue) for more information about binding values.
    */
-  public allSync<T>(...params: VariadicBindParams): T[];
   public allSync<T>(params: BindParams): T[];
+  /**
+   * @hidden
+   */
+  public allSync<T>(...params: VariadicBindParams): T[];
   public allSync<T>(...params: unknown[]): T[] {
     const { params: bindParams, shouldPassAsObject } = normalizeParams(...params);
-    if (shouldPassAsObject) {
-      return this.nativeStatement.objectGetAllSync(this.nativeDatabase, bindParams);
-    } else {
-      return this.nativeStatement.arrayGetAllSync(this.nativeDatabase, bindParams);
-    }
+    const columnNames = this.getColumnNamesSync();
+    const columnValuesList = shouldPassAsObject
+      ? this.nativeStatement.objectGetAllSync(this.nativeDatabase, bindParams)
+      : this.nativeStatement.arrayGetAllSync(this.nativeDatabase, bindParams);
+    return composeRows<T>(columnNames, columnValuesList);
+  }
+
+  /**
+   * Get the column names of the prepared statement.
+   */
+  public getColumnNamesSync(): string[] {
+    return this.nativeStatement.getColumnNamesSync();
   }
 
   /**
@@ -232,6 +254,9 @@ export function normalizeParams(...params: any[]): {
   shouldPassAsObject: boolean;
 } {
   let bindParams = params.length > 1 ? params : (params[0] as BindParams);
+  if (bindParams == null) {
+    bindParams = [];
+  }
   if (typeof bindParams !== 'object') {
     bindParams = [bindParams];
   }
@@ -241,3 +266,45 @@ export function normalizeParams(...params: any[]): {
     shouldPassAsObject,
   };
 }
+
+/**
+ * Compose `columnNames` and `columnValues` to an row object.
+ * @hidden
+ */
+export function composeRow<T>(columnNames: ColumnNames, columnValues: ColumnValues): T {
+  const row = {};
+  if (columnNames.length !== columnValues.length) {
+    throw new Error(
+      `Column names and values count mismatch. Names: ${columnNames.length}, Values: ${columnValues.length}`
+    );
+  }
+  for (let i = 0; i < columnNames.length; i++) {
+    row[columnNames[i]] = columnValues[i];
+  }
+  return row as T;
+}
+
+/**
+ * Compose `columnNames` and `columnValuesList` to an array of row objects.
+ * @hidden
+ */
+export function composeRows<T>(columnNames: ColumnNames, columnValuesList: ColumnValues[]): T[] {
+  if (columnValuesList.length === 0) {
+    return [];
+  }
+  if (columnNames.length !== columnValuesList[0].length) {
+    // We only check the first row because SQLite returns the same column count for all rows.
+    throw new Error(
+      `Column names and values count mismatch. Names: ${columnNames.length}, Values: ${columnValuesList[0].length}`
+    );
+  }
+  const results: T[] = [];
+  for (const columnValues of columnValuesList) {
+    const row = {};
+    for (let i = 0; i < columnNames.length; i++) {
+      row[columnNames[i]] = columnValues[i];
+    }
+    results.push(row as T);
+  }
+  return results;
+}

package/src/next/hooks.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useContext, useEffect, useState } from 'react';
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
 
 import { openDatabaseAsync, type Database } from './Database';
 import type { OpenOptions } from './NativeDatabase';
@@ -38,10 +38,15 @@ export interface SQLiteProviderProps {
   errorHandler?: (error: Error) => void;
 }
 
-// Create a context for the SQLite database
+/**
+ * Create a context for the SQLite database
+ */
 const SQLiteContext = createContext<Database | null>(null);
 
-// Create a provider component
+/**
+ * Context.Provider component that provides a SQLite database to all children.
+ * All descendants of this component will be able to access the database using the [`useSQLiteContext`](#usesqlitecontext) hook.
+ */
 export function SQLiteProvider({
   dbName,
   options,
@@ -50,7 +55,7 @@ export function SQLiteProvider({
   loadingFallback,
   errorHandler,
 }: SQLiteProviderProps) {
-  const [database, setDatabase] = useState<Database | null>(null);
+  const databaseRef = useRef<Database | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<Error | null>(null);
 
@@ -58,19 +63,19 @@ export function SQLiteProvider({
     async function setup() {
       try {
         const db = await openDatabaseAsync(dbName, options);
-        setDatabase(db);
         if (initHandler != null) {
           await initHandler(db);
         }
+        databaseRef.current = db;
         setLoading(false);
       } catch (e) {
         setError(e);
       }
     }
 
-    async function teardown() {
+    async function teardown(db: Database | null) {
       try {
-        await database?.closeAsync();
+        await db?.closeAsync();
       } catch (e) {
         setError(e);
       }
@@ -79,7 +84,10 @@ export function SQLiteProvider({
     setup();
 
     return () => {
-      teardown();
+      const db = databaseRef.current;
+      teardown(db);
+      databaseRef.current = null;
+      setLoading(true);
     };
   }, [dbName, options, initHandler]);
 
@@ -92,14 +100,34 @@ export function SQLiteProvider({
     handler(error);
   }
 
-  if (loading) {
+  if (loading || !databaseRef.current) {
     return loadingFallback != null ? <>{loadingFallback}</> : null;
   }
-  return <SQLiteContext.Provider value={database}>{children}</SQLiteContext.Provider>;
+  return <SQLiteContext.Provider value={databaseRef.current}>{children}</SQLiteContext.Provider>;
 }
 
-// Create a hook for accessing the SQLite database context
-export function useSQLiteContext() {
+/**
+ * A global hook for accessing the SQLite database across components.
+ * This hook should only be used within a [`<SQLiteProvider>`](#sqliteprovider) component.
+ *
+ * @example
+ * ```tsx
+ * export default function App() {
+ *   return (
+ *     <SQLiteProvider dbName="test.db">
+ *       <Main />
+ *     </SQLiteProvider>
+ *   );
+ * }
+ *
+ * export function Main() {
+ *   const db = useSQLiteContext();
+ *   console.log('sqlite version', db.getSync('SELECT sqlite_version()'));
+ *   return <View />
+ * }
+ * ```
+ */
+export function useSQLiteContext(): Database {
   const context = useContext(SQLiteContext);
   if (context == null) {
     throw new Error('useSQLiteContext must be used within a <SQLiteProvider>');