@livestore/livestore 0.0.12 → 0.0.15

package/dist/store.d.ts

@@ -0,0 +1,199 @@
+import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
+import * as otel from '@opentelemetry/api';
+import type { GraphQLSchema } from 'graphql';
+import type * as Sqlite from 'sqlite-esm';
+import type { ComponentKey } from './componentKey.js';
+import type { QueryDefinition } from './effect/LiveStore.js';
+import type { LiveStoreEvent } from './events.js';
+import { InMemoryDatabase } from './inMemoryDatabase.js';
+import type { Atom, Ref } from './reactive.js';
+import { ReactiveGraph } from './reactive.js';
+import { LiveStoreGraphQLQuery } from './reactiveQueries/graphql.js';
+import { LiveStoreJSQuery } from './reactiveQueries/js.js';
+import { LiveStoreSQLQuery } from './reactiveQueries/sql.js';
+import type { GetActionArgs, Schema } from './schema.js';
+import type { Storage, StorageInit } from './storage/index.js';
+import type { Bindable, ParamsObject } from './util.js';
+export type GetAtomResult = <T>(atom: Atom<T> | LiveStoreJSQuery<T>) => T;
+export type LiveStoreQuery<TResult extends Record<string, any> = any> = LiveStoreSQLQuery<TResult> | LiveStoreJSQuery<TResult> | LiveStoreGraphQLQuery<TResult, any, any>;
+export type BaseGraphQLContext = {
+    queriedTables: Set<string>;
+    /** Needed by Pothos Otel plugin for resolver tracing to work */
+    otelContext?: otel.Context;
+};
+export type QueryResult<TQuery> = TQuery extends LiveStoreSQLQuery<infer R> ? ReadonlyArray<Readonly<R>> : TQuery extends LiveStoreJSQuery<infer S> ? Readonly<S> : TQuery extends LiveStoreGraphQLQuery<infer Result, any, any> ? Readonly<Result> : never;
+export type GraphQLOptions<TContext> = {
+    schema: GraphQLSchema;
+    makeContext: (db: InMemoryDatabase, tracer: otel.Tracer) => TContext;
+};
+export type StoreOptions<TGraphQLContext extends BaseGraphQLContext> = {
+    db: InMemoryDatabase;
+    /** A `Proxy`d version of `db` except that it also mirrors `execute` calls to the storage */
+    dbProxy: InMemoryDatabase;
+    schema: Schema;
+    storage?: Storage;
+    graphQLOptions?: GraphQLOptions<TGraphQLContext>;
+    otelTracer: otel.Tracer;
+    otelRootSpanContext: otel.Context;
+};
+export type RefreshReason = {
+    _tag: 'applyEvent';
+    /** The event that was applied */
+    event: Omit<LiveStoreEvent, 'id'>;
+    /** The tables that were written to by the event */
+    writeTables: string[];
+} | {
+    _tag: 'applyEvents';
+    /** The events that was applied */
+    events: Omit<LiveStoreEvent, 'id'>[];
+    /** The tables that were written to by the event */
+    writeTables: string[];
+}
+/** Usually in response to some `applyEvent`/`applyEvents` with `skipRefresh: true` */
+ | {
+    _tag: 'manualRefresh';
+} | {
+    _tag: 'makeThunk';
+    label?: string;
+} | {
+    _tag: 'unknown';
+};
+export type QueryDebugInfo = {
+    _tag: 'graphql' | 'sql' | 'js' | 'unknown';
+    label: string;
+    query: string;
+};
+export type StoreOtel = {
+    tracer: otel.Tracer;
+    applyEventsSpanContext: otel.Context;
+    queriesSpanContext: otel.Context;
+};
+export declare class Store<TGraphQLContext extends BaseGraphQLContext = BaseGraphQLContext> {
+    graph: ReactiveGraph<RefreshReason, QueryDebugInfo>;
+    inMemoryDB: InMemoryDatabase;
+    _proxyDb: InMemoryDatabase;
+    schema: Schema;
+    graphQLSchema?: GraphQLSchema;
+    graphQLContext?: TGraphQLContext;
+    otel: StoreOtel;
+    /**
+     * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
+     * This only works in combination with `equal: () => false` which will always trigger a refresh.
+     */
+    tableRefs: {
+        [key: string]: Ref<null>;
+    };
+    activeQueries: Set<LiveStoreQuery>;
+    storage?: Storage;
+    temporaryQueries: Set<LiveStoreQuery> | undefined;
+    private constructor();
+    static createStore: <TGraphQLContext_1 extends BaseGraphQLContext>(storeOptions: StoreOptions<TGraphQLContext_1>, parentSpan: otel.Span) => Store<TGraphQLContext_1>;
+    /**
+     * Creates a reactive LiveStore SQL query
+     *
+     * NOTE The query is actually running (even if no one has subscribed to it yet) and will be kept up to date.
+     */
+    querySQL: <TResult>(genQueryString: string | ((get: GetAtomResult) => string), { queriedTables, bindValues, componentKey, label, otelContext, }: {
+        /**
+         * List of tables that are queried in this query;
+         * used to determine reactive dependencies.
+         *
+         * NOTE In the future we want to auto-generate this via parsing the query
+         */
+        queriedTables: string[];
+        bindValues?: Bindable | undefined;
+        componentKey?: ComponentKey | undefined;
+        label?: string | undefined;
+        otelContext?: otel.Context | undefined;
+    }) => LiveStoreSQLQuery<TResult>;
+    queryJS: <TResult>(genResults: (get: GetAtomResult) => TResult, { componentKey, label, otelContext, }: {
+        componentKey?: ComponentKey | undefined;
+        label?: string | undefined;
+        otelContext?: otel.Context | undefined;
+    }) => LiveStoreJSQuery<TResult>;
+    queryGraphQL: <TResult extends Record<string, any>, TVariableValues extends Record<string, any>>(document: DocumentNode<TResult, TVariableValues>, genVariableValues: TVariableValues | ((get: GetAtomResult) => TVariableValues), { componentKey, label, otelContext, }: {
+        componentKey: ComponentKey;
+        label?: string | undefined;
+        otelContext?: otel.Context | undefined;
+    }) => LiveStoreGraphQLQuery<TResult, TVariableValues, TGraphQLContext>;
+    queryGraphQLOnce: <TResult extends Record<string, any>, TVariableValues extends Record<string, any>>(document: DocumentNode<TResult, TVariableValues>, variableValues: TVariableValues, otelContext?: otel.Context) => {
+        result: TResult;
+        queriedTables: string[];
+    };
+    /**
+     * Subscribe to the results of a query
+     * Returns a function to cancel the subscription.
+     */
+    subscribe: <TQuery extends LiveStoreQuery<any>>(query: TQuery, onNewValue: (value: QueryResult<TQuery>) => void, onSubsubscribe?: () => void, options?: {
+        label?: string;
+    } | undefined) => (() => void);
+    /**
+     * Any queries created in the callback will be destroyed when the callback is complete.
+     * Useful for temporarily creating reactive queries, which is an idempotent operation
+     * that can be safely called inside a React useMemo hook.
+     */
+    inTempQueryContext: <TResult>(callback: () => TResult) => TResult;
+    /**
+     * Destroys the entire store, including all queries and subscriptions.
+     *
+     * Currently only used when shutting down the app for debugging purposes (e.g. to close Otel spans).
+     */
+    destroy: () => void;
+    private destroyQuery;
+    /**
+     * Clean up queries and downstream subscriptions associated with a component.
+     * This is critical to avoid memory leaks.
+     */
+    unmountComponent: (componentKey: ComponentKey) => void;
+    applyEvent: <TEventType extends string>(eventType: TEventType, args?: any, options?: {
+        skipRefresh?: boolean;
+    }) => {
+        durationMs: number;
+    };
+    /**
+     * Apply multiple write events to the store, and refresh all queries in response.
+     * This is faster than calling applyEvent many times in quick succession because
+     * we can do a single refresh after all the events.
+     */
+    applyEvents: (events: Iterable<{
+        eventType: string;
+        args: any;
+    }>, options?: {
+        label?: string;
+        skipRefresh?: boolean;
+    }) => {
+        durationMs: number;
+    };
+    /**
+     * This can be used in combination with `skipRefresh` when applying events.
+     * We might need a better solution for this. Let's see.
+     */
+    manualRefresh: (options?: {
+        label?: string;
+    }) => void;
+    runOnce: <TQueryDef extends QueryDefinition>(queryDef: TQueryDef) => QueryResult<ReturnType<TQueryDef>>;
+    /**
+     * Apply an event to the store.
+     * Returns the tables that were affected by the event.
+     * This is an internal method that doesn't trigger a refresh;
+     * the caller must refresh queries after calling this method.
+     */
+    private applyEventWithoutRefresh;
+    /**
+     * Directly execute a SQL query on the Store.
+     * This should only be used for framework-internal purposes;
+     * all app writes should go through applyEvent.
+     */
+    execute: (query: string, params?: ParamsObject, writeTables?: string[]) => Promise<void>;
+}
+/** Create a new LiveStore Store */
+export declare const createStore: <TGraphQLContext extends BaseGraphQLContext>({ schema, loadStorage, graphQLOptions, otelTracer, otelRootSpanContext, boot, sqlite3, }: {
+    schema: Schema;
+    loadStorage: () => StorageInit | Promise<StorageInit>;
+    graphQLOptions?: GraphQLOptions<TGraphQLContext> | undefined;
+    otelTracer?: otel.Tracer | undefined;
+    otelRootSpanContext?: otel.Context | undefined;
+    boot?: ((db: InMemoryDatabase, parentSpan: otel.Span) => unknown | Promise<unknown>) | undefined;
+    sqlite3: Sqlite.Sqlite3Static;
+}) => Promise<Store<TGraphQLContext>>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

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