@livestore/common 0.4.0-dev.8 → 0.4.0

package/src/schema/unknown-events.ts

@@ -0,0 +1,131 @@
+import { Effect } from '@livestore/utils/effect'
+
+import { UnknownEventError } from '../errors.ts'
+import type { EventDef, Materializer } from './EventDef/mod.ts'
+import type * as LiveStoreEvent from './LiveStoreEvent/mod.ts'
+import type { LiveStoreSchema } from './schema.ts'
+
+export type UnknownEventContext = {
+  readonly event: Pick<LiveStoreEvent.Client.Encoded, 'name' | 'args' | 'seqNum' | 'clientId' | 'sessionId'>
+  readonly reason: 'event-definition-missing' | 'materializer-missing'
+  readonly operation: string
+}
+
+export namespace UnknownEvents {
+  export type HandlingStrategy = 'warn' | 'fail' | 'ignore' | 'callback'
+
+  export type Callback = (
+    context: UnknownEventContext,
+    error: UnknownEventError,
+  ) => Effect.SyncOrPromiseOrEffect<void, unknown>
+
+  export type HandlingConfig =
+    | { readonly strategy: 'warn' }
+    | { readonly strategy: 'ignore' }
+    | { readonly strategy: 'fail' }
+    | { readonly strategy: 'callback'; readonly onUnknownEvent: Callback }
+
+  export type Reason = UnknownEventContext['reason']
+
+  export type ResolveContext = Omit<UnknownEventContext, 'reason'>
+
+  export type Resolved =
+    | {
+        readonly _tag: 'known'
+        readonly eventDef: EventDef.AnyWithoutFn
+        readonly materializer: Materializer
+      }
+    | {
+        readonly _tag: 'unknown'
+        readonly reason: Reason
+      }
+}
+
+const DEFAULT_UNKNOWN_EVENT_HANDLING: UnknownEvents.HandlingConfig = { strategy: 'warn' }
+
+export const normalizeUnknownEventHandling = (
+  input: UnknownEvents.HandlingConfig | undefined,
+): UnknownEvents.HandlingConfig => input ?? DEFAULT_UNKNOWN_EVENT_HANDLING
+
+const handleUnknownEvent = ({
+  schema,
+  context,
+}: {
+  schema: LiveStoreSchema
+  context: UnknownEventContext
+}): Effect.Effect<void, UnknownEventError> =>
+  Effect.gen(function* () {
+    const config = schema.unknownEventHandling
+    const error = new UnknownEventError(context)
+
+    switch (config.strategy) {
+      case 'fail': {
+        return yield* error
+      }
+      case 'warn': {
+        yield* Effect.logWarning('@livestore/common:schema:unknown-event', context)
+        return
+      }
+      case 'ignore': {
+        return
+      }
+      case 'callback': {
+        const callback = config.onUnknownEvent
+
+        yield* Effect.tryAll<void>(() => callback(context, error)).pipe(
+          Effect.catchAll((cause) =>
+            Effect.logWarning('@livestore/common:schema:unknown-event:callback-error', {
+              event: context.event,
+              reason: context.reason,
+              operation: context.operation,
+              cause,
+            }),
+          ),
+        )
+        return
+      }
+    }
+  })
+
+/**
+ * Resolves the runtime event definition + materializer for a given event name.
+ *
+ * Behaviour is intentionally split across the result and error channels:
+ * - For `'fail'` handling, we surface an `UnknownEventError` via the failure channel so
+ *   callers can convert it into the appropriate domain error (for example `MaterializeError`).
+ * - For all other strategies (`warn`, `ignore`, `callback`) we succeed with an
+ *   `{ _tag: 'unknown' }` value, signalling that the caller should skip the event while
+ *   continuing normal processing.
+ */
+export const resolveEventDef = (
+  schema: LiveStoreSchema,
+  context: UnknownEvents.ResolveContext,
+): Effect.Effect<UnknownEvents.Resolved, UnknownEventError> =>
+  Effect.gen(function* () {
+    const eventName = context.event.name
+    const eventDef = schema.eventsDefsMap.get(eventName)
+    if (eventDef === undefined) {
+      yield* handleUnknownEvent({
+        schema,
+        context: {
+          event: context.event,
+          reason: 'event-definition-missing',
+          operation: context.operation,
+        },
+      })
+      return { _tag: 'unknown', reason: 'event-definition-missing' }
+    }
+    const materializer = schema.state.materializers.get(eventName)
+    if (materializer === undefined) {
+      yield* handleUnknownEvent({
+        schema,
+        context: {
+          event: context.event,
+          reason: 'materializer-missing',
+          operation: context.operation,
+        },
+      })
+      return { _tag: 'unknown', reason: 'materializer-missing' }
+    }
+    return { _tag: 'known', eventDef, materializer }
+  })

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

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import { Effect, Option, Schema } from '@livestore/utils/effect'
+
+import { SqliteAst } from '../../schema/state/sqlite/db-schema/mod.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 db: SqliteDb = {
+    _tag: 'SqliteDb',
+    metadata: { dbPointer: 0, persistenceInfo: { fileName: ':memory:' } } as any,
+    debug: { head: 0 as any },
+    prepare: (queryStr: string): PreparedStatement => ({
+      sql: queryStr,
+      execute: (_bind: PreparedBindValues | undefined) => {
+        executed.push(queryStr)
+      },
+      select: <T>(_bind: PreparedBindValues | undefined) => [] as unknown as ReadonlyArray<T>,
+      finalize: () => {},
+    }),
+    execute: () => {},
+    select: () => [],
+    export: () => new Uint8Array(),
+    import: () => {},
+    close: () => {},
+    destroy: () => {},
+    session: () => ({ changeset: () => undefined, finish: () => {} }),
+    makeChangeset: () => ({ invert: () => ({ invert: () => ({}) as any, apply: () => {} }) as any, apply: () => {} }),
+  }
+
+  return { db, executed }
+}
+
+describe('migrateTable - quoting and autoincrement', () => {
+  it('creates valid CREATE TABLE with inline INTEGER PRIMARY KEY AUTOINCREMENT and double-quoted identifiers', () => {
+    const { db, executed } = makeStubDb()
+
+    const table = SqliteAst.table(
+      'todos',
+      [
+        SqliteAst.column({
+          name: 'id',
+          type: { _tag: 'integer' },
+          nullable: false,
+          primaryKey: true,
+          autoIncrement: true,
+          default: Option.none(),
+          schema: Schema.Number,
+        }),
+        SqliteAst.column({
+          name: 'text',
+          type: { _tag: 'text' },
+          nullable: false,
+          primaryKey: false,
+          autoIncrement: false,
+          default: Option.some(''),
+          schema: Schema.String,
+        }),
+        SqliteAst.column({
+          name: 'completed',
+          type: { _tag: 'integer' },
+          nullable: false,
+          primaryKey: false,
+          autoIncrement: false,
+          default: Option.some(0),
+          schema: Schema.Number,
+        }),
+      ],
+      [],
+    )
+
+    migrateTable({ db, tableAst: table, behaviour: 'create-if-not-exists', skipMetaTable: true }).pipe(Effect.runSync)
+
+    const createStmt = executed.find((s) => /create table if not exists/i.test(s))
+    expect(createStmt).toBeDefined()
+
+    // Identifiers must be double-quoted, not single-quoted
+    expect(createStmt!).toContain('create table if not exists "todos"')
+    expect(createStmt!).toContain('"id" integer primary key autoincrement')
+    expect(createStmt!).toContain(" default ''")
+    expect(createStmt!).not.toContain("PRIMARY KEY ('id')")
+    expect(createStmt!).not.toMatch(/'todos'|'id'|'text'/)
+  })
+})

