@tanstack/db 0.5.11 → 0.5.13

package/src/collection/events.ts

@@ -1,6 +1,6 @@
-import { EventEmitter } from "../event-emitter.js"
-import type { Collection } from "./index.js"
-import type { CollectionStatus } from "../types.js"
+import { EventEmitter } from '../event-emitter.js'
+import type { Collection } from './index.js'
+import type { CollectionStatus } from '../types.js'
 
 /**
  * Event emitted when the collection status changes
@@ -43,10 +43,19 @@ export interface CollectionLoadingSubsetChangeEvent {
   loadingSubsetTransition: `start` | `end`
 }
 
+/**
+ * Event emitted when the collection is truncated (all data cleared)
+ */
+export interface CollectionTruncateEvent {
+  type: `truncate`
+  collection: Collection<any, any, any, any, any>
+}
+
 export type AllCollectionEvents = {
-  "status:change": CollectionStatusChangeEvent
-  "subscribers:change": CollectionSubscribersChangeEvent
-  "loadingSubset:change": CollectionLoadingSubsetChangeEvent
+  'status:change': CollectionStatusChangeEvent
+  'subscribers:change': CollectionSubscribersChangeEvent
+  'loadingSubset:change': CollectionLoadingSubsetChangeEvent
+  truncate: CollectionTruncateEvent
 } & {
   [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>
 }
@@ -56,9 +65,10 @@ export type CollectionEvent =
   | CollectionStatusChangeEvent
   | CollectionSubscribersChangeEvent
   | CollectionLoadingSubsetChangeEvent
+  | CollectionTruncateEvent
 
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (
-  event: AllCollectionEvents[T]
+  event: AllCollectionEvents[T],
 ) => void
 
 export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
@@ -78,14 +88,14 @@ export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
    */
   emit<T extends keyof AllCollectionEvents>(
     event: T,
-    eventPayload: AllCollectionEvents[T]
+    eventPayload: AllCollectionEvents[T],
   ): void {
     this.emitInner(event, eventPayload)
   }
 
   emitStatusChange<T extends CollectionStatus>(
     status: T,
-    previousStatus: CollectionStatus
+    previousStatus: CollectionStatus,
   ) {
     this.emit(`status:change`, {
       type: `status:change`,
@@ -106,7 +116,7 @@ export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
 
   emitSubscribersChange(
     subscriberCount: number,
-    previousSubscriberCount: number
+    previousSubscriberCount: number,
   ) {
     this.emit(`subscribers:change`, {
       type: `subscribers:change`,

package/src/collection/index.ts

@@ -1,20 +1,20 @@
 import {
   CollectionRequiresConfigError,
   CollectionRequiresSyncConfigError,
-} from "../errors"
-import { currentStateAsChanges } from "./change-events"
-
-import { CollectionStateManager } from "./state"
-import { CollectionChangesManager } from "./changes"
-import { CollectionLifecycleManager } from "./lifecycle.js"
-import { CollectionSyncManager } from "./sync"
-import { CollectionIndexesManager } from "./indexes"
-import { CollectionMutationsManager } from "./mutations"
-import { CollectionEventsManager } from "./events.js"
-import type { CollectionSubscription } from "./subscription"
-import type { AllCollectionEvents, CollectionEventHandler } from "./events.js"
-import type { BaseIndex, IndexResolver } from "../indexes/base-index.js"
-import type { IndexOptions } from "../indexes/index-options.js"
+} from '../errors'
+import { currentStateAsChanges } from './change-events'
+
+import { CollectionStateManager } from './state'
+import { CollectionChangesManager } from './changes'
+import { CollectionLifecycleManager } from './lifecycle.js'
+import { CollectionSyncManager } from './sync'
+import { CollectionIndexesManager } from './indexes'
+import { CollectionMutationsManager } from './mutations'
+import { CollectionEventsManager } from './events.js'
+import type { CollectionSubscription } from './subscription'
+import type { AllCollectionEvents, CollectionEventHandler } from './events.js'
+import type { BaseIndex, IndexResolver } from '../indexes/base-index.js'
+import type { IndexOptions } from '../indexes/index-options.js'
 import type {
   ChangeMessage,
   CollectionConfig,
@@ -32,11 +32,11 @@ import type {
   Transaction as TransactionType,
   UtilsRecord,
   WritableDeep,
-} from "../types"
-import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { BTreeIndex } from "../indexes/btree-index.js"
-import type { IndexProxy } from "../indexes/lazy-index.js"
+} from '../types'
+import type { SingleRowRefProxy } from '../query/builder/ref-proxy'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { BTreeIndex } from '../indexes/btree-index.js'
+import type { IndexProxy } from '../indexes/lazy-index.js'
 
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
@@ -142,7 +142,7 @@ export function createCollection<
   > & {
     schema: T
     utils: TUtils // Required utils
-  } & NonSingleResult
+  } & NonSingleResult,
 ): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &
   NonSingleResult
 
@@ -155,7 +155,7 @@ export function createCollection<
 >(
   options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {
     schema: T
-  } & NonSingleResult
+  } & NonSingleResult,
 ): Collection<
   InferSchemaOutput<T>,
   TKey,
@@ -177,7 +177,7 @@ export function createCollection<
   > & {
     schema: T
     utils: TUtils // Required utils
-  } & SingleResult
+  } & SingleResult,
 ): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &
   SingleResult
 
@@ -189,7 +189,7 @@ export function createCollection<
 >(
   options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {
     schema: T
-  } & SingleResult
+  } & SingleResult,
 ): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &
   SingleResult
 
