@livestore/adapter-expo 0.4.0-dev.2 → 0.4.0-dev.21

package/src/index.ts

@@ -5,19 +5,35 @@ import {
   type BootStatus,
   ClientSessionLeaderThreadProxy,
   Devtools,
+  IntentionalShutdownCause,
   type LockStatus,
   liveStoreStorageFormatVersion,
   makeClientSession,
   type SyncOptions,
-  UnexpectedError,
+  UnknownError,
 } from '@livestore/common'
 import type { DevtoolsOptions, LeaderSqliteDb } from '@livestore/common/leader-thread'
-import { Eventlog, LeaderThreadCtx, makeLeaderThreadLayer } from '@livestore/common/leader-thread'
+import {
+  Eventlog,
+  LeaderThreadCtx,
+  makeLeaderThreadLayer,
+  streamEventsWithSyncState,
+} from '@livestore/common/leader-thread'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { LiveStoreEvent } from '@livestore/common/schema'
 import { shouldNeverHappen } from '@livestore/utils'
 import type { Schema, Scope } from '@livestore/utils/effect'
-import { Effect, Exit, FetchHttpClient, Fiber, Layer, Queue, Stream, SubscriptionRef } from '@livestore/utils/effect'
+import {
+  Effect,
+  Exit,
+  FetchHttpClient,
+  Fiber,
+  Layer,
+  Queue,
+  Schedule,
+  Stream,
+  SubscriptionRef,
+} from '@livestore/utils/effect'
 import * as Webmesh from '@livestore/webmesh'
 import * as ExpoApplication from 'expo-application'
 import * as SQLite from 'expo-sqlite'
@@ -43,30 +59,79 @@ export type MakeDbOptions = {
   clientId?: string
   /** @default 'static' */
   sessionId?: string
+  /**
+   * Warning: This will reset both the app and eventlog database. This should only be used during development.
+   *
+   * @default false
+   */
+  resetPersistence?: boolean
 }
 
-declare global {
-  var RN$Bridgeless: boolean | undefined
-}
-
-const IS_NEW_ARCH = globalThis.RN$Bridgeless === true
+// Expo Go with the New Architecture enables Fabric and TurboModules, but may not run in "bridgeless" mode.
+// Rely on Fabric/TurboModules feature detection instead of RN$Bridgeless.
+const IS_NEW_ARCH =
+  // Fabric global – set when the new renderer is enabled
+  Boolean((globalThis as any).nativeFabricUIManager) ||
+  // TurboModule proxy – indicates new arch TurboModules
+  Boolean((globalThis as any).__turboModuleProxy)
 
