@livestore/livestore 0.0.12 → 0.0.14

package/src/util.ts

@@ -1,8 +1,14 @@
+/// <reference lib="es2022" />
+
+import type { Brand } from '@livestore/utils/effect'
+
 export type ParamsObject = Record<string, SqlValue>
-export type SqlValue = string | number | Uint8Array
+export type SqlValue = string | number | Uint8Array | null
 
 export type Bindable = SqlValue[] | ParamsObject
 
+export type PreparedBindValues = Brand.Branded<Bindable, 'PreparedBindValues'>
+
 /**
  * This is a tag function for tagged literals.
  * it lets us get syntax highlighting on SQL queries in VSCode, but
@@ -23,7 +29,9 @@ export const sql = (template: TemplateStringsArray, ...args: unknown[]): string
 /*  because rusqlite doesn't allow unused named params
 /*  TODO: Search for unused params via proper parsing, not string search
 **/
-export const prepareBindValues = (values: ParamsObject, statement: string): ParamsObject => {
+export const prepareBindValues = (values: Bindable, statement: string): PreparedBindValues => {
+  if (Array.isArray(values)) return values as PreparedBindValues
+
   const result: ParamsObject = {}
   for (const [key, value] of Object.entries(values)) {
     if (statement.includes(key)) {
@@ -31,7 +39,7 @@ export const prepareBindValues = (values: ParamsObject, statement: string): Para
     }
   }
 
-  return result
+  return result as PreparedBindValues
 }
 
 /**
@@ -57,3 +65,5 @@ export const objectToString = (error: any): string => {
     return 'Error while printing error: ' + e
   }
 }
+
+export const isPromise = (value: any): value is Promise<unknown> => typeof value?.then === 'function'

package/tsconfig.json

@@ -9,7 +9,5 @@
     "tsBuildInfoFile": "./dist/.tsbuildinfo"
   },
   "include": ["./src"],
-  "references": [
-    { "path": "../utils" },
-  ]
+  "references": [{ "path": "../../effect-db-schema" }, { "path": "../utils" }]
 }

package/src/backends/base.ts

@@ -1,67 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-import { errorToString } from '@livestore/utils'
-import { identity } from '@livestore/utils/effect'
-import * as otel from '@opentelemetry/api'
-
-import type { LiveStoreEvent } from '../events.js'
-// import { EVENTS_TABLE_NAME } from '../events.js'
-import type { ActionDefinition } from '../schema.js'
-import type { ParamsObject } from '../util.js'
-import type { Backend, SelectResponse } from './index.js'
-
-export abstract class BaseBackend implements Backend {
-  abstract otelTracer: otel.Tracer
-
-  select = async <T = any>(query: string, bindValues?: ParamsObject): Promise<SelectResponse<T>> => {
-    throw new Error('Method not implemented.')
-  }
-
-  execute = (query: string, bindValues?: ParamsObject, parentSpan?: otel.Span): void => {
-    throw new Error('Method not implemented.')
-  }
-
-  getPersistedData = async (parentSpan?: otel.Span): Promise<Uint8Array> => {
-    throw new Error('Method not implemented.')
-  }
-
-  // TODO move `applyEvent` logic to Store and only call `execute` here
-  applyEvent = (event: LiveStoreEvent, eventDefinition: ActionDefinition, parentSpan?: otel.Span): void => {
-    const ctx = parentSpan ? otel.trace.setSpan(otel.context.active(), parentSpan) : otel.context.active()
-    this.otelTracer.startActiveSpan('LiveStore:backend:applyEvent', {}, ctx, (span) => {
-      try {
-        // Careful: this SQL statement is duplicated in the backend.
-        // Remember to update it in src-tauri/src/store.rs:apply_event as well.
-        // await this.execute(sql`insert into ${EVENTS_TABLE_NAME} (id, type, args) values ($id, $type, $args)`, {
-        //   id: event.id,
-        //   type: event.type,
-        //   args: JSON.stringify(event.args ?? {}),
-        // })
-
-        const statement =
-          typeof eventDefinition.statement === 'function'
-            ? eventDefinition.statement(event.args)
-            : eventDefinition.statement
-
-        const prepareBindValues = eventDefinition.prepareBindValues ?? identity
-
-        const bindValues =
-          typeof eventDefinition.statement === 'function' && statement.argsAlreadyBound
-            ? {}
-            : prepareBindValues(event.args)
-
-        span.setAttributes({
-          'livestore.statement.sql': statement.sql,
-          'livestore.statement.writeTables': statement.writeTables,
-          'livestore.statement.bindVales': JSON.stringify(bindValues),
-        })
-
-        this.execute(statement.sql, bindValues, span)
-      } catch (e: any) {
-        span.setStatus({ code: otel.SpanStatusCode.ERROR, message: errorToString(e) })
-        throw e
-      } finally {
-        span.end()
-      }
-    })
-  }
-}

package/src/backends/index.ts

@@ -1,98 +0,0 @@
-// A backend represents a raw SQLite database.
-// Examples include:
-// - A native SQLite process running in a Tauri Rust process
-// - A SQL.js WASM version of SQLite running in a web worker
-//
-// We can send commands to execute various kinds of queries,
-// and respond to various events from the database.
-
-import type * as otel from '@opentelemetry/api'
-
-import type { LiveStoreEvent } from '../events.js'
-import type { ActionDefinition } from '../schema.js'
-import type { ParamsObject } from '../util.js'
-import { casesHandled } from '../util.js'
-import type { BackendOptionsTauri } from './tauri.js'
-import type { BackendOptionsWeb } from './web.js'
-import { WebWorkerBackend } from './web.js'
-import type { BackendOptionsWebInMemory } from './web-in-memory.js'
-import { WebInMemoryBackend } from './web-in-memory.js'
-
-/* A location of a persistent writable SQLite file */
-export type WritableDatabaseLocation =
-  | {
-      type: 'opfs'
-      virtualFilename: string
-    }
-  | {
-      type: 'indexeddb'
-      virtualFilename: string
-    }
-  | {
-      type: 'filesystem'
-      directory: string
-      filename: string
-    }
-  | {
-      type: 'volatile-in-memory'
-    }
-
-export interface Backend {
-  // Select some data from the DB.
-  // This should only do reads, not writes, but we don't strongly enforce that.
-  select<T = any>(query: string, bindValues?: ParamsObject, parentSpan?: otel.Span): Promise<SelectResponse<T>>
-
-  // Execute a query where you don't care about the result.
-  // Used for writes and configuration changes.
-  execute(query: string, bindValues?: ParamsObject, parentSpan?: otel.Span): void
-
-  /** Apply an event to the backend */
-  applyEvent(event: LiveStoreEvent, eventDefiniton: ActionDefinition, parentSpan?: otel.Span): void
-
-  /** Return a snapshot of persisted data from the backend */
-  getPersistedData(parentSpan?: otel.Span): Promise<Uint8Array>
-}
-
-export type BackendType = 'tauri' | 'web' | 'web-in-memory'
-
-export const isBackendType = (type: string): type is BackendType => {
-  return type === 'tauri' || type === 'web' || type === 'web-in-memory'
-}
-
-export type SelectResponse<T = any> = {
-  results: T[]
-
-  // other perf stats metadata about how long the query took
-  [key: string]: any
-}
-
-export enum IndexType {
-  Basic = 'Basic',
-  FullText = 'FullText',
-}
-
-export type BackendOptions = BackendOptionsTauri | BackendOptionsWeb | BackendOptionsWebInMemory
-export type BackendOtelProps = {
-  otelTracer: otel.Tracer
-  parentSpan: otel.Span
-}
-
-export const createBackend = async (options: BackendOptions, otelProps: BackendOtelProps): Promise<Backend> => {
-  switch (options.type) {
-    case 'tauri': {
-      // NOTE Dynamic import is needed to avoid Tauri is a dependency of LiveStore (e.g. when used in the web)
-      const { TauriBackend } = await import('./tauri.js')
-      return await TauriBackend.load(options, otelProps)
-    }
-    case 'web': {
-      return WebWorkerBackend.load(options, otelProps)
-    }
-    // NOTE currently only needed for testing
-    case 'web-in-memory': {
-      return WebInMemoryBackend.load(options, otelProps)
-    }
-    default: {
-      casesHandled(options)
-    }
-  }
-}

package/src/backends/noop.ts

@@ -1,32 +0,0 @@
-import { makeNoopTracer } from '@livestore/utils'
-import type * as otel from '@opentelemetry/api'
-
-import type { ParamsObject } from '../util.js'
-import { BaseBackend } from './base.js'
-import type { SelectResponse } from './index.js'
-
-export type BackendOptionsNoop = {
-  type: 'noop'
-  /** Specifies where to persist data for this backend */
-  otelTracer?: otel.Tracer
-}
-
-export class NoopBackend extends BaseBackend {
-  constructor(readonly otelTracer: otel.Tracer) {
-    super()
-  }
-
-  static load = async (options: BackendOptionsNoop): Promise<NoopBackend> => {
-    return new NoopBackend(options.otelTracer ?? makeNoopTracer())
-  }
-
-  execute = (_query: string, _bindValues?: ParamsObject): void => {}
-
-  select = async <T>(_query: string, _bindValues?: ParamsObject): Promise<SelectResponse<T>> => {
-    return { results: [] }
-  }
-
-  getPersistedData = async (): Promise<Uint8Array> => {
-    return new Uint8Array()
-  }
-}

package/src/backends/web-in-memory.ts

@@ -1,65 +0,0 @@
-import type * as otel from '@opentelemetry/api'
-import type * as SqliteWasm from 'sqlite-esm'
-import sqlite3InitModule from 'sqlite-esm'
-
-import type { ParamsObject } from '../util.js'
-import { prepareBindValues } from '../util.js'
-import { BaseBackend } from './base.js'
-import type { BackendOtelProps, SelectResponse } from './index.js'
-
-export type BackendOptionsWebInMemory = {
-  type: 'web-in-memory'
-}
-
-declare type DatabaseWithCAPI = SqliteWasm.Database & { capi: SqliteWasm.CAPI }
-
-// NOTE: This backend is currently only used for testing
-export class WebInMemoryBackend extends BaseBackend {
-  constructor(
-    readonly otelTracer: otel.Tracer,
-    readonly db: DatabaseWithCAPI,
-  ) {
-    super()
-  }
-
-  static load = async (
-    _options: BackendOptionsWebInMemory,
-    { otelTracer }: BackendOtelProps,
-  ): Promise<WebInMemoryBackend> => {
-    const sqlite3 = await sqlite3InitModule({
-      print: (message) => console.log(`[sql-client] ${message}`),
-      printErr: (message) => console.error(`[sql-client] ${message}`),
-    })
-    const db = new sqlite3.oo1.DB({ filename: ':memory:', flags: 'c' }) as DatabaseWithCAPI
-    db.capi = sqlite3.capi
-
-    return new WebInMemoryBackend(otelTracer, db)
-  }
-
-  execute = (query: string, bindValues?: ParamsObject): void => {
-    this.db.exec({
-      sql: query,
-      bind: prepareBindValues(bindValues ?? {}, query) as TODO,
-      returnValue: 'resultRows',
-      rowMode: 'object',
-    })
-  }
-
-  select = async <T>(query: string, bindValues?: ParamsObject): Promise<SelectResponse<T>> => {
-    const resultRows: T[] = []
-
-    this.db.exec({
-      sql: query,
-      bind: prepareBindValues(bindValues ?? {}, query) as TODO,
-      rowMode: 'object',
-      resultRows,
-      // callback: (row: any) => console.log('select result', db.filename, query, row),
-    } as TODO)
-
-    return { results: resultRows }
-  }
-
-  getPersistedData = async (): Promise<Uint8Array> => {
-    return this.db.capi.sqlite3_js_db_export(this.db.pointer)
-  }
-}

package/src/backends/web.ts

@@ -1,97 +0,0 @@
-import type * as otel from '@opentelemetry/api'
-import * as Comlink from 'comlink'
-
-import type { ParamsObject } from '../util.js'
-import { prepareBindValues } from '../util.js'
-import { BaseBackend } from './base.js'
-import type { BackendOtelProps, SelectResponse, WritableDatabaseLocation } from './index.js'
-import type { WrappedWorker } from './web-worker.js'
-
-export type BackendOptionsWeb = {
-  type: 'web'
-  /** Specifies where to persist data for this backend */
-  persistentDatabaseLocation: WritableDatabaseLocation
-}
-
-export class WebWorkerBackend extends BaseBackend {
-  worker: Comlink.Remote<WrappedWorker>
-  persistentDatabaseLocation: WritableDatabaseLocation
-  otelTracer: otel.Tracer
-
-  executionBacklog: { query: string; bindValues?: ParamsObject }[] = []
-  executionPromise: Promise<void> | undefined = undefined
-
-  private constructor({
-    worker,
-    persistentDatabaseLocation,
-    otelTracer,
-  }: {
-    worker: Comlink.Remote<WrappedWorker>
-    persistentDatabaseLocation: WritableDatabaseLocation
-    otelTracer: otel.Tracer
-  }) {
-    super()
-    this.worker = worker
-    this.persistentDatabaseLocation = persistentDatabaseLocation
-    this.otelTracer = otelTracer
-  }
-
-  static load = async (
-    { persistentDatabaseLocation }: BackendOptionsWeb,
-    { otelTracer }: BackendOtelProps,
-  ): Promise<WebWorkerBackend> => {
-    // TODO: Importing the worker like this only works with Vite;
-    // should this really be inside the LiveStore library?
-    // Doesn't work with Firefox right now during dev https://bugzilla.mozilla.org/show_bug.cgi?id=1247687
-    const worker = new Worker(new URL('./web-worker.js', import.meta.url), {
-      type: 'module',
-    })
-    const wrappedWorker = Comlink.wrap<WrappedWorker>(worker)
-
-    await wrappedWorker.initialize({ persistentDatabaseLocation })
-
-    return new WebWorkerBackend({
-      worker: wrappedWorker,
-      persistentDatabaseLocation,
-      otelTracer,
-    })
-  }
-
-  execute = (query: string, bindValues_?: ParamsObject) => {
-    const bindValues = prepareBindValues(bindValues_ ?? {}, query)
-    this.executionBacklog.push({ query, bindValues })
-
-    // Instead of sending the queries to the worker immediately, we wait a bit and batch them up (which reduces the number of messages sent to the worker)
-    if (this.executionPromise === undefined) {
-      this.executionPromise = new Promise((resolve) => {
-        setTimeout(() => {
-          void this.worker.executeBulk(this.executionBacklog)
-          this.executionBacklog = []
-          this.executionPromise = undefined
-
-          resolve()
-        }, 10)
-      })
-    }
-  }
-
-  select = async <T>(query: string, bindValues?: ParamsObject): Promise<SelectResponse<T>> => {
-    // NOTE we need to wait for the executionBacklog to be worked off, before we run the select query (as it might depend on the previous execution queries)
-    await this.executionPromise
-
-    try {
-      const response = (await this.worker.select(query, bindValues)) as SelectResponse<T>
-      return response
-    } catch (e) {
-      console.error(`Error while executing query via "select": ${query}`)
-      throw e
-    }
-  }
-
-  getPersistedData = async (_parentSpan?: otel.Span): Promise<Uint8Array> => {
-    // NOTE we need to wait for the executionBacklog to be worked off
-    await this.executionPromise
-
-    return this.worker.getPersistedData()
-  }
-}

package/src/react/useGlobalQuery.ts

@@ -1,40 +0,0 @@
-import { useEffect, useState } from 'react'
-
-import { labelForKey } from '../componentKey.js'
-import { TODO_REMOVE_trackLongRunningSpan } from '../otel.js'
-import type { LiveStoreQuery, QueryResult } from '../store.js'
-
-export const useGlobalQuery = <Q extends LiveStoreQuery>(query: Q): QueryResult<Q> => {
-  // We know the query has a result by the time we use it; so we can synchronously populate a default state
-  const [value, setValue] = useState<QueryResult<Q>>(query.results$.result)
-
-  // Subscribe to future updates for this query
-  useEffect(() => {
-    return query.store.otel.tracer.startActiveSpan(
-      `LiveStore:useGlobalQuery:${labelForKey(query.componentKey)}:${query.label}`,
-      {},
-      query.store.otel.queriesSpanContext,
-      (span) => {
-        TODO_REMOVE_trackLongRunningSpan(span)
-
-        const cancel = query.store.subscribe(
-          query,
-          (v) => {
-            // NOTE: we return a reference to the result object within LiveStore;
-            // this implies that app code must not mutate the results, or else
-            // there may be weird reactivity bugs.
-            return setValue(v)
-          },
-          undefined,
-          { label: query.label },
-        )
-        return () => {
-          cancel()
-          span.end()
-        }
-      },
-    )
-  }, [query])
-
-  return value
-}

package/src/react/useGraphQL.ts

@@ -1,112 +0,0 @@
-import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
-import * as otel from '@opentelemetry/api'
-import { isEqual } from 'lodash-es'
-import React from 'react'
-
-import { labelForKey } from '../componentKey.js'
-import { useStore } from './LiveStoreContext.js'
-import { type ComponentKeyConfig, useComponentKey } from './useLiveStoreComponent.js'
-import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
-
-export type UseLiveStoreComponentProps<TResult extends Record<string, any>, TVariables extends Record<string, any>> = {
-  query: DocumentNode<TResult, TVariables>
-  variables: TVariables
-  componentKey: ComponentKeyConfig
-  reactDeps?: React.DependencyList
-}
-
-/**
- * This is needed because the `React.useMemo` call below, can sometimes be called multiple times 🤷,
- * so we need to "cache" the fact that we've already started a span for this component.
- * The map entry is being removed again in the `React.useEffect` call below.
- */
-const spanAlreadyStartedCache = new Map<string, { span: otel.Span; otelContext: otel.Context }>()
-
-// TODO 1) figure out a way to make `variables` optional if the query doesn't have any variables (probably requires positional args)
-// TODO 2) allow `.pipe` on the resulting query (possibly as a separate optional prop)
-export const useGraphQL = <TResult extends Record<string, any>, TVariables extends Record<string, any> = {}>({
-  query,
-  variables,
-  componentKey: componentKeyConfig,
-  reactDeps = [],
-}: UseLiveStoreComponentProps<TResult, TVariables>): Readonly<TResult> => {
-  const componentKey = useComponentKey(componentKeyConfig, reactDeps)
-  const { store } = useStore()
-
-  const componentKeyLabel = React.useMemo(() => labelForKey(componentKey), [componentKey])
-
-  // The following `React.useMemo` and `React.useEffect` calls are used to start and end a span for the lifetime of this component.
-  const { span, otelContext } = React.useMemo(() => {
-    const existingSpan = spanAlreadyStartedCache.get(componentKeyLabel)
-    if (existingSpan !== undefined) return existingSpan
-
-    const span = store.otel.tracer.startSpan(
-      `LiveStore:useGraphQL:${componentKeyLabel}`,
-      {},
-      store.otel.queriesSpanContext,
-    )
-
-    const otelContext = otel.trace.setSpan(otel.context.active(), span)
-
-    spanAlreadyStartedCache.set(componentKeyLabel, { span, otelContext })
-
-    return { span, otelContext }
-  }, [componentKeyLabel, store.otel.queriesSpanContext, store.otel.tracer])
-
-  React.useEffect(
-    () => () => {
-      spanAlreadyStartedCache.delete(componentKeyLabel)
-      span.end()
-    },
-    [componentKeyLabel, span],
-  )
-
-  const makeLiveStoreQuery = React.useCallback(
-    () => store.queryGraphQL(query, () => variables ?? ({} as TVariables), { componentKey, otelContext }),
-    // NOTE: we don't include the queries function passed in by the user here;
-    // the reason is that we don't want to force them to memoize that function.
-    // Instead, we just assume that the function always has the same contents.
-    // This makes sense for LiveStore because the component config should be static.
-    // TODO: document this and consider whether it's the right API surface.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [componentKey, store],
-  )
-
-  // TODO get rid of the temporary query workaround
-  const initialQueryResults = React.useMemo(
-    () => store.inTempQueryContext(() => makeLiveStoreQuery().results$.result),
-    [makeLiveStoreQuery, store],
-  )
-
-  const [queryResultsRef, setQueryResults_] = useStateRefWithReactiveInput<TResult>(initialQueryResults)
-
-  React.useEffect(() => {
-    const liveStoreQuery = makeLiveStoreQuery()
-    const unsubscribe = store.subscribe(
-      liveStoreQuery,
-      (results) => {
-        if (isEqual(results, queryResultsRef.current) === false) {
-          setQueryResults_(results)
-        }
-      },
-      undefined,
-      { label: `useGraphQL:query:subscribe:${liveStoreQuery.label}` },
-    )
-
-    return () => {
-      unsubscribe()
-    }
-    // NOTE `setQueryResults_` from the deps array as it seems to cause an infinite loop
-    // This should probably be improved
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    makeLiveStoreQuery,
-    // setQueryResults_,
-    store,
-  ])
-
-  // Very important: remove any queries / other resources associated w/ this component
-  React.useEffect(() => () => store.unmountComponent(componentKey), [store, componentKey])
-
-  return queryResultsRef.current
-}