@@ -203,7 +203,7 @@ export function createCollection<
   options: Omit<CollectionConfig<T, TKey, never, TUtils>, `utils`> & {
     schema?: never // prohibit schema if an explicit type is provided
     utils: TUtils // Required utils
-  } & NonSingleResult
+  } & NonSingleResult,
 ): Collection<T, TKey, TUtils, never, T> & NonSingleResult
 
 // Overload for when no schema is provided
@@ -215,7 +215,7 @@ export function createCollection<
 >(
   options: CollectionConfig<T, TKey, never, TUtils> & {
     schema?: never // prohibit schema if an explicit type is provided
-  } & NonSingleResult
+  } & NonSingleResult,
 ): Collection<T, TKey, TUtils, never, T> & NonSingleResult
 
 // Overload for when no schema is provided, singleResult is true, and utils is required
@@ -228,7 +228,7 @@ export function createCollection<
   options: Omit<CollectionConfig<T, TKey, never, TUtils>, `utils`> & {
     schema?: never // prohibit schema if an explicit type is provided
     utils: TUtils // Required utils
-  } & SingleResult
+  } & SingleResult,
 ): Collection<T, TKey, TUtils, never, T> & SingleResult
 
 // Overload for when no schema is provided and singleResult is true
@@ -240,17 +240,17 @@ export function createCollection<
 >(
   options: CollectionConfig<T, TKey, never, TUtils> & {
     schema?: never // prohibit schema if an explicit type is provided
-  } & SingleResult
+  } & SingleResult,
 ): Collection<T, TKey, TUtils, never, T> & SingleResult
 
 // Implementation
 export function createCollection(
   options: CollectionConfig<any, string | number, any, UtilsRecord> & {
     schema?: StandardSchemaV1
-  }
+  },
 ): Collection<any, string | number, UtilsRecord, any, any> {
   const collection = new CollectionImpl<any, string | number, any, any, any>(
-    options
+    options,
   )
 
   // Attach utils to collection
@@ -365,6 +365,7 @@ export class CollectionImpl<
       lifecycle: this._lifecycle,
       changes: this._changes,
       indexes: this._indexes,
+      events: this._events,
     })
     this._sync.setDeps({
       collection: this, // Required for passing to config.sync callback
@@ -500,7 +501,7 @@ export class CollectionImpl<
    * Execute a callback for each entry in the collection
    */
   public forEach(
-    callbackfn: (value: TOutput, key: TKey, index: number) => void
+    callbackfn: (value: TOutput, key: TKey, index: number) => void,
   ): void {
     return this._state.forEach(callbackfn)
   }
@@ -509,7 +510,7 @@ export class CollectionImpl<
    * Create a new array with the results of calling a function for each entry in the collection
    */
   public map<U>(
-    callbackfn: (value: TOutput, key: TKey, index: number) => U
+    callbackfn: (value: TOutput, key: TKey, index: number) => U,
   ): Array<U> {
     return this._state.map(callbackfn)
   }
@@ -553,7 +554,7 @@ export class CollectionImpl<
    */
   public createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(
     indexCallback: (row: SingleRowRefProxy<TOutput>) => any,
-    config: IndexOptions<TResolver> = {}
+    config: IndexOptions<TResolver> = {},
   ): IndexProxy<TKey> {
     return this._indexes.createIndex(indexCallback, config)
   }
@@ -571,7 +572,7 @@ export class CollectionImpl<
   public validateData(
     data: unknown,
     type: `insert` | `update`,
-    key?: TKey
+    key?: TKey,
   ): TOutput | never {
     return this._mutations.validateData(data, type, key)
   }
@@ -664,27 +665,27 @@ export class CollectionImpl<
   // Overload 1: Update multiple items with a callback
   update(
     key: Array<TKey | unknown>,
-    callback: (drafts: Array<WritableDeep<TInput>>) => void
+    callback: (drafts: Array<WritableDeep<TInput>>) => void,
   ): TransactionType
 
   // Overload 2: Update multiple items with config and a callback
   update(
     keys: Array<TKey | unknown>,
     config: OperationConfig,
-    callback: (drafts: Array<WritableDeep<TInput>>) => void
+    callback: (drafts: Array<WritableDeep<TInput>>) => void,
   ): TransactionType
 
   // Overload 3: Update a single item with a callback
   update(
     id: TKey | unknown,
-    callback: (draft: WritableDeep<TInput>) => void
+    callback: (draft: WritableDeep<TInput>) => void,
   ): TransactionType
 
   // Overload 4: Update a single item with config and a callback
   update(
     id: TKey | unknown,
     config: OperationConfig,
-    callback: (draft: WritableDeep<TInput>) => void
+    callback: (draft: WritableDeep<TInput>) => void,
   ): TransactionType
 
   update(
@@ -695,7 +696,7 @@ export class CollectionImpl<
       | OperationConfig,
     maybeCallback?:
       | ((draft: WritableDeep<TInput>) => void)
-      | ((drafts: Array<WritableDeep<TInput>>) => void)
+      | ((drafts: Array<WritableDeep<TInput>>) => void),
   ) {
     return this._mutations.update(keys, configOrCallback, maybeCallback)
   }
@@ -732,7 +733,7 @@ export class CollectionImpl<
    */
   delete = (
     keys: Array<TKey> | TKey,
-    config?: OperationConfig
+    config?: OperationConfig,
   ): TransactionType<any> => {
     return this._mutations.delete(keys, config)
   }
@@ -821,7 +822,7 @@ export class CollectionImpl<
    * })
    */
   public currentStateAsChanges(
-    options: CurrentStateAsChangesOptions = {}
+    options: CurrentStateAsChangesOptions = {},
   ): Array<ChangeMessage<TOutput>> | void {
     return currentStateAsChanges(this, options)
   }
