effect-state-machine API / LocalStorageMachineStore

LocalStorageMachineStore

configuration

Config

Defined in: packages/core/src/LocalStorageMachineStore.ts:85

Construction settings shared by coordinated and explicitly single-context stores.

Details

namespace defaults to "effect-state-machine". now defaults to Effect's current clock and can be replaced by a virtual-clock Effect for deterministic tests.

Since

0.2.0

Extended by

CoordinatedConfig

Properties

storage

readonly storage: Storage

Defined in: packages/core/src/LocalStorageMachineStore.ts:86

namespace?

readonly optional namespace?: string

Defined in: packages/core/src/LocalStorageMachineStore.ts:87

now?

readonly optional now?: Effect<number, LocalStorageMachineStoreError, never>

Defined in: packages/core/src/LocalStorageMachineStore.ts:88

CoordinatedConfig

Defined in: packages/core/src/LocalStorageMachineStore.ts:102

Settings for the cross-context-safe adapter.

Gotchas

locks is optional in the input so capability detection can remain explicit, but make and layer fail with UnsupportedPlatform when it is absent.

Since

0.2.0

Extends

Config

Properties

storage

readonly storage: Storage

Defined in: packages/core/src/LocalStorageMachineStore.ts:86

Inherited from

Config.storage

namespace?

readonly optional namespace?: string

Defined in: packages/core/src/LocalStorageMachineStore.ts:87

Inherited from

Config.namespace

now?

readonly optional now?: Effect<number, LocalStorageMachineStoreError, never>

Defined in: packages/core/src/LocalStorageMachineStore.ts:88

Inherited from

Config.now

locks?

readonly optional locks?: Locks

Defined in: packages/core/src/LocalStorageMachineStore.ts:103

constructors

webLocks()

webLocks(manager): Locks

Defined in: packages/core/src/LocalStorageMachineStore.ts:128

Wraps an injected browser Web Locks manager as the Effect-level Locks capability.

When to use

Use at a browser application boundary to adapt navigator.locks without reading browser globals from this module.

Gotchas

The callback crosses a Promise boundary while preserving the current Effect context and Cause. A rejected lock request becomes LocalStorageMachineStoreError.

Parameters

manager

WebLockManager

Returns

Locks

Since

0.2.0

make()

make(config): Effect<Service, UnsupportedPlatform>

Defined in: packages/core/src/LocalStorageMachineStore.ts:255

Constructs a cross-context-safe machine store using injected storage and lock capabilities.

When to use

Use when the same namespace may be written by multiple tabs, frames, or workers.

Gotchas

Construction fails with UnsupportedPlatform when no lock capability is supplied. Storage and serialization failures occur later through the returned MachineStore.Service error channel.

Parameters

config

CoordinatedConfig

Returns

Effect<Service, UnsupportedPlatform>

See

layerSingleContext for an explicit single-context opt-in.

Since

0.2.0

errors

LocalStorageMachineStoreError

Defined in: packages/core/src/LocalStorageMachineStore.ts:55

Expected failure while locking, reading, writing, decoding, or encoding browser-local state.

Details

Adapter layers translate this boundary error into MachineStore.MachineStoreError before the service is exposed to MachineEngine.

Since

0.2.0

Extends

YieldableError<this> & object & Readonly<{ operation: ...; message: ...; cause?: ...; }>

Constructors

Constructor

new LocalStorageMachineStoreError(args): LocalStorageMachineStoreError

Defined in: node_modules/.pnpm/effect@4.0.0-rc.110/node_modules/effect/dist/Data.d.ts:966

Parameters

args

operation

"decode" | "encode" | "lock" | "read" | "write"

message

string

cause?

unknown

Returns

LocalStorageMachineStoreError

Inherited from

Data.TaggedError( "LocalStorageMachineStoreError", )<{ readonly operation: "lock" | "read" | "write" | "decode" | "encode" readonly message: string readonly cause?: unknown }>.constructor

Properties

operation

readonly operation: "decode" | "encode" | "lock" | "read" | "write"

Defined in: packages/core/src/LocalStorageMachineStore.ts:58

Inherited from

Data.TaggedError( "LocalStorageMachineStoreError", ).operation

cause?

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

Data.TaggedError( "LocalStorageMachineStoreError", ).cause

message

message: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Data.TaggedError( "LocalStorageMachineStoreError", ).message

UnsupportedPlatform

Defined in: packages/core/src/LocalStorageMachineStore.ts:69

Safe refusal to construct a coordinated store without Web Locks.

Since

0.2.0

Extends

YieldableError<this> & object & Readonly<{ feature: ...; message: ...; }>

Constructors

Constructor

new UnsupportedPlatform(args): UnsupportedPlatform

Defined in: node_modules/.pnpm/effect@4.0.0-rc.110/node_modules/effect/dist/Data.d.ts:966

Parameters

args

feature

"web-locks"

message

string

Returns

UnsupportedPlatform

Inherited from

Data.TaggedError("UnsupportedPlatform")<{ readonly feature: "web-locks" readonly message: string }>.constructor

Properties

feature

readonly feature: "web-locks"

Defined in: packages/core/src/LocalStorageMachineStore.ts:70

Inherited from

Data.TaggedError("UnsupportedPlatform").feature

message

message: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Data.TaggedError("UnsupportedPlatform").message

layers

layer()

layer(config): Layer<MachineStore, UnsupportedPlatform>

Defined in: packages/core/src/LocalStorageMachineStore.ts:279

Provides a cross-context-safe localStorage-backed MachineStore Layer.

Gotchas

The Layer can fail to build with UnsupportedPlatform. Construct it in browser code and provide the resulting store to MachineEngine.layer at the application boundary.

Parameters

config

CoordinatedConfig

Returns

Layer<MachineStore, UnsupportedPlatform>

See

make for direct service construction.

Since

0.2.0

layerSingleContext()

layerSingleContext(config): Layer<MachineStore>

Defined in: packages/core/src/LocalStorageMachineStore.ts:303

Explicit same-page-only localStorage layer.

This mode performs no cross-tab synchronization. Use it only when one JavaScript context can access the configured namespace for the entire application lifetime.

When to use

Use only when the application can prove that a namespace has one writer for its full lifetime.

Gotchas

Multiple tabs, frames, workers, or independently mounted applications can lose updates because this Layer deliberately performs no cross-context locking.

readonly getItem: (key) => string | null

Defined in: packages/core/src/LocalStorageMachineStore.ts:17

readonly setItem: (key, value) => void

Defined in: packages/core/src/LocalStorageMachineStore.ts:18

readonly withLock: <A, E, R>(name, effect) => Effect<A, E | LocalStorageMachineStoreError, R>

Defined in: packages/core/src/LocalStorageMachineStore.ts:28

readonly request: <A>(name, callback) => Promise<A>

Defined in: packages/core/src/LocalStorageMachineStore.ts:41

LocalStorageMachineStore API