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

package/src/session-id-symbol.ts

@@ -0,0 +1,59 @@
+/**
+ * SessionIdSymbol is a user-facing placeholder for "the current client session".
+ * User code can keep using the same event/query object across sessions, while the
+ * storage and eventlog layers require concrete string ids. Resolving the symbol at
+ * those boundaries preserves the symbolic API without mutating caller-owned values.
+ *
+ * @module
+ */
+import { Predicate } from '@livestore/utils/effect'
+
+import type { Bindable, SqlValue } from './util.ts'
+
+/**
+ * Can be used in queries to refer to the current session id.
+ * Will be replaced with the actual session id at runtime.
+ *
+ * In client document table:
+ * ```ts
+ * const uiState = State.SQLite.clientDocument({
+ *   name: 'ui_state',
+ *   schema: Schema.Struct({
+ *     theme: Schema.Literals(['dark', 'light', 'system']),
+ *     user: Schema.String,
+ *     showToolbar: Schema.Boolean,
+ *   }),
+ *   default: { value: defaultFrontendState, id: SessionIdSymbol },
+ * })
+ * ```
+ *
+ * Or in a client document query:
+ * ```ts
+ * const query$ = queryDb(tables.uiState.get(SessionIdSymbol))
+ * ```
+ */
+export const SessionIdSymbol = Symbol.for('@livestore/session-id')
+export type SessionIdSymbol = typeof SessionIdSymbol
+
+export type BindableWithSessionIdSymbol =
+  | ReadonlyArray<SqlValue | SessionIdSymbol>
+  | Record<string, SqlValue | SessionIdSymbol>
+
+export const resolveSessionIdSymbolInBindValues = (
+  bindValues: BindableWithSessionIdSymbol,
+  sessionId: string,
+): Bindable => {
+  return Array.isArray(bindValues) === true
+    ? bindValues.map((value) => (value === SessionIdSymbol ? sessionId : value))
+    : (Object.fromEntries(
+        Object.entries(bindValues).map(([key, value]) => [key, value === SessionIdSymbol ? sessionId : value]),
+      ) as Record<string, SqlValue>)
+}
+
+export const resolveSessionIdSymbolInEventArgs = (args: unknown, sessionId: string): unknown => {
+  if (Predicate.hasProperty(args, 'id') === false) {
+    return args
+  }
+
+  return args.id === SessionIdSymbol ? { ...args, id: sessionId } : args
+}

package/src/sql-queries/sql-queries.ts