@@ -867,7 +868,7 @@ export class CollectionImpl<
    */
   public subscribeChanges(
     callback: (changes: Array<ChangeMessage<TOutput>>) => void,
-    options: SubscribeChangesOptions = {}
+    options: SubscribeChangesOptions = {},
   ): CollectionSubscription {
     return this._changes.subscribeChanges(callback, options)
   }
@@ -877,7 +878,7 @@ export class CollectionImpl<
    */
   public on<T extends keyof AllCollectionEvents>(
     event: T,
-    callback: CollectionEventHandler<T>
+    callback: CollectionEventHandler<T>,
   ) {
     return this._events.on(event, callback)
   }
@@ -887,7 +888,7 @@ export class CollectionImpl<
    */
   public once<T extends keyof AllCollectionEvents>(
     event: T,
-    callback: CollectionEventHandler<T>
+    callback: CollectionEventHandler<T>,
   ) {
     return this._events.once(event, callback)
   }
@@ -897,7 +898,7 @@ export class CollectionImpl<
    */
   public off<T extends keyof AllCollectionEvents>(
     event: T,
-    callback: CollectionEventHandler<T>
+    callback: CollectionEventHandler<T>,
   ) {
     this._events.off(event, callback)
   }
@@ -907,7 +908,7 @@ export class CollectionImpl<
    */
   public waitFor<T extends keyof AllCollectionEvents>(
     event: T,
-    timeout?: number
+    timeout?: number,
   ) {
     return this._events.waitFor(event, timeout)
   }
