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

package/src/query-builder/impl.ts

@@ -1,9 +1,11 @@
-import { Option, Predicate, Schema } from '@livestore/utils/effect'
+import { casesHandled } from '@livestore/utils'
+import { Match, Option, Predicate, Schema } from '@livestore/utils/effect'
 
 import type { QueryInfo } from '../query-info.js'
 import type { DbSchema } from '../schema/mod.js'
 import type { QueryBuilder, QueryBuilderAst } from './api.js'
 import { QueryBuilderAstSymbol, TypeId } from './api.js'
+import { astToSql } from './astToSql.js'
 
 export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBase>(
   tableDef: TTableDef,
@@ -12,7 +14,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
   const api = {
     // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
     select() {
-      assertQueryBuilderAst(ast)
+      assertSelectQueryBuilderAst(ast)
 
       // eslint-disable-next-line prefer-rest-params
       const params = [...arguments]
@@ -36,8 +38,9 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
       }) as any
     },
     // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
-    where() {
-      if (isRowQuery(ast)) return invalidQueryBuilder()
+    where: function () {
+      if (ast._tag === 'InsertQuery') return invalidQueryBuilder('Cannot use where with insert')
+      if (ast._tag === 'RowQuery') return invalidQueryBuilder('Cannot use where with row')
 
       if (arguments.length === 1) {
         // eslint-disable-next-line prefer-rest-params
@@ -50,24 +53,45 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
               : { col, op: '=', value },
           )
 
-        return makeQueryBuilder(tableDef, {
-          ...ast,
-          where: [...ast.where, ...newOps],
-        }) as any
+        switch (ast._tag) {
+          case 'CountQuery':
+          case 'SelectQuery':
+          case 'UpdateQuery':
+          case 'DeleteQuery': {
+            return makeQueryBuilder(tableDef, {
+              ...ast,
+              where: [...ast.where, ...newOps],
+            }) as any
+          }
+          default: {
+            return casesHandled(ast)
+          }
+        }
       }
 
       // eslint-disable-next-line prefer-rest-params
       const [col, opOrValue, valueOrUndefined] = arguments
       const op = valueOrUndefined === undefined ? '=' : opOrValue
       const value = valueOrUndefined === undefined ? opOrValue : valueOrUndefined
-      return makeQueryBuilder(tableDef, {
-        ...ast,
-        where: [...ast.where, { col, op, value }],
-      })
+
+      switch (ast._tag) {
+        case 'CountQuery':
+        case 'SelectQuery':
+        case 'UpdateQuery':
+        case 'DeleteQuery': {
+          return makeQueryBuilder(tableDef, {
+            ...ast,
+            where: [...ast.where, { col, op, value }],
+          }) as any
+        }
+        default: {
+          return casesHandled(ast)
+        }
+      }
     },
     // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
     orderBy() {
-      assertQueryBuilderAst(ast)
+      assertSelectQueryBuilderAst(ast)
 
       if (arguments.length === 0 || arguments.length > 2) return invalidQueryBuilder()
 
@@ -89,12 +113,12 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
       }) as any
     },
     limit: (limit) => {
-      assertQueryBuilderAst(ast)
+      assertSelectQueryBuilderAst(ast)
 
       return makeQueryBuilder(tableDef, { ...ast, limit: Option.some(limit) })
     },
     offset: (offset) => {
-      assertQueryBuilderAst(ast)
+      assertSelectQueryBuilderAst(ast)
 
       return makeQueryBuilder(tableDef, { ...ast, offset: Option.some(offset) })
     },
@@ -102,17 +126,18 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
       if (isRowQuery(ast)) return invalidQueryBuilder()
 
       return makeQueryBuilder(tableDef, {
-        ...ast,
+        _tag: 'CountQuery',
+        tableDef,
+        where: [],
         resultSchema: Schema.Struct({ count: Schema.Number }).pipe(
           Schema.pluck('count'),
           Schema.Array,
           Schema.headOrElse(),
         ),
-        _tag: 'CountQuery',
       })
     },
     first: (options) => {
-      assertQueryBuilderAst(ast)
+      assertSelectQueryBuilderAst(ast)
 
       if (ast.limit._tag === 'Some') return invalidQueryBuilder(`.first() can't be called after .limit()`)
 
@@ -149,6 +174,65 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
         insertValues,
       }) as any
     },
