@livestore/common 0.3.2-dev.9 → 0.4.0-dev.0

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

@@ -1,6 +1,7 @@
-import type { Nullable } from '@livestore/utils'
-import type { Schema, Types } from '@livestore/utils/effect'
+import { type Nullable, shouldNeverHappen, type Writeable } from '@livestore/utils'
+import { Option, Schema, SchemaAST, type Types } from '@livestore/utils/effect'
 
+import { AutoIncrement, ColumnType, Default, PrimaryKeyId, Unique } from './column-annotations.ts'
 import { SqliteDsl } from './db-schema/mod.ts'
 import type { QueryBuilder } from './query-builder/mod.ts'
 import { makeQueryBuilder, QueryBuilderAstSymbol, QueryBuilderTypeId } from './query-builder/mod.ts'
@@ -17,6 +18,7 @@ export const TableDefInternalsSymbol = Symbol('TableDefInternals')
 export type TableDefInternalsSymbol = typeof TableDefInternalsSymbol
 
 export type TableDefBase<
+  // TODO replace SqliteDef type param with Effect Schema (see below)
   TSqliteDef extends DefaultSqliteTableDef = DefaultSqliteTableDefConstrained,
   TOptions extends TableOptions = TableOptions,
 > = {
@@ -28,10 +30,14 @@ export type TableDefBase<
 }
 
 export type TableDef<
+  // TODO replace SqliteDef type param with Effect Schema
+  // We can only do this with Effect Schema v4 once the default values are tracked on the type level
+  // 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'],
@@ -66,28 +72,192 @@ export type TableOptions = {
   readonly isClientDocumentTable: boolean
 }
 
-export const table = <
+/**
+ * Creates a SQLite table definition from columns or an Effect Schema.
+ *
+ * This function supports two main ways to define a table:
+ * 1. Using explicit column definitions
+ * 2. Using an Effect Schema (either the `name` property needs to be provided or the schema needs to have a title/identifier)
+ *
+ * ```ts
+ * // Using explicit columns
+ * const usersTable = State.SQLite.table({
+ *   name: 'users',
+ *   columns: {
+ *     id: State.SQLite.text({ primaryKey: true }),
+ *     name: State.SQLite.text({ nullable: false }),
+ *     email: State.SQLite.text({ nullable: false }),
+ *     age: State.SQLite.integer({ nullable: true }),
+ *   },
+ * })
+ * ```
+ *
+ * ```ts
+ * // Using Effect Schema with annotations
+ * import { Schema } from '@livestore/utils/effect'
+ *
+ * const UserSchema = Schema.Struct({
+ *   id: Schema.Int.pipe(State.SQLite.withPrimaryKey).pipe(State.SQLite.withAutoIncrement),
+ *   email: Schema.String.pipe(State.SQLite.withUnique),
+ *   name: Schema.String,
+ *   active: Schema.Boolean.pipe(State.SQLite.withDefault(true)),
+ *   createdAt: Schema.optional(Schema.Date),
+ * })
+ *
+ * // Option 1: With explicit name
+ * const usersTable = State.SQLite.table({
+ *   name: 'users',
+ *   schema: UserSchema,
+ * })
+ *
+ * // Option 2: With name from schema annotation (title or identifier)
+ * const AnnotatedUserSchema = UserSchema.annotations({ title: 'users' })
+ * const usersTable2 = State.SQLite.table({
+ *   schema: AnnotatedUserSchema,
+ * })
+ * ```
+ *
+ * ```ts
+ * // Adding indexes
+ * const PostSchema = Schema.Struct({
+ *   id: Schema.String.pipe(State.SQLite.withPrimaryKey),
+ *   title: Schema.String,
+ *   authorId: Schema.String,
+ *   createdAt: Schema.Date,
+ * }).annotations({ identifier: 'posts' })
+ *
+ * const postsTable = State.SQLite.table({
+ *   schema: PostSchema,
+ *   indexes: [
+ *     { name: 'idx_posts_author', columns: ['authorId'] },
+ *     { name: 'idx_posts_created', columns: ['createdAt'], isUnique: false },
+ *   ],
+ * })
+ * ```
+ *
+ * @remarks
+ * - Primary key columns are automatically non-nullable
+ * - Columns with `State.SQLite.withUnique` annotation automatically get unique indexes
+ * - The `State.SQLite.withAutoIncrement` annotation only works with integer primary keys
+ * - Default values can be literal values or SQL expressions
+ * - When using Effect Schema without explicit name, the schema must have a title or identifier annotation
+ */
+// Overload 1: With columns
+// TODO drop support for `column` when Effect Schema v4 is released
+export function table<
   TName extends string,
