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

package/src/effect/LiveStore.ts

@@ -1,13 +1,29 @@
-import type { UnexpectedError } from '@livestore/common'
-import type { LiveStoreSchema } from '@livestore/common/schema'
+import type { UnknownError } from '@livestore/common'
+import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema'
 import { omitUndefineds } from '@livestore/utils'
-import type { Cause, OtelTracer, Scope } from '@livestore/utils/effect'
-import { Deferred, Duration, Effect, Layer, pipe } from '@livestore/utils/effect'
+import type { Schema } from '@livestore/utils/effect'
+import {
+  type Cause,
+  type OtelTracer,
+  type Scope,
+  Context,
+  Deferred,
+  Duration,
+  Effect,
+  Layer,
+  pipe,
+} from '@livestore/utils/effect'
 
 import type { LiveStoreContextProps } from '../store/create-store.ts'
 import { createStore, DeferredStoreContext, LiveStoreContextRunning } from '../store/create-store.ts'
+import type { LiveStoreContextRunning as LiveStoreContextRunningType, Queryable } from '../store/store-types.ts'
+import type { Store as StoreClass } from '../store/store.ts'
 
-export const makeLiveStoreContext = <TSchema extends LiveStoreSchema, TContext = {}>({
+export const makeLiveStoreContext = <
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
+>({
   schema,
   storeId = 'default',
   context,
@@ -16,9 +32,11 @@ export const makeLiveStoreContext = <TSchema extends LiveStoreSchema, TContext =
   disableDevtools,
   onBootStatus,
   batchUpdates,
-}: LiveStoreContextProps<TSchema, TContext>): Effect.Effect<
-  LiveStoreContextRunning['Type'],
-  UnexpectedError | Cause.TimeoutException,
+  syncPayload,
+  syncPayloadSchema,
+}: LiveStoreContextProps<TSchema, TContext, TSyncPayloadSchema>): Effect.Effect<
+  LiveStoreContextRunning['Service'],
+  UnknownError | Cause.TimeoutError,
   DeferredStoreContext | Scope.Scope | OtelTracer.OtelTracer
 > =>
   pipe(
@@ -28,18 +46,12 @@ export const makeLiveStoreContext = <TSchema extends LiveStoreSchema, TContext =
         storeId,
         adapter,
         batchUpdates,
-        ...omitUndefineds({ context, boot, disableDevtools, onBootStatus }),
+        ...omitUndefineds({ context, boot, disableDevtools, onBootStatus, syncPayload, syncPayloadSchema }),
       })
 
-      globalThis.__debugLiveStore ??= {}
-      if (Object.keys(globalThis.__debugLiveStore).length === 0) {
-        globalThis.__debugLiveStore._ = store
-      }
-      globalThis.__debugLiveStore[storeId] = store
-
-      return { stage: 'running', store } as any as LiveStoreContextRunning['Type']
+      return LiveStoreContextRunning.of({ stage: 'running', store } as any as LiveStoreContextRunning['Service'])
     }),
-    Effect.tapErrorCause((cause) => Effect.flatMap(DeferredStoreContext, (def) => Deferred.failCause(def, cause))),
+    Effect.tapCause((cause) => Effect.flatMap(DeferredStoreContext, (def) => Deferred.failCause(def, cause))),
     Effect.tap((storeCtx) => Effect.flatMap(DeferredStoreContext, (def) => Deferred.succeed(def, storeCtx))),
     // This can take quite a while.
     // TODO make this configurable
@@ -47,15 +59,407 @@ export const makeLiveStoreContext = <TSchema extends LiveStoreSchema, TContext =
     Effect.withSpan('@livestore/livestore/effect:makeLiveStoreContext'),
   )
 
