@livestore/adapter-node 0.4.0-dev.20 → 0.4.0-dev.22

package/src/client-session/adapter.ts

@@ -13,7 +13,7 @@ import {
   type SyncOptions,
   UnknownError,
 } from '@livestore/common'
-import { Eventlog, LeaderThreadCtx } from '@livestore/common/leader-thread'
+import { Eventlog, LeaderThreadCtx, streamEventsWithSyncState } from '@livestore/common/leader-thread'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { LiveStoreEvent } from '@livestore/common/schema'
 import { loadSqlite3Wasm } from '@livestore/sqlite-wasm/load-wasm'
@@ -88,7 +88,43 @@ export interface NodeAdapterOptions {
   }
 }
 
-/** Runs everything in the same thread. Use `makeWorkerAdapter` for multi-threaded implementation. */
+/**
+ * Creates a single-threaded LiveStore adapter for Node.js applications.
+ *
+ * This adapter runs the leader thread (persistence and sync) in the same thread as
+ * your application. Suitable for CLI tools, scripts, and applications where simplicity
+ * is preferred over maximum performance.
+ *
+ * For production servers or performance-critical applications, consider `makeWorkerAdapter`
+ * which runs persistence/sync in a separate worker thread.
+ *
+ * @example
+ * ```ts
+ * import { makeAdapter } from '@livestore/adapter-node'
+ * import { makeWsSync } from '@livestore/sync-cf/client'
+ *
+ * const adapter = makeAdapter({
+ *   storage: { type: 'fs', baseDirectory: './data' },
+ *   sync: {
+ *     backend: makeWsSync({ url: 'wss://api.example.com/sync' }),
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With DevTools support
+ * const adapter = makeAdapter({
+ *   storage: { type: 'fs', baseDirectory: './data' },
+ *   devtools: {
+ *     schemaPath: new URL('./schema.ts', import.meta.url),
+ *     port: 4242,
+ *   },
+ * })
+ * ```
+ *
+ * @see https://livestore.dev/docs/reference/adapters/node for setup guide
+ */
 export const makeAdapter = ({
   sync,
   ...options
@@ -97,7 +133,36 @@ export const makeAdapter = ({
 }): Adapter => makeAdapterImpl({ ...options, leaderThread: { _tag: 'single-threaded', sync } })
 
 /**
- * Runs persistence and syncing in a worker thread.
+ * Creates a multi-threaded LiveStore adapter for Node.js applications.
+ *
+ * This adapter runs the leader thread (persistence, sync, and heavy SQLite operations)
+ * in a separate worker thread, keeping your main thread responsive. Recommended for
+ * production servers and performance-critical applications.
+ *
+ * You must create a worker file that calls `makeLeaderWorker()` and pass its URL
+ * to this function.
+ *
+ * @example
+ * ```ts
+ * // In your main file:
+ * import { makeWorkerAdapter } from '@livestore/adapter-node'
+ *
+ * const adapter = makeWorkerAdapter({
+ *   storage: { type: 'fs', baseDirectory: './data' },
+ *   workerUrl: new URL('./livestore.worker.ts', import.meta.url),
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // In livestore.worker.ts:
+ * import { makeLeaderWorker } from '@livestore/adapter-node/worker'
+ * import { schema } from './schema'
+ *
+ * makeLeaderWorker({ schema })
+ * ```
+ *
+ * @see https://livestore.dev/docs/reference/adapters/node for setup guide
  */
 export const makeWorkerAdapter = ({
   workerUrl,
@@ -341,8 +406,18 @@ const makeLocalLeaderThread = ({
                 batch.map((item) => new LiveStoreEvent.Client.EncodedWithMeta(item)),
                 { waitForProcessing: true },
               ),
+            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(() => dbState.export()),
           getEventlogData: Effect.sync(() => dbEventlog.export()),
           syncState: syncProcessor.syncState,
@@ -481,10 +556,16 @@ const makeWorkerLeaderThread = ({
                 attributes: { batchSize: batch.length },
               }),
             ),
+          stream: (options) =>
+            runInWorkerStream(new WorkerSchema.LeaderWorkerInnerStreamEvents(options)).pipe(
+              Stream.withSpan('@livestore/adapter-node:client-session:streamEvents'),
+              Stream.orDie,
+            ),
         },
         initialState: {
           leaderHead: initialLeaderHead,
           migrationsReport: bootResult.migrationsReport,
+          storageMode: 'persisted',
         },
         export: runInWorker(new WorkerSchema.LeaderWorkerInnerExport()).pipe(
           Effect.timeout(10_000),

package/src/devtools/devtools-server.ts

@@ -20,6 +20,16 @@ import { makeMeshNode, makeWebSocketEdge } from '@livestore/webmesh'
 
 import { makeViteMiddleware } from './vite-dev-server.ts'
 
+/**
+ * Determines if a request URL should be routed to the Vite middleware.
+ * Includes LiveStore devtools paths and Vite internal paths like `/@fs/`, `/@vite/`, etc.
+ */
+const shouldRouteToVite = (url: string): boolean =>
+  url.startsWith('/_livestore') ||
+  url.startsWith('/@fs') ||
+  url.startsWith('/@vite') ||
+  url.startsWith('/@react-refresh')
+
 /**
  * Starts a devtools HTTP/WS server which serves ...
  * - the Devtools UI via Vite
@@ -96,7 +106,7 @@ export const startDevtoolsServer = ({
       } else {
         if (req.url === '/' || req.url === '') {
           return HttpServerResponse.redirect('/_livestore/node')
-        } else if (req.url.startsWith('/_livestore')) {
+        } else if (shouldRouteToVite(req.url)) {
           // Here we're delegating to the Vite middleware
 
           // TODO replace this once @effect/platform-node supports Node HTTP middlewares

package/src/make-leader-worker.ts

@@ -9,7 +9,8 @@ if (process.execArgv.includes('--inspect')) {
 
 import type { SyncOptions } from '@livestore/common'
 import { LogConfig, UnknownError } from '@livestore/common'
-import { Eventlog, LeaderThreadCtx } from '@livestore/common/leader-thread'
+import type { StreamEventsOptions } from '@livestore/common/leader-thread'
+import { Eventlog, LeaderThreadCtx, streamEventsWithSyncState } from '@livestore/common/leader-thread'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { LiveStoreEvent } from '@livestore/common/schema'
 import { loadSqlite3Wasm } from '@livestore/sqlite-wasm/load-wasm'
@@ -86,6 +87,20 @@ export const makeWorkerEffect = (options: WorkerOptions) => {
         const { syncProcessor } = yield* LeaderThreadCtx
         return syncProcessor.pull({ cursor })
       }).pipe(Stream.unwrapScoped),
+    StreamEvents: (options: WorkerSchema.LeaderWorkerInnerStreamEvents) =>
+      LeaderThreadCtx.pipe(
+        Effect.map(({ dbEventlog, syncProcessor }) => {
+          const { _tag: _ignored, ...payload } = options
+          const streamOptions = payload as StreamEventsOptions
+          return streamEventsWithSyncState({
+            dbEventlog,
+            syncState: syncProcessor.syncState,
+            options: streamOptions,
+          })
+        }),
+        Stream.unwrapScoped,
+        Stream.withSpan('@livestore/adapter-node:worker:StreamEvents'),
+      ),
     Export: () =>
       Effect.andThen(LeaderThreadCtx, (_) => _.dbState.export()).pipe(
         UnknownError.mapToUnknownError,

package/src/worker-schema.ts

@@ -7,6 +7,7 @@ import {
   SyncState,
   UnknownError,
 } from '@livestore/common'
+import { StreamEventsOptionsFields } from '@livestore/common/leader-thread'
 import { EventSequenceNumber, LiveStoreEvent } from '@livestore/common/schema'
 import { Schema, Transferable } from '@livestore/utils/effect'
 
@@ -111,6 +112,15 @@ export class LeaderWorkerInnerPullStream extends Schema.TaggedRequest<LeaderWork
   failure: UnknownError,
 }) {}
 
+export class LeaderWorkerInnerStreamEvents extends Schema.TaggedRequest<LeaderWorkerInnerStreamEvents>()(
+  'StreamEvents',
+  {
+    payload: StreamEventsOptionsFields,
+    success: LiveStoreEvent.Client.Encoded,
+    failure: UnknownError,
+  },
+) {}
+
 export class LeaderWorkerInnerPushToLeader extends Schema.TaggedRequest<LeaderWorkerInnerPushToLeader>()(
   'PushToLeader',
   {
@@ -215,6 +225,7 @@ export const LeaderWorkerInnerRequest = Schema.Union(
   LeaderWorkerInnerInitialMessage,
   LeaderWorkerInnerBootStatusStream,
   LeaderWorkerInnerPullStream,
+  LeaderWorkerInnerStreamEvents,
   LeaderWorkerInnerPushToLeader,
   LeaderWorkerInnerExport,
   LeaderWorkerInnerGetRecreateSnapshot,