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

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

@@ -1,7 +1,6 @@
 import type { Nullable } from '@livestore/utils'
 import { omitUndefineds } from '@livestore/utils'
-import type { Option, Types } from '@livestore/utils/effect'
-import { Schema } from '@livestore/utils/effect'
+import { type Option, Schema, Struct, type Types } from '@livestore/utils/effect'
 
 import type * as SqliteAst from '../ast/sqlite.ts'
 import type { ColumnDefinition } from './field-defs.ts'
@@ -20,19 +19,18 @@ export type DbSchemaInput = Record<string, TableDefinition<any, any>> | Readonly
  * - array: we use the table name of each array item (= table definition) as the object key
  * - object: we discard the keys of the input object and use the table name of each object value (= table definition) as the new object key
  */
-export type DbSchemaFromInputSchema<TSchemaInput extends DbSchemaInput> = TSchemaInput extends ReadonlyArray<
-  TableDefinition<any, any>
->
-  ? { [K in TSchemaInput[number] as K['name']]: K }
-  : TSchemaInput extends Record<string, TableDefinition<any, any>>
-    ? { [K in keyof TSchemaInput as TSchemaInput[K]['name']]: TSchemaInput[K] }
-    : never
+export type DbSchemaFromInputSchema<TSchemaInput extends DbSchemaInput> =
+  TSchemaInput extends ReadonlyArray<TableDefinition<any, any>>
+    ? { [K in TSchemaInput[number] as K['name']]: K }
+    : TSchemaInput extends Record<string, TableDefinition<any, any>>
+      ? { [K in keyof TSchemaInput as TSchemaInput[K]['name']]: TSchemaInput[K] }
+      : never
 
 // TODO ensure via runtime check (possibly even via type-level check) that all index names are unique
 export const makeDbSchema = <TDbSchemaInput extends DbSchemaInput>(
   schema: TDbSchemaInput,
 ): DbSchemaFromInputSchema<TDbSchemaInput> => {
-  return Array.isArray(schema) ? Object.fromEntries(schema.map((_) => [_.name, _])) : (schema as any)
+  return Array.isArray(schema) === true ? Object.fromEntries(schema.map((_) => [_.name, _])) : (schema as any)
 }
 
 export const table = <TTableName extends string, TColumns extends Columns, TIndexes extends Index[]>(
@@ -53,34 +51,50 @@ export const table = <TTableName extends string, TColumns extends Columns, TInde
 export type AnyIfConstained<In, Out> = '__constrained' extends keyof In ? any : Out
 export type EmptyObjIfConstained<In> = '__constrained' extends keyof In ? {} : In
 
-export type StructSchemaForColumns<TCols extends ConstraintColumns> = Schema.Schema<
-  AnyIfConstained<TCols, FromColumns.RowDecoded<TCols>>,
-  AnyIfConstained<TCols, FromColumns.RowEncoded<TCols>>
->
+export type StructFieldsForColumns<TCols extends ConstraintColumns> = '__constrained' extends keyof TCols
+  ? Record<string, Schema.Codec<any, any>>
+  : { readonly [K in keyof TCols]: TCols[K]['schema'] }
+
+export type StructSchemaForColumns<TCols extends ConstraintColumns> = Schema.Struct<StructFieldsForColumns<TCols>>
 
-export type InsertStructSchemaForColumns<TCols extends ConstraintColumns> = Schema.Schema<
+export type InsertStructSchemaForColumns<TCols extends ConstraintColumns> = Schema.Codec<
   AnyIfConstained<TCols, FromColumns.InsertRowDecoded<TCols>>,
   AnyIfConstained<TCols, FromColumns.InsertRowEncoded<TCols>>
 >
 
-export const structSchemaForTable = <TTableDefinition extends TableDefinition<any, any>>(
-  tableDef: TTableDefinition,
-): StructSchemaForColumns<TTableDefinition['columns']> =>
-  Schema.Struct(Object.fromEntries(tableDef.ast.columns.map((column) => [column.name, column.schema]))).annotations({
+interface GetColumnSchema extends Struct.Lambda {
+  <TEncoded, TDecoded, TNullable extends boolean>(
+    column: ColumnDefinition<TEncoded, TDecoded, TNullable>,
+  ): ColumnDefinition<TEncoded, TDecoded, TNullable>['schema']
+  readonly '~lambda.out': this['~lambda.in'] extends ColumnDefinition<any, any, any>
+    ? this['~lambda.in']['schema']
+    : never
+}
+
+const getColumnSchema = Struct.lambda<GetColumnSchema>((column) => column.schema)
+
+const structFieldsForColumns = <TCols extends ConstraintColumns>(columns: TCols): StructFieldsForColumns<TCols> =>
+  Struct.map(columns, getColumnSchema)
+
+export const structSchemaForTable = <TTableName extends string, TColumns extends ConstraintColumns>(
+  tableDef: TableDefinition<TTableName, TColumns>,
+): StructSchemaForColumns<TColumns> =>
+  Schema.Struct(structFieldsForColumns(tableDef.columns)).annotate({
     title: tableDef.name,
-  }) as any
+  })
 
-export const insertStructSchemaForTable = <TTableDefinition extends TableDefinition<any, any>>(
-  tableDef: TTableDefinition,
-): InsertStructSchemaForColumns<TTableDefinition['columns']> =>
+export const insertStructSchemaForTable = <TTableName extends string, TColumns extends ConstraintColumns>(
+  tableDef: TableDefinition<TTableName, TColumns>,
+): InsertStructSchemaForColumns<TColumns> =>
   Schema.Struct(
     Object.fromEntries(
       tableDef.ast.columns.map((column) => [
         column.name,
+
         column.nullable === true || column.default._tag === 'Some' ? Schema.optional(column.schema) : column.schema,
       ]),
     ),
-  ).annotations({
+  ).annotate({
     title: tableDef.name,
   }) as any
 
@@ -116,12 +130,8 @@ export type TableDefinition<TName extends string, TColumns extends Columns> = {
 
 export type Columns = Record<string, ColumnDefinition<any, any>>
 
-export type IsSingleColumn<TColumns extends Columns | ColumnDefinition<any, any>> = TColumns extends ColumnDefinition<
-  any,
-  any
->
-  ? true
-  : false
+export type IsSingleColumn<TColumns extends Columns | ColumnDefinition<any, any>> =
+  TColumns extends ColumnDefinition<any, any> ? true : false
 
 /**
  * NOTE this is only needed to avoid a TS limitation where `StructSchemaForColumns` in the default case
@@ -154,7 +164,7 @@ export namespace FromTable {
   }
 
   export type RowEncodeNonNullable<TTableDefinition extends TableDefinition<any, any>> = {
-    [K in keyof TTableDefinition['columns']]: Schema.Schema.Encoded<TTableDefinition['columns'][K]['schema']>
+    [K in keyof TTableDefinition['columns']]: TTableDefinition['columns'][K]['schema']['Encoded']
   }
 
   export type RowEncoded<TTableDefinition extends TableDefinition<any, any>> = Types.Simplify<
@@ -171,7 +181,7 @@ export namespace FromTable {
   // >
 
   export type RowDecodedAll<TTableDefinition extends TableDefinition<any, any>> = {
-    [K in keyof TTableDefinition['columns']]: Schema.Schema.Type<TTableDefinition['columns'][K]['schema']>
+    [K in keyof TTableDefinition['columns']]: TTableDefinition['columns'][K]['schema']['Type']
   }
 }
 
@@ -183,11 +193,11 @@ export namespace FromColumns {
   >
 
   export type RowDecodedAll<TColumns extends Columns> = {
-    readonly [K in keyof TColumns]: Schema.Schema.Type<TColumns[K]['schema']>
+    readonly [K in keyof TColumns]: TColumns[K]['schema']['Type']
   }
 
   export type RowEncodedAll<TColumns extends Columns> = {
-    readonly [K in keyof TColumns]: Schema.Schema.Encoded<TColumns[K]['schema']>
+    readonly [K in keyof TColumns]: TColumns[K]['schema']['Encoded']
   }
 
   export type RowEncoded<TColumns extends Columns> = Types.Simplify<
@@ -196,12 +206,11 @@ export namespace FromColumns {
   >
 
   export type RowEncodeNonNullable<TColumns extends Columns> = {
-    readonly [K in keyof TColumns]: Schema.Schema.Encoded<TColumns[K]['schema']>
+    readonly [K in keyof TColumns]: TColumns[K]['schema']['Encoded']
   }
 
   export type NullableColumnNames<TColumns extends Columns> = keyof {
-    // TODO double check why there is a `true` in the type
-    [K in keyof TColumns as TColumns[K] extends ColumnDefinition<any, true> ? K : never]: {}
+    [K in keyof TColumns as TColumns[K]['nullable'] extends true ? K : never]: {}
   }
 
   export type RequiredInsertColumns<TColumns extends Columns> = {
@@ -214,9 +223,8 @@ export namespace FromColumns {
 
   export type RequiredInsertColumnNames<TColumns extends Columns> = keyof RequiredInsertColumns<TColumns>
 
-  export type RequiresInsertValues<TColumns extends Columns> = RequiredInsertColumnNames<TColumns> extends never
-    ? false
-    : true
+  export type RequiresInsertValues<TColumns extends Columns> =
+    RequiredInsertColumnNames<TColumns> extends never ? false : true
 
   export type InsertRowDecoded<TColumns extends Columns> = Types.Simplify<
     Pick<RowDecodedAll<TColumns>, RequiredInsertColumnNames<TColumns>> &

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

@@ -1,14 +1,14 @@
 import { shouldNeverHappen } from '@livestore/utils'
 
 import type { MigrationOptions } from '../../../adapter-types.ts'
-import type { Materializer } from '../../EventDef.ts'
+import type { Materializer } from '../../EventDef/mod.ts'
 import type { InternalState } from '../../schema.ts'
 import { ClientDocumentTableDefSymbol, tableIsClientDocumentTable } from './client-document-def.ts'
 import { SqliteAst } from './db-schema/mod.ts'
-import { stateSystemTables } from './system-tables.ts'
+import { stateSystemTables } from './system-tables/state-tables.ts'
 import type { TableDef, TableDefBase } from './table-def.ts'
 
-export * from '../../EventDef.ts'
+export * from '../../EventDef/mod.ts'
 export {
   type ClientDocumentTableDef,
   ClientDocumentTableDefSymbol,
@@ -22,16 +22,15 @@ export * from './column-spec.ts'
 export * from './table-def.ts'
 
 export const makeState = <TStateInput extends InputState>(inputSchema: TStateInput): InternalState => {
-  const inputTables: ReadonlyArray<TableDef> = Array.isArray(inputSchema.tables)
-    ? inputSchema.tables
-    : Object.values(inputSchema.tables)
+  const inputTables: ReadonlyArray<TableDef> =
+    Array.isArray(inputSchema.tables) === true ? inputSchema.tables : Object.values(inputSchema.tables)
 
   const tables = new Map<string, TableDef.Any>()
 
   for (const tableDef of inputTables) {
     const sqliteDef = tableDef.sqliteDef
     // TODO validate tables (e.g. index names are unique)
-    if (tables.has(sqliteDef.ast.name)) {
+    if (tables.has(sqliteDef.ast.name) === true) {
       shouldNeverHappen(`Duplicate table name: ${sqliteDef.ast.name}. Please use unique names for tables.`)
     }
     tables.set(sqliteDef.ast.name, tableDef)
@@ -48,7 +47,7 @@ export const makeState = <TStateInput extends InputState>(inputSchema: TStateInp
   }
 
   for (const tableDef of inputTables) {
-    if (tableIsClientDocumentTable(tableDef)) {
+    if (tableIsClientDocumentTable(tableDef) === true) {
       materializers.set(
         tableDef[ClientDocumentTableDefSymbol].derived.setEventDef.name,
         tableDef[ClientDocumentTableDefSymbol].derived.setMaterializer,
@@ -61,14 +60,12 @@ export const makeState = <TStateInput extends InputState>(inputSchema: TStateInp
     tables: [...tables.values()].map((_) => _.sqliteDef.ast),
   })
 
-  return { sqlite: { tables, migrations: inputSchema.migrations ?? { strategy: 'auto' }, hash }, materializers }
+  return { sqlite: { tables, migrations: inputSchema.migrations ?? {}, hash }, materializers }
 }
 
 export type InputState = {
   readonly tables: Record<string, TableDefBase> | ReadonlyArray<TableDefBase>
   readonly materializers: Record<string, Materializer<any>>
-  /**
-   * @default { strategy: 'auto' }
-   */
+  /** Configures hooks and logging for automatic state migration. */
   readonly migrations?: MigrationOptions
 }

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

@@ -0,0 +1,11 @@
+import type { LiveStoreSchema } from '../../schema.ts'
+
+/**
+ * Returns the schema-keyed base name shared by persisted state databases.
+ *
+ * @remarks
+ *
+ * Adapters append backend-specific storage-format namespaces and file
+ * extensions.
+ */
+export const getStateDbBaseName = (schema: LiveStoreSchema): string => `state${schema.state.sqlite.hash}`

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

@@ -1,7 +1,7 @@
 import type { GetValForKey, SingleOrReadonlyArray } from '@livestore/utils'
 import { type Option, Predicate, type Schema } from '@livestore/utils/effect'
 
-import type { SessionIdSymbol } from '../../../../adapter-types.ts'
+import type { SessionIdSymbol } from '../../../../session-id-symbol.ts'
 import type { SqlValue } from '../../../../util.ts'
 import type { ClientDocumentTableDef, ClientDocumentTableDefSymbol } from '../client-document-def.ts'
 import type { SqliteDsl } from '../db-schema/mod.ts'
@@ -32,14 +32,14 @@ export namespace QueryBuilderAst {
     readonly limit: Option.Option<number>
     readonly tableDef: TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
-    readonly resultSchemaSingle: Schema.Schema<any>
+    readonly resultSchemaSingle: Schema.Codec<any, any>
   }
 
   export interface CountQuery {
     readonly _tag: 'CountQuery'
     readonly tableDef: TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
-    readonly resultSchema: Schema.Schema<number, ReadonlyArray<{ count: number }>>
+    readonly resultSchema: Schema.Codec<number, ReadonlyArray<{ count: number }>>
   }
 
   export interface RowQuery {
@@ -55,7 +55,7 @@ export namespace QueryBuilderAst {
     readonly values: Record<string, unknown>
     readonly onConflict: OnConflict | undefined
     readonly returning: string[] | undefined
-    readonly resultSchema: Schema.Schema<any>
+    readonly resultSchema: Schema.Codec<any, any>
   }
 
   export interface OnConflict {
@@ -76,7 +76,7 @@ export namespace QueryBuilderAst {
     readonly values: Record<string, unknown>
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
     readonly returning: string[] | undefined
-    readonly resultSchema: Schema.Schema<any>
+    readonly resultSchema: Schema.Codec<any, any>
   }
 
   export interface DeleteQuery {
@@ -84,7 +84,7 @@ export namespace QueryBuilderAst {
     readonly tableDef: TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
     readonly returning: string[] | undefined
-    readonly resultSchema: Schema.Schema<any>
+    readonly resultSchema: Schema.Codec<any, any>
   }
 
   export type WriteQuery = InsertQuery | UpdateQuery | DeleteQuery
@@ -115,7 +115,7 @@ export const isQueryBuilder = (value: unknown): value is QueryBuilder<any, any,
 
 export type QueryBuilder<
   TResult,
-  TTableDef extends TableDefBase,
+  TTableDef extends TableDefBase<any, any>,
   /** Used to gradually remove features from the API based on the query context */
   TWithout extends QueryBuilder.ApiFeature = never,
 > = {
@@ -128,15 +128,25 @@ export type QueryBuilder<
 
 export namespace QueryBuilder {
   export type Any = QueryBuilder<any, any, any>
-  export type WhereOps = WhereOps.Equality | WhereOps.Order | WhereOps.Like | WhereOps.In
+  export type WhereOps = WhereOps.Equality | WhereOps.Order | WhereOps.Like | WhereOps.In | WhereOps.JsonArray
 
   export namespace WhereOps {
     export type Equality = '=' | '!='
     export type Order = '<' | '>' | '<=' | '>='
     export type Like = 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE'
     export type In = 'IN' | 'NOT IN'
+    /**
+     * Operators for checking if a JSON array column contains a value.
+     *
+     * ⚠️ **Performance note**: These operators use SQLite's `json_each()` table-valued function
+     * which **cannot be indexed** and requires a full table scan. For large tables with frequent
+     * lookups, consider denormalizing the data into a separate indexed table.
+     *
+     * @see https://sqlite.org/json1.html#jeach
+     */
+    export type JsonArray = 'JSON_CONTAINS' | 'JSON_NOT_CONTAINS'
 
-    export type SingleValue = Equality | Order | Like
+    export type SingleValue = Equality | Order | Like | JsonArray
     export type MultiValue = In
   }
 
@@ -155,14 +165,26 @@ export namespace QueryBuilder {
     | 'returning'
     | 'onConflict'
 
+  /** Extracts the element type from an array type, or returns never if not an array */
+  type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never
+
   export type WhereParams<TTableDef extends TableDefBase> = Partial<{
     [K in keyof TTableDef['sqliteDef']['columns']]:
       | TTableDef['sqliteDef']['columns'][K]['schema']['Type']
-      | { op: QueryBuilder.WhereOps.SingleValue; value: TTableDef['sqliteDef']['columns'][K]['schema']['Type'] }
+      | {
+          op: Exclude<QueryBuilder.WhereOps.SingleValue, QueryBuilder.WhereOps.JsonArray>
+          value: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
+        }
       | {
           op: QueryBuilder.WhereOps.MultiValue
           value: ReadonlyArray<TTableDef['sqliteDef']['columns'][K]['schema']['Type']>
         }
+      | (ArrayElement<TTableDef['sqliteDef']['columns'][K]['schema']['Type']> extends never
+          ? never
+          : {
+              op: QueryBuilder.WhereOps.JsonArray
+              value: ArrayElement<TTableDef['sqliteDef']['columns'][K]['schema']['Type']>
+            })
       | undefined
   }>
 
@@ -208,9 +230,8 @@ export namespace QueryBuilder {
       /** Select multiple columns */
       <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
         ...columns: TColumns[]
-        // TODO also support arbitrary SQL selects
-        // params: QueryBuilderSelectParams,
       ): QueryBuilder<
+        // params: QueryBuilderSelectParams, // TODO also support arbitrary SQL selects
         ReadonlyArray<{
           readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
         }>,
@@ -242,7 +263,12 @@ export namespace QueryBuilder {
       ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
       <TColName extends keyof TTableDef['sqliteDef']['columns']>(
         col: TColName,
-        op: QueryBuilder.WhereOps,
+        op: QueryBuilder.WhereOps.MultiValue,
+        value: ReadonlyArray<TTableDef['sqliteDef']['columns'][TColName]['schema']['Type']>,
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
+      <TColName extends keyof TTableDef['sqliteDef']['columns']>(
+        col: TColName,
+        op: QueryBuilder.WhereOps.SingleValue,
         value: TTableDef['sqliteDef']['columns'][TColName]['schema']['Type'],
       ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
     }
@@ -331,12 +357,20 @@ export namespace QueryBuilder {
     >
 
     /**
-     * Insert a new row into the table
+     * Insert a new row into the table.
+     *
+     * @remarks
+     *
+     * Follows SQL semantics: nullable columns and columns with defaults are omittable.
+     * `NullOr(S)` and `optional(NullOr(S))` both produce nullable columns, so both are omittable.
+     *
+     * @example
      *
-     * Example:
      * ```ts
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' })
      * ```
+     *
+     * @param values - The row values to insert.
      */
     readonly insert: (
       values: TTableDef['insertSchema']['Type'],
@@ -347,22 +381,26 @@ export namespace QueryBuilder {
     >
 
     /**
-     * Example: If the row already exists, it will be ignored.
+     * Upsert: insert a row, or handle conflicts on existing rows.
+     * Equivalent to SQLite's `INSERT ... ON CONFLICT` clause.
+     *
+     * Actions:
+     * - `'ignore'`: Skip the insert if a row with the same key exists
+     * - `'replace'`: Delete the existing row and insert the new one
+     * - `'update'`: Update specific columns on the existing row
+     *
      * ```ts
+     * // Ignore: skip if row exists
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')
-     * ```
      *
-     * Example: If the row already exists, it will be replaced.
-     * ```ts
+     * // Replace: delete existing row and insert new one
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')
-     * ```
      *
-     * Example: If the row already exists, it will be updated.
-     * ```ts
+     * // Update: merge specific columns into existing row
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'update', { text: 'Buy soy milk' })
      * ```
      *
-     * NOTE This API doesn't yet support composite primary keys.
+     * NOTE: Composite primary keys are not yet supported.
      */
     readonly onConflict: {
       <TTarget extends SingleOrReadonlyArray<keyof TTableDef['sqliteDef']['columns']>>(