-export const LiveStoreContextLayer = <TSchema extends LiveStoreSchema, TContext = {}>(
-  props: LiveStoreContextProps<TSchema, TContext>,
-): Layer.Layer<LiveStoreContextRunning, UnexpectedError | Cause.TimeoutException, OtelTracer.OtelTracer> =>
-  Layer.scoped(LiveStoreContextRunning, makeLiveStoreContext(props)).pipe(
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` instead for type-safe store contexts.
+ *
+ * @example Migration
+ * ```ts
+ * // Before
+ * const layer = LiveStoreContextLayer({ schema, adapter, ... })
+ *
+ * // After
+ * class MainStore extends Store.Tag(schema, 'main') {}
+ * const layer = MainStore.layer({ adapter, ... })
+ * ```
+ */
+export const LiveStoreContextLayer = <
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
+>(
+  props: LiveStoreContextProps<TSchema, TContext, TSyncPayloadSchema>,
+): Layer.Layer<LiveStoreContextRunning, UnknownError | Cause.TimeoutError, OtelTracer.OtelTracer> =>
+  Layer.effect(LiveStoreContextRunning, makeLiveStoreContext(props)).pipe(
     Layer.withSpan('LiveStore'),
     Layer.provide(LiveStoreContextDeferred),
   )
 
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` and `MainStore.DeferredLayer` instead.
+ */
 export const LiveStoreContextDeferred = Layer.effect(
   DeferredStoreContext,
-  Deferred.make<LiveStoreContextRunning['Type'], UnexpectedError>(),
+  Deferred.make<LiveStoreContextRunning['Service'], UnknownError>(),
 )
+
+// =============================================================================
+// Store.Tag - Idiomatic Effect API
+// =============================================================================
+
+/** Branded type for unique store context identity */
+declare const StoreContextTypeId: unique symbol
+
+/** Phantom type carrying schema and storeId information */
+export interface StoreContextId<TSchema extends LiveStoreSchema, TStoreId extends string> {
+  readonly [StoreContextTypeId]: {
+    readonly schema: TSchema
+    readonly storeId: TStoreId
+  }
+}
+
+/** Phantom type for deferred store context */
+declare const DeferredContextTypeId: unique symbol
+
+export interface DeferredContextId<TStoreId extends string> {
+  readonly [DeferredContextTypeId]: {
+    readonly storeId: TStoreId
+  }
+}
+
+/** Props for creating a store layer (schema and storeId are already provided) */
+export type StoreLayerProps<
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
+> = Omit<LiveStoreContextProps<TSchema, TContext, TSyncPayloadSchema>, 'storeId' | 'schema'>
+
+/**
+ * Type for a Store.Tag class. This is the return type of `Store.Tag(schema, storeId)`.
+ * Can be extended as a class and is yieldable in Effect.gen.
+ *
+ * Note: This uses a type alias with a new() signature to make it extendable.
+ */
+/**
+ * Type for a Store.Tag class. Uses self-referential identifier so that `yield*`
+ * and method R channels resolve to the same type, enabling proper layer composition.
+ *
+ * Uses `interface` (not `type`) to allow the self-referential identifier without
+ * triggering TS2456 (circular type alias).
+ */
+export interface StoreTagClass<TSchema extends LiveStoreSchema, TStoreId extends string> extends Context.Key<
+  StoreTagClass<TSchema, TStoreId>,
+  LiveStoreContextRunningType<TSchema>
+> {
+  /** Constructor signature (makes the type extendable as a class) */
+  new (): Context.Key<StoreTagClass<TSchema, TStoreId>, LiveStoreContextRunningType<TSchema>>
+
+  /** Key identity type (from Context.Key) */
+  readonly Id: StoreTagClass<TSchema, TStoreId>
+
+  /** Service type (from Context.Key) */
+  readonly Service: LiveStoreContextRunningType<TSchema>
+
+  /** The LiveStore schema for this store */
+  readonly schema: TSchema
+
+  /** Unique identifier for this store */
+  readonly storeId: TStoreId
+
+  /** Creates a layer that initializes the store */
+  layer<TContext, TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json>(
+    props: StoreLayerProps<TSchema, TContext, TSyncPayloadSchema>,
+  ): Layer.Layer<StoreTagClass<TSchema, TStoreId>, UnknownError | Cause.TimeoutError, OtelTracer.OtelTracer>
+
+  /** Deferred store tag for async initialization patterns */
+  readonly Deferred: Context.Key<
+    DeferredContextId<TStoreId>,
+    Deferred.Deferred<LiveStoreContextRunningType<TSchema>, UnknownError>
+  >
+
+  /** Layer that provides the Deferred tag */
+  readonly DeferredLayer: Layer.Layer<DeferredContextId<TStoreId>>
+
+  /** Layer that waits for Deferred and provides the running store */
+  readonly fromDeferred: Layer.Layer<StoreTagClass<TSchema, TStoreId>, UnknownError, DeferredContextId<TStoreId>>
+
+  /** Query the store. Returns an Effect that yields the query result. */
+  query<TResult>(query: Queryable<TResult>): Effect.Effect<TResult, never, StoreTagClass<TSchema, TStoreId>>
+
+  /** Commit events to the store. */
+  commit(
+    ...eventInputs: LiveStoreEvent.Input.ForSchema<TSchema>[]
+  ): Effect.Effect<void, never, StoreTagClass<TSchema, TStoreId>>
+
+  /** Use the store with a callback function. */
+  use<A, E, R>(
+    f: (ctx: LiveStoreContextRunningType<TSchema>) => Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E, R | StoreTagClass<TSchema, TStoreId>>
+}
+
+/**
+ * Create a typed store context class for use with Effect.
+ *
+ * Returns a class that extends `Context.Service`, making it directly yieldable in Effect code.
+ * The class includes static methods for creating layers and accessors for common operations.
+ *
+ * @param schema - The LiveStore schema (used for type inference and runtime)
+ * @param storeId - Unique identifier for this store
+ *
+ * @example Basic usage
+ * ```ts
+ * import { Store } from '@livestore/livestore/effect'
+ * import { schema } from './schema.ts'
+ *
+ * // Define your store (once per store)
+ * export class MainStore extends Store.Tag(schema, 'main') {}
+ *
+ * // Create the layer
+ * const storeLayer = MainStore.layer({
+ *   adapter: myAdapter,
+ *   batchUpdates: ReactDOM.unstable_batchedUpdates,
+ * })
+ *
+ * // Use in Effect code
+ * Effect.gen(function* () {
+ *   const { store } = yield* MainStore
+ *   //       ^? Store<typeof schema> - fully typed!
+ *
+ *   // Or use accessors
+ *   const users = yield* MainStore.query(tables.users.all())
+ *   yield* MainStore.commit(events.createUser({ id: '1', name: 'Alice' }))
+ * })
+ * ```
+ *
+ * @example Multiple stores
+ * ```ts
+ * class MainStore extends Store.Tag(mainSchema, 'main') {}
+ * class SettingsStore extends Store.Tag(settingsSchema, 'settings') {}
+ *
+ * // Both available in same Effect context
+ * Effect.gen(function* () {
+ *   const main = yield* MainStore
+ *   const settings = yield* SettingsStore
+ * })
+ *
+ * const layer = Layer.mergeAll(
+ *   MainStore.layer({ adapter: mainAdapter }),
+ *   SettingsStore.layer({ adapter: settingsAdapter }),
+ * )
+ * ```
+ */
+const makeStoreTag = <TSchema extends LiveStoreSchema, TStoreId extends string>(
+  schema: TSchema,
+  storeId: TStoreId,
+): StoreTagClass<TSchema, TStoreId> => {
+  type RunningType = LiveStoreContextRunningType<TSchema>
+  type DeferredType = Deferred.Deferred<RunningType, UnknownError>
+
+  // Create the deferred tag and layers upfront
+  const _DeferredTag = Context.Service<DeferredContextId<TStoreId>, DeferredType>(
+    `@livestore/store-deferred/${storeId}`,
+  )
+
+  const _DeferredLayer = Layer.effect(_DeferredTag, Deferred.make<RunningType, UnknownError>())
+
+  class Tag extends Context.Service<Tag, RunningType>()(`@livestore/store/${storeId}`) {
+    static readonly schema: TSchema = schema
+    static readonly storeId: TStoreId = storeId
+
+    static layer<TContext = {}, TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json>(
+      props: StoreLayerProps<TSchema, TContext, TSyncPayloadSchema>,
+    ) {
+      return pipe(
+        Effect.gen(function* () {
+          const store = yield* createStore({
+            schema,
+            storeId,
+            adapter: props.adapter,
+            batchUpdates: props.batchUpdates,
+            ...omitUndefineds({
+              context: props.context,
+              boot: props.boot,
+              disableDevtools: props.disableDevtools,
+              onBootStatus: props.onBootStatus,
+              syncPayload: props.syncPayload,
+              syncPayloadSchema: props.syncPayloadSchema,
+            }),
+          })
+
+          const ctx: RunningType = { stage: 'running', store: store as StoreClass<TSchema> }
+
+          // Also fulfill the deferred if it exists in context
+          yield* Effect.flatMap(Effect.serviceOption(_DeferredTag), (optDeferred) =>
+            optDeferred._tag === 'Some' ? Deferred.succeed(optDeferred.value, ctx) : Effect.void,
+          )
+
+          return Tag.of(ctx)
+        }),
+        Effect.timeout(Duration.minutes(5)),
+        Effect.withSpan(`@livestore/effect:Store.Tag:${storeId}`),
+        Layer.effect(Tag),
+        Layer.withSpan(`LiveStore:${storeId}`),
+        Layer.provide(_DeferredLayer),
+      )
+    }
+
+    static readonly Deferred = _DeferredTag
+    static readonly DeferredLayer = _DeferredLayer
+
+    static readonly fromDeferred = pipe(
+      Effect.gen(function* () {
+        const deferred = yield* _DeferredTag
+        const ctx = yield* Deferred.await(deferred)
+        return Layer.succeed(Tag, Tag.of(ctx))
+      }),
+      Layer.unwrap,
+    )
+
+    static query<TResult>(query: Queryable<TResult>) {
+      return Effect.map(Tag, ({ store }) => store.query(query))
+    }
+
+    static commit(...eventInputs: LiveStoreEvent.Input.ForSchema<TSchema>[]) {
+      return Effect.map(Tag, ({ store }) => {
+        store.commit(...eventInputs)
+      })
+    }
+
+    static override use<A, E, R>(f: (ctx: RunningType) => Effect.Effect<A, E, R>) {
+      return Effect.flatMap(Tag, f)
+    }
+  }
+
+  return Tag as unknown as StoreTagClass<TSchema, TStoreId>
+}
+
+/**
+ * Store utilities for Effect integration.
+ *
+ * @example
+ * ```ts
+ * import { Store } from '@livestore/livestore/effect'
+ *
+ * export class MainStore extends Store.Tag(schema, 'main') {}
+ * ```
+ */
+export const Store = {
+  /**
+   * Create a typed store context class for use with Effect.
+   * @see {@link makeStoreTag} for full documentation
+   */
+  Tag: makeStoreTag,
+}
+
+// =============================================================================
+// Legacy API (deprecated)
+// =============================================================================
+
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` instead.
+ *
+ * @example Migration
+ * ```ts
+ * // Before
+ * const MainStoreContext = makeStoreContext<typeof schema>()('main')
+ * export const MainStore = MainStoreContext.Tag
+ * export const MainStoreLayer = MainStoreContext.Layer
+ *
+ * // After
+ * export class MainStore extends Store.Tag(schema, 'main') {}
+ * // MainStore.layer({ ... }) for the layer
+ * ```
+ */
+export interface StoreContext<TSchema extends LiveStoreSchema, TStoreId extends string> {
+  readonly storeId: TStoreId
+  readonly Tag: Context.Key<StoreContextId<TSchema, TStoreId>, LiveStoreContextRunningType<TSchema>>
+  readonly DeferredTag: Context.Key<
+    DeferredContextId<TStoreId>,
+    Deferred.Deferred<LiveStoreContextRunningType<TSchema>, UnknownError>
+  >
+  readonly Layer: <
+    TContext = {},
+    TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
+  >(
+    props: Omit<LiveStoreContextProps<TSchema, TContext, TSyncPayloadSchema>, 'storeId'>,
+  ) => Layer.Layer<StoreContextId<TSchema, TStoreId>, UnknownError | Cause.TimeoutError, OtelTracer.OtelTracer>
+  readonly DeferredLayer: Layer.Layer<DeferredContextId<TStoreId>>
+  readonly fromDeferred: Layer.Layer<StoreContextId<TSchema, TStoreId>, UnknownError, DeferredContextId<TStoreId>>
+}
+
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` instead.
+ *
+ * @example Migration
+ * ```ts
+ * // Before
+ * const MainStoreContext = makeStoreContext<typeof schema>()('main')
+ *
+ * // After
+ * class MainStore extends Store.Tag(schema, 'main') {}
+ * ```
+ */
+export const makeStoreContext =
+  <TSchema extends LiveStoreSchema>() =>
+  <TStoreId extends string>(storeId: TStoreId): StoreContext<TSchema, TStoreId> => {
+    type RunningType = LiveStoreContextRunningType<TSchema>
+    type DeferredType = Deferred.Deferred<RunningType, UnknownError>
+
+    const Tag = Context.Service<StoreContextId<TSchema, TStoreId>, RunningType>(`@livestore/store/${storeId}`)
+
+    const DeferredTag = Context.Service<DeferredContextId<TStoreId>, DeferredType>(
+      `@livestore/store-deferred/${storeId}`,
+    )
+
+    const DeferredLayer = Layer.effect(DeferredTag, Deferred.make<RunningType, UnknownError>())
+
+    const makeLayer = <
+      TContext = {},
+      TSyncPayloadSchema extends Schema.Codec<Schema.Json, Schema.Json> = typeof Schema.Json,
+    >(
+      props: Omit<LiveStoreContextProps<TSchema, TContext, TSyncPayloadSchema>, 'storeId'>,
+    ): Layer.Layer<StoreContextId<TSchema, TStoreId>, UnknownError | Cause.TimeoutError, OtelTracer.OtelTracer> =>
+      pipe(
+        Effect.gen(function* () {
+          const store = yield* createStore({
+            schema: props.schema,
+            storeId,
+            adapter: props.adapter,
+            batchUpdates: props.batchUpdates,
+            ...omitUndefineds({
+              context: props.context,
+              boot: props.boot,
+              disableDevtools: props.disableDevtools,
+              onBootStatus: props.onBootStatus,
+              syncPayload: props.syncPayload,
+              syncPayloadSchema: props.syncPayloadSchema,
+            }),
+          })
+
+          const ctx: RunningType = { stage: 'running', store: store as StoreClass<TSchema> }
+
+          // Also fulfill the deferred if it exists in context
+          yield* Effect.flatMap(Effect.serviceOption(DeferredTag), (optDeferred) =>
+            optDeferred._tag === 'Some' ? Deferred.succeed(optDeferred.value, ctx) : Effect.void,
+          )
+
+          return ctx
+        }),
+        Effect.timeout(Duration.minutes(5)),
+        Effect.withSpan(`@livestore/effect:makeStoreContext:${storeId}`),
+        Layer.effect(Tag),
+        Layer.withSpan(`LiveStore:${storeId}`),
+        Layer.provide(DeferredLayer),
+      )
+
+    const fromDeferred: Layer.Layer<
+      StoreContextId<TSchema, TStoreId>,
+      UnknownError,
+      DeferredContextId<TStoreId>
+    > = pipe(
+      Effect.gen(function* () {
+        const deferred = yield* DeferredTag
+        const ctx = yield* Deferred.await(deferred)
+        return Layer.succeed(Tag, ctx)
+      }),
+      Layer.unwrap,
+    )
+
+    return {
+      storeId,
+      Tag,
+      DeferredTag,
+      Layer: makeLayer,
+      DeferredLayer,
+      fromDeferred,
+    }
+  }

package/src/effect/mod.ts

@@ -4,4 +4,16 @@ export {
   LiveStoreContextRunning as LiveStoreContext,
   LiveStoreContextRunning,
 } from '../store/create-store.ts'
-export { LiveStoreContextDeferred, LiveStoreContextLayer } from './LiveStore.ts'
+// Store.Tag - Idiomatic Effect API
+// Legacy API (deprecated)
+export {
+  type DeferredContextId,
+  LiveStoreContextDeferred,
+  LiveStoreContextLayer,
+  makeStoreContext,
+  Store,
+  type StoreContext,
+  type StoreContextId,
+  type StoreLayerProps,
+  type StoreTagClass,
+} from './LiveStore.ts'