@tanstack/query-db-collection 0.1.0 → 0.1.2

package/src/manual-sync.ts

@@ -0,0 +1,236 @@
+import {
+  DeleteOperationItemNotFoundError,
+  DuplicateKeyInBatchError,
+  SyncNotInitializedError,
+  UpdateOperationItemNotFoundError,
+} from "./errors"
+import type { QueryClient } from "@tanstack/query-core"
+import type { ChangeMessage, Collection } from "@tanstack/db"
+
+// Types for sync operations
+export type SyncOperation<
+  TRow extends object,
+  TKey extends string | number = string | number,
+  TInsertInput extends object = TRow,
+> =
+  | { type: `insert`; data: TInsertInput | Array<TInsertInput> }
+  | { type: `update`; data: Partial<TRow> | Array<Partial<TRow>> }
+  | { type: `delete`; key: TKey | Array<TKey> }
+  | { type: `upsert`; data: Partial<TRow> | Array<Partial<TRow>> }
+
+export interface SyncContext<
+  TRow extends object,
+  TKey extends string | number = string | number,
+> {
+  collection: Collection<TRow>
+  queryClient: QueryClient
+  queryKey: Array<unknown>
+  getKey: (item: TRow) => TKey
+  begin: () => void
+  write: (message: Omit<ChangeMessage<TRow>, `key`>) => void
+  commit: () => void
+}
+
+interface NormalizedOperation<
+  TRow extends object,
+  TKey extends string | number = string | number,
+> {
+  type: `insert` | `update` | `delete` | `upsert`
+  key: TKey
+  data?: TRow | Partial<TRow>
+}
+
+// Normalize operations into a consistent format
+function normalizeOperations<
+  TRow extends object,
+  TKey extends string | number = string | number,
+  TInsertInput extends object = TRow,
+>(
+  ops:
+    | SyncOperation<TRow, TKey, TInsertInput>
+    | Array<SyncOperation<TRow, TKey, TInsertInput>>,
+  ctx: SyncContext<TRow, TKey>
+): Array<NormalizedOperation<TRow, TKey>> {
+  const operations = Array.isArray(ops) ? ops : [ops]
+  const normalized: Array<NormalizedOperation<TRow, TKey>> = []
+
+  for (const op of operations) {
+    if (op.type === `delete`) {
+      const keys = Array.isArray(op.key) ? op.key : [op.key]
+      for (const key of keys) {
+        normalized.push({ type: `delete`, key })
+      }
+    } else {
+      const items = Array.isArray(op.data) ? op.data : [op.data]
+      for (const item of items) {
+        let key: TKey
+        if (op.type === `update`) {
+          // For updates, we need to get the key from the partial data
+          key = ctx.getKey(item as TRow)
+        } else {
+          // For insert/upsert, validate and resolve the full item first
+          const resolved = ctx.collection.validateData(
+            item,
+            op.type === `upsert` ? `insert` : op.type
+          )
+          key = ctx.getKey(resolved)
+        }
+        normalized.push({ type: op.type, key, data: item })
+      }
+    }
+  }
+
+  return normalized
+}
+
+// Validate operations before executing
+function validateOperations<
+  TRow extends object,
+  TKey extends string | number = string | number,
+>(
+  operations: Array<NormalizedOperation<TRow, TKey>>,
+  ctx: SyncContext<TRow, TKey>
+): void {
+  const seenKeys = new Set<TKey>()
+
+  for (const op of operations) {
+    // Check for duplicate keys within the batch
+    if (seenKeys.has(op.key)) {
+      throw new DuplicateKeyInBatchError(op.key)
+    }
+    seenKeys.add(op.key)
+
+    // Validate operation-specific requirements
+    if (op.type === `update`) {
+      if (!ctx.collection.has(op.key)) {
+        throw new UpdateOperationItemNotFoundError(op.key)
+      }
+    } else if (op.type === `delete`) {
+      if (!ctx.collection.has(op.key)) {
+        throw new DeleteOperationItemNotFoundError(op.key)
+      }
+    }
+  }
+}
+
+// Execute a batch of operations
+export function performWriteOperations<
+  TRow extends object,
+  TKey extends string | number = string | number,
+  TInsertInput extends object = TRow,
+>(
+  operations:
+    | SyncOperation<TRow, TKey, TInsertInput>
+    | Array<SyncOperation<TRow, TKey, TInsertInput>>,
+  ctx: SyncContext<TRow, TKey>
+): void {
+  const normalized = normalizeOperations(operations, ctx)
+  validateOperations(normalized, ctx)
+
+  ctx.begin()
+
+  for (const op of normalized) {
+    switch (op.type) {
+      case `insert`: {
+        const resolved = ctx.collection.validateData(op.data, `insert`)
+        ctx.write({
+          type: `insert`,
+          value: resolved,
+        })
+        break
+      }
+      case `update`: {
+        const currentItem = ctx.collection.get(op.key)!
+        const updatedItem = {
+          ...currentItem,
+          ...op.data,
+        }
+        const resolved = ctx.collection.validateData(
+          updatedItem,
+          `update`,
+          op.key
+        )
+        ctx.write({
+          type: `update`,
+          value: resolved,
+        })
+        break
+      }
+      case `delete`: {
+        const currentItem = ctx.collection.get(op.key)!
+        ctx.write({
+          type: `delete`,
+          value: currentItem,
+        })
+        break
+      }
+      case `upsert`: {
+        const resolved = ctx.collection.validateData(
+          op.data,
+          ctx.collection.has(op.key) ? `update` : `insert`,
+          op.key
+        )
+        if (ctx.collection.has(op.key)) {
+          ctx.write({
+            type: `update`,
+            value: resolved,
+          })
+        } else {
+          ctx.write({
+            type: `insert`,
+            value: resolved,
+          })
+        }
+        break
+      }
+    }
+  }
+
+  ctx.commit()
+
+  // Update query cache after successful commit
+  const updatedData = ctx.collection.toArray
+  ctx.queryClient.setQueryData(ctx.queryKey, updatedData)
+}
+
+// Factory function to create write utils
+export function createWriteUtils<
+  TRow extends object,
+  TKey extends string | number = string | number,
+  TInsertInput extends object = TRow,
+>(getContext: () => SyncContext<TRow, TKey> | null) {
+  function ensureContext(): SyncContext<TRow, TKey> {
+    const context = getContext()
+    if (!context) {
+      throw new SyncNotInitializedError()
+    }
+    return context
+  }
+
+  return {
+    writeInsert(data: TInsertInput | Array<TInsertInput>) {
+      const ctx = ensureContext()
+      performWriteOperations({ type: `insert`, data }, ctx)
+    },
+
+    writeUpdate(data: Partial<TRow> | Array<Partial<TRow>>) {
+      const ctx = ensureContext()
+      performWriteOperations({ type: `update`, data }, ctx)
+    },
+
+    writeDelete(key: TKey | Array<TKey>) {
+      const ctx = ensureContext()
+      performWriteOperations({ type: `delete`, key }, ctx)
+    },
+
+    writeUpsert(data: Partial<TRow> | Array<Partial<TRow>>) {
+      const ctx = ensureContext()
+      performWriteOperations({ type: `upsert`, data }, ctx)
+    },
+
+    writeBatch(operations: Array<SyncOperation<TRow, TKey, TInsertInput>>) {
+      const ctx = ensureContext()
+      performWriteOperations(operations, ctx)
+    },
+  }
+}

