@livestore/common 0.4.0 → 0.5.0-dev.1

package/src/schema/state/sqlite/table-def.ts

@@ -1,5 +1,6 @@
 import { type Nullable, shouldNeverHappen } from '@livestore/utils'
-import { Option, Schema, SchemaAST, type Types } from '@livestore/utils/effect'
+import type { Schema } from '@livestore/utils/effect'
+import { SchemaAST, type Types } from '@livestore/utils/effect'
 
 import { getColumnDefForSchema, schemaFieldsToColumns } from './column-def.ts'
 import { SqliteDsl } from './db-schema/mod.ts'
@@ -38,29 +39,17 @@ export type TableDef<
   // https://github.com/livestorejs/livestore/issues/382
   TSqliteDef extends DefaultSqliteTableDef = DefaultSqliteTableDefConstrained,
   TOptions extends TableOptions = TableOptions,
-  // NOTE we're not using `SqliteDsl.StructSchemaForColumns<TSqliteDef['columns']>`
-  // as we don't want the alias type for users to show up, so we're redefining it here
-  // TODO adjust this to `TSchema = Schema.TypeLiteral<` but requires some advance type-level work
-  TSchema = Schema.Schema<
-    SqliteDsl.AnyIfConstained<
-      TSqliteDef['columns'],
-      { readonly [K in keyof TSqliteDef['columns']]: TSqliteDef['columns'][K]['schema']['Type'] }
-    >,
-    SqliteDsl.AnyIfConstained<
-      TSqliteDef['columns'],
-      { readonly [K in keyof TSqliteDef['columns']]: TSqliteDef['columns'][K]['schema']['Encoded'] }
-    >
-  >,
+  TSchema extends Schema.Top = Schema.Struct<SqliteDsl.StructFieldsForColumns<TSqliteDef['columns']>>,
 > = {
   sqliteDef: TSqliteDef
   options: TOptions
   // Derived from `sqliteDef`, so only exposed for convenience
   rowSchema: TSchema
   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>
-} & QueryBuilder<ReadonlyArray<Schema.Schema.Type<TSchema>>, TableDefBase<TSqliteDef & {}, TOptions>>
+  // query: QueryBuilder<ReadonlyArray<TSchema['Type']>>, TableDefBase<TSqliteDef & {}, TOptions>>
+  readonly Type: TSchema['Type']
+  readonly Encoded: TSchema['Encoded']
+} & QueryBuilder<ReadonlyArray<TSchema['Type']>, TableDefBase<TSqliteDef & {}, TOptions>>
 
 export type TableOptionsInput = Partial<{
   indexes: SqliteDsl.Index[]
@@ -114,7 +103,7 @@ export type TableOptions = {
  * })
  *
  * // Option 2: With name from schema annotation (title or identifier)
- * const AnnotatedUserSchema = UserSchema.annotations({ title: 'users' })
+ * const AnnotatedUserSchema = UserSchema.annotate({ title: 'users' })
  * const usersTable2 = State.SQLite.table({
  *   schema: AnnotatedUserSchema,
  * })