@@ -923,7 +924,7 @@ export class CollectionImpl<
 }
 
 function buildCompareOptionsFromConfig(
-  config: CollectionConfig<any, any, any>
+  config: CollectionConfig<any, any, any>,
 ): StringCollationConfig {
   if (config.defaultStringCollation) {
     const options = config.defaultStringCollation

package/src/collection/indexes.ts

@@ -1,16 +1,16 @@
-import { IndexProxy, LazyIndexWrapper } from "../indexes/lazy-index"
+import { IndexProxy, LazyIndexWrapper } from '../indexes/lazy-index'
 import {
   createSingleRowRefProxy,
   toExpression,
-} from "../query/builder/ref-proxy"
-import { BTreeIndex } from "../indexes/btree-index"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { BaseIndex, IndexResolver } from "../indexes/base-index"
-import type { ChangeMessage } from "../types"
-import type { IndexOptions } from "../indexes/index-options"
-import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
-import type { CollectionLifecycleManager } from "./lifecycle"
-import type { CollectionStateManager } from "./state"
+} from '../query/builder/ref-proxy'
+import { BTreeIndex } from '../indexes/btree-index'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { BaseIndex, IndexResolver } from '../indexes/base-index'
+import type { ChangeMessage } from '../types'
+import type { IndexOptions } from '../indexes/index-options'
+import type { SingleRowRefProxy } from '../query/builder/ref-proxy'
+import type { CollectionLifecycleManager } from './lifecycle'
+import type { CollectionStateManager } from './state'
 
 export class CollectionIndexesManager<
   TOutput extends object = Record<string, unknown>,
@@ -41,7 +41,7 @@ export class CollectionIndexesManager<
    */
   public createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(
     indexCallback: (row: SingleRowRefProxy<TOutput>) => any,
-    config: IndexOptions<TResolver> = {}
+    config: IndexOptions<TResolver> = {},
   ): IndexProxy<TKey> {
     this.lifecycle.validateCollectionUsable(`createIndex`)
 
@@ -60,7 +60,7 @@ export class CollectionIndexesManager<
       config.name,
       resolver,
       config.options,
-      this.state.entries()
+      this.state.entries(),
     )
 
     this.lazyIndexes.set(indexId, lazyIndex)
@@ -109,7 +109,7 @@ export class CollectionIndexesManager<
 
         this.resolvedIndexes.set(indexId, resolvedIndex)
         return { indexId, resolvedIndex }
-      }
+      },
     )
 
     await Promise.all(resolutionPromises)
