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

package/dist/live-queries/computed.d.ts

@@ -2,10 +2,66 @@ import type { Thunk } from '../reactive.ts';
 import type { RefreshReason } from '../store/store-types.ts';
 import type { DepKey, GetAtomResult, LiveQueryDef, ReactivityGraph, ReactivityGraphContext } from './base-class.ts';
 import { LiveStoreQueryBase } from './base-class.ts';
+/**
+ * Creates a derived query that computes a value from other queries or signals.
+ *
+ * Computed queries are memoized—they only re-evaluate when their dependencies change,
+ * and if the new result equals the previous result, downstream dependents won't re-run.
+ * Use them for expensive calculations, aggregations, or transformations.
+ *
+ * The `get` function inside `computed` establishes reactive dependencies automatically.
+ * When any dependency updates, the computed re-evaluates.
+ *
+ * @example
+ * ```ts
+ * // Derive a count from a database query
+ * const todos$ = queryDb(tables.todos.all())
+ * const todoCount$ = computed((get) => get(todos$).length, { label: 'todoCount' })
+ *
+ * // Use in a component
+ * const count = store.query(todoCount$) // 5
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Combine multiple queries into derived stats
+ * const stats$ = computed((get) => {
+ *   const todos = get(todos$)
+ *   const completed = todos.filter((t) => t.completed).length
+ *   return {
+ *     total: todos.length,
+ *     completed,
+ *     remaining: todos.length - completed,
+ *     percentComplete: todos.length > 0 ? (completed / todos.length) * 100 : 0,
+ *   }
+ * }, { label: 'todoStats' })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Chain computed queries
+ * const hasCompletedTodos$ = computed(
+ *   (get) => get(stats$).completed > 0,
+ *   { label: 'hasCompletedTodos' }
+ * )
+ * ```
+ *
+ * @param fn - Pure function that computes the result. Use `get()` to read dependencies.
+ * @param options.label - Human-readable label for debugging and devtools
+ * @param options.deps - Explicit dependency keys (required on Expo/React Native where `fn.toString()` returns `[native code]`)
+ * @returns A query definition usable with `store.query()`, `store.subscribe()`, and as a dependency in other queries
+ */
 export declare const computed: <TResult>(fn: (get: GetAtomResult) => TResult, options?: {
     label?: string;
     deps?: DepKey;
 }) => LiveQueryDef<TResult>;