@@ -127,7 +116,7 @@ export type TableOptions = {
  *   title: Schema.String,
  *   authorId: Schema.String,
  *   createdAt: Schema.Date,
- * }).annotations({ identifier: 'posts' })
+ * }).annotate({ identifier: 'posts' })
  *
  * const postsTable = State.SQLite.table({
  *   schema: PostSchema,
@@ -161,24 +150,21 @@ export function table<
 // Overload 2: With schema and explicit name
 export function table<
   TName extends string,
-  TSchema extends Schema.Schema.AnyNoContext,
+  TSchema extends Schema.Top,
   const TOptionsInput extends TableOptionsInput = TableOptionsInput,
 >(
   args: {
     name: TName
     schema: TSchema
   } & Partial<TOptionsInput>,
-): TableDef<SqliteTableDefForSchemaInput<TName, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>>
+): TableDef<SqliteTableDefForSchemaInput<TName, TSchema['Type'], TSchema['Encoded'], TSchema>>
 
 // Overload 3: With schema and no name (uses schema annotations)
-export function table<
-  TSchema extends Schema.Schema.AnyNoContext,
-  const TOptionsInput extends TableOptionsInput = TableOptionsInput,
->(
+export function table<TSchema extends Schema.Top, const TOptionsInput extends TableOptionsInput = TableOptionsInput>(
   args: {
     schema: TSchema
   } & Partial<TOptionsInput>,
-): TableDef<SqliteTableDefForSchemaInput<string, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>>
+): TableDef<SqliteTableDefForSchemaInput<string, TSchema['Type'], TSchema['Encoded'], TSchema>>
 
 // Implementation
 export function table<
@@ -193,10 +179,10 @@ export function table<
       }
     | {
         name: TName
-        schema: Schema.Schema.AnyNoContext
+        schema: Schema.Top
       }
     | {
-        schema: Schema.Schema.AnyNoContext
+        schema: Schema.Top
       }
   ) &
     Partial<TOptionsInput>,
@@ -213,7 +199,7 @@ export function table<
     columns = SqliteDsl.isColumnDefinition(columnOrColumns) === true ? { value: columnOrColumns } : columnOrColumns
     additionalIndexes = []
   } else if ('schema' in args) {
-    const result = schemaFieldsToColumns(Schema.getResolvedPropertySignatures(args.schema))
+    const result = args.schema.pipe(getSqlitePropertySignatures, schemaFieldsToColumns)
     columns = result.columns
 
     // We'll set tableName first, then use it for index names
@@ -224,14 +210,12 @@ export function table<
       tempTableName = args.name
     } else {
       // Use title or identifier, with preference for title
-      tempTableName = SchemaAST.getTitleAnnotation(args.schema.ast).pipe(
-        Option.orElse(() => SchemaAST.getIdentifierAnnotation(args.schema.ast)),
-        Option.getOrElse(() =>
-          shouldNeverHappen(
-            'When using schema without explicit name, the schema must have a title or identifier annotation',
-          ),
-        ),
-      )
+      tempTableName =
+        SchemaAST.resolveTitle(args.schema.ast) ??
+        SchemaAST.resolveIdentifier(args.schema.ast) ??
+        shouldNeverHappen(
+          'When using schema without explicit name, the schema must have a title or identifier annotation',
+        )
     }
 
     tableName = tempTableName
@@ -281,6 +265,90 @@ export function table<
   return tableDef as any
 }
 
