@livestore/livestore 0.0.0

package/dist/util.js

@@ -0,0 +1,51 @@
+/**
+ * This is a tag function for tagged literals.
+ * it lets us get syntax highlighting on SQL queries in VSCode, but
+ * doesn't do anything at runtime.
+ * Code copied from: https://esdiscuss.org/topic/string-identity-template-tag
+ */
+export const sql = (template, ...args) => {
+    let str = '';
+    for (const [i, arg] of args.entries()) {
+        str += template[i] + String(arg);
+    }
+    return str + template.at(-1);
+};
+/** Prepare bind values to send to SQLite
+/*  Add $ to the beginning of keys; which we use as our interpolation syntax
+/*  We also strip out any params that aren't used in the statement,
+/*  because rusqlite doesn't allow unused named params
+/*  TODO: Search for unused params via proper parsing, not string search
+**/
+export const prepareBindValues = (values, statement) => {
+    const result = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (statement.includes(key)) {
+            result[`$${key}`] = value;
+        }
+    }
+    return result;
+};
+/**
+ * Use this to make assertion at end of if-else chain that all members of a
+ * union have been accounted for.
+ */
+/* eslint-disable-next-line prefer-arrow/prefer-arrow-functions */
+export function casesHandled(x) {
+    throw new Error(`A case was not handled for value: ${objectToString(x)}`);
+}
+export const objectToString = (error) => {
+    const stack = typeof process !== 'undefined' && process.env.CL_DEBUG ? error.stack : undefined;
+    const str = error.toString();
+    const stackStr = stack ? `\n${stack}` : '';
+    if (str !== '[object Object]')
+        return str + stackStr;
+    try {
+        return JSON.stringify({ ...error, stack }, null, 2);
+    }
+    catch (e) {
+        console.log(error);
+        return 'Error while printing error: ' + e;
+    }
+};
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,QAA8B,EAAE,GAAG,IAAe,EAAU,EAAE;IAChF,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE;QACrC,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;KACjC;IACD,OAAO,GAAG,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAoB,EAAE,SAAiB,EAAgB,EAAE;IACzF,MAAM,MAAM,GAAiB,EAAE,CAAA;IAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QACjD,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;YAC3B,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,KAAK,CAAA;SAC1B;KACF;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;GAGG;AACH,kEAAkE;AAClE,MAAM,UAAU,YAAY,CAAC,CAAQ;IACnC,MAAM,IAAI,KAAK,CAAC,qCAAqC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAC3E,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAU,EAAU,EAAE;IACnD,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IAC9F,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;IAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1C,IAAI,GAAG,KAAK,iBAAiB;QAAE,OAAO,GAAG,GAAG,QAAQ,CAAA;IAEpD,IAAI;QACF,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;KACpD;IAAC,OAAO,CAAM,EAAE;QACf,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAElB,OAAO,8BAA8B,GAAG,CAAC,CAAA;KAC1C;AACH,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@livestore/livestore",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react/index.js",
+    "./util": "./dist/util.js"
+  },
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./dist/react/index.d.ts"
+      ],
+      "util": [
+        "./dist/util.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "@livestore/utils": "0.0.0",
+    "@opentelemetry/api": "^1.4.1",
+    "comlink": "^4.4.1",
+    "graphql": "^16.8.0",
+    "lodash-es": "^4.17.21",
+    "sqlite-esm": "3.42.0-build6",
+    "uuid": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@tauri-apps/api": "=1.0.0-rc.1",
+    "react": "^17",
+    "react-dom": "^17"
+  },
+  "devDependencies": {
+    "@tauri-apps/api": "^1.4.0",
+    "@testing-library/react": "^14.0.0",
+    "@types/lodash-es": "^4.17.9",
+    "@types/uuid": "^9.0.3",
+    "jsdom": "^22.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "5.2.2",
+    "vite": "4.4.9",
+    "vitest": "^0.34.3"
+  }
+}

package/src/QueryCache.ts