package/src/query.ts

@@ -5,6 +5,8 @@ import {
   QueryFnRequiredError,
   QueryKeyRequiredError,
 } from "./errors"
+import { createWriteUtils } from "./manual-sync"
+import type { SyncOperation } from "./manual-sync"
 import type {
   QueryClient,
   QueryFunctionContext,
@@ -12,6 +14,7 @@ import type {
   QueryObserverOptions,
 } from "@tanstack/query-core"
 import type {
+  ChangeMessage,
   CollectionConfig,
   DeleteMutationFn,
   DeleteMutationFnParams,
@@ -23,6 +26,9 @@ import type {
   UtilsRecord,
 } from "@tanstack/db"
 
+// Re-export for external use
+export type { SyncOperation } from "./manual-sync"
+
 export interface QueryCollectionConfig<
   TItem extends object,
   TError = unknown,
@@ -222,8 +228,22 @@ export type RefetchFn = () => Promise<void>
 /**
  * Query collection utilities type
  */
-export interface QueryCollectionUtils extends UtilsRecord {
+/**
+ * Write operation types for batch operations
+ */
+export interface QueryCollectionUtils<
+  TItem extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TInsertInput extends object = TItem,
+> extends UtilsRecord {
   refetch: RefetchFn
+  writeInsert: (data: TInsertInput | Array<TInsertInput>) => void
+  writeUpdate: (updates: Partial<TItem> | Array<Partial<TItem>>) => void
+  writeDelete: (keys: TKey | Array<TKey>) => void
+  writeUpsert: (data: Partial<TItem> | Array<Partial<TItem>>) => void
+  writeBatch: (
+    operations: Array<SyncOperation<TItem, TKey, TInsertInput>>
+  ) => void
 }
 
 /**
@@ -236,9 +256,13 @@ export function queryCollectionOptions<
   TItem extends object,
   TError = unknown,
   TQueryKey extends QueryKey = QueryKey,
+  TKey extends string | number = string | number,
+  TInsertInput extends object = TItem,
 >(
   config: QueryCollectionConfig<TItem, TError, TQueryKey>
-): CollectionConfig<TItem> & { utils: QueryCollectionUtils } {
+): CollectionConfig<TItem> & {
+  utils: QueryCollectionUtils<TItem, TKey, TInsertInput>
+} {
   const {
     queryKey,
     queryFn,
@@ -407,6 +431,41 @@ export function queryCollectionOptions<
     })
   }
 
+  // Create write context for manual write operations
+  let writeContext: {
+    collection: any
+    queryClient: QueryClient
+    queryKey: Array<unknown>
+    getKey: (item: TItem) => TKey
+    begin: () => void
+    write: (message: Omit<ChangeMessage<TItem>, `key`>) => void
+    commit: () => void
+  } | null = null
+
+  // Enhanced internalSync that captures write functions for manual use
+  const enhancedInternalSync: SyncConfig<TItem>[`sync`] = (params) => {
+    const { begin, write, commit, collection } = params
+
+    // Store references for manual write operations
+    writeContext = {
+      collection,
+      queryClient,
+      queryKey: queryKey as unknown as Array<unknown>,
+      getKey: getKey as (item: TItem) => TKey,
+      begin,
+      write,
+      commit,
+    }
+
+    // Call the original internalSync logic
+    return internalSync(params)
+  }
+
+  // Create write utils using the manual-sync module
+  const writeUtils = createWriteUtils<TItem, TKey, TInsertInput>(
+    () => writeContext
+  )
+
   // Create wrapper handlers for direct persistence operations that handle refetching
   const wrappedOnInsert = onInsert
     ? async (params: InsertMutationFnParams<TItem>) => {
@@ -453,12 +512,13 @@ export function queryCollectionOptions<
   return {
     ...baseCollectionConfig,
     getKey,
-    sync: { sync: internalSync },
+    sync: { sync: enhancedInternalSync },
     onInsert: wrappedOnInsert,
     onUpdate: wrappedOnUpdate,
     onDelete: wrappedOnDelete,
     utils: {
       refetch,
+      ...writeUtils,
     },
   }
 }