@tanstack/db 0.2.3 → 0.2.5

package/dist/esm/local-only.d.ts

@@ -1,50 +1,17 @@
-import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, UpdateMutationFnParams, UtilsRecord } from './types.js';
+import { BaseCollectionConfig, CollectionConfig, InferSchemaOutput, UtilsRecord } from './types.js';
 import { 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, 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;
+export interface LocalOnlyCollectionConfig<T extends object = object, TSchema extends StandardSchemaV1 = never, TKey extends string | number = string | number> 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>;
 }
 /**
  * Local-only collection utilities type (currently empty but matches the pattern)
@@ -58,9 +25,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)
@@ -97,6 +62,15 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {
  *   })
  * )
  */
-export declare function localOnlyCollectionOptions<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends Record<string, unknown> = Record<string, unknown>, TKey extends string | number = string | number>(config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>): CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey> & {
+export declare function localOnlyCollectionOptions<T extends StandardSchemaV1, TKey extends string | number = string | number>(config: LocalOnlyCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
+    schema: T;
+}): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+    utils: LocalOnlyCollectionUtils;
+    schema: T;
+};
+export declare function localOnlyCollectionOptions<T extends object, TKey extends string | number = string | number>(config: LocalOnlyCollectionConfig<T, never, TKey> & {
+    schema?: never;
+}): CollectionConfig<T, TKey> & {
     utils: LocalOnlyCollectionUtils;
+    schema?: never;
 };

package/dist/esm/local-only.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-only.js","sources":["../../src/local-only.ts"],"sourcesContent":["import type {\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  OperationType,\n  ResolveType,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Configuration interface for Local-only collection options\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @template TKey - The type of the key returned by getKey\n *\n * @remarks\n * Type resolution follows a priority order:\n * 1. If you provide an explicit type via generic parameter, it will be used\n * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred\n * 3. If neither explicit type nor schema is provided, the fallback type will be used\n *\n * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.\n */\nexport interface LocalOnlyCollectionConfig<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Record<string, unknown> = Record<string, unknown>,\n  TKey extends string | number = string | number,\n> {\n  /**\n   * Standard Collection configuration properties\n   */\n  id?: string\n  schema?: TSchema\n  getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => TKey\n\n  /**\n   * Optional initial data to populate the collection with on creation\n   * This data will be applied during the initial sync process\n   */\n  initialData?: Array<ResolveType<TExplicit, TSchema, TFallback>>\n\n  /**\n   * Optional asynchronous handler function called after an insert operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onInsert?: (\n    params: InsertMutationFnParams<\n      ResolveType<TExplicit, TSchema, TFallback>,\n      TKey,\n      LocalOnlyCollectionUtils\n    >\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called after an update operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onUpdate?: (\n    params: UpdateMutationFnParams<\n      ResolveType<TExplicit, TSchema, TFallback>,\n      TKey,\n      LocalOnlyCollectionUtils\n    >\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called after a delete operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onDelete?: (\n    params: DeleteMutationFnParams<\n      ResolveType<TExplicit, TSchema, TFallback>,\n      TKey,\n      LocalOnlyCollectionUtils\n    >\n  ) => Promise<any>\n}\n\n/**\n * Local-only collection utilities type (currently empty but matches the pattern)\n */\nexport interface LocalOnlyCollectionUtils extends UtilsRecord {}\n\n/**\n * Creates Local-only collection options for use with a standard Collection\n *\n * This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config\n * that immediately \"syncs\" all optimistic changes to the collection, making them permanent.\n * Perfect for local-only data that doesn't need persistence or external synchronization.\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @template TKey - The type of the key returned by getKey\n * @param config - Configuration options for the Local-only collection\n * @returns Collection options with utilities (currently empty but follows the pattern)\n *\n * @example\n * // Basic local-only collection\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Local-only collection with initial data\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *     initialData: [\n *       { id: 1, name: 'Item 1' },\n *       { id: 2, name: 'Item 2' },\n *     ],\n *   })\n * )\n *\n * @example\n * // Local-only collection with mutation handlers\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *       // Custom logic after insert\n *     },\n *   })\n * )\n */\nexport function localOnlyCollectionOptions<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Record<string, unknown> = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>\n): CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey> & {\n  utils: LocalOnlyCollectionUtils\n} {\n  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>\n\n  const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config\n\n  // Create the sync configuration with transaction confirmation capability\n  const syncResult = createLocalOnlySync<ResolvedType, TKey>(initialData)\n\n  /**\n   * Create wrapper handlers that call user handlers first, then confirm transactions\n   * Wraps the user's onInsert handler to also confirm the transaction immediately\n   */\n  const wrappedOnInsert = async (\n    params: InsertMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onInsert) {\n      handlerResult = (await onInsert(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  /**\n   * Wrapper for onUpdate handler that also confirms the transaction immediately\n   */\n  const wrappedOnUpdate = async (\n    params: UpdateMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onUpdate) {\n      handlerResult = (await onUpdate(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  /**\n   * Wrapper for onDelete handler that also confirms the transaction immediately\n   */\n  const wrappedOnDelete = async (\n    params: DeleteMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onDelete) {\n      handlerResult = (await onDelete(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  return {\n    ...restConfig,\n    sync: syncResult.sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {} as LocalOnlyCollectionUtils,\n    startSync: true,\n    gcTime: 0,\n  }\n}\n\n/**\n * Internal function to create Local-only sync configuration with transaction confirmation\n *\n * This captures the sync functions and provides synchronous confirmation of operations.\n * It creates a loopback sync that immediately confirms all optimistic operations,\n * making them permanent in the collection.\n *\n * @param initialData - Optional array of initial items to populate the collection\n * @returns Object with sync configuration and confirmOperationsSync function\n */\nfunction createLocalOnlySync<T extends object, TKey extends string | number>(\n  initialData?: Array<T>\n) {\n  // Capture sync functions for transaction confirmation\n  let syncBegin: (() => void) | null = null\n  let syncWrite: ((message: { type: OperationType; value: T }) => void) | null =\n    null\n  let syncCommit: (() => void) | null = null\n\n  const sync: SyncConfig<T, TKey> = {\n    /**\n     * Sync function that captures sync parameters and applies initial data\n     * @param params - Sync parameters containing begin, write, and commit functions\n     * @returns Unsubscribe function (empty since no ongoing sync is needed)\n     */\n    sync: (params) => {\n      const { begin, write, commit, markReady } = params\n\n      // Capture sync functions for later use by confirmOperationsSync\n      syncBegin = begin\n      syncWrite = write\n      syncCommit = commit\n\n      // Apply initial data if provided\n      if (initialData && initialData.length > 0) {\n        begin()\n        initialData.forEach((item) => {\n          write({\n            type: `insert`,\n            value: item,\n          })\n        })\n        commit()\n      }\n\n      // Mark collection as ready since local-only collections are immediately ready\n      markReady()\n\n      // Return empty unsubscribe function - no ongoing sync needed\n      return () => {}\n    },\n    /**\n     * Get sync metadata - returns empty object for local-only collections\n     * @returns Empty metadata object\n     */\n    getSyncMetadata: () => ({}),\n  }\n\n  /**\n   * Synchronously confirms optimistic operations by immediately writing through sync\n   *\n   * This loops through transaction mutations and applies them to move from optimistic to synced state.\n   * It's called after user handlers to make optimistic changes permanent.\n   *\n   * @param mutations - Array of mutation objects from the transaction\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncBegin || !syncWrite || !syncCommit) {\n      return // Sync not initialized yet, which is fine\n    }\n\n    // Immediately write back through sync interface\n    syncBegin()\n    mutations.forEach((mutation) => {\n      if (syncWrite) {\n        syncWrite({\n          type: mutation.type,\n          value: mutation.modified,\n        })\n      }\n    })\n    syncCommit()\n  }\n\n  return {\n    sync,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":"AAyIO,SAAS,2BAMd,QAGA;AAGA,QAAM,EAAE,aAAa,UAAU,UAAU,UAAU,GAAG,eAAe;AAGrE,QAAM,aAAa,oBAAwC,WAAW;AAMtE,QAAM,kBAAkB,OACtB,WACG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAKA,QAAM,kBAAkB,OACtB,WACG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAKA,QAAM,kBAAkB,OACtB,WACG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,MAAM,WAAW;AAAA,IACjB,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,OAAO,CAAA;AAAA,IACP,WAAW;AAAA,IACX,QAAQ;AAAA,EAAA;AAEZ;AAYA,SAAS,oBACP,aACA;AAEA,MAAI,YAAiC;AACrC,MAAI,YACF;AACF,MAAI,aAAkC;AAEtC,QAAM,OAA4B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMhC,MAAM,CAAC,WAAW;AAChB,YAAM,EAAE,OAAO,OAAO,QAAQ,cAAc;AAG5C,kBAAY;AACZ,kBAAY;AACZ,mBAAa;AAGb,UAAI,eAAe,YAAY,SAAS,GAAG;AACzC,cAAA;AACA,oBAAY,QAAQ,CAAC,SAAS;AAC5B,gBAAM;AAAA,YACJ,MAAM;AAAA,YACN,OAAO;AAAA,UAAA,CACR;AAAA,QACH,CAAC;AACD,eAAA;AAAA,MACF;AAGA,gBAAA;AAGA,aAAO,MAAM;AAAA,MAAC;AAAA,IAChB;AAAA;AAAA;AAAA;AAAA;AAAA,IAKA,iBAAiB,OAAO,CAAA;AAAA,EAAC;AAW3B,QAAM,wBAAwB,CAAC,cAA0B;AACvD,QAAI,CAAC,aAAa,CAAC,aAAa,CAAC,YAAY;AAC3C;AAAA,IACF;AAGA,cAAA;AACA,cAAU,QAAQ,CAAC,aAAa;AAC9B,UAAI,WAAW;AACb,kBAAU;AAAA,UACR,MAAM,SAAS;AAAA,UACf,OAAO,SAAS;AAAA,QAAA,CACjB;AAAA,MACH;AAAA,IACF,CAAC;AACD,eAAA;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"local-only.js","sources":["../../src/local-only.ts"],"sourcesContent":["import type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InferSchemaOutput,\n  InsertMutationFnParams,\n  OperationType,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Configuration interface for Local-only collection options\n * @template T - The type of items in the collection\n * @template TSchema - The schema type for validation\n * @template TKey - The type of the key returned by `getKey`\n */\nexport interface LocalOnlyCollectionConfig<\n  T extends object = object,\n  TSchema extends StandardSchemaV1 = never,\n  TKey extends string | number = string | number,\n> extends Omit<\n    BaseCollectionConfig<T, TKey, TSchema, LocalOnlyCollectionUtils>,\n    `gcTime` | `startSync`\n  > {\n  /**\n   * Optional initial data to populate the collection with on creation\n   * This data will be applied during the initial sync process\n   */\n  initialData?: Array<T>\n}\n\n/**\n * Local-only collection utilities type (currently empty but matches the pattern)\n */\nexport interface LocalOnlyCollectionUtils extends UtilsRecord {}\n\n/**\n * Creates Local-only collection options for use with a standard Collection\n *\n * This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config\n * that immediately \"syncs\" all optimistic changes to the collection, making them permanent.\n * Perfect for local-only data that doesn't need persistence or external synchronization.\n *\n * @template T - The schema type if a schema is provided, otherwise the type of items in the collection\n * @template TKey - The type of the key returned by getKey\n * @param config - Configuration options for the Local-only collection\n * @returns Collection options with utilities (currently empty but follows the pattern)\n *\n * @example\n * // Basic local-only collection\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Local-only collection with initial data\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *     initialData: [\n *       { id: 1, name: 'Item 1' },\n *       { id: 2, name: 'Item 2' },\n *     ],\n *   })\n * )\n *\n * @example\n * // Local-only collection with mutation handlers\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *       // Custom logic after insert\n *     },\n *   })\n * )\n */\n\n// Overload for when schema is provided\nexport function localOnlyCollectionOptions<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n>(\n  config: LocalOnlyCollectionConfig<InferSchemaOutput<T>, T, TKey> & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  utils: LocalOnlyCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function localOnlyCollectionOptions<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  config: LocalOnlyCollectionConfig<T, never, TKey> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  utils: LocalOnlyCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function localOnlyCollectionOptions(\n  config: LocalOnlyCollectionConfig<any, any, string | number>\n): CollectionConfig<any, string | number, any> & {\n  utils: LocalOnlyCollectionUtils\n  schema?: StandardSchemaV1\n} {\n  const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config\n\n  // Create the sync configuration with transaction confirmation capability\n  const syncResult = createLocalOnlySync(initialData)\n\n  /**\n   * Create wrapper handlers that call user handlers first, then confirm transactions\n   * Wraps the user's onInsert handler to also confirm the transaction immediately\n   */\n  const wrappedOnInsert = async (\n    params: InsertMutationFnParams<\n      any,\n      string | number,\n      LocalOnlyCollectionUtils\n    >\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onInsert) {\n      handlerResult = (await onInsert(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  /**\n   * Wrapper for onUpdate handler that also confirms the transaction immediately\n   */\n  const wrappedOnUpdate = async (\n    params: UpdateMutationFnParams<\n      any,\n      string | number,\n      LocalOnlyCollectionUtils\n    >\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onUpdate) {\n      handlerResult = (await onUpdate(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  /**\n   * Wrapper for onDelete handler that also confirms the transaction immediately\n   */\n  const wrappedOnDelete = async (\n    params: DeleteMutationFnParams<\n      any,\n      string | number,\n      LocalOnlyCollectionUtils\n    >\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onDelete) {\n      handlerResult = (await onDelete(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  return {\n    ...restConfig,\n    sync: syncResult.sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {} as LocalOnlyCollectionUtils,\n    startSync: true,\n    gcTime: 0,\n  }\n}\n\n/**\n * Internal function to create Local-only sync configuration with transaction confirmation\n *\n * This captures the sync functions and provides synchronous confirmation of operations.\n * It creates a loopback sync that immediately confirms all optimistic operations,\n * making them permanent in the collection.\n *\n * @param initialData - Optional array of initial items to populate the collection\n * @returns Object with sync configuration and confirmOperationsSync function\n */\nfunction createLocalOnlySync<T extends object, TKey extends string | number>(\n  initialData?: Array<T>\n) {\n  // Capture sync functions for transaction confirmation\n  let syncBegin: (() => void) | null = null\n  let syncWrite: ((message: { type: OperationType; value: T }) => void) | null =\n    null\n  let syncCommit: (() => void) | null = null\n\n  const sync: SyncConfig<T, TKey> = {\n    /**\n     * Sync function that captures sync parameters and applies initial data\n     * @param params - Sync parameters containing begin, write, and commit functions\n     * @returns Unsubscribe function (empty since no ongoing sync is needed)\n     */\n    sync: (params) => {\n      const { begin, write, commit, markReady } = params\n\n      // Capture sync functions for later use by confirmOperationsSync\n      syncBegin = begin\n      syncWrite = write\n      syncCommit = commit\n\n      // Apply initial data if provided\n      if (initialData && initialData.length > 0) {\n        begin()\n        initialData.forEach((item) => {\n          write({\n            type: `insert`,\n            value: item,\n          })\n        })\n        commit()\n      }\n\n      // Mark collection as ready since local-only collections are immediately ready\n      markReady()\n\n      // Return empty unsubscribe function - no ongoing sync needed\n      return () => {}\n    },\n    /**\n     * Get sync metadata - returns empty object for local-only collections\n     * @returns Empty metadata object\n     */\n    getSyncMetadata: () => ({}),\n  }\n\n  /**\n   * Synchronously confirms optimistic operations by immediately writing through sync\n   *\n   * This loops through transaction mutations and applies them to move from optimistic to synced state.\n   * It's called after user handlers to make optimistic changes permanent.\n   *\n   * @param mutations - Array of mutation objects from the transaction\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncBegin || !syncWrite || !syncCommit) {\n      return // Sync not initialized yet, which is fine\n    }\n\n    // Immediately write back through sync interface\n    syncBegin()\n    mutations.forEach((mutation) => {\n      if (syncWrite) {\n        syncWrite({\n          type: mutation.type,\n          value: mutation.modified,\n        })\n      }\n    })\n    syncCommit()\n  }\n\n  return {\n    sync,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":"AA+GO,SAAS,2BACd,QAIA;AACA,QAAM,EAAE,aAAa,UAAU,UAAU,UAAU,GAAG,eAAe;AAGrE,QAAM,aAAa,oBAAoB,WAAW;AAMlD,QAAM,kBAAkB,OACtB,WAKG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAKA,QAAM,kBAAkB,OACtB,WAKG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAKA,QAAM,kBAAkB,OACtB,WAKG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,MAAM,WAAW;AAAA,IACjB,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,OAAO,CAAA;AAAA,IACP,WAAW;AAAA,IACX,QAAQ;AAAA,EAAA;AAEZ;AAYA,SAAS,oBACP,aACA;AAEA,MAAI,YAAiC;AACrC,MAAI,YACF;AACF,MAAI,aAAkC;AAEtC,QAAM,OAA4B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMhC,MAAM,CAAC,WAAW;AAChB,YAAM,EAAE,OAAO,OAAO,QAAQ,cAAc;AAG5C,kBAAY;AACZ,kBAAY;AACZ,mBAAa;AAGb,UAAI,eAAe,YAAY,SAAS,GAAG;AACzC,cAAA;AACA,oBAAY,QAAQ,CAAC,SAAS;AAC5B,gBAAM;AAAA,YACJ,MAAM;AAAA,YACN,OAAO;AAAA,UAAA,CACR;AAAA,QACH,CAAC;AACD,eAAA;AAAA,MACF;AAGA,gBAAA;AAGA,aAAO,MAAM;AAAA,MAAC;AAAA,IAChB;AAAA;AAAA;AAAA;AAAA;AAAA,IAKA,iBAAiB,OAAO,CAAA;AAAA,EAAC;AAW3B,QAAM,wBAAwB,CAAC,cAA0B;AACvD,QAAI,CAAC,aAAa,CAAC,aAAa,CAAC,YAAY;AAC3C;AAAA,IACF;AAGA,cAAA;AACA,cAAU,QAAQ,CAAC,aAAa;AAC9B,UAAI,WAAW;AACb,kBAAU;AAAA,UACR,MAAM,SAAS;AAAA,UACf,OAAO,SAAS;AAAA,QAAA,CACjB;AAAA,MACH;AAAA,IACF,CAAC;AACD,eAAA;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,EAAA;AAEJ;"}

package/dist/esm/local-storage.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, UpdateMutationFnParams, UtilsRecord } from './types.js';
+import { BaseCollectionConfig, CollectionConfig, InferSchemaOutput, UtilsRecord } from './types.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 /**
  * Storage API interface - subset of DOM Storage that we need
@@ -13,19 +13,11 @@ export type StorageEventApi = {
 };
 /**
  * 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, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>> {
+export interface LocalStorageCollectionConfig<T extends object = object, TSchema extends StandardSchemaV1 = never, TKey extends string | number = string | number> extends BaseCollectionConfig<T, TKey, TSchema> {
     /**
      * The key to use for storing the collection data in localStorage/sessionStorage
      */
@@ -40,31 +32,6 @@ export interface LocalStorageCollectionConfig<TExplicit = unknown, TSchema exten
      * 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>;
 }
 /**
  * Type for the clear utility function
@@ -124,7 +91,17 @@ export interface LocalStorageCollectionUtils extends UtilsRecord {
  *   })
  * )
  */