+    insert: (values) => {
+      return makeQueryBuilder(tableDef, {
+        _tag: 'InsertQuery',
+        tableDef,
+        values: values as any,
+        onConflict: undefined,
+        returning: undefined,
+        resultSchema: Schema.Void,
+      }) as any
+    },
+    onConflict: (target: string, action: 'ignore' | 'replace' | 'update', updateValues?: Record<string, unknown>) => {
+      assertInsertQueryBuilderAst(ast)
+
+      const onConflict = Match.value(action).pipe(
+        Match.when('ignore', () => ({ target, action: { _tag: 'ignore' } }) satisfies QueryBuilderAst.OnConflict),
+        Match.when('replace', () => ({ target, action: { _tag: 'replace' } }) satisfies QueryBuilderAst.OnConflict),
+        Match.when(
+          'update',
+          () => ({ target, action: { _tag: 'update', update: updateValues! } }) satisfies QueryBuilderAst.OnConflict,
+        ),
+        Match.exhaustive,
+      )
+
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        onConflict,
+      }) as any
+    },
+
+    returning: (...columns) => {
+      assertWriteQueryBuilderAst(ast)
+
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        returning: columns,
+        resultSchema: tableDef.schema.pipe(Schema.pick(...columns), Schema.Array),
+      }) as any
+    },
+
+    update: (values) => {
+      return makeQueryBuilder(tableDef, {
+        _tag: 'UpdateQuery',
+        tableDef,
+        values: values as any,
+        where: [],
+        returning: undefined,
+        resultSchema: Schema.Void,
+      }) as any
+    },
+
+    delete: () => {
+      return makeQueryBuilder(tableDef, {
+        _tag: 'DeleteQuery',
+        tableDef,
+        where: [],
+        returning: undefined,
+        resultSchema: Schema.Void,
+      }) as any
+    },
   } satisfies QueryBuilder.ApiFull<TResult, TTableDef, never, QueryInfo.None>
 
   return {
@@ -167,94 +251,38 @@ export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBas
   } satisfies QueryBuilder<TResult, TTableDef>
 }
 