+/**
+ * Creates a persisted LiveStore adapter for Expo/React Native applications.
+ *
+ * This adapter stores data in SQLite databases on the device filesystem, providing
+ * persistence across app restarts. It supports optional sync backends for multi-device
+ * synchronization.
+ *
+ * **Requirements:**
+ * - React Native New Architecture (Fabric) must be enabled
+ * - Expo SDK 51+ recommended
+ *
+ * @example
+ * ```ts
+ * import { makePersistedAdapter } from '@livestore/adapter-expo'
+ * import { makeWsSync } from '@livestore/sync-cf/client'
+ *
+ * const adapter = makePersistedAdapter({
+ *   sync: {
+ *     backend: makeWsSync({ url: 'wss://api.example.com/sync' }),
+ *   },
+ *   storage: {
+ *     subDirectory: 'my-app',
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Minimal setup without sync
+ * const adapter = makePersistedAdapter()
+ * ```
+ *
+ * @see https://livestore.dev/docs/reference/adapters/expo for detailed setup guide
+ */
 // TODO refactor with leader-thread code from `@livestore/common/leader-thread`
 export const makePersistedAdapter =
   (options: MakeDbOptions = {}): Adapter =>
   (adapterArgs) =>
     Effect.gen(function* () {
       if (IS_NEW_ARCH === false) {
-        return yield* UnexpectedError.make({
+        return yield* UnknownError.make({
           cause: new Error(
             'The LiveStore Expo adapter requires the new React Native architecture (aka Fabric). See https://docs.expo.dev/guides/new-architecture',
           ),
         })
       }
 
-      const { schema, shutdown, devtoolsEnabled, storeId, bootStatusQueue, syncPayload } = adapterArgs
+      const { schema, shutdown, devtoolsEnabled, storeId, bootStatusQueue, syncPayloadEncoded, syncPayloadSchema } =
+        adapterArgs
 
-      const { storage, clientId = yield* getDeviceId, sessionId = 'static', sync: syncOptions } = options
+      const {
+        storage,
+        clientId = yield* getDeviceId,
+        sessionId = 'static',
+        sync: syncOptions,
+        resetPersistence = false,
+      } = options
 
       yield* Queue.offer(bootStatusQueue, { stage: 'loading' })
 
@@ -74,6 +139,12 @@ export const makePersistedAdapter =
 
       const shutdownChannel = yield* makeShutdownChannel(storeId)
 
+      if (resetPersistence === true) {
+        yield* shutdownChannel.send(IntentionalShutdownCause.make({ reason: 'adapter-reset' }))
+
+        yield* resetExpoPersistence({ storeId, storage, schema })
+      }
+
       yield* shutdownChannel.listen.pipe(
         Stream.flatten(),
         Stream.tap((cause) =>
@@ -85,7 +156,7 @@ export const makePersistedAdapter =
         Effect.forkScoped,
       )
 
-      const devtoolsUrl = getDevtoolsUrl().toString()
+      const devtoolsUrl = devtoolsEnabled ? getDevtoolsUrl().toString() : 'ws://127.0.0.1:4242'
 
       const { leaderThread, initialSnapshot } = yield* makeLeaderThread({
         storeId,
@@ -96,7 +167,8 @@ export const makePersistedAdapter =
         storage: storage ?? {},
         devtoolsEnabled,
         bootStatusQueue,
-        syncPayload,
+        syncPayloadEncoded,
+        syncPayloadSchema,
         devtoolsUrl,
       })
 
@@ -128,10 +200,11 @@ export const makePersistedAdapter =
 
           return () => {}
         },
+        origin: undefined,
       })
 
       return clientSession
-    }).pipe(UnexpectedError.mapToUnexpectedError, Effect.provide(FetchHttpClient.layer), Effect.tapCauseLogPretty)
+    }).pipe(UnknownError.mapToUnknownError, Effect.provide(FetchHttpClient.layer), Effect.tapCauseLogPretty)
 
 const makeLeaderThread = ({
   storeId,
@@ -142,7 +215,8 @@ const makeLeaderThread = ({
   storage,
   devtoolsEnabled,
   bootStatusQueue: bootStatusQueueClientSession,
-  syncPayload,
+  syncPayloadEncoded,
+  syncPayloadSchema,
   devtoolsUrl,
 }: {
   storeId: string
@@ -155,21 +229,19 @@ const makeLeaderThread = ({
   }
   devtoolsEnabled: boolean
   bootStatusQueue: Queue.Queue<BootStatus>
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadEncoded: Schema.JsonValue | undefined
+  syncPayloadSchema: Schema.Schema<any> | undefined
   devtoolsUrl: string
 }) =>
   Effect.gen(function* () {
-    const subDirectory = storage.subDirectory ? `${storage.subDirectory.replace(/\/$/, '')}/` : ''
-    const pathJoin = (...paths: string[]) => paths.join('/').replaceAll(/\/+/g, '/')
-    const directory = pathJoin(SQLite.defaultDatabaseDirectory, subDirectory, storeId)
-
-    const schemaHashSuffix =
-      schema.state.sqlite.migrations.strategy === 'manual' ? 'fixed' : schema.state.sqlite.hash.toString()
-    const stateDatabaseName = `${'livestore-'}${schemaHashSuffix}@${liveStoreStorageFormatVersion}.db`
-    const dbEventlogPath = `${'livestore-'}eventlog@${liveStoreStorageFormatVersion}.db`
+    const { directory, stateDatabaseName, eventlogDatabaseName } = resolveExpoPersistencePaths({
+      storeId,
+      storage,
+      schema,
+    })
 
     const dbState = yield* makeSqliteDb({ _tag: 'file', databaseName: stateDatabaseName, directory })
-    const dbEventlog = yield* makeSqliteDb({ _tag: 'file', databaseName: dbEventlogPath, directory })
+    const dbEventlog = yield* makeSqliteDb({ _tag: 'file', databaseName: eventlogDatabaseName, directory })
 
     const devtoolsOptions = yield* makeDevtoolsOptions({
       devtoolsEnabled,
@@ -192,7 +264,8 @@ const makeLeaderThread = ({
         shutdownChannel: yield* makeShutdownChannel(storeId),
         storeId,
         syncOptions,
-        syncPayload,
+        syncPayloadEncoded,
+        syncPayloadSchema,
       }).pipe(Layer.provideMerge(FetchHttpClient.layer)),
     )
 
@@ -204,6 +277,7 @@ const makeLeaderThread = ({
         extraIncomingMessagesQueue,
         initialState,
         bootStatusQueue,
+        networkStatus,
       } = yield* LeaderThreadCtx
 
       const bootStatusFiber = yield* Queue.takeBetween(bootStatusQueue, 1, 1000).pipe(
@@ -227,16 +301,23 @@ const makeLeaderThread = ({
           push: (batch) =>
             syncProcessor
               .push(
-                batch.map((item) => new LiveStoreEvent.EncodedWithMeta(item)),
+                batch.map((item) => new LiveStoreEvent.Client.EncodedWithMeta(item)),
                 { waitForProcessing: true },
               )
               .pipe(Effect.provide(layer), Effect.scoped),
+          stream: (options) =>
+            streamEventsWithSyncState({
+              dbEventlog,
+              syncState: syncProcessor.syncState,
+              options,
+            }),
         },
         initialState: { leaderHead: initialLeaderHead, migrationsReport: initialState.migrationsReport },
         export: Effect.sync(() => db.export()),
         getEventlogData: Effect.sync(() => dbEventlog.export()),
-        getSyncState: syncProcessor.syncState,
+        syncState: syncProcessor.syncState,
         sendDevtoolsMessage: (message) => extraIncomingMessagesQueue.offer(message),
+        networkStatus,
       })
 
       const initialSnapshot = db.export()
@@ -245,6 +326,57 @@ const makeLeaderThread = ({
     }).pipe(Effect.provide(layer))
   })
 
+const resolveExpoPersistencePaths = ({
+  storeId,
+  storage,
+  schema,
+}: {
+  storeId: string
+  storage: { subDirectory?: string } | undefined
+  schema: LiveStoreSchema
+}) => {
+  const subDirectory = storage?.subDirectory ? `${storage.subDirectory.replace(/\/$/, '')}/` : ''
+  const pathJoin = (...paths: string[]) => paths.join('/').replaceAll(/\/+/g, '/')
+  const directory = pathJoin(SQLite.defaultDatabaseDirectory, subDirectory, storeId)
+
+  const schemaHashSuffix =
+    schema.state.sqlite.migrations.strategy === 'manual' ? 'fixed' : schema.state.sqlite.hash.toString()
+  const stateDatabaseName = `livestore-${schemaHashSuffix}@${liveStoreStorageFormatVersion}.db`
+  const eventlogDatabaseName = `livestore-eventlog@${liveStoreStorageFormatVersion}.db`
+
+  return { directory, stateDatabaseName, eventlogDatabaseName }
+}
+
+const resetExpoPersistence = ({
+  storeId,
+  storage,
+  schema,
+}: {
+  storeId: string
+  storage: MakeDbOptions['storage']
+  schema: LiveStoreSchema
+}) =>
+  Effect.try({
+    try: () => {
+      const { directory, stateDatabaseName, eventlogDatabaseName } = resolveExpoPersistencePaths({
+        storeId,
+        storage,
+        schema,
+      })
+
+      SQLite.deleteDatabaseSync(stateDatabaseName, directory)
+      SQLite.deleteDatabaseSync(eventlogDatabaseName, directory)
+    },
+    catch: (cause) =>
+      new UnknownError({
+        cause,
+        note: `@livestore/adapter-expo: Failed to reset persistence for store ${storeId}`,
+      }),
+  }).pipe(
+    Effect.retry({ schedule: Schedule.exponentialBackoff10Sec }),
+    Effect.withSpan('@livestore/adapter-expo:resetPersistence', { attributes: { storeId } }),
+  )
+
 const makeDevtoolsOptions = ({
   devtoolsEnabled,
   devtoolsUrl,
@@ -259,7 +391,7 @@ const makeDevtoolsOptions = ({
   dbEventlog: LeaderSqliteDb
   storeId: string
   clientId: string
-}): Effect.Effect<DevtoolsOptions, UnexpectedError, Scope.Scope> =>
+}): Effect.Effect<DevtoolsOptions, UnknownError, Scope.Scope> =>
   Effect.sync(() => {
     if (devtoolsEnabled === false) {
       return {

package/src/make-sqlite-db.ts

@@ -9,10 +9,6 @@ import {
 import { EventSequenceNumber } from '@livestore/common/schema'
 import { ensureUint8ArrayBuffer, shouldNeverHappen } from '@livestore/utils'
 import { Effect } from '@livestore/utils/effect'
-// TODO remove `expo-file-system` dependency once expo-sqlite supports `import`
-// // @ts-expect-error package misses `exports`
-// import * as ExpoFs from 'expo-file-system/src/next'
-// import * as ExpoFs from 'expo-file-system'
 import * as SQLite from 'expo-sqlite'
 
 type Metadata = {
@@ -80,7 +76,7 @@ const makeSqliteDb_ = <TMetadata extends Metadata>({
     _tag: 'SqliteDb',
     debug: {
       // Setting initially to root but will be set to correct value shortly after
-      head: EventSequenceNumber.ROOT,
+      head: EventSequenceNumber.Client.ROOT,
     },
     prepare: (queryStr) => {
       try {