@@ -0,0 +1,81 @@
+import BoundMap, { BoundSet } from './bounded-collections.js'
+import type { Bindable } from './util.js'
+
+type Opaque<BaseType, BrandType = unknown> = BaseType & {
+  readonly [Symbols.base]: BaseType
+  readonly [Symbols.brand]: BrandType
+}
+
+namespace Symbols {
+  export declare const base: unique symbol
+  export declare const brand: unique symbol
+}
+
+export type CacheKey = Opaque<string, string>
+type TableName = string
+
+const ignore = ['begin', 'rollback', 'commit', 'savepoint', 'release']
+
+// TODO: profile to see how big we need this cache to be.
+const cacheSize = 200
+export default class QueryCache {
+  #entries = new BoundMap<CacheKey, any>(cacheSize)
+  #dependencies = new Map<TableName, BoundSet<CacheKey>>()
+
+  getKey = (sql: string, bindValues?: Bindable): CacheKey => {
+    if (bindValues == null) {
+      return sql as CacheKey
+    }
+
+    if (Array.isArray(bindValues)) {
+      return (sql + '\n' + bindValues.join('\n')) as CacheKey
+    }
+
+    return (sql + '\n' + Object.values(bindValues).join('\n')) as CacheKey
+  }
+
+  get = (key: CacheKey) => {
+    return this.#entries.get(key)
+  }
+
+  set = (queriedTables: string[], key: CacheKey, results: any) => {
+    this.#entries.set(key, results)
+    for (const table of queriedTables) {
+      let keys = this.#dependencies.get(table)
+      if (keys == null) {
+        keys = new BoundSet(cacheSize)
+        keys.onEvict = this.#dependencyTrackerEvicted
+        this.#dependencies.set(table, keys)
+      }
+      keys.add(key)
+    }
+  }
+
+  #dependencyTrackerEvicted = (key: CacheKey) => {
+    this.#entries.delete(key)
+  }
+
+  ignoreQuery = (query: string) => {
+    return ignore.some((prefix) => query.startsWith(prefix))
+  }
+
+  // The next simplest step is to create a specific implementation for invalidating
+  // the expensive track list queries only when constraints data in a write overlaps with read constraints.
+  //
+  // As well as either:
+  // a. removeing the big view (since we'll have our cache)
+  // b. incrementally updating the view on insert by the EventImporter
+  //
+  // We'll not try to tackle any generalized approach until we have a proof of concept working.
+  invalidate = (queriedTables: string[]) => {
+    for (const table of queriedTables) {
+      const keys = this.#dependencies.get(table)
+      if (keys == null) {
+        continue
+      }
+      for (const k of keys) {
+        this.#entries.delete(k)
+      }
+    }
+  }
+}

package/src/__tests__/react/fixture.tsx

@@ -0,0 +1,106 @@
+import { mapObjectValues } from '@livestore/utils'
+import * as otel from '@opentelemetry/api'
+import React from 'react'
+
+import * as LiveStore from '../../index.js'
+import { sql } from '../../index.js'
+import * as LiveStoreReact from '../../react/index.js'
+
+const mockOtelCtx = otel.context.active()
+
+export type Todo = {
+  id: string
+  text: string | null
+  completed: boolean
+}
+
+export type Filter = 'all' | 'active' | 'completed'
+
+export type AppState = {
+  newTodoText: string
+  filter: Filter
+}
+
+const appState: LiveStore.QueryDefinition = (store) =>
+  store
+    .querySQL<AppState>(
+      () => `select newTodoText, filter from app;`,
+      ['app'],
+      undefined,
+      undefined,
+      undefined,
+      mockOtelCtx,
+    )
+    .getFirstRow()
+
+export const globalQueryDefs = {
+  appState,
+}
+
+export const schema = LiveStore.defineSchema({
+  tables: {
+    todos: {
+      columns: {
+        id: { type: 'text', primaryKey: true },
+        text: { type: 'text', default: '', nullable: false },
+        completed: { type: 'boolean', default: false, nullable: false },
+      },
+    },
+    app: {
+      columns: {
+        id: { type: 'text', primaryKey: true },
+        newTodoText: { type: 'text', default: '', nullable: true },
+        filter: { type: 'text', default: 'all', nullable: false },
+      },
+    },
+  },
+  materializedViews: {},
+  actions: {
+    // TODO: fix these actions to make them have write annotatinos
+    addTodo: {
+      statement: {
+        sql: sql`INSERT INTO todos (id, text, completed) VALUES ($id, $text, false);`,
+        writeTables: ['app'],
+      },
+    },
+    completeTodo: { statement: { sql: sql`UPDATE todos SET completed = true WHERE id = $id;`, writeTables: ['app'] } },
+    uncompleteTodo: {
+      statement: { sql: sql`UPDATE todos SET completed = false WHERE id = $id;`, writeTables: ['app'] },
+    },
+    deleteTodo: { statement: { sql: sql`DELETE FROM todos WHERE id = $id;`, writeTables: ['app'] } },
+    clearCompleted: { statement: { sql: sql`DELETE FROM todos WHERE completed = true;`, writeTables: ['app'] } },
+    updateNewTodoText: { statement: { sql: sql`UPDATE app SET newTodoText = $text;`, writeTables: ['app'] } },
+    setFilter: { statement: { sql: sql`UPDATE app SET filter = $filter;`, writeTables: ['app'] } },
+  },
+})
+
+export const makeTodoMvc = async () => {
+  type UserInfoComponentState = { username: string }
+
+  const AppSchema = LiveStore.defineComponentStateSchema<UserInfoComponentState>({
+    componentType: 'UserInfo',
+    columns: {
+      username: { type: 'text', default: '' },
+    },
+  })
+
+  const store = await LiveStore.createStore({
+    schema,
+    backendOptions: { type: 'web-in-memory' },
+    boot: async (backend) => {
+      backend.execute(sql`INSERT INTO app (newTodoText, filter) VALUES ('', 'all');`)
+      // NOTE we can't insert into components__UserInfo yet because the table doesn't exist yet
+      // backend.execute(sql`INSERT INTO components__UserInfo (id, username) VALUES ('u1', 'username_u1');`)
+      // backend.execute(sql`INSERT INTO components__UserInfo (id, username) VALUES ('u2', 'username_u2');`)
+    },
+  })
+
+  const globalQueries = mapObjectValues(globalQueryDefs, (_, queryDef) => queryDef(store))
+  const storeContext: LiveStore.LiveStoreContext = { store, globalQueries }
+
+  const wrapper = ({ children }: any) => (
+    <LiveStoreReact.LiveStoreContext.Provider value={storeContext}>{children}</LiveStoreReact.LiveStoreContext.Provider>
+  )
+
+  return { wrapper, AppSchema, store }
+}