-  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
+  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition.Any,
   const TOptionsInput extends TableOptionsInput = TableOptionsInput,
 >(
   args: {
     name: TName
     columns: TColumns
   } & Partial<TOptionsInput>,
-): TableDef<SqliteTableDefForInput<TName, TColumns>, WithDefaults<TColumns>> => {
-  const { name, columns: columnOrColumns, ...options } = args
-  const tablePath = name
+): TableDef<SqliteTableDefForInput<TName, TColumns>, WithDefaults<TColumns>>
+
+// Overload 2: With schema and explicit name
+export function table<
+  TName extends string,
+  TSchema extends Schema.Schema.AnyNoContext,
+  const TOptionsInput extends TableOptionsInput = TableOptionsInput,
+>(
+  args: {
+    name: TName
+    schema: TSchema
+  } & Partial<TOptionsInput>,
+): TableDef<
+  SqliteTableDefForSchemaInput<TName, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>,
+  TableOptions
+>
+
+// Overload 3: With schema and no name (uses schema annotations)
+export function table<
+  TSchema extends Schema.Schema.AnyNoContext,
+  const TOptionsInput extends TableOptionsInput = TableOptionsInput,
+>(
+  args: {
+    schema: TSchema
+  } & Partial<TOptionsInput>,
+): TableDef<
+  SqliteTableDefForSchemaInput<string, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>,
+  TableOptions
+>
+
+// Implementation
+export function table<
+  TName extends string,
+  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition.Any,
+  const TOptionsInput extends TableOptionsInput = TableOptionsInput,
+>(
+  args: (
+    | {
+        name: TName
+        columns: TColumns
+      }
+    | {
+        name: TName
+        schema: Schema.Schema.AnyNoContext
+      }
+    | {
+        schema: Schema.Schema.AnyNoContext
+      }
+  ) &
+    Partial<TOptionsInput>,
+): TableDef<any, any> {
+  const { ...options } = args
+
+  let tableName: string
+  let columns: SqliteDsl.Columns
+  let additionalIndexes: SqliteDsl.Index[] = []
+
+  if ('columns' in args) {
+    tableName = args.name
+    const columnOrColumns = args.columns
+    columns = (
+      SqliteDsl.isColumnDefinition(columnOrColumns) ? { value: columnOrColumns } : columnOrColumns
+    ) as SqliteDsl.Columns
+    additionalIndexes = []
+  } else if ('schema' in args) {
+    const result = schemaFieldsToColumns(SchemaAST.getPropertySignatures(args.schema.ast))
+    columns = result.columns
+
+    // We'll set tableName first, then use it for index names
+    let tempTableName: string
+
+    // If name is provided, use it; otherwise extract from schema annotations
+    if ('name' in args) {
+      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',
+          ),
+        ),
+      )
+    }
+
+    tableName = tempTableName
+
+    // Create unique indexes for columns with unique annotation
+    additionalIndexes = (result.uniqueColumns || []).map((columnName) => ({
+      name: `idx_${tableName}_${columnName}_unique`,
+      columns: [columnName],
+      isUnique: true,
+    }))
+  } else {
+    return shouldNeverHappen('Either `columns` or `schema` must be provided when calling `table()`')
+  }
 
   const options_: TableOptions = {
     isClientDocumentTable: false,
   }
 
-  const columns = (
-    SqliteDsl.isColumnDefinition(columnOrColumns) ? { value: columnOrColumns } : columnOrColumns
-  ) as SqliteDsl.Columns
-
-  const sqliteDef = SqliteDsl.table(tablePath, columns, options?.indexes ?? [])
+  // Combine user-provided indexes with unique column indexes
+  const allIndexes = [...(options?.indexes ?? []), ...additionalIndexes]
+  const sqliteDef = SqliteDsl.table(tableName, columns, allIndexes)
 
   const rowSchema = SqliteDsl.structSchemaForTable(sqliteDef)
   const insertSchema = SqliteDsl.insertStructSchemaForTable(sqliteDef)
