@livestore/common 0.3.0-dev.3 → 0.3.0-dev.31

package/src/query-builder/api.ts

@@ -1,51 +1,97 @@
-import type { GetValForKey } from '@livestore/utils'
+import type { GetValForKey, SingleOrReadonlyArray } from '@livestore/utils'
 import { type Option, Predicate, type Schema } from '@livestore/utils/effect'
 
 import type { SessionIdSymbol } from '../adapter-types.js'
-import type { QueryInfo } from '../query-info.js'
-import type { DbSchema } from '../schema/mod.js'
-import type { SqliteDsl } from '../schema/table-def.js'
+import type { ClientDocumentTableDef } from '../schema/client-document-def.js'
+import type { SqliteDsl } from '../schema/db-schema/mod.js'
+import type { State } from '../schema/mod.js'
 import type { SqlValue } from '../util.js'
 
-export type QueryBuilderAst = QueryBuilderAst.SelectQuery | QueryBuilderAst.CountQuery | QueryBuilderAst.RowQuery
+export type QueryBuilderAst =
+  | QueryBuilderAst.SelectQuery
+  | QueryBuilderAst.CountQuery
+  | QueryBuilderAst.RowQuery
+  | QueryBuilderAst.InsertQuery
+  | QueryBuilderAst.UpdateQuery
+  | QueryBuilderAst.DeleteQuery
 
 export namespace QueryBuilderAst {
-  export type SelectQuery = {
+  export interface SelectQuery {
     readonly _tag: 'SelectQuery'
     readonly columns: string[]
-    readonly pickFirst: false | { fallback: () => any }
+    readonly pickFirst: false | { fallback: () => any } | 'no-fallback'
     readonly select: {
       columns: ReadonlyArray<string>
     }
     readonly orderBy: ReadonlyArray<OrderBy>
     readonly offset: Option.Option<number>
     readonly limit: Option.Option<number>
-    readonly tableDef: DbSchema.TableDefBase
+    readonly tableDef: State.SQLite.TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
     readonly resultSchemaSingle: Schema.Schema<any>
   }
 
-  export type CountQuery = {
+  export interface CountQuery {
     readonly _tag: 'CountQuery'
-    readonly tableDef: DbSchema.TableDefBase
+    readonly tableDef: State.SQLite.TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
     readonly resultSchema: Schema.Schema<number, ReadonlyArray<{ count: number }>>
   }
 
-  export type RowQuery = {
+  export interface RowQuery {
     readonly _tag: 'RowQuery'
-    readonly tableDef: DbSchema.TableDefBase
+    readonly tableDef: State.SQLite.ClientDocumentTableDef.Any
     readonly id: string | SessionIdSymbol
-    readonly insertValues: Record<string, unknown>
+    readonly explicitDefaultValues: Record<string, unknown>
   }
 
-  export type Where = {
+  export interface InsertQuery {
+    readonly _tag: 'InsertQuery'
+    readonly tableDef: State.SQLite.TableDefBase
+    readonly values: Record<string, unknown>
+    readonly onConflict: OnConflict | undefined
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export interface OnConflict {
+    /** Conflicting column name */
+    readonly targets: string[]
+    readonly action:
+      | { readonly _tag: 'ignore' }
+      | { readonly _tag: 'replace' }
+      | {
+          readonly _tag: 'update'
+          readonly update: Record<string, unknown>
+        }
+  }
+
+  export interface UpdateQuery {
+    readonly _tag: 'UpdateQuery'
+    readonly tableDef: State.SQLite.TableDefBase
+    readonly values: Record<string, unknown>
+    readonly where: ReadonlyArray<QueryBuilderAst.Where>
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export interface DeleteQuery {
+    readonly _tag: 'DeleteQuery'
+    readonly tableDef: State.SQLite.TableDefBase
+    readonly where: ReadonlyArray<QueryBuilderAst.Where>
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export type WriteQuery = InsertQuery | UpdateQuery | DeleteQuery
+
+  export interface Where {
     readonly col: string
     readonly op: QueryBuilder.WhereOps
     readonly value: unknown
   }
 
-  export type OrderBy = {
+  export interface OrderBy {
     readonly col: string
     readonly direction: 'asc' | 'desc'
   }
@@ -53,27 +99,31 @@ export namespace QueryBuilderAst {
 
 export const QueryBuilderAstSymbol = Symbol.for('QueryBuilderAst')
 export type QueryBuilderAstSymbol = typeof QueryBuilderAstSymbol
-export const TypeId = Symbol.for('QueryBuilder')
-export type TypeId = typeof TypeId
+
+export const QueryBuilderResultSymbol = Symbol.for('QueryBuilderResult')
+export type QueryBuilderResultSymbol = typeof QueryBuilderResultSymbol
+
+export const QueryBuilderTypeId = Symbol.for('QueryBuilder')
+export type QueryBuilderTypeId = typeof QueryBuilderTypeId
 
 export const isQueryBuilder = (value: unknown): value is QueryBuilder<any, any, any> =>
-  Predicate.hasProperty(value, TypeId)
+  Predicate.hasProperty(value, QueryBuilderTypeId)
 
 export type QueryBuilder<
   TResult,
-  TTableDef extends DbSchema.TableDefBase,
+  TTableDef extends State.SQLite.TableDefBase,
   /** Used to gradually remove features from the API based on the query context */
   TWithout extends QueryBuilder.ApiFeature = never,
-  TQueryInfo extends QueryInfo = QueryInfo.None,
 > = {
-  readonly [TypeId]: TypeId
+  readonly [QueryBuilderTypeId]: QueryBuilderTypeId
   readonly [QueryBuilderAstSymbol]: QueryBuilderAst
+  readonly ['ResultType']: TResult
   readonly asSql: () => { query: string; bindValues: SqlValue[] }
   readonly toString: () => string
-} & Omit<QueryBuilder.ApiFull<TResult, TTableDef, TWithout, TQueryInfo>, TWithout>
+} & Omit<QueryBuilder.ApiFull<TResult, TTableDef, TWithout>, TWithout>
 
 export namespace QueryBuilder {
-  export type Any = QueryBuilder<any, any, any, any>
+  export type Any = QueryBuilder<any, any, any>
   export type WhereOps = WhereOps.Equality | WhereOps.Order | WhereOps.Like | WhereOps.In
 
   export namespace WhereOps {
@@ -86,9 +136,22 @@ export namespace QueryBuilder {
     export type MultiValue = In
   }
 
-  export type ApiFeature = 'select' | 'where' | 'count' | 'orderBy' | 'offset' | 'limit' | 'first' | 'row'
+  export type ApiFeature =
+    | 'select'
+    | 'where'
+    | 'count'
+    | 'orderBy'
+    | 'offset'
+    | 'limit'
+    | 'first'
+    | 'row'
+    | 'insert'
+    | 'update'
+    | 'delete'
+    | 'returning'
+    | 'onConflict'
 
-  export type WhereParams<TTableDef extends DbSchema.TableDefBase> = Partial<{
+  export type WhereParams<TTableDef extends State.SQLite.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'] }
@@ -99,40 +162,31 @@ export namespace QueryBuilder {
       | undefined
   }>
 
-  export type OrderByParams<TTableDef extends DbSchema.TableDefBase> = ReadonlyArray<{
+  export type OrderByParams<TTableDef extends State.SQLite.TableDefBase> = ReadonlyArray<{
     col: keyof TTableDef['sqliteDef']['columns'] & string
     direction: 'asc' | 'desc'
   }>
 
-  export type ApiFull<
-    TResult,
-    TTableDef extends DbSchema.TableDefBase,
-    TWithout extends ApiFeature,
-    TQueryInfo extends QueryInfo,
-  > = {
+  export type ApiFull<TResult, TTableDef extends State.SQLite.TableDefBase, TWithout extends ApiFeature> = {
     /**
      * `SELECT *` is the default
      *
      * Example:
      * ```ts
      * db.todos.select('id', 'text', 'completed')
-     * db.todos.select('id', { pluck: true })
+     * db.todos.select('id')
      * ```
      */
     readonly select: {
-      <TColumn extends keyof TTableDef['sqliteDef']['columns'] & string, TPluck extends boolean = false>(
-        column: TColumn,
-        options?: { pluck: TPluck },
+      /** Selects and plucks a single column */
+      <TColumn extends keyof TTableDef['sqliteDef']['columns'] & string>(
+        pluckColumn: TColumn,
       ): QueryBuilder<
-        TPluck extends true
-          ? ReadonlyArray<TTableDef['sqliteDef']['columns'][TColumn]['schema']['Type']>
-          : ReadonlyArray<{
-              readonly [K in TColumn]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
-            }>,
+        ReadonlyArray<TTableDef['sqliteDef']['columns'][TColumn]['schema']['Type']>,
         TTableDef,
-        TWithout | 'row' | 'select',
-        TQueryInfo
+        TWithout | 'row' | 'select' | 'returning' | 'onConflict'
       >
+      /** Select multiple columns */
       <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
         ...columns: TColumns[]
         // TODO also support arbitrary SQL selects
@@ -142,8 +196,7 @@ export namespace QueryBuilder {
           readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
         }>,
         TTableDef,
-        TWithout | 'row' | 'select' | 'count',
-        TQueryInfo
+        TWithout | 'row' | 'select' | 'count' | 'returning' | 'onConflict'
       >
     }
 
@@ -163,18 +216,16 @@ export namespace QueryBuilder {
      * TODO: Also support `OR`
      */
     readonly where: {
-      <TParams extends QueryBuilder.WhereParams<TTableDef>>(
-        params: TParams,
-      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select', TQueryInfo>
+      (params: QueryBuilder.WhereParams<TTableDef>): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
       <TColName extends keyof TTableDef['sqliteDef']['columns']>(
         col: TColName,
         value: TTableDef['sqliteDef']['columns'][TColName]['schema']['Type'],
-      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select', TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
       <TColName extends keyof TTableDef['sqliteDef']['columns']>(
         col: TColName,
         op: QueryBuilder.WhereOps,
         value: TTableDef['sqliteDef']['columns'][TColName]['schema']['Type'],
-      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select', TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
     }
 
     /**
@@ -187,8 +238,7 @@ export namespace QueryBuilder {
     readonly count: () => QueryBuilder<
       number,
       TTableDef,
-      TWithout | 'row' | 'count' | 'select' | 'orderBy' | 'first' | 'offset' | 'limit',
-      TQueryInfo
+      TWithout | 'row' | 'count' | 'select' | 'orderBy' | 'first' | 'offset' | 'limit' | 'returning' | 'onConflict'
     >
 
     /**
@@ -201,10 +251,10 @@ export namespace QueryBuilder {
       <TColName extends keyof TTableDef['sqliteDef']['columns'] & string>(
         col: TColName,
         direction: 'asc' | 'desc',
-      ): QueryBuilder<TResult, TTableDef, TWithout, TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict'>
       <TParams extends QueryBuilder.OrderByParams<TTableDef>>(
         params: TParams,
-      ): QueryBuilder<TResult, TTableDef, TWithout, TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict'>
     }
 
     /**
@@ -215,7 +265,7 @@ export namespace QueryBuilder {
      */
     readonly offset: (
       offset: number,
-    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'offset' | 'orderBy', TQueryInfo>
+    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'offset' | 'orderBy' | 'returning' | 'onConflict'>
 
     /**
      * Example:
@@ -225,65 +275,166 @@ export namespace QueryBuilder {
      */
     readonly limit: (
       limit: number,
-    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'limit' | 'offset' | 'first' | 'orderBy', TQueryInfo>
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'limit' | 'offset' | 'first' | 'orderBy' | 'returning' | 'onConflict'
+    >
 
     /**
      * Example:
      * ```ts
      * db.todos.first()
+     * db.todos.where('id', '123').first()
      * ```
+     *
+     * Query will fail if no rows are returned and no fallback is provided.
      */
-    readonly first: <TFallback extends GetSingle<TResult> = never>(options?: {
-      fallback?: () => TFallback
+    readonly first: <TFallback = never>(options?: {
+      fallback?: () => TFallback | GetSingle<TResult>
     }) => QueryBuilder<
       TFallback | GetSingle<TResult>,
       TTableDef,
-      TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where',
-      TQueryInfo
+      TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where' | 'returning' | 'onConflict'
+    >
+
+    /**
+     * Insert a new row into the table
+     *
+     * Example:
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' })
+     * ```
+     */
+    readonly insert: (
+      values: TTableDef['insertSchema']['Type'],
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where'
+    >
+
+    /**
+     * Example: If the row already exists, it will be ignored.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')
+     * ```
+     *
+     * Example: If the row already exists, it will be replaced.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')
+     * ```
+     *
+     * Example: If the row already exists, it will be updated.
+     * ```ts
+     * 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.
+     */
+    readonly onConflict: {
+      <TTarget extends SingleOrReadonlyArray<keyof TTableDef['sqliteDef']['columns']>>(
+        target: TTarget,
+        action: 'ignore' | 'replace',
+      ): QueryBuilder<
+        TResult,
+        TTableDef,
+        TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where'
+      >
+      <TTarget extends SingleOrReadonlyArray<keyof TTableDef['sqliteDef']['columns']>>(
+        target: TTarget,
+        action: 'update',
+        updateValues: Partial<TTableDef['rowSchema']['Type']>,
+      ): QueryBuilder<
+        TResult,
+        TTableDef,
+        TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where'
+      >
+    }
+
+    /**
+     * Similar to the `.select` API but for write queries (insert, update, delete).
+     *
+     * Example:
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id')
+     * ```
+     */
+    readonly returning: <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
+      ...columns: TColumns[]
+    ) => QueryBuilder<
+      ReadonlyArray<{
+        readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
+      }>,
+      TTableDef
+    >
+
+    /**
+     * Update rows in the table that match the where clause
+     *
+     * Example:
+     * ```ts
+     * db.todos.update({ status: 'completed' }).where({ id: '123' })
+     * ```
+     */
+    readonly update: (
+      values: Partial<TTableDef['rowSchema']['Type']>,
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'onConflict'
     >
 
     /**
-     * Gets a single row from the table and will create it if it doesn't exist yet.
+     * Delete rows from the table that match the where clause
+     *
+     * Example:
+     * ```ts
+     * db.todos.delete().where({ status: 'completed' })
+     * ```
+     *
+     * Note that it's generally recommended to do soft-deletes for synced apps.
      */
-    // TODO maybe call `getsert`?
-    readonly row: TTableDef['options']['isSingleton'] extends true
-      ? () => QueryBuilder<RowQuery.Result<TTableDef>, TTableDef, QueryBuilder.ApiFeature, QueryInfo.Row>
-      : TTableDef['options']['deriveMutations']['enabled'] extends false
-        ? (_: 'Error: Need to enable deriveMutations to use row()') => any
-        : TTableDef['options']['requiredInsertColumnNames'] extends never
-          ? (
-              id: string | SessionIdSymbol,
-            ) => QueryBuilder<RowQuery.Result<TTableDef>, TTableDef, QueryBuilder.ApiFeature, QueryInfo.Row>
-          : <TOptions extends RowQuery.RequiredColumnsOptions<TTableDef>>(
-              id: string | SessionIdSymbol,
-              opts: TOptions,
-            ) => QueryBuilder<RowQuery.Result<TTableDef>, TTableDef, QueryBuilder.ApiFeature, QueryInfo.Row>
+    readonly delete: () => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'onConflict'
+    >
   }
 }
 
 export namespace RowQuery {
-  export type RequiredColumnsOptions<TTableDef extends DbSchema.TableDefBase> = {
+  export type GetOrCreateOptions<TTableDef extends ClientDocumentTableDef.TraitAny> = {
+    default: Partial<TTableDef['Value']>
+  }
+
+  // TODO get rid of this
+  export type RequiredColumnsOptions<TTableDef extends State.SQLite.TableDefBase> = {
     /**
      * Values to be inserted into the row if it doesn't exist yet
      */
-    insertValues: Pick<
+    explicitDefaultValues: Pick<
       SqliteDsl.FromColumns.RowDecodedAll<TTableDef['sqliteDef']['columns']>,
       SqliteDsl.FromColumns.RequiredInsertColumnNames<Omit<TTableDef['sqliteDef']['columns'], 'id'>>
     >
   }
 
-  export type Result<TTableDef extends DbSchema.TableDefBase> = TTableDef['options']['isSingleColumn'] extends true
-    ? GetValForKey<SqliteDsl.FromColumns.RowDecoded<TTableDef['sqliteDef']['columns']>, 'value'>
-    : SqliteDsl.FromColumns.RowDecoded<TTableDef['sqliteDef']['columns']>
+  export type Result<TTableDef extends State.SQLite.TableDefBase> = SqliteDsl.FromColumns.RowDecoded<
+    TTableDef['sqliteDef']['columns']
+  >
+
+  export type DocumentResult<TTableDef extends ClientDocumentTableDef.Any> = GetValForKey<
+    SqliteDsl.FromColumns.RowDecoded<TTableDef['sqliteDef']['columns']>,
+    'value'
+  >
 
-  export type ResultEncoded<TTableDef extends DbSchema.TableDefBase> =
-    TTableDef['options']['isSingleColumn'] extends true
+  export type ResultEncoded<TTableDef extends State.SQLite.TableDefBase> =
+    TTableDef['options']['isClientDocumentTable'] extends true
       ? GetValForKey<SqliteDsl.FromColumns.RowEncoded<TTableDef['sqliteDef']['columns']>, 'value'>
       : SqliteDsl.FromColumns.RowEncoded<TTableDef['sqliteDef']['columns']>
+
+  export type GetIdColumnType<TTableDef extends State.SQLite.TableDefBase> =
+    TTableDef['sqliteDef']['columns']['id']['schema']['Type']
 }
 
 type GetSingle<T> = T extends ReadonlyArray<infer U> ? U : never
-
-// export type QueryBuilderParamRef = { _tag: 'QueryBuilderParamRef' }
-// export type QueryBuilderSelectParams = { [key: string]: QueryBuilderSelectParam }
-// export type QueryBuilderSelectParam = boolean | ((ref: QueryBuilderParamRef) => QueryBuilder<any, any>)