+/**
+ * The encoded side of the schema decides which columns exist (a transformation may flatten a nested
+ * type into columns). Where the schema itself declares a property of the same name, that property's
+ * own AST becomes the column schema: it still carries the field's encoding, so a codec such as
+ * `Schema.DateFromString` or `Schema.DateFromMillis` stores its encoded form and decodes back to
+ * its type. Substituting the type-side AST instead would strip that encoding and leave a `Date`
+ * with nothing SQLite can store natively, which is how date columns ended up JSON-encoded and
+ * unreadable.
+ */
+const getSqlitePropertySignatures = (schema: Schema.Top): ReadonlyArray<SchemaAST.PropertySignature> => {
+  const encodedPropertySignatures = getPropertySignatures(SchemaAST.toEncoded(schema.ast))
+  const ownPropertySignatures = getPropertySignatures(schema.ast)
+
+  return encodedPropertySignatures.map((encodedPropertySignature) => {
+    const ownPropertySignature = ownPropertySignatures.find(
+      (propertySignature) => propertySignature.name === encodedPropertySignature.name,
+    )
+
+    if (ownPropertySignature === undefined || hasLiveStoreSqliteAnnotation(encodedPropertySignature.type) === true) {
+      return encodedPropertySignature
+    }
+
+    return ownPropertySignature
+  })
+}
+
+const getPropertySignatures = (ast: SchemaAST.AST): ReadonlyArray<SchemaAST.PropertySignature> => {
+  if (SchemaAST.isObjects(ast) === true) return ast.propertySignatures
+
+  // Class declarations encode through their fields object. Inspect that first
+  // link before toEncoded strips the individual field codecs.
+  if (SchemaAST.isDeclaration(ast) === true) {
+    const fieldsAst = ast.encoding?.[0]?.to
+    if (fieldsAst !== undefined) return getPropertySignatures(fieldsAst)
+  }
+
+  if (SchemaAST.isUnion(ast) === true) {
+    const members = ast.types.map(getPropertySignatures)
+    const [head, ...tail] = members
+    if (head === undefined) return []
+
+    return head.flatMap((propertySignature) => {
+      const matchingPropertySignatures: Array<SchemaAST.PropertySignature> = []
+      for (const propertySignatures of tail) {
+        const matchingPropertySignature = propertySignatures.find(
+          (memberPropertySignature) => memberPropertySignature.name === propertySignature.name,
+        )
+        if (matchingPropertySignature === undefined) {
+          return []
+        }
+        matchingPropertySignatures.push(matchingPropertySignature)
+      }
+
+      const propertySignatures = [propertySignature, ...matchingPropertySignatures]
+      /**
+       * `SchemaAST.optionalKey` became internal in Effect rc.109, so the optional-key marker is
+       * applied by constructing the union with an optional `Context`. Equivalent here because the
+       * union is freshly built and therefore carries no encoding chain to propagate the marker to.
+       */
+      const hasOptionalMember =
+        propertySignatures.some((memberPropertySignature) => SchemaAST.isOptional(memberPropertySignature.type)) ===
+        true
+      const keyContext = hasOptionalMember === true ? new SchemaAST.Context(true, false) : undefined
+      const union = new SchemaAST.Union(
+        propertySignatures.map((memberPropertySignature) => memberPropertySignature.type),
+        ast.options,
+        undefined,
+        undefined,
+        undefined,
+        keyContext,
+      )
+
+      return [new SchemaAST.PropertySignature(propertySignature.name, union)]
+    })
+  }
+
+  return []
+}
+
+const hasLiveStoreSqliteAnnotation = (ast: SchemaAST.AST): boolean => {
+  const annotationKeys = [...Object.keys(ast.annotations ?? {}), ...Object.keys(ast.context?.annotations ?? {})]
+  return annotationKeys.some((key) => key.startsWith('livestore/state/sqlite/annotations/'))
+}
+
 export namespace FromTable {
   // TODO this sometimes doesn't preserve the order of columns
   export type RowDecoded<TTableDef extends TableDefBase> = Types.Simplify<
@@ -297,9 +365,7 @@ export namespace FromTable {
   }
 
   export type RowEncodeNonNullable<TTableDef extends TableDefBase> = {
-    [K in keyof TTableDef['sqliteDef']['columns']]: Schema.Schema.Encoded<
-      TTableDef['sqliteDef']['columns'][K]['schema']
-    >
+    [K in keyof TTableDef['sqliteDef']['columns']]: TTableDef['sqliteDef']['columns'][K]['schema']['Encoded']
   }
 
   export type RowEncoded<TTableDef extends TableDefBase> = Types.Simplify<
@@ -308,7 +374,7 @@ export namespace FromTable {
   >
 
   export type RowDecodedAll<TTableDef extends TableDefBase> = {
-    [K in keyof TTableDef['sqliteDef']['columns']]: Schema.Schema.Type<TTableDef['sqliteDef']['columns'][K]['schema']>
+    [K in keyof TTableDef['sqliteDef']['columns']]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
   }
 }
 
@@ -320,7 +386,7 @@ export namespace FromColumns {
   >
 
   export type RowDecodedAll<TColumns extends SqliteDsl.Columns> = {
-    [K in keyof TColumns]: Schema.Schema.Type<TColumns[K]['schema']>
+    [K in keyof TColumns]: TColumns[K]['schema']['Type']
   }
 
   export type RowEncoded<TColumns extends SqliteDsl.Columns> = Types.Simplify<
@@ -329,7 +395,7 @@ export namespace FromColumns {
   >
 
   export type RowEncodeNonNullable<TColumns extends SqliteDsl.Columns> = {
-    [K in keyof TColumns]: Schema.Schema.Encoded<TColumns[K]['schema']>
+    [K in keyof TColumns]: TColumns[K]['schema']['Encoded']
   }
 
   export type NullableColumnNames<TColumns extends SqliteDsl.Columns> = keyof {
@@ -378,7 +444,8 @@ export declare namespace SchemaToColumns {
   export type FromTypes<TType, TEncoded> =
     TEncoded extends Record<string, any>
       ? {
-          [K in keyof TEncoded]-?: ColumnDefForType<TEncoded[K],
+          [K in keyof TEncoded]-?: ColumnDefForType<
+            TEncoded[K],
             TType extends Record<string, any> ? (K extends keyof TType ? TType[K] : TEncoded[K]) : TEncoded[K]
           >
         }

package/src/schema/unknown-events.ts

@@ -72,8 +72,9 @@ const handleUnknownEvent = ({
       case 'callback': {
         const callback = config.onUnknownEvent
 
-        yield* Effect.tryAll<void>(() => callback(context, error)).pipe(
-          Effect.catchAll((cause) =>
+        // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- user callback errors are immediately handled and logged below
+        yield* Effect.trySyncOrPromiseOrEffect(() => callback(context, error)).pipe(
+          Effect.catch((cause) =>
             Effect.logWarning('@livestore/common:schema:unknown-event:callback-error', {
               event: context.event,
               reason: context.reason,

package/src/schema-management/__tests__/migrations-autoincrement-quoting.test.ts

@@ -2,13 +2,16 @@ import { describe, expect, it } from 'vitest'
 
 import { Effect, Option, Schema } from '@livestore/utils/effect'
 
+import { fingerprint } from '../../schema/state/sqlite/db-schema/ast/fingerprint.ts'
 import { SqliteAst } from '../../schema/state/sqlite/db-schema/mod.ts'
+import { schemaMetaTable } from '../../schema/state/sqlite/system-tables/state-tables.ts'
 import type { PreparedStatement, SqliteDb } from '../../sqlite-types.ts'
 import type { PreparedBindValues } from '../../util.ts'
 import { migrateTable } from '../migrations.ts'
 
 const makeStubDb = () => {
   const executed: string[] = []
+  const bindings: Array<PreparedBindValues | undefined> = []
 
   const db: SqliteDb = {
     _tag: 'SqliteDb',
@@ -16,8 +19,9 @@ const makeStubDb = () => {
     debug: { head: 0 as any },
     prepare: (queryStr: string): PreparedStatement => ({
       sql: queryStr,
-      execute: (_bind: PreparedBindValues | undefined) => {
+      execute: (bind: PreparedBindValues | undefined) => {
         executed.push(queryStr)
+        bindings.push(bind)
       },
       select: <T>(_bind: PreparedBindValues | undefined) => [] as unknown as ReadonlyArray<T>,
       finalize: () => {},
@@ -32,7 +36,7 @@ const makeStubDb = () => {
     makeChangeset: () => ({ invert: () => ({ invert: () => ({}) as any, apply: () => {} }) as any, apply: () => {} }),
   }
 
-  return { db, executed }
+  return { db, executed, bindings }
 }
 
 describe('migrateTable - quoting and autoincrement', () => {
@@ -49,7 +53,7 @@ describe('migrateTable - quoting and autoincrement', () => {
           primaryKey: true,
           autoIncrement: true,
           default: Option.none(),
-          schema: Schema.Number,
+          schema: Schema.Finite,
         }),
         SqliteAst.column({
           name: 'text',
@@ -67,7 +71,7 @@ describe('migrateTable - quoting and autoincrement', () => {
           primaryKey: false,
           autoIncrement: false,
           default: Option.some(0),
-          schema: Schema.Number,
+          schema: Schema.Finite,
         }),
       ],
       [],
@@ -85,4 +89,31 @@ describe('migrateTable - quoting and autoincrement', () => {
     expect(createStmt!).not.toContain("PRIMARY KEY ('id')")
     expect(createStmt!).not.toMatch(/'todos'|'id'|'text'/)
   })
+
+  it('persists full textual table fingerprints', () => {
+    const { db, bindings } = makeStubDb()
+    const table = SqliteAst.table(
+      'todos',
+      [
+        SqliteAst.column({
+          name: 'id',
+          type: { _tag: 'text' },
+          nullable: false,
+          primaryKey: true,
+          autoIncrement: false,
+          default: Option.none(),
+          schema: Schema.String,
+        }),
+      ],
+      [],
+    )
+
+    migrateTable({ db, tableAst: table, behaviour: 'create-if-not-exists' }).pipe(Effect.runSync)
+
+    const schemaMetaBinding = bindings.find(
+      (binding) => binding !== undefined && Array.isArray(binding) === false && '$schemaHash' in binding,
+    )
+    expect(schemaMetaBinding).toMatchObject({ $schemaHash: fingerprint(table) })
+    expect(schemaMetaTable.sqliteDef.ast.columns.find((column) => column.name === 'schemaHash')?.type._tag).toBe('text')
+  })
 })

package/src/schema-management/migrations.ts

@@ -8,7 +8,7 @@
  * - EVENTLOG TABLES (NEVER modify): Changes cause data loss - need manual versioning!
  *
  * How it works:
- * 1. Each table's schema is hashed using SqliteAst.hash()
+ * 1. Each table's schema is fingerprinted
  * 2. Hashes are stored in SCHEMA_META_TABLE after successful migrations
  * 3. On app start, current schema hashes are compared with stored hashes
  * 4. Mismatches trigger migrations:
@@ -37,7 +37,8 @@ import type { MigrationsReport, MigrationsReportEntry } from '../defs.ts'
 import type { UnknownError } from '../errors.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { makeColumnSpec } from '../schema/state/sqlite/column-spec.ts'
-import { SqliteAst } from '../schema/state/sqlite/db-schema/mod.ts'
+import { fingerprint } from '../schema/state/sqlite/db-schema/ast/fingerprint.ts'
+import type { SqliteAst } from '../schema/state/sqlite/db-schema/mod.ts'
 import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables/state-tables.ts'
 import {
   isStateSystemTable,
@@ -114,14 +115,14 @@ export const migrateDb = ({
       ...Array.from(schema.state.sqlite.tables.values()).filter((_) => !isStateSystemTable(_.sqliteDef.name)),
     ]
 
-    const tablesToMigrate = new Set<{ tableAst: SqliteAst.Table; schemaHash: number }>()
+    const tablesToMigrate = new Set<{ tableAst: SqliteAst.Table; schemaHash: string }>()
 
     const migrationsReportEntries: MigrationsReportEntry[] = []
     for (const tableDef of tableDefs) {
       const tableAst = tableDef.sqliteDef.ast
       const tableName = tableAst.name
       const dbSchemaHash = dbSchemaHashByTable[tableName]
-      const schemaHash = SqliteAst.hash(tableAst)
+      const schemaHash = fingerprint(tableAst)
 
       if (schemaHash !== dbSchemaHash) {
         tablesToMigrate.add({ tableAst, schemaHash })
@@ -151,13 +152,13 @@ export const migrateDb = ({
 export const migrateTable = ({
   db,
   tableAst,
-  schemaHash = SqliteAst.hash(tableAst),
+  schemaHash = fingerprint(tableAst),
   behaviour,
   skipMetaTable = false,
 }: {
   db: SqliteDb
   tableAst: SqliteAst.Table
-  schemaHash?: number
+  schemaHash?: string
   behaviour: 'drop-and-recreate' | 'create-if-not-exists'
   skipMetaTable?: boolean
 }) =>

package/src/session-id-symbol.ts

@@ -0,0 +1,59 @@
+/**
+ * SessionIdSymbol is a user-facing placeholder for "the current client session".
+ * User code can keep using the same event/query object across sessions, while the
+ * storage and eventlog layers require concrete string ids. Resolving the symbol at
+ * those boundaries preserves the symbolic API without mutating caller-owned values.
+ *
+ * @module
+ */
+import { Predicate } from '@livestore/utils/effect'
+
+import type { Bindable, SqlValue } from './util.ts'
+
+/**
+ * Can be used in queries to refer to the current session id.
+ * Will be replaced with the actual session id at runtime.
+ *
+ * In client document table:
+ * ```ts
+ * const uiState = State.SQLite.clientDocument({
+ *   name: 'ui_state',
+ *   schema: Schema.Struct({
+ *     theme: Schema.Literals(['dark', 'light', 'system']),
+ *     user: Schema.String,
+ *     showToolbar: Schema.Boolean,
+ *   }),
+ *   default: { value: defaultFrontendState, id: SessionIdSymbol },
+ * })
+ * ```
+ *
+ * Or in a client document query:
+ * ```ts
+ * const query$ = queryDb(tables.uiState.get(SessionIdSymbol))
+ * ```
+ */
+export const SessionIdSymbol = Symbol.for('@livestore/session-id')
+export type SessionIdSymbol = typeof SessionIdSymbol
+
+export type BindableWithSessionIdSymbol =
+  | ReadonlyArray<SqlValue | SessionIdSymbol>
+  | Record<string, SqlValue | SessionIdSymbol>
+
+export const resolveSessionIdSymbolInBindValues = (
+  bindValues: BindableWithSessionIdSymbol,
+  sessionId: string,
+): Bindable => {
+  return Array.isArray(bindValues) === true
+    ? bindValues.map((value) => (value === SessionIdSymbol ? sessionId : value))
+    : (Object.fromEntries(
+        Object.entries(bindValues).map(([key, value]) => [key, value === SessionIdSymbol ? sessionId : value]),
+      ) as Record<string, SqlValue>)
+}
+
+export const resolveSessionIdSymbolInEventArgs = (args: unknown, sessionId: string): unknown => {
+  if (Predicate.hasProperty(args, 'id') === false) {
+    return args
+  }
+
+  return args.id === SessionIdSymbol ? { ...args, id: sessionId } : args
+}

package/src/sql-queries/sql-queries.ts

@@ -1,9 +1,8 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import { pipe, ReadonlyArray, Schema, TreeFormatter } from '@livestore/utils/effect'
+import { pipe, ReadonlyArray, ReadonlyRecord, Result, Schema, SchemaIssue } from '@livestore/utils/effect'
 
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 import { sql } from '../util.ts'
-import { objectEntries } from './misc.ts'
 import * as ClientTypes from './types.ts'
 
 export type BindValues = {
@@ -106,7 +105,6 @@ export const insertRows = <TColumns extends SqliteDsl.Columns>({
 
   const bindValues = valuesArray.reduce(
     (acc, values, itemIndex) => ({
-      // biome-ignore lint/performance/noAccumulatingSpread: TODO improve this some day
       ...acc,
       ...makeBindValues({ columns, values, variablePrefix: `item_${itemIndex}_` }),
     }),
@@ -279,15 +277,14 @@ export const makeBindValues = <TColumns extends SqliteDsl.Columns, TKeys extends
   skipNil?: boolean
 }): Record<string, any> => {
   const codecMap = pipe(
-    columns,
-    objectEntries,
+    ReadonlyRecord.toEntries(columns),
     ReadonlyArray.map(([columnName, columnDef]) => [
       columnName,
       (value: any) => {
         if (columnDef.nullable === true && (value === null || value === undefined)) return null
-        const res = Schema.encodeEither(columnDef.schema)(value)
-        if (res._tag === 'Left') {
-          const parseErrorStr = TreeFormatter.formatErrorSync(res.left)
+        const res = Schema.encodeResult(columnDef.schema)(value)
+        if (Result.isFailure(res) === true) {
+          const parseErrorStr = SchemaIssue.makeFormatterDefault()(res.failure.issue)
           const expectedSchemaStr = String(columnDef.schema.ast)
 
           console.error(
@@ -301,11 +298,11 @@ Error: ${parseErrorStr}
 Value:`,
             value,
           )
-          // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for SQL decode errors
+          // oxlint-disable-next-line no-debugger -- intentional breakpoint for SQL decode errors
           debugger
-          throw res.left
+          throw res.failure
         } else {
-          return res.right
+          return res.success
         }
       },
     ]),
@@ -363,8 +360,7 @@ const buildWhereSql = <TColumns extends SqliteDsl.Columns>({
   }
 
   return pipe(
-    where,
-    objectEntries,
+    ReadonlyRecord.toEntries(where),
     ReadonlyArray.map(([columnName, value]) => `${columnName} ${getWhereOp(columnName, value)}`),
     ReadonlyArray.join(' AND '),
   )

package/src/sql-queries/types.ts

@@ -1,16 +1,15 @@
-import type { Prettify } from '@livestore/utils'
-import type { Schema } from '@livestore/utils/effect'
+import type { Schema, Types } from '@livestore/utils/effect'
 
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 
 export type DecodedValuesForTableAll<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = {
-  [K in keyof GetColumns<TSchema, TTableName>]: Schema.Schema.Type<GetColumn<TSchema, TTableName, K>['schema']>
+  [K in keyof GetColumns<TSchema, TTableName>]: GetColumn<TSchema, TTableName, K>['schema']['Type']
 }
 
 export type DecodedValuesForTablePretty<
   TSchema extends SqliteDsl.DbSchema,
   TTableName extends keyof TSchema,
-> = Prettify<DecodedValuesForTable<TSchema, TTableName>>
+> = Types.Simplify<DecodedValuesForTable<TSchema, TTableName>>
 
 export type DecodedValuesForTable<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = Partial<
   Pick<DecodedValuesForTableAll<TSchema, TTableName>, GetNullableColumnNamesForTable<TSchema, TTableName>>
@@ -40,7 +39,7 @@ export const isValidWhereOp = (op: string): op is WhereOp => {
 }
 
 export type EncodedValuesForTableAll<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = {
-  [K in keyof GetColumns<TSchema, TTableName>]: Schema.Schema.Type<GetColumn<TSchema, TTableName, K>['schema']>
+  [K in keyof GetColumns<TSchema, TTableName>]: GetColumn<TSchema, TTableName, K>['schema']['Type']
 }
 
 export type EncodedValuesForTable<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = Partial<
@@ -69,7 +68,7 @@ export type GetColumn<
 > = TSchema[TTableName]['columns'][TColumnName]
 
 export type DecodedValuesForColumnsAll<TColumns extends SqliteDsl.Columns> = {
-  [K in keyof TColumns]: Schema.Schema.Type<TColumns[K]['schema']>
+  [K in keyof TColumns]: TColumns[K]['schema']['Type']
 }
 
 export type DecodedValuesForColumns<TColumns extends SqliteDsl.Columns> = Partial<
@@ -78,7 +77,7 @@ export type DecodedValuesForColumns<TColumns extends SqliteDsl.Columns> = Partia
   Omit<DecodedValuesForColumnsAll<TColumns>, GetNullableColumnNames<TColumns>>
 
 export type EncodedValuesForColumnsAll<TColumns extends SqliteDsl.Columns> = {
-  [K in keyof TColumns]: Schema.Schema.Encoded<TColumns[K]['schema']>
+  [K in keyof TColumns]: TColumns[K]['schema']['Encoded']
 }
 
 export type EncodedValuesForColumns<TColumns extends SqliteDsl.Columns> = Partial<

package/src/sqlite-db-helper.ts

@@ -1,4 +1,4 @@
-import { Schema } from '@livestore/utils/effect'
+import { Effect, Exit, Function, Schema } from '@livestore/utils/effect'
 
 import { type SqliteDb, SqliteError } from './adapter-types.ts'
 import { getResultSchema, isQueryBuilder } from './schema/state/sqlite/query-builder/mod.ts'
@@ -33,13 +33,75 @@ export const makeSelect = <T>(
       const { query, bindValues } = queryStrOrQueryBuilder.asSql()
       const resultSchema = getResultSchema(queryStrOrQueryBuilder)
       const results = select(query, bindValues as unknown as PreparedBindValues)
-      return Schema.decodeSync(resultSchema)(results)
+      return Schema.decodeUnknownSync(resultSchema)(results)
     } else {
       return select(queryStrOrQueryBuilder, maybeBindValues)
     }
   }
 }
 
+/**
+ * Runs an Effect inside an SQLite savepoint.
+ *
+ * @remarks
+ *
+ * This starts a savepoint before running `effect`, releases the savepoint on
+ * success, and rolls back to the savepoint before re-emitting the original
+ * failure on failure.
+ *
+ * Use this for atomic DB updates that need to compose with callers that may
+ * already have an open transaction.
+ *
+ * @see {@link https://sqlite.org/lang_savepoint.html | SQLite savepoint documentation}
+ * @see {@link https://sqlite.org/lang_transaction.html | SQLite transaction documentation}
+ */
+export const withSavepoint: {
+  (db: SqliteDb): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqliteError, R>
+  <A, E, R>(self: Effect.Effect<A, E, R>, db: SqliteDb): Effect.Effect<A, E | SqliteError, R>
+} = Function.dual(
+  2,
+  <A, E, R>(self: Effect.Effect<A, E, R>, db: SqliteDb): Effect.Effect<A, E | SqliteError, R> =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.sync(generateSavepointName).pipe(
+        Effect.flatMap((savepointName) => {
+          const savepointSql = `SAVEPOINT ${savepointName}`
+          const releaseSql = `RELEASE SAVEPOINT ${savepointName}`
+
+          return executeSavepointSql(db, savepointSql).pipe(
+            // Cleanup is installed only after SQLite successfully creates the savepoint.
+            Effect.andThen(
+              restore(self).pipe(
+                Effect.exit,
+                Effect.flatMap((exit) => {
+                  const cleanup =
+                    Exit.isSuccess(exit) === true
+                      ? executeSavepointSql(db, releaseSql)
+                      : executeSavepointSql(db, `ROLLBACK TO SAVEPOINT ${savepointName}`).pipe(
+                          Effect.andThen(executeSavepointSql(db, releaseSql)),
+                        )
+
+                  // Cleanup failures supersede the wrapped exit because the connection state is uncertain.
+                  return cleanup.pipe(Effect.andThen(exit))
+                }),
+              ),
+            ),
+          )
+        }),
+      ),
+    ),
+)
+
+let nextSavepointId = 0
+
+/** Uses a reserved prefix and process-local counter to avoid caller-controlled or reused identifiers. */
+const generateSavepointName = () => `livestore_savepoint_${nextSavepointId++}`
+
+const executeSavepointSql = (db: SqliteDb, sql: string): Effect.Effect<void, SqliteError> =>
+  Effect.try({
+    try: () => db.execute(sql),
+    catch: (cause) => new SqliteError({ cause, query: { sql, bindValues: [] } }),
+  })
+
 export const validateSnapshot = (snapshot: Uint8Array) => {
   const headerBytes = new TextDecoder().decode(snapshot.slice(0, 16))
   const hasValidHeader = headerBytes.startsWith('SQLite format 3')