-export declare function localStorageCollectionOptions<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>>(config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>): Omit<CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>, `id`> & {
+export declare function localStorageCollectionOptions<T extends StandardSchemaV1, TKey extends string | number = string | number>(config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
+    schema: T;
+}): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+    id: string;
+    utils: LocalStorageCollectionUtils;
+    schema: T;
+};
+export declare function localStorageCollectionOptions<T extends object, TKey extends string | number = string | number>(config: LocalStorageCollectionConfig<T, never, TKey> & {
+    schema?: never;
+}): CollectionConfig<T, TKey> & {
     id: string;
     utils: LocalStorageCollectionUtils;
+    schema?: never;
 };

package/dist/esm/local-storage.js

@@ -68,10 +68,7 @@ function localStorageCollectionOptions(config) {
     if (config.onInsert) {
       handlerResult = await config.onInsert(params) ?? {};
     }
-    const currentData = loadFromStorage(
-      config.storageKey,
-      storage
-    );
+    const currentData = loadFromStorage(config.storageKey, storage);
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.modified);
       const storedItem = {
@@ -92,10 +89,7 @@ function localStorageCollectionOptions(config) {
     if (config.onUpdate) {
       handlerResult = await config.onUpdate(params) ?? {};
     }
-    const currentData = loadFromStorage(
-      config.storageKey,
-      storage
-    );
+    const currentData = loadFromStorage(config.storageKey, storage);
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.modified);
       const storedItem = {
@@ -113,10 +107,7 @@ function localStorageCollectionOptions(config) {
     if (config.onDelete) {
       handlerResult = await config.onDelete(params) ?? {};
     }
-    const currentData = loadFromStorage(
-      config.storageKey,
-      storage
-    );
+    const currentData = loadFromStorage(config.storageKey, storage);
     params.transaction.mutations.forEach((mutation) => {
       const key = config.getKey(mutation.original);
       currentData.delete(key);

package/dist/esm/local-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import {\n  InvalidStorageDataFormatError,\n  InvalidStorageObjectFormatError,\n  NoStorageAvailableError,\n  NoStorageEventApiError,\n  SerializationError,\n  StorageKeyRequiredError,\n} from \"./errors\"\nimport type {\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  ResolveType,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Storage API interface - subset of DOM Storage that we need\n */\nexport type StorageApi = Pick<Storage, `getItem` | `setItem` | `removeItem`>\n\n/**\n * Storage event API - subset of Window for 'storage' events only\n */\nexport type StorageEventApi = {\n  addEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n  removeEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n}\n\n/**\n * Internal storage format that includes version tracking\n */\ninterface StoredItem<T> {\n  versionKey: string\n  data: T\n}\n\n/**\n * Configuration interface for localStorage collection options\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n *\n * @remarks\n * Type resolution follows a priority order:\n * 1. If you provide an explicit type via generic parameter, it will be used\n * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred\n * 3. If neither explicit type nor schema is provided, the fallback type will be used\n *\n * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.\n */\nexport interface LocalStorageCollectionConfig<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends object = Record<string, unknown>,\n> {\n  /**\n   * The key to use for storing the collection data in localStorage/sessionStorage\n   */\n  storageKey: string\n\n  /**\n   * Storage API to use (defaults to window.localStorage)\n   * Can be any object that implements the Storage interface (e.g., sessionStorage)\n   */\n  storage?: StorageApi\n\n  /**\n   * Storage event API to use for cross-tab synchronization (defaults to window)\n   * Can be any object that implements addEventListener/removeEventListener for storage events\n   */\n  storageEventApi?: StorageEventApi\n\n  /**\n   * Collection identifier (defaults to \"local-collection:{storageKey}\" if not provided)\n   */\n  id?: string\n  schema?: TSchema\n  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]\n  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]\n\n  /**\n   * Optional asynchronous handler function called before an insert operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onInsert?: (\n    params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called before an update operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onUpdate?: (\n    params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called before a delete operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onDelete?: (\n    params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<any>\n}\n\n/**\n * Type for the clear utility function\n */\nexport type ClearStorageFn = () => void\n\n/**\n * Type for the getStorageSize utility function\n */\nexport type GetStorageSizeFn = () => number\n\n/**\n * LocalStorage collection utilities type\n */\nexport interface LocalStorageCollectionUtils extends UtilsRecord {\n  clearStorage: ClearStorageFn\n  getStorageSize: GetStorageSizeFn\n}\n\n/**\n * Validates that a value can be JSON serialized\n * @param value - The value to validate for JSON serialization\n * @param operation - The operation type being performed (for error messages)\n * @throws Error if the value cannot be JSON serialized\n */\nfunction validateJsonSerializable(value: any, operation: string): void {\n  try {\n    JSON.stringify(value)\n  } catch (error) {\n    throw new SerializationError(\n      operation,\n      error instanceof Error ? error.message : String(error)\n    )\n  }\n}\n\n/**\n * Generate a UUID for version tracking\n * @returns A unique identifier string for tracking data versions\n */\nfunction generateUuid(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Creates localStorage collection options for use with a standard Collection\n *\n * This function creates a collection that persists data to localStorage/sessionStorage\n * and synchronizes changes across browser tabs using storage events.\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the localStorage collection\n * @returns Collection options with utilities including clearStorage and getStorageSize\n *\n * @example\n * // Basic localStorage collection\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with custom storage\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     storage: window.sessionStorage, // Use sessionStorage instead\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with mutation handlers\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *     },\n *   })\n * )\n */\nexport function localStorageCollectionOptions<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends object = Record<string, unknown>,\n>(\n  config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>\n): Omit<CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>, `id`> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n} {\n  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>\n\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new StorageKeyRequiredError()\n  }\n\n  // Default to window.localStorage if no storage is provided\n  const storage =\n    config.storage ||\n    (typeof window !== `undefined` ? window.localStorage : null)\n\n  if (!storage) {\n    throw new NoStorageAvailableError()\n  }\n\n  // Default to window for storage events if not provided\n  const storageEventApi =\n    config.storageEventApi || (typeof window !== `undefined` ? window : null)\n\n  if (!storageEventApi) {\n    throw new NoStorageEventApiError()\n  }\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<ResolvedType>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<ResolvedType>(\n    config.storageKey,\n    storage,\n    storageEventApi,\n    config.getKey,\n    lastKnownData\n  )\n\n  /**\n   * Manual trigger function for local sync updates\n   * Forces a check for storage changes and updates the collection if needed\n   */\n  const triggerLocalSync = () => {\n    if (sync.manualTrigger) {\n      sync.manualTrigger()\n    }\n  }\n\n  /**\n   * Save data to storage\n   * @param dataMap - Map of items with version tracking to save to storage\n   */\n  const saveToStorage = (\n    dataMap: Map<string | number, StoredItem<ResolvedType>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<ResolvedType>> = {}\n      dataMap.forEach((storedItem, key) => {\n        objectData[String(key)] = storedItem\n      })\n      const serialized = JSON.stringify(objectData)\n      storage.setItem(config.storageKey, serialized)\n    } catch (error) {\n      console.error(\n        `[LocalStorageCollection] Error saving data to storage key \"${config.storageKey}\":`,\n        error\n      )\n      throw error\n    }\n  }\n\n  /**\n   * Removes all collection data from the configured storage\n   */\n  const clearStorage: ClearStorageFn = (): void => {\n    storage.removeItem(config.storageKey)\n  }\n\n  /**\n   * Get the size of the stored data in bytes (approximate)\n   * @returns The approximate size in bytes of the stored collection data\n   */\n  const getStorageSize: GetStorageSizeFn = (): number => {\n    const data = storage.getItem(config.storageKey)\n    return data ? new Blob([data]).size : 0\n  }\n\n  /*\n   * Create wrapper handlers for direct persistence operations that perform actual storage operations\n   * Wraps the user's onInsert handler to also save changes to localStorage\n   */\n  const wrappedOnInsert = async (\n    params: InsertMutationFnParams<ResolvedType>\n  ) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(mutation.modified, `insert`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onInsert) {\n      handlerResult = (await config.onInsert(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<ResolvedType>(\n      config.storageKey,\n      storage\n    )\n\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      const key = config.getKey(mutation.modified)\n      const storedItem: StoredItem<ResolvedType> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      currentData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  const wrappedOnUpdate = async (\n    params: UpdateMutationFnParams<ResolvedType>\n  ) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(mutation.modified, `update`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onUpdate) {\n      handlerResult = (await config.onUpdate(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<ResolvedType>(\n      config.storageKey,\n      storage\n    )\n\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      const key = config.getKey(mutation.modified)\n      const storedItem: StoredItem<ResolvedType> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      currentData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  const wrappedOnDelete = async (\n    params: DeleteMutationFnParams<ResolvedType>\n  ) => {\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onDelete) {\n      handlerResult = (await config.onDelete(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<ResolvedType>(\n      config.storageKey,\n      storage\n    )\n\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // For delete operations, mutation.original contains the full object\n      const key = config.getKey(mutation.original as ResolvedType)\n      currentData.delete(key)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  // Extract standard Collection config properties\n  const {\n    storageKey: _storageKey,\n    storage: _storage,\n    storageEventApi: _storageEventApi,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    id,\n    ...restConfig\n  } = config\n\n  // Default id to a pattern based on storage key if not provided\n  const collectionId = id ?? `local-collection:${config.storageKey}`\n\n  return {\n    ...restConfig,\n    id: collectionId,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      clearStorage,\n      getStorageSize,\n    },\n  }\n}\n\n/**\n * Load data from storage and return as a Map\n * @param storageKey - The key used to store data in the storage API\n * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)\n * @returns Map of stored items with version tracking, or empty Map if loading fails\n */\nfunction loadFromStorage<T extends object>(\n  storageKey: string,\n  storage: StorageApi\n): Map<string | number, StoredItem<T>> {\n  try {\n    const rawData = storage.getItem(storageKey)\n    if (!rawData) {\n      return new Map()\n    }\n\n    const parsed = JSON.parse(rawData)\n    const dataMap = new Map<string | number, StoredItem<T>>()\n\n    // Handle object format where keys map to StoredItem values\n    if (\n      typeof parsed === `object` &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      Object.entries(parsed).forEach(([key, value]) => {\n        // Runtime check to ensure the value has the expected StoredItem structure\n        if (\n          value &&\n          typeof value === `object` &&\n          `versionKey` in value &&\n          `data` in value\n        ) {\n          const storedItem = value as StoredItem<T>\n          dataMap.set(key, storedItem)\n        } else {\n          throw new InvalidStorageDataFormatError(storageKey, key)\n        }\n      })\n    } else {\n      throw new InvalidStorageObjectFormatError(storageKey)\n    }\n\n    return dataMap\n  } catch (error) {\n    console.warn(\n      `[LocalStorageCollection] Error loading data from storage key \"${storageKey}\":`,\n      error\n    )\n    return new Map()\n  }\n}\n\n/**\n * Internal function to create localStorage sync configuration\n * Creates a sync configuration that handles localStorage persistence and cross-tab synchronization\n * @param storageKey - The key used for storing data in localStorage\n * @param storage - The storage API to use (localStorage, sessionStorage, etc.)\n * @param storageEventApi - The event API for listening to storage changes\n * @param getKey - Function to extract the key from an item\n * @param lastKnownData - Map tracking the last known state for change detection\n * @returns Sync configuration with manual trigger capability\n */\nfunction createLocalStorageSync<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  storageEventApi: StorageEventApi,\n  _getKey: (item: T) => string | number,\n  lastKnownData: Map<string | number, StoredItem<T>>\n): SyncConfig<T> & { manualTrigger?: () => void } {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n\n  /**\n   * Compare two Maps to find differences using version keys\n   * @param oldData - The previous state of stored items\n   * @param newData - The current state of stored items\n   * @returns Array of changes with type, key, and value information\n   */\n  const findChanges = (\n    oldData: Map<string | number, StoredItem<T>>,\n    newData: Map<string | number, StoredItem<T>>\n  ): Array<{\n    type: `insert` | `update` | `delete`\n    key: string | number\n    value?: T\n  }> => {\n    const changes: Array<{\n      type: `insert` | `update` | `delete`\n      key: string | number\n      value?: T\n    }> = []\n\n    // Check for deletions and updates\n    oldData.forEach((oldStoredItem, key) => {\n      const newStoredItem = newData.get(key)\n      if (!newStoredItem) {\n        changes.push({ type: `delete`, key, value: oldStoredItem.data })\n      } else if (oldStoredItem.versionKey !== newStoredItem.versionKey) {\n        changes.push({ type: `update`, key, value: newStoredItem.data })\n      }\n    })\n\n    // Check for insertions\n    newData.forEach((newStoredItem, key) => {\n      if (!oldData.has(key)) {\n        changes.push({ type: `insert`, key, value: newStoredItem.data })\n      }\n    })\n\n    return changes\n  }\n\n  /**\n   * Process storage changes and update collection\n   * Loads new data from storage, compares with last known state, and applies changes\n   */\n  const processStorageChanges = () => {\n    if (!syncParams) return\n\n    const { begin, write, commit } = syncParams\n\n    // Load the new data\n    const newData = loadFromStorage<T>(storageKey, storage)\n\n    // Find the specific changes\n    const changes = findChanges(lastKnownData, newData)\n\n    if (changes.length > 0) {\n      begin()\n      changes.forEach(({ type, value }) => {\n        if (value) {\n          validateJsonSerializable(value, type)\n          write({ type, value })\n        }\n      })\n      commit()\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      newData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n    }\n  }\n\n  const syncConfig: SyncConfig<T> & { manualTrigger?: () => void } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady } = params\n\n      // Store sync params for later use\n      syncParams = params\n\n      // Initial load\n      const initialData = loadFromStorage<T>(storageKey, storage)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(storedItem.data, `load`)\n          write({ type: `insert`, value: storedItem.data })\n        })\n        commit()\n      }\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      initialData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n\n      // Mark collection as ready after initial load\n      markReady()\n\n      // Listen for storage events from other tabs\n      const handleStorageEvent = (event: StorageEvent) => {\n        // Only respond to changes to our specific key and from our storage\n        if (event.key !== storageKey || event.storageArea !== storage) {\n          return\n        }\n\n        processStorageChanges()\n      }\n\n      // Add storage event listener for cross-tab sync\n      storageEventApi.addEventListener(`storage`, handleStorageEvent)\n\n      // Note: Cleanup is handled automatically by the collection when it's disposed\n    },\n\n    /**\n     * Get sync metadata - returns storage key information\n     * @returns Object containing storage key and storage type metadata\n     */\n    getSyncMetadata: () => ({\n      storageKey,\n      storageType:\n        storage === (typeof window !== `undefined` ? window.localStorage : null)\n          ? `localStorage`\n          : `custom`,\n    }),\n\n    // Manual trigger function for local updates\n    manualTrigger: processStorageChanges,\n  }\n\n  return syncConfig\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import {\n  InvalidStorageDataFormatError,\n  InvalidStorageObjectFormatError,\n  NoStorageAvailableError,\n  NoStorageEventApiError,\n  SerializationError,\n  StorageKeyRequiredError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InferSchemaOutput,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Storage API interface - subset of DOM Storage that we need\n */\nexport type StorageApi = Pick<Storage, `getItem` | `setItem` | `removeItem`>\n\n/**\n * Storage event API - subset of Window for 'storage' events only\n */\nexport type StorageEventApi = {\n  addEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n  removeEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n}\n\n/**\n * Internal storage format that includes version tracking\n */\ninterface StoredItem<T> {\n  versionKey: string\n  data: T\n}\n\n/**\n * Configuration interface for localStorage collection options\n * @template T - The type of items in the collection\n * @template TSchema - The schema type for validation\n * @template TKey - The type of the key returned by `getKey`\n */\nexport interface LocalStorageCollectionConfig<\n  T extends object = object,\n  TSchema extends StandardSchemaV1 = never,\n  TKey extends string | number = string | number,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /**\n   * The key to use for storing the collection data in localStorage/sessionStorage\n   */\n  storageKey: string\n\n  /**\n   * Storage API to use (defaults to window.localStorage)\n   * Can be any object that implements the Storage interface (e.g., sessionStorage)\n   */\n  storage?: StorageApi\n\n  /**\n   * Storage event API to use for cross-tab synchronization (defaults to window)\n   * Can be any object that implements addEventListener/removeEventListener for storage events\n   */\n  storageEventApi?: StorageEventApi\n}\n\n/**\n * Type for the clear utility function\n */\nexport type ClearStorageFn = () => void\n\n/**\n * Type for the getStorageSize utility function\n */\nexport type GetStorageSizeFn = () => number\n\n/**\n * LocalStorage collection utilities type\n */\nexport interface LocalStorageCollectionUtils extends UtilsRecord {\n  clearStorage: ClearStorageFn\n  getStorageSize: GetStorageSizeFn\n}\n\n/**\n * Validates that a value can be JSON serialized\n * @param value - The value to validate for JSON serialization\n * @param operation - The operation type being performed (for error messages)\n * @throws Error if the value cannot be JSON serialized\n */\nfunction validateJsonSerializable(value: any, operation: string): void {\n  try {\n    JSON.stringify(value)\n  } catch (error) {\n    throw new SerializationError(\n      operation,\n      error instanceof Error ? error.message : String(error)\n    )\n  }\n}\n\n/**\n * Generate a UUID for version tracking\n * @returns A unique identifier string for tracking data versions\n */\nfunction generateUuid(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Creates localStorage collection options for use with a standard Collection\n *\n * This function creates a collection that persists data to localStorage/sessionStorage\n * and synchronizes changes across browser tabs using storage events.\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the localStorage collection\n * @returns Collection options with utilities including clearStorage and getStorageSize\n *\n * @example\n * // Basic localStorage collection\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with custom storage\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     storage: window.sessionStorage, // Use sessionStorage instead\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with mutation handlers\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *     },\n *   })\n * )\n */\n\n// Overload for when schema is provided\nexport function localStorageCollectionOptions<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function localStorageCollectionOptions<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<T, never, TKey> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function localStorageCollectionOptions(\n  config: LocalStorageCollectionConfig<any, any, string | number>\n): Omit<CollectionConfig<any, string | number, any>, `id`> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: StandardSchemaV1\n} {\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new StorageKeyRequiredError()\n  }\n\n  // Default to window.localStorage if no storage is provided\n  const storage =\n    config.storage ||\n    (typeof window !== `undefined` ? window.localStorage : null)\n\n  if (!storage) {\n    throw new NoStorageAvailableError()\n  }\n\n  // Default to window for storage events if not provided\n  const storageEventApi =\n    config.storageEventApi || (typeof window !== `undefined` ? window : null)\n\n  if (!storageEventApi) {\n    throw new NoStorageEventApiError()\n  }\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<any>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<any>(\n    config.storageKey,\n    storage,\n    storageEventApi,\n    config.getKey,\n    lastKnownData\n  )\n\n  /**\n   * Manual trigger function for local sync updates\n   * Forces a check for storage changes and updates the collection if needed\n   */\n  const triggerLocalSync = () => {\n    if (sync.manualTrigger) {\n      sync.manualTrigger()\n    }\n  }\n\n  /**\n   * Save data to storage\n   * @param dataMap - Map of items with version tracking to save to storage\n   */\n  const saveToStorage = (\n    dataMap: Map<string | number, StoredItem<any>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<any>> = {}\n      dataMap.forEach((storedItem, key) => {\n        objectData[String(key)] = storedItem\n      })\n      const serialized = JSON.stringify(objectData)\n      storage.setItem(config.storageKey, serialized)\n    } catch (error) {\n      console.error(\n        `[LocalStorageCollection] Error saving data to storage key \"${config.storageKey}\":`,\n        error\n      )\n      throw error\n    }\n  }\n\n  /**\n   * Removes all collection data from the configured storage\n   */\n  const clearStorage: ClearStorageFn = (): void => {\n    storage.removeItem(config.storageKey)\n  }\n\n  /**\n   * Get the size of the stored data in bytes (approximate)\n   * @returns The approximate size in bytes of the stored collection data\n   */\n  const getStorageSize: GetStorageSizeFn = (): number => {\n    const data = storage.getItem(config.storageKey)\n    return data ? new Blob([data]).size : 0\n  }\n\n  /*\n   * Create wrapper handlers for direct persistence operations that perform actual storage operations\n   * Wraps the user's onInsert handler to also save changes to localStorage\n   */\n  const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(mutation.modified, `insert`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onInsert) {\n      handlerResult = (await config.onInsert(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<any>(config.storageKey, storage)\n\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      const key = config.getKey(mutation.modified)\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      currentData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(mutation.modified, `update`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onUpdate) {\n      handlerResult = (await config.onUpdate(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<any>(config.storageKey, storage)\n\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      const key = config.getKey(mutation.modified)\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      currentData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  const wrappedOnDelete = async (params: DeleteMutationFnParams<any>) => {\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onDelete) {\n      handlerResult = (await config.onDelete(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<any>(config.storageKey, storage)\n\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // For delete operations, mutation.original contains the full object\n      const key = config.getKey(mutation.original)\n      currentData.delete(key)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  // Extract standard Collection config properties\n  const {\n    storageKey: _storageKey,\n    storage: _storage,\n    storageEventApi: _storageEventApi,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    id,\n    ...restConfig\n  } = config\n\n  // Default id to a pattern based on storage key if not provided\n  const collectionId = id ?? `local-collection:${config.storageKey}`\n\n  return {\n    ...restConfig,\n    id: collectionId,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      clearStorage,\n      getStorageSize,\n    },\n  }\n}\n\n/**\n * Load data from storage and return as a Map\n * @param storageKey - The key used to store data in the storage API\n * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)\n * @returns Map of stored items with version tracking, or empty Map if loading fails\n */\nfunction loadFromStorage<T extends object>(\n  storageKey: string,\n  storage: StorageApi\n): Map<string | number, StoredItem<T>> {\n  try {\n    const rawData = storage.getItem(storageKey)\n    if (!rawData) {\n      return new Map()\n    }\n\n    const parsed = JSON.parse(rawData)\n    const dataMap = new Map<string | number, StoredItem<T>>()\n\n    // Handle object format where keys map to StoredItem values\n    if (\n      typeof parsed === `object` &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      Object.entries(parsed).forEach(([key, value]) => {\n        // Runtime check to ensure the value has the expected StoredItem structure\n        if (\n          value &&\n          typeof value === `object` &&\n          `versionKey` in value &&\n          `data` in value\n        ) {\n          const storedItem = value as StoredItem<T>\n          dataMap.set(key, storedItem)\n        } else {\n          throw new InvalidStorageDataFormatError(storageKey, key)\n        }\n      })\n    } else {\n      throw new InvalidStorageObjectFormatError(storageKey)\n    }\n\n    return dataMap\n  } catch (error) {\n    console.warn(\n      `[LocalStorageCollection] Error loading data from storage key \"${storageKey}\":`,\n      error\n    )\n    return new Map()\n  }\n}\n\n/**\n * Internal function to create localStorage sync configuration\n * Creates a sync configuration that handles localStorage persistence and cross-tab synchronization\n * @param storageKey - The key used for storing data in localStorage\n * @param storage - The storage API to use (localStorage, sessionStorage, etc.)\n * @param storageEventApi - The event API for listening to storage changes\n * @param getKey - Function to extract the key from an item\n * @param lastKnownData - Map tracking the last known state for change detection\n * @returns Sync configuration with manual trigger capability\n */\nfunction createLocalStorageSync<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  storageEventApi: StorageEventApi,\n  _getKey: (item: T) => string | number,\n  lastKnownData: Map<string | number, StoredItem<T>>\n): SyncConfig<T> & { manualTrigger?: () => void } {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n\n  /**\n   * Compare two Maps to find differences using version keys\n   * @param oldData - The previous state of stored items\n   * @param newData - The current state of stored items\n   * @returns Array of changes with type, key, and value information\n   */\n  const findChanges = (\n    oldData: Map<string | number, StoredItem<T>>,\n    newData: Map<string | number, StoredItem<T>>\n  ): Array<{\n    type: `insert` | `update` | `delete`\n    key: string | number\n    value?: T\n  }> => {\n    const changes: Array<{\n      type: `insert` | `update` | `delete`\n      key: string | number\n      value?: T\n    }> = []\n\n    // Check for deletions and updates\n    oldData.forEach((oldStoredItem, key) => {\n      const newStoredItem = newData.get(key)\n      if (!newStoredItem) {\n        changes.push({ type: `delete`, key, value: oldStoredItem.data })\n      } else if (oldStoredItem.versionKey !== newStoredItem.versionKey) {\n        changes.push({ type: `update`, key, value: newStoredItem.data })\n      }\n    })\n\n    // Check for insertions\n    newData.forEach((newStoredItem, key) => {\n      if (!oldData.has(key)) {\n        changes.push({ type: `insert`, key, value: newStoredItem.data })\n      }\n    })\n\n    return changes\n  }\n\n  /**\n   * Process storage changes and update collection\n   * Loads new data from storage, compares with last known state, and applies changes\n   */\n  const processStorageChanges = () => {\n    if (!syncParams) return\n\n    const { begin, write, commit } = syncParams\n\n    // Load the new data\n    const newData = loadFromStorage<T>(storageKey, storage)\n\n    // Find the specific changes\n    const changes = findChanges(lastKnownData, newData)\n\n    if (changes.length > 0) {\n      begin()\n      changes.forEach(({ type, value }) => {\n        if (value) {\n          validateJsonSerializable(value, type)\n          write({ type, value })\n        }\n      })\n      commit()\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      newData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n    }\n  }\n\n  const syncConfig: SyncConfig<T> & { manualTrigger?: () => void } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady } = params\n\n      // Store sync params for later use\n      syncParams = params\n\n      // Initial load\n      const initialData = loadFromStorage<T>(storageKey, storage)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(storedItem.data, `load`)\n          write({ type: `insert`, value: storedItem.data })\n        })\n        commit()\n      }\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      initialData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n\n      // Mark collection as ready after initial load\n      markReady()\n\n      // Listen for storage events from other tabs\n      const handleStorageEvent = (event: StorageEvent) => {\n        // Only respond to changes to our specific key and from our storage\n        if (event.key !== storageKey || event.storageArea !== storage) {\n          return\n        }\n\n        processStorageChanges()\n      }\n\n      // Add storage event listener for cross-tab sync\n      storageEventApi.addEventListener(`storage`, handleStorageEvent)\n\n      // Note: Cleanup is handled automatically by the collection when it's disposed\n    },\n\n    /**\n     * Get sync metadata - returns storage key information\n     * @returns Object containing storage key and storage type metadata\n     */\n    getSyncMetadata: () => ({\n      storageKey,\n      storageType:\n        storage === (typeof window !== `undefined` ? window.localStorage : null)\n          ? `localStorage`\n          : `custom`,\n    }),\n\n    // Manual trigger function for local updates\n    manualTrigger: processStorageChanges,\n  }\n\n  return syncConfig\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/query/builder/types.d.ts

@@ -1,7 +1,6 @@
 import { CollectionImpl } from '../../collection.js';
 import { Aggregate, BasicExpression, Func, OrderByDirection, PropRef, Value } from '../ir.js';
 import { QueryBuilder } from './index.js';
-import { ResolveType } from '../../types.js';
 /**
  * Context - The central state container for query builder operations
  *
@@ -57,16 +56,10 @@ 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;
+export type InferCollectionType<T> = T extends CollectionImpl<infer TOutput, any, any, any, any> ? TOutput : never;
 /**
  * SchemaFromSource - Converts a Source definition into a ContextSchema
  *
@@ -345,7 +338,7 @@ type NonNull<T> = T extends null ? never : T;
  * ```
  */
 export type Ref<T = any> = {
-    [K in keyof T]: IsNonExactOptional<T[K]> extends true ? IsNonExactNullable<T[K]> extends true ? NonNullable<T[K]> extends Record<string, any> ? Ref<NonNullable<T[K]>> | undefined : RefLeaf<NonNullable<T[K]>> | undefined : NonUndefined<T[K]> extends Record<string, any> ? Ref<NonUndefined<T[K]>> | undefined : RefLeaf<NonUndefined<T[K]>> | undefined : IsNonExactNullable<T[K]> extends true ? NonNull<T[K]> extends Record<string, any> ? Ref<NonNull<T[K]>> | null : RefLeaf<NonNull<T[K]>> | null : T[K] extends Record<string, any> ? Ref<T[K]> : RefLeaf<T[K]>;
+    [K in keyof T]: IsNonExactOptional<T[K]> extends true ? IsNonExactNullable<T[K]> extends true ? IsPlainObject<NonNullable<T[K]>> extends true ? Ref<NonNullable<T[K]>> | undefined : RefLeaf<NonNullable<T[K]>> | undefined : IsPlainObject<NonUndefined<T[K]>> extends true ? Ref<NonUndefined<T[K]>> | undefined : RefLeaf<NonUndefined<T[K]>> | undefined : IsNonExactNullable<T[K]> extends true ? IsPlainObject<NonNull<T[K]>> extends true ? Ref<NonNull<T[K]>> | null : RefLeaf<NonNull<T[K]>> | null : IsPlainObject<T[K]> extends true ? Ref<T[K]> : RefLeaf<T[K]>;
 } & RefLeaf<T>;
 /**
  * Ref - The user-facing ref type with clean IDE display
@@ -564,4 +557,12 @@ export type WithResult<TContext extends Context, TResult> = Prettify<Omit<TConte
 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 | 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>;
 export {};

package/dist/esm/query/compiler/joins.js

@@ -103,7 +103,7 @@ function processJoin(pipeline, joinClause, tables, mainTableId, mainTableAlias,
       }
       let deoptimized = false;
       const activePipelineWithLoading = activePipeline.pipe(
-        tap(([joinKey, _]) => {
+        tap((data) => {
           if (deoptimized) {
             return;
           }
@@ -118,8 +118,9 @@ function processJoin(pipeline, joinClause, tables, mainTableId, mainTableAlias,
             );
           }
           const { loadKeys, loadInitialState } = collectionCallbacks;
-          if (index && index.supports(`eq`)) {
-            const matchingKeys = index.lookup(`eq`, joinKey);
+          if (index && index.supports(`in`)) {
+            const joinKeys = data.getInner().map(([[joinKey]]) => joinKey);
+            const matchingKeys = index.lookup(`in`, joinKeys);
             loadKeys(matchingKeys);
           } else {
             deoptimized = true;

package/dist/esm/query/compiler/joins.js.map

@@ -1 +1 @@
-{"version":3,"file":"joins.js","sources":["../../../../src/query/compiler/joins.ts"],"sourcesContent":["import {\n  consolidate,\n  filter,\n  join as joinOperator,\n  map,\n  tap,\n} from \"@tanstack/db-ivm\"\nimport {\n  CollectionInputNotFoundError,\n  InvalidJoinCondition,\n  InvalidJoinConditionLeftTableError,\n  InvalidJoinConditionRightTableError,\n  InvalidJoinConditionSameTableError,\n  InvalidJoinConditionTableMismatchError,\n  JoinCollectionNotFoundError,\n  UnsupportedJoinSourceTypeError,\n  UnsupportedJoinTypeError,\n} from \"../../errors.js\"\nimport { findIndexForField } from \"../../utils/index-optimization.js\"\nimport { ensureIndexForField } from \"../../indexes/auto-index.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { compileQuery, followRef } from \"./index.js\"\nimport type { OrderByOptimizationInfo } from \"./order-by.js\"\nimport type {\n  BasicExpression,\n  CollectionRef,\n  JoinClause,\n  PropRef,\n  QueryIR,\n  QueryRef,\n} from \"../ir.js\"\nimport type { IStreamBuilder, JoinType } from \"@tanstack/db-ivm\"\nimport type { Collection } from \"../../collection.js\"\nimport type {\n  KeyedStream,\n  NamespacedAndKeyedStream,\n  NamespacedRow,\n} from \"../../types.js\"\nimport type { QueryCache, QueryMapping } from \"./types.js\"\nimport type { BaseIndex } from \"../../indexes/base-index.js\"\n\nexport type LoadKeysFn = (key: Set<string | number>) => void\nexport type LazyCollectionCallbacks = {\n  loadKeys: LoadKeysFn\n  loadInitialState: () => void\n}\n\n/**\n * Processes all join clauses in a query\n */\nexport function processJoins(\n  pipeline: NamespacedAndKeyedStream,\n  joinClauses: Array<JoinClause>,\n  tables: Record<string, KeyedStream>,\n  mainTableId: string,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  rawQuery: QueryIR\n): NamespacedAndKeyedStream {\n  let resultPipeline = pipeline\n\n  for (const joinClause of joinClauses) {\n    resultPipeline = processJoin(\n      resultPipeline,\n      joinClause,\n      tables,\n      mainTableId,\n      mainTableAlias,\n      allInputs,\n      cache,\n      queryMapping,\n      collections,\n      callbacks,\n      lazyCollections,\n      optimizableOrderByCollections,\n      rawQuery\n    )\n  }\n\n  return resultPipeline\n}\n\n/**\n * Processes a single join clause\n */\nfunction processJoin(\n  pipeline: NamespacedAndKeyedStream,\n  joinClause: JoinClause,\n  tables: Record<string, KeyedStream>,\n  mainTableId: string,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  rawQuery: QueryIR\n): NamespacedAndKeyedStream {\n  // Get the joined table alias and input stream\n  const {\n    alias: joinedTableAlias,\n    input: joinedInput,\n    collectionId: joinedCollectionId,\n  } = processJoinSource(\n    joinClause.from,\n    allInputs,\n    collections,\n    callbacks,\n    lazyCollections,\n    optimizableOrderByCollections,\n    cache,\n    queryMapping\n  )\n\n  // Add the joined table to the tables map\n  tables[joinedTableAlias] = joinedInput\n\n  const mainCollection = collections[mainTableId]\n  const joinedCollection = collections[joinedCollectionId]\n\n  if (!mainCollection) {\n    throw new JoinCollectionNotFoundError(mainTableId)\n  }\n\n  if (!joinedCollection) {\n    throw new JoinCollectionNotFoundError(joinedCollectionId)\n  }\n\n  const { activeCollection, lazyCollection } = getActiveAndLazyCollections(\n    joinClause.type,\n    mainCollection,\n    joinedCollection\n  )\n\n  // Analyze which table each expression refers to and swap if necessary\n  const availableTableAliases = Object.keys(tables)\n  const { mainExpr, joinedExpr } = analyzeJoinExpressions(\n    joinClause.left,\n    joinClause.right,\n    availableTableAliases,\n    joinedTableAlias\n  )\n\n  // Pre-compile the join expressions\n  const compiledMainExpr = compileExpression(mainExpr)\n  const compiledJoinedExpr = compileExpression(joinedExpr)\n\n  // Prepare the main pipeline for joining\n  let mainPipeline = pipeline.pipe(\n    map(([currentKey, namespacedRow]) => {\n      // Extract the join key from the main table expression\n      const mainKey = compiledMainExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [mainKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Prepare the joined pipeline\n  let joinedPipeline = joinedInput.pipe(\n    map(([currentKey, row]) => {\n      // Wrap the row in a namespaced structure\n      const namespacedRow: NamespacedRow = { [joinedTableAlias]: row }\n\n      // Extract the join key from the joined table expression\n      const joinedKey = compiledJoinedExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [joinedKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Apply the join operation\n  if (![`inner`, `left`, `right`, `full`].includes(joinClause.type)) {\n    throw new UnsupportedJoinTypeError(joinClause.type)\n  }\n\n  if (activeCollection) {\n    // If the lazy collection comes from a subquery that has a limit and/or an offset clause\n    // then we need to deoptimize the join because we don't know which rows are in the result set\n    // since we simply lookup matching keys in the index but the index contains all rows\n    // (not just the ones that pass the limit and offset clauses)\n    const lazyFrom =\n      activeCollection === `main` ? joinClause.from : rawQuery.from\n    const limitedSubquery =\n      lazyFrom.type === `queryRef` &&\n      (lazyFrom.query.limit || lazyFrom.query.offset)\n\n    if (!limitedSubquery) {\n      // This join can be optimized by having the active collection\n      // dynamically load keys into the lazy collection\n      // based on the value of the joinKey and by looking up\n      // matching rows in the index of the lazy collection\n\n      // Mark the lazy collection as lazy\n      // this Set is passed by the liveQueryCollection to the compiler\n      // such that the liveQueryCollection can check it after compilation\n      // to know which collections are lazy collections\n      lazyCollections.add(lazyCollection.id)\n\n      const activePipeline =\n        activeCollection === `main` ? mainPipeline : joinedPipeline\n\n      let index: BaseIndex<string | number> | undefined\n\n      const lazyCollectionJoinExpr =\n        activeCollection === `main`\n          ? (joinedExpr as PropRef)\n          : (mainExpr as PropRef)\n\n      const followRefResult = followRef(\n        rawQuery,\n        lazyCollectionJoinExpr,\n        lazyCollection\n      )!\n      const followRefCollection = followRefResult.collection\n\n      const fieldName = followRefResult.path[0]\n      if (fieldName) {\n        ensureIndexForField(\n          fieldName,\n          followRefResult.path,\n          followRefCollection\n        )\n      }\n\n      let deoptimized = false\n\n      const activePipelineWithLoading: IStreamBuilder<\n        [key: unknown, [originalKey: string, namespacedRow: NamespacedRow]]\n      > = activePipeline.pipe(\n        tap(([joinKey, _]) => {\n          if (deoptimized) {\n            return\n          }\n\n          // Find the index for the path we join on\n          // we need to find the index inside the map operator\n          // because the indexes are only available after the initial sync\n          // so we can't fetch it during compilation\n          index ??= findIndexForField(\n            followRefCollection.indexes,\n            followRefResult.path\n          )\n\n          // The `callbacks` object is passed by the liveQueryCollection to the compiler.\n          // It contains a function to lazy load keys for each lazy collection\n          // as well as a function to switch back to a regular collection\n          // (useful when there's no index for available for lazily loading the collection)\n          const collectionCallbacks = callbacks[lazyCollection.id]\n          if (!collectionCallbacks) {\n            throw new Error(\n              `Internal error: callbacks for collection are missing in join pipeline. Make sure the live query collection sets them before running the pipeline.`\n            )\n          }\n\n          const { loadKeys, loadInitialState } = collectionCallbacks\n\n          if (index && index.supports(`eq`)) {\n            // Use the index to fetch the PKs of the rows in the lazy collection\n            // that match this row from the active collection based on the value of the joinKey\n            const matchingKeys = index.lookup(`eq`, joinKey)\n            // Inform the lazy collection that those keys need to be loaded\n            loadKeys(matchingKeys)\n          } else {\n            // We can't optimize the join because there is no index for the join key\n            // on the lazy collection, so we load the initial state\n            deoptimized = true\n            loadInitialState()\n          }\n        })\n      )\n\n      if (activeCollection === `main`) {\n        mainPipeline = activePipelineWithLoading\n      } else {\n        joinedPipeline = activePipelineWithLoading\n      }\n    }\n  }\n\n  return mainPipeline.pipe(\n    joinOperator(joinedPipeline, joinClause.type as JoinType),\n    consolidate(),\n    processJoinResults(joinClause.type)\n  )\n}\n\n/**\n * Analyzes join expressions to determine which refers to which table\n * and returns them in the correct order (available table expression first, joined table expression second)\n */\nfunction analyzeJoinExpressions(\n  left: BasicExpression,\n  right: BasicExpression,\n  allAvailableTableAliases: Array<string>,\n  joinedTableAlias: string\n): { mainExpr: BasicExpression; joinedExpr: BasicExpression } {\n  // Filter out the joined table alias from the available table aliases\n  const availableTableAliases = allAvailableTableAliases.filter(\n    (alias) => alias !== joinedTableAlias\n  )\n\n  const leftTableAlias = getTableAliasFromExpression(left)\n  const rightTableAlias = getTableAliasFromExpression(right)\n\n  // If left expression refers to an available table and right refers to joined table, keep as is\n  if (\n    leftTableAlias &&\n    availableTableAliases.includes(leftTableAlias) &&\n    rightTableAlias === joinedTableAlias\n  ) {\n    return { mainExpr: left, joinedExpr: right }\n  }\n\n  // If left expression refers to joined table and right refers to an available table, swap them\n  if (\n    leftTableAlias === joinedTableAlias &&\n    rightTableAlias &&\n    availableTableAliases.includes(rightTableAlias)\n  ) {\n    return { mainExpr: right, joinedExpr: left }\n  }\n\n  // If one expression doesn't refer to any table, this is an invalid join\n  if (!leftTableAlias || !rightTableAlias) {\n    // For backward compatibility, use the first available table alias in error message\n    throw new InvalidJoinConditionTableMismatchError()\n  }\n\n  // If both expressions refer to the same alias, this is an invalid join\n  if (leftTableAlias === rightTableAlias) {\n    throw new InvalidJoinConditionSameTableError(leftTableAlias)\n  }\n\n  // Left side must refer to an available table\n  // This cannot happen with the query builder as there is no way to build a ref\n  // to an unavailable table, but just in case, but could happen with the IR\n  if (!availableTableAliases.includes(leftTableAlias)) {\n    throw new InvalidJoinConditionLeftTableError(leftTableAlias)\n  }\n\n  // Right side must refer to the joined table\n  if (rightTableAlias !== joinedTableAlias) {\n    throw new InvalidJoinConditionRightTableError(joinedTableAlias)\n  }\n\n  // This should not be reachable given the logic above, but just in case\n  throw new InvalidJoinCondition()\n}\n\n/**\n * Extracts the table alias from a join expression\n */\nfunction getTableAliasFromExpression(expr: BasicExpression): string | null {\n  switch (expr.type) {\n    case `ref`:\n      // PropRef path has the table alias as the first element\n      return expr.path[0] || null\n    case `func`: {\n      // For function expressions, we need to check if all arguments refer to the same table\n      const tableAliases = new Set<string>()\n      for (const arg of expr.args) {\n        const alias = getTableAliasFromExpression(arg)\n        if (alias) {\n          tableAliases.add(alias)\n        }\n      }\n      // If all arguments refer to the same table, return that table alias\n      return tableAliases.size === 1 ? Array.from(tableAliases)[0]! : null\n    }\n    default:\n      // Values (type='val') don't reference any table\n      return null\n  }\n}\n\n/**\n * Processes the join source (collection or sub-query)\n */\nfunction processJoinSource(\n  from: CollectionRef | QueryRef,\n  allInputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  cache: QueryCache,\n  queryMapping: QueryMapping\n): { alias: string; input: KeyedStream; collectionId: string } {\n  switch (from.type) {\n    case `collectionRef`: {\n      const input = allInputs[from.collection.id]\n      if (!input) {\n        throw new CollectionInputNotFoundError(from.collection.id)\n      }\n      return { alias: from.alias, input, collectionId: from.collection.id }\n    }\n    case `queryRef`: {\n      // Find the original query for caching purposes\n      const originalQuery = queryMapping.get(from.query) || from.query\n\n      // Recursively compile the sub-query with cache\n      const subQueryResult = compileQuery(\n        originalQuery,\n        allInputs,\n        collections,\n        callbacks,\n        lazyCollections,\n        optimizableOrderByCollections,\n        cache,\n        queryMapping\n      )\n\n      // Extract the pipeline from the compilation result\n      const subQueryInput = subQueryResult.pipeline\n\n      // Subqueries may return [key, [value, orderByIndex]] (with ORDER BY) or [key, value] (without ORDER BY)\n      // We need to extract just the value for use in parent queries\n      const extractedInput = subQueryInput.pipe(\n        map((data: any) => {\n          const [key, [value, _orderByIndex]] = data\n          return [key, value] as [unknown, any]\n        })\n      )\n\n      return {\n        alias: from.alias,\n        input: extractedInput as KeyedStream,\n        collectionId: subQueryResult.collectionId,\n      }\n    }\n    default:\n      throw new UnsupportedJoinSourceTypeError((from as any).type)\n  }\n}\n\n/**\n * Processes the results of a join operation\n */\nfunction processJoinResults(joinType: string) {\n  return function (\n    pipeline: IStreamBuilder<\n      [\n        key: string,\n        [\n          [string, NamespacedRow] | undefined,\n          [string, NamespacedRow] | undefined,\n        ],\n      ]\n    >\n  ): NamespacedAndKeyedStream {\n    return pipeline.pipe(\n      // Process the join result and handle nulls\n      filter((result) => {\n        const [_key, [main, joined]] = result\n        const mainNamespacedRow = main?.[1]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Handle different join types\n        if (joinType === `inner`) {\n          return !!(mainNamespacedRow && joinedNamespacedRow)\n        }\n\n        if (joinType === `left`) {\n          return !!mainNamespacedRow\n        }\n\n        if (joinType === `right`) {\n          return !!joinedNamespacedRow\n        }\n\n        // For full joins, always include\n        return true\n      }),\n      map((result) => {\n        const [_key, [main, joined]] = result\n        const mainKey = main?.[0]\n        const mainNamespacedRow = main?.[1]\n        const joinedKey = joined?.[0]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Merge the namespaced rows\n        const mergedNamespacedRow: NamespacedRow = {}\n\n        // Add main row data if it exists\n        if (mainNamespacedRow) {\n          Object.assign(mergedNamespacedRow, mainNamespacedRow)\n        }\n\n        // Add joined row data if it exists\n        if (joinedNamespacedRow) {\n          Object.assign(mergedNamespacedRow, joinedNamespacedRow)\n        }\n\n        // We create a composite key that combines the main and joined keys\n        const resultKey = `[${mainKey},${joinedKey}]`\n\n        return [resultKey, mergedNamespacedRow] as [string, NamespacedRow]\n      })\n    )\n  }\n}\n\n/**\n * Returns the active and lazy collections for a join clause.\n * The active collection is the one that we need to fully iterate over\n * and it can be the main table (i.e. left collection) or the joined table (i.e. right collection).\n * The lazy collection is the one that we should join-in lazily based on matches in the active collection.\n * @param joinClause - The join clause to analyze\n * @param leftCollection - The left collection\n * @param rightCollection - The right collection\n * @returns The active and lazy collections. They are undefined if we need to loop over both collections (i.e. both are active)\n */\nfunction getActiveAndLazyCollections(\n  joinType: JoinClause[`type`],\n  leftCollection: Collection,\n  rightCollection: Collection\n):\n  | { activeCollection: `main` | `joined`; lazyCollection: Collection }\n  | { activeCollection: undefined; lazyCollection: undefined } {\n  if (leftCollection.id === rightCollection.id) {\n    // We can't apply this optimization if there's only one collection\n    // because `liveQueryCollection` will detect that the collection is lazy\n    // and treat it lazily (because the collection is shared)\n    // and thus it will not load any keys because both sides of the join\n    // will be handled lazily\n    return { activeCollection: undefined, lazyCollection: undefined }\n  }\n\n  switch (joinType) {\n    case `left`:\n      return { activeCollection: `main`, lazyCollection: rightCollection }\n    case `right`:\n      return { activeCollection: `joined`, lazyCollection: leftCollection }\n    case `inner`:\n      // The smallest collection should be the active collection\n      // and the biggest collection should be lazy\n      return leftCollection.size < rightCollection.size\n        ? { activeCollection: `main`, lazyCollection: rightCollection }\n        : { activeCollection: `joined`, lazyCollection: leftCollection }\n    default:\n      return { activeCollection: undefined, lazyCollection: undefined }\n  }\n}\n"],"names":["joinOperator"],"mappings":"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"}
+{"version":3,"file":"joins.js","sources":["../../../../src/query/compiler/joins.ts"],"sourcesContent":["import {\n  consolidate,\n  filter,\n  join as joinOperator,\n  map,\n  tap,\n} from \"@tanstack/db-ivm\"\nimport {\n  CollectionInputNotFoundError,\n  InvalidJoinCondition,\n  InvalidJoinConditionLeftTableError,\n  InvalidJoinConditionRightTableError,\n  InvalidJoinConditionSameTableError,\n  InvalidJoinConditionTableMismatchError,\n  JoinCollectionNotFoundError,\n  UnsupportedJoinSourceTypeError,\n  UnsupportedJoinTypeError,\n} from \"../../errors.js\"\nimport { findIndexForField } from \"../../utils/index-optimization.js\"\nimport { ensureIndexForField } from \"../../indexes/auto-index.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { compileQuery, followRef } from \"./index.js\"\nimport type { OrderByOptimizationInfo } from \"./order-by.js\"\nimport type {\n  BasicExpression,\n  CollectionRef,\n  JoinClause,\n  PropRef,\n  QueryIR,\n  QueryRef,\n} from \"../ir.js\"\nimport type { IStreamBuilder, JoinType } from \"@tanstack/db-ivm\"\nimport type { Collection } from \"../../collection.js\"\nimport type {\n  KeyedStream,\n  NamespacedAndKeyedStream,\n  NamespacedRow,\n} from \"../../types.js\"\nimport type { QueryCache, QueryMapping } from \"./types.js\"\nimport type { BaseIndex } from \"../../indexes/base-index.js\"\n\nexport type LoadKeysFn = (key: Set<string | number>) => void\nexport type LazyCollectionCallbacks = {\n  loadKeys: LoadKeysFn\n  loadInitialState: () => void\n}\n\n/**\n * Processes all join clauses in a query\n */\nexport function processJoins(\n  pipeline: NamespacedAndKeyedStream,\n  joinClauses: Array<JoinClause>,\n  tables: Record<string, KeyedStream>,\n  mainTableId: string,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  rawQuery: QueryIR\n): NamespacedAndKeyedStream {\n  let resultPipeline = pipeline\n\n  for (const joinClause of joinClauses) {\n    resultPipeline = processJoin(\n      resultPipeline,\n      joinClause,\n      tables,\n      mainTableId,\n      mainTableAlias,\n      allInputs,\n      cache,\n      queryMapping,\n      collections,\n      callbacks,\n      lazyCollections,\n      optimizableOrderByCollections,\n      rawQuery\n    )\n  }\n\n  return resultPipeline\n}\n\n/**\n * Processes a single join clause\n */\nfunction processJoin(\n  pipeline: NamespacedAndKeyedStream,\n  joinClause: JoinClause,\n  tables: Record<string, KeyedStream>,\n  mainTableId: string,\n  mainTableAlias: string,\n  allInputs: Record<string, KeyedStream>,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  rawQuery: QueryIR\n): NamespacedAndKeyedStream {\n  // Get the joined table alias and input stream\n  const {\n    alias: joinedTableAlias,\n    input: joinedInput,\n    collectionId: joinedCollectionId,\n  } = processJoinSource(\n    joinClause.from,\n    allInputs,\n    collections,\n    callbacks,\n    lazyCollections,\n    optimizableOrderByCollections,\n    cache,\n    queryMapping\n  )\n\n  // Add the joined table to the tables map\n  tables[joinedTableAlias] = joinedInput\n\n  const mainCollection = collections[mainTableId]\n  const joinedCollection = collections[joinedCollectionId]\n\n  if (!mainCollection) {\n    throw new JoinCollectionNotFoundError(mainTableId)\n  }\n\n  if (!joinedCollection) {\n    throw new JoinCollectionNotFoundError(joinedCollectionId)\n  }\n\n  const { activeCollection, lazyCollection } = getActiveAndLazyCollections(\n    joinClause.type,\n    mainCollection,\n    joinedCollection\n  )\n\n  // Analyze which table each expression refers to and swap if necessary\n  const availableTableAliases = Object.keys(tables)\n  const { mainExpr, joinedExpr } = analyzeJoinExpressions(\n    joinClause.left,\n    joinClause.right,\n    availableTableAliases,\n    joinedTableAlias\n  )\n\n  // Pre-compile the join expressions\n  const compiledMainExpr = compileExpression(mainExpr)\n  const compiledJoinedExpr = compileExpression(joinedExpr)\n\n  // Prepare the main pipeline for joining\n  let mainPipeline = pipeline.pipe(\n    map(([currentKey, namespacedRow]) => {\n      // Extract the join key from the main table expression\n      const mainKey = compiledMainExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [mainKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Prepare the joined pipeline\n  let joinedPipeline = joinedInput.pipe(\n    map(([currentKey, row]) => {\n      // Wrap the row in a namespaced structure\n      const namespacedRow: NamespacedRow = { [joinedTableAlias]: row }\n\n      // Extract the join key from the joined table expression\n      const joinedKey = compiledJoinedExpr(namespacedRow)\n\n      // Return [joinKey, [originalKey, namespacedRow]]\n      return [joinedKey, [currentKey, namespacedRow]] as [\n        unknown,\n        [string, typeof namespacedRow],\n      ]\n    })\n  )\n\n  // Apply the join operation\n  if (![`inner`, `left`, `right`, `full`].includes(joinClause.type)) {\n    throw new UnsupportedJoinTypeError(joinClause.type)\n  }\n\n  if (activeCollection) {\n    // If the lazy collection comes from a subquery that has a limit and/or an offset clause\n    // then we need to deoptimize the join because we don't know which rows are in the result set\n    // since we simply lookup matching keys in the index but the index contains all rows\n    // (not just the ones that pass the limit and offset clauses)\n    const lazyFrom =\n      activeCollection === `main` ? joinClause.from : rawQuery.from\n    const limitedSubquery =\n      lazyFrom.type === `queryRef` &&\n      (lazyFrom.query.limit || lazyFrom.query.offset)\n\n    if (!limitedSubquery) {\n      // This join can be optimized by having the active collection\n      // dynamically load keys into the lazy collection\n      // based on the value of the joinKey and by looking up\n      // matching rows in the index of the lazy collection\n\n      // Mark the lazy collection as lazy\n      // this Set is passed by the liveQueryCollection to the compiler\n      // such that the liveQueryCollection can check it after compilation\n      // to know which collections are lazy collections\n      lazyCollections.add(lazyCollection.id)\n\n      const activePipeline =\n        activeCollection === `main` ? mainPipeline : joinedPipeline\n\n      let index: BaseIndex<string | number> | undefined\n\n      const lazyCollectionJoinExpr =\n        activeCollection === `main`\n          ? (joinedExpr as PropRef)\n          : (mainExpr as PropRef)\n\n      const followRefResult = followRef(\n        rawQuery,\n        lazyCollectionJoinExpr,\n        lazyCollection\n      )!\n      const followRefCollection = followRefResult.collection\n\n      const fieldName = followRefResult.path[0]\n      if (fieldName) {\n        ensureIndexForField(\n          fieldName,\n          followRefResult.path,\n          followRefCollection\n        )\n      }\n\n      let deoptimized = false\n\n      const activePipelineWithLoading: IStreamBuilder<\n        [key: unknown, [originalKey: string, namespacedRow: NamespacedRow]]\n      > = activePipeline.pipe(\n        tap((data) => {\n          if (deoptimized) {\n            return\n          }\n\n          // Find the index for the path we join on\n          // we need to find the index inside the map operator\n          // because the indexes are only available after the initial sync\n          // so we can't fetch it during compilation\n          index ??= findIndexForField(\n            followRefCollection.indexes,\n            followRefResult.path\n          )\n\n          // The `callbacks` object is passed by the liveQueryCollection to the compiler.\n          // It contains a function to lazy load keys for each lazy collection\n          // as well as a function to switch back to a regular collection\n          // (useful when there's no index for available for lazily loading the collection)\n          const collectionCallbacks = callbacks[lazyCollection.id]\n          if (!collectionCallbacks) {\n            throw new Error(\n              `Internal error: callbacks for collection are missing in join pipeline. Make sure the live query collection sets them before running the pipeline.`\n            )\n          }\n\n          const { loadKeys, loadInitialState } = collectionCallbacks\n\n          if (index && index.supports(`in`)) {\n            // Use the index to fetch the PKs of the rows in the lazy collection\n            // that match this row from the active collection based on the value of the joinKey\n            const joinKeys = data.getInner().map(([[joinKey]]) => joinKey)\n            const matchingKeys = index.lookup(`in`, joinKeys)\n            // Inform the lazy collection that those keys need to be loaded\n            loadKeys(matchingKeys)\n          } else {\n            // We can't optimize the join because there is no index for the join key\n            // on the lazy collection, so we load the initial state\n            deoptimized = true\n            loadInitialState()\n          }\n        })\n      )\n\n      if (activeCollection === `main`) {\n        mainPipeline = activePipelineWithLoading\n      } else {\n        joinedPipeline = activePipelineWithLoading\n      }\n    }\n  }\n\n  return mainPipeline.pipe(\n    joinOperator(joinedPipeline, joinClause.type as JoinType),\n    consolidate(),\n    processJoinResults(joinClause.type)\n  )\n}\n\n/**\n * Analyzes join expressions to determine which refers to which table\n * and returns them in the correct order (available table expression first, joined table expression second)\n */\nfunction analyzeJoinExpressions(\n  left: BasicExpression,\n  right: BasicExpression,\n  allAvailableTableAliases: Array<string>,\n  joinedTableAlias: string\n): { mainExpr: BasicExpression; joinedExpr: BasicExpression } {\n  // Filter out the joined table alias from the available table aliases\n  const availableTableAliases = allAvailableTableAliases.filter(\n    (alias) => alias !== joinedTableAlias\n  )\n\n  const leftTableAlias = getTableAliasFromExpression(left)\n  const rightTableAlias = getTableAliasFromExpression(right)\n\n  // If left expression refers to an available table and right refers to joined table, keep as is\n  if (\n    leftTableAlias &&\n    availableTableAliases.includes(leftTableAlias) &&\n    rightTableAlias === joinedTableAlias\n  ) {\n    return { mainExpr: left, joinedExpr: right }\n  }\n\n  // If left expression refers to joined table and right refers to an available table, swap them\n  if (\n    leftTableAlias === joinedTableAlias &&\n    rightTableAlias &&\n    availableTableAliases.includes(rightTableAlias)\n  ) {\n    return { mainExpr: right, joinedExpr: left }\n  }\n\n  // If one expression doesn't refer to any table, this is an invalid join\n  if (!leftTableAlias || !rightTableAlias) {\n    // For backward compatibility, use the first available table alias in error message\n    throw new InvalidJoinConditionTableMismatchError()\n  }\n\n  // If both expressions refer to the same alias, this is an invalid join\n  if (leftTableAlias === rightTableAlias) {\n    throw new InvalidJoinConditionSameTableError(leftTableAlias)\n  }\n\n  // Left side must refer to an available table\n  // This cannot happen with the query builder as there is no way to build a ref\n  // to an unavailable table, but just in case, but could happen with the IR\n  if (!availableTableAliases.includes(leftTableAlias)) {\n    throw new InvalidJoinConditionLeftTableError(leftTableAlias)\n  }\n\n  // Right side must refer to the joined table\n  if (rightTableAlias !== joinedTableAlias) {\n    throw new InvalidJoinConditionRightTableError(joinedTableAlias)\n  }\n\n  // This should not be reachable given the logic above, but just in case\n  throw new InvalidJoinCondition()\n}\n\n/**\n * Extracts the table alias from a join expression\n */\nfunction getTableAliasFromExpression(expr: BasicExpression): string | null {\n  switch (expr.type) {\n    case `ref`:\n      // PropRef path has the table alias as the first element\n      return expr.path[0] || null\n    case `func`: {\n      // For function expressions, we need to check if all arguments refer to the same table\n      const tableAliases = new Set<string>()\n      for (const arg of expr.args) {\n        const alias = getTableAliasFromExpression(arg)\n        if (alias) {\n          tableAliases.add(alias)\n        }\n      }\n      // If all arguments refer to the same table, return that table alias\n      return tableAliases.size === 1 ? Array.from(tableAliases)[0]! : null\n    }\n    default:\n      // Values (type='val') don't reference any table\n      return null\n  }\n}\n\n/**\n * Processes the join source (collection or sub-query)\n */\nfunction processJoinSource(\n  from: CollectionRef | QueryRef,\n  allInputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazyCollections: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  cache: QueryCache,\n  queryMapping: QueryMapping\n): { alias: string; input: KeyedStream; collectionId: string } {\n  switch (from.type) {\n    case `collectionRef`: {\n      const input = allInputs[from.collection.id]\n      if (!input) {\n        throw new CollectionInputNotFoundError(from.collection.id)\n      }\n      return { alias: from.alias, input, collectionId: from.collection.id }\n    }\n    case `queryRef`: {\n      // Find the original query for caching purposes\n      const originalQuery = queryMapping.get(from.query) || from.query\n\n      // Recursively compile the sub-query with cache\n      const subQueryResult = compileQuery(\n        originalQuery,\n        allInputs,\n        collections,\n        callbacks,\n        lazyCollections,\n        optimizableOrderByCollections,\n        cache,\n        queryMapping\n      )\n\n      // Extract the pipeline from the compilation result\n      const subQueryInput = subQueryResult.pipeline\n\n      // Subqueries may return [key, [value, orderByIndex]] (with ORDER BY) or [key, value] (without ORDER BY)\n      // We need to extract just the value for use in parent queries\n      const extractedInput = subQueryInput.pipe(\n        map((data: any) => {\n          const [key, [value, _orderByIndex]] = data\n          return [key, value] as [unknown, any]\n        })\n      )\n\n      return {\n        alias: from.alias,\n        input: extractedInput as KeyedStream,\n        collectionId: subQueryResult.collectionId,\n      }\n    }\n    default:\n      throw new UnsupportedJoinSourceTypeError((from as any).type)\n  }\n}\n\n/**\n * Processes the results of a join operation\n */\nfunction processJoinResults(joinType: string) {\n  return function (\n    pipeline: IStreamBuilder<\n      [\n        key: string,\n        [\n          [string, NamespacedRow] | undefined,\n          [string, NamespacedRow] | undefined,\n        ],\n      ]\n    >\n  ): NamespacedAndKeyedStream {\n    return pipeline.pipe(\n      // Process the join result and handle nulls\n      filter((result) => {\n        const [_key, [main, joined]] = result\n        const mainNamespacedRow = main?.[1]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Handle different join types\n        if (joinType === `inner`) {\n          return !!(mainNamespacedRow && joinedNamespacedRow)\n        }\n\n        if (joinType === `left`) {\n          return !!mainNamespacedRow\n        }\n\n        if (joinType === `right`) {\n          return !!joinedNamespacedRow\n        }\n\n        // For full joins, always include\n        return true\n      }),\n      map((result) => {\n        const [_key, [main, joined]] = result\n        const mainKey = main?.[0]\n        const mainNamespacedRow = main?.[1]\n        const joinedKey = joined?.[0]\n        const joinedNamespacedRow = joined?.[1]\n\n        // Merge the namespaced rows\n        const mergedNamespacedRow: NamespacedRow = {}\n\n        // Add main row data if it exists\n        if (mainNamespacedRow) {\n          Object.assign(mergedNamespacedRow, mainNamespacedRow)\n        }\n\n        // Add joined row data if it exists\n        if (joinedNamespacedRow) {\n          Object.assign(mergedNamespacedRow, joinedNamespacedRow)\n        }\n\n        // We create a composite key that combines the main and joined keys\n        const resultKey = `[${mainKey},${joinedKey}]`\n\n        return [resultKey, mergedNamespacedRow] as [string, NamespacedRow]\n      })\n    )\n  }\n}\n\n/**\n * Returns the active and lazy collections for a join clause.\n * The active collection is the one that we need to fully iterate over\n * and it can be the main table (i.e. left collection) or the joined table (i.e. right collection).\n * The lazy collection is the one that we should join-in lazily based on matches in the active collection.\n * @param joinClause - The join clause to analyze\n * @param leftCollection - The left collection\n * @param rightCollection - The right collection\n * @returns The active and lazy collections. They are undefined if we need to loop over both collections (i.e. both are active)\n */\nfunction getActiveAndLazyCollections(\n  joinType: JoinClause[`type`],\n  leftCollection: Collection,\n  rightCollection: Collection\n):\n  | { activeCollection: `main` | `joined`; lazyCollection: Collection }\n  | { activeCollection: undefined; lazyCollection: undefined } {\n  if (leftCollection.id === rightCollection.id) {\n    // We can't apply this optimization if there's only one collection\n    // because `liveQueryCollection` will detect that the collection is lazy\n    // and treat it lazily (because the collection is shared)\n    // and thus it will not load any keys because both sides of the join\n    // will be handled lazily\n    return { activeCollection: undefined, lazyCollection: undefined }\n  }\n\n  switch (joinType) {\n    case `left`:\n      return { activeCollection: `main`, lazyCollection: rightCollection }\n    case `right`:\n      return { activeCollection: `joined`, lazyCollection: leftCollection }\n    case `inner`:\n      // The smallest collection should be the active collection\n      // and the biggest collection should be lazy\n      return leftCollection.size < rightCollection.size\n        ? { activeCollection: `main`, lazyCollection: rightCollection }\n        : { activeCollection: `joined`, lazyCollection: leftCollection }\n    default:\n      return { activeCollection: undefined, lazyCollection: undefined }\n  }\n}\n"],"names":["joinOperator"],"mappings":"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"}

package/dist/esm/query/live/collection-subscriber.js

@@ -81,14 +81,18 @@ class CollectionSubscriber {
     );
   }
   loadKeys(keys, filterFn) {
+    const changes = [];
     for (const key of keys) {
       if (this.sentKeys.has(key)) continue;
       const value = this.collection.get(key);
       if (value !== void 0 && 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);
+    }
   }
   subscribeToAllChanges(whereExpression) {
     const sendChangesToPipeline = this.sendChangesToPipeline.bind(this);