@livestore/common 0.3.0-dev.23 → 0.3.0-dev.25

package/src/mutation.ts

@@ -1,8 +1,11 @@
 import { Schema } from '@livestore/utils/effect'
 
 import { SessionIdSymbol } from './adapter-types.js'
+import type { QueryBuilder } from './query-builder/api.js'
+import { isQueryBuilder } from './query-builder/api.js'
 import type * as MutationEvent from './schema/MutationEvent.js'
-import type { MutationDef } from './schema/mutations.js'
+import type { MutationDef, MutationHandlerResult } from './schema/mutations.js'
+import type { BindValues } from './sql-queries/sql-queries.js'
 import type { PreparedBindValues } from './util.js'
 import { prepareBindValues } from './util.js'
 
@@ -34,8 +37,22 @@ export const getExecArgsFromMutation = ({
     case 'function': {
       const mutationArgsDecoded =
         mutationEvent.decoded?.args ?? Schema.decodeUnknownSync(mutationDef.schema)(mutationEvent.encoded!.args)
-      const res = mutationDef.sql(mutationArgsDecoded)
-      statementRes = Array.isArray(res) ? res : [res]
+
+      const res = mutationDef.sql(mutationArgsDecoded, {
+        clientOnly: mutationDef.options.clientOnly,
+        // TODO properly implement this
+        currentFacts: new Map(),
+      })
+
+      statementRes = (Array.isArray(res) ? res : [res]).map((_: QueryBuilder.Any | MutationHandlerResult) => {
+        if (isQueryBuilder(_)) {
+          const { query, bindValues } = _.asSql()
+          return { sql: query, bindValues: bindValues as BindValues }
+        }
+
+        return _
+      })
+
       break
     }
     case 'string': {

package/src/query-builder/api.ts

@@ -7,10 +7,16 @@ import type { SqliteDsl } from '../schema/db-schema/mod.js'
 import type { DbSchema } from '../schema/mod.js'
 import type { SqlValue } from '../util.js'
 
-export type QueryBuilderAst = QueryBuilderAst.SelectQuery | QueryBuilderAst.CountQuery | QueryBuilderAst.RowQuery
+export type QueryBuilderAst =
+  | QueryBuilderAst.SelectQuery
+  | QueryBuilderAst.CountQuery
+  | QueryBuilderAst.RowQuery
+  | QueryBuilderAst.InsertQuery
+  | QueryBuilderAst.UpdateQuery
+  | QueryBuilderAst.DeleteQuery
 
 export namespace QueryBuilderAst {
-  export type SelectQuery = {
+  export interface SelectQuery {
     readonly _tag: 'SelectQuery'
     readonly columns: string[]
     readonly pickFirst: false | { fallback: () => any }
@@ -25,27 +31,67 @@ export namespace QueryBuilderAst {
     readonly resultSchemaSingle: Schema.Schema<any>
   }
 
-  export type CountQuery = {
+  export interface CountQuery {
     readonly _tag: 'CountQuery'
     readonly tableDef: DbSchema.TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
     readonly resultSchema: Schema.Schema<number, ReadonlyArray<{ count: number }>>
   }
 
-  export type RowQuery = {
+  export interface RowQuery {
     readonly _tag: 'RowQuery'
     readonly tableDef: DbSchema.TableDefBase
     readonly id: string | SessionIdSymbol | number
     readonly insertValues: Record<string, unknown>
   }
 
-  export type Where = {
+  export interface InsertQuery {
+    readonly _tag: 'InsertQuery'
+    readonly tableDef: DbSchema.TableDefBase
+    readonly values: Record<string, unknown>
+    readonly onConflict: OnConflict | undefined
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export interface OnConflict {
+    /** Conflicting column name */
+    readonly target: string
+    readonly action:
+      | { readonly _tag: 'ignore' }
+      | { readonly _tag: 'replace' }
+      | {
+          readonly _tag: 'update'
+          readonly update: Record<string, unknown>
+        }
+  }
+
+  export interface UpdateQuery {
+    readonly _tag: 'UpdateQuery'
+    readonly tableDef: DbSchema.TableDefBase
+    readonly values: Record<string, unknown>
+    readonly where: ReadonlyArray<QueryBuilderAst.Where>
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export interface DeleteQuery {
+    readonly _tag: 'DeleteQuery'
+    readonly tableDef: DbSchema.TableDefBase
+    readonly where: ReadonlyArray<QueryBuilderAst.Where>
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export type WriteQuery = InsertQuery | UpdateQuery | DeleteQuery
+
+  export interface Where {
     readonly col: string
     readonly op: QueryBuilder.WhereOps
     readonly value: unknown
   }
 
-  export type OrderBy = {
+  export interface OrderBy {
     readonly col: string
     readonly direction: 'asc' | 'desc'
   }
@@ -86,7 +132,20 @@ export namespace QueryBuilder {
     export type MultiValue = In
   }
 
-  export type ApiFeature = 'select' | 'where' | 'count' | 'orderBy' | 'offset' | 'limit' | 'first' | 'row'
+  export type ApiFeature =
+    | 'select'
+    | 'where'
+    | 'count'
+    | 'orderBy'
+    | 'offset'
+    | 'limit'
+    | 'first'
+    | 'row'
+    | 'insert'
+    | 'update'
+    | 'delete'
+    | 'returning'
+    | 'onConflict'
 
   export type WhereParams<TTableDef extends DbSchema.TableDefBase> = Partial<{
     [K in keyof TTableDef['sqliteDef']['columns']]:
@@ -130,7 +189,7 @@ export namespace QueryBuilder {
               readonly [K in TColumn]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
             }>,
         TTableDef,
-        TWithout | 'row' | 'select',
+        TWithout | 'row' | 'select' | 'returning' | 'onConflict',
         TQueryInfo
       >
       <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
@@ -142,7 +201,7 @@ export namespace QueryBuilder {
           readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
         }>,
         TTableDef,
-        TWithout | 'row' | 'select' | 'count',
+        TWithout | 'row' | 'select' | 'count' | 'returning' | 'onConflict',
         TQueryInfo
       >
     }
@@ -187,7 +246,7 @@ export namespace QueryBuilder {
     readonly count: () => QueryBuilder<
       number,
       TTableDef,
-      TWithout | 'row' | 'count' | 'select' | 'orderBy' | 'first' | 'offset' | 'limit',
+      TWithout | 'row' | 'count' | 'select' | 'orderBy' | 'first' | 'offset' | 'limit' | 'returning' | 'onConflict',
       TQueryInfo
     >
 
@@ -201,10 +260,10 @@ export namespace QueryBuilder {
       <TColName extends keyof TTableDef['sqliteDef']['columns'] & string>(
         col: TColName,
         direction: 'asc' | 'desc',
-      ): QueryBuilder<TResult, TTableDef, TWithout, TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict', TQueryInfo>
       <TParams extends QueryBuilder.OrderByParams<TTableDef>>(
         params: TParams,
-      ): QueryBuilder<TResult, TTableDef, TWithout, TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict', TQueryInfo>
     }
 
     /**
@@ -215,7 +274,12 @@ export namespace QueryBuilder {
      */
     readonly offset: (
       offset: number,
-    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'offset' | 'orderBy', TQueryInfo>
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'offset' | 'orderBy' | 'returning' | 'onConflict',
+      TQueryInfo
+    >
 
     /**
      * Example:
@@ -225,7 +289,12 @@ export namespace QueryBuilder {
      */
     readonly limit: (
       limit: number,
-    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'limit' | 'offset' | 'first' | 'orderBy', TQueryInfo>
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'limit' | 'offset' | 'first' | 'orderBy' | 'returning' | 'onConflict',
+      TQueryInfo
+    >
 
     /**
      * Example:
@@ -238,7 +307,7 @@ export namespace QueryBuilder {
     }) => QueryBuilder<
       TFallback | GetSingle<TResult>,
       TTableDef,
-      TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where',
+      TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where' | 'returning' | 'onConflict',
       TQueryInfo
     >
 
@@ -258,6 +327,114 @@ export namespace QueryBuilder {
               id: string | SessionIdSymbol | number,
               opts: TOptions,
             ) => QueryBuilder<RowQuery.Result<TTableDef>, TTableDef, QueryBuilder.ApiFeature, QueryInfo.Row>
+
+    /**
+     * Insert a new row into the table
+     *
+     * Example:
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' })
+     * ```
+     */
+    readonly insert: (
+      values: TTableDef['insertSchema']['Type'],
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where',
+      QueryInfo.Write
+    >
+
+    /**
+     * Example: If the row already exists, it will be ignored.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')
+     * ```
+     *
+     * Example: If the row already exists, it will be replaced.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')
+     * ```
+     *
+     * Example: If the row already exists, it will be updated.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'update', { text: 'Buy soy milk' })
+     * ```
+     *
+     * NOTE This API doesn't yet support composite primary keys.
+     */
+    readonly onConflict: {
+      (
+        target: string,
+        action: 'ignore' | 'replace',
+      ): QueryBuilder<
+        TResult,
+        TTableDef,
+        TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where',
+        TQueryInfo
+      >
+      <TTarget extends keyof TTableDef['sqliteDef']['columns'] & string>(
+        target: TTarget,
+        action: 'update',
+        updateValues: Partial<TTableDef['schema']['Type']>,
+      ): QueryBuilder<
+        TResult,
+        TTableDef,
+        TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where',
+        TQueryInfo
+      >
+    }
+
+    /**
+     * Similar to the `.select` API but for write queries (insert, update, delete).
+     *
+     * Example:
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id')
+     * ```
+     */
+    readonly returning: <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
+      ...columns: TColumns[]
+    ) => QueryBuilder<
+      ReadonlyArray<{
+        readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
+      }>,
+      TTableDef
+    >
+
+    /**
+     * Update rows in the table that match the where clause
+     *
+     * Example:
+     * ```ts
+     * db.todos.update({ status: 'completed' }).where({ id: '123' })
+     * ```
+     */
+    readonly update: (
+      values: Partial<TTableDef['schema']['Type']>,
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'onConflict',
+      QueryInfo.Write
+    >
+
+    /**
+     * Delete rows from the table that match the where clause
+     *
+     * Example:
+     * ```ts
+     * db.todos.delete().where({ status: 'completed' })
+     * ```
+     *
+     * Note that it's generally recommended to do soft-deletes for synced apps.
+     */
+    readonly delete: () => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'onConflict',
+      QueryInfo.Write
+    >
   }
 }
 

package/src/query-builder/astToSql.ts

@@ -0,0 +1,203 @@
+import { shouldNeverHappen } from '@livestore/utils'
+import { Schema } from '@livestore/utils/effect'
+
+import { SessionIdSymbol } from '../adapter-types.js'
+import type { DbSchema } from '../schema/mod.js'
+import type { SqlValue } from '../util.js'
+import type { QueryBuilderAst } from './api.js'
+
+// Helper functions for SQL generation
+const formatWhereClause = (
+  whereConditions: ReadonlyArray<QueryBuilderAst.Where>,
+  tableDef: DbSchema.TableDefBase,
+  bindValues: SqlValue[],
+): string => {
+  if (whereConditions.length === 0) return ''
+
+  const whereClause = whereConditions
+    .map(({ col, op, value }) => {
+      // Handle NULL values
+      if (value === null) {
+        if (op !== '=' && op !== '!=') {
+          throw new Error(`Unsupported operator for NULL value: ${op}`)
+        }
+        const opStmt = op === '=' ? 'IS' : 'IS NOT'
+        return `${col} ${opStmt} NULL`
+      }
+
+      // Get column definition and encode value
+      const colDef = tableDef.sqliteDef.columns[col]
+      if (colDef === undefined) {
+        throw new Error(`Column ${col} not found`)
+      }
+
+      // Handle array values for IN/NOT IN operators
+      const isArray = op === 'IN' || op === 'NOT IN'
+
+      if (isArray) {
+        // Verify value is an array
+        if (!Array.isArray(value)) {
+          return shouldNeverHappen(`Expected array value for ${op} operator but got`, value)
+        }
+
+        // Handle empty arrays
+        if (value.length === 0) {
+          return op === 'IN' ? '0=1' : '1=1'
+        }
+
+        const encodedValues = value.map((v) => Schema.encodeSync(colDef.schema)(v)) as SqlValue[]
+        bindValues.push(...encodedValues)
+        const placeholders = encodedValues.map(() => '?').join(', ')
+        return `${col} ${op} (${placeholders})`
+      } else {
+        const encodedValue = Schema.encodeSync(colDef.schema)(value)
+        bindValues.push(encodedValue as SqlValue)
+        return `${col} ${op} ?`
+      }
+    })
+    .join(' AND ')
+
+  return `WHERE ${whereClause}`
+}
+
+const formatReturningClause = (returning?: string[]): string => {
+  if (!returning || returning.length === 0) return ''
+  return ` RETURNING ${returning.join(', ')}`
+}
+
+export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: SqlValue[] } => {
+  const bindValues: SqlValue[] = []
+
+  // INSERT query
+  if (ast._tag === 'InsertQuery') {
+    const columns = Object.keys(ast.values)
+    const placeholders = columns.map(() => '?').join(', ')
+    const values = Object.values(Schema.encodeSync(ast.tableDef.insertSchema)(ast.values)) as SqlValue[]
+
+    bindValues.push(...values)
+
+    let query = `INSERT INTO '${ast.tableDef.sqliteDef.name}' (${columns.join(', ')}) VALUES (${placeholders})`
+
+    // Handle ON CONFLICT clause
+    if (ast.onConflict) {
+      query += ` ON CONFLICT (${ast.onConflict.target}) `
+      if (ast.onConflict.action._tag === 'ignore') {
+        query += 'DO NOTHING'
+      } else if (ast.onConflict.action._tag === 'replace') {
+        query += 'DO REPLACE'
+      } else {
+        // Handle the update record case
+        const updateValues = ast.onConflict.action.update
+        const updateCols = Object.keys(updateValues)
+        if (updateCols.length === 0) {
+          throw new Error('No update columns provided for ON CONFLICT DO UPDATE')
+        }
+
+        const updates = updateCols
+          .map((col) => {
+            const value = updateValues[col]
+            // If the value is undefined, use excluded.col
+            return value === undefined ? `${col} = excluded.${col}` : `${col} = ?`
+          })
+          .join(', ')
+
+        // Add values for the parameters
+        updateCols.forEach((col) => {
+          const value = updateValues[col]
+          if (value !== undefined) {
+            const colDef = ast.tableDef.sqliteDef.columns[col]
+            if (colDef === undefined) {
+              throw new Error(`Column ${col} not found`)
+            }
+            const encodedValue = Schema.encodeSync(colDef.schema)(value)
+            bindValues.push(encodedValue as SqlValue)
+          }
+        })
+
+        query += `DO UPDATE SET ${updates}`
+      }
+    }
+
+    query += formatReturningClause(ast.returning)
+    return { query, bindValues }
+  }
+
+  // UPDATE query
+  if (ast._tag === 'UpdateQuery') {
+    const setColumns = Object.keys(ast.values)
+    const setValues = Object.values(Schema.encodeSync(Schema.partial(ast.tableDef.schema))(ast.values))
+    bindValues.push(...setValues)
+
+    let query = `UPDATE '${ast.tableDef.sqliteDef.name}' SET ${setColumns.map((col) => `${col} = ?`).join(', ')}`
+
+    const whereClause = formatWhereClause(ast.where, ast.tableDef, bindValues)
+    if (whereClause) query += ` ${whereClause}`
+
+    query += formatReturningClause(ast.returning)
+    return { query, bindValues }
+  }
+
+  // DELETE query
+  if (ast._tag === 'DeleteQuery') {
+    let query = `DELETE FROM '${ast.tableDef.sqliteDef.name}'`
+
+    const whereClause = formatWhereClause(ast.where, ast.tableDef, bindValues)
+    if (whereClause) query += ` ${whereClause}`
+
+    query += formatReturningClause(ast.returning)
+    return { query, bindValues }
+  }
+
+  // COUNT query
+  if (ast._tag === 'CountQuery') {
+    const query = [
+      `SELECT COUNT(*) as count FROM '${ast.tableDef.sqliteDef.name}'`,
+      formatWhereClause(ast.where, ast.tableDef, bindValues),
+    ]
+      .filter((clause) => clause.length > 0)
+      .join(' ')
+
+    return { query, bindValues }
+  }
+
+  // ROW query
+  if (ast._tag === 'RowQuery') {
+    // Handle the id value by encoding it with the id column schema
+    const idColDef = ast.tableDef.sqliteDef.columns.id
+    if (idColDef === undefined) {
+      throw new Error('Column id not found for ROW query')
+    }
+
+    // NOTE we're not encoding the id if it's the session id symbol, which needs to be taken care of by the caller
+    const encodedId = ast.id === SessionIdSymbol ? ast.id : Schema.encodeSync(idColDef.schema)(ast.id)
+
+    return {
+      query: `SELECT * FROM '${ast.tableDef.sqliteDef.name}' WHERE id = ?`,
+      bindValues: [encodedId as SqlValue],
+    }
+  }
+
+  // SELECT query
+  const columnsStmt = ast.select.columns.length === 0 ? '*' : ast.select.columns.join(', ')
+  const selectStmt = `SELECT ${columnsStmt}`
+  const fromStmt = `FROM '${ast.tableDef.sqliteDef.name}'`
+  const whereStmt = formatWhereClause(ast.where, ast.tableDef, bindValues)
+
+  const orderByStmt =
+    ast.orderBy.length > 0
+      ? `ORDER BY ${ast.orderBy.map(({ col, direction }) => `${col} ${direction}`).join(', ')}`
+      : ''
+
+  const limitStmt = ast.limit._tag === 'Some' ? `LIMIT ?` : ''
+  if (ast.limit._tag === 'Some') bindValues.push(ast.limit.value)
+
+  const offsetStmt = ast.offset._tag === 'Some' ? `OFFSET ?` : ''
+  if (ast.offset._tag === 'Some') bindValues.push(ast.offset.value)
+
+  const query = [selectStmt, fromStmt, whereStmt, orderByStmt, offsetStmt, limitStmt]
+    .map((clause) => clause.trim())
+    .filter((clause) => clause.length > 0)
+    .join(' ')
+
+  return { query, bindValues }
+}

package/src/query-builder/impl.test.ts

@@ -226,6 +226,110 @@ describe('query builder', () => {
       `)
     })
   })
+
+  describe('write operations', () => {
+    it('should handle INSERT queries', () => {
+      expect(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).asSql()).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "123",
+            "Buy milk",
+            "active",
+          ],
+          "query": "INSERT INTO 'todos' (id, text, status) VALUES (?, ?, ?)",
+        }
+      `)
+    })
+
+    it('should handle UPDATE queries', () => {
+      expect(db.todos.update({ status: 'completed' }).where({ id: '123' }).asSql()).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+            "123",
+          ],
+          "query": "UPDATE 'todos' SET status = ? WHERE id = ?",
+        }
+      `)
+    })
+
+    it('should handle DELETE queries', () => {
+      expect(db.todos.delete().where({ status: 'completed' }).asSql()).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+          ],
+          "query": "DELETE FROM 'todos' WHERE status = ?",
+        }
+      `)
+    })
+
+    it('should handle INSERT with ON CONFLICT', () => {
+      expect(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore').asSql())
+        .toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "123",
+            "Buy milk",
+            "active",
+          ],
+          "query": "INSERT INTO 'todos' (id, text, status) VALUES (?, ?, ?) ON CONFLICT (id) DO NOTHING",
+        }
+      `)
+
+      expect(
+        db.todos
+          .insert({ id: '123', text: 'Buy milk', status: 'active' })
+          .onConflict('id', 'update', { text: 'Buy soy milk', status: 'active' })
+          .asSql(),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "123",
+            "Buy milk",
+            "active",
+            "Buy soy milk",
+            "active",
+          ],
+          "query": "INSERT INTO 'todos' (id, text, status) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET text = ?, status = ?",
+        }
+      `)
+    })
+
+    it('should handle RETURNING clause', () => {
+      expect(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id').asSql())
+        .toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "123",
+            "Buy milk",
+            "active",
+          ],
+          "query": "INSERT INTO 'todos' (id, text, status) VALUES (?, ?, ?) RETURNING id",
+        }
+      `)
+
+      expect(db.todos.update({ status: 'completed' }).where({ id: '123' }).returning('id').asSql())
+        .toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+            "123",
+          ],
+          "query": "UPDATE 'todos' SET status = ? WHERE id = ? RETURNING id",
+        }
+      `)
+
+      expect(db.todos.delete().where({ status: 'completed' }).returning('id').asSql()).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "completed",
+          ],
+          "query": "DELETE FROM 'todos' WHERE status = ? RETURNING id",
+        }
+      `)
+    })
+  })
 })
 
 // TODO nested queries