@livestore/adapter-expo 0.4.0-dev.9 → 0.5.0-dev.0

package/src/index.ts

@@ -9,13 +9,19 @@ import {
   type LockStatus,
   liveStoreStorageFormatVersion,
   makeClientSession,
+  StateHead,
   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 { getStateDbBaseName, LiveStoreEvent } from '@livestore/common/schema'
 import { shouldNeverHappen } from '@livestore/utils'
 import type { Schema, Scope } from '@livestore/utils/effect'
 import {
@@ -42,7 +48,12 @@ export type MakeDbOptions = {
   sync?: SyncOptions
   storage?: {
     /**
-     * Relative to expo-sqlite's default directory
+     * The directory where the database file is located.
+     * @default SQLite.defaultDatabaseDirectory
+     */
+    directory?: string
+    /**
+     * Sub-directory relative to the configured `directory` (or expo-sqlite's default directory if not specified).
      *
      * Example of a resulting path for `subDirectory: 'my-app'`:
      * `/data/Containers/Data/Application/<APP_UUID>/Documents/ExponentExperienceData/@<USERNAME>/<APPNAME>/SQLite/my-app/<STORE_ID>/livestore-eventlog@3.db`
@@ -62,26 +73,63 @@ export type MakeDbOptions = {
   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,
@@ -104,9 +152,9 @@ export const makePersistedAdapter =
       }
 
       yield* shutdownChannel.listen.pipe(
-        Stream.flatten(),
+        Stream.mapEffect(Effect.fromResult),
         Stream.tap((cause) =>
-          shutdown(cause._tag === 'LiveStore.IntentionalShutdownCause' ? Exit.succeed(cause) : Exit.fail(cause)),
+          shutdown(cause._tag === 'IntentionalShutdownCause' ? Exit.succeed(cause) : Exit.fail(cause)),
         ),
         Stream.runDrain,
         Effect.interruptible,
@@ -114,7 +162,7 @@ export const makePersistedAdapter =
         Effect.forkScoped,
       )
 
-      const devtoolsUrl = getDevtoolsUrl().toString()
+      const devtoolsUrl = devtoolsEnabled === true ? getDevtoolsUrl().toString() : 'ws://127.0.0.1:4242'
 
       const { leaderThread, initialSnapshot } = yield* makeLeaderThread({
         storeId,
@@ -125,11 +173,14 @@ export const makePersistedAdapter =
         storage: storage ?? {},
         devtoolsEnabled,
         bootStatusQueue,
-        syncPayload,
+        syncPayloadEncoded,
+        syncPayloadSchema,
         devtoolsUrl,
       })
 
-      const sqliteDb = yield* makeSqliteDb({ _tag: 'in-memory' })
+      const sqliteDb = yield* Effect.acquireRelease(makeSqliteDb({ _tag: 'in-memory' }), (db) =>
+        Effect.try(() => db.close()).pipe(Effect.ignore),
+      )
       sqliteDb.import(initialSnapshot)
 
       const clientSession = yield* makeClientSession({
@@ -142,7 +193,7 @@ export const makePersistedAdapter =
         sqliteDb,
         webmeshMode: 'proxy',
         connectWebmeshNode: Effect.fnUntraced(function* ({ webmeshNode }) {
-          if (devtoolsEnabled) {
+          if (devtoolsEnabled === true) {
             yield* Webmesh.connectViaWebSocket({
               node: webmeshNode,
               url: devtoolsUrl,
@@ -157,10 +208,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,
@@ -171,7 +223,8 @@ const makeLeaderThread = ({
   storage,
   devtoolsEnabled,
   bootStatusQueue: bootStatusQueueClientSession,
-  syncPayload,
+  syncPayloadEncoded,
+  syncPayloadSchema,
   devtoolsUrl,
 }: {
   storeId: string
@@ -180,11 +233,13 @@ const makeLeaderThread = ({
   makeSqliteDb: MakeExpoSqliteDb
   syncOptions: SyncOptions | undefined
   storage: {
+    directory?: string
     subDirectory?: string
   }
   devtoolsEnabled: boolean
   bootStatusQueue: Queue.Queue<BootStatus>
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadEncoded: Schema.Json | undefined
+  syncPayloadSchema: Schema.Decoder<Schema.Json> | undefined
   devtoolsUrl: string
 }) =>
   Effect.gen(function* () {
@@ -194,8 +249,14 @@ const makeLeaderThread = ({
       schema,
     })
 
-    const dbState = yield* makeSqliteDb({ _tag: 'file', databaseName: stateDatabaseName, directory })
-    const dbEventlog = yield* makeSqliteDb({ _tag: 'file', databaseName: eventlogDatabaseName, directory })
+    const dbState = yield* Effect.acquireRelease(
+      makeSqliteDb({ _tag: 'file', databaseName: stateDatabaseName, directory }),
+      (db) => Effect.try(() => db.close()).pipe(Effect.ignore),
+    )
+    const dbEventlog = yield* Effect.acquireRelease(
+      makeSqliteDb({ _tag: 'file', databaseName: eventlogDatabaseName, directory }),
+      (db) => Effect.try(() => db.close()).pipe(Effect.ignore),
+    )
 
     const devtoolsOptions = yield* makeDevtoolsOptions({
       devtoolsEnabled,
@@ -206,7 +267,7 @@ const makeLeaderThread = ({
       clientId,
     })
 
-    const layer = yield* Layer.memoize(
+    const layer = yield* Layer.build(
       makeLeaderThreadLayer({
         clientId,
         dbState,
@@ -218,8 +279,9 @@ const makeLeaderThread = ({
         shutdownChannel: yield* makeShutdownChannel(storeId),
         storeId,
         syncOptions,
-        syncPayload,
-      }).pipe(Layer.provideMerge(FetchHttpClient.layer)),
+        syncPayloadEncoded,
+        syncPayloadSchema,
+      }).pipe(Layer.provide(StateHead.layer({ dbState })), Layer.provideMerge(FetchHttpClient.layer)),
     )
 
     return yield* Effect.gen(function* () {
@@ -230,6 +292,7 @@ const makeLeaderThread = ({
         extraIncomingMessagesQueue,
         initialState,
         bootStatusQueue,
+        networkStatus,
       } = yield* LeaderThreadCtx
 
       const bootStatusFiber = yield* Queue.takeBetween(bootStatusQueue, 1, 1000).pipe(
@@ -239,7 +302,7 @@ const makeLeaderThread = ({
         Effect.forkScoped,
       )
 
-      yield* Queue.awaitShutdown(bootStatusQueueClientSession).pipe(
+      yield* Queue.await(bootStatusQueueClientSession).pipe(
         Effect.andThen(Fiber.interrupt(bootStatusFiber)),
         Effect.tapCauseLogPretty,
         Effect.forkScoped,
@@ -251,18 +314,24 @@ const makeLeaderThread = ({
         events: {
           pull: ({ cursor }) => syncProcessor.pull({ cursor }),
           push: (batch) =>
-            syncProcessor
-              .push(
-                batch.map((item) => new LiveStoreEvent.EncodedWithMeta(item)),
-                { waitForProcessing: true },
-              )
-              .pipe(Effect.provide(layer), Effect.scoped),
+            syncProcessor.push(batch.map((item) => new LiveStoreEvent.Client.EncodedWithMeta(item))),
+          stream: (options) =>
+            streamEventsWithSyncState({
+              dbEventlog,
+              syncState: syncProcessor.syncState,
+              options,
+            }),
+        },
+        initialState: {
+          leaderHead: initialLeaderHead,
+          migrationsReport: initialState.migrationsReport,
+          storageMode: 'persisted',
         },
-        initialState: { leaderHead: initialLeaderHead, migrationsReport: initialState.migrationsReport },
         export: Effect.sync(() => db.export()),
         getEventlogData: Effect.sync(() => dbEventlog.export()),
-        getSyncState: syncProcessor.syncState,
-        sendDevtoolsMessage: (message) => extraIncomingMessagesQueue.offer(message),
+        syncState: syncProcessor.syncState,
+        sendDevtoolsMessage: (message) => Queue.offer(extraIncomingMessagesQueue, message),
+        networkStatus,
       })
 
       const initialSnapshot = db.export()
@@ -277,16 +346,16 @@ const resolveExpoPersistencePaths = ({
   schema,
 }: {
   storeId: string
-  storage: { subDirectory?: string } | undefined
   schema: LiveStoreSchema
+  storage: { directory?: string; subDirectory?: string } | undefined
 }) => {
-  const subDirectory = storage?.subDirectory ? `${storage.subDirectory.replace(/\/$/, '')}/` : ''
+  const subDirectory = storage?.subDirectory !== undefined ? `${storage.subDirectory.replace(/\/$/, '')}/` : ''
   const pathJoin = (...paths: string[]) => paths.join('/').replaceAll(/\/+/g, '/')
-  const directory = pathJoin(SQLite.defaultDatabaseDirectory, subDirectory, storeId)
+  const directoryBasePath = storage?.directory ?? SQLite.defaultDatabaseDirectory
+
+  const directory = pathJoin(directoryBasePath, subDirectory, storeId)
 
-  const schemaHashSuffix =
-    schema.state.sqlite.migrations.strategy === 'manual' ? 'fixed' : schema.state.sqlite.hash.toString()
-  const stateDatabaseName = `livestore-${schemaHashSuffix}@${liveStoreStorageFormatVersion}.db`
+  const stateDatabaseName = `${getStateDbBaseName(schema)}@${liveStoreStorageFormatVersion}.db`
   const eventlogDatabaseName = `livestore-eventlog@${liveStoreStorageFormatVersion}.db`
 
   return { directory, stateDatabaseName, eventlogDatabaseName }
@@ -313,7 +382,7 @@ const resetExpoPersistence = ({
       SQLite.deleteDatabaseSync(eventlogDatabaseName, directory)
     },
     catch: (cause) =>
-      new UnexpectedError({
+      new UnknownError({
         cause,
         note: `@livestore/adapter-expo: Failed to reset persistence for store ${storeId}`,
       }),
@@ -336,7 +405,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 {

package/src/polyfill.ts

@@ -6,6 +6,7 @@
 
 if (typeof Array.prototype.toSorted === 'undefined') {
   Array.prototype.toSorted = function (compareFn) {
-    return this.sort(compareFn)
+    // oxlint-disable-next-line unicorn/no-array-sort -- this is the toSorted polyfill itself
+    return this.slice().sort(compareFn)
   }
 }