@livestore/livestore 0.0.39-dev.3 → 0.0.40

package/src/reactive.ts

@@ -24,7 +24,7 @@
 /* eslint-disable prefer-arrow/prefer-arrow-functions */
 
 import type { PrettifyFlat } from '@livestore/utils'
-import { pick, shouldNeverHappen } from '@livestore/utils'
+import { shouldNeverHappen } from '@livestore/utils'
 import type * as otel from '@opentelemetry/api'
 import { isEqual } from 'lodash-es'
 
@@ -94,7 +94,7 @@ export type DebugThunkInfo<T extends string = string> = {
 }
 
 export type DebugRefreshReasonBase =
-  /** Usually in response to some `applyEvent`/`applyEvents` with `skipRefresh: true` */
+  /** Usually in response to some `mutate` calls with `skipRefresh: true` */
   | {
       _tag: 'runDeferredEffects'
       originalRefreshReasons?: ReadonlyArray<DebugRefreshReasonBase>
@@ -135,7 +135,7 @@ const unknownRefreshReason = () => {
 
 export type SerializedAtom = Readonly<
   PrettifyFlat<
-    Pick<Atom<unknown, unknown, any>, '_tag' | 'id' | 'label' | 'meta'> & {
+    Pick<Atom<unknown, unknown, any>, '_tag' | 'id' | 'label' | 'meta' | 'isDirty'> & {
       sub: ReadonlyArray<string>
       super: ReadonlyArray<string>
     }
@@ -162,17 +162,6 @@ const uniqueNodeId = () => `node-${++nodeIdCounter}`
 let refreshInfoIdCounter = 0
 const uniqueRefreshInfoId = () => `refresh-info-${++refreshInfoIdCounter}`
 
-const serializeAtom = (atom: Atom<any, unknown, any>): SerializedAtom => ({
-  ...pick(atom, ['_tag', 'id', 'label', 'meta', 'isDirty']),
-  sub: Array.from(atom.sub).map((a) => a.id),
-  super: Array.from(atom.super).map((a) => a.id),
-})
-
-const serializeEffect = (effect: Effect): SerializedEffect => ({
-  ...pick(effect, ['_tag', 'id', 'label']),
-  sub: Array.from(effect.sub).map((a) => a.id),
-})
-
 let globalGraphIdCounter = 0
 const uniqueGraphId = () => `graph-${++globalGraphIdCounter}`
 
@@ -515,11 +504,25 @@ export class ReactiveGraph<
     subComp.super.delete(superComp)
   }
 
-  getSnapshot = (): ReactiveGraphSnapshot => ({
-    atoms: Array.from(this.atoms).map(serializeAtom),
-    effects: Array.from(this.effects).map(serializeEffect),
-    deferredEffects: Array.from(this.deferredEffects.keys()).map((_) => _.id),
-  })
+  // NOTE This function is performance-optimized (i.e. not using `Array.from`)
+  getSnapshot = (): ReactiveGraphSnapshot => {
+    const atoms: SerializedAtom[] = []
+    for (const atom of this.atoms) {
+      atoms.push(serializeAtom(atom))
+    }
+
+    const effects: SerializedEffect[] = []
+    for (const effect of this.effects) {
+      effects.push(serializeEffect(effect))
+    }
+
+    const deferredEffects: string[] = []
+    for (const [effect] of this.deferredEffects) {
+      deferredEffects.push(effect.id)
+    }
+
+    return { atoms, effects, deferredEffects }
+  }
 
   subscribeToRefresh = (cb: () => void) => {
     this.refreshCallbacks.add(cb)
@@ -561,3 +564,41 @@ const markSuperCompDirtyRec = <T>(atom: Atom<T, unknown, any>, effectsToRefresh:
 export const throwContextNotSetError = (graph: ReactiveGraph<any, any, any>): never => {
   throw new Error(`LiveStore Error: \`context\` not set on ReactiveGraph (${graph.id})`)
 }
+
+// NOTE This function is performance-optimized (i.e. not using `pick` and `Array.from`)
+const serializeAtom = (atom: Atom<any, unknown, any>): SerializedAtom => {
+  const sub: string[] = []
+  for (const a of atom.sub) {
+    sub.push(a.id)
+  }
+
+  const super_: string[] = []
+  for (const a of atom.super) {
+    super_.push(a.id)
+  }
+
+  return {
+    _tag: atom._tag,
+    id: atom.id,
+    label: atom.label,
+    meta: atom.meta,
+    isDirty: atom.isDirty,
+    sub,
+    super: super_,
+  }
+}
+
+// NOTE This function is performance-optimized (i.e. not using `pick` and `Array.from`)
+const serializeEffect = (effect: Effect): SerializedEffect => {
+  const sub: string[] = []
+  for (const a of effect.sub) {
+    sub.push(a.id)
+  }
+
+  return {
+    _tag: effect._tag,
+    id: effect.id,
+    label: effect.label,
+    sub,
+  }
+}

package/src/reactiveQueries/base-class.ts

@@ -1,10 +1,10 @@
 import type * as otel from '@opentelemetry/api'
 import ReactDOM from 'react-dom'
 
+import type { QueryInfo, QueryInfoNone } from '../query-info.js'
 import type { StackInfo } from '../react/utils/stack-info.js'
 import { type Atom, type GetAtom, ReactiveGraph, throwContextNotSetError, type Thunk } from '../reactive.js'
 import type { QueryDebugInfo, RefreshReason, Store } from '../store.js'
-import type { UpdatePathDesc, UpdatePathDescNone } from '../update-path.js'
 
 export type DbGraph = ReactiveGraph<RefreshReason, QueryDebugInfo, DbContext>
 
@@ -26,12 +26,14 @@ export type GetResult<TQuery extends LiveQueryAny> = TQuery extends LiveQuery<in
 
 let queryIdCounter = 0
 
-export type LiveQueryAny = LiveQuery<any, UpdatePathDesc>
+export type LiveQueryAny = LiveQuery<any, QueryInfo>
 
-export interface LiveQuery<TResult, TUpdatePath extends UpdatePathDesc = UpdatePathDescNone> {
+export interface LiveQuery<TResult, TQueryInfo extends QueryInfo = QueryInfoNone> {
   id: number
   _tag: 'js' | 'sql' | 'graphql'
-  'result!': TResult
+
+  /** This should only be used on a type-level and doesn't hold any value during runtime */
+  '__result!': TResult
 
   /** A reactive thunk representing the query results */
   results$: Thunk<TResult, DbContext, RefreshReason>
@@ -40,19 +42,29 @@ export interface LiveQuery<TResult, TUpdatePath extends UpdatePathDesc = UpdateP
 
   run: (otelContext?: otel.Context, debugRefreshReason?: RefreshReason) => TResult
 
+  runAndDestroy: (otelContext?: otel.Context, debugRefreshReason?: RefreshReason) => TResult
+
   destroy(): void
 
+  subscribe(
+    onNewValue: (value: TResult) => void,
+    onUnsubsubscribe?: () => void,
+    options?: { label?: string; otelContext?: otel.Context },
+  ): () => void
+
   activeSubscriptions: Set<StackInfo>
 
-  updatePathDesc: TUpdatePath
+  queryInfo: TQueryInfo
 
   runs: number
+
+  executionTimes: number[]
 }
 
-export abstract class LiveStoreQueryBase<TResult, TUpdatePath extends UpdatePathDesc>
-  implements LiveQuery<TResult, TUpdatePath>
+export abstract class LiveStoreQueryBase<TResult, TQueryInfo extends QueryInfo>
+  implements LiveQuery<TResult, TQueryInfo>
 {
-  'result!'!: TResult
+  '__result!'!: TResult
   id = queryIdCounter++
   abstract _tag: 'js' | 'sql' | 'graphql'
 
@@ -65,12 +77,14 @@ export abstract class LiveStoreQueryBase<TResult, TUpdatePath extends UpdatePath
 
   protected abstract dbGraph: DbGraph
 
-  abstract updatePathDesc: TUpdatePath
+  abstract queryInfo: TQueryInfo
 
   get runs() {
     return this.results$.recomputations
   }
 
+  executionTimes: number[] = []
+
   abstract destroy: () => void
 
   run = (otelContext?: otel.Context, debugRefreshReason?: RefreshReason): TResult =>

package/src/reactiveQueries/graphql.ts

@@ -1,34 +1,43 @@
 import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
-import { assertNever, shouldNeverHappen } from '@livestore/utils'
+import { shouldNeverHappen } from '@livestore/utils'
+import { Schema, TreeFormatter } from '@livestore/utils/effect'
 import * as otel from '@opentelemetry/api'
 import * as graphql from 'graphql'
 
 import { globalDbGraph } from '../global-state.js'
+import type { QueryInfoNone } from '../query-info.js'
 import type { Thunk } from '../reactive.js'
 import type { BaseGraphQLContext, RefreshReason, Store } from '../store.js'
-import type { UpdatePathDescNone } from '../update-path.js'
 import { getDurationMsFromSpan } from '../utils/otel.js'
 import type { DbContext, DbGraph, GetAtomResult, LiveQuery } from './base-class.js'
 import { LiveStoreQueryBase, makeGetAtomResult } from './base-class.js'
 
-export const queryGraphQL = <TResult extends Record<string, any>, TVariableValues extends Record<string, any>>(
+export type MapResult<To, From> = ((res: From, get: GetAtomResult) => To) | Schema.Schema<never, From, To>
+
+export const queryGraphQL = <
+  TResult extends Record<string, any>,
+  TVariableValues extends Record<string, any>,
+  TResultMapped extends Record<string, any> = TResult,
+>(
   document: DocumentNode<TResult, TVariableValues>,
   genVariableValues: TVariableValues | ((get: GetAtomResult) => TVariableValues),
-  { label, dbGraph }: { label?: string; dbGraph?: DbGraph } = {},
-): LiveQuery<TResult, UpdatePathDescNone> => new LiveStoreGraphQLQuery({ document, genVariableValues, label, dbGraph })
+  { label, dbGraph, map }: { label?: string; dbGraph?: DbGraph; map?: MapResult<TResultMapped, TResult> } = {},
+): LiveQuery<TResultMapped, QueryInfoNone> =>
+  new LiveStoreGraphQLQuery({ document, genVariableValues, label, dbGraph, map })
 
 export class LiveStoreGraphQLQuery<
   TResult extends Record<string, any>,
   TVariableValues extends Record<string, any>,
   TContext extends BaseGraphQLContext,
-> extends LiveStoreQueryBase<TResult, UpdatePathDescNone> {
+  TResultMapped extends Record<string, any> = TResult,
+> extends LiveStoreQueryBase<TResultMapped, QueryInfoNone> {
   _tag: 'graphql' = 'graphql'
 
   /** The abstract GraphQL query */
   document: DocumentNode<TResult, TVariableValues>
 
   /** A reactive thunk representing the query results */
-  results$: Thunk<TResult, DbContext, RefreshReason>
+  results$: Thunk<TResultMapped, DbContext, RefreshReason>
 
   variableValues$: Thunk<TVariableValues, DbContext, RefreshReason>
 
@@ -36,18 +45,22 @@ export class LiveStoreGraphQLQuery<
 
   protected dbGraph: DbGraph
 
-  updatePathDesc: UpdatePathDescNone = { _tag: 'None' }
+  queryInfo: QueryInfoNone = { _tag: 'None' }
+
+  private mapResult
 
   constructor({
     document,
     label,
     genVariableValues,
     dbGraph,
+    map,
   }: {
     document: DocumentNode<TResult, TVariableValues>
     genVariableValues: TVariableValues | ((get: GetAtomResult) => TVariableValues)
     label?: string
     dbGraph?: DbGraph
+    map?: MapResult<TResultMapped, TResult>
   }) {
     super()
 
@@ -58,6 +71,23 @@ export class LiveStoreGraphQLQuery<
 
     this.dbGraph = dbGraph ?? globalDbGraph
 
+    this.mapResult =
+      map === undefined
+        ? (res: TResult) => res as any as TResultMapped
+        : Schema.isSchema(map)
+          ? (res: TResult) => {
+              const parseResult = Schema.decodeEither(map as Schema.Schema<never, TResult, TResultMapped>)(res)
+              if (parseResult._tag === 'Left') {
+                console.error(`Error parsing GraphQL query result: ${TreeFormatter.formatError(parseResult.left)}`)
+                return shouldNeverHappen(`Error parsing SQL query result: ${parseResult.left}`)
+              } else {
+                return parseResult.right as TResultMapped
+              }
+            }
+          : typeof map === 'function'
+            ? map
+            : shouldNeverHappen(`Invalid map function ${map}`)
+
     // TODO don't even create a thunk if variables are static
     const variableValues$ = this.dbGraph.makeThunk(
       (get, _setDebugInfo, { rootOtelContext }, otelContext) => {
@@ -73,7 +103,7 @@ export class LiveStoreGraphQLQuery<
     this.variableValues$ = variableValues$
 
     const resultsLabel = `${labelWithDefault}:results`
-    this.results$ = this.dbGraph.makeThunk<TResult>(
+    this.results$ = this.dbGraph.makeThunk<TResultMapped>(
       (get, setDebugInfo, { store, otelTracer, rootOtelContext }, otelContext) => {
         const variableValues = get(variableValues$)
         const { result, queriedTables, durationMs } = this.queryOnce({
@@ -82,13 +112,13 @@ export class LiveStoreGraphQLQuery<
           otelContext: otelContext ?? rootOtelContext,
           otelTracer,
           store: store as Store<TContext>,
+          get: makeGetAtomResult(get, otelContext ?? rootOtelContext),
         })
 
         // Add dependencies on any tables that were used
         for (const tableName of queriedTables) {
-          const tableRef = store.tableRefs[tableName]
-          assertNever(tableRef !== undefined, `No table ref found for ${tableName}`)
-          get(tableRef!)
+          const tableRef = store.tableRefs[tableName] ?? shouldNeverHappen(`No table ref found for ${tableName}`)
+          get(tableRef)
         }
 
         setDebugInfo({ _tag: 'graphql', label: resultsLabel, query: graphql.print(document), durationMs })
@@ -121,12 +151,14 @@ export class LiveStoreGraphQLQuery<
     otelTracer,
     variableValues,
     store,
+    get,
   }: {
     document: graphql.DocumentNode
     otelContext: otel.Context
     otelTracer: otel.Tracer
     variableValues: TVariableValues
     store: Store<TContext>
+    get: GetAtomResult
   }) => {
     const schema =
       store.graphQLSchema ?? shouldNeverHappen("Can't run a GraphQL query on a store without GraphQL schema")
@@ -161,10 +193,14 @@ export class LiveStoreGraphQLQuery<
 
       span.end()
 
+      const result = this.mapResult(res.data as unknown as TResult, get)
+
       const durationMs = getDurationMsFromSpan(span)
 
+      this.executionTimes.push(durationMs)
+
       return {
-        result: res.data as unknown as TResult,
+        result,
         queriedTables: Array.from(context.queriedTables.values()),
         durationMs,
       }

package/src/reactiveQueries/js.ts

@@ -1,32 +1,32 @@
 import * as otel from '@opentelemetry/api'
 
 import { globalDbGraph } from '../global-state.js'
+import type { QueryInfo, QueryInfoNone } from '../query-info.js'
 import type { Thunk } from '../reactive.js'
 import type { RefreshReason } from '../store.js'
-import type { UpdatePathDesc, UpdatePathDescNone } from '../update-path.js'
 import { getDurationMsFromSpan } from '../utils/otel.js'
 import type { DbContext, DbGraph, GetAtomResult, LiveQuery } from './base-class.js'
 import { LiveStoreQueryBase, makeGetAtomResult } from './base-class.js'
 
-export const computed = <TResult, TUpdatePath extends UpdatePathDesc = UpdatePathDescNone>(
+export const computed = <TResult, TQueryInfo extends QueryInfo = QueryInfoNone>(
   fn: (get: GetAtomResult) => TResult,
   options?: {
     label: string
     dbGraph?: DbGraph
-    updatePathDesc?: TUpdatePath
+    queryInfo?: TQueryInfo
   },
-): LiveQuery<TResult, TUpdatePath> =>
-  new LiveStoreJSQuery<TResult, TUpdatePath>({
+): LiveQuery<TResult, TQueryInfo> =>
+  new LiveStoreJSQuery<TResult, TQueryInfo>({
     fn,
     label: options?.label ?? fn.toString(),
     dbGraph: options?.dbGraph,
-    updatePathDesc: options?.updatePathDesc,
+    queryInfo: options?.queryInfo,
   })
 
-export class LiveStoreJSQuery<
+export class LiveStoreJSQuery<TResult, TQueryInfo extends QueryInfo = QueryInfoNone> extends LiveStoreQueryBase<
   TResult,
-  TUpdatePath extends UpdatePathDesc = UpdatePathDescNone,
-> extends LiveStoreQueryBase<TResult, TUpdatePath> {
+  TQueryInfo
+> {
   _tag: 'js' = 'js'
 
   /** A reactive thunk representing the query results */
@@ -36,7 +36,7 @@ export class LiveStoreJSQuery<
 
   protected dbGraph: DbGraph
 
-  updatePathDesc: TUpdatePath
+  queryInfo: TQueryInfo
 
   /**
    * Currently only used for "nested destruction" of piped queries
@@ -51,14 +51,14 @@ export class LiveStoreJSQuery<
     label,
     onDestroy,
     dbGraph,
-    updatePathDesc,
+    queryInfo,
   }: {
     label: string
     fn: (get: GetAtomResult) => TResult
     /** Currently only used for "nested destruction" of piped queries */
     onDestroy?: () => void
     dbGraph?: DbGraph
-    updatePathDesc?: TUpdatePath
+    queryInfo?: TQueryInfo
   }) {
     super()
 
@@ -66,7 +66,7 @@ export class LiveStoreJSQuery<
     this.label = label
 
     this.dbGraph = dbGraph ?? globalDbGraph
-    this.updatePathDesc = updatePathDesc ?? ({ _tag: 'None' } as TUpdatePath)
+    this.queryInfo = queryInfo ?? ({ _tag: 'None' } as TQueryInfo)
 
     const queryLabel = `${label}:results`
 
@@ -80,6 +80,8 @@ export class LiveStoreJSQuery<
 
           const durationMs = getDurationMsFromSpan(span)
 
+          this.executionTimes.push(durationMs)
+
           setDebugInfo({ _tag: 'js', label, query: fn.toString(), durationMs })
 
           return res

package/src/{__tests__/reactiveQueries → reactiveQueries}/sql.test.ts

@@ -3,8 +3,8 @@ import type { ReadableSpan } from '@opentelemetry/sdk-trace-base'
 import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
 import { describe, expect, it } from 'vitest'
 
-import { computed, ParseUtils, querySQL, sql } from '../../index.js'
-import { makeTodoMvc, todos } from '../react/fixture.js'
+import { makeTodoMvc, todos } from '../__tests__/react/fixture.js'
+import { computed, ParseUtils, querySQL, rawSqlMutation, sql } from '../index.js'
 
 /*
 TODO write tests for:
@@ -40,10 +40,7 @@ describe('otel', () => {
     const query = querySQL(`select * from todos`, { queriedTables: new Set(['todos']) })
     expect(query.run()).toMatchInlineSnapshot('[]')
 
-    store.applyEvent('livestore.RawSql', {
-      sql: sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);`,
-      writeTables: ['todos'],
-    })
+    store.mutate(rawSqlMutation({ sql: sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)` }))
 
     expect(query.run()).toMatchInlineSnapshot(`
       [
@@ -91,28 +88,36 @@ describe('otel', () => {
             },
           },
           {
-            "_name": "LiveStore:applyEvents",
+            "_name": "LiveStore:mutations",
             "children": [
               {
-                "_name": "LiveStore:applyEvent",
+                "_name": "LiveStore:mutate",
+                "attributes": {
+                  "livestore.mutateLabel": "mutate",
+                },
                 "children": [
                   {
-                    "_name": "LiveStore:applyEventWithoutRefresh",
+                    "_name": "LiveStore:processWrites",
                     "attributes": {
-                      "livestore.actionType": "livestore.RawSql",
-                      "livestore.args": "{
-        "sql": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);",
-        "writeTables": [
-          "todos"
-        ]
-      }",
+                      "livestore.mutateLabel": "mutate",
                     },
                     "children": [
                       {
-                        "_name": "livestore.in-memory-db:execute",
+                        "_name": "LiveStore:mutatetWithoutRefresh",
                         "attributes": {
-                          "sql.query": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);",
+                          "livestore.args": "{
+        "sql": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)"
+      }",
+                          "livestore.mutation": "livestore.RawSql",
                         },
+                        "children": [
+                          {
+                            "_name": "livestore.in-memory-db:execute",
+                            "attributes": {
+                              "sql.query": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)",
+                            },
+                          },
+                        ],
                       },
                     ],
                   },
@@ -183,10 +188,7 @@ describe('otel', () => {
       }
     `)
 
-    store.applyEvent('livestore.RawSql', {
-      sql: sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);`,
-      writeTables: ['todos'],
-    })
+    store.mutate(rawSqlMutation({ sql: sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)` }))
 
     expect(query.run()).toMatchInlineSnapshot(`
       {
@@ -232,28 +234,36 @@ describe('otel', () => {
             },
           },
           {
-            "_name": "LiveStore:applyEvents",
+            "_name": "LiveStore:mutations",
             "children": [
               {
-                "_name": "LiveStore:applyEvent",
+                "_name": "LiveStore:mutate",
+                "attributes": {
+                  "livestore.mutateLabel": "mutate",
+                },
                 "children": [
                   {
-                    "_name": "LiveStore:applyEventWithoutRefresh",
+                    "_name": "LiveStore:processWrites",
                     "attributes": {
-                      "livestore.actionType": "livestore.RawSql",
-                      "livestore.args": "{
-        "sql": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);",
-        "writeTables": [
-          "todos"
-        ]
-      }",
+                      "livestore.mutateLabel": "mutate",
                     },
                     "children": [
                       {
-                        "_name": "livestore.in-memory-db:execute",
+                        "_name": "LiveStore:mutatetWithoutRefresh",
                         "attributes": {
-                          "sql.query": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);",
+                          "livestore.args": "{
+        "sql": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)"
+      }",
+                          "livestore.mutation": "livestore.RawSql",
                         },
+                        "children": [
+                          {
+                            "_name": "livestore.in-memory-db:execute",
+                            "attributes": {
+                              "sql.query": "INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)",
+                            },
+                          },
+                        ],
                       },
                     ],
                   },