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

package/src/schema/state/sqlite/db-schema/dsl/field-defs.ts

@@ -9,9 +9,15 @@ export type ColumnDefinition<TEncoded, TDecoded> = {
   readonly nullable: boolean
   /** @default false */
   readonly primaryKey: boolean
+  /** @default false */
+  readonly autoIncrement: boolean
+}
+
+export declare namespace ColumnDefinition {
+  export type Any = ColumnDefinition<any, any>
 }
 
-export const isColumnDefinition = (value: unknown): value is ColumnDefinition<any, any> => {
+export const isColumnDefinition = (value: unknown): value is ColumnDefinition.Any => {
   const validColumnTypes = ['text', 'integer', 'real', 'blob'] as const
   return (
     typeof value === 'object' &&
@@ -26,6 +32,7 @@ export type ColumnDefinitionInput = {
   readonly default?: unknown | NoDefault
   readonly nullable?: boolean
   readonly primaryKey?: boolean
+  readonly autoIncrement?: boolean
 }
 
 export const NoDefault = Symbol.for('NoDefault')
@@ -46,6 +53,7 @@ export type ColDefFn<TColumnType extends FieldColumnType> = {
     default: Option.None<never>
     nullable: false
     primaryKey: false
+    autoIncrement: false
   }
   <
     TEncoded extends DefaultEncodedForColumnType<TColumnType>,
@@ -53,11 +61,13 @@ export type ColDefFn<TColumnType extends FieldColumnType> = {
     const TNullable extends boolean = false,
     const TDefault extends TDecoded | SqlDefaultValue | NoDefault | (TNullable extends true ? null : never) = NoDefault,
     const TPrimaryKey extends boolean = false,
+    const TAutoIncrement extends boolean = false,
   >(args: {
     schema?: Schema.Schema<TDecoded, TEncoded>
     default?: TDefault
     nullable?: TNullable
     primaryKey?: TPrimaryKey
+    autoIncrement?: TAutoIncrement
   }): {
     columnType: TColumnType
     schema: TNullable extends true
@@ -66,6 +76,7 @@ export type ColDefFn<TColumnType extends FieldColumnType> = {
     default: TDefault extends NoDefault ? Option.None<never> : Option.Some<NoInfer<TDefault>>
     nullable: NoInfer<TNullable>
     primaryKey: NoInfer<TPrimaryKey>
+    autoIncrement: NoInfer<TAutoIncrement>
   }
 }
 
@@ -83,6 +94,7 @@ const makeColDef =
       default: default_,
       nullable,
       primaryKey: def?.primaryKey ?? false,
+      autoIncrement: def?.autoIncrement ?? false,
     } as any
   }
 
@@ -115,12 +127,14 @@ export type SpecializedColDefFn<
     default: Option.None<never>
     nullable: false
     primaryKey: false
+    autoIncrement: false
   }
   <
     TDecoded = TBaseDecoded,
     const TNullable extends boolean = false,
     const TDefault extends TDecoded | NoDefault | (TNullable extends true ? null : never) = NoDefault,
     const TPrimaryKey extends boolean = false,
+    const TAutoIncrement extends boolean = false,
   >(
     args: TAllowsCustomSchema extends true
       ? {
@@ -128,11 +142,13 @@ export type SpecializedColDefFn<
           default?: TDefault
           nullable?: TNullable
           primaryKey?: TPrimaryKey
+          autoIncrement?: TAutoIncrement
         }
       : {
           default?: TDefault
           nullable?: TNullable
           primaryKey?: TPrimaryKey
+          autoIncrement?: TAutoIncrement
         },
   ): {
     columnType: TColumnType
@@ -142,6 +158,7 @@ export type SpecializedColDefFn<
     default: TDefault extends NoDefault ? Option.None<never> : Option.Some<TDefault>
     nullable: NoInfer<TNullable>
     primaryKey: NoInfer<TPrimaryKey>
+    autoIncrement: NoInfer<TAutoIncrement>
   }
 }
 
@@ -176,6 +193,7 @@ const makeSpecializedColDef: MakeSpecializedColDefFn = (columnType, opts) => (de
     default: default_,
     nullable,
     primaryKey: def?.primaryKey ?? false,
+    autoIncrement: def?.autoIncrement ?? false,
   } as any
 }
 
@@ -214,7 +232,7 @@ export type DefaultEncodedForColumnType<TColumnType extends FieldColumnType> = T
     : TColumnType extends 'real'
       ? number
       : TColumnType extends 'blob'