-const emptyAst = (tableDef: DbSchema.TableDefBase) =>
-  ({
-    _tag: 'SelectQuery',
-    columns: [],
-    pickFirst: false,
-    select: { columns: [] },
-    orderBy: [],
-    offset: Option.none(),
-    limit: Option.none(),
-    tableDef,
-    where: [],
-    resultSchemaSingle: tableDef.schema,
-  }) satisfies QueryBuilderAst
-
-const astToSql = (ast: QueryBuilderAst) => {
-  if (isRowQuery(ast)) {
-    // TODO
-    return { query: `SELECT * FROM '${ast.tableDef.sqliteDef.name}' WHERE id = ?`, bindValues: [ast.id as TODO] }
+const emptyAst = (tableDef: DbSchema.TableDefBase): QueryBuilderAst.SelectQuery => ({
+  _tag: 'SelectQuery',
+  columns: [],
+  pickFirst: false,
+  select: { columns: [] },
+  orderBy: [],
+  offset: Option.none(),
+  limit: Option.none(),
+  tableDef,
+  where: [],
+  resultSchemaSingle: tableDef.schema,
+})
+
+// Helper functions
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+function assertSelectQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.SelectQuery {
+  if (ast._tag !== 'SelectQuery') {
+    throw new Error('Expected SelectQuery but got ' + ast._tag)
   }
+}
 
-  const bindValues: unknown[] = []
-
-  // TODO bind values
-  const whereStmt =
-    ast.where.length > 0
-      ? `WHERE ${ast.where
-          .map(({ col, op, value }) => {
-            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`
-            } else {
-              const colDef = ast.tableDef.sqliteDef.columns[col]
-              if (colDef === undefined) {
-                throw new Error(`Column ${col} not found`)
-              }
-              const isArray = op === 'IN' || op === 'NOT IN'
-              const colSchema = isArray ? Schema.Array(colDef.schema) : colDef.schema
-              const encodedValue = Schema.encodeSync(colSchema)(value)
-
-              if (isArray) {
-                bindValues.push(...encodedValue)
-                const placeholders = Array.from({ length: encodedValue.length }, () => '?').join(', ')
-                return `${col} ${op} (${placeholders})`
-              } else {
-                bindValues.push(encodedValue)
-                return `${col} ${op} ?`
-              }
-            }
-          })
-          .join(' AND ')}`
-      : ''
-
-  if (ast._tag === 'CountQuery') {
-    const selectFromStmt = `SELECT COUNT(*) as count FROM '${ast.tableDef.sqliteDef.name}'`
-    const query = [selectFromStmt, whereStmt].filter((_) => _.length > 0).join(' ')
-    return { query, bindValues }
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+function assertInsertQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.InsertQuery {
+  if (ast._tag !== 'InsertQuery') {
+    throw new Error('Expected InsertQuery but got ' + ast._tag)
   }
-  const columnsStmt = ast.select.columns.length === 0 ? '*' : ast.select.columns.join(', ')
-  const selectStmt = `SELECT ${columnsStmt}`
-  const fromStmt = `FROM '${ast.tableDef.sqliteDef.name}'`
-
-  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((_) => _.trim())
-    .filter((_) => _.length > 0)
-    .join(' ')
-
-  // TODO bind values
-  return { query, bindValues }
 }
 
 // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
-function assertQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.SelectQuery {
-  if (ast._tag !== 'SelectQuery') {
-    throw new Error('Expected SelectQuery but got ' + ast._tag)
+function assertWriteQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.WriteQuery {
+  if (ast._tag !== 'InsertQuery' && ast._tag !== 'UpdateQuery' && ast._tag !== 'DeleteQuery') {
+    throw new Error('Expected WriteQuery but got ' + ast._tag)
   }
 }
 
@@ -264,22 +292,38 @@ export const invalidQueryBuilder = (msg?: string) => {
   throw new Error('Invalid query builder' + (msg ? `: ${msg}` : ''))
 }
 
-export const getResultSchema = (qb: QueryBuilder<any, any, any>) => {
+export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<any> => {
   const queryAst = qb[QueryBuilderAstSymbol]
-  if (queryAst._tag === 'SelectQuery') {
-    const arraySchema = Schema.Array(queryAst.resultSchemaSingle)
-    if (queryAst.pickFirst !== false) {
-      return arraySchema.pipe(Schema.headOrElse(queryAst.pickFirst.fallback))
+  switch (queryAst._tag) {
+    case 'SelectQuery': {
+      const arraySchema = Schema.Array(queryAst.resultSchemaSingle)
+      if (queryAst.pickFirst !== false) {
+        return arraySchema.pipe(Schema.headOrElse(queryAst.pickFirst.fallback))
+      }
+
+      return arraySchema
     }
+    case 'CountQuery': {
+      return Schema.Struct({ count: Schema.Number }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
+    }
+    case 'InsertQuery':
+    case 'UpdateQuery':
+    case 'DeleteQuery': {
+      // For write operations with RETURNING clause, we need to return the appropriate schema
+      if (queryAst.returning && queryAst.returning.length > 0) {
+        // Create a schema for the returned columns
+        return queryAst.tableDef.schema.pipe(Schema.pick(...queryAst.returning), Schema.Array)
+      }
 
-    return arraySchema
-  } else if (queryAst._tag === 'CountQuery') {
-    return Schema.Struct({ count: Schema.Number }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
-  } else {
-    if (queryAst.tableDef.options.isSingleColumn) {
-      return queryAst.tableDef.schema.pipe(Schema.pluck('value'), Schema.Array, Schema.headOrElse())
-    } else {
-      return queryAst.tableDef.schema.pipe(Schema.Array, Schema.headOrElse())
+      // For write operations without RETURNING, the result is the number of affected rows
+      return Schema.Number
+    }
+    default: {
+      if (queryAst.tableDef.options.isSingleColumn) {
+        return queryAst.tableDef.schema.pipe(Schema.pluck('value'), Schema.Array, Schema.headOrElse())
+      } else {
+        return queryAst.tableDef.schema.pipe(Schema.Array, Schema.headOrElse())
+      }
     }
   }
 }

package/src/query-builder/mod.ts

@@ -7,4 +7,11 @@ export * from './impl.js'
  * - Close abstraction to SQLite to provide a simple & convenient API with predictable behaviour
  * - Use table schema definitions to parse, map & validate query results
  * - Implementation detail: Separate type-level & AST-based runtime implementation
+ *
+ * Currently not supported (not exhaustive list):
+ * - Assumes a `id` column as primary key
+ * - Composite primary keys
+ *
+ * Other known limitations
+ * - Doesn't exclude all invalid query patterns on type level `e.g. `db.todos.returning('id')`
  */

