@tanstack/db 0.2.4 → 0.2.5

package/src/local-only.ts

@@ -1,9 +1,10 @@
 import type {
+  BaseCollectionConfig,
   CollectionConfig,
   DeleteMutationFnParams,
+  InferSchemaOutput,
   InsertMutationFnParams,
   OperationType,
-  ResolveType,
   SyncConfig,
   UpdateMutationFnParams,
   UtilsRecord,
@@ -12,76 +13,23 @@ import type { StandardSchemaV1 } from "@standard-schema/spec"
 
 /**
  * Configuration interface for Local-only collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @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
- * @template TKey - The type of the key returned by getKey
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
+ * @template TKey - The type of the key returned by `getKey`
  */
 export interface LocalOnlyCollectionConfig<
-  TExplicit = unknown,
+  T extends object = object,
   TSchema extends StandardSchemaV1 = never,
-  TFallback extends Record<string, unknown> = Record<string, unknown>,
   TKey extends string | number = string | number,
-> {
-  /**
-   * Standard Collection configuration properties
-   */
-  id?: string
-  schema?: TSchema
-  getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => TKey
-
+> extends Omit<
+    BaseCollectionConfig<T, TKey, TSchema, LocalOnlyCollectionUtils>,
+    `gcTime` | `startSync`
+  > {
   /**
    * Optional initial data to populate the collection with on creation
    * This data will be applied during the initial sync process
    */
-  initialData?: Array<ResolveType<TExplicit, TSchema, TFallback>>
-
-  /**
-   * Optional asynchronous handler function called after an insert operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onInsert?: (
-    params: InsertMutationFnParams<
-      ResolveType<TExplicit, TSchema, TFallback>,
-      TKey,
-      LocalOnlyCollectionUtils
-    >
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called after an update operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onUpdate?: (
-    params: UpdateMutationFnParams<
-      ResolveType<TExplicit, TSchema, TFallback>,
-      TKey,
-      LocalOnlyCollectionUtils
-    >
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called after a delete operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onDelete?: (
-    params: DeleteMutationFnParams<
-      ResolveType<TExplicit, TSchema, TFallback>,
-      TKey,
-      LocalOnlyCollectionUtils
-    >
-  ) => Promise<any>
+  initialData?: Array<T>
 }
 
 /**
@@ -96,9 +44,7 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {}
  * that immediately "syncs" all optimistic changes to the collection, making them permanent.
  * Perfect for local-only data that doesn't need persistence or external synchronization.
  *
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @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
+ * @template T - The schema type if a schema is provided, otherwise the type of items in the collection
  * @template TKey - The type of the key returned by getKey
  * @param config - Configuration options for the Local-only collection
  * @returns Collection options with utilities (currently empty but follows the pattern)
@@ -135,29 +81,55 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {}
  *   })
  * )
  */
+
+// Overload for when schema is provided
 export function localOnlyCollectionOptions<
-  TExplicit = unknown,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends Record<string, unknown> = Record<string, unknown>,
+  T extends StandardSchemaV1,
   TKey extends string | number = string | number,
 >(
-  config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>
-): CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey> & {
+  config: LocalOnlyCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
+    schema: T
+  }
+): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
   utils: LocalOnlyCollectionUtils
-} {
-  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>
+  schema: T
+}
+
+// Overload for when no schema is provided
+// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config
+export function localOnlyCollectionOptions<
+  T extends object,
+  TKey extends string | number = string | number,
+>(
+  config: LocalOnlyCollectionConfig<T, never, TKey> & {
+    schema?: never // prohibit schema
+  }
+): CollectionConfig<T, TKey> & {
+  utils: LocalOnlyCollectionUtils
+  schema?: never // no schema in the result
+}
 
+export function localOnlyCollectionOptions(
+  config: LocalOnlyCollectionConfig<any, any, string | number>
+): CollectionConfig<any, string | number, any> & {
+  utils: LocalOnlyCollectionUtils
+  schema?: StandardSchemaV1
+} {
   const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config
 
   // Create the sync configuration with transaction confirmation capability
-  const syncResult = createLocalOnlySync<ResolvedType, TKey>(initialData)
+  const syncResult = createLocalOnlySync(initialData)
 
   /**
    * Create wrapper handlers that call user handlers first, then confirm transactions
    * Wraps the user's onInsert handler to also confirm the transaction immediately
    */
   const wrappedOnInsert = async (
-    params: InsertMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+    params: InsertMutationFnParams<
+      any,
+      string | number,
+      LocalOnlyCollectionUtils
+    >
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -175,7 +147,11 @@ export function localOnlyCollectionOptions<
    * Wrapper for onUpdate handler that also confirms the transaction immediately
    */
   const wrappedOnUpdate = async (
-    params: UpdateMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+    params: UpdateMutationFnParams<
+      any,
+      string | number,
+      LocalOnlyCollectionUtils
+    >
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -193,7 +169,11 @@ export function localOnlyCollectionOptions<
    * Wrapper for onDelete handler that also confirms the transaction immediately
    */
   const wrappedOnDelete = async (
-    params: DeleteMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+    params: DeleteMutationFnParams<
+      any,
+      string | number,
+      LocalOnlyCollectionUtils
+    >
   ) => {
     // Call user handler first if provided
     let handlerResult

package/src/local-storage.ts

@@ -7,10 +7,11 @@ import {
   StorageKeyRequiredError,
 } from "./errors"
 import type {
+  BaseCollectionConfig,
   CollectionConfig,
   DeleteMutationFnParams,
+  InferSchemaOutput,
   InsertMutationFnParams,
-  ResolveType,
   SyncConfig,
   UpdateMutationFnParams,
   UtilsRecord,
@@ -46,23 +47,15 @@ interface StoredItem<T> {
 
 /**
  * Configuration interface for localStorage collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @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
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
+ * @template TKey - The type of the key returned by `getKey`
  */
 export interface LocalStorageCollectionConfig<
-  TExplicit = unknown,
+  T extends object = object,
   TSchema extends StandardSchemaV1 = never,
-  TFallback extends object = Record<string, unknown>,
-> {
+  TKey extends string | number = string | number,
+> extends BaseCollectionConfig<T, TKey, TSchema> {
   /**
    * The key to use for storing the collection data in localStorage/sessionStorage
    */
@@ -79,41 +72,6 @@ export interface LocalStorageCollectionConfig<
    * Can be any object that implements addEventListener/removeEventListener for storage events
    */
   storageEventApi?: StorageEventApi
-
-  /**
-   * Collection identifier (defaults to "local-collection:{storageKey}" if not provided)
-   */
-  id?: string
-  schema?: TSchema
-  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]
-  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]
-
-  /**
-   * Optional asynchronous handler function called before an insert operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onInsert?: (
-    params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called before an update operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onUpdate?: (
-    params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<any>
-
-  /**
-   * Optional asynchronous handler function called before a delete operation
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to any value
-   */
-  onDelete?: (
-    params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<any>
 }
 
 /**
@@ -202,18 +160,43 @@ function generateUuid(): string {
  *   })
  * )
  */
+
+// Overload for when schema is provided
 export function localStorageCollectionOptions<
-  TExplicit = unknown,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends object = Record<string, unknown>,
+  T extends StandardSchemaV1,
+  TKey extends string | number = string | number,
 >(
-  config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>
-): Omit<CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>, `id`> & {
+  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
+    schema: T
+  }
+): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
   id: string
   utils: LocalStorageCollectionUtils
-} {
-  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>
+  schema: T
+}
 
+// Overload for when no schema is provided
+// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config
+export function localStorageCollectionOptions<
+  T extends object,
+  TKey extends string | number = string | number,
+>(
+  config: LocalStorageCollectionConfig<T, never, TKey> & {
+    schema?: never // prohibit schema
+  }
+): CollectionConfig<T, TKey> & {
+  id: string
+  utils: LocalStorageCollectionUtils
+  schema?: never // no schema in the result
+}
+
+export function localStorageCollectionOptions(
+  config: LocalStorageCollectionConfig<any, any, string | number>
+): Omit<CollectionConfig<any, string | number, any>, `id`> & {
+  id: string
+  utils: LocalStorageCollectionUtils
+  schema?: StandardSchemaV1
+} {
   // Validate required parameters
   if (!config.storageKey) {
     throw new StorageKeyRequiredError()
@@ -237,10 +220,10 @@ export function localStorageCollectionOptions<
   }
 
   // Track the last known state to detect changes
-  const lastKnownData = new Map<string | number, StoredItem<ResolvedType>>()
+  const lastKnownData = new Map<string | number, StoredItem<any>>()
 
   // Create the sync configuration
-  const sync = createLocalStorageSync<ResolvedType>(
+  const sync = createLocalStorageSync<any>(
     config.storageKey,
     storage,
     storageEventApi,
@@ -263,11 +246,11 @@ export function localStorageCollectionOptions<
    * @param dataMap - Map of items with version tracking to save to storage
    */
   const saveToStorage = (
-    dataMap: Map<string | number, StoredItem<ResolvedType>>
+    dataMap: Map<string | number, StoredItem<any>>
   ): void => {
     try {
       // Convert Map to object format for storage
-      const objectData: Record<string, StoredItem<ResolvedType>> = {}
+      const objectData: Record<string, StoredItem<any>> = {}
       dataMap.forEach((storedItem, key) => {
         objectData[String(key)] = storedItem
       })
@@ -302,9 +285,7 @@ export function localStorageCollectionOptions<
    * Create wrapper handlers for direct persistence operations that perform actual storage operations
    * Wraps the user's onInsert handler to also save changes to localStorage
    */
-  const wrappedOnInsert = async (
-    params: InsertMutationFnParams<ResolvedType>
-  ) => {
+  const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
       validateJsonSerializable(mutation.modified, `insert`)
@@ -318,15 +299,12 @@ export function localStorageCollectionOptions<
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<ResolvedType>(
-      config.storageKey,
-      storage
-    )
+    const currentData = loadFromStorage<any>(config.storageKey, storage)
 
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.modified)
-      const storedItem: StoredItem<ResolvedType> = {
+      const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
@@ -342,9 +320,7 @@ export function localStorageCollectionOptions<
     return handlerResult
   }
 
-  const wrappedOnUpdate = async (
-    params: UpdateMutationFnParams<ResolvedType>
-  ) => {
+  const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
       validateJsonSerializable(mutation.modified, `update`)
@@ -358,15 +334,12 @@ export function localStorageCollectionOptions<
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<ResolvedType>(
-      config.storageKey,
-      storage
-    )
+    const currentData = loadFromStorage<any>(config.storageKey, storage)
 
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.modified)
-      const storedItem: StoredItem<ResolvedType> = {
+      const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
@@ -382,9 +355,7 @@ export function localStorageCollectionOptions<
     return handlerResult
   }
 
-  const wrappedOnDelete = async (
-    params: DeleteMutationFnParams<ResolvedType>
-  ) => {
+  const wrappedOnDelete = async (params: DeleteMutationFnParams<any>) => {
     // Call the user handler BEFORE persisting changes (if provided)
     let handlerResult: any = {}
     if (config.onDelete) {
@@ -393,15 +364,12 @@ export function localStorageCollectionOptions<
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<ResolvedType>(
-      config.storageKey,
-      storage
-    )
+    const currentData = loadFromStorage<any>(config.storageKey, storage)
 
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
       // For delete operations, mutation.original contains the full object
-      const key = config.getKey(mutation.original as ResolvedType)
+      const key = config.getKey(mutation.original)
       currentData.delete(key)
     })
 

package/src/query/builder/types.ts

@@ -8,7 +8,6 @@ import type {
   Value,
 } from "../ir.js"
 import type { QueryBuilder } from "./index.js"
-import type { ResolveType } from "../../types.js"
 
 /**
  * Context - The central state container for query builder operations
@@ -77,19 +76,11 @@ export type Source = {
 /**
  * InferCollectionType - Extracts the TypeScript type from a CollectionImpl
  *
- * This helper ensures we get the same type that would be used when creating
- * the collection itself. It uses the internal `ResolveType` logic to maintain
- * consistency between collection creation and query type inference.
- *
- * The complex generic parameters extract:
- * - U: The base document type
- * - TSchema: The schema definition
- * - The resolved type combines these with any transforms
+ * This helper ensures we get the same type that was used when creating the collection itself.
+ * This can be an explicit type passed by the user or the schema output type.
  */
 export type InferCollectionType<T> =
-  T extends CollectionImpl<infer U, any, any, infer TSchema, any>
-    ? ResolveType<U, TSchema, U>
-    : never
+  T extends CollectionImpl<infer TOutput, any, any, any, any> ? TOutput : never
 
 /**
  * SchemaFromSource - Converts a Source definition into a ContextSchema

package/src/query/live-query-collection.ts

@@ -130,7 +130,7 @@ export function createLiveQueryCollection<
 
 /**
  * Bridge function that handles the type compatibility between query2's TResult
- * and core collection's ResolveType without exposing ugly type assertions to users
+ * and core collection's output type without exposing ugly type assertions to users
  */
 function bridgeToCreateCollection<
   TResult extends object,

package/src/types.ts

@@ -28,51 +28,6 @@ export type InferSchemaInput<T> = T extends StandardSchemaV1
     : Record<string, unknown>
   : Record<string, unknown>
 
-/**
- * Helper type to determine the insert input type
- * This takes the raw generics (TExplicit, TSchema, TFallback) instead of the resolved T.
- *
- * Priority:
- * 1. Explicit generic TExplicit (if not 'unknown')
- * 2. Schema input type (if schema provided)
- * 3. Fallback type TFallback
- *
- * @internal This is used for collection insert type inference
- */
-export type ResolveInsertInput<
-  TExplicit = unknown,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends object = Record<string, unknown>,
-> = unknown extends TExplicit
-  ? [TSchema] extends [never]
-    ? TFallback
-    : InferSchemaInput<TSchema>
-  : TExplicit extends object
-    ? TExplicit
-    : 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`
 
 /**
@@ -304,19 +259,22 @@ export type InsertMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = Record<string, Fn>,
-> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<any>
+  TReturn = any,
+> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>
 
 export type UpdateMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = Record<string, Fn>,
-> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<any>
+  TReturn = any,
+> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>
 
 export type DeleteMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = Record<string, Fn>,
-> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<any>
+  TReturn = any,
+> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>
 
 /**
  * Collection status values for lifecycle management
@@ -347,16 +305,20 @@ export type CollectionStatus =
   /** Collection has been cleaned up and resources freed */
   | `cleaned-up`
 
-export interface CollectionConfig<
+export interface BaseCollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-  TSchema extends StandardSchemaV1 = StandardSchemaV1,
-  TInsertInput extends object = T,
+  // Let TSchema default to `never` such that if a user provides T explicitly and no schema
+  // then TSchema will be `never` otherwise if it would default to StandardSchemaV1
+  // then it would conflict with the overloads of createCollection which
+  // requires either T to be provided or a schema to be provided but not both!
+  TSchema extends StandardSchemaV1 = never,
+  TUtils extends UtilsRecord = Record<string, Fn>,
+  TReturn = any,
 > {
   // If an id isn't passed in, a UUID will be
   // generated for it.
   id?: string
-  sync: SyncConfig<T, TKey>
   schema?: TSchema
   /**
    * Function to extract the ID from an object
@@ -439,7 +401,7 @@ export interface CollectionConfig<
    *   })
    * }
    */
-  onInsert?: InsertMutationFn<TInsertInput, TKey>
+  onInsert?: InsertMutationFn<T, TKey, TUtils, TReturn>
 
   /**
    * Optional asynchronous handler function called before an update operation
@@ -483,7 +445,7 @@ export interface CollectionConfig<
    *   }
    * }
    */
-  onUpdate?: UpdateMutationFn<T, TKey>
+  onUpdate?: UpdateMutationFn<T, TKey, TUtils, TReturn>
   /**
    * Optional asynchronous handler function called before a delete operation
    * @param params Object containing transaction and collection information
@@ -526,7 +488,15 @@ export interface CollectionConfig<
    *   }
    * }
    */
-  onDelete?: DeleteMutationFn<T, TKey>
+  onDelete?: DeleteMutationFn<T, TKey, TUtils, TReturn>
+}
+
+export interface CollectionConfig<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TSchema extends StandardSchemaV1 = never,
+> extends BaseCollectionConfig<T, TKey, TSchema> {
+  sync: SyncConfig<T, TKey>
 }
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<