@@ -179,19 +349,305 @@ export namespace FromColumns {
 
 export type SqliteTableDefForInput<
   TName extends string,
-  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
+  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition.Any,
 > = SqliteDsl.TableDefinition<TName, PrettifyFlat<ToColumns<TColumns>>>
 
-type WithDefaults<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>> = {
+export type SqliteTableDefForSchemaInput<
+  TName extends string,
+  TType,
+  TEncoded,
+  _TSchema = any,
+> = TableDefInput.ForSchema<TName, TType, TEncoded, _TSchema>
+
+export type WithDefaults<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition.Any> = {
   isClientDocumentTable: false
   requiredInsertColumnNames: SqliteDsl.FromColumns.RequiredInsertColumnNames<ToColumns<TColumns>>
 }
 
 export type PrettifyFlat<T> = T extends infer U ? { [K in keyof U]: U[K] } : never
 
-type ToColumns<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>> =
+export type ToColumns<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition.Any> =
   TColumns extends SqliteDsl.Columns
     ? TColumns
-    : TColumns extends SqliteDsl.ColumnDefinition<any, any>
+    : TColumns extends SqliteDsl.ColumnDefinition.Any
       ? { value: TColumns }
       : never
+
+export declare namespace SchemaToColumns {
+  // Type helper to create column definition with proper schema
+  export type ColumnDefForType<TEncoded, TType> = SqliteDsl.ColumnDefinition<TEncoded, TType>
+
+  // Create columns type from schema Type and Encoded
+  export type FromTypes<TType, TEncoded> = TType extends Record<string, any>
+    ? TEncoded extends Record<string, any>
+      ? {
+          [K in keyof TType & keyof TEncoded]: ColumnDefForType<TEncoded[K], TType[K]>
+        }
+      : SqliteDsl.Columns
+    : SqliteDsl.Columns
+}
+
+export declare namespace TableDefInput {
+  export type ForColumns<
+    TName extends string,
+    TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition.Any,
+  > = SqliteDsl.TableDefinition<TName, PrettifyFlat<ToColumns<TColumns>>>
+
+  export type ForSchema<TName extends string, TType, TEncoded, _TSchema = any> = SqliteDsl.TableDefinition<
+    TName,
+    SchemaToColumns.FromTypes<TType, TEncoded>
+  >
+}
+
+/**
+ * Checks if a property signature has a specific annotation, checking both
+ * the property signature itself and its type AST.
+ */
+const hasPropertyAnnotation = <T>(
+  propertySignature: SchemaAST.PropertySignature,
+  annotationId: symbol,
+): Option.Option<T> => {
+  // When using Schema.optional(Schema.String).pipe(withPrimaryKey) in a struct,
+  // the annotation ends up on a PropertySignatureDeclaration, not the Union type
+  // Check if this is a PropertySignatureDeclaration with annotations
+  if ('annotations' in propertySignature && propertySignature.annotations) {
+    const annotation = SchemaAST.getAnnotation<T>(annotationId)(propertySignature as any)
+    if (Option.isSome(annotation)) {
+      return annotation
+    }
+  }
+
+  // Otherwise check the type AST
+  return SchemaAST.getAnnotation<T>(annotationId)(propertySignature.type)
+}
+
+/**
+ * Maps schema property signatures to SQLite column definitions.
+ * Returns both columns and unique column names for index creation.
+ */
+const schemaFieldsToColumns = (
+  propertySignatures: ReadonlyArray<SchemaAST.PropertySignature>,
+): { columns: SqliteDsl.Columns; uniqueColumns: string[] } => {
+  const columns: SqliteDsl.Columns = {}
+  const uniqueColumns: string[] = []
+
+  for (const prop of propertySignatures) {
+    if (typeof prop.name === 'string') {
+      // Create a schema from the AST
+      const fieldSchema = Schema.make(prop.type)
+      // Check if property has primary key annotation
+      const hasPrimaryKey = hasPropertyAnnotation<boolean>(prop, PrimaryKeyId).pipe(Option.getOrElse(() => false))
+      // Check if property has unique annotation
+      const hasUnique = hasPropertyAnnotation<boolean>(prop, Unique).pipe(Option.getOrElse(() => false))
+
+      columns[prop.name] = schemaFieldToColumn(fieldSchema, prop, hasPrimaryKey)
+
+      if (hasUnique) {
+        uniqueColumns.push(prop.name)
+      }
+    }
+  }
+
+  return { columns, uniqueColumns }
+}
+
+/**
+ * Converts a schema field and its property signature to a SQLite column definition.
+ */
+const schemaFieldToColumn = (
+  fieldSchema: Schema.Schema.AnyNoContext,
+  propertySignature: SchemaAST.PropertySignature,
+  forceHasPrimaryKey?: boolean,
+): SqliteDsl.ColumnDefinition.Any => {
+  // Determine column type based on schema type
+  const columnDef = getColumnDefForSchema(fieldSchema, propertySignature)
+
+  // Create a new object with appropriate properties
+  const result: Writeable<SqliteDsl.ColumnDefinition.Any> = {
+    columnType: columnDef.columnType,
+    schema: columnDef.schema,
+    default: columnDef.default,
+    nullable: columnDef.nullable,
+    primaryKey: columnDef.primaryKey,
+    autoIncrement: columnDef.autoIncrement,
+  }
+
+  // Set primaryKey property explicitly
+  if (forceHasPrimaryKey || columnDef.primaryKey) {
+    result.primaryKey = true
+  } else {
+    result.primaryKey = false
+  }
+
+  // Check for invalid primary key + nullable combination
+  if (result.primaryKey && (propertySignature.isOptional || columnDef.nullable)) {
+    return shouldNeverHappen(
+      `Primary key columns cannot be nullable. Found nullable primary key for column. ` +
+        `Either remove the primary key annotation or use a non-nullable schema.`,
+    )
+  }
+
+  // Set nullable property explicitly
+  if (propertySignature.isOptional) {
+    result.nullable = true
+  } else if (columnDef.nullable) {
+    result.nullable = true
+  } else {
+    result.nullable = false
+  }
+
+  // Only add autoIncrement if it's true
+  if (columnDef.autoIncrement) {
+    result.autoIncrement = true
+  }
+
+  return result as SqliteDsl.ColumnDefinition.Any
+}
+
+/**
+ * Maps a schema to a SQLite column definition, respecting column annotations.
+ */
+export const getColumnDefForSchema = (
+  schema: Schema.Schema.AnyNoContext,
+  propertySignature?: SchemaAST.PropertySignature,
+): SqliteDsl.ColumnDefinition.Any => {
+  const ast = schema.ast
+
+  // Check for annotations
+  const hasPrimaryKey = propertySignature
+    ? hasPropertyAnnotation<boolean>(propertySignature, PrimaryKeyId).pipe(Option.getOrElse(() => false))
+    : SchemaAST.getAnnotation<boolean>(PrimaryKeyId)(ast).pipe(Option.getOrElse(() => false))
+
+  const hasAutoIncrement = propertySignature
+    ? hasPropertyAnnotation<boolean>(propertySignature, AutoIncrement).pipe(Option.getOrElse(() => false))
+    : SchemaAST.getAnnotation<boolean>(AutoIncrement)(ast).pipe(Option.getOrElse(() => false))
+
+  const defaultValue = propertySignature
+    ? hasPropertyAnnotation<unknown>(propertySignature, Default)
+    : SchemaAST.getAnnotation<unknown>(Default)(ast)
+
+  /** Adds annotations to a column definition if they are present. */
+  const withAnnotationsIfNeeded = (columnDef: SqliteDsl.ColumnDefinition.Any): SqliteDsl.ColumnDefinition.Any => {
+    const result = { ...columnDef }
+
+    if (hasPrimaryKey) {
+      result.primaryKey = true
+    }
+
+    if (hasAutoIncrement) {
+      result.autoIncrement = true
+    }
+
+    if (Option.isSome(defaultValue)) {
+      result.default = Option.some(defaultValue.value)
+    }
+
+    return result
+  }
+
+  // Check for custom column type annotation
+  const columnTypeAnnotation = SchemaAST.getAnnotation<SqliteDsl.FieldColumnType>(ColumnType)(ast)
+  if (Option.isSome(columnTypeAnnotation)) {
+    const columnType = columnTypeAnnotation.value
+    let columnDef: SqliteDsl.ColumnDefinition.Any
+    switch (columnType) {
+      case 'text':
+        columnDef = SqliteDsl.text()
+        break
+      case 'integer':
+        columnDef = SqliteDsl.integer()
+        break
+      case 'real':
+        columnDef = SqliteDsl.real()
+        break
+      case 'blob':
+        columnDef = SqliteDsl.blob()
+        break
+      default:
+        return shouldNeverHappen(`Unsupported column type annotation: ${columnType}`)
+    }
+
+    return withAnnotationsIfNeeded(columnDef)
+  }
+
+  // Check for refinements (e.g., Schema.Int)
+  if (SchemaAST.isRefinement(ast)) {
+    // Check if this is specifically Schema.Int by looking at the identifier annotation
+    const identifier = SchemaAST.getIdentifierAnnotation(ast).pipe(Option.getOrElse(() => ''))
+    if (identifier === 'Int') {
+      return withAnnotationsIfNeeded(SqliteDsl.integer())
+    }
+    // For other refinements, check the underlying type
+    return getColumnDefForSchema(Schema.make(ast.from), propertySignature)
+  }
+
+  // Check for string types
+  if (SchemaAST.isStringKeyword(ast)) {
+    return withAnnotationsIfNeeded(SqliteDsl.text())
+  }
+
+  // Check for number types
+  if (SchemaAST.isNumberKeyword(ast)) {
+    return withAnnotationsIfNeeded(SqliteDsl.real())
+  }
+
+  // Check for boolean types
+  if (SchemaAST.isBooleanKeyword(ast)) {
+    return withAnnotationsIfNeeded(SqliteDsl.boolean())
+  }
+
+  // Check for unions (like optional or nullable)
+  if (SchemaAST.isUnion(ast)) {
+    // Check if this union contains null or undefined (making it nullable/optional)
+    let hasNull = false
+    let hasUndefined = false
+    let nonNullableType: SchemaAST.AST | undefined
+
+    for (const type of ast.types) {
+      if (SchemaAST.isUndefinedKeyword(type)) {
+        hasUndefined = true
+      } else if (SchemaAST.isLiteral(type) && type.literal === null) {
+        hasNull = true
+      } else {
+        nonNullableType = type
+      }
+    }
+
+    // If we found a non-nullable type, use it for the column definition
+    if (nonNullableType) {
+      const innerSchema = Schema.make(nonNullableType)
+      const innerColumnDef = getColumnDefForSchema(innerSchema, propertySignature)
+
+      // If the union contains null or undefined, mark as nullable
+      if (hasNull || hasUndefined) {
+        return withAnnotationsIfNeeded({
+          ...innerColumnDef,
+          nullable: true,
+        })
+      }
+
+      return withAnnotationsIfNeeded(innerColumnDef)
+    }
+  }
+
+  // Check for Date types
+  if (SchemaAST.isTransformation(ast)) {
+    // Try to map the transformation's target type
+    return getColumnDefForSchema(Schema.make(ast.to), propertySignature)
+  }
+
+  // Check for literal types
+  if (SchemaAST.isLiteral(ast)) {
+    const value = ast.literal
+    if (typeof value === 'string') {
+      return withAnnotationsIfNeeded(SqliteDsl.text())
+    } else if (typeof value === 'number') {
+      return withAnnotationsIfNeeded(SqliteDsl.real())
+    } else if (typeof value === 'boolean') {
+      return withAnnotationsIfNeeded(SqliteDsl.boolean())
+    }
+  }
+
+  // Default to JSON column for complex types
+  return withAnnotationsIfNeeded(SqliteDsl.json({ schema }))
+}

package/src/schema-management/common.ts

@@ -1,4 +1,4 @@
-import type { SqliteDb } from '../adapter-types.ts'
+import { type SqliteDb, SqliteError } from '../adapter-types.ts'
 import type { ParamsObject } from '../util.ts'
 import { prepareBindValues } from '../util.ts'
 
@@ -15,9 +15,16 @@ export const dbExecute = (db: SqliteDb, queryStr: string, bindValues?: ParamsObj
 
   const preparedBindValues = bindValues ? prepareBindValues(bindValues, queryStr) : undefined
 
-  stmt.execute(preparedBindValues)
+  try {
+    stmt.execute(preparedBindValues)
 
-  stmt.finalize()
+    stmt.finalize()
+  } catch (cause) {
+    throw new SqliteError({
+      cause,
+      query: { sql: queryStr, bindValues: preparedBindValues ?? {} },
+    })
+  }
 }
 
 export const dbSelect = <T>(db: SqliteDb, queryStr: string, bindValues?: ParamsObject) => {

package/src/schema-management/migrations.ts

@@ -1,11 +1,12 @@
 import { memoizeByStringifyArgs } from '@livestore/utils'
-import { Effect, Schema as EffectSchema } from '@livestore/utils/effect'
+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 { LiveStoreSchema } from '../schema/mod.ts'
-import { SqliteAst, SqliteDsl } from '../schema/state/sqlite/db-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 {
   isStateSystemTable,
@@ -169,35 +170,5 @@ 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.join(', ')})`
-}
-
-export const makeColumnSpec = (tableAst: SqliteAst.Table) => {
-  const primaryKeys = tableAst.columns.filter((_) => _.primaryKey).map((_) => `'${_.name}'`)
-  const columnDefStrs = tableAst.columns.map(toSqliteColumnSpec)
-  if (primaryKeys.length > 0) {
-    columnDefStrs.push(`PRIMARY KEY (${primaryKeys.join(', ')})`)
-  }
-
-  return columnDefStrs.join(', ')
-}
-
-/** NOTE primary keys are applied on a table level not on a column level to account for multi-column primary keys */
-const toSqliteColumnSpec = (column: SqliteAst.Column) => {
-  const columnTypeStr = column.type._tag
-  const nullableStr = column.nullable === false ? 'not null' : ''
-  const defaultValueStr = (() => {
-    if (column.default._tag === 'None') return ''
-
-    if (column.default.value === null) return 'default null'
-    if (SqliteDsl.isSqlDefaultValue(column.default.value)) return `default ${column.default.value.sql}`
-
-    const encodeValue = EffectSchema.encodeSync(column.schema)
-    const encodedDefaultValue = encodeValue(column.default.value)
-
-    if (columnTypeStr === 'text') return `default '${encodedDefaultValue}'`
-    return `default ${encodedDefaultValue}`
-  })()
-
-  return `'${column.name}' ${columnTypeStr} ${nullableStr} ${defaultValueStr}`
+  return sql`create ${uniqueStr} index if not exists '${index.name}' on '${tableName}' (${index.columns.map((col) => `'${col}'`).join(', ')})`
 }

package/src/sqlite-db-helper.ts

@@ -1,6 +1,6 @@
 import { Schema } from '@livestore/utils/effect'
 
-import type { SqliteDb } from './adapter-types.ts'
+import { type SqliteDb, SqliteError } from './adapter-types.ts'
 import { getResultSchema, isQueryBuilder } from './schema/state/sqlite/query-builder/mod.ts'
 import type { PreparedBindValues } from './util.ts'
 
@@ -39,3 +39,21 @@ export const makeSelect = <T>(
     }
   }
 }
+
+export const validateSnapshot = (snapshot: Uint8Array) => {
+  const headerBytes = new TextDecoder().decode(snapshot.slice(0, 16))
+  const hasValidHeader = headerBytes.startsWith('SQLite format 3')
+
+  if (!hasValidHeader) {
+    throw new SqliteError({
+      cause: 'Invalid SQLite header',
+      note: `Expected header to start with 'SQLite format 3', but got: ${headerBytes}`,
+    })
+  }
+}
+
+export const makeExport = (exportFn: () => Uint8Array<ArrayBuffer>) => () => {
+  const snapshot = exportFn()
+  validateSnapshot(snapshot)
+  return snapshot
+}

package/src/sqlite-types.ts

@@ -25,12 +25,12 @@ export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
   select<T>(queryStr: string, bindValues?: PreparedBindValues | undefined): ReadonlyArray<T>
   select<T>(queryBuilder: QueryBuilder<T, any, any>): T
 
-  export(): Uint8Array
-  import: (data: Uint8Array | SqliteDb<TReq>) => void
+  export(): Uint8Array<ArrayBuffer>
+  import: (data: Uint8Array<ArrayBuffer> | SqliteDb<TReq>) => void
   close(): void
   destroy(): void
   session(): SqliteDbSession
-  makeChangeset: (data: Uint8Array) => SqliteDbChangeset
+  makeChangeset: (data: Uint8Array<ArrayBuffer>) => SqliteDbChangeset
 }
 
 export type SqliteDebugInfo = { head: EventSequenceNumber.EventSequenceNumber }
@@ -56,7 +56,7 @@ export interface PreparedStatement {
 }
 
 export type SqliteDbSession = {
-  changeset: () => Uint8Array | undefined
+  changeset: () => Uint8Array<ArrayBuffer> | undefined
   finish: () => void
 }