package/src/query-info.ts

@@ -9,7 +9,7 @@ import type { DbSchema } from './schema/mod.js'
  *
  * This information is currently only used for derived mutations.
  */
-export type QueryInfo = QueryInfo.None | QueryInfo.Row | QueryInfo.Col | QueryInfo.ColJsonValue
+export type QueryInfo = QueryInfo.None | QueryInfo.Row | QueryInfo.Col | QueryInfo.ColJsonValue | QueryInfo.Write
 // export type QueryInfo<TTableDef extends DbSchema.TableDefBase = DbSchema.TableDefBase> =
 // | QueryInfo.None
 // | QueryInfo.Row<TTableDef>
@@ -45,6 +45,11 @@ export namespace QueryInfo {
     jsonPath: string
   }
 
+  // NOTE Not yet used but we might want to use this in order to avoid write queries in read-only situations
+  export type Write = {
+    _tag: 'Write'
+  }
+
   // NOTE maybe we want to bring back type-params back like below
   // export type Row<TTableDef extends DbSchema.TableDefBase> = {
   //   _tag: 'Row'

package/src/rehydrate-from-mutationlog.ts

@@ -65,7 +65,7 @@ This likely means the schema has changed in an incompatible way.
           mutation: row.mutation,
           args,
           clientId: row.clientId,
-          sessionId: row.sessionId ?? undefined,
+          sessionId: row.sessionId,
         } satisfies MutationEvent.AnyEncoded
 
         yield* applyMutation(mutationEventEncoded, { skipMutationLog: true })

package/src/schema/MutationEvent.ts