+/**
+ * A live computed query instance bound to a specific Store.
+ *
+ * Computed query instances are created internally when you use a `LiveQueryDef` (from {@link computed})
+ * with the Store. You typically don't construct these directly—use `computed()` to create definitions
+ * and `store.query()` / `store.subscribe()` to interact with them.
+ */
 export declare class LiveStoreComputedQuery<TResult> extends LiveStoreQueryBase<TResult> {
     _tag: "computed";
     /** A reactive thunk representing the query results */

package/dist/live-queries/computed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/live-queries/computed.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACnH,OAAO,EAAgB,kBAAkB,EAAgC,MAAM,iBAAiB,CAAA;AAEhG,eAAO,MAAM,QAAQ,GAAI,OAAO,EAC9B,IAAI,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,EACnC,UAAU;IACR,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,KACA,YAAY,CAAC,OAAO,CA+BtB,CAAA;AAED,qBAAa,sBAAsB,CAAC,OAAO,CAAE,SAAQ,kBAAkB,CAAC,OAAO,CAAC;IAC9E,IAAI,EAAG,UAAU,CAAS;IAE1B,sDAAsD;IACtD,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAE/D,KAAK,EAAE,MAAM,CAAA;IAEb,eAAe,EAAE,eAAe,CAAA;IAChC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;gBAEd,EACV,EAAE,EACF,KAAK,EACL,eAAe,EACf,GAAG,GACJ,EAAE;QACD,KAAK,EAAE,MAAM,CAAA;QACb,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAA;QACnC,eAAe,EAAE,eAAe,CAAA;QAChC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;KAC3B;IA6BD,OAAO,aAQN;CACF"}
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/live-queries/computed.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACnH,OAAO,EAAgB,kBAAkB,EAAgC,MAAM,iBAAiB,CAAA;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,EAC9B,IAAI,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,EACnC,UAAU;IACR,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,KACA,YAAY,CAAC,OAAO,CA+BtB,CAAA;AAED;;;;;;GAMG;AACH,qBAAa,sBAAsB,CAAC,OAAO,CAAE,SAAQ,kBAAkB,CAAC,OAAO,CAAC;IAC9E,IAAI,EAAG,UAAU,CAAS;IAE1B,sDAAsD;IACtD,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAE/D,KAAK,EAAE,MAAM,CAAA;IAEb,eAAe,EAAE,eAAe,CAAA;IAChC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;gBAEd,EACV,EAAE,EACF,KAAK,EACL,eAAe,EACf,GAAG,GACJ,EAAE;QACD,KAAK,EAAE,MAAM,CAAA;QACb,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAA;QACnC,eAAe,EAAE,eAAe,CAAA;QAChC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;KAC3B;IA6BD,OAAO,aAQN;CACF"}

package/dist/live-queries/computed.js

@@ -3,6 +3,55 @@ import { Equal, Hash } from '@livestore/utils/effect';
 import * as otel from '@opentelemetry/api';
 import { isValidFunctionString } from "../utils/function-string.js";
 import { depsToString, LiveStoreQueryBase, makeGetAtomResult, withRCMap } from "./base-class.js";
+/**
+ * Creates a derived query that computes a value from other queries or signals.
+ *
+ * Computed queries are memoized—they only re-evaluate when their dependencies change,
+ * and if the new result equals the previous result, downstream dependents won't re-run.
+ * Use them for expensive calculations, aggregations, or transformations.
+ *
+ * The `get` function inside `computed` establishes reactive dependencies automatically.
+ * When any dependency updates, the computed re-evaluates.
+ *
+ * @example
+ * ```ts
+ * // Derive a count from a database query
+ * const todos$ = queryDb(tables.todos.all())
+ * const todoCount$ = computed((get) => get(todos$).length, { label: 'todoCount' })
+ *
+ * // Use in a component
+ * const count = store.query(todoCount$) // 5
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Combine multiple queries into derived stats
+ * const stats$ = computed((get) => {
+ *   const todos = get(todos$)
+ *   const completed = todos.filter((t) => t.completed).length
+ *   return {
+ *     total: todos.length,
+ *     completed,
+ *     remaining: todos.length - completed,
+ *     percentComplete: todos.length > 0 ? (completed / todos.length) * 100 : 0,
+ *   }
+ * }, { label: 'todoStats' })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Chain computed queries
+ * const hasCompletedTodos$ = computed(
+ *   (get) => get(stats$).completed > 0,
+ *   { label: 'hasCompletedTodos' }
+ * )
+ * ```
+ *
+ * @param fn - Pure function that computes the result. Use `get()` to read dependencies.
+ * @param options.label - Human-readable label for debugging and devtools
+ * @param options.deps - Explicit dependency keys (required on Expo/React Native where `fn.toString()` returns `[native code]`)
+ * @returns A query definition usable with `store.query()`, `store.subscribe()`, and as a dependency in other queries
+ */
 export const computed = (fn, options) => {
     const hash = options?.deps ? depsToString(options.deps) : fn.toString();
     if (isValidFunctionString(hash)._tag === 'invalid') {
@@ -33,6 +82,13 @@ export const computed = (fn, options) => {
     };
     return def;
 };
+/**
+ * A live computed query instance bound to a specific Store.
+ *
+ * Computed query instances are created internally when you use a `LiveQueryDef` (from {@link computed})
+ * with the Store. You typically don't construct these directly—use `computed()` to create definitions
+ * and `store.query()` / `store.subscribe()` to interact with them.
+ */
 export class LiveStoreComputedQuery extends LiveStoreQueryBase {
     _tag = 'computed';
     /** A reactive thunk representing the query results */

package/dist/live-queries/computed.js.map

@@ -1 +1 @@
-{"version":3,"file":"computed.js","sourceRoot":"","sources":["../../src/live-queries/computed.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"computed.js","sourceRoot":"","sources":["../../src/live-queries/computed.ts"],"names":[],"mappings":"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"}

package/dist/live-queries/signal.d.ts

@@ -2,9 +2,58 @@ import type * as RG from '../reactive.ts';
 import type { RefreshReason } from '../store/store-types.ts';
 import type { ISignal, ReactivityGraph, ReactivityGraphContext, SignalDef } from './base-class.ts';
 import { LiveStoreQueryBase } from './base-class.ts';
+/**
+ * Creates a reactive signal for ephemeral, local-only state that isn't persisted to the database.
+ *
+ * Signals are useful for UI state that needs to trigger query re-evaluation but shouldn't be
+ * synced across clients or stored permanently—such as search filters, selected items, or
+ * temporary form values.
+ *
+ * Unlike database-backed state (via events), signals:
+ * - Are not persisted or synced
+ * - Exist only for the lifetime of the Store
+ * - Can hold any value type (primitives, objects, functions)
+ *
+ * @example
+ * ```ts
+ * // Create a signal for search text
+ * const searchText$ = signal('', { label: 'searchText' })
+ *
+ * // Create a query that depends on the signal
+ * const filteredTodos$ = queryDb(
+ *   (get) => tables.todos.where({ text: { $like: `%${get(searchText$)}%` } }),
+ *   { deps: [searchText$] }
+ * )
+ *
+ * // Update the signal (triggers query re-evaluation)
+ * store.setSignal(searchText$, 'buy')
+ *
+ * // Read the current value
+ * const results = store.query(filteredTodos$)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Counter with functional updates
+ * const count$ = signal(0, { label: 'count' })
+ *
+ * store.setSignal(count$, (prev) => prev + 1)
+ * ```
+ *
+ * @param defaultValue - Initial value of the signal
+ * @param options.label - Human-readable label for debugging and devtools
+ * @returns A signal definition that can be used with `store.query()`, `store.setSignal()`, and as a dependency in other queries
+ */
 export declare const signal: <T>(defaultValue: T, options?: {
     label?: string;
 }) => SignalDef<T>;
+/**
+ * A live signal instance bound to a specific Store.
+ *
+ * Signal instances are created internally when you use a `SignalDef` with the Store.
+ * You typically don't construct these directly—use {@link signal} to create definitions
+ * and `store.setSignal()` / `store.query()` to interact with them.
+ */
 export declare class Signal<T> extends LiveStoreQueryBase<T> implements ISignal<T> {
     _tag: "signal";
     readonly ref: RG.Ref<T, ReactivityGraphContext, RefreshReason>;

package/dist/live-queries/signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/live-queries/signal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAClG,OAAO,EAAE,kBAAkB,EAAa,MAAM,iBAAiB,CAAA;AAE/D,eAAO,MAAM,MAAM,GAAI,CAAC,EACtB,cAAc,CAAC,EACf,UAAU;IACR,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,KACA,SAAS,CAAC,CAAC,CA0Bb,CAAA;AAED,qBAAa,MAAM,CAAC,CAAC,CAAE,SAAQ,kBAAkB,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;IACxE,IAAI,EAAG,QAAQ,CAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,EAAE,eAAe,CAAA;IAChC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAC1D,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;gBAOf,EACE,YAAY,EACZ,eAAe,EACf,KAAK,EACL,GAAG,GACJ,EAAE;QACD,YAAY,EAAE,CAAC,CAAA;QACf,eAAe,EAAE,eAAe,CAAA;QAChC,KAAK,EAAE,MAAM,CAAA;QACb,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;KAClB;IAYH,GAAG,GAAI,OAAO,CAAC,UAEd;IAED,GAAG,UAEF;IAED,OAAO,aAEN;CACF"}
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/live-queries/signal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAClG,OAAO,EAAE,kBAAkB,EAAa,MAAM,iBAAiB,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EACtB,cAAc,CAAC,EACf,UAAU;IACR,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,KACA,SAAS,CAAC,CAAC,CA0Bb,CAAA;AAED;;;;;;GAMG;AACH,qBAAa,MAAM,CAAC,CAAC,CAAE,SAAQ,kBAAkB,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;IACxE,IAAI,EAAG,QAAQ,CAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,EAAE,eAAe,CAAA;IAChC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAC1D,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;gBAOf,EACE,YAAY,EACZ,eAAe,EACf,KAAK,EACL,GAAG,GACJ,EAAE;QACD,YAAY,EAAE,CAAC,CAAA;QACf,eAAe,EAAE,eAAe,CAAA;QAChC,KAAK,EAAE,MAAM,CAAA;QACb,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;KAClB;IAYH,GAAG,GAAI,OAAO,CAAC,UAEd;IAED,GAAG,UAEF;IAED,OAAO,aAEN;CACF"}

package/dist/live-queries/signal.js

@@ -1,6 +1,48 @@
 import { Equal, Hash } from '@livestore/utils/effect';
 import { nanoid } from '@livestore/utils/nanoid';
 import { LiveStoreQueryBase, withRCMap } from "./base-class.js";
+/**
+ * Creates a reactive signal for ephemeral, local-only state that isn't persisted to the database.
+ *
+ * Signals are useful for UI state that needs to trigger query re-evaluation but shouldn't be
+ * synced across clients or stored permanently—such as search filters, selected items, or
+ * temporary form values.
+ *
+ * Unlike database-backed state (via events), signals:
+ * - Are not persisted or synced
+ * - Exist only for the lifetime of the Store
+ * - Can hold any value type (primitives, objects, functions)
+ *
+ * @example
+ * ```ts
+ * // Create a signal for search text
+ * const searchText$ = signal('', { label: 'searchText' })
+ *
+ * // Create a query that depends on the signal
+ * const filteredTodos$ = queryDb(
+ *   (get) => tables.todos.where({ text: { $like: `%${get(searchText$)}%` } }),
+ *   { deps: [searchText$] }
+ * )
+ *
+ * // Update the signal (triggers query re-evaluation)
+ * store.setSignal(searchText$, 'buy')
+ *
+ * // Read the current value
+ * const results = store.query(filteredTodos$)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Counter with functional updates
+ * const count$ = signal(0, { label: 'count' })
+ *
+ * store.setSignal(count$, (prev) => prev + 1)
+ * ```
+ *
+ * @param defaultValue - Initial value of the signal
+ * @param options.label - Human-readable label for debugging and devtools
+ * @returns A signal definition that can be used with `store.query()`, `store.setSignal()`, and as a dependency in other queries
+ */
 export const signal = (defaultValue, options) => {
     const id = nanoid();
     const def = {
@@ -23,6 +65,13 @@ export const signal = (defaultValue, options) => {
     };
     return def;
 };
+/**
+ * A live signal instance bound to a specific Store.
+ *
+ * Signal instances are created internally when you use a `SignalDef` with the Store.
+ * You typically don't construct these directly—use {@link signal} to create definitions
+ * and `store.setSignal()` / `store.query()` to interact with them.
+ */
 export class Signal extends LiveStoreQueryBase {
     _tag = 'signal';
     ref;

package/dist/live-queries/signal.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/live-queries/signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAKhD,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE/D,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,YAAe,EACf,OAEC,EACa,EAAE;IAChB,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;IACnB,MAAM,GAAG,GAAiB;QACxB,IAAI,EAAE,YAAY;QAClB,YAAY;QACZ,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ;QACjC,IAAI,EAAE,SAAS,CACb,EAAE,EACF,CAAC,GAAG,EAAE,EAAE,CACN,IAAI,MAAM,CAAC;YACT,YAAY;YACZ,eAAe,EAAE,GAAG,CAAC,eAAe,CAAC,KAAK,EAAG;YAC7C,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ;YACjC,GAAG;SACJ,CAAC,CACL;QACD,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAkB;YAC/B,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAA;QAChC,CAAC;QACD,CAAC,IAAI,CAAC,MAAM,CAAC;YACX,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC/B,CAAC;KACF,CAAA;IAED,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED,MAAM,OAAO,MAAU,SAAQ,kBAAqB;IAClD,IAAI,GAAG,QAAiB,CAAA;IACf,GAAG,CAAkD;IAC9D,KAAK,CAAQ;IACb,eAAe,CAAiB;IAChC,QAAQ,CAAkD;IAC1D,GAAG,CAAc;IACjB;IACE,2BAA2B;IAC3B,6CAA6C;IAC7C,sBAAsB;IACtB,mBAAmB;IACnB,KAAK;IACL,EACE,YAAY,EACZ,eAAe,EACf,KAAK,EACL,GAAG,GAMJ;QAED,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QAC3D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAA;QACtC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;QAEd,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAA;IAC1B,CAAC;IAED,GAAG,GAAG,CAAC,KAAQ,EAAE,EAAE;QACjB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC9C,CAAC,CAAA;IAED,GAAG,GAAG,GAAG,EAAE;QACT,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAA;IACjC,CAAC,CAAA;IAED,OAAO,GAAG,GAAG,EAAE;QACb,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC5C,CAAC,CAAA;CACF"}
+{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/live-queries/signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAKhD,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,YAAe,EACf,OAEC,EACa,EAAE;IAChB,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;IACnB,MAAM,GAAG,GAAiB;QACxB,IAAI,EAAE,YAAY;QAClB,YAAY;QACZ,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ;QACjC,IAAI,EAAE,SAAS,CACb,EAAE,EACF,CAAC,GAAG,EAAE,EAAE,CACN,IAAI,MAAM,CAAC;YACT,YAAY;YACZ,eAAe,EAAE,GAAG,CAAC,eAAe,CAAC,KAAK,EAAG;YAC7C,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ;YACjC,GAAG;SACJ,CAAC,CACL;QACD,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAkB;YAC/B,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAA;QAChC,CAAC;QACD,CAAC,IAAI,CAAC,MAAM,CAAC;YACX,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC/B,CAAC;KACF,CAAA;IAED,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,OAAO,MAAU,SAAQ,kBAAqB;IAClD,IAAI,GAAG,QAAiB,CAAA;IACf,GAAG,CAAkD;IAC9D,KAAK,CAAQ;IACb,eAAe,CAAiB;IAChC,QAAQ,CAAkD;IAC1D,GAAG,CAAc;IACjB;IACE,2BAA2B;IAC3B,6CAA6C;IAC7C,sBAAsB;IACtB,mBAAmB;IACnB,KAAK;IACL,EACE,YAAY,EACZ,eAAe,EACf,KAAK,EACL,GAAG,GAMJ;QAED,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QAC3D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAA;QACtC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;QAEd,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAA;IAC1B,CAAC;IAED,GAAG,GAAG,CAAC,KAAQ,EAAE,EAAE;QACjB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC9C,CAAC,CAAA;IAED,GAAG,GAAG,GAAG,EAAE;QACT,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAA;IACjC,CAAC,CAAA;IAED,OAAO,GAAG,GAAG,EAAE;QACb,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC5C,CAAC,CAAA;CACF"}

package/dist/mod.d.ts

@@ -7,6 +7,7 @@ export { nanoid } from '@livestore/utils/nanoid';
 export { computed, type LiveQuery, type LiveQueryDef, queryDb, type RcRef, type Signal, type SignalDef, signal, } from './live-queries/mod.ts';
 export { emptyDebugInfo, SqliteDbWrapper } from './SqliteDbWrapper.ts';
 export { type CreateStoreOptions, type CreateStoreOptionsPromise, createStore, createStorePromise, } from './store/create-store.ts';
+export { type RegistryStoreOptions, StoreRegistry, storeOptions } from './store/StoreRegistry.ts';
 export { Store } from './store/store.ts';
 export { isLiveQueryDef, isLiveQueryInstance, isQueryable, type LiveStoreContext, type LiveStoreContextRunning, makeShutdownDeferred, type OtelOptions, type Queryable, type QueryDebugInfo, type RefreshReason, type ShutdownDeferred, type StoreInternals, StoreInternalsSymbol, type SubscribeOptions, type Unsubscribe, } from './store/store-types.ts';
 export { exposeDebugUtils } from './utils/dev.ts';

package/dist/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAClF,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,SAAS,EACd,wBAAwB,EACxB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,eAAe,EACf,KAAK,QAAQ,EACb,gBAAgB,EAChB,KAAK,SAAS,EACd,GAAG,GACJ,MAAM,mBAAmB,CAAA;AAC1B,cAAc,0BAA0B,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EACL,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,OAAO,EACP,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,EACd,MAAM,GACP,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,WAAW,EACX,kBAAkB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAClF,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,SAAS,EACd,wBAAwB,EACxB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,eAAe,EACf,KAAK,QAAQ,EACb,gBAAgB,EAChB,KAAK,SAAS,EACd,GAAG,GACJ,MAAM,mBAAmB,CAAA;AAC1B,cAAc,0BAA0B,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EACL,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,OAAO,EACP,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,EACd,MAAM,GACP,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,WAAW,EACX,kBAAkB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACjG,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,cAAc,uBAAuB,CAAA"}

package/dist/mod.js

@@ -7,6 +7,7 @@ export { nanoid } from '@livestore/utils/nanoid';
 export { computed, queryDb, signal, } from "./live-queries/mod.js";
 export { emptyDebugInfo, SqliteDbWrapper } from "./SqliteDbWrapper.js";
 export { createStore, createStorePromise, } from "./store/create-store.js";
+export { StoreRegistry, storeOptions } from "./store/StoreRegistry.js";
 export { Store } from "./store/store.js";
 export { isLiveQueryDef, isLiveQueryInstance, isQueryable, makeShutdownDeferred, StoreInternalsSymbol, } from "./store/store-types.js";
 export { exposeDebugUtils } from "./utils/dev.js";

package/dist/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,wBAAwB,EACxB,gBAAgB,EAGhB,iBAAiB,EACjB,WAAW,EAIX,eAAe,EAEf,gBAAgB,EAEhB,GAAG,GACJ,MAAM,mBAAmB,CAAA;AAC1B,cAAc,0BAA0B,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,4DAA4D;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EACL,QAAQ,EAGR,OAAO,EAIP,MAAM,GACP,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EAGL,WAAW,EACX,kBAAkB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,WAAW,EAGX,oBAAoB,EAOpB,oBAAoB,GAGrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,wBAAwB,EACxB,gBAAgB,EAGhB,iBAAiB,EACjB,WAAW,EAIX,eAAe,EAEf,gBAAgB,EAEhB,GAAG,GACJ,MAAM,mBAAmB,CAAA;AAC1B,cAAc,0BAA0B,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,4DAA4D;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EACL,QAAQ,EAGR,OAAO,EAIP,MAAM,GACP,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EAGL,WAAW,EACX,kBAAkB,GACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAA6B,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACjG,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,WAAW,EAGX,oBAAoB,EAOpB,oBAAoB,GAGrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,cAAc,uBAAuB,CAAA"}

package/dist/store/StoreRegistry.d.ts

@@ -0,0 +1,190 @@
+import { UnknownError } from '@livestore/common';
+import type { LiveStoreSchema } from '@livestore/common/schema';
+import { Effect, type OtelTracer, Runtime, type Schema, type Scope } from '@livestore/utils/effect';
+import { type CreateStoreOptions } from './create-store.ts';
+import type { Store } from './store.ts';
+import type { OtelOptions } from './store-types.ts';
+/**
+ * Configuration options for stores managed by a {@link StoreRegistry}.
+ *
+ * Extends {@link CreateStoreOptions} with registry-specific settings for caching and observability.
+ * Use with {@link storeOptions} helper to get full type inference when defining reusable store configurations.
+ *
+ * @typeParam TSchema - The LiveStore schema type
+ * @typeParam TContext - User-defined context attached to the store
+ * @typeParam TSyncPayloadSchema - Schema for the sync payload sent to the backend
+ *
+ * @see {@link storeOptions} for defining reusable store configurations
+ * @see {@link StoreRegistry} for managing store lifecycles
+ */
+export interface RegistryStoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue> extends CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema> {
+    /**
+     * OpenTelemetry configuration for tracing store operations.
+     *
+     * When provided, store operations (boot, queries, commits) will be traced
+     * under the given root span context using the specified tracer.
+     */
+    otelOptions?: Partial<OtelOptions>;
+    /**
+     * The time in milliseconds that this store should remain
+     * in memory after becoming unused. When this store becomes
+     * unused (no active retentions), it will be disposed after this duration.
+     *
+     * Stores transition to the unused state as soon as they have no
+     * active retentions, so when all components which use that store
+     * have unmounted.
+     *
+     * @remarks
+     * - **Limitation:** Per-store values are not yet supported. Only the registry-level default
+     *   (via `StoreRegistry` constructor's `defaultOptions.unusedCacheTime`) is used.
+     *   See {@link https://github.com/livestorejs/livestore/issues/917 | #917} for per-store support
+     *   and {@link https://github.com/livestorejs/livestore/issues/918 | #918} for dynamic "longest wins" behavior.
+     * - If set to `Infinity`, will disable automatic disposal
+     * - The maximum allowed time is about {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#maximum_delay_value | 24 days}
+     *
+     * @defaultValue `60_000` (60 seconds) or `Infinity` during SSR to avoid
+     * disposing stores before server render completes.
+     */
+    unusedCacheTime?: number;
+}
+type StoreRegistryConfig = {
+    /**
+     * Default options that are applied to all stores when they are loaded.
+     *
+     * @remarks
+     * These are options that typically don't depend on the specific store being loaded:
+     * - Framework integration (`batchUpdates`)
+     * - Environment settings (`disableDevtools`, `debug`, `otelOptions`)
+     * - Behavior defaults (`confirmUnsavedChanges`, `unusedCacheTime`)
+     *
+     * Store-specific fields like `schema`, `adapter`, `storeId`, and `boot` are intentionally
+     * excluded since they vary per store definition.
+     */
+    defaultOptions?: Partial<Pick<RegistryStoreOptions, 'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'debug' | 'otelOptions' | 'unusedCacheTime'>>;
+    /**
+     * Custom Effect runtime for all registry operations (loading, caching, etc.).
+     * When the runtime's scope closes, all managed stores are automatically shut down.
+     */
+    runtime?: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>;
+};
+/**
+ * Store Registry coordinating store loading, caching, and retention
+ *
+ * @public
+ */
+export declare class StoreRegistry {
+    #private;
+    /**
+     * Creates a new StoreRegistry instance.
+     *
+     * @example
+     * ```ts
+     * const registry = new StoreRegistry({
+     *   defaultOptions: {
+     *     batchUpdates,
+     *     unusedCacheTime: 30_000,
+     *   }
+     * })
+     * ```
+     */
+    constructor(config?: StoreRegistryConfig);
+    /**
+     * Gets a cached store or loads a new one, with the store lifetime scoped to the caller.
+     *
+     * @typeParam TSchema - The schema type for the store
+     * @typeParam TContext - The context type for the store
+     * @typeParam TSyncPayloadSchema - The sync payload schema type
+     * @returns 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
+     */
+    getOrLoad: <TSchema extends LiveStoreSchema, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>(options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>) => Effect.Effect<Store<TSchema, TContext>, UnknownError, Scope.Scope>;
+    /**
+     * Get or load a store, returning it directly if already loaded or a promise if loading.
+     *
+     * @typeParam TSchema - The schema type for the store
+     * @typeParam TContext - The context type for the store
+     * @typeParam TSyncPayloadSchema - The sync payload schema type
+     * @returns 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
+     */
+    getOrLoadPromise: <TSchema extends LiveStoreSchema, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>(options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>) => Store<TSchema, TContext> | Promise<Store<TSchema, TContext>>;
+    /**
+     * Retains the store in cache.
+     *
+     * @typeParam TSchema - The schema type for the store
+     * @typeParam TContext - The context type for the store
+     * @typeParam TSyncPayloadSchema - The sync payload schema type
+     * @returns A release function that, when called, removes this retention hold
+     *
+     * @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
+     */
+    retain: <TSchema extends LiveStoreSchema, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>(options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>) => (() => void);
+    /**
+     * Loads a store (without suspending) to warm up the cache.
+     *
+     * @typeParam TSchema - The schema of the store to preload
+     * @typeParam TContext - The context type for the store
+     * @typeParam TSyncPayloadSchema - The sync payload schema type
+     * @returns 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.
+     */
+    preload: <TSchema extends LiveStoreSchema, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>(options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>) => Promise<void>;
+}
+/**
+ * Helper for defining reusable store options with full type inference. Returns
+ * options that can be passed to `useStore()` or `storeRegistry.preload()`.
+ *
+ * @remarks
+ * At runtime this is an identity function that returns the input unchanged.
+ * Its value lies in enabling TypeScript's excess property checking to catch
+ * typos and configuration errors, while allowing options to be shared across
+ * `useStore()`, `storeRegistry.preload()`, `storeRegistry.getOrLoad()`, etc.
+ *
+ * @typeParam TSchema - The LiveStore schema type
+ * @typeParam TContext - User-defined context attached to the store
+ * @typeParam TSyncPayloadSchema - Schema for the sync payload sent to the backend
+ * @param options - The store configuration options
+ * @returns The same options object, unchanged
+ *
+ * @example
+ * ```ts
+ * export const issueStoreOptions = (issueId: string) =>
+ *   storeOptions({
+ *     storeId: `issue-${issueId}`,
+ *     schema,
+ *     adapter,
+ *     unusedCacheTime: 30_000,
+ *   })
+ *
+ * // In a component
+ * const issueStore = useStore(issueStoreOptions(issueId))
+ *
+ * // In a route loader or event handler
+ * storeRegistry.preload({
+ *   ...issueStoreOptions(issueId),
+ *   unusedCacheTime: 10_000,
+ * });
+ * ```
+ */
+export declare function storeOptions<TSchema extends LiveStoreSchema, TContext = {}, TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>(options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>): RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>;
+export {};
+//# sourceMappingURL=StoreRegistry.d.ts.map

package/dist/store/StoreRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoreRegistry.d.ts","sourceRoot":"","sources":["../../src/store/StoreRegistry.ts"],"names":[],"mappings":"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"}