@@ -1,9 +1,8 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import { pipe, ReadonlyArray, Schema, TreeFormatter } from '@livestore/utils/effect'
+import { pipe, ReadonlyArray, ReadonlyRecord, Result, Schema, SchemaIssue } from '@livestore/utils/effect'
 
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 import { sql } from '../util.ts'
-import { objectEntries } from './misc.ts'
 import * as ClientTypes from './types.ts'
 
 export type BindValues = {
@@ -23,7 +22,7 @@ export const findManyRows = <TColumns extends SqliteDsl.Columns>({
 }): [string, BindValues] => {
   const whereSql = buildWhereSql({ where })
   const whereModifier = whereSql === '' ? '' : `WHERE ${whereSql}`
-  const limitModifier = limit ? `LIMIT ${limit}` : ''
+  const limitModifier = limit !== undefined ? `LIMIT ${limit}` : ''
 
   const whereBindValues = makeBindValues({ columns, values: where, variablePrefix: 'where_', skipNil: true })
 
@@ -80,7 +79,7 @@ export const insertRowPrepared = <TColumns extends SqliteDsl.Columns>({
   const keysStr = keys.join(', ')
   const valuesStr = keys.map((key) => `$${key}`).join(', ')
 
-  return sql`INSERT ${options.orReplace ? 'OR REPLACE ' : ''}INTO ${tableName} (${keysStr}) VALUES (${valuesStr})`
+  return sql`INSERT ${options.orReplace === true ? 'OR REPLACE ' : ''}INTO ${tableName} (${keysStr}) VALUES (${valuesStr})`
 }
 
 export const insertRows = <TColumns extends SqliteDsl.Columns>({
@@ -106,7 +105,6 @@ export const insertRows = <TColumns extends SqliteDsl.Columns>({
 
   const bindValues = valuesArray.reduce(
     (acc, values, itemIndex) => ({
-      // biome-ignore lint/performance/noAccumulatingSpread: TODO improve this some day
       ...acc,
       ...makeBindValues({ columns, values, variablePrefix: `item_${itemIndex}_` }),
     }),
@@ -134,7 +132,7 @@ export const insertOrIgnoreRow = <TColumns extends SqliteDsl.Columns>({
     .join(', ')
 
   const bindValues = makeBindValues({ columns, values })
-  const returningStmt = returnRow ? 'RETURNING *' : ''
+  const returningStmt = returnRow === true ? 'RETURNING *' : ''
 
   return [sql`INSERT OR IGNORE INTO ${tableName} (${keysStr}) VALUES (${valuesStr}) ${returningStmt}`, bindValues]
 }
@@ -247,7 +245,15 @@ export const createTable = ({
     .map(([columnName, _]) => columnName)
   const columnDefStrs = Object.entries(table.columns).map(([columnName, columnDef]) => {
     const nullModifier = columnDef.nullable === true ? '' : 'NOT NULL'
-    const defaultModifier = columnDef.default._tag === 'None' ? '' : `DEFAULT ${columnDef.default.value}`
+    const defaultModifier = (() => {
+      if (columnDef.default._tag === 'None') return ''
+      const defaultValue = columnDef.default.value
+      if (typeof defaultValue === 'function') return ''
+      if (defaultValue !== undefined && typeof defaultValue === 'object' && 'sql' in defaultValue) {
+        return `DEFAULT ${defaultValue.sql}`
+      }
+      return `DEFAULT ${defaultValue}`
+    })()
     return sql`${columnName} ${columnDef.columnType} ${nullModifier} ${defaultModifier}`
   })
 
@@ -271,15 +277,14 @@ export const makeBindValues = <TColumns extends SqliteDsl.Columns, TKeys extends
   skipNil?: boolean
 }): Record<string, any> => {
   const codecMap = pipe(
-    columns,
-    objectEntries,
+    ReadonlyRecord.toEntries(columns),
     ReadonlyArray.map(([columnName, columnDef]) => [
       columnName,
       (value: any) => {
         if (columnDef.nullable === true && (value === null || value === undefined)) return null
-        const res = Schema.encodeEither(columnDef.schema)(value)
-        if (res._tag === 'Left') {
-          const parseErrorStr = TreeFormatter.formatErrorSync(res.left)
+        const res = Schema.encodeResult(columnDef.schema)(value)
+        if (Result.isFailure(res) === true) {
+          const parseErrorStr = SchemaIssue.makeFormatterDefault()(res.failure.issue)
           const expectedSchemaStr = String(columnDef.schema.ast)
 
           console.error(
@@ -293,11 +298,11 @@ Error: ${parseErrorStr}
 Value:`,
             value,
           )
-          // biome-ignore lint/suspicious/noDebugger: debug
+          // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for SQL decode errors
           debugger
-          throw res.left
+          throw res.failure
         } else {
-          return res.right
+          return res.success
         }
       },
     ]),
@@ -341,7 +346,11 @@ const buildWhereSql = <TColumns extends SqliteDsl.Columns>({
   const getWhereOp = (columnName: string, value: ClientTypes.WhereValueForDecoded<any>) => {
     if (value === null) {
       return `IS NULL`
-    } else if (typeof value === 'object' && typeof value.op === 'string' && ClientTypes.isValidWhereOp(value.op)) {
+    } else if (
+      typeof value === 'object' &&
+      typeof value.op === 'string' &&
+      ClientTypes.isValidWhereOp(value.op) === true
+    ) {
       return `${value.op} $where_${columnName}`
     } else if (typeof value === 'object' && typeof value.op === 'string' && value.op === 'in') {
       return `in (${value.val.map((_: any, i: number) => `$where_${columnName}_${i}`).join(', ')})`
@@ -351,8 +360,7 @@ const buildWhereSql = <TColumns extends SqliteDsl.Columns>({
   }
 
   return pipe(
-    where,
-    objectEntries,
+    ReadonlyRecord.toEntries(where),
     ReadonlyArray.map(([columnName, value]) => `${columnName} ${getWhereOp(columnName, value)}`),
     ReadonlyArray.join(' AND '),
   )

package/src/sql-queries/sql-query-builder.ts

@@ -1,4 +1,5 @@
 import { omitUndefineds } from '@livestore/utils'
+
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 import type { BindValues } from './sql-queries.ts'
 import * as SqlQueries from './sql-queries.ts'

package/src/sql-queries/types.ts

@@ -1,16 +1,15 @@
-import type { Prettify } from '@livestore/utils'
-import type { Schema } from '@livestore/utils/effect'
+import type { Schema, Types } from '@livestore/utils/effect'
 
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 
 export type DecodedValuesForTableAll<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = {
-  [K in keyof GetColumns<TSchema, TTableName>]: Schema.Schema.Type<GetColumn<TSchema, TTableName, K>['schema']>
+  [K in keyof GetColumns<TSchema, TTableName>]: GetColumn<TSchema, TTableName, K>['schema']['Type']
 }
 
 export type DecodedValuesForTablePretty<
   TSchema extends SqliteDsl.DbSchema,
   TTableName extends keyof TSchema,
-> = Prettify<DecodedValuesForTable<TSchema, TTableName>>
+> = Types.Simplify<DecodedValuesForTable<TSchema, TTableName>>
 
 export type DecodedValuesForTable<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = Partial<
   Pick<DecodedValuesForTableAll<TSchema, TTableName>, GetNullableColumnNamesForTable<TSchema, TTableName>>
@@ -40,7 +39,7 @@ export const isValidWhereOp = (op: string): op is WhereOp => {
 }
 
 export type EncodedValuesForTableAll<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = {
-  [K in keyof GetColumns<TSchema, TTableName>]: Schema.Schema.Type<GetColumn<TSchema, TTableName, K>['schema']>
+  [K in keyof GetColumns<TSchema, TTableName>]: GetColumn<TSchema, TTableName, K>['schema']['Type']
 }
 
 export type EncodedValuesForTable<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = Partial<
@@ -69,7 +68,7 @@ export type GetColumn<
 > = TSchema[TTableName]['columns'][TColumnName]
 
 export type DecodedValuesForColumnsAll<TColumns extends SqliteDsl.Columns> = {
-  [K in keyof TColumns]: Schema.Schema.Type<TColumns[K]['schema']>
+  [K in keyof TColumns]: TColumns[K]['schema']['Type']
 }
 
 export type DecodedValuesForColumns<TColumns extends SqliteDsl.Columns> = Partial<
@@ -78,7 +77,7 @@ export type DecodedValuesForColumns<TColumns extends SqliteDsl.Columns> = Partia
   Omit<DecodedValuesForColumnsAll<TColumns>, GetNullableColumnNames<TColumns>>
 
 export type EncodedValuesForColumnsAll<TColumns extends SqliteDsl.Columns> = {
-  [K in keyof TColumns]: Schema.Schema.Encoded<TColumns[K]['schema']>
+  [K in keyof TColumns]: TColumns[K]['schema']['Encoded']
 }
 
 export type EncodedValuesForColumns<TColumns extends SqliteDsl.Columns> = Partial<

package/src/sqlite-db-helper.ts

@@ -1,4 +1,4 @@
-import { Schema } from '@livestore/utils/effect'
+import { Effect, Exit, Function, Schema } from '@livestore/utils/effect'
 
 import { type SqliteDb, SqliteError } from './adapter-types.ts'
 import { getResultSchema, isQueryBuilder } from './schema/state/sqlite/query-builder/mod.ts'
@@ -14,7 +14,7 @@ export const makeExecute = (
   return (...args: any[]) => {
     const [queryStrOrQueryBuilder, bindValuesOrOptions, maybeOptions] = args
 
-    if (isQueryBuilder(queryStrOrQueryBuilder)) {
+    if (isQueryBuilder(queryStrOrQueryBuilder) === true) {
       const { query, bindValues } = queryStrOrQueryBuilder.asSql()
       return execute(query, bindValues as unknown as PreparedBindValues, bindValuesOrOptions)
     } else {
@@ -29,22 +29,84 @@ export const makeSelect = <T>(
   return (...args: any[]) => {
     const [queryStrOrQueryBuilder, maybeBindValues] = args
 
-    if (isQueryBuilder(queryStrOrQueryBuilder)) {
+    if (isQueryBuilder(queryStrOrQueryBuilder) === true) {
       const { query, bindValues } = queryStrOrQueryBuilder.asSql()
       const resultSchema = getResultSchema(queryStrOrQueryBuilder)
       const results = select(query, bindValues as unknown as PreparedBindValues)
-      return Schema.decodeSync(resultSchema)(results)
+      return Schema.decodeUnknownSync(resultSchema)(results)
     } else {
       return select(queryStrOrQueryBuilder, maybeBindValues)
     }
   }
 }
 
+/**
+ * Runs an Effect inside an SQLite savepoint.
+ *
+ * @remarks
+ *
+ * This starts a savepoint before running `effect`, releases the savepoint on
+ * success, and rolls back to the savepoint before re-emitting the original
+ * failure on failure.
+ *
+ * Use this for atomic DB updates that need to compose with callers that may
+ * already have an open transaction.
+ *
+ * @see {@link https://sqlite.org/lang_savepoint.html | SQLite savepoint documentation}
+ * @see {@link https://sqlite.org/lang_transaction.html | SQLite transaction documentation}
+ */
+export const withSavepoint: {
+  (db: SqliteDb): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqliteError, R>
+  <A, E, R>(self: Effect.Effect<A, E, R>, db: SqliteDb): Effect.Effect<A, E | SqliteError, R>
+} = Function.dual(
+  2,
+  <A, E, R>(self: Effect.Effect<A, E, R>, db: SqliteDb): Effect.Effect<A, E | SqliteError, R> =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.sync(generateSavepointName).pipe(
+        Effect.flatMap((savepointName) => {
+          const savepointSql = `SAVEPOINT ${savepointName}`
+          const releaseSql = `RELEASE SAVEPOINT ${savepointName}`
+
+          return executeSavepointSql(db, savepointSql).pipe(
+            // Cleanup is installed only after SQLite successfully creates the savepoint.
+            Effect.andThen(
+              restore(self).pipe(
+                Effect.exit,
+                Effect.flatMap((exit) => {
+                  const cleanup =
+                    Exit.isSuccess(exit) === true
+                      ? executeSavepointSql(db, releaseSql)
+                      : executeSavepointSql(db, `ROLLBACK TO SAVEPOINT ${savepointName}`).pipe(
+                          Effect.andThen(executeSavepointSql(db, releaseSql)),
+                        )
+
+                  // Cleanup failures supersede the wrapped exit because the connection state is uncertain.
+                  return cleanup.pipe(Effect.andThen(exit))
+                }),
+              ),
+            ),
+          )
+        }),
+      ),
+    ),
+)
+
+let nextSavepointId = 0
+
+/** Uses a reserved prefix and process-local counter to avoid caller-controlled or reused identifiers. */
+const generateSavepointName = () => `livestore_savepoint_${nextSavepointId++}`
+
+const executeSavepointSql = (db: SqliteDb, sql: string): Effect.Effect<void, SqliteError> =>
+  Effect.try({
+    try: () => db.execute(sql),
+    catch: (cause) => new SqliteError({ cause, query: { sql, bindValues: [] } }),
+  })
+
 export const validateSnapshot = (snapshot: Uint8Array) => {
   const headerBytes = new TextDecoder().decode(snapshot.slice(0, 16))
   const hasValidHeader = headerBytes.startsWith('SQLite format 3')
 
-  if (!hasValidHeader) {
+  if (hasValidHeader === false) {
     throw new SqliteError({
       cause: 'Invalid SQLite header',
       note: `Expected header to start with 'SQLite format 3', but got: ${headerBytes}`,

package/src/sqlite-types.ts

@@ -1,5 +1,6 @@
 import { type Effect, Schema } from '@livestore/utils/effect'
-import type { SqliteError, UnexpectedError } from './errors.ts'
+
+import type { SqliteError, UnknownError } from './errors.ts'
 import type { EventSequenceNumber } from './schema/mod.ts'
 import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import type { PreparedBindValues } from './util.ts'
@@ -17,12 +18,12 @@ export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
   prepare(queryStr: string): PreparedStatement
   execute(
     queryStr: string,
-    bindValues?: PreparedBindValues | undefined,
+    bindValues?: PreparedBindValues,
     options?: { onRowsChanged?: (rowsChanged: number) => void },
   ): void
   execute(queryBuilder: QueryBuilder.Any, options?: { onRowsChanged?: (rowsChanged: number) => void }): void
 
-  select<T>(queryStr: string, bindValues?: PreparedBindValues | undefined): ReadonlyArray<T>
+  select<T>(queryStr: string, bindValues?: PreparedBindValues): ReadonlyArray<T>
   select<T>(queryBuilder: QueryBuilder<T, any, any>): T
 
   export(): Uint8Array<ArrayBuffer>
@@ -33,7 +34,7 @@ export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
   makeChangeset: (data: Uint8Array<ArrayBuffer>) => SqliteDbChangeset
 }
 
-export type SqliteDebugInfo = { head: EventSequenceNumber.EventSequenceNumber }
+export type SqliteDebugInfo = { head: EventSequenceNumber.Client.Composite }
 
 // TODO refactor this helper type. It's quite cumbersome to use and should be revisited.
 export type MakeSqliteDb<
@@ -46,7 +47,7 @@ export type MakeSqliteDb<
   TMetadata extends TMetadata_ & { _tag: TInput['_tag'] } = TMetadata_ & { _tag: TInput['_tag'] },
 >(
   input: TInput,
-) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnexpectedError, R>
+) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnknownError, R>
 
 export interface PreparedStatement {
   execute(bindValues: PreparedBindValues | undefined, options?: { onRowsChanged?: (rowsChanged: number) => void }): void
@@ -66,11 +67,8 @@ export type SqliteDbChangeset = {
   apply: () => void
 }
 
-export const PersistenceInfo = Schema.Struct(
-  {
-    fileName: Schema.String,
-  },
-  { key: Schema.String, value: Schema.Any },
-).annotations({ title: 'LiveStore.PersistenceInfo' })
+export const PersistenceInfo = Schema.StructWithRest(Schema.Struct({ fileName: Schema.String }), [
+  Schema.Record(Schema.String, Schema.Any),
+]).annotate({ title: 'LiveStore.PersistenceInfo' })
 
 export type PersistenceInfo<With extends {} = {}> = typeof PersistenceInfo.Type & With