expo-sqlite 12.2.1 → 13.1.0

package/src/next/hooks.tsx

@@ -1,18 +1,18 @@
 import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
 
-import { openDatabaseAsync, type Database } from './Database';
-import type { OpenOptions } from './NativeDatabase';
+import type { SQLiteOpenOptions } from './NativeDatabase';
+import { openDatabaseAsync, type SQLiteDatabase } from './SQLiteDatabase';
 
 export interface SQLiteProviderProps {
   /**
    * The name of the database file to open.
    */
-  dbName: string;
+  databaseName: string;
 
   /**
    * Open options.
    */
-  options?: OpenOptions;
+  options?: SQLiteOpenOptions;
 
   /**
    * The children to render.
@@ -23,49 +23,130 @@ export interface SQLiteProviderProps {
    * A custom initialization handler to run before rendering the children.
    * You can use this to run database migrations or other setup tasks.
    */
-  initHandler?: (db: Database) => Promise<void>;
+  onInit?: (db: SQLiteDatabase) => Promise<void>;
 
   /**
-   * A custom loading fallback to render before the database is ready.
-   * @default null
+   * Handle errors from SQLiteProvider.
+   * @default rethrow the error
    */
-  loadingFallback?: React.ReactNode;
+  onError?: (error: Error) => void;
 
   /**
-   * Handle errors from SQLiteProvider.
-   * @default rethrow the error
+   * Enable [`React.Suspense`](https://react.dev/reference/react/Suspense) integration.
+   * @default false
+   * @example
+   * ```tsx
+   * export default function App() {
+   *   return (
+   *     <Suspense fallback={<Text>Loading...</Text>}>
+   *       <SQLiteProvider databaseName="test.db" useSuspense={true}>
+   *         <Main />
+   *       </SQLiteProvider>
+   *     </Suspense>
+   *   );
+   * }
+   * ```
    */
-  errorHandler?: (error: Error) => void;
+  useSuspense?: boolean;
 }
 
 /**
  * Create a context for the SQLite database
  */
