@livestore/common 0.3.0-dev.27 → 0.3.0-dev.29

package/src/schema/table-def.ts

@@ -1,12 +1,8 @@
-import type { Nullable } from '@livestore/utils'
-import { shouldNeverHappen } from '@livestore/utils'
-import type { Types } from '@livestore/utils/effect'
-import { ReadonlyRecord, Schema } from '@livestore/utils/effect'
+import { type Nullable } from '@livestore/utils'
+import type { Schema, Types } from '@livestore/utils/effect'
 
-import type { DerivedMutationHelperFns } from '../derived-mutations.js'
-import { makeDerivedMutationDefsForTable } from '../derived-mutations.js'
 import type { QueryBuilder } from '../query-builder/mod.js'
-import { makeQueryBuilder } from '../query-builder/mod.js'
+import { makeQueryBuilder, QueryBuilderAstSymbol, QueryBuilderTypeId } from '../query-builder/mod.js'
 import { SqliteDsl } from './db-schema/mod.js'
 
 export const { blob, boolean, column, datetime, integer, isColumnDefinition, json, real, text } = SqliteDsl
@@ -16,6 +12,10 @@ export type StateType = 'singleton' | 'dynamic'
 export type DefaultSqliteTableDef = SqliteDsl.TableDefinition<string, SqliteDsl.Columns>
 export type DefaultSqliteTableDefConstrained = SqliteDsl.TableDefinition<string, SqliteDsl.ConstraintColumns>
 
+// TODO use to hide table def internals
+export const TableDefInternalsSymbol = Symbol('TableDefInternals')
+export type TableDefInternalsSymbol = typeof TableDefInternalsSymbol
+
 export type TableDefBase<
   TSqliteDef extends DefaultSqliteTableDef = DefaultSqliteTableDefConstrained,
   TOptions extends TableOptions = TableOptions,
@@ -23,7 +23,7 @@ export type TableDefBase<
   sqliteDef: TSqliteDef
   options: TOptions
   // Derived from `sqliteDef`, so only exposed for convenience
-  schema: SqliteDsl.StructSchemaForColumns<TSqliteDef['columns']>
+  rowSchema: SqliteDsl.StructSchemaForColumns<TSqliteDef['columns']>
   insertSchema: SqliteDsl.InsertStructSchemaForColumns<TSqliteDef['columns']>
 }
 
@@ -46,249 +46,74 @@ export type TableDef<
   sqliteDef: TSqliteDef
   options: TOptions
   // Derived from `sqliteDef`, so only exposed for convenience
-  schema: TSchema
+  rowSchema: TSchema
   insertSchema: SqliteDsl.InsertStructSchemaForColumns<TSqliteDef['columns']>
-  query: QueryBuilder<ReadonlyArray<Schema.Schema.Type<TSchema>>, TableDefBase<TSqliteDef & {}, TOptions>>
+  // query: QueryBuilder<ReadonlyArray<Schema.Schema.Type<TSchema>>, TableDefBase<TSqliteDef & {}, TOptions>>
   readonly Type: Schema.Schema.Type<TSchema>
   readonly Encoded: Schema.Schema.Encoded<TSchema>
-} & (TOptions['deriveMutations']['enabled'] extends true
-  ? DerivedMutationHelperFns<TSqliteDef['columns'], TOptions>
-  : {})
+} & QueryBuilder<ReadonlyArray<Schema.Schema.Type<TSchema>>, TableDefBase<TSqliteDef & {}, TOptions>>
 
 export type TableOptionsInput = Partial<{
   indexes: SqliteDsl.Index[]
-  disableAutomaticIdColumn: boolean
-  isSingleton: boolean
-  deriveMutations:
-    | boolean
-    | {
-        clientOnly?: boolean
-      }
 }>
 
