StoreRegistry

Defined in: packages/@livestore/livestore/src/store/StoreRegistry.ts:144

Store Registry coordinating store loading, caching, and retention

Constructors

Constructor

new StoreRegistry(config): StoreRegistry

Defined in: packages/@livestore/livestore/src/store/StoreRegistry.ts:181

Creates a new StoreRegistry instance.

Parameters

config

StoreRegistryConfig = {}

Returns

StoreRegistry

Example

const registry = new StoreRegistry({
  defaultOptions: {
    batchUpdates,
    unusedCacheTime: 30_000,
  }
})

Methods

getOrLoad()

getOrLoad<TSchema, TContext, TSyncPayloadSchema>(options): Effect<Store<TSchema, TContext>, UnknownError, Scope>

Defined in: packages/@livestore/livestore/src/store/StoreRegistry.ts:223

Gets a cached store or loads a new one, with the store lifetime scoped to the caller.

Type Parameters

TSchema

TSchema extends LiveStoreSchema<DbSchema, EventDefRecord>

The schema type for the store

TContext

TContext = { }

The context type for the store

TSyncPayloadSchema

TSyncPayloadSchema extends Schema<any, any, never> = Schema<JsonValue, JsonValue, never>

The sync payload schema type

Parameters

options

RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>

Returns

Effect<Store<TSchema, TContext>, UnknownError, Scope>

An Effect that yields the store, scoped to the provided Scope

Remarks

• Stores are kept in cache and reused while any scope holds them
• When the scope closes, the reference is released; the store is disposed after unusedCacheTime if no other scopes retain it
• Concurrent calls with the same storeId share the same store instance

---

getOrLoadPromise()

getOrLoadPromise<TSchema, TContext, TSyncPayloadSchema>(options): Store<TSchema, TContext> | Promise<Store<TSchema, TContext>>

Defined in: packages/@livestore/livestore/src/store/StoreRegistry.ts:254

Get or load a store, returning it directly if already loaded or a promise if loading.

Type Parameters

TSchema

TSchema extends LiveStoreSchema<DbSchema, EventDefRecord>

The schema type for the store

TContext

TContext = { }

The context type for the store

TSyncPayloadSchema

TSyncPayloadSchema extends Schema<any, any, never> = Schema<JsonValue, JsonValue, never>

The sync payload schema type

Parameters

options

RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>

Returns

Store<TSchema, TContext> | Promise<Store<TSchema, TContext>>

The loaded store if available, or a Promise that resolves to the loaded store

Throws

unknown - store loading error

Remarks

• Returns the store instance directly (synchronous) when already loaded
• Returns a stable Promise reference when loading is in progress or needs to be initiated
• Throws with the same error instance on subsequent calls after failure
• Applies default options from registry config, with call-site options taking precedence
• Concurrent calls with the same storeId share the same store instance

---

preload()

preload<TSchema, TContext, TSyncPayloadSchema>(options): Promise<void>

Defined in: packages/@livestore/livestore/src/store/StoreRegistry.ts:334

Loads a store (without suspending) to warm up the cache.

Type Parameters

TSchema

TSchema extends LiveStoreSchema<DbSchema, EventDefRecord>

The schema of the store to preload

TContext

TContext = { }

The context type for the store

TSyncPayloadSchema

TSyncPayloadSchema extends Schema<any, any, never> = Schema<JsonValue, JsonValue, never>

The sync payload schema type

Parameters

options

RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>

Returns

Promise<void>

A promise that resolves when the loading is complete (success or failure)

Remarks

• We don’t return the store or throw as this is a fire-and-forget operation.
• If the entry remains unused after preload resolves/rejects, it is scheduled for disposal.
• Does not affect the retention of the store in cache.

---

retain()

retain<TSchema, TContext, TSyncPayloadSchema>(options): () => void

Defined in: packages/@livestore/livestore/src/store/StoreRegistry.ts:301

Retains the store in cache.

Type Parameters

TSchema

TSchema extends LiveStoreSchema<DbSchema, EventDefRecord>

The schema type for the store

TContext

TContext = { }

The context type for the store

TSyncPayloadSchema

TSyncPayloadSchema extends Schema<any, any, never> = Schema<JsonValue, JsonValue, never>

The sync payload schema type

Parameters

options

RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>

Returns

A release function that, when called, removes this retention hold

(): void

Returns

void

Remarks

• Multiple retains on the same store are independent; each must be released separately
• If the store isn’t cached yet, it will be loaded and then retained
• The store will remain in cache until all retains are released and after unusedCacheTime expires