-        ? Uint8Array
+        ? Uint8Array<ArrayBuffer>
         : never
 
 export const defaultSchemaForColumnType = <TColumnType extends FieldColumnType>(

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

@@ -92,6 +92,7 @@ const columsToAst = (columns: Columns): ReadonlyArray<SqliteAst.Column> => {
       default: column.default as any,
       nullable: column.nullable ?? false,
       primaryKey: column.primaryKey ?? false,
+      autoIncrement: column.autoIncrement ?? false,
       type: { _tag: column.columnType },
     } satisfies SqliteAst.Column
   })

package/src/schema/state/sqlite/mod.ts

@@ -16,6 +16,8 @@ export {
   clientDocument,
   tableIsClientDocumentTable,
 } from './client-document-def.ts'
+export * from './column-annotations.ts'
+export * from './column-spec.ts'
 export * from './table-def.ts'
 
 export const makeState = <TStateInput extends InputState>(inputSchema: TStateInput): InternalState => {

package/src/schema/state/sqlite/query-builder/api.ts

@@ -122,7 +122,7 @@ export type QueryBuilder<
   readonly [QueryBuilderTypeId]: QueryBuilderTypeId
   readonly [QueryBuilderAstSymbol]: QueryBuilderAst
   readonly ResultType: TResult
-  readonly asSql: () => { query: string; bindValues: SqlValue[] }
+  readonly asSql: () => { query: string; bindValues: SqlValue[]; usedTables: Set<string> }
   readonly toString: () => string
 } & Omit<QueryBuilder.ApiFull<TResult, TTableDef, TWithout>, TWithout>
 
@@ -264,14 +264,15 @@ export namespace QueryBuilder {
      * Example:
      * ```ts
      * db.todos.orderBy('createdAt', 'desc')
+     * db.todos.orderBy([{ col: 'createdAt', direction: 'desc' }])
      * ```
      */
     readonly orderBy: {
-      <TColName extends keyof TTableDef['sqliteDef']['columns'] & string>(
+      <const TColName extends keyof TTableDef['sqliteDef']['columns'] & string>(
         col: TColName,
         direction: 'asc' | 'desc',
       ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict'>
-      <TParams extends QueryBuilder.OrderByParams<TTableDef>>(
+      <const TParams extends QueryBuilder.OrderByParams<TTableDef>>(
         params: TParams,
       ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict'>
     }

package/src/schema/state/sqlite/query-builder/astToSql.ts

@@ -65,8 +65,9 @@ const formatReturningClause = (returning?: string[]): string => {
   return ` RETURNING ${returning.join(', ')}`
 }
 
-export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: SqlValue[] } => {
+export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: SqlValue[]; usedTables: Set<string> } => {
   const bindValues: SqlValue[] = []
+  const usedTables = new Set<string>([ast.tableDef.sqliteDef.name])
 
   // INSERT query
   if (ast._tag === 'InsertQuery') {
@@ -134,7 +135,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     query += conflictClause
 
     query += formatReturningClause(ast.returning)
-    return { query, bindValues }
+    return { query, bindValues, usedTables }
   }
 
   // UPDATE query
@@ -145,7 +146,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
       console.warn(
         `UPDATE query requires at least one column to set (for table ${ast.tableDef.sqliteDef.name}). Running no-op query instead to skip this update query.`,
       )
-      return { query: 'SELECT 1', bindValues: [] }
+      return { query: 'SELECT 1', bindValues: [], usedTables }
       // return shouldNeverHappen('UPDATE query requires at least one column to set.')
     }
 
@@ -162,7 +163,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     if (whereClause) query += ` ${whereClause}`
 
     query += formatReturningClause(ast.returning)
-    return { query, bindValues }
+    return { query, bindValues, usedTables }
   }
 
   // DELETE query
@@ -173,7 +174,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     if (whereClause) query += ` ${whereClause}`
 
     query += formatReturningClause(ast.returning)
-    return { query, bindValues }
+    return { query, bindValues, usedTables }
   }
 
   // COUNT query
@@ -185,7 +186,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
       .filter((clause) => clause.length > 0)
       .join(' ')
 
-    return { query, bindValues }
+    return { query, bindValues, usedTables }
   }
 
   // ROW query
@@ -202,6 +203,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     return {
       query: `SELECT * FROM '${ast.tableDef.sqliteDef.name}' WHERE id = ?`,
       bindValues: [encodedId as SqlValue],
+      usedTables,
     }
   }
 