-type ToColumns<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>> =
-  TColumns extends SqliteDsl.Columns
-    ? TColumns
-    : TColumns extends SqliteDsl.ColumnDefinition<any, any>
-      ? { value: TColumns }
-      : never
-
-type ValidateTableOptionsInput<
-  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
-  TOptionsInput extends TableOptionsInput,
-  TPassthroughIfValid,
-> =
-  SqliteDsl.FromColumns.RequiresInsertValues<ToColumns<TColumns>> extends true
-    ? TOptionsInput['isSingleton'] extends true
-      ? 'Error: To use `isSingleton: true` with this table, each column must have a default value or be nullable'
-      : TPassthroughIfValid
-    : TPassthroughIfValid
+export namespace TableDef {
+  export type Any = TableDef<any, any>
+}
 
 export type TableOptions = {
-  /**
-   * Setting this to true will have the following consequences:
-   * - An `id` column will be added with `primaryKey: true` and `"singleton"` as default value and only allowed value
-   * - LiveStore will automatically create the singleton row when booting up
-   * - LiveStore will fail if there is already a column defined with `primaryKey: true`
-   *
-   * @default false
-   */
-  readonly isSingleton: boolean
-
-  readonly disableAutomaticIdColumn: boolean
-
-  /**
-   * Setting this to true will automatically derive insert, update and delete mutations for this table. Example:
-   *
-   * ```ts
-   * const todos = table('todos', { ... }, { deriveMutations: true })
-   * todos.insert({ id: '1', text: 'Hello' })
-   * ```
-   *
-   * This is also a prerequisite for using the `useRow`, `useAtom` and `rowQuery` APIs.
-   *
-   * Important: When using this option, make sure you're following the "Rules of mutations" for the table schema.
-   */
-  readonly deriveMutations:
-    | { enabled: false }
-    | {
-        enabled: true
-        /**
-         * When set to true, the mutations won't be synced over the network
-         */
-        clientOnly: boolean
-      }
-
   /** Derived based on whether the table definition has one or more columns (besides the `id` column) */
-  readonly isSingleColumn: boolean
-
-  /**
-   * Derived based on whether the table definition has one or more columns (besides the `id` column) that require
-   * insert values (i.e. are not nullable and don't have a default value)
-   *
-   * `isSingleton` tables always imply `requiresInsertValues: false`
-   */
-  readonly requiredInsertColumnNames: string
+  readonly isClientDocumentTable: boolean
 }
 
 export const table = <
   TName extends string,
   TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