-const SQLiteContext = createContext<Database | null>(null);
+const SQLiteContext = createContext<SQLiteDatabase | null>(null);
 
 /**
  * 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,
   children,
-  initHandler,
-  loadingFallback,
-  errorHandler,
+  onError,
+  useSuspense = false,
+  ...props
 }: SQLiteProviderProps) {
-  const databaseRef = useRef<Database | null>(null);
+  if (onError != null && useSuspense) {
+    throw new Error('Cannot use `onError` with `useSuspense`, use error boundaries instead.');
+  }
+
+  if (useSuspense) {
+    return <SQLiteProviderSuspense {...props}>{children}</SQLiteProviderSuspense>;
+  }
+
+  return (
+    <SQLiteProviderNonSuspense {...props} onError={onError}>
+      {children}
+    </SQLiteProviderNonSuspense>
+  );
+}
+
+/**
+ * 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 databaseName="test.db">
+ *       <Main />
+ *     </SQLiteProvider>
+ *   );
+ * }
+ *
+ * export function Main() {
+ *   const db = useSQLiteContext();
+ *   console.log('sqlite version', db.getSync('SELECT sqlite_version()'));
+ *   return <View />
+ * }
+ * ```
+ */
+export function useSQLiteContext(): SQLiteDatabase {
+  const context = useContext(SQLiteContext);
+  if (context == null) {
+    throw new Error('useSQLiteContext must be used within a <SQLiteProvider>');
+  }
+  return context;
+}
+
+//#region Internals
+
+type DatabaseInstanceType = Pick<SQLiteProviderProps, 'databaseName' | 'options' | 'onInit'> & {
+  promise: Promise<SQLiteDatabase> | null;
+};
+
+let databaseInstance: DatabaseInstanceType | null = null;
+
+function SQLiteProviderSuspense({
+  databaseName,
+  options,
+  children,
+  onInit,
+}: Omit<SQLiteProviderProps, 'onError' | 'useSuspense'>) {
+  const databasePromise = getDatabaseAsync({
+    databaseName,
+    options,
+    onInit,
+  });
+  const database = use(databasePromise);
+  return <SQLiteContext.Provider value={database}>{children}</SQLiteContext.Provider>;
+}
+
+function SQLiteProviderNonSuspense({
+  databaseName,
+  options,
+  children,
+  onInit,
+  onError,
+}: Omit<SQLiteProviderProps, 'useSuspense'>) {
+  const databaseRef = useRef<SQLiteDatabase | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<Error | null>(null);
 
   useEffect(() => {
     async function setup() {
       try {
-        const db = await openDatabaseAsync(dbName, options);
-        if (initHandler != null) {
-          await initHandler(db);
-        }
+        const db = await openDatabaseWithInitAsync({ databaseName, options, onInit });
         databaseRef.current = db;
         setLoading(false);
       } catch (e) {
@@ -73,7 +154,7 @@ export function SQLiteProvider({
       }
     }
 
-    async function teardown(db: Database | null) {
+    async function teardown(db: SQLiteDatabase | null) {
       try {
         await db?.closeAsync();
       } catch (e) {
@@ -89,48 +170,118 @@ export function SQLiteProvider({
       databaseRef.current = null;
       setLoading(true);
     };
-  }, [dbName, options, initHandler]);
+  }, [databaseName, options, onInit]);
 
   if (error != null) {
     const handler =
-      errorHandler ??
+      onError ??
       ((e) => {
         throw e;
       });
     handler(error);
   }
-
   if (loading || !databaseRef.current) {
-    return loadingFallback != null ? <>{loadingFallback}</> : null;
+    return null;
   }
   return <SQLiteContext.Provider value={databaseRef.current}>{children}</SQLiteContext.Provider>;
 }
 
+function getDatabaseAsync({
+  databaseName,
+  options,
+  onInit,
+}: Pick<SQLiteProviderProps, 'databaseName' | 'options' | 'onInit'>): Promise<SQLiteDatabase> {
+  if (
+    databaseInstance?.promise != null &&
+    databaseInstance?.databaseName === databaseName &&
+    databaseInstance?.options === options &&
+    databaseInstance?.onInit === onInit
+  ) {
+    return databaseInstance.promise;
+  }
+
+  let promise: Promise<SQLiteDatabase>;
+  if (databaseInstance?.promise != null) {
+    promise = databaseInstance.promise
+      .then((db) => {
+        db.closeAsync();
+      })
+      .then(() => {
+        return openDatabaseWithInitAsync({ databaseName, options, onInit });
+      });
+  } else {
+    promise = openDatabaseWithInitAsync({ databaseName, options, onInit });
+  }
+  databaseInstance = {
+    databaseName,
+    options,
+    onInit,
+    promise,
+  };
+  return promise;
+}
+
+async function openDatabaseWithInitAsync({
+  databaseName,
+  options,
+  onInit,
+}: Pick<SQLiteProviderProps, 'databaseName' | 'options' | 'onInit'>): Promise<SQLiteDatabase> {
+  const database = await openDatabaseAsync(databaseName, options);
+  if (onInit != null) {
+    await onInit(database);
+  }
+  return database;
+}
+
+//#endregion
+
+//#region Private Suspense API similar to `React.use`
+
+// Referenced from https://github.com/vercel/swr/blob/1d8110900d1aee3747199bfb377b149b7ff6848e/_internal/src/types.ts#L27-L31
+type ReactUsePromise<T, E extends Error = Error> = Promise<T> & {
+  status?: 'pending' | 'fulfilled' | 'rejected';
+  value?: T;
+  reason?: E;
+};
+
+// Referenced from https://github.com/reactjs/react.dev/blob/6570e6cd79a16ac3b1a2902632eddab7e6abb9ad/src/content/reference/react/Suspense.md
 /**
- * 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 />
- * }
- * ```
+ * A custom hook like [`React.use`](https://react.dev/reference/react/use) hook using private Suspense implementation.
  */
-export function useSQLiteContext(): Database {
-  const context = useContext(SQLiteContext);
-  if (context == null) {
-    throw new Error('useSQLiteContext must be used within a <SQLiteProvider>');
+function use<T>(promise: Promise<T> | ReactUsePromise<T>) {
+  if (isReactUsePromise(promise)) {
+    if (promise.status === 'fulfilled') {
+      if (promise.value === undefined) {
+        throw new Error('[use] Unexpected undefined value from promise');
+      }
+      return promise.value;
+    } else if (promise.status === 'rejected') {
+      throw promise.reason;
+    } else if (promise.status === 'pending') {
+      throw promise;
+    }
+    throw new Error('[use] Promise is in an invalid state');
   }
-  return context;
+
+  const suspensePromise = promise as ReactUsePromise<T>;
+  suspensePromise.status = 'pending';
+  suspensePromise.then(
+    (result: T) => {
+      suspensePromise.status = 'fulfilled';
+      suspensePromise.value = result;
+    },
+    (reason) => {
+      suspensePromise.status = 'rejected';
+      suspensePromise.reason = reason;
+    }
+  );
+  throw suspensePromise;
 }
+
+function isReactUsePromise<T>(
+  promise: Promise<T> | ReactUsePromise<T>
+): promise is ReactUsePromise<T> {
+  return typeof promise === 'object' && promise !== null && 'status' in promise;
+}
+
+//#endregion

package/src/next/index.ts

@@ -1,3 +1,3 @@
-export * from './Database';
-export * from './Statement';
+export * from './SQLiteDatabase';
+export * from './SQLiteStatement';
 export * from './hooks';

package/src/next/paramUtils.ts

@@ -0,0 +1,94 @@
+import {
+  SQLiteBindBlobParams,
+  SQLiteBindParams,
+  SQLiteBindPrimitiveParams,
+  SQLiteBindValue,
+  type SQLiteColumnNames,
+  type SQLiteColumnValues,
+} from './NativeStatement';
+
+/**
+ * Normalize the bind params to data structure that can be passed to native module.
+ * The data structure is a tuple of [primitiveParams, blobParams, shouldPassAsArray].
+ * @hidden
+ */
+export function normalizeParams(
+  ...params: any[]
+): [SQLiteBindPrimitiveParams, SQLiteBindBlobParams, boolean] {
+  let bindParams = params.length > 1 ? params : (params[0] as SQLiteBindParams);
+  if (bindParams == null) {
+    bindParams = [];
+  }
+  if (
+    typeof bindParams !== 'object' ||
+    bindParams instanceof ArrayBuffer ||
+    ArrayBuffer.isView(bindParams)
+  ) {
+    bindParams = [bindParams];
+  }
+  const shouldPassAsArray = Array.isArray(bindParams);
+  if (Array.isArray(bindParams)) {
+    bindParams = bindParams.reduce<Record<string, SQLiteBindValue>>((acc, value, index) => {
+      acc[index] = value;
+      return acc;
+    }, {});
+  }
+
+  const primitiveParams: SQLiteBindPrimitiveParams = {};
+  const blobParams: SQLiteBindBlobParams = {};
+  for (const key in bindParams) {
+    const value = bindParams[key];
+    if (value instanceof Uint8Array) {
+      blobParams[key] = value;
+    } else {
+      primitiveParams[key] = value;
+    }
+  }
+
+  return [primitiveParams, blobParams, shouldPassAsArray];
+}
+
+/**
+ * Compose `columnNames` and `columnValues` to an row object.
+ * @hidden
+ */
+export function composeRow<T>(columnNames: SQLiteColumnNames, columnValues: SQLiteColumnValues): 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: SQLiteColumnNames,
+  columnValuesList: SQLiteColumnValues[]
+): 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;
+}