@tanstack/db 0.0.11 → 0.0.12

package/dist/esm/query/compiled-query.js

@@ -18,7 +18,12 @@ class CompiledQuery {
     const inputs = Object.fromEntries(
       Object.entries(collections).map(([key]) => [key, graph.newInput()])
     );
-    const sync = ({ begin, write, commit }) => {
+    const sync = ({
+      begin,
+      write,
+      commit,
+      collection
+    }) => {
       compileQueryPipeline(
         query,
         inputs
@@ -42,12 +47,17 @@ class CompiledQuery {
           }, /* @__PURE__ */ new Map()).forEach((changes, rawKey) => {
             const { deletes, inserts, value } = changes;
             const valueWithKey = { ...value, _key: rawKey };
-            if (inserts && !deletes) {
+            if (inserts && deletes === 0) {
               write({
                 value: valueWithKey,
                 type: `insert`
               });
-            } else if (inserts >= deletes) {
+            } else if (
+              // Insert & update(s) (updates are a delete & insert)
+              inserts > deletes || // Just update(s) but the item is already in the collection (so
+              // was inserted previously).
+              inserts === deletes && collection.has(valueWithKey._key)
+            ) {
               write({
                 value: valueWithKey,
                 type: `update`
@@ -57,6 +67,10 @@ class CompiledQuery {
                 value: valueWithKey,
                 type: `delete`
               });
+            } else {
+              throw new Error(
+                `This should never happen ${JSON.stringify(changes)}`
+              );
             }
           });
           commit();
@@ -67,8 +81,6 @@ class CompiledQuery {
     this.graph = graph;
     this.inputs = inputs;
     this.resultCollection = createCollection({
-      id: crypto.randomUUID(),
-      // TODO: remove when we don't require any more
       getKey: (val) => {
         return val._key;
       },

package/dist/esm/query/compiled-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"compiled-query.js","sources":["../../../src/query/compiled-query.ts"],"sourcesContent":["import { D2, MultiSet, output } from \"@electric-sql/d2mini\"\nimport { createCollection } from \"../collection.js\"\nimport { compileQueryPipeline } from \"./pipeline-compiler.js\"\nimport type { Collection } from \"../collection.js\"\nimport type { ChangeMessage, SyncConfig } from \"../types.js\"\nimport type {\n  IStreamBuilder,\n  MultiSetArray,\n  RootStreamBuilder,\n} from \"@electric-sql/d2mini\"\nimport type { QueryBuilder, ResultsFromContext } from \"./query-builder.js\"\nimport type { Context, Schema } from \"./types.js\"\n\nexport function compileQuery<TContext extends Context<Schema>>(\n  queryBuilder: QueryBuilder<TContext>\n) {\n  return new CompiledQuery<\n    ResultsFromContext<TContext> & { _key?: string | number }\n  >(queryBuilder)\n}\n\nexport class CompiledQuery<TResults extends object = Record<string, unknown>> {\n  private graph: D2\n  private inputs: Record<string, RootStreamBuilder<any>>\n  private inputCollections: Record<string, Collection<any>>\n  private resultCollection: Collection<TResults>\n  public state: `compiled` | `running` | `stopped` = `compiled`\n  private unsubscribeCallbacks: Array<() => void> = []\n\n  constructor(queryBuilder: QueryBuilder<Context<Schema>>) {\n    const query = queryBuilder._query\n    const collections = query.collections\n\n    if (!collections) {\n      throw new Error(`No collections provided`)\n    }\n\n    this.inputCollections = collections\n\n    const graph = new D2()\n    const inputs = Object.fromEntries(\n      Object.entries(collections).map(([key]) => [key, graph.newInput<any>()])\n    )\n\n    const sync: SyncConfig<TResults>[`sync`] = ({ begin, write, commit }) => {\n      compileQueryPipeline<IStreamBuilder<[unknown, TResults]>>(\n        query,\n        inputs\n      ).pipe(\n        output((data) => {\n          begin()\n          data\n            .getInner()\n            .reduce((acc, [[key, value], multiplicity]) => {\n              const changes = acc.get(key) || {\n                deletes: 0,\n                inserts: 0,\n                value,\n              }\n              if (multiplicity < 0) {\n                changes.deletes += Math.abs(multiplicity)\n              } else if (multiplicity > 0) {\n                changes.inserts += multiplicity\n                changes.value = value\n              }\n              acc.set(key, changes)\n              return acc\n            }, new Map<unknown, { deletes: number; inserts: number; value: TResults }>())\n            .forEach((changes, rawKey) => {\n              const { deletes, inserts, value } = changes\n              const valueWithKey = { ...value, _key: rawKey }\n              if (inserts && !deletes) {\n                write({\n                  value: valueWithKey,\n                  type: `insert`,\n                })\n              } else if (inserts >= deletes) {\n                write({\n                  value: valueWithKey,\n                  type: `update`,\n                })\n              } else if (deletes > 0) {\n                write({\n                  value: valueWithKey,\n                  type: `delete`,\n                })\n              }\n            })\n          commit()\n        })\n      )\n      graph.finalize()\n    }\n\n    this.graph = graph\n    this.inputs = inputs\n    this.resultCollection = createCollection<TResults>({\n      id: crypto.randomUUID(), // TODO: remove when we don't require any more\n      getKey: (val: unknown) => {\n        return (val as any)._key\n      },\n      sync: {\n        sync,\n      },\n    })\n  }\n\n  get results() {\n    return this.resultCollection\n  }\n\n  private sendChangesToInput(\n    inputKey: string,\n    changes: Array<ChangeMessage>,\n    getKey: (item: ChangeMessage[`value`]) => any\n  ) {\n    const input = this.inputs[inputKey]!\n    const multiSetArray: MultiSetArray<unknown> = []\n    for (const change of changes) {\n      const key = getKey(change.value)\n      if (change.type === `insert`) {\n        multiSetArray.push([[key, change.value], 1])\n      } else if (change.type === `update`) {\n        multiSetArray.push([[key, change.previousValue], -1])\n        multiSetArray.push([[key, change.value], 1])\n      } else {\n        // change.type === `delete`\n        multiSetArray.push([[key, change.value], -1])\n      }\n    }\n    input.sendData(new MultiSet(multiSetArray))\n  }\n\n  private runGraph() {\n    this.graph.run()\n  }\n\n  start() {\n    if (this.state === `running`) {\n      throw new Error(`Query is already running`)\n    } else if (this.state === `stopped`) {\n      throw new Error(`Query is stopped`)\n    }\n\n    // Send initial state\n    Object.entries(this.inputCollections).forEach(([key, collection]) => {\n      this.sendChangesToInput(\n        key,\n        collection.currentStateAsChanges(),\n        collection.config.getKey\n      )\n    })\n    this.runGraph()\n\n    // Subscribe to changes\n    Object.entries(this.inputCollections).forEach(([key, collection]) => {\n      const unsubscribe = collection.subscribeChanges((changes) => {\n        this.sendChangesToInput(key, changes, collection.config.getKey)\n        this.runGraph()\n      })\n\n      this.unsubscribeCallbacks.push(unsubscribe)\n    })\n\n    this.state = `running`\n    return () => {\n      this.stop()\n    }\n  }\n\n  stop() {\n    this.unsubscribeCallbacks.forEach((unsubscribe) => unsubscribe())\n    this.unsubscribeCallbacks = []\n    this.state = `stopped`\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"compiled-query.js","sources":["../../../src/query/compiled-query.ts"],"sourcesContent":["import { D2, MultiSet, output } from \"@electric-sql/d2mini\"\nimport { createCollection } from \"../collection.js\"\nimport { compileQueryPipeline } from \"./pipeline-compiler.js\"\nimport type { Collection } from \"../collection.js\"\nimport type { ChangeMessage, ResolveType, SyncConfig } from \"../types.js\"\nimport type {\n  IStreamBuilder,\n  MultiSetArray,\n  RootStreamBuilder,\n} from \"@electric-sql/d2mini\"\nimport type { QueryBuilder, ResultsFromContext } from \"./query-builder.js\"\nimport type { Context, Schema } from \"./types.js\"\n\nexport function compileQuery<TContext extends Context<Schema>>(\n  queryBuilder: QueryBuilder<TContext>\n) {\n  return new CompiledQuery<\n    ResultsFromContext<TContext> & { _key?: string | number }\n  >(queryBuilder)\n}\n\nexport class CompiledQuery<TResults extends object = Record<string, unknown>> {\n  private graph: D2\n  private inputs: Record<string, RootStreamBuilder<any>>\n  private inputCollections: Record<string, Collection<any>>\n  private resultCollection: Collection<TResults>\n  public state: `compiled` | `running` | `stopped` = `compiled`\n  private unsubscribeCallbacks: Array<() => void> = []\n\n  constructor(queryBuilder: QueryBuilder<Context<Schema>>) {\n    const query = queryBuilder._query\n    const collections = query.collections\n\n    if (!collections) {\n      throw new Error(`No collections provided`)\n    }\n\n    this.inputCollections = collections\n\n    const graph = new D2()\n    const inputs = Object.fromEntries(\n      Object.entries(collections).map(([key]) => [key, graph.newInput<any>()])\n    )\n\n    // Use TResults directly to ensure type compatibility\n    const sync: SyncConfig<TResults>[`sync`] = ({\n      begin,\n      write,\n      commit,\n      collection,\n    }) => {\n      compileQueryPipeline<IStreamBuilder<[unknown, TResults]>>(\n        query,\n        inputs\n      ).pipe(\n        output((data) => {\n          begin()\n          data\n            .getInner()\n            .reduce((acc, [[key, value], multiplicity]) => {\n              const changes = acc.get(key) || {\n                deletes: 0,\n                inserts: 0,\n                value,\n              }\n              if (multiplicity < 0) {\n                changes.deletes += Math.abs(multiplicity)\n              } else if (multiplicity > 0) {\n                changes.inserts += multiplicity\n                changes.value = value\n              }\n              acc.set(key, changes)\n              return acc\n            }, new Map<unknown, { deletes: number; inserts: number; value: TResults }>())\n            .forEach((changes, rawKey) => {\n              const { deletes, inserts, value } = changes\n              const valueWithKey = { ...value, _key: rawKey }\n\n              // Simple singular insert.\n              if (inserts && deletes === 0) {\n                write({\n                  value: valueWithKey,\n                  type: `insert`,\n                })\n              } else if (\n                // Insert & update(s) (updates are a delete & insert)\n                inserts > deletes ||\n                // Just update(s) but the item is already in the collection (so\n                // was inserted previously).\n                (inserts === deletes &&\n                  collection.has(valueWithKey._key as string | number))\n              ) {\n                write({\n                  value: valueWithKey,\n                  type: `update`,\n                })\n                // Only delete is left as an option\n              } else if (deletes > 0) {\n                write({\n                  value: valueWithKey,\n                  type: `delete`,\n                })\n              } else {\n                throw new Error(\n                  `This should never happen ${JSON.stringify(changes)}`\n                )\n              }\n            })\n          commit()\n        })\n      )\n      graph.finalize()\n    }\n\n    this.graph = graph\n    this.inputs = inputs\n    this.resultCollection = createCollection<TResults>({\n      getKey: (val: unknown) => {\n        return (val as any)._key\n      },\n      sync: {\n        sync: sync as unknown as (params: {\n          collection: Collection<\n            ResolveType<TResults, never, Record<string, unknown>>,\n            string | number,\n            {}\n          >\n          begin: () => void\n          write: (\n            message: Omit<\n              ChangeMessage<\n                ResolveType<TResults, never, Record<string, unknown>>,\n                string | number\n              >,\n              `key`\n            >\n          ) => void\n          commit: () => void\n        }) => void,\n      },\n    }) as unknown as Collection<TResults, string | number, {}>\n  }\n\n  get results() {\n    return this.resultCollection\n  }\n\n  private sendChangesToInput(\n    inputKey: string,\n    changes: Array<ChangeMessage>,\n    getKey: (item: ChangeMessage[`value`]) => any\n  ) {\n    const input = this.inputs[inputKey]!\n    const multiSetArray: MultiSetArray<unknown> = []\n    for (const change of changes) {\n      const key = getKey(change.value)\n      if (change.type === `insert`) {\n        multiSetArray.push([[key, change.value], 1])\n      } else if (change.type === `update`) {\n        multiSetArray.push([[key, change.previousValue], -1])\n        multiSetArray.push([[key, change.value], 1])\n      } else {\n        // change.type === `delete`\n        multiSetArray.push([[key, change.value], -1])\n      }\n    }\n    input.sendData(new MultiSet(multiSetArray))\n  }\n\n  private runGraph() {\n    this.graph.run()\n  }\n\n  start() {\n    if (this.state === `running`) {\n      throw new Error(`Query is already running`)\n    } else if (this.state === `stopped`) {\n      throw new Error(`Query is stopped`)\n    }\n\n    // Send initial state\n    Object.entries(this.inputCollections).forEach(([key, collection]) => {\n      this.sendChangesToInput(\n        key,\n        collection.currentStateAsChanges(),\n        collection.config.getKey\n      )\n    })\n    this.runGraph()\n\n    // Subscribe to changes\n    Object.entries(this.inputCollections).forEach(([key, collection]) => {\n      const unsubscribe = collection.subscribeChanges((changes) => {\n        this.sendChangesToInput(key, changes, collection.config.getKey)\n        this.runGraph()\n      })\n\n      this.unsubscribeCallbacks.push(unsubscribe)\n    })\n\n    this.state = `running`\n    return () => {\n      this.stop()\n    }\n  }\n\n  stop() {\n    this.unsubscribeCallbacks.forEach((unsubscribe) => unsubscribe())\n    this.unsubscribeCallbacks = []\n    this.state = `stopped`\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -2,6 +2,23 @@ import { IStreamBuilder } from '@electric-sql/d2mini';
 import { Collection } from './collection.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.js';
+/**
+ * Helper type to extract the output type from a standard schema
+ *
+ * @internal This is used by the type resolution system
+ */
+export type InferSchemaOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> extends object ? StandardSchemaV1.InferOutput<T> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Helper type to determine the final type based on priority:
+ * 1. Explicit generic TExplicit (if not 'unknown')
+ * 2. Schema output type (if schema provided)
+ * 3. Fallback type TFallback
+ *
+ * @remarks
+ * This type is used internally to resolve the collection item type based on the provided generics and schema.
+ * Users should not need to use this type directly, but understanding the priority order helps when defining collections.
+ */
+export type ResolveType<TExplicit, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>> = unknown extends TExplicit ? [TSchema] extends [never] ? TFallback : InferSchemaOutput<TSchema> : TExplicit extends object ? TExplicit : Record<string, unknown>;
 export type TransactionState = `pending` | `persisting` | `completed` | `failed`;
 /**
  * Represents a utility function that can be attached to a collection
@@ -15,11 +32,11 @@ export type UtilsRecord = Record<string, Fn>;
  * 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>> {
+export interface PendingMutation<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> {
     mutationId: string;
-    original: Partial<T>;
+    original: TOperation extends `insert` ? {} : T;
     modified: T;
-    changes: Partial<T>;
+    changes: TOperation extends `insert` ? T : TOperation extends `delete` ? T : Partial<T>;
     globalKey: string;
     key: any;
     type: OperationType;
@@ -44,8 +61,8 @@ export type NonEmptyArray<T> = [T, ...Array<T>];
  * Utility type for a Transaction with at least one mutation
  * This is used internally by the Transaction.commit method
  */
-export type TransactionWithMutations<T extends object = Record<string, unknown>> = Transaction<T> & {
-    mutations: NonEmptyArray<PendingMutation<T>>;
+export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Transaction<T> & {
+    mutations: NonEmptyArray<PendingMutation<T, TOperation>>;
 };
 export interface TransactionConfig<T extends object = Record<string, unknown>> {
     /** Unique identifier for the transaction */
@@ -106,10 +123,22 @@ export interface OperationConfig {
 export interface InsertConfig {
     metadata?: Record<string, unknown>;
 }
-export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+export type UpdateMutationFnParams<T extends object = Record<string, unknown>> = {
+    transaction: TransactionWithMutations<T, `update`>;
+};
+export type InsertMutationFnParams<T extends object = Record<string, unknown>> = {
+    transaction: TransactionWithMutations<T, `insert`>;
+};
+export type DeleteMutationFnParams<T extends object = Record<string, unknown>> = {
+    transaction: TransactionWithMutations<T, `delete`>;
+};
+export type InsertMutationFn<T extends object = Record<string, unknown>> = (params: InsertMutationFnParams<T>) => Promise<any>;
+export type UpdateMutationFn<T extends object = Record<string, unknown>> = (params: UpdateMutationFnParams<T>) => Promise<any>;
+export type DeleteMutationFn<T extends object = Record<string, unknown>> = (params: DeleteMutationFnParams<T>) => Promise<any>;
+export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1> {
     id?: string;
     sync: SyncConfig<T, TKey>;
-    schema?: StandardSchema<T>;
+    schema?: TSchema;
     /**
      * Function to extract the ID from an object
      * This is required for update/delete operations which now only accept IDs
@@ -125,19 +154,19 @@ export interface CollectionConfig<T extends object = Record<string, unknown>, TK
      * @param params Object containing transaction and mutation information
      * @returns Promise resolving to any value
      */
-    onInsert?: MutationFn<T>;
+    onInsert?: InsertMutationFn<T>;
     /**
      * Optional asynchronous handler function called before an update operation
      * @param params Object containing transaction and mutation information
      * @returns Promise resolving to any value
      */
-    onUpdate?: MutationFn<T>;
+    onUpdate?: UpdateMutationFn<T>;
     /**
      * Optional asynchronous handler function called before a delete operation
      * @param params Object containing transaction and mutation information
      * @returns Promise resolving to any value
      */
-    onDelete?: MutationFn<T>;
+    onDelete?: DeleteMutationFn<T>;
 }
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<ChangeMessage<T>>;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "dependencies": {
     "@electric-sql/d2mini": "^0.1.2",
     "@standard-schema/spec": "^1.0.0",

package/src/collection.ts

@@ -11,23 +11,16 @@ import type {
   OperationConfig,
   OptimisticChangeMessage,
   PendingMutation,
+  ResolveType,
   StandardSchema,
   Transaction as TransactionType,
   UtilsRecord,
 } from "./types"
+import type { StandardSchemaV1 } from "@standard-schema/spec"
 
 // Store collections in memory
 export const collectionsStore = new Map<string, CollectionImpl<any, any>>()
 
-// Map to track loading collections
-const loadingCollectionResolvers = new Map<
-  string,
-  {
-    promise: Promise<CollectionImpl<any, any>>
-    resolve: (value: CollectionImpl<any, any>) => void
-  }
->()
-
 interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
   committed: boolean
   operations: Array<OptimisticChangeMessage<T>>
@@ -36,6 +29,7 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
  * @template T - The type of items in the collection
+ * @template TKey - The type of the key for the collection
  * @template TUtils - The utilities record type
  */
 export interface Collection<
@@ -49,20 +43,53 @@ export interface Collection<
 /**
  * Creates a new Collection instance with the given configuration
  *
- * @template T - The type of items in the collection
+ * @template TExplicit - The explicit type of items in the collection (highest priority)
  * @template TKey - The type of the key for the collection
  * @template TUtils - The utilities record type
+ * @template TSchema - The schema type for validation and type inference (second priority)
+ * @template TFallback - The fallback type if no explicit or schema type is provided
  * @param options - Collection options with optional utilities
  * @returns A new Collection with utilities exposed both at top level and under .utils
+ *
+ * @example
+ * // Using explicit type
+ * const todos = createCollection<Todo>({
+ *   getKey: (todo) => todo.id,
+ *   sync: { sync: () => {} }
+ * })
+ *
+ * // Using schema for type inference (preferred as it also gives you client side validation)
+ * const todoSchema = z.object({
+ *   id: z.string(),
+ *   title: z.string(),
+ *   completed: z.boolean()
+ * })
+ *
+ * const todos = createCollection({
+ *   schema: todoSchema,
+ *   getKey: (todo) => todo.id,
+ *   sync: { sync: () => {} }
+ * })
+ *
+ * // Note: You must provide either an explicit type or a schema, but not both
  */
 export function createCollection<
-  T extends object = Record<string, unknown>,
+  TExplicit = unknown,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = {},
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+  TFallback extends object = Record<string, unknown>,
 >(
-  options: CollectionConfig<T, TKey> & { utils?: TUtils }
-): Collection<T, TKey, TUtils> {
-  const collection = new CollectionImpl<T, TKey>(options)
+  options: CollectionConfig<
+    ResolveType<TExplicit, TSchema, TFallback>,
+    TKey,
+    TSchema
+  > & { utils?: TUtils }
+): Collection<ResolveType<TExplicit, TSchema, TFallback>, TKey, TUtils> {
+  const collection = new CollectionImpl<
+    ResolveType<TExplicit, TSchema, TFallback>,
+    TKey
+  >(options)
 
   // Copy utils to both top level and .utils namespace
   if (options.utils) {
@@ -71,98 +98,11 @@ export function createCollection<
     collection.utils = {} as TUtils
   }
 
-  return collection as Collection<T, TKey, TUtils>
-}
-
-/**
- * Preloads a collection with the given configuration
- * Returns a promise that resolves once the sync tool has done its first commit (initial sync is finished)
- * If the collection has already loaded, it resolves immediately
- *
- * This function is useful in route loaders or similar pre-rendering scenarios where you want
- * to ensure data is available before a route transition completes. It uses the same shared collection
- * instance that will be used by useCollection, ensuring data consistency.
- *
- * @example
- * ```typescript
- * // In a route loader
- * async function loader({ params }) {
- *   await preloadCollection({
- *     id: `users-${params.userId}`,
- *     sync: { ... },
- *   });
- *
- *   return null;
- * }
- * ```
- *
- * @template T - The type of items in the collection
- * @param config - Configuration for the collection, including id and sync
- * @returns Promise that resolves when the initial sync is finished
- */
-export function preloadCollection<
-  T extends object = Record<string, unknown>,
-  TKey extends string | number = string | number,
->(config: CollectionConfig<T, TKey>): Promise<CollectionImpl<T, TKey>> {
-  if (!config.id) {
-    throw new Error(`The id property is required for preloadCollection`)
-  }
-
-  // If the collection is already fully loaded, return a resolved promise
-  if (
-    collectionsStore.has(config.id) &&
-    !loadingCollectionResolvers.has(config.id)
-  ) {
-    return Promise.resolve(
-      collectionsStore.get(config.id)! as CollectionImpl<T, TKey>
-    )
-  }
-
-  // If the collection is in the process of loading, return its promise
-  if (loadingCollectionResolvers.has(config.id)) {
-    return loadingCollectionResolvers.get(config.id)!.promise
-  }
-
-  // Create a new collection instance if it doesn't exist
-  if (!collectionsStore.has(config.id)) {
-    collectionsStore.set(
-      config.id,
-      createCollection<T, TKey>({
-        id: config.id,
-        getKey: config.getKey,
-        sync: config.sync,
-        schema: config.schema,
-      })
-    )
-  }
-
-  const collection = collectionsStore.get(config.id)! as CollectionImpl<T, TKey>
-
-  // Create a promise that will resolve after the first commit
-  let resolveFirstCommit: (value: CollectionImpl<T, TKey>) => void
-  const firstCommitPromise = new Promise<CollectionImpl<T, TKey>>((resolve) => {
-    resolveFirstCommit = resolve
-  })
-
-  // Store the loading promise first
-  loadingCollectionResolvers.set(config.id, {
-    promise: firstCommitPromise,
-    resolve: resolveFirstCommit!,
-  })
-
-  // Register a one-time listener for the first commit
-  collection.onFirstCommit(() => {
-    if (!config.id) {
-      throw new Error(`The id property is required for preloadCollection`)
-    }
-    if (loadingCollectionResolvers.has(config.id)) {
-      const resolver = loadingCollectionResolvers.get(config.id)!
-      loadingCollectionResolvers.delete(config.id)
-      resolver.resolve(collection)
-    }
-  })
-
-  return firstCommitPromise
+  return collection as Collection<
+    ResolveType<TExplicit, TSchema, TFallback>,
+    TKey,
+    TUtils
+  >
 }
 
 /**
@@ -184,8 +124,8 @@ export class SchemaValidationError extends Error {
     message?: string
   ) {
     const defaultMessage = `${type === `insert` ? `Insert` : `Update`} validation failed: ${issues
-      .map((issue) => issue.message)
-      .join(`, `)}`
+      .map((issue) => `\n- ${issue.message} - path: ${issue.path}`)
+      .join(``)}`
 
     super(message || defaultMessage)
     this.name = `SchemaValidationError`
@@ -221,7 +161,7 @@ export class CollectionImpl<
 
   private pendingSyncedTransactions: Array<PendingSyncedTransaction<T>> = []
   private syncedKeys = new Set<TKey>()
-  public config: CollectionConfig<T, TKey>
+  public config: CollectionConfig<T, TKey, any>
   private hasReceivedFirstCommit = false
 
   // Array to store one-time commit listeners
@@ -244,7 +184,7 @@ export class CollectionImpl<
    * @param config - Configuration object for the collection
    * @throws Error if sync config is missing
    */
-  constructor(config: CollectionConfig<T, TKey>) {
+  constructor(config: CollectionConfig<T, TKey, any>) {
     // eslint-disable-next-line
     if (!config) {
       throw new Error(`Collection requires a config`)
@@ -803,7 +743,7 @@ export class CollectionImpl<
     }
 
     const items = Array.isArray(data) ? data : [data]
-    const mutations: Array<PendingMutation<T>> = []
+    const mutations: Array<PendingMutation<T, `insert`>> = []
 
     // Create mutations for each item
     items.forEach((item) => {
@@ -817,7 +757,7 @@ export class CollectionImpl<
       }
       const globalKey = this.generateGlobalKey(key, item)
 
-      const mutation: PendingMutation<T> = {
+      const mutation: PendingMutation<T, `insert`> = {
         mutationId: crypto.randomUUID(),
         original: {},
         modified: validatedData,
@@ -987,7 +927,7 @@ export class CollectionImpl<
     }
 
     // Create mutations for each object that has changes
-    const mutations: Array<PendingMutation<T>> = keysArray
+    const mutations: Array<PendingMutation<T, `update`>> = keysArray
       .map((key, index) => {
         const itemChanges = changesArray[index] // User-provided changes for this specific item
 
@@ -1025,9 +965,9 @@ export class CollectionImpl<
 
         return {
           mutationId: crypto.randomUUID(),
-          original: originalItem as Record<string, unknown>,
-          modified: modifiedItem as Record<string, unknown>,
-          changes: validatedUpdatePayload as Record<string, unknown>,
+          original: originalItem,
+          modified: modifiedItem,
+          changes: validatedUpdatePayload as Partial<T>,
           globalKey,
           key,
           metadata: config.metadata as unknown,
@@ -1041,7 +981,7 @@ export class CollectionImpl<
           collection: this,
         }
       })
-      .filter(Boolean) as Array<PendingMutation<T>>
+      .filter(Boolean) as Array<PendingMutation<T, `update`>>
 
     // If no changes were made, return an empty transaction early
     if (mutations.length === 0) {
@@ -1117,15 +1057,20 @@ export class CollectionImpl<
     }
 
     const keysArray = Array.isArray(keys) ? keys : [keys]
-    const mutations: Array<PendingMutation<T>> = []
+    const mutations: Array<PendingMutation<T, `delete`>> = []
 
     for (const key of keysArray) {
+      if (!this.has(key)) {
+        throw new Error(
+          `Collection.delete was called with key '${key}' but there is no item in the collection with this key`
+        )
+      }
       const globalKey = this.generateGlobalKey(key, this.get(key)!)
-      const mutation: PendingMutation<T> = {
+      const mutation: PendingMutation<T, `delete`> = {
         mutationId: crypto.randomUUID(),
-        original: this.get(key) || {},
+        original: this.get(key)!,
         modified: this.get(key)!,
-        changes: this.get(key) || {},
+        changes: this.get(key)!,
         globalKey,
         key,
         metadata: config?.metadata as unknown,

package/src/query/compiled-query.ts

@@ -2,7 +2,7 @@ import { D2, MultiSet, output } from "@electric-sql/d2mini"
 import { createCollection } from "../collection.js"
 import { compileQueryPipeline } from "./pipeline-compiler.js"
 import type { Collection } from "../collection.js"
-import type { ChangeMessage, SyncConfig } from "../types.js"
+import type { ChangeMessage, ResolveType, SyncConfig } from "../types.js"
 import type {
   IStreamBuilder,
   MultiSetArray,
@@ -42,7 +42,13 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
       Object.entries(collections).map(([key]) => [key, graph.newInput<any>()])
     )
 
-    const sync: SyncConfig<TResults>[`sync`] = ({ begin, write, commit }) => {
+    // Use TResults directly to ensure type compatibility
+    const sync: SyncConfig<TResults>[`sync`] = ({
+      begin,
+      write,
+      commit,
+      collection,
+    }) => {
       compileQueryPipeline<IStreamBuilder<[unknown, TResults]>>(
         query,
         inputs
@@ -69,21 +75,35 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
             .forEach((changes, rawKey) => {
               const { deletes, inserts, value } = changes
               const valueWithKey = { ...value, _key: rawKey }
-              if (inserts && !deletes) {
+
+              // Simple singular insert.
+              if (inserts && deletes === 0) {
                 write({
                   value: valueWithKey,
                   type: `insert`,
                 })
-              } else if (inserts >= deletes) {
+              } else if (
+                // Insert & update(s) (updates are a delete & insert)
+                inserts > deletes ||
+                // Just update(s) but the item is already in the collection (so
+                // was inserted previously).
+                (inserts === deletes &&
+                  collection.has(valueWithKey._key as string | number))
+              ) {
                 write({
                   value: valueWithKey,
                   type: `update`,
                 })
+                // Only delete is left as an option
               } else if (deletes > 0) {
                 write({
                   value: valueWithKey,
                   type: `delete`,
                 })
+              } else {
+                throw new Error(
+                  `This should never happen ${JSON.stringify(changes)}`
+                )
               }
             })
           commit()
@@ -95,14 +115,30 @@ export class CompiledQuery<TResults extends object = Record<string, unknown>> {
     this.graph = graph
     this.inputs = inputs
     this.resultCollection = createCollection<TResults>({
-      id: crypto.randomUUID(), // TODO: remove when we don't require any more
       getKey: (val: unknown) => {
         return (val as any)._key
       },
       sync: {
-        sync,
+        sync: sync as unknown as (params: {
+          collection: Collection<
+            ResolveType<TResults, never, Record<string, unknown>>,
+            string | number,
+            {}
+          >
+          begin: () => void
+          write: (
+            message: Omit<
+              ChangeMessage<
+                ResolveType<TResults, never, Record<string, unknown>>,
+                string | number
+              >,
+              `key`
+            >
+          ) => void
+          commit: () => void
+        }) => void,
       },
-    })
+    }) as unknown as Collection<TResults, string | number, {}>
   }
 
   get results() {