@@ -121,7 +121,7 @@ export class CollectionIndexesManager<
    */
   private async resolveSingleIndex(
     indexId: number,
-    lazyIndex: LazyIndexWrapper<TKey>
+    lazyIndex: LazyIndexWrapper<TKey>,
   ): Promise<BaseIndex<TKey>> {
     const resolvedIndex = await lazyIndex.resolve()
     resolvedIndex.build(this.state.entries())

package/src/collection/lifecycle.ts

@@ -2,19 +2,19 @@ import {
   CollectionInErrorStateError,
   CollectionStateError,
   InvalidCollectionStatusTransitionError,
-} from "../errors"
+} from '../errors'
 import {
   safeCancelIdleCallback,
   safeRequestIdleCallback,
-} from "../utils/browser-polyfills"
-import type { IdleCallbackDeadline } from "../utils/browser-polyfills"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { CollectionConfig, CollectionStatus } from "../types"
-import type { CollectionEventsManager } from "./events"
-import type { CollectionIndexesManager } from "./indexes"
-import type { CollectionChangesManager } from "./changes"
-import type { CollectionSyncManager } from "./sync"
-import type { CollectionStateManager } from "./state"
+} from '../utils/browser-polyfills'
+import type { IdleCallbackDeadline } from '../utils/browser-polyfills'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { CollectionConfig, CollectionStatus } from '../types'
+import type { CollectionEventsManager } from './events'
+import type { CollectionIndexesManager } from './indexes'
+import type { CollectionChangesManager } from './changes'
+import type { CollectionSyncManager } from './sync'
+import type { CollectionStateManager } from './state'
 
 export class CollectionLifecycleManager<
   TOutput extends object = Record<string, unknown>,
@@ -64,7 +64,7 @@ export class CollectionLifecycleManager<
    */
   public validateStatusTransition(
     from: CollectionStatus,
-    to: CollectionStatus
+    to: CollectionStatus,
   ): void {
     if (from === to) {
       // Allow same state transitions
@@ -78,7 +78,7 @@ export class CollectionLifecycleManager<
       loading: [`ready`, `error`, `cleaned-up`],
       ready: [`cleaned-up`, `error`],
       error: [`cleaned-up`, `idle`],
-      "cleaned-up": [`loading`, `error`],
+      'cleaned-up': [`loading`, `error`],
     }
 
     if (!validTransitions[from].includes(to)) {
@@ -92,14 +92,14 @@ export class CollectionLifecycleManager<
    */
   public setStatus(
     newStatus: CollectionStatus,
-    allowReady: boolean = false
+    allowReady: boolean = false,
   ): void {
     if (newStatus === `ready` && !allowReady) {
       // setStatus('ready') is an internal method that should not be called directly
       // Instead, use markReady to transition to ready triggering the necessary events
       // and side effects.
       throw new CollectionStateError(
-        `You can't directly call "setStatus('ready'). You must use markReady instead.`
+        `You can't directly call "setStatus('ready'). You must use markReady instead.`,
       )
     }
     this.validateStatusTransition(this.status, newStatus)
@@ -112,7 +112,7 @@ export class CollectionLifecycleManager<
       this.indexes.resolveAllIndexes().catch((error) => {
         console.warn(
           `${this.config.id ? `[${this.config.id}] ` : ``}Failed to resolve indexes:`,
-          error
+          error,
         )
       })
     }
@@ -235,7 +235,7 @@ export class CollectionLifecycleManager<
           this.idleCallbackId = null
         }
       },
-      { timeout: 1000 }
+      { timeout: 1000 },
     )
   }
 

package/src/collection/mutations.ts

@@ -1,8 +1,9 @@
-import { withArrayChangeTracking, withChangeTracking } from "../proxy"
-import { createTransaction, getActiveTransaction } from "../transactions"
+import { withArrayChangeTracking, withChangeTracking } from '../proxy'
+import { createTransaction, getActiveTransaction } from '../transactions'
 import {
   DeleteKeyNotFoundError,
   DuplicateKeyError,
+  InvalidKeyError,
   InvalidSchemaError,
   KeyUpdateNotAllowedError,
   MissingDeleteHandlerError,
@@ -15,9 +16,9 @@ import {
   SchemaValidationError,
   UndefinedKeyError,
   UpdateKeyNotFoundError,
-} from "../errors"
-import type { Collection, CollectionImpl } from "./index.js"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
+} from '../errors'
+import type { Collection, CollectionImpl } from './index.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type {
   CollectionConfig,
   InsertConfig,
