@tanstack/db 0.2.3 → 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
@@ -500,20 +491,20 @@ export type Ref<T = any> = {
   [K in keyof T]: IsNonExactOptional<T[K]> extends true
     ? IsNonExactNullable<T[K]> extends true
       ? // Both optional and nullable
-        NonNullable<T[K]> extends Record<string, any>
+        IsPlainObject<NonNullable<T[K]>> extends true
         ? Ref<NonNullable<T[K]>> | undefined
         : RefLeaf<NonNullable<T[K]>> | undefined
       : // Optional only
-        NonUndefined<T[K]> extends Record<string, any>
+        IsPlainObject<NonUndefined<T[K]>> extends true
         ? Ref<NonUndefined<T[K]>> | undefined
         : RefLeaf<NonUndefined<T[K]>> | undefined
     : IsNonExactNullable<T[K]> extends true
       ? // Nullable only
-        NonNull<T[K]> extends Record<string, any>
+        IsPlainObject<NonNull<T[K]>> extends true
         ? Ref<NonNull<T[K]>> | null
         : RefLeaf<NonNull<T[K]>> | null
       : // Required
-        T[K] extends Record<string, any>
+        IsPlainObject<T[K]> extends true
         ? Ref<T[K]>
         : RefLeaf<T[K]>
 } & RefLeaf<T>
@@ -825,3 +816,48 @@ export type WithResult<TContext extends Context, TResult> = Prettify<
 export type Prettify<T> = {
   [K in keyof T]: T[K]
 } & {}
+
+/**
+ * IsPlainObject - Utility type to check if T is a plain object
+ */
+type IsPlainObject<T> = T extends unknown
+  ? T extends object
+    ? T extends ReadonlyArray<any>
+      ? false
+      : T extends JsBuiltIns
+        ? false
+        : true
+    : false
+  : false
+
+/**
+ * JsBuiltIns - List of JavaScript built-ins
+ */
+type JsBuiltIns =
+  | ArrayBuffer
+  | ArrayBufferLike
+  | AsyncGenerator<any, any, any>
+  | BigInt64Array
+  | BigUint64Array
+  | DataView
+  | Date
+  | Error
+  | Float32Array
+  | Float64Array
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  | Function
+  | Generator<any, any, any>
+  | Int16Array
+  | Int32Array
+  | Int8Array
+  | Map<any, any>
+  | Promise<any>
+  | RegExp
+  | Set<any>
+  | string
+  | Uint16Array
+  | Uint32Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | WeakMap<any, any>
+  | WeakSet<any>

package/src/query/compiler/joins.ts

@@ -243,7 +243,7 @@ function processJoin(
       const activePipelineWithLoading: IStreamBuilder<
         [key: unknown, [originalKey: string, namespacedRow: NamespacedRow]]
       > = activePipeline.pipe(
-        tap(([joinKey, _]) => {
+        tap((data) => {
           if (deoptimized) {
             return
           }
@@ -270,10 +270,11 @@ function processJoin(
 
           const { loadKeys, loadInitialState } = collectionCallbacks
 
-          if (index && index.supports(`eq`)) {
+          if (index && index.supports(`in`)) {
             // Use the index to fetch the PKs of the rows in the lazy collection
             // that match this row from the active collection based on the value of the joinKey
-            const matchingKeys = index.lookup(`eq`, joinKey)
+            const joinKeys = data.getInner().map(([[joinKey]]) => joinKey)
+            const matchingKeys = index.lookup(`in`, joinKeys)
             // Inform the lazy collection that those keys need to be loaded
             loadKeys(matchingKeys)
           } else {

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

@@ -138,6 +138,7 @@ export class CollectionSubscriber<
     keys: Iterable<string | number>,
     filterFn: (item: object) => boolean
   ) {
+    const changes: Array<ChangeMessage<any, string | number>> = []
     for (const key of keys) {
       // Only load the key once
       if (this.sentKeys.has(key)) continue
@@ -145,9 +146,12 @@ export class CollectionSubscriber<
       const value = this.collection.get(key)
       if (value !== undefined && filterFn(value)) {
         this.sentKeys.add(key)
-        this.sendChangesToPipeline([{ type: `insert`, key, value }])
+        changes.push({ type: `insert`, key, value })
       }
     }
+    if (changes.length > 0) {
+      this.sendChangesToPipeline(changes)
+    }
   }
 
   private subscribeToAllChanges(

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,