package/src/__tests__/react/useLiveStoreComponent.test.tsx

@@ -0,0 +1,111 @@
+import { act, renderHook } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { sql } from '../../index.js'
+import * as LiveStoreReact from '../../react/index.js'
+import { makeTodoMvc } from './fixture.js'
+
+describe('useLiveStoreComponent', () => {
+  it('should update the data based on component key', async () => {
+    let renderCount = 0
+
+    const { wrapper, AppSchema, store } = await makeTodoMvc()
+
+    const { result, rerender } = renderHook(
+      (userId: string) => {
+        renderCount++
+
+        return LiveStoreReact.useLiveStoreComponent({
+          stateSchema: AppSchema,
+          componentKey: { name: 'UserInfo', id: userId },
+          queries: () => ({}),
+        })
+      },
+      { wrapper, initialProps: 'u1' },
+    )
+
+    expect(result.current.state.id).toBe('u1')
+    expect(result.current.state.username).toBe('')
+    expect(renderCount).toBe(1)
+
+    act(() => {
+      void store.execute(sql`INSERT INTO components__UserInfo (id, username) VALUES ('u2', 'username_u2');`)
+    })
+
+    rerender('u2')
+
+    expect(result.current.state.id).toBe('u2')
+    expect(result.current.state.username).toBe('username_u2')
+    expect(renderCount).toBe(2)
+  })
+
+  it('should update the data reactively - via setState', async () => {
+    let renderCount = 0
+
+    const { wrapper, AppSchema } = await makeTodoMvc()
+
+    const { result } = renderHook(
+      (userId: string) => {
+        renderCount++
+
+        return LiveStoreReact.useLiveStoreComponent({
+          stateSchema: AppSchema,
+          componentKey: { name: 'UserInfo', id: userId },
+          queries: () => ({}),
+        })
+      },
+      { wrapper, initialProps: 'u1' },
+    )
+
+    expect(result.current.state.id).toBe('u1')
+    expect(result.current.state.username).toBe('')
+    expect(renderCount).toBe(1)
+
+    act(() => {
+      result.current.setState.username('username_u1_hello')
+    })
+
+    // act(() => {
+    //   store.execute(sql`UPDATE components__UserInfo SET username = 'username_u1_hello' WHERE id = 'u1';`)
+    // })
+
+    expect(result.current.state.id).toBe('u1')
+    expect(result.current.state.username).toBe('username_u1_hello')
+    expect(renderCount).toBe(2)
+  })
+
+  it('should update the data reactively - via raw store update', async () => {
+    let renderCount = 0
+
+    const { wrapper, AppSchema, store } = await makeTodoMvc()
+
+    const { result } = renderHook(
+      (userId: string) => {
+        renderCount++
+
+        return LiveStoreReact.useLiveStoreComponent({
+          stateSchema: AppSchema,
+          componentKey: { name: 'UserInfo', id: userId },
+          queries: () => ({}),
+        })
+      },
+      { wrapper, initialProps: 'u1' },
+    )
+
+    expect(result.current.state.id).toBe('u1')
+    expect(result.current.state.username).toBe('')
+    expect(renderCount).toBe(1)
+
+    act(() => {
+      result.current.setState.username('username_u1_hello')
+    })
+
+    act(() => {
+      void store.execute(sql`UPDATE components__UserInfo SET username = 'username_u1_hello' WHERE id = 'u1';`)
+    })
+
+    expect(result.current.state.id).toBe('u1')
+    expect(result.current.state.username).toBe('username_u1_hello')
+    expect(renderCount).toBe(2)
+  })
+})

