@tanstack/db 0.0.1

package/src/transactions.ts

@@ -0,0 +1,198 @@
+import { createDeferred } from "./deferred"
+import type { Deferred } from "./deferred"
+import type {
+  PendingMutation,
+  TransactionConfig,
+  TransactionState,
+} from "./types"
+
+function generateUUID() {
+  // Check if crypto.randomUUID is available (modern browsers and Node.js 15+)
+  if (
+    typeof crypto !== `undefined` &&
+    typeof crypto.randomUUID === `function`
+  ) {
+    return crypto.randomUUID()
+  }
+
+  // Fallback implementation for older environments
+  return `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g, function (c) {
+    const r = (Math.random() * 16) | 0
+    const v = c === `x` ? r : (r & 0x3) | 0x8
+    return v.toString(16)
+  })
+}
+
+const transactions: Array<Transaction> = []
+
+export function createTransaction(config: TransactionConfig): Transaction {
+  if (typeof config.mutationFn === `undefined`) {
+    throw `mutationFn is required when creating a transaction`
+  }
+
+  let transactionId = config.id
+  if (!transactionId) {
+    transactionId = generateUUID()
+  }
+  const newTransaction = new Transaction({ ...config, id: transactionId })
+  transactions.push(newTransaction)
+
+  return newTransaction
+}
+
+let transactionStack: Array<Transaction> = []
+
+export function getActiveTransaction(): Transaction | undefined {
+  if (transactionStack.length > 0) {
+    return transactionStack.slice(-1)[0]
+  } else {
+    return undefined
+  }
+}
+
+function registerTransaction(tx: Transaction) {
+  transactionStack.push(tx)
+}
+
+function unregisterTransaction(tx: Transaction) {
+  transactionStack = transactionStack.filter((t) => t.id !== tx.id)
+}
+
+export class Transaction {
+  public id: string
+  public state: TransactionState
+  public mutationFn
+  public mutations: Array<PendingMutation<any>>
+  public isPersisted: Deferred<Transaction>
+  public autoCommit: boolean
+  public createdAt: Date
+  public metadata: Record<string, unknown>
+  public error?: {
+    message: string
+    error: Error
+  }
+
+  constructor(config: TransactionConfig) {
+    this.id = config.id!
+    this.mutationFn = config.mutationFn
+    this.state = `pending`
+    this.mutations = []
+    this.isPersisted = createDeferred()
+    this.autoCommit = config.autoCommit ?? true
+    this.createdAt = new Date()
+    this.metadata = config.metadata ?? {}
+  }
+
+  setState(newState: TransactionState) {
+    this.state = newState
+  }
+
+  mutate(callback: () => void): Transaction {
+    if (this.state !== `pending`) {
+      throw `You can no longer call .mutate() as the transaction is no longer pending`
+    }
+
+    registerTransaction(this)
+    try {
+      callback()
+    } finally {
+      unregisterTransaction(this)
+    }
+
+    if (this.autoCommit) {
+      this.commit()
+    }
+
+    return this
+  }
+
+  applyMutations(mutations: Array<PendingMutation<any>>): void {
+    for (const newMutation of mutations) {
+      const existingIndex = this.mutations.findIndex(
+        (m) => m.key === newMutation.key
+      )
+
+      if (existingIndex >= 0) {
+        // Replace existing mutation
+        this.mutations[existingIndex] = newMutation
+      } else {
+        // Insert new mutation
+        this.mutations.push(newMutation)
+      }
+    }
+  }
+
+  rollback(config?: { isSecondaryRollback?: boolean }): Transaction {
+    const isSecondaryRollback = config?.isSecondaryRollback ?? false
+    if (this.state === `completed`) {
+      throw `You can no longer call .rollback() as the transaction is already completed`
+    }
+
+    this.setState(`failed`)
+
+    // See if there's any other transactions w/ mutations on the same keys
+    // and roll them back as well.
+    if (!isSecondaryRollback) {
+      const mutationKeys = new Set()
+      this.mutations.forEach((m) => mutationKeys.add(m.key))
+      transactions.forEach(
+        (t) =>
+          t.state === `pending` &&
+          t.mutations.some((m) => mutationKeys.has(m.key)) &&
+          t.rollback({ isSecondaryRollback: true })
+      )
+    }
+
+    // Reject the promise
+    this.isPersisted.reject(this.error?.error)
+
+    this.touchCollection()
+
+    return this
+  }
+
+  // Tell collection that something has changed with the transaction
+  touchCollection(): void {
+    const hasCalled = new Set()
+    this.mutations.forEach((mutation) => {
+      if (!hasCalled.has(mutation.collection.id)) {
+        mutation.collection.transactions.setState((state) => state)
+        mutation.collection.commitPendingTransactions()
+        hasCalled.add(mutation.collection.id)
+      }
+    })
+  }
+
+  async commit(): Promise<Transaction> {
+    if (this.state !== `pending`) {
+      throw `You can no longer call .commit() as the transaction is no longer pending`
+    }
+
+    this.setState(`persisting`)
+
+    if (this.mutations.length === 0) {
+      this.setState(`completed`)
+    }
+
+    // Run mutationFn
+    try {
+      await this.mutationFn({ transaction: this })
+
+      this.setState(`completed`)
+      this.touchCollection()
+
+      this.isPersisted.resolve(this)
+    } catch (error) {
+      // Update transaction with error information
+      this.error = {
+        message: error instanceof Error ? error.message : String(error),
+        error: error instanceof Error ? error : new Error(String(error)),
+      }
+
+      // rollback the transaction
+      return this.rollback()
+    }
+
+    return this
+  }
+}

package/src/types.ts

@@ -0,0 +1,125 @@
+import type { Collection } from "./collection"
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { Transaction } from "./transactions"
+
+export type TransactionState = `pending` | `persisting` | `completed` | `failed`
+
+/**
+ * Represents a pending mutation within a transaction
+ * Contains information about the original and modified data, as well as metadata
+ */
+export interface PendingMutation<T extends object = Record<string, unknown>> {
+  mutationId: string
+  original: Record<string, unknown>
+  modified: Record<string, unknown>
+  changes: Record<string, unknown>
+  key: string
+  type: OperationType
+  metadata: unknown
+  syncMetadata: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+  collection: Collection<T>
+}
+
+/**
+ * Configuration options for creating a new transaction
+ */
+export type MutationFnParams = {
+  transaction: Transaction
+}
+
+export type MutationFn = (params: MutationFnParams) => Promise<any>
+
+export interface TransactionConfig {
+  /** Unique identifier for the transaction */
+  id?: string
+  /* If the transaction should autocommit after a mutate call or should commit be called explicitly */
+  autoCommit?: boolean
+  mutationFn: MutationFn
+  /** Custom metadata to associate with the transaction */
+  metadata?: Record<string, unknown>
+}
+
+export type { Transaction }
+
+type Value<TExtensions = never> =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | TExtensions
+  | Array<Value<TExtensions>>
+  | { [key: string]: Value<TExtensions> }
+
+export type Row<TExtensions = never> = Record<string, Value<TExtensions>>
+
+export type OperationType = `insert` | `update` | `delete`
+
+export interface SyncConfig<T extends object = Record<string, unknown>> {
+  sync: (params: {
+    collection: Collection<T>
+    begin: () => void
+    write: (message: ChangeMessage<T>) => void
+    commit: () => void
+  }) => void
+
+  /**
+   * Get the sync metadata for insert operations
+   * @returns Record containing primaryKey and relation information
+   */
+  getSyncMetadata?: () => Record<string, unknown>
+}
+
+export interface ChangeMessage<T extends object = Record<string, unknown>> {
+  key: string
+  value: T
+  previousValue?: T
+  type: OperationType
+  metadata?: Record<string, unknown>
+}
+
+export interface OptimisticChangeMessage<
+  T extends object = Record<string, unknown>,
+> extends ChangeMessage<T> {
+  // Is this change message part of an active transaction. Only applies to optimistic changes.
+  isActive?: boolean
+}
+
+/**
+ * The Standard Schema interface.
+ * This follows the standard-schema specification: https://github.com/standard-schema/standard-schema
+ */
+export type StandardSchema<T> = StandardSchemaV1 & {
+  "~standard": {
+    types?: {
+      input: T
+      output: T
+    }
+  }
+}
+
+/**
+ * Type alias for StandardSchema
+ */
+export type StandardSchemaAlias<T = unknown> = StandardSchema<T>
+
+export interface OperationConfig {
+  metadata?: Record<string, unknown>
+}
+
+export interface InsertConfig {
+  key?: string | Array<string | undefined>
+  metadata?: Record<string, unknown>
+}
+
+export interface CollectionConfig<T extends object = Record<string, unknown>> {
+  id: string
+  sync: SyncConfig<T>
+  schema?: StandardSchema<T>
+}
+
+export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
+  ChangeMessage<T>
+>

package/src/utils.ts

@@ -0,0 +1,15 @@
+export function getLockedObjects(): Set<string> {
+  // Stub implementation that returns an empty Set
+  return new Set()
+}
+
+let globalVersion = 0
+
+export function getGlobalVersion(): number {
+  return globalVersion
+}
+
+export function advanceGlobalVersion(): number {
+  console.log(`==== advancing global version`, globalVersion + 1)
+  return globalVersion++
+}