@livestore/common 0.1.0 → 0.2.0-dev.0

package/src/query-builder/impl.ts

@@ -0,0 +1,268 @@
+import { Option, Predicate, Schema } from '@livestore/utils/effect'
+
+import type { QueryInfo } from '../query-info.js'
+import type { DbSchema } from '../schema/index.js'
+import type { QueryBuilder, QueryBuilderAst } from './api.js'
+import { QueryBuilderAstSymbol, TypeId } from './api.js'
+
+export const makeQueryBuilder = <TResult, TTableDef extends DbSchema.TableDefBase>(
+  tableDef: TTableDef,
+  ast: QueryBuilderAst = emptyAst(tableDef),
+): QueryBuilder<TResult, TTableDef, never, QueryInfo.None> => {
+  const api = {
+    // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+    select() {
+      assertQueryBuilderAst(ast)
+
+      // eslint-disable-next-line prefer-rest-params
+      const params = [...arguments]
+
+      if (params.length === 2 && typeof params[0] === 'string' && typeof params[1] === 'object') {
+        const [col, options] = params as any as [string, { pluck: boolean }]
+        return makeQueryBuilder(tableDef, {
+          ...ast,
+          resultSchemaSingle: options.pluck ? ast.resultSchemaSingle.pipe(Schema.pluck(col)) : ast.resultSchemaSingle,
+          select: { columns: [col] },
+        })
+      }
+
+      const columns = params as unknown as ReadonlyArray<string>
+
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        resultSchemaSingle:
+          columns.length === 0 ? ast.resultSchemaSingle : ast.resultSchemaSingle.pipe(Schema.pick(...columns)),
+        select: { columns },
+      }) as any
+    },
+    // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+    where() {
+      if (isRowQuery(ast)) return invalidQueryBuilder()
+
+      if (arguments.length === 1) {
+        // eslint-disable-next-line prefer-rest-params
+        const params = arguments[0]
+        const newOps = Object.entries(params)
+          .filter(([, value]) => value !== undefined)
+          .map<QueryBuilderAst.Where>(([col, value]) =>
+            Predicate.hasProperty(value, 'op') && Predicate.hasProperty(value, 'value')
+              ? ({ col, op: value.op, value: value.value } as any)
+              : { col, op: '=', value },
+          )
+
+        return makeQueryBuilder(tableDef, {
+          ...ast,
+          where: [...ast.where, ...newOps],
+        }) as any
+      }
+
+      // eslint-disable-next-line prefer-rest-params
+      const [col, opOrValue, valueOrUndefined] = arguments
+      const op = valueOrUndefined === undefined ? '=' : opOrValue
+      const value = valueOrUndefined === undefined ? opOrValue : valueOrUndefined
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        where: [...ast.where, { col, op, value }],
+      })
+    },
+    // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+    orderBy() {
+      assertQueryBuilderAst(ast)
+
+      if (arguments.length === 0 || arguments.length > 2) return invalidQueryBuilder()
+
+      if (arguments.length === 1) {
+        // eslint-disable-next-line prefer-rest-params
+        const params = arguments[0] as QueryBuilder.OrderByParams<TTableDef>
+        return makeQueryBuilder(tableDef, {
+          ...ast,
+          orderBy: [...ast.orderBy, ...params],
+        })
+      }
+
+      // eslint-disable-next-line prefer-rest-params
+      const [col, direction] = arguments as any as [keyof TTableDef['sqliteDef']['columns'] & string, 'asc' | 'desc']
+
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        orderBy: [...ast.orderBy, { col, direction }],
+      }) as any
+    },
+    limit: (limit) => {
+      assertQueryBuilderAst(ast)
+
+      return makeQueryBuilder(tableDef, { ...ast, limit: Option.some(limit) })
+    },
+    offset: (offset) => {
+      assertQueryBuilderAst(ast)
+
+      return makeQueryBuilder(tableDef, { ...ast, offset: Option.some(offset) })
+    },
+    count: () => {
+      if (isRowQuery(ast)) return invalidQueryBuilder()
+
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        resultSchema: Schema.Struct({ count: Schema.Number }).pipe(
+          Schema.pluck('count'),
+          Schema.Array,
+          Schema.headOrElse(),
+        ),
+        _tag: 'CountQuery',
+      })
+    },
+    first: (options) => {
+      assertQueryBuilderAst(ast)
+
+      if (ast.limit._tag === 'Some') return invalidQueryBuilder(`.first() can't be called after .limit()`)
+
+      return makeQueryBuilder(tableDef, {
+        ...ast,
+        limit: Option.some(1),
+        pickFirst: options?.fallback ? { fallback: options.fallback } : false,
+      })
+    },
+    // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+    row() {
+      // eslint-disable-next-line prefer-rest-params
+      const params = [...arguments]
+
+      let id: string
+
+      if (tableDef.options.isSingleton) {
+        id = tableDef.sqliteDef.columns.id!.default.pipe(Option.getOrThrow)
+      } else {
+        id = params[0] as string
+        if (id === undefined) {
+          invalidQueryBuilder(`Id missing for row query on non-singleton table ${tableDef.sqliteDef.name}`)
+        }
+      }
+
+      // TODO validate all required columns are present and values are matching the schema
+      const insertValues: Record<string, unknown> = params[1]?.insertValues ?? {}
+
+      return makeQueryBuilder(tableDef, {
+        _tag: 'RowQuery',
+        id,
+        tableDef,
+        insertValues,
+      }) as any
+    },
+  } satisfies QueryBuilder.ApiFull<TResult, TTableDef, never, QueryInfo.None>
+
+  return {
+    [TypeId]: TypeId,
+    [QueryBuilderAstSymbol]: ast,
+    asSql: () => astToSql(ast),
+    toString: () => astToSql(ast).query,
+    ...api,
+  } satisfies QueryBuilder<TResult, TTableDef>
+}
+
+const emptyAst = (tableDef: DbSchema.TableDefBase) =>
+  ({
+    _tag: 'SelectQuery',
+    columns: [],
+    pickFirst: false,
+    select: { columns: [] },
+    orderBy: [],
+    offset: Option.none(),
+    limit: Option.none(),
+    tableDef,
+    where: [],
+    resultSchemaSingle: tableDef.schema,
+  }) satisfies QueryBuilderAst
+
+const astToSql = (ast: QueryBuilderAst) => {
+  if (isRowQuery(ast)) {
+    // TODO
+    return { query: `SELECT * FROM '${ast.tableDef.sqliteDef.name}' WHERE id = ?`, bindValues: [ast.id as TODO] }
+  }
+
+  const bindValues: unknown[] = []
+
+  // TODO bind values
+  const whereStmt =
+    ast.where.length > 0
+      ? `WHERE ${ast.where
+          .map(({ col, op, value }) => {
+            if (value === null) {
+              if (op !== '=' && op !== '!=') {
+                throw new Error(`Unsupported operator for NULL value: ${op}`)
+              }
+              const opStmt = op === '=' ? 'IS' : 'IS NOT'
+              return `${col} ${opStmt} NULL`
+            } else {
+              const colDef = ast.tableDef.sqliteDef.columns[col]
+              if (colDef === undefined) {
+                throw new Error(`Column ${col} not found`)
+              }
+              const encodedValue = Schema.encodeSync(colDef.schema)(value)
+              bindValues.push(encodedValue)
+              return `${col} ${op} ?`
+            }
+          })
+          .join(' AND ')}`
+      : ''
+
+  if (ast._tag === 'CountQuery') {
+    const selectFromStmt = `SELECT COUNT(*) as count FROM '${ast.tableDef.sqliteDef.name}'`
+    const query = [selectFromStmt, whereStmt].filter((_) => _.length > 0).join(' ')
+    return { query, bindValues }
+  }
+  const columnsStmt = ast.select.columns.length === 0 ? '*' : ast.select.columns.join(', ')
+  const selectStmt = `SELECT ${columnsStmt}`
+  const fromStmt = `FROM '${ast.tableDef.sqliteDef.name}'`
+
+  const orderByStmt =
+    ast.orderBy.length > 0
+      ? `ORDER BY ${ast.orderBy.map(({ col, direction }) => `${col} ${direction}`).join(', ')}`
+      : ''
+
+  const limitStmt = ast.limit._tag === 'Some' ? `LIMIT ?` : ''
+  if (ast.limit._tag === 'Some') bindValues.push(ast.limit.value)
+
+  const offsetStmt = ast.offset._tag === 'Some' ? `OFFSET ?` : ''
+  if (ast.offset._tag === 'Some') bindValues.push(ast.offset.value)
+
+  const query = [selectStmt, fromStmt, whereStmt, orderByStmt, offsetStmt, limitStmt]
+    .map((_) => _.trim())
+    .filter((_) => _.length > 0)
+    .join(' ')
+
+  // TODO bind values
+  return { query, bindValues }
+}
+
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+function assertQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.SelectQuery {
+  if (ast._tag !== 'SelectQuery') {
+    throw new Error('Expected SelectQuery but got ' + ast._tag)
+  }
+}
+
+const isRowQuery = (ast: QueryBuilderAst): ast is QueryBuilderAst.RowQuery => ast._tag === 'RowQuery'
+
+export const invalidQueryBuilder = (msg?: string) => {
+  throw new Error('Invalid query builder' + (msg ? `: ${msg}` : ''))
+}
+
+export const getResultSchema = (qb: QueryBuilder<any, any, any>) => {
+  const queryAst = qb[QueryBuilderAstSymbol]
+  if (queryAst._tag === 'SelectQuery') {
+    const arraySchema = Schema.Array(queryAst.resultSchemaSingle)
+    if (queryAst.pickFirst !== false) {
+      return arraySchema.pipe(Schema.headOrElse(queryAst.pickFirst.fallback))
+    }
+
+    return arraySchema
+  } else if (queryAst._tag === 'CountQuery') {
+    return Schema.Struct({ count: Schema.Number }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
+  } else {
+    if (queryAst.tableDef.options.isSingleColumn) {
+      return queryAst.tableDef.schema.pipe(Schema.pluck('value'), Schema.Array, Schema.headOrElse())
+    } else {
+      return queryAst.tableDef.schema.pipe(Schema.Array, Schema.headOrElse())
+    }
+  }
+}

package/src/query-builder/mod.ts

@@ -0,0 +1,10 @@
+export * from './api.js'
+export * from './impl.js'
+
+/**
+ * Design decisions:
+ *
+ * - Close abstraction to SQLite to provide a simple & convenient API with predictable behaviour
+ * - Use table schema definitions to parse, map & validate query results
+ * - Implementation detail: Separate type-level & AST-based runtime implementation
+ */

package/src/query-info.ts

@@ -1,5 +1,3 @@
-import type { Schema } from '@livestore/utils/effect'
-
 import type { SessionIdSymbol } from './adapter-types.js'
 import type { DbSchema } from './schema/index.js'
 
@@ -8,98 +6,73 @@ import type { DbSchema } from './schema/index.js'
  * - a whole row
  * - a single column value
  * - a sub value in a JSON column
+ *
+ * This information is currently only used for derived mutations.
  */
-export type QueryInfo<TTableDef extends DbSchema.TableDef = DbSchema.TableDef> =
-  | QueryInfoNone
-  | QueryInfoRow<TTableDef>
-  | QueryInfoColJsonValue<TTableDef, GetJsonColumn<TTableDef>>
-  | QueryInfoCol<TTableDef, keyof TTableDef['sqliteDef']['columns']>
-
-export type QueryInfoNone = {
-  _tag: 'None'
-}
-
-export type QueryInfoRow<TTableDef extends DbSchema.TableDef> = {
-  _tag: 'Row'
-  table: TTableDef
-  id: string | SessionIdSymbol
-}
-
-export type QueryInfoCol<
-  TTableDef extends DbSchema.TableDef,
-  TColName extends keyof TTableDef['sqliteDef']['columns'],
-> = {
-  _tag: 'Col'
-  table: TTableDef
-  id: string | SessionIdSymbol
-  column: TColName
-}
-
-export type QueryInfoColJsonValue<TTableDef extends DbSchema.TableDef, TColName extends GetJsonColumn<TTableDef>> = {
-  _tag: 'ColJsonValue'
-  table: TTableDef
-  id: string | SessionIdSymbol
-  column: TColName
-  /**
-   * example: `$.tabs[3].items[2]` (`$` referring to the column value)
-   */
-  jsonPath: string
-}
-
-type GetJsonColumn<TTableDef extends DbSchema.TableDef> = keyof {
-  [ColName in keyof TTableDef['sqliteDef']['columns'] as TTableDef['sqliteDef']['columns'][ColName]['columnType'] extends 'text'
-    ? ColName
-    : never]: {}
+export type QueryInfo = QueryInfo.None | QueryInfo.Row | QueryInfo.Col | QueryInfo.ColJsonValue
+// export type QueryInfo<TTableDef extends DbSchema.TableDefBase = DbSchema.TableDefBase> =
+// | QueryInfo.None
+// | QueryInfo.Row<TTableDef>
+// | QueryInfo.ColJsonValue<TTableDef, GetJsonColumn<TTableDef>>
+// | QueryInfo.Col<TTableDef, keyof TTableDef['sqliteDef']['columns']>
+
+export namespace QueryInfo {
+  export type None = {
+    _tag: 'None'
+  }
+
+  export type Row = {
+    _tag: 'Row'
+    table: DbSchema.TableDefBase
+    id: string | SessionIdSymbol
+  }
+
+  export type Col = {
+    _tag: 'Col'
+    table: DbSchema.TableDefBase
+    id: string | SessionIdSymbol
+    column: string
+  }
+
+  export type ColJsonValue = {
+    _tag: 'ColJsonValue'
+    table: DbSchema.TableDefBase
+    id: string | SessionIdSymbol
+    column: string
+    /**
+     * example: `$.tabs[3].items[2]` (`$` referring to the column value)
+     */
+    jsonPath: string
+  }
+
+  // NOTE maybe we want to bring back type-params back like below
+  // export type Row<TTableDef extends DbSchema.TableDefBase> = {
+  //   _tag: 'Row'
+  //   table: TTableDef
+  //   id: string | SessionIdSymbol
+  // }
+
+  // export type Col<TTableDef extends DbSchema.TableDefBase, TColName extends keyof TTableDef['sqliteDef']['columns']> = {
+  //   _tag: 'Col'
+  //   table: TTableDef
+  //   id: string | SessionIdSymbol
+  //   column: TColName
+  // }
+
+  // export type ColJsonValue<TTableDef extends DbSchema.TableDefBase, TColName extends GetJsonColumn<TTableDef>> = {
+  //   _tag: 'ColJsonValue'
+  //   table: TTableDef
+  //   id: string | SessionIdSymbol
+  //   column: TColName
+  //   /**
+  //    * example: `$.tabs[3].items[2]` (`$` referring to the column value)
+  //    */
+  //   jsonPath: string
+  // }
 }
 
-export type UpdateValueForPath<TQueryInfo extends QueryInfo> = TQueryInfo extends { _tag: 'Row' }
-  ? Partial<DbSchema.FromTable.RowDecodedAll<TQueryInfo['table']>>
-  : TQueryInfo extends { _tag: 'Col' }
-    ? Schema.Schema.Type<TQueryInfo['table']['sqliteDef']['columns'][TQueryInfo['column']]['schema']>
-    : TQueryInfo extends { _tag: 'ColJsonValue' }
-      ? { TODO: true }
-      : never
-
-// export const mutationForQueryInfo = <const TQueryInfo extends QueryInfo>(
-//   queryInfo: TQueryInfo,
-//   value: UpdateValueForPath<TQueryInfo>,
-// ): RawSqlMutationEvent => {
-//   if (queryInfo._tag === 'ColJsonValue' || queryInfo._tag === 'None') {
-//     return notYetImplemented('TODO')
-//   }
-
-//   const sqliteTableDef = queryInfo.table.sqliteDef
-//   const id = queryInfo.id
-
-//   const { columnNames, bindValues } = (() => {
-//     if (queryInfo._tag === 'Row') {
-//       const columnNames = Object.keys(value)
-
-//       const partialStructSchema = queryInfo.table.schema.pipe(Schema.pick(...columnNames))
-
-//       // const columnNames = Object.keys(value)
-//       const encodedBindValues = Schema.encodeEither(partialStructSchema)(value)
-//       if (encodedBindValues._tag === 'Left') {
-//         return shouldNeverHappen(encodedBindValues.left.toString())
-//       } else {
-//         return { columnNames, bindValues: encodedBindValues.right }
-//       }
-//     } else if (queryInfo._tag === 'Col') {
-//       const columnName = queryInfo.column
-//       const columnSchema =
-//         sqliteTableDef.columns[columnName]?.schema ?? shouldNeverHappen(`Column ${columnName} not found`)
-//       const bindValues = { [columnName]: Schema.encodeSync(columnSchema)(value) }
-//       return { columnNames: [columnName], bindValues }
-//     } else {
-//       return shouldNeverHappen()
-//     }
-//   })()
-
-//   const updateClause = columnNames.map((columnName) => `${columnName} = $${columnName}`).join(', ')
-
-//   const whereClause = `where id = '${id}'`
-//   const sql = `UPDATE ${sqliteTableDef.name} SET ${updateClause} ${whereClause}`
-//   const writeTables = new Set<string>([queryInfo.table.sqliteDef.name])
-
-//   return rawSqlMutation({ sql, bindValues, writeTables })
+// type GetJsonColumn<TTableDef extends DbSchema.TableDefBase> = keyof {
+//   [ColName in keyof TTableDef['sqliteDef']['columns'] as TTableDef['sqliteDef']['columns'][ColName]['columnType'] extends 'text'
+//     ? ColName
+//     : never]: {}
 // }

package/src/schema/index.ts

@@ -12,7 +12,8 @@ import {
   rawSqlMutation,
 } from './mutations.js'
 import { systemTables } from './system-tables.js'
-import { type TableDef, tableHasDerivedMutations } from './table-def.js'
+import type { TableDef, TableDefBase } from './table-def.js'
+import { tableHasDerivedMutations } from './table-def.js'
 
 export * from './system-tables.js'
 export * as DbSchema from './table-def.js'
@@ -41,7 +42,7 @@ export type LiveStoreSchema<
 }
 
 export type InputSchema = {
-  readonly tables: Record<string, TableDef> | ReadonlyArray<TableDef>
+  readonly tables: Record<string, TableDefBase> | ReadonlyArray<TableDefBase>
   readonly mutations?: ReadonlyArray<MutationDef.Any> | Record<string, MutationDef.Any>
   /**
    * Can be used to isolate multiple LiveStore apps running in the same origin
@@ -72,6 +73,7 @@ export const makeSchema = <TInputSchema extends InputSchema>(
   }
 
   for (const tableDef of systemTables) {
+    // @ts-expect-error TODO fix type level issue
     tables.set(tableDef.sqliteDef.name, tableDef)
   }
 

package/src/schema/schema-helpers.ts

@@ -2,7 +2,7 @@ import { SqliteDsl } from '@livestore/db-schema'
 import { shouldNeverHappen } from '@livestore/utils'
 import { pipe, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 
-import type { TableDef } from './table-def.js'
+import type { TableDef, TableDefBase } from './table-def.js'
 
 export const getDefaultValuesEncoded = <TTableDef extends TableDef>(
   tableDef: TTableDef,
@@ -26,7 +26,7 @@ export const getDefaultValuesEncoded = <TTableDef extends TableDef>(
     ),
   )
 
-export const getDefaultValuesDecoded = <TTableDef extends TableDef>(
+export const getDefaultValuesDecoded = <TTableDef extends TableDefBase>(
   tableDef: TTableDef,
   fallbackValues?: Record<string, any>,
 ) =>