@@ -228,5 +230,5 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     .filter((clause) => clause.length > 0)
     .join(' ')
 
-  return { query, bindValues }
+  return { query, bindValues, usedTables }
 }

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

@@ -0,0 +1,241 @@
+import { Schema } from '@livestore/utils/effect'
+import { describe, expect, it } from 'vitest'
+import { State } from '../../mod.ts'
+
+describe('table function overloads', () => {
+  it('should extract table name from title annotation', () => {
+    const TodoSchema = Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      completed: Schema.Boolean,
+    }).annotations({ title: 'todos' })
+
+    const todosTable = State.SQLite.table({
+      schema: TodoSchema,
+    })
+
+    expect(todosTable.sqliteDef.name).toBe('todos')
+  })
+
+  it('should extract table name from identifier annotation', () => {
+    const TodoSchema = Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      completed: Schema.Boolean,
+    }).annotations({ identifier: 'TodoItem' })
+
+    const todosTable = State.SQLite.table({ schema: TodoSchema })
+
+    expect(todosTable.sqliteDef.name).toBe('TodoItem')
+  })
+
+  it('should prefer title over identifier annotation', () => {
+    const TodoSchema = Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      completed: Schema.Boolean,
+    }).annotations({
+      title: 'todos',
+      identifier: 'TodoItem',
+    })
+
+    const todosTable = State.SQLite.table({ schema: TodoSchema })
+
+    expect(todosTable.sqliteDef.name).toBe('todos')
+  })
+
+  it('should throw when schema has no name, title, or identifier', () => {
+    const TodoSchema = Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      completed: Schema.Boolean,
+    })
+
+    expect(() => State.SQLite.table({ schema: TodoSchema })).toThrow(
+      'When using schema without explicit name, the schema must have a title or identifier annotation',
+    )
+  })
+
+  it('should work with columns parameter', () => {
+    const todosTable = State.SQLite.table({
+      name: 'todos',
+      columns: {
+        id: State.SQLite.text({ primaryKey: true }),
+        text: State.SQLite.text({ default: '' }),
+        completed: State.SQLite.boolean({ default: false }),
+        optionalComplex: State.SQLite.json({
+          nullable: true,
+          schema: Schema.Struct({ color: Schema.String }).pipe(Schema.UndefinedOr),
+        }),
+      },
+    })
+
+    expect((todosTable.rowSchema as any).fields.completed.toString()).toMatchInlineSnapshot(`"(number <-> boolean)"`)
+    expect(todosTable.sqliteDef.name).toBe('todos')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('id')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('text')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('completed')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('optionalComplex')
+    expect(todosTable.sqliteDef.columns.optionalComplex.nullable).toBe(true)
+    expect((todosTable.rowSchema as any).fields.optionalComplex.toString()).toBe(
+      '(parseJson <-> { readonly color: string } | undefined) | null',
+    )
+  })
+
+  it('should work with schema parameter', () => {
+    const TodoSchema = Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      completed: Schema.Boolean,
+    })
+
+    const todosTable = State.SQLite.table({
+      name: 'todos',
+      schema: TodoSchema,
+    })
+
+    expect(todosTable.sqliteDef.name).toBe('todos')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('id')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('text')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('completed')
+  })
+
+  it('should work with single column', () => {
+    const simpleTable = State.SQLite.table({
+      name: 'simple',
+      columns: State.SQLite.text({ primaryKey: true }),
+    })
+
+    expect(simpleTable.sqliteDef.name).toBe('simple')
+    expect(simpleTable.sqliteDef.columns).toHaveProperty('value')
+    expect(simpleTable.sqliteDef.columns.value.primaryKey).toBe(true)
+  })
+
+  it('should handle optional fields in schema', () => {
+    const UserSchema = Schema.Struct({
+      id: Schema.String,
+      name: Schema.String,
+      email: Schema.optional(Schema.String),
+    })
+
+    const userTable = State.SQLite.table({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    expect(userTable.sqliteDef.columns.id.nullable).toBe(false)
+    expect(userTable.sqliteDef.columns.name.nullable).toBe(false)
+    expect(userTable.sqliteDef.columns.email.nullable).toBe(true)
+  })
+
+  it('should handle Schema.Int as integer column', () => {
+    const CounterSchema = Schema.Struct({
+      id: Schema.String,
+      count: Schema.Int,
+    })
+
+    const counterTable = State.SQLite.table({
+      name: 'counters',
+      schema: CounterSchema,
+    })
+
+    expect(counterTable.sqliteDef.columns.count.columnType).toBe('integer')
+  })
+
+  it('should work with Schema.Class', () => {
+    class User extends Schema.Class<User>('User')({
+      id: Schema.String,
+      name: Schema.String,
+      email: Schema.optional(Schema.String),
+      age: Schema.Int,
+    }) {}
+
+    const userTable = State.SQLite.table({
+      name: 'users',
+      schema: User,
+    })
+
+    expect(userTable.sqliteDef.name).toBe('users')
+    expect(userTable.sqliteDef.columns).toHaveProperty('id')
+    expect(userTable.sqliteDef.columns).toHaveProperty('name')
+    expect(userTable.sqliteDef.columns).toHaveProperty('email')
+    expect(userTable.sqliteDef.columns).toHaveProperty('age')
+
+    // Check column types
+    expect(userTable.sqliteDef.columns.id.columnType).toBe('text')
+    expect(userTable.sqliteDef.columns.name.columnType).toBe('text')
+    expect(userTable.sqliteDef.columns.email.columnType).toBe('text')
+    expect(userTable.sqliteDef.columns.email.nullable).toBe(true)
+    expect(userTable.sqliteDef.columns.age.columnType).toBe('integer')
+  })
+
+  it('should extract table name from Schema.Class identifier', () => {
+    class TodoItem extends Schema.Class<TodoItem>('TodoItem')({
+      id: Schema.String,
+      text: Schema.String,
+      completed: Schema.Boolean,
+    }) {}
+
+    // Schema.Class doesn't set identifier/title annotations, so we need to provide an explicit name
+    const todosTable = State.SQLite.table({
+      name: 'TodoItem',
+      schema: TodoItem,
+    })
+
+    expect(todosTable.sqliteDef.name).toBe('TodoItem')
+  })
+
+  it('should properly infer types from schema', () => {
+    const UserSchema = Schema.Struct({
+      id: Schema.String,
+      name: Schema.String,
+      age: Schema.Int,
+      active: Schema.Boolean,
+      metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    })
+
+    const userTable = State.SQLite.table({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    // Test that Type is properly inferred
+    type UserType = typeof userTable.Type
+    const _userTypeCheck: UserType = {
+      id: 'test-id',
+      name: 'John',
+      age: 30,
+      active: true,
+      metadata: { key1: 'value1', key2: 123 },
+    }
+
+    // Test that columns have proper schema types
+    type IdColumn = typeof userTable.sqliteDef.columns.id
+    type NameColumn = typeof userTable.sqliteDef.columns.name
+    type AgeColumn = typeof userTable.sqliteDef.columns.age
+    type ActiveColumn = typeof userTable.sqliteDef.columns.active
+    type MetadataColumn = typeof userTable.sqliteDef.columns.metadata
+
+    // Should derive proper column schema
+    expect((userTable.rowSchema as any).fields.age.toString()).toMatchInlineSnapshot(`"number"`)
+    expect((userTable.rowSchema as any).fields.active.toString()).toMatchInlineSnapshot(`"(number <-> boolean)"`)
+    expect((userTable.rowSchema as any).fields.metadata.toString()).toMatchInlineSnapshot(
+      `"(parseJson <-> { readonly [x: string]: unknown } | undefined)"`,
+    )
+
+    // These should compile without errors
+    const _idCheck: IdColumn['schema']['Type'] = 'string'
+    const _nameCheck: NameColumn['schema']['Type'] = 'string'
+    const _ageCheck: AgeColumn['schema']['Type'] = 123
+    const _activeCheck: ActiveColumn['schema']['Type'] = true
+    const _metadataCheck: MetadataColumn['schema']['Type'] = { foo: 'bar' }
+
+    // Verify column definitions
+    expect(userTable.sqliteDef.columns.id.columnType).toBe('text')
+    expect(userTable.sqliteDef.columns.name.columnType).toBe('text')
+    expect(userTable.sqliteDef.columns.age.columnType).toBe('integer')
+    expect(userTable.sqliteDef.columns.active.columnType).toBe('integer')
+    expect(userTable.sqliteDef.columns.metadata.columnType).toBe('text')
+    expect(userTable.sqliteDef.columns.metadata.nullable).toBe(true)
+  })
+})