@livestore/livestore 0.4.0 → 0.5.0-dev.0

package/src/store/create-store.ts

@@ -2,18 +2,17 @@ import * as otel from '@opentelemetry/api'
 
 import {
   type Adapter,
+  type BackendIdMismatchError,
   type BootStatus,
   type ClientSession,
   type ClientSessionDevtoolsChannel,
-  type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
-  LogConfig,
   type MaterializeError,
-  type BackendIdMismatchError,
   type MigrationsReport,
   provideOtel,
   type ServerAheadError,
   UnknownError,
+  type LogConfig,
 } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { isDevEnv, LS_DEV, omitUndefineds } from '@livestore/utils'
@@ -27,7 +26,7 @@ import {
   Layer,
   OtelTracer,
   Queue,
-  Runtime,
+  References,
   Schema,
   Scope,
   TaskTracing,
@@ -43,6 +42,14 @@ import type {
 import { StoreInternalsSymbol } from './store-types.ts'
 import { STORE_DEFAULT_PARAMS, Store } from './store.ts'
 
+/**
+ * Hard upper bound (ms) for the detached shutdown drain. A dead/unresponsive leader must not keep
+ * the drain (and therefore the lifetime scope) alive forever; after this bound the scope is
+ * force-closed. Kept comfortably above the 1s caller-side soft wait so that a still-progressing
+ * in-flight leader push is allowed to finish rather than being interrupted.
+ */
+const SHUTDOWN_DRAIN_HARD_TIMEOUT_MS = 30_000
+
 declare global {
   /** Store instances for console debugging */
   var __debugLiveStore: Record<string, Store<any, any>> | undefined
@@ -64,29 +71,28 @@ declare global {
  * const { store } = yield* AppStore.Tag
  * ```
  */
-export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/effect/LiveStoreContextRunning')<
-  LiveStoreContextRunning,
-  LiveStoreContextRunning_
->() {
+export class LiveStoreContextRunning extends Context.Service<LiveStoreContextRunning, LiveStoreContextRunning_>()(
+  '@livestore/livestore/effect/LiveStoreContextRunning',
+) {
   static fromDeferred = Effect.gen(function* () {
     const deferred = yield* DeferredStoreContext
-    const ctx = yield* deferred
-    return Layer.succeed(LiveStoreContextRunning, ctx)
-  }).pipe(Layer.unwrapScoped)
+    const ctx = yield* Deferred.await(deferred)
+    return Layer.succeed(LiveStoreContextRunning, LiveStoreContextRunning.of(ctx))
+  }).pipe(Layer.unwrap)
 }
 
 /**
  * @deprecated Use `StoreContext.DeferredTag` from `makeStoreContext()` instead.
  */
-export class DeferredStoreContext extends Context.Tag('@livestore/livestore/effect/DeferredStoreContext')<
+export class DeferredStoreContext extends Context.Service<
   DeferredStoreContext,
-  Deferred.Deferred<LiveStoreContextRunning['Type'], UnknownError>
->() {}
+  Deferred.Deferred<LiveStoreContextRunning['Service'], UnknownError>
+>()('@livestore/livestore/effect/DeferredStoreContext') {}
 
 export type LiveStoreContextProps<
   TSchema extends LiveStoreSchema,
   TContext = {},
-  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
 > = {
   schema: TSchema
   /**
@@ -115,7 +121,7 @@ export type LiveStoreContextProps<
   /**
    * Schema describing the shape of the sync payload and used to encode it.
    *
-   * - If omitted, `Schema.JsonValue` is used (no additional typing/validation).
+   * - If omitted, `Schema.Json` is used (no additional typing/validation).
    * - Prefer exporting a schema from your app (e.g. `export const SyncPayload = Schema.Struct({ authToken: Schema.String })`)
    *   and pass it here to get end-to-end type safety and validation.
    */
@@ -130,14 +136,15 @@ export type LiveStoreContextProps<
    *   const SyncPayload = Schema.Struct({ authToken: Schema.String })
    *   useStore({ ..., syncPayloadSchema: SyncPayload, syncPayload: { authToken: '...' } })
    */
-  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
+  syncPayload?: TSyncPayloadSchema['Type']
 }
 
 export interface CreateStoreOptions<
   TSchema extends LiveStoreSchema,
   TContext = {},
-  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
-> extends LogConfig.WithLoggerOptions {
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
+>
+  extends LogConfig.LoggerOptions {
   /** The LiveStore schema defining tables, events, and materializers. */
   schema: TSchema
   /** Adapter used for data storage and synchronization. */
@@ -192,7 +199,7 @@ export interface CreateStoreOptions<
   /**
    * Schema describing the shape of the sync payload and used to encode it.
    *
-   * - If omitted, `Schema.JsonValue` is used (no additional typing/validation).
+   * - If omitted, `Schema.Json` is used (no additional typing/validation).
    * - Prefer exporting a schema from your app (e.g. `export const SyncPayload = Schema.Struct({ authToken: Schema.String })`)
    *   and pass it here to get end-to-end type safety and validation.
    */
@@ -206,16 +213,13 @@ export interface CreateStoreOptions<
    *
    * @default undefined
    */
-  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
+  syncPayload?: TSyncPayloadSchema['Type']
   /** Options provided to the Store constructor. */
   params?: {
     /** Max events pushed to the leader per write batch. */
     leaderPushBatchSize?: number
     /** Chunk size used when the stream replays confirmed events. */
     eventQueryBatchSize?: number
-    simulation?: {
-      clientSessionSyncProcessor: typeof ClientSessionSyncProcessorSimulationParams.Type
-    }
   }
   debug?: {
     instanceId?: string
@@ -225,7 +229,7 @@ export interface CreateStoreOptions<
 export type CreateStoreOptionsPromise<
   TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
   TContext = {},
-  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
 > = CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema> & {
   signal?: AbortSignal
   otelOptions?: Partial<OtelOptions>
@@ -235,7 +239,7 @@ export type CreateStoreOptionsPromise<
 export const createStorePromise = async <
   TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
   TContext = {},
-  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
 >({
   signal,
   otelOptions,
@@ -243,15 +247,15 @@ export const createStorePromise = async <
 }: CreateStoreOptionsPromise<TSchema, TContext, TSyncPayloadSchema>): Promise<Store<TSchema, TContext>> =>
   Effect.gen(function* () {
     const scope = yield* Scope.make()
-    const runtime = yield* Effect.runtime()
+    const services = yield* Effect.context()
 
     if (signal !== undefined) {
       signal.addEventListener('abort', () => {
-        Scope.close(scope, Exit.void).pipe(Effect.tapCauseLogPretty, Runtime.runFork(runtime))
+        Scope.close(scope, Exit.void).pipe(Effect.tapCauseLogPretty, Effect.runForkWith(services))
       })
     }
 
-    return yield* createStore({ ...options }).pipe(Scope.extend(scope))
+    return yield* createStore({ ...options }).pipe(Scope.provide(scope))
   }).pipe(
     Effect.withSpan('createStore', {
       attributes: { storeId: options.storeId, disableDevtools: options.disableDevtools },
@@ -259,14 +263,19 @@ export const createStorePromise = async <
     provideOtel(omitUndefineds({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer })),
     Effect.tapCauseLogPretty,
     Effect.annotateLogs({ thread: 'window' }),
-    LogConfig.withLoggerConfig(options, { threadName: 'window' }),
+    Effect.provide(
+      Layer.mergeAll(
+        options.logger ?? Layer.empty,
+        Layer.succeed(References.MinimumLogLevel, options.logLevel ?? (isDevEnv() === true ? 'Debug' : 'Info')),
+      ),
+    ),
     Effect.runPromise,
   )
 
 export const createStore = <
   TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
   TContext = {},
-  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
 >({
   schema,
   adapter,
@@ -295,18 +304,20 @@ export const createStore = <
     yield* Effect.addFinalizer((_) => Scope.close(lifetimeScope, _))
 
     const debugInstanceId = debug?.instanceId ?? nanoid(10)
-    const resolvedSyncPayloadSchema = (syncPayloadSchema ?? Schema.JsonValue) as TSyncPayloadSchema
+    const resolvedSyncPayloadSchema = (syncPayloadSchema ?? Schema.Json) as TSyncPayloadSchema
 
     return yield* Effect.gen(function* () {
       const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
       const otelRootSpanContext = otel.trace.setSpan(otel.context.active(), span)
       const otelTracer = yield* OtelTracer.OtelTracer
 
-      const bootStatusQueue = yield* Queue.unbounded<BootStatus>().pipe(Effect.acquireRelease(Queue.shutdown))
+      const bootStatusQueue = yield* Effect.acquireRelease(Queue.unbounded<BootStatus>(), Queue.shutdown)
 
       yield* Queue.take(bootStatusQueue).pipe(
         Effect.tapSync((status) => onBootStatus?.(status)),
-        Effect.tap((status) => (status.stage === 'done' ? Queue.shutdown(bootStatusQueue) : Effect.void)),
+        Effect.tap((status) =>
+          status.stage === 'done' ? Queue.shutdown(bootStatusQueue).pipe(Effect.asVoid) : Effect.void,
+        ),
         Effect.forever,
         Effect.tapCauseLogPretty,
         Effect.forkScoped,
@@ -316,23 +327,40 @@ export const createStore = <
 
       const connectDevtoolsToStore_ = (storeDevtoolsChannel: ClientSessionDevtoolsChannel) =>
         Effect.gen(function* () {
-          const store = yield* storeDeferred
+          const store = yield* Deferred.await(storeDeferred)
           yield* connectDevtoolsToStore({ storeDevtoolsChannel, store })
         })
 
-      const runtime = yield* Effect.runtime<Scope.Scope>()
+      const services = yield* Effect.context<Scope.Scope>()
+      let shutdownSyncProcessor: ((exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void>) | undefined
 
       const shutdown = (
-        exit: Exit.Exit<
-          IntentionalShutdownCause,
-          UnknownError | MaterializeError | BackendIdMismatchError
-        >,
+        exit: Exit.Exit<IntentionalShutdownCause, UnknownError | MaterializeError | BackendIdMismatchError>,
       ) =>
         Effect.gen(function* () {
-          yield* Scope.close(lifetimeScope, exit).pipe(
+          // Hard outer bound on the DETACHED teardown: the processor drain `awaitEmpty`s the
+          // leader-push worker, which never completes if the leader is dead/unresponsive. Without a
+          // bound the drain would block forever, so `Scope.close(lifetimeScope)` (in `ensuring`)
+          // would never run and the lifetime scope + its resources would leak indefinitely (a later
+          // `createStore`/registry dispose on the same `storeId` would observe a never-closed store).
+          // Drain up to the bound, then force-close the scope regardless. The bound exceeds the
+          // caller-side wait below so an in-flight (but progressing) push is not cut short.
+          const closeFiber = yield* (shutdownSyncProcessor?.(exit) ?? Effect.void).pipe(
+            Effect.timeout(SHUTDOWN_DRAIN_HARD_TIMEOUT_MS),
+            Effect.catchTag('TimeoutError', () =>
+              Effect.logError(
+                `@livestore/livestore:shutdown: drain exceeded hard bound of ${SHUTDOWN_DRAIN_HARD_TIMEOUT_MS}ms; forcing scope close`,
+              ),
+            ),
+            Effect.ensuring(Scope.close(lifetimeScope, exit)),
+            Effect.forkDetach,
+          )
+          // Caller-side soft wait: stop blocking the shutdown() caller after 1s without cancelling
+          // the detached teardown above (which remains bounded by SHUTDOWN_DRAIN_HARD_TIMEOUT_MS).
+          yield* Fiber.join(closeFiber).pipe(
             Effect.logWarnIfTakesLongerThan({ label: '@livestore/livestore:shutdown', duration: 500 }),
             Effect.timeout(1000),
-            Effect.catchTag('TimeoutException', () =>
+            Effect.catchTag('TimeoutError', () =>
               Effect.logError('@livestore/livestore:shutdown: Timed out after 1 second'),
             ),
           )
@@ -344,7 +372,7 @@ export const createStore = <
           yield* Effect.logDebug('LiveStore shutdown complete')
         }).pipe(
           Effect.withSpan('@livestore/livestore:shutdown'),
-          Effect.provide(runtime),
+          Effect.provide(services),
           Effect.tapCauseLogPretty,
           // Given that the shutdown flow might also interrupt the effect that is calling the shutdown,
           // we want to detach the shutdown effect so it's not interrupted by itself
@@ -355,7 +383,7 @@ export const createStore = <
       const syncPayloadEncoded =
         syncPayload === undefined
           ? undefined
-          : yield* Schema.encode(resolvedSyncPayloadSchema)(syncPayload).pipe(UnknownError.mapToUnknownError)
+          : yield* Schema.encodeEffect(resolvedSyncPayloadSchema)(syncPayload).pipe(UnknownError.mapToUnknownError)
 
       const clientSession: ClientSession = yield* adapter({
         schema,
@@ -385,10 +413,10 @@ export const createStore = <
         schema,
         context,
         otelOptions: { tracer: otelTracer, rootSpanContext: otelRootSpanContext },
-        effectContext: { lifetimeScope, runtime },
+        effectContext: { lifetimeScope, services },
         // TODO find a better way to detect if we're running LiveStore in the LiveStore devtools
         // But for now this is a good enough approximation with little downsides
-        __runningInDevtools: ! getDevtoolsEnabled(disableDevtools),
+        __runningInDevtools: !getDevtoolsEnabled(disableDevtools),
         confirmUnsavedChanges,
         // NOTE during boot we're not yet executing events in a batched context
         // but only set the provided `batchUpdates` function after boot
@@ -397,26 +425,32 @@ export const createStore = <
         params: {
           leaderPushBatchSize: params?.leaderPushBatchSize ?? STORE_DEFAULT_PARAMS.leaderPushBatchSize,
           eventQueryBatchSize: params?.eventQueryBatchSize ?? STORE_DEFAULT_PARAMS.eventQueryBatchSize,
-          ...omitUndefineds({ simulation: params?.simulation }),
         },
       })
+      shutdownSyncProcessor = store[StoreInternalsSymbol].syncProcessor.shutdown
 
       // Starts background fibers (syncing, event processing, etc) for store
       yield* store[StoreInternalsSymbol].boot
 
       if (boot !== undefined) {
         // TODO also incorporate `boot` function progress into `bootStatusQueue`
-        yield* Effect.tryAll(() =>
+        // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- user boot errors are immediately normalized to LiveStore UnknownError
+        yield* Effect.trySyncOrPromiseOrEffect(() =>
           boot(store, { migrationsReport: clientSession.leaderThread.initialState.migrationsReport, parentSpan: span }),
         ).pipe(
           UnknownError.mapToUnknownError,
-          Effect.provide(Layer.succeed(LiveStoreContextRunning, { stage: 'running', store: store as any as Store })),
+          Effect.provide(
+            Layer.succeed(
+              LiveStoreContextRunning,
+              LiveStoreContextRunning.of({ stage: 'running', store: store as any as Store }),
+            ),
+          ),
           Effect.withSpan('createStore:boot'),
         )
       }
 
       // NOTE it's important to yield here to allow the forked Effect in the store constructor to run
-      yield* Effect.yieldNow()
+      yield* Effect.yieldNow
 
       if (batchUpdates !== undefined) {
         // Replacing the default batchUpdates function with the provided one after boot
@@ -440,7 +474,7 @@ export const createStore = <
       Effect.withSpan('createStore', { attributes: { debugInstanceId, storeId } }),
       Effect.annotateLogs({ debugInstanceId, storeId }),
       LS_DEV === true ? TaskTracing.withAsyncTaggingTracing((name) => (console as any).createTask(name)) : identity,
-      Scope.extend(lifetimeScope),
+      Scope.provide(lifetimeScope),
     )
   })