@@ -21,7 +21,7 @@ export type MutationEvent<TMutationsDef extends MutationDef.Any> = {
   id: EventId.EventId
   parentId: EventId.EventId
   clientId: string
-  sessionId: string | undefined
+  sessionId: string
 }
 
 export type MutationEventEncoded<TMutationsDef extends MutationDef.Any> = {
@@ -30,7 +30,7 @@ export type MutationEventEncoded<TMutationsDef extends MutationDef.Any> = {
   id: EventId.EventId
   parentId: EventId.EventId
   clientId: string
-  sessionId: string | undefined
+  sessionId: string
 }
 
 export type AnyDecoded = MutationEvent<MutationDef.Any>
@@ -40,7 +40,7 @@ export const AnyDecoded = Schema.Struct({
   id: EventId.EventId,
   parentId: EventId.EventId,
   clientId: Schema.String,
-  sessionId: Schema.UndefinedOr(Schema.String),
+  sessionId: Schema.String,
 }).annotations({ title: 'MutationEvent.AnyDecoded' })
 
 export type AnyEncoded = MutationEventEncoded<MutationDef.Any>
@@ -50,7 +50,7 @@ export const AnyEncoded = Schema.Struct({
   id: EventId.EventId,
   parentId: EventId.EventId,
   clientId: Schema.String,
-  sessionId: Schema.UndefinedOr(Schema.String),
+  sessionId: Schema.String,
 }).annotations({ title: 'MutationEvent.AnyEncoded' })
 
 export const AnyEncodedGlobal = Schema.Struct({
@@ -59,6 +59,7 @@ export const AnyEncodedGlobal = Schema.Struct({
   id: EventId.GlobalEventId,
   parentId: EventId.GlobalEventId,
   clientId: Schema.String,
+  sessionId: Schema.String,
 }).annotations({ title: 'MutationEvent.AnyEncodedGlobal' })
 export type AnyEncodedGlobal = typeof AnyEncodedGlobal.Type
 
@@ -90,7 +91,7 @@ export type ForMutationDefRecord<TMutationsDefRecord extends MutationDefRecord>
       id: EventId.EventId
       parentId: EventId.EventId
       clientId: string
-      sessionId: string | undefined
+      sessionId: string
     }
   }[keyof TMutationsDefRecord],
   {
@@ -100,7 +101,7 @@ export type ForMutationDefRecord<TMutationsDefRecord extends MutationDefRecord>
       id: EventId.EventId
       parentId: EventId.EventId
       clientId: string
-      sessionId: string | undefined
+      sessionId: string
     }
   }[keyof TMutationsDefRecord]
 >
@@ -131,7 +132,7 @@ export const makeMutationEventSchema = <TSchema extends LiveStoreSchema>(
         id: EventId.EventId,
         parentId: EventId.EventId,
         clientId: Schema.String,
-        sessionId: Schema.UndefinedOr(Schema.String),
+        sessionId: Schema.String,
       }),
     ),
   ).annotations({ title: 'MutationEvent' }) as any