-  TOptionsInput extends TableOptionsInput = TableOptionsInput,
+  const TOptionsInput extends TableOptionsInput = TableOptionsInput,
 >(
-  name: TName,
-  columnOrColumns: TColumns,
-  options?: TOptionsInput,
-): ValidateTableOptionsInput<
-  TColumns,
-  TOptionsInput,
-  TableDef<
-    SqliteTableDefForInput<TName, TColumns, WithDefaults<TOptionsInput, TColumns>>,
-    WithDefaults<TOptionsInput, TColumns>
-  >
-> => {
+  args: {
+    name: TName
+    columns: TColumns
+  } & Partial<TOptionsInput>,
+): TableDef<SqliteTableDefForInput<TName, TColumns>, WithDefaults<TColumns>> => {
+  const { name, columns: columnOrColumns, ...options } = args
   const tablePath = name
 
   const options_: TableOptions = {
-    isSingleton: options?.isSingleton ?? false,
-    disableAutomaticIdColumn: options?.disableAutomaticIdColumn ?? false,
-    deriveMutations:
-      options?.deriveMutations === true
-        ? { enabled: true as const, clientOnly: false }
-        : options?.deriveMutations === false
-          ? { enabled: false as const }
-          : options?.deriveMutations === undefined
-            ? { enabled: false as const }
-            : { enabled: true as const, clientOnly: options.deriveMutations.clientOnly ?? false },
-    isSingleColumn: SqliteDsl.isColumnDefinition(columnOrColumns) === true,
-    requiredInsertColumnNames: 'type-level-only',
+    isClientDocumentTable: false,
   }
 
   const columns = (
     SqliteDsl.isColumnDefinition(columnOrColumns) ? { value: columnOrColumns } : columnOrColumns
   ) as SqliteDsl.Columns
 
-  if (options_.disableAutomaticIdColumn === true) {
-    if (columns.id === undefined && options_.isSingleton === true) {
-      shouldNeverHappen(
-        `Cannot create table ${name} with "isSingleton: true" because there is no column with name "id" and "disableAutomaticIdColumn: true" is set`,
-      )
-    }
-  } else if (columns.id === undefined && ReadonlyRecord.some(columns, (_) => _.primaryKey === true) === false) {
-    if (options_.isSingleton) {
-      columns.id = SqliteDsl.text({ schema: Schema.Literal('singleton'), primaryKey: true, default: 'singleton' })
-    } else {
-      columns.id = SqliteDsl.text({ primaryKey: true })
-    }
-  }
-
   const sqliteDef = SqliteDsl.table(tablePath, columns, options?.indexes ?? [])
 
-  // TODO also enforce this on the type level
-  if (options_.isSingleton) {
-    for (const column of sqliteDef.ast.columns) {
-      if (column.nullable === false && column.default._tag === 'None') {
-        shouldNeverHappen(
-          `When creating a singleton table, each column must be either nullable or have a default value. Column '${column.name}' is neither.`,
-        )
-      }
-    }
-  }
-
-  const isSingleColumn = SqliteDsl.isColumnDefinition(columnOrColumns) === true
-
-  const schema = SqliteDsl.structSchemaForTable(sqliteDef)
+  const rowSchema = SqliteDsl.structSchemaForTable(sqliteDef)
   const insertSchema = SqliteDsl.insertStructSchemaForTable(sqliteDef)
   const tableDef = {
     sqliteDef,
     options: options_,
-    schema,
+    rowSchema,
     insertSchema,
   } satisfies TableDefBase
 
   const query = makeQueryBuilder(tableDef)
-  // const tableDef = { ...tableDefBase, query } satisfies TableDef
+  // tableDef.query = query
 
   // NOTE we're currently patching the existing tableDef object
   // as it's being used as part of the query builder API
-  // @ts-expect-error TODO properly implement this
-  tableDef.query = query
-
-  if (tableHasDerivedMutations(tableDef)) {
-    const derivedMutationDefs = makeDerivedMutationDefsForTable(tableDef)
-
-    tableDef.insert = (valuesOrValue: any) => {
-      if (isSingleColumn && options_.isSingleton) {
-        return derivedMutationDefs.insert({ id: 'singleton', value: { value: valuesOrValue } })
-      } else {
-        return derivedMutationDefs.insert(valuesOrValue as any)
-      }
-    }
-
-    tableDef.update = (argsOrValues: any) => {
-      if (isSingleColumn && options_.isSingleton) {
-        return derivedMutationDefs.update({ where: { id: 'singleton' }, values: { value: argsOrValues } as any })
-      } else {
-        return derivedMutationDefs.update(argsOrValues as any)
-      }
-    }
-
-    tableDef.delete = (args: any) => derivedMutationDefs.delete(args)
+  for (const key of Object.keys(query)) {
+    // @ts-expect-error TODO properly implement this
+    tableDef[key] = query[key]
   }
 
-  return tableDef as any
-}
-
-export const tableHasDerivedMutations = <TTableDef extends TableDefBase>(
-  tableDef: TTableDef,
-): tableDef is TTableDef & {
-  options: { deriveMutations: { enabled: true; clientOnly: boolean } }
-} & DerivedMutationHelperFns<TTableDef['sqliteDef']['columns'], TTableDef['options']> =>
-  tableDef.options.deriveMutations.enabled === true
-
-export const tableIsSingleton = <TTableDef extends TableDefBase>(
-  tableDef: TTableDef,
-): tableDef is TTableDef & { options: { isSingleton: true } } => tableDef.options.isSingleton === true
-
-export type PrettifyFlat<T> = T extends infer U ? { [K in keyof U]: U[K] } : never
+  // @ts-expect-error TODO properly type this
+  tableDef[QueryBuilderAstSymbol] = query[QueryBuilderAstSymbol]
+  // @ts-expect-error TODO properly type this
+  tableDef[QueryBuilderTypeId] = query[QueryBuilderTypeId]
 
-type SqliteTableDefForInput<
-  TName extends string,
-  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
-  TOptions extends TableOptions,
-> = SqliteDsl.TableDefinition<TName, PrettifyFlat<WithId<ToColumns<TColumns>, TOptions>>>
-
-type WithId<TColumns extends SqliteDsl.Columns, TOptions extends TableOptions> = TColumns &
-  ('id' extends keyof TColumns
-    ? {}
-    : TOptions['disableAutomaticIdColumn'] extends true
-      ? {}
-      : TOptions['isSingleton'] extends true
-        ? {
-            id: SqliteDsl.ColumnDefinition<'singleton', 'singleton'>
-          }
-        : {
-            id: SqliteDsl.ColumnDefinition<string, string>
-          })
-
-type WithDefaults<
-  TOptionsInput extends TableOptionsInput,
-  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
-> = {
-  isSingleton: TOptionsInput['isSingleton'] extends true ? true : false
-  disableAutomaticIdColumn: TOptionsInput['disableAutomaticIdColumn'] extends true ? true : false
-  deriveMutations: TOptionsInput['deriveMutations'] extends true
-    ? { enabled: true; clientOnly: false }
-    : TOptionsInput['deriveMutations'] extends false
-      ? { enabled: false }
-      : TOptionsInput['deriveMutations'] extends { clientOnly: boolean }
-        ? {
-            enabled: true
-            clientOnly: TOptionsInput['deriveMutations']['clientOnly'] extends true ? true : false
-          }
-        : never
-  isSingleColumn: SqliteDsl.IsSingleColumn<TColumns>
-  requiredInsertColumnNames: SqliteDsl.FromColumns.RequiredInsertColumnNames<ToColumns<TColumns>>
+  return tableDef as any
 }
 
 export namespace FromTable {
@@ -351,3 +176,22 @@ export namespace FromColumns {
 
   export type InsertRowDecoded<TColumns extends SqliteDsl.Columns> = SqliteDsl.FromColumns.InsertRowDecoded<TColumns>
 }
+
+type SqliteTableDefForInput<
+  TName extends string,
+  TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
+> = SqliteDsl.TableDefinition<TName, PrettifyFlat<ToColumns<TColumns>>>
+
+type WithDefaults<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, 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>> =
+  TColumns extends SqliteDsl.Columns
+    ? TColumns
+    : TColumns extends SqliteDsl.ColumnDefinition<any, any>
+      ? { value: TColumns }
+      : never

package/src/schema/view.ts

@@ -0,0 +1,2 @@
+export * as SQLite from './sqlite-state.js'
+export { QueryBuilderAstSymbol, QueryBuilderTypeId } from '../query-builder/mod.js'

package/src/schema-management/common.ts

@@ -33,12 +33,12 @@ export const dbSelect = <T>(db: SqliteDb, queryStr: string, bindValues?: ParamsO
 }
 
 export interface SchemaManager {
-  getMutationDefInfos: () => ReadonlyArray<MutationDefInfo>
+  getEventDefInfos: () => ReadonlyArray<EventDefInfo>
 
-  setMutationDefInfo: (mutationDefInfo: MutationDefInfo) => void
+  setEventDefInfo: (eventDefInfo: EventDefInfo) => void
 }
 
-export type MutationDefInfo = {
-  mutationName: string
+export type EventDefInfo = {
+  eventName: string
   schemaHash: number
 }

package/src/schema-management/migrations.ts

@@ -4,12 +4,12 @@ import { Effect, Schema as EffectSchema } from '@livestore/utils/effect'
 import type { MigrationsReport, MigrationsReportEntry, SqliteDb, UnexpectedError } from '../adapter-types.js'
 import { SqliteAst, SqliteDsl } from '../schema/db-schema/mod.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
-import type { SchemaMetaRow, SchemaMutationsMetaRow } from '../schema/system-tables.js'
+import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/system-tables.js'
 import {
+  SCHEMA_EVENT_DEFS_META_TABLE,
   SCHEMA_META_TABLE,
-  SCHEMA_MUTATIONS_META_TABLE,
+  schemaEventDefsMetaTable,
   schemaMetaTable,
-  schemaMutationsMetaTable,
   systemTables,
 } from '../schema/system-tables.js'
 import { sql } from '../util.js'
@@ -23,20 +23,19 @@ export const makeSchemaManager = (db: SqliteDb): Effect.Effect<SchemaManager> =>
   Effect.gen(function* () {
     yield* migrateTable({
       db,
-      tableAst: schemaMutationsMetaTable.sqliteDef.ast,
+      tableAst: schemaEventDefsMetaTable.sqliteDef.ast,
       behaviour: 'create-if-not-exists',
     })
 
     return {
-      getMutationDefInfos: () =>
-        dbSelect<SchemaMutationsMetaRow>(db, sql`SELECT * FROM ${SCHEMA_MUTATIONS_META_TABLE}`),
+      getEventDefInfos: () => dbSelect<SchemaEventDefsMetaRow>(db, sql`SELECT * FROM ${SCHEMA_EVENT_DEFS_META_TABLE}`),
 
-      setMutationDefInfo: (info) => {
+      setEventDefInfo: (info) => {
         dbExecute(
           db,
-          sql`INSERT OR REPLACE INTO ${SCHEMA_MUTATIONS_META_TABLE} (mutationName, schemaHash, updatedAt) VALUES ($mutationName, $schemaHash, $updatedAt)`,
+          sql`INSERT OR REPLACE INTO ${SCHEMA_EVENT_DEFS_META_TABLE} (eventName, schemaHash, updatedAt) VALUES ($eventName, $schemaHash, $updatedAt)`,
           {
-            mutationName: info.mutationName,
+            eventName: info.eventName,
             schemaHash: info.schemaHash,
             updatedAt: new Date().toISOString(),
           },

package/src/schema-management/validate-mutation-defs.ts

@@ -1,63 +1,61 @@
 import { Effect, Schema } from '@livestore/utils/effect'
 
 import { UnexpectedError } from '../adapter-types.js'
+import type { EventDef } from '../schema/EventDef.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
-import type { MutationDef } from '../schema/mutations.js'
-import type { MutationDefInfo, SchemaManager } from './common.js'
+import type { EventDefInfo, SchemaManager } from './common.js'
 
 export const validateSchema = (schema: LiveStoreSchema, schemaManager: SchemaManager) =>
   Effect.gen(function* () {
     // Validate mutation definitions
-    const registeredMutationDefInfos = schemaManager.getMutationDefInfos()
+    const registeredEventDefInfos = schemaManager.getEventDefInfos()
 
-    const missingMutationDefs = registeredMutationDefInfos.filter(
-      (registeredMutationDefInfo) => !schema.mutations.map.has(registeredMutationDefInfo.mutationName),
+    const missingEventDefs = registeredEventDefInfos.filter(
+      (registeredEventDefInfo) => !schema.eventsDefsMap.has(registeredEventDefInfo.eventName),
     )
 
-    if (missingMutationDefs.length > 0) {
+    if (missingEventDefs.length > 0) {
       yield* new UnexpectedError({
-        cause: `Missing mutation definitions: ${missingMutationDefs.map((info) => info.mutationName).join(', ')}`,
+        cause: `Missing mutation definitions: ${missingEventDefs.map((info) => info.eventName).join(', ')}`,
       })
     }
 
-    for (const [, mutationDef] of schema.mutations.map) {
-      const registeredMutationDefInfo = registeredMutationDefInfos.find(
-        (info) => info.mutationName === mutationDef.name,
-      )
+    for (const [, eventDef] of schema.eventsDefsMap) {
+      const registeredEventDefInfo = registeredEventDefInfos.find((info) => info.eventName === eventDef.name)
 
-      validateMutationDef(mutationDef, schemaManager, registeredMutationDefInfo)
+      validateEventDef(eventDef, schemaManager, registeredEventDefInfo)
     }
 
     // Validate table schemas
   })
 
-export const validateMutationDef = (
-  mutationDef: MutationDef.Any,
+export const validateEventDef = (
+  eventDef: EventDef.AnyWithoutFn,
   schemaManager: SchemaManager,
-  registeredMutationDefInfo: MutationDefInfo | undefined,
+  registeredEventDefInfo: EventDefInfo | undefined,
 ) => {
-  const schemaHash = Schema.hash(mutationDef.schema)
+  const schemaHash = Schema.hash(eventDef.schema)
 
-  if (registeredMutationDefInfo === undefined) {
-    schemaManager.setMutationDefInfo({
+  if (registeredEventDefInfo === undefined) {
+    schemaManager.setEventDefInfo({
       schemaHash,
-      mutationName: mutationDef.name,
+      eventName: eventDef.name,
     })
 
     return
   }
 
-  if (schemaHash === registeredMutationDefInfo.schemaHash) return
+  if (schemaHash === registeredEventDefInfo.schemaHash) return
 
   // TODO bring back some form of schema compatibility check (see https://github.com/livestorejs/livestore/issues/69)
-  // const newSchemaIsCompatibleWithOldSchema = Schema.isSubType(jsonSchemaDefFromMgmtStore, mutationDef.schema)
+  // const newSchemaIsCompatibleWithOldSchema = Schema.isSubType(jsonSchemaDefFromMgmtStore, eventDef.schema)
 
   // if (!newSchemaIsCompatibleWithOldSchema) {
-  //   shouldNeverHappen(`Schema for mutation ${mutationDef.name} has changed in an incompatible way`)
+  //   shouldNeverHappen(`Schema for mutation ${eventDef.name} has changed in an incompatible way`)
   // }
 
-  schemaManager.setMutationDefInfo({
+  schemaManager.setEventDefInfo({
     schemaHash,
-    mutationName: mutationDef.name,
+    eventName: eventDef.name,
   })
 }