@@ -28,9 +29,9 @@ import type {
   TransactionWithMutations,
   UtilsRecord,
   WritableDeep,
-} from "../types"
-import type { CollectionLifecycleManager } from "./lifecycle"
-import type { CollectionStateManager } from "./state"
+} from '../types'
+import type { CollectionLifecycleManager } from './lifecycle'
+import type { CollectionStateManager } from './state'
 
 export class CollectionMutationsManager<
   TOutput extends object = Record<string, unknown>,
@@ -72,7 +73,7 @@ export class CollectionMutationsManager<
   public validateData(
     data: unknown,
     type: `insert` | `update`,
-    key?: TKey
+    key?: TKey,
   ): TOutput | never {
     if (!this.config.schema) return data as TOutput
 
@@ -113,7 +114,7 @@ export class CollectionMutationsManager<
         const validatedMergedData = result.value as TOutput
         const modifiedKeys = Object.keys(data)
         const extractedChanges = Object.fromEntries(
-          modifiedKeys.map((k) => [k, validatedMergedData[k as keyof TOutput]])
+          modifiedKeys.map((k) => [k, validatedMergedData[k as keyof TOutput]]),
         ) as TOutput
 
         return extractedChanges
@@ -141,8 +142,12 @@ export class CollectionMutationsManager<
   }
 
   public generateGlobalKey(key: any, item: any): string {
-    if (typeof key === `undefined`) {
-      throw new UndefinedKeyError(item)
+    if (typeof key !== `string` && typeof key !== `number`) {
+      // Preserve specific error for undefined keys
+      if (typeof key === `undefined`) {
+        throw new UndefinedKeyError(item)
+      }
+      throw new InvalidKeyError(key, item)
     }
 
     return `KEY::${this.id}/${key}`
@@ -189,7 +194,7 @@ export class CollectionMutationsManager<
           Object.keys(item).map((k) => [
             k,
             validatedData[k as keyof typeof validatedData],
-          ])
+          ]),
         ) as TInput,
         globalKey,
         key,
@@ -255,7 +260,7 @@ export class CollectionMutationsManager<
       | OperationConfig,
     maybeCallback?:
       | ((draft: WritableDeep<TInput>) => void)
-      | ((drafts: Array<WritableDeep<TInput>>) => void)
+      | ((drafts: Array<WritableDeep<TInput>>) => void),
   ) {
     if (typeof keys === `undefined`) {
       throw new MissingUpdateArgumentError()
@@ -298,12 +303,12 @@ export class CollectionMutationsManager<
       // Use the proxy to track changes for all objects
       changesArray = withArrayChangeTracking(
         currentObjects,
-        callback as (draft: Array<TInput>) => void
+        callback as (draft: Array<TInput>) => void,
       )
     } else {
       const result = withChangeTracking(
         currentObjects[0]!,
-        callback as (draft: TInput) => void
+        callback as (draft: TInput) => void,
       )
       changesArray = [result]
     }
@@ -329,14 +334,14 @@ export class CollectionMutationsManager<
         const validatedUpdatePayload = this.validateData(
           itemChanges,
           `update`,
-          key
+          key,
         )
 
         // Construct the full modified item by applying the validated update payload to the original item
         const modifiedItem = Object.assign(
           {},
           originalItem,
-          validatedUpdatePayload
+          validatedUpdatePayload,
         )
 
         // Check if the ID of the item is being changed
@@ -361,7 +366,7 @@ export class CollectionMutationsManager<
             Object.keys(itemChanges).map((k) => [
               k,
               modifiedItem[k as keyof typeof modifiedItem],
-            ])
+            ]),
           ) as TInput,
           globalKey,
           key,
@@ -444,7 +449,7 @@ export class CollectionMutationsManager<
    */
   delete = (
     keys: Array<TKey> | TKey,
-    config?: OperationConfig
+    config?: OperationConfig,
   ): TransactionType<any> => {
     const state = this.state
     this.lifecycle.validateCollectionUsable(`delete`)