package/src/__tests__/reactive.test.ts

@@ -0,0 +1,227 @@
+import { makeNoopTracer } from '@livestore/utils'
+import * as otel from '@opentelemetry/api'
+import { describe, expect, it } from 'vitest'
+
+import { ReactiveGraph } from '../reactive.js'
+
+const mockOtelCtx = otel.context.active()
+
+describe('a trivial graph', () => {
+  const makeGraph = () => {
+    const graph = new ReactiveGraph({ otelTracer: makeNoopTracer() })
+    const a = graph.makeRef(1)
+    const b = graph.makeRef(2)
+    const numberOfRunsForC = { runs: 0 }
+    const c = graph.makeThunk(
+      (get) => {
+        numberOfRunsForC.runs++
+        return get(a) + get(b)
+      },
+      undefined,
+      mockOtelCtx,
+    )
+    const d = graph.makeRef(3)
+    const e = graph.makeThunk((get) => get(c) + get(d), undefined, mockOtelCtx)
+
+    // a(1)   b(2)
+    //   \     /
+    //    \   /
+    //      c = a + b
+    //       \
+    //        \
+    // d(3)    \
+    //   \       \
+    //    \       \
+    //      e = c + d
+
+    return { graph, a, b, c, d, e, numberOfRunsForC }
+  }
+
+  it('has the right initial values', () => {
+    const { c, e } = makeGraph()
+    expect(c.result).toBe(3)
+    expect(e.result).toBe(6)
+  })
+
+  it('propagates change through the graph', () => {
+    const { graph, a, c, e } = makeGraph()
+    graph.setRef(a, 5, undefined, mockOtelCtx)
+    expect(c.result).toBe(7)
+    expect(e.result).toBe(10)
+  })
+
+  it('cuts off reactive propagation when a thunk evaluates to same result as before', () => {
+    const { graph, a, c, d } = makeGraph()
+
+    let numberOfRuns = 0
+    const f = graph.makeThunk(
+      (get) => {
+        numberOfRuns++
+        return get(c) + get(d)
+      },
+      undefined,
+      mockOtelCtx,
+    )
+    expect(numberOfRuns).toBe(1) // initializing f should run it once
+
+    // f doesn't run because a is set to same value as before
+    graph.setRef(a, 1, undefined, mockOtelCtx)
+    expect(f.result).toBe(6)
+    expect(numberOfRuns).toBe(1)
+
+    // f runs because a is set to a different value
+    graph.setRef(a, 5, undefined, mockOtelCtx)
+    expect(f.result).toBe(10)
+    expect(numberOfRuns).toBe(2)
+
+    // f runs again when d is set to a different value
+    graph.setRef(d, 4, undefined, mockOtelCtx)
+    expect(f.result).toBe(11)
+    expect(numberOfRuns).toBe(3)
+
+    // f only runs one time if we set two refs together
+    graph.setRefs(
+      [
+        [a, 6],
+        [d, 5],
+      ],
+      undefined,
+      mockOtelCtx,
+    )
+    expect(f.result).toBe(13)
+    expect(numberOfRuns).toBe(4)
+  })
+
+  it('only runs a thunk once when two upstream refs are updated together', () => {
+    const { graph, a, b, c, numberOfRunsForC } = makeGraph()
+    expect(numberOfRunsForC.runs).toBe(1)
+    graph.setRefs(
+      [
+        [a, 5],
+        [b, 6],
+      ],
+      undefined,
+      mockOtelCtx,
+    )
+    expect(numberOfRunsForC.runs).toBe(2)
+    expect(c.result).toBe(11)
+  })
+
+  it('skips refresh when that option is passed when setting a single ref', () => {
+    const { graph, a, c, numberOfRunsForC } = makeGraph()
+    expect(numberOfRunsForC.runs).toBe(1)
+
+    graph.setRef(a, 5, { skipRefresh: true }, mockOtelCtx)
+
+    // C hasn't changed
+    expect(numberOfRunsForC.runs).toBe(1)
+    expect(c.result).toBe(3)
+
+    // Now we trigger a refresh and everything runs
+    graph.refresh(undefined, mockOtelCtx)
+    expect(numberOfRunsForC.runs).toBe(2)
+    expect(c.result).toBe(7)
+  })
+
+  it('skips refresh when that option is passed when setting multiple refs together', () => {
+    const { graph, a, b, c, numberOfRunsForC } = makeGraph()
+    expect(numberOfRunsForC.runs).toBe(1)
+
+    graph.setRefs(
+      [
+        [a, 5],
+        [b, 6],
+      ],
+      { skipRefresh: true },
+      mockOtelCtx,
+    )
+
+    // C hasn't changed
+    expect(numberOfRunsForC.runs).toBe(1)
+    expect(c.result).toBe(3)
+
+    // Now we trigger a refresh and everything runs
+    graph.refresh(undefined, mockOtelCtx)
+    expect(numberOfRunsForC.runs).toBe(2)
+    expect(c.result).toBe(11)
+  })
+
+  describe('effects', () => {
+    it('only reruns an effect if the thunk value changed', () => {
+      const { graph, a, c } = makeGraph()
+      let numberOfCallsToC = 0
+      graph.makeEffect(
+        (get) => {
+          // establish a dependency on thunk c and mutate an outside value
+          get(c)
+          numberOfCallsToC++
+        },
+        undefined,
+        mockOtelCtx,
+      )
+      expect(numberOfCallsToC).toBe(1)
+
+      // if we set a to the same value, the effect should not run again
+      graph.setRef(a, 1, undefined, mockOtelCtx)
+      expect(numberOfCallsToC).toBe(1)
+
+      graph.setRef(a, 2, undefined, mockOtelCtx)
+      expect(numberOfCallsToC).toBe(2)
+    })
+  })
+})
+
+describe('a diamond shaped graph', () => {
+  const makeGraph = () => {
+    const graph = new ReactiveGraph({ otelTracer: makeNoopTracer() })
+    const a = graph.makeRef(1)
+    const b = graph.makeThunk((get) => get(a) + 1, undefined, mockOtelCtx)
+    const c = graph.makeThunk((get) => get(a) + 1, undefined, mockOtelCtx)
+
+    // track the number of times d has run in an object so we can mutate it
+    const dRuns = { runs: 0 }
+
+    // normally thunks aren't supposed to side effect;
+    // we do it here to track the number of times d has run
+    const d = graph.makeThunk(
+      (get) => {
+        dRuns.runs++
+        return get(b) + get(c)
+      },
+      undefined,
+      mockOtelCtx,
+    )
+
+    // a(1)
+    //  / \
+    // b   c
+    //  \ /
+    //   d = b + c
+
+    return { graph, a, b, c, d, dRuns }
+  }
+
+  it('has the right initial values', () => {
+    const { b, c, d } = makeGraph()
+    expect(b.result).toBe(2)
+    expect(c.result).toBe(2)
+    expect(d.result).toBe(4)
+  })
+
+  it('propagates change through the graph', () => {
+    const { graph, a, b, c, d } = makeGraph()
+    graph.setRef(a, 5, undefined, mockOtelCtx)
+    expect(b.result).toBe(6)
+    expect(c.result).toBe(6)
+    expect(d.result).toBe(12)
+  })
+
+  // if we're being efficient, we should update b and c before updating d,
+  // so d only needs to update one time
+  it('only runs d once when a changes', () => {
+    const { graph, a, dRuns } = makeGraph()
+    expect(dRuns.runs).toBe(1)
+    graph.setRef(a, 5, undefined, mockOtelCtx)
+    expect(dRuns.runs).toBe(2)
+  })
+})

package/src/ambient.d.ts

@@ -0,0 +1,7 @@
+interface Window {
+  [key: `__debug${string}`]: any
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}