package/src/schema-management/common.ts

@@ -13,7 +13,7 @@ export const dbExecute = (db: SqliteDb, queryStr: string, bindValues?: ParamsObj
   // cachedStmts.set(queryStr, stmt)
   // }
 
-  const preparedBindValues = bindValues ? prepareBindValues(bindValues, queryStr) : undefined
+  const preparedBindValues = bindValues !== undefined ? prepareBindValues(bindValues, queryStr) : undefined
 
   try {
     stmt.execute(preparedBindValues)
@@ -34,7 +34,7 @@ export const dbSelect = <T>(db: SqliteDb, queryStr: string, bindValues?: ParamsO
   // cachedStmts.set(queryStr, stmt)
   // }
 
-  const res = stmt.select<T>(bindValues ? prepareBindValues(bindValues, queryStr) : undefined)
+  const res = stmt.select<T>(bindValues !== undefined ? prepareBindValues(bindValues, queryStr) : undefined)
   stmt.finalize()
   return res
 }

package/src/schema-management/migrations.ts

@@ -1,20 +1,51 @@
+/**
+ * AUTOMATIC HASH-BASED SCHEMA MIGRATIONS
+ *
+ * This module implements automatic schema versioning using hash-based change detection.
+ *
+ * ⚠️  CRITICAL DISTINCTION:
+ * - STATE TABLES (safe to modify): Changes trigger rematerialization from eventlog
+ * - EVENTLOG TABLES (NEVER modify): Changes cause data loss - need manual versioning!
+ *
+ * How it works:
+ * 1. Each table's schema is hashed using SqliteAst.hash()
+ * 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:
+ *    - State tables: Recreated and repopulated from eventlog (safe, no data loss)
+ *    - Eventlog tables: Uses 'create-if-not-exists' (UNSAFE - causes data loss!)
+ *
+ * State Table Changes (SAFE):
+ * - User-defined tables are rebuilt from eventlog
+ * - System tables (schemaMetaTable, etc.) are recreated
+ * - Data preserved through rematerializeFromEventlog()
+ *
+ * Eventlog Table Changes (UNSAFE):
+ * - eventlogMetaTable, syncStatusTable changes cause "soft reset"
+ * - Old table becomes inaccessible (but remains in DB)
+ * - No automatic migration - effectively data loss
+ * - TODO: Implement proper EVENTLOG_PERSISTENCE_FORMAT_VERSION system
+ *
+ * See system-tables/state-tables.ts and system-tables/eventlog-tables.ts for detailed documentation on each table type.
+ */
+
 import { memoizeByStringifyArgs } from '@livestore/utils'
 import { Effect } from '@livestore/utils/effect'
 
 import type { SqliteDb } from '../adapter-types.ts'
 import type { MigrationsReport, MigrationsReportEntry } from '../defs.ts'
-import type { UnexpectedError } from '../errors.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 type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables.ts'
+import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables/state-tables.ts'
 import {
   isStateSystemTable,
   SCHEMA_EVENT_DEFS_META_TABLE,
   SCHEMA_META_TABLE,
   schemaEventDefsMetaTable,
   stateSystemTables,
-} from '../schema/state/sqlite/system-tables.ts'
+} from '../schema/state/sqlite/system-tables/state-tables.ts'
 import { sql } from '../util.ts'
 import type { SchemaManager } from './common.ts'
 import { dbExecute, dbSelect } from './common.ts'
@@ -56,7 +87,7 @@ export const migrateDb = ({
   db: SqliteDb
   schema: LiveStoreSchema
   onProgress?: (opts: { done: number; total: number }) => Effect.Effect<void>
-}): Effect.Effect<MigrationsReport, UnexpectedError> =>
+}): Effect.Effect<MigrationsReport, UnknownError> =>
   Effect.gen(function* () {
     for (const tableDef of stateSystemTables) {
       yield* migrateTable({
@@ -137,10 +168,10 @@ export const migrateTable = ({
 
     if (behaviour === 'drop-and-recreate') {
       // TODO need to possibly handle cascading deletes due to foreign keys
-      dbExecute(db, sql`drop table if exists '${tableName}'`)
-      dbExecute(db, sql`create table if not exists '${tableName}' (${columnSpec}) strict`)
+      dbExecute(db, sql`drop table if exists "${tableName}"`)
+      dbExecute(db, sql`create table if not exists "${tableName}" (${columnSpec}) strict`)
     } else if (behaviour === 'create-if-not-exists') {
-      dbExecute(db, sql`create table if not exists '${tableName}' (${columnSpec}) strict`)
+      dbExecute(db, sql`create table if not exists "${tableName}" (${columnSpec}) strict`)
     }
 
     for (const index of tableAst.indexes) {
@@ -169,6 +200,8 @@ export const migrateTable = ({
   )
 
 const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) => {
-  const uniqueStr = index.unique ? 'UNIQUE' : ''
-  return sql`create ${uniqueStr} index if not exists '${index.name}' on '${tableName}' (${index.columns.map((col) => `'${col}'`).join(', ')})`
+  const uniqueStr = index.unique === true ? 'UNIQUE' : ''
+  return sql`create ${uniqueStr} index if not exists "${index.name}" on "${tableName}" (${index.columns
+    .map((col) => `"${col}"`)
+    .join(', ')})`
 }

package/src/schema-management/validate-schema.ts

@@ -1,7 +1,7 @@
 import { Effect, Schema } from '@livestore/utils/effect'
 
-import { UnexpectedError } from '../adapter-types.ts'
-import type { EventDef } from '../schema/EventDef.ts'
+import { UnknownError } from '../adapter-types.ts'
+import type { EventDef } from '../schema/EventDef/mod.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import type { EventDefInfo, SchemaManager } from './common.ts'
 
@@ -15,7 +15,7 @@ export const validateSchema = (schema: LiveStoreSchema, schemaManager: SchemaMan
     )
 
     if (missingEventDefs.length > 0) {
-      return yield* new UnexpectedError({
+      return yield* new UnknownError({
         cause: `Missing mutation definitions: ${missingEventDefs.map((info) => info.eventName).join(', ')}`,
       })
     }

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

@@ -23,7 +23,7 @@ export const findManyRows = <TColumns extends SqliteDsl.Columns>({
 }): [string, BindValues] => {
   const whereSql = buildWhereSql({ where })
   const whereModifier = whereSql === '' ? '' : `WHERE ${whereSql}`
-  const limitModifier = limit ? `LIMIT ${limit}` : ''
+  const limitModifier = limit !== undefined ? `LIMIT ${limit}` : ''
 
   const whereBindValues = makeBindValues({ columns, values: where, variablePrefix: 'where_', skipNil: true })
 
@@ -80,7 +80,7 @@ export const insertRowPrepared = <TColumns extends SqliteDsl.Columns>({
   const keysStr = keys.join(', ')
   const valuesStr = keys.map((key) => `$${key}`).join(', ')
 
-  return sql`INSERT ${options.orReplace ? 'OR REPLACE ' : ''}INTO ${tableName} (${keysStr}) VALUES (${valuesStr})`
+  return sql`INSERT ${options.orReplace === true ? 'OR REPLACE ' : ''}INTO ${tableName} (${keysStr}) VALUES (${valuesStr})`
 }
 
 export const insertRows = <TColumns extends SqliteDsl.Columns>({
@@ -134,7 +134,7 @@ export const insertOrIgnoreRow = <TColumns extends SqliteDsl.Columns>({
     .join(', ')
 
   const bindValues = makeBindValues({ columns, values })
-  const returningStmt = returnRow ? 'RETURNING *' : ''
+  const returningStmt = returnRow === true ? 'RETURNING *' : ''
 
   return [sql`INSERT OR IGNORE INTO ${tableName} (${keysStr}) VALUES (${valuesStr}) ${returningStmt}`, bindValues]
 }
@@ -247,7 +247,15 @@ export const createTable = ({
     .map(([columnName, _]) => columnName)
   const columnDefStrs = Object.entries(table.columns).map(([columnName, columnDef]) => {
     const nullModifier = columnDef.nullable === true ? '' : 'NOT NULL'
-    const defaultModifier = columnDef.default._tag === 'None' ? '' : `DEFAULT ${columnDef.default.value}`
+    const defaultModifier = (() => {
+      if (columnDef.default._tag === 'None') return ''
+      const defaultValue = columnDef.default.value
+      if (typeof defaultValue === 'function') return ''
+      if (defaultValue !== undefined && typeof defaultValue === 'object' && 'sql' in defaultValue) {
+        return `DEFAULT ${defaultValue.sql}`
+      }
+      return `DEFAULT ${defaultValue}`
+    })()
     return sql`${columnName} ${columnDef.columnType} ${nullModifier} ${defaultModifier}`
   })
 
@@ -293,7 +301,7 @@ Error: ${parseErrorStr}
 Value:`,
             value,
           )
-          // biome-ignore lint/suspicious/noDebugger: debug
+          // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for SQL decode errors
           debugger
           throw res.left
         } else {
@@ -341,7 +349,11 @@ const buildWhereSql = <TColumns extends SqliteDsl.Columns>({
   const getWhereOp = (columnName: string, value: ClientTypes.WhereValueForDecoded<any>) => {
     if (value === null) {
       return `IS NULL`
-    } else if (typeof value === 'object' && typeof value.op === 'string' && ClientTypes.isValidWhereOp(value.op)) {
+    } else if (
+      typeof value === 'object' &&
+      typeof value.op === 'string' &&
+      ClientTypes.isValidWhereOp(value.op) === true
+    ) {
       return `${value.op} $where_${columnName}`
     } else if (typeof value === 'object' && typeof value.op === 'string' && value.op === 'in') {
       return `in (${value.val.map((_: any, i: number) => `$where_${columnName}_${i}`).join(', ')})`

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

@@ -1,4 +1,5 @@
 import { omitUndefineds } from '@livestore/utils'
+
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 import type { BindValues } from './sql-queries.ts'
 import * as SqlQueries from './sql-queries.ts'

package/src/sqlite-db-helper.ts

@@ -14,7 +14,7 @@ export const makeExecute = (
   return (...args: any[]) => {
     const [queryStrOrQueryBuilder, bindValuesOrOptions, maybeOptions] = args
 
-    if (isQueryBuilder(queryStrOrQueryBuilder)) {
+    if (isQueryBuilder(queryStrOrQueryBuilder) === true) {
       const { query, bindValues } = queryStrOrQueryBuilder.asSql()
       return execute(query, bindValues as unknown as PreparedBindValues, bindValuesOrOptions)
     } else {
@@ -29,7 +29,7 @@ export const makeSelect = <T>(
   return (...args: any[]) => {
     const [queryStrOrQueryBuilder, maybeBindValues] = args
 
-    if (isQueryBuilder(queryStrOrQueryBuilder)) {
+    if (isQueryBuilder(queryStrOrQueryBuilder) === true) {
       const { query, bindValues } = queryStrOrQueryBuilder.asSql()
       const resultSchema = getResultSchema(queryStrOrQueryBuilder)
       const results = select(query, bindValues as unknown as PreparedBindValues)
@@ -44,7 +44,7 @@ export const validateSnapshot = (snapshot: Uint8Array) => {
   const headerBytes = new TextDecoder().decode(snapshot.slice(0, 16))
   const hasValidHeader = headerBytes.startsWith('SQLite format 3')
 
-  if (!hasValidHeader) {
+  if (hasValidHeader === false) {
     throw new SqliteError({
       cause: 'Invalid SQLite header',
       note: `Expected header to start with 'SQLite format 3', but got: ${headerBytes}`,

package/src/sqlite-types.ts

@@ -1,5 +1,6 @@
 import { type Effect, Schema } from '@livestore/utils/effect'
-import type { SqliteError, UnexpectedError } from './errors.ts'
+
+import type { SqliteError, UnknownError } from './errors.ts'
 import type { EventSequenceNumber } from './schema/mod.ts'
 import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import type { PreparedBindValues } from './util.ts'
@@ -17,12 +18,12 @@ export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
   prepare(queryStr: string): PreparedStatement
   execute(
     queryStr: string,
-    bindValues?: PreparedBindValues | undefined,
+    bindValues?: PreparedBindValues  ,
     options?: { onRowsChanged?: (rowsChanged: number) => void },
   ): void
   execute(queryBuilder: QueryBuilder.Any, options?: { onRowsChanged?: (rowsChanged: number) => void }): void
 
-  select<T>(queryStr: string, bindValues?: PreparedBindValues | undefined): ReadonlyArray<T>
+  select<T>(queryStr: string, bindValues?: PreparedBindValues  ): ReadonlyArray<T>
   select<T>(queryBuilder: QueryBuilder<T, any, any>): T
 
   export(): Uint8Array<ArrayBuffer>
@@ -33,7 +34,7 @@ export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
   makeChangeset: (data: Uint8Array<ArrayBuffer>) => SqliteDbChangeset
 }
 
-export type SqliteDebugInfo = { head: EventSequenceNumber.EventSequenceNumber }
+export type SqliteDebugInfo = { head: EventSequenceNumber.Client.Composite }
 
 // TODO refactor this helper type. It's quite cumbersome to use and should be revisited.
 export type MakeSqliteDb<
@@ -46,7 +47,7 @@ export type MakeSqliteDb<
   TMetadata extends TMetadata_ & { _tag: TInput['_tag'] } = TMetadata_ & { _tag: TInput['_tag'] },
 >(
   input: TInput,
-) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnexpectedError, R>
+) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnknownError, R>
 
 export interface PreparedStatement {
   execute(bindValues: PreparedBindValues | undefined, options?: { onRowsChanged?: (rowsChanged: number) => void }): void