@@ -157,7 +158,7 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('MutationEven
   id: EventId.EventId,
   parentId: EventId.EventId,
   clientId: Schema.String,
-  sessionId: Schema.UndefinedOr(Schema.String),
+  sessionId: Schema.String,
   // TODO get rid of `meta` again by cleaning up the usage implementations
   meta: Schema.optionalWith(
     Schema.Any as Schema.Schema<{
@@ -177,10 +178,26 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('MutationEven
     }
   }
 
-  rebase = (parentId: EventId.EventId, isLocal: boolean) =>
+  /**
+   * Example: (global event)
+   * For event id (2,0) → (1,0) which should be rebased on event id (3,1) → (3,0)
+   * the resulting event id will be (4,0) → (3,0)
+   *
+   * Example: (client event)
+   * For event id (2,1) → (2,0) which should be rebased on event id (3,0) → (2,0)
+   * the resulting event id will be (3,1) → (3,0)
+   *
+   * Syntax: (2,1) → (2,0)
+   *          ^ ^     ^ ^
+   *          | |     | +- client parent id
+   *          | |     +--- global parent id
+   *          | +-- client id
+   *          +---- global id
+   */
+  rebase = (parentId: EventId.EventId, isClient: boolean) =>
     new EncodedWithMeta({
       ...this,
-      ...EventId.nextPair(parentId, isLocal),
+      ...EventId.nextPair(parentId, isClient),
     })
 
   static fromGlobal = (mutationEvent: AnyEncodedGlobal) =>
@@ -188,7 +205,6 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('MutationEven
       ...mutationEvent,
       id: { global: mutationEvent.id, client: EventId.clientDefault },
       parentId: { global: mutationEvent.parentId, client: EventId.clientDefault },
-      sessionId: undefined,
     })
 
   toGlobal = (): AnyEncodedGlobal => ({
@@ -203,6 +219,6 @@ export const isEqualEncoded = (a: AnyEncoded, b: AnyEncoded) =>
   a.id.client === b.id.client &&
   a.mutation === b.mutation &&
   a.clientId === b.clientId &&
-  // a.sessionId === b.sessionId &&
+  a.sessionId === b.sessionId &&
   // TODO use schema equality here
   JSON.stringify(a.args) === JSON.stringify(b.args)

package/src/schema/db-schema/dsl/mod.ts

@@ -52,8 +52,13 @@ export type AnyIfConstained<In, Out> = '__constrained' extends keyof In ? any :
 export type EmptyObjIfConstained<In> = '__constrained' extends keyof In ? {} : In
 
 export type StructSchemaForColumns<TCols extends ConstraintColumns> = Schema.Schema<
-  AnyIfConstained<TCols, { readonly [K in keyof TCols]: TCols[K]['schema']['Type'] }>,
-  AnyIfConstained<TCols, { readonly [K in keyof TCols]: TCols[K]['schema']['Encoded'] }>
+  AnyIfConstained<TCols, FromColumns.RowDecoded<TCols>>,
+  AnyIfConstained<TCols, FromColumns.RowEncoded<TCols>>
+>
+
+export type InsertStructSchemaForColumns<TCols extends ConstraintColumns> = Schema.Schema<
+  AnyIfConstained<TCols, FromColumns.InsertRowDecoded<TCols>>,
+  AnyIfConstained<TCols, FromColumns.InsertRowEncoded<TCols>>
 >
 
 export const structSchemaForTable = <TTableDefinition extends TableDefinition<any, any>>(
@@ -63,6 +68,20 @@ export const structSchemaForTable = <TTableDefinition extends TableDefinition<an
     title: tableDef.name,
   }) as any
 
+export const insertStructSchemaForTable = <TTableDefinition extends TableDefinition<any, any>>(
+  tableDef: TTableDefinition,
+): InsertStructSchemaForColumns<TTableDefinition['columns']> =>
+  Schema.Struct(
+    Object.fromEntries(
+      tableDef.ast.columns.map((column) => [
+        column.name,
+        column.nullable === true || column.default._tag === 'Some' ? Schema.optional(column.schema) : column.schema,
+      ]),
+    ),
+  ).annotations({
+    title: tableDef.name,
+  }) as any
+
 const columsToAst = (columns: Columns): ReadonlyArray<SqliteAst.Column> => {
   return Object.entries(columns).map(([name, column]) => {
     return {
@@ -161,6 +180,10 @@ export namespace FromColumns {
     readonly [K in keyof TColumns]: Schema.Schema.Type<TColumns[K]['schema']>
   }
 
+  export type RowEncodedAll<TColumns extends Columns> = {
+    readonly [K in keyof TColumns]: Schema.Schema.Encoded<TColumns[K]['schema']>
+  }
+
   export type RowEncoded<TColumns extends Columns> = Types.Simplify<
     Nullable<Pick<RowEncodeNonNullable<TColumns>, NullableColumnNames<TColumns>>> &
       Omit<RowEncodeNonNullable<TColumns>, NullableColumnNames<TColumns>>
@@ -192,4 +215,9 @@ export namespace FromColumns {
     Pick<RowDecodedAll<TColumns>, RequiredInsertColumnNames<TColumns>> &
       Partial<Omit<RowDecodedAll<TColumns>, RequiredInsertColumnNames<TColumns>>>
   >
+
+  export type InsertRowEncoded<TColumns extends Columns> = Types.Simplify<
+    Pick<RowEncodedAll<TColumns>, RequiredInsertColumnNames<TColumns>> &
+      Partial<Omit<RowEncodedAll<TColumns>, RequiredInsertColumnNames<TColumns>>>
+  >
 }

package/src/schema/mutations.ts

@@ -1,5 +1,6 @@
 import { Schema } from '@livestore/utils/effect'
 
+import type { QueryBuilder } from '../query-builder/mod.js'
 import type { BindValues } from '../sql-queries/sql-queries.js'
 
 export type MutationDefMap = {
@@ -20,7 +21,10 @@ export type InternalMutationSchema<TRecord extends MutationDefRecord = MutationD
 
 export type MutationDefSqlResult<TTo> =
   | SingleOrReadonlyArray<string>
-  | ((args: TTo) => SingleOrReadonlyArray<
+  | ((
+      args: TTo,
+      context: { currentFacts: MutationEventFacts; clientOnly: boolean },
+    ) => SingleOrReadonlyArray<
       | string
       | {
           sql: string
@@ -28,8 +32,15 @@ export type MutationDefSqlResult<TTo> =
           bindValues: BindValues
           writeTables?: ReadonlySet<string>
         }
+      | QueryBuilder.Any
     >)
 
+export type MutationHandlerResult = {
+  sql: string
+  bindValues: BindValues
+  writeTables?: ReadonlySet<string>
+}
+
 export type SingleOrReadonlyArray<T> = T | ReadonlyArray<T>
 
 export type MutationDef<TName extends string, TFrom, TTo> = {

package/src/schema/system-tables.ts

@@ -79,8 +79,7 @@ export const mutationLogMetaTable = table(
     mutation: SqliteDsl.text({}),
     argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
     clientId: SqliteDsl.text({}),
-    /** Only available for mutations which were executed in this client */
-    sessionId: SqliteDsl.text({ nullable: true }),
+    sessionId: SqliteDsl.text({}),
     schemaHash: SqliteDsl.integer({}),
     syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
   },

package/src/schema/table-def.ts

@@ -19,12 +19,12 @@ export type DefaultSqliteTableDefConstrained = SqliteDsl.TableDefinition<string,
 export type TableDefBase<
   TSqliteDef extends DefaultSqliteTableDef = DefaultSqliteTableDefConstrained,
   TOptions extends TableOptions = TableOptions,
-  TSchema = SqliteDsl.StructSchemaForColumns<TSqliteDef['columns']>,
 > = {
   sqliteDef: TSqliteDef
   options: TOptions
   // Derived from `sqliteDef`, so only exposed for convenience
-  schema: TSchema
+  schema: SqliteDsl.StructSchemaForColumns<TSqliteDef['columns']>
+  insertSchema: SqliteDsl.InsertStructSchemaForColumns<TSqliteDef['columns']>
 }
 
 export type TableDef<
@@ -47,7 +47,10 @@ export type TableDef<
   options: TOptions
   // Derived from `sqliteDef`, so only exposed for convenience
   schema: TSchema
-  query: QueryBuilder<ReadonlyArray<Schema.Schema.Type<TSchema>>, TableDef<TSqliteDef & {}, TOptions>>
+  insertSchema: SqliteDsl.InsertStructSchemaForColumns<TSqliteDef['columns']>
+  query: QueryBuilder<ReadonlyArray<Schema.Schema.Type<TSchema>>, TableDefBase<TSqliteDef & {}, TOptions>>
+  readonly Type: Schema.Schema.Type<TSchema>
+  readonly Encoded: Schema.Schema.Encoded<TSchema>
 } & (TOptions['deriveMutations']['enabled'] extends true
   ? DerivedMutationHelperFns<TSqliteDef['columns'], TOptions>
   : {})
@@ -195,7 +198,14 @@ export const table = <
   const isSingleColumn = SqliteDsl.isColumnDefinition(columnOrColumns) === true
 
   const schema = SqliteDsl.structSchemaForTable(sqliteDef)
-  const tableDef = { sqliteDef, options: options_, schema } satisfies TableDefBase
+  const insertSchema = SqliteDsl.insertStructSchemaForTable(sqliteDef)
+  const tableDef = {
+    sqliteDef,
+    options: options_,
+    schema,
+    insertSchema,
+  } satisfies TableDefBase
+
   const query = makeQueryBuilder(tableDef)
   // const tableDef = { ...tableDefBase, query } satisfies TableDef