@tanstack/db 0.1.0 → 0.1.3

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

@@ -1 +1 @@
-{"version":3,"file":"local-only.js","sources":["../../src/local-only.ts"],"sourcesContent":["import type {\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>(config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>) {\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":"AAwIO,SAAS,2BAKd,QAAwE;AAGxE,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  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;"}

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

@@ -1,4 +1,4 @@
-import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, SyncConfig, UpdateMutationFnParams, UtilsRecord } from './types.js';
+import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, UpdateMutationFnParams, UtilsRecord } from './types.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 /**
  * Storage API interface - subset of DOM Storage that we need
@@ -124,18 +124,7 @@ 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>): {
+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`> & {
     id: string;
-    sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number> & {
-        manualTrigger?: () => void;
-    };
-    onInsert: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
-    onUpdate: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
-    onDelete: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
-    utils: {
-        clearStorage: ClearStorageFn;
-        getStorageSize: GetStorageSizeFn;
-    };
-    schema?: TSchema | undefined;
-    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => string | number;
+    utils: LocalStorageCollectionUtils;
 };

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>(config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>) {\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  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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"}

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

@@ -1,5 +1,5 @@
 import { OrderByDirection, QueryIR } from '../ir.js';
-import { Context, GroupByCallback, JoinOnCallback, MergeContext, MergeContextWithJoinType, OrderByCallback, RefProxyForContext, ResultTypeFromSelect, SchemaFromSource, SelectObject, Source, WhereCallback, WithResult } from './types.js';
+import { Context, GroupByCallback, JoinOnCallback, MergeContext, MergeContextWithJoinType, OrderByCallback, OrderByOptions, RefProxyForContext, ResultTypeFromSelect, SchemaFromSource, SelectObject, Source, WhereCallback, WithResult } from './types.js';
 export declare class BaseQueryBuilder<TContext extends Context = Context> {
     private readonly query;
     constructor(query?: Partial<QueryIR>);
@@ -243,7 +243,7 @@ export declare class BaseQueryBuilder<TContext extends Context = Context> {
      *   .orderBy(({users}) => users.firstName)
      * ```
      */
-    orderBy(callback: OrderByCallback<TContext>, direction?: OrderByDirection): QueryBuilder<TContext>;
+    orderBy(callback: OrderByCallback<TContext>, options?: OrderByDirection | OrderByOptions): QueryBuilder<TContext>;
     /**
      * Group rows by one or more columns for aggregation
      *

package/dist/esm/query/builder/index.js

@@ -343,13 +343,20 @@ class BaseQueryBuilder {
    *   .orderBy(({users}) => users.firstName)
    * ```
    */
-  orderBy(callback, direction = `asc`) {
+  orderBy(callback, options = `asc`) {
     const aliases = this._getCurrentAliases();
     const refProxy = createRefProxy(aliases);
     const result = callback(refProxy);
+    const opts = typeof options === `string` ? { direction: options, nulls: `first`, stringSort: `locale` } : {
+      direction: options.direction ?? `asc`,
+      nulls: options.nulls ?? `first`,
+      stringSort: options.stringSort ?? `locale`,
+      locale: options.stringSort === `locale` ? options.locale : void 0,
+      localeOptions: options.stringSort === `locale` ? options.localeOptions : void 0
+    };
     const orderByClause = {
       expression: toExpression(result),
-      direction
+      compareOptions: opts
     };
     const existingOrderBy = this.query.orderBy || [];
     return new BaseQueryBuilder({

package/dist/esm/query/builder/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/query/builder/index.ts"],"sourcesContent":["import { CollectionImpl } from \"../../collection.js\"\nimport { CollectionRef, QueryRef } from \"../ir.js\"\nimport {\n  InvalidSourceError,\n  JoinConditionMustBeEqualityError,\n  OnlyOneSourceAllowedError,\n  QueryMustHaveFromClauseError,\n  SubQueryMustHaveFromClauseError,\n} from \"../../errors.js\"\nimport { createRefProxy, isRefProxy, toExpression } from \"./ref-proxy.js\"\nimport type { NamespacedRow } from \"../../types.js\"\nimport type {\n  Aggregate,\n  BasicExpression,\n  JoinClause,\n  OrderBy,\n  OrderByClause,\n  OrderByDirection,\n  QueryIR,\n} from \"../ir.js\"\nimport type {\n  Context,\n  GroupByCallback,\n  JoinOnCallback,\n  MergeContext,\n  MergeContextWithJoinType,\n  OrderByCallback,\n  RefProxyForContext,\n  ResultTypeFromSelect,\n  SchemaFromSource,\n  SelectObject,\n  Source,\n  WhereCallback,\n  WithResult,\n} from \"./types.js\"\n\nexport class BaseQueryBuilder<TContext extends Context = Context> {\n  private readonly query: Partial<QueryIR> = {}\n\n  constructor(query: Partial<QueryIR> = {}) {\n    this.query = { ...query }\n  }\n\n  /**\n   * Creates a CollectionRef or QueryRef from a source object\n   * @param source - An object with a single key-value pair\n   * @param context - Context string for error messages (e.g., \"from clause\", \"join clause\")\n   * @returns A tuple of [alias, ref] where alias is the source key and ref is the created reference\n   */\n  private _createRefForSource<TSource extends Source>(\n    source: TSource,\n    context: string\n  ): [string, CollectionRef | QueryRef] {\n    if (Object.keys(source).length !== 1) {\n      throw new OnlyOneSourceAllowedError(context)\n    }\n\n    const alias = Object.keys(source)[0]!\n    const sourceValue = source[alias]\n\n    let ref: CollectionRef | QueryRef\n\n    if (sourceValue instanceof CollectionImpl) {\n      ref = new CollectionRef(sourceValue, alias)\n    } else if (sourceValue instanceof BaseQueryBuilder) {\n      const subQuery = sourceValue._getQuery()\n      if (!(subQuery as Partial<QueryIR>).from) {\n        throw new SubQueryMustHaveFromClauseError(context)\n      }\n      ref = new QueryRef(subQuery, alias)\n    } else {\n      throw new InvalidSourceError()\n    }\n\n    return [alias, ref]\n  }\n\n  /**\n   * Specify the source table or subquery for the query\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @returns A QueryBuilder with the specified source\n   *\n   * @example\n   * ```ts\n   * // Query from a collection\n   * query.from({ users: usersCollection })\n   *\n   * // Query from a subquery\n   * const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)\n   * query.from({ activeUsers })\n   * ```\n   */\n  from<TSource extends Source>(\n    source: TSource\n  ): QueryBuilder<{\n    baseSchema: SchemaFromSource<TSource>\n    schema: SchemaFromSource<TSource>\n    fromSourceName: keyof TSource & string\n    hasJoins: false\n  }> {\n    const [, from] = this._createRefForSource(source, `from clause`)\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      from,\n    }) as any\n  }\n\n  /**\n   * Join another table or subquery to the current query\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @param type - The type of join: 'inner', 'left', 'right', or 'full' (defaults to 'left')\n   * @returns A QueryBuilder with the joined table available\n   *\n   * @example\n   * ```ts\n   * // Left join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   *\n   * // Inner join with explicit type\n   * query\n   *   .from({ u: usersCollection })\n   *   .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId), 'inner')\n   * ```\n   *\n   * // Join with a subquery\n   * const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)\n   * query\n   *   .from({ activeUsers })\n   *   .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId))\n   */\n  join<\n    TSource extends Source,\n    TJoinType extends `inner` | `left` | `right` | `full` = `left`,\n  >(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >,\n    type: TJoinType = `left` as TJoinType\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, TJoinType>\n  > {\n    const [alias, from] = this._createRefForSource(source, `join clause`)\n\n    // Create a temporary context for the callback\n    const currentAliases = this._getCurrentAliases()\n    const newAliases = [...currentAliases, alias]\n    const refProxy = createRefProxy(newAliases) as RefProxyForContext<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n\n    // Get the join condition expression\n    const onExpression = onCallback(refProxy)\n\n    // Extract left and right from the expression\n    // For now, we'll assume it's an eq function with two arguments\n    let left: BasicExpression\n    let right: BasicExpression\n\n    if (\n      onExpression.type === `func` &&\n      onExpression.name === `eq` &&\n      onExpression.args.length === 2\n    ) {\n      left = onExpression.args[0]!\n      right = onExpression.args[1]!\n    } else {\n      throw new JoinConditionMustBeEqualityError()\n    }\n\n    const joinClause: JoinClause = {\n      from,\n      type,\n      left,\n      right,\n    }\n\n    const existingJoins = this.query.join || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      join: [...existingJoins, joinClause],\n    }) as any\n  }\n\n  /**\n   * Perform a LEFT JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the left joined table available\n   *\n   * @example\n   * ```ts\n   * // Left join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .leftJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  leftJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `left`>\n  > {\n    return this.join(source, onCallback, `left`)\n  }\n\n  /**\n   * Perform a RIGHT JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the right joined table available\n   *\n   * @example\n   * ```ts\n   * // Right join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .rightJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  rightJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `right`>\n  > {\n    return this.join(source, onCallback, `right`)\n  }\n\n  /**\n   * Perform an INNER JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the inner joined table available\n   *\n   * @example\n   * ```ts\n   * // Inner join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .innerJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  innerJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `inner`>\n  > {\n    return this.join(source, onCallback, `inner`)\n  }\n\n  /**\n   * Perform a FULL JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the full joined table available\n   *\n   * @example\n   * ```ts\n   * // Full join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .fullJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  fullJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `full`>\n  > {\n    return this.join(source, onCallback, `full`)\n  }\n\n  /**\n   * Filter rows based on a condition\n   *\n   * @param callback - A function that receives table references and returns an expression\n   * @returns A QueryBuilder with the where condition applied\n   *\n   * @example\n   * ```ts\n   * // Simple condition\n   * query\n   *   .from({ users: usersCollection })\n   *   .where(({users}) => gt(users.age, 18))\n   *\n   * // Multiple conditions\n   * query\n   *   .from({ users: usersCollection })\n   *   .where(({users}) => and(\n   *     gt(users.age, 18),\n   *     eq(users.active, true)\n   *   ))\n   *\n   * // Multiple where calls are ANDed together\n   * query\n   *   .from({ users: usersCollection })\n   *   .where(({users}) => gt(users.age, 18))\n   *   .where(({users}) => eq(users.active, true))\n   * ```\n   */\n  where(callback: WhereCallback<TContext>): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const expression = callback(refProxy)\n\n    const existingWhere = this.query.where || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      where: [...existingWhere, expression],\n    }) as any\n  }\n\n  /**\n   * Filter grouped rows based on aggregate conditions\n   *\n   * @param callback - A function that receives table references and returns an expression\n   * @returns A QueryBuilder with the having condition applied\n   *\n   * @example\n   * ```ts\n   * // Filter groups by count\n   * query\n   *   .from({ posts: postsCollection })\n   *   .groupBy(({posts}) => posts.userId)\n   *   .having(({posts}) => gt(count(posts.id), 5))\n   *\n   * // Filter by average\n   * query\n   *   .from({ orders: ordersCollection })\n   *   .groupBy(({orders}) => orders.customerId)\n   *   .having(({orders}) => gt(avg(orders.total), 100))\n   *\n   * // Multiple having calls are ANDed together\n   * query\n   *   .from({ orders: ordersCollection })\n   *   .groupBy(({orders}) => orders.customerId)\n   *   .having(({orders}) => gt(count(orders.id), 5))\n   *   .having(({orders}) => gt(avg(orders.total), 100))\n   * ```\n   */\n  having(callback: WhereCallback<TContext>): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const expression = callback(refProxy)\n\n    const existingHaving = this.query.having || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      having: [...existingHaving, expression],\n    }) as any\n  }\n\n  /**\n   * Select specific columns or computed values from the query\n   *\n   * @param callback - A function that receives table references and returns an object with selected fields or expressions\n   * @returns A QueryBuilder that returns only the selected fields\n   *\n   * @example\n   * ```ts\n   * // Select specific columns\n   * query\n   *   .from({ users: usersCollection })\n   *   .select(({users}) => ({\n   *     name: users.name,\n   *     email: users.email\n   *   }))\n   *\n   * // Select with computed values\n   * query\n   *   .from({ users: usersCollection })\n   *   .select(({users}) => ({\n   *     fullName: concat(users.firstName, ' ', users.lastName),\n   *     ageInMonths: mul(users.age, 12)\n   *   }))\n   *\n   * // Select with aggregates (requires GROUP BY)\n   * query\n   *   .from({ posts: postsCollection })\n   *   .groupBy(({posts}) => posts.userId)\n   *   .select(({posts, count}) => ({\n   *     userId: posts.userId,\n   *     postCount: count(posts.id)\n   *   }))\n   * ```\n   */\n  select<TSelectObject extends SelectObject>(\n    callback: (refs: RefProxyForContext<TContext>) => TSelectObject\n  ): QueryBuilder<WithResult<TContext, ResultTypeFromSelect<TSelectObject>>> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const selectObject = callback(refProxy)\n\n    // Check if any tables were spread during the callback\n    const spreadSentinels = (refProxy as any).__spreadSentinels as Set<string>\n\n    // Convert the select object to use expressions, including spread sentinels\n    const select: Record<string, BasicExpression | Aggregate> = {}\n\n    // First, add spread sentinels for any tables that were spread\n    for (const spreadAlias of spreadSentinels) {\n      const sentinelKey = `__SPREAD_SENTINEL__${spreadAlias}`\n      select[sentinelKey] = toExpression(spreadAlias) // Use alias as a simple reference\n    }\n\n    // Then add the explicit select fields\n    for (const [key, value] of Object.entries(selectObject)) {\n      if (isRefProxy(value)) {\n        select[key] = toExpression(value)\n      } else if (\n        typeof value === `object` &&\n        `type` in value &&\n        (value.type === `agg` || value.type === `func`)\n      ) {\n        select[key] = value as BasicExpression | Aggregate\n      } else {\n        select[key] = toExpression(value)\n      }\n    }\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      select,\n      fnSelect: undefined, // remove the fnSelect clause if it exists\n    }) as any\n  }\n\n  /**\n   * Sort the query results by one or more columns\n   *\n   * @param callback - A function that receives table references and returns the field to sort by\n   * @param direction - Sort direction: 'asc' for ascending, 'desc' for descending (defaults to 'asc')\n   * @returns A QueryBuilder with the ordering applied\n   *\n   * @example\n   * ```ts\n   * // Sort by a single column\n   * query\n   *   .from({ users: usersCollection })\n   *   .orderBy(({users}) => users.name)\n   *\n   * // Sort descending\n   * query\n   *   .from({ users: usersCollection })\n   *   .orderBy(({users}) => users.createdAt, 'desc')\n   *\n   * // Multiple sorts (chain orderBy calls)\n   * query\n   *   .from({ users: usersCollection })\n   *   .orderBy(({users}) => users.lastName)\n   *   .orderBy(({users}) => users.firstName)\n   * ```\n   */\n  orderBy(\n    callback: OrderByCallback<TContext>,\n    direction: OrderByDirection = `asc`\n  ): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const result = callback(refProxy)\n\n    // Create the new OrderBy structure with expression and direction\n    const orderByClause: OrderByClause = {\n      expression: toExpression(result),\n      direction,\n    }\n\n    const existingOrderBy: OrderBy = this.query.orderBy || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      orderBy: [...existingOrderBy, orderByClause],\n    }) as any\n  }\n\n  /**\n   * Group rows by one or more columns for aggregation\n   *\n   * @param callback - A function that receives table references and returns the field(s) to group by\n   * @returns A QueryBuilder with grouping applied (enables aggregate functions in SELECT and HAVING)\n   *\n   * @example\n   * ```ts\n   * // Group by a single column\n   * query\n   *   .from({ posts: postsCollection })\n   *   .groupBy(({posts}) => posts.userId)\n   *   .select(({posts, count}) => ({\n   *     userId: posts.userId,\n   *     postCount: count()\n   *   }))\n   *\n   * // Group by multiple columns\n   * query\n   *   .from({ sales: salesCollection })\n   *   .groupBy(({sales}) => [sales.region, sales.category])\n   *   .select(({sales, sum}) => ({\n   *     region: sales.region,\n   *     category: sales.category,\n   *     totalSales: sum(sales.amount)\n   *   }))\n   * ```\n   */\n  groupBy(callback: GroupByCallback<TContext>): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const result = callback(refProxy)\n\n    const newExpressions = Array.isArray(result)\n      ? result.map((r) => toExpression(r))\n      : [toExpression(result)]\n\n    // Replace existing groupBy expressions instead of extending them\n    return new BaseQueryBuilder({\n      ...this.query,\n      groupBy: newExpressions,\n    }) as any\n  }\n\n  /**\n   * Limit the number of rows returned by the query\n   * `orderBy` is required for `limit`\n   *\n   * @param count - Maximum number of rows to return\n   * @returns A QueryBuilder with the limit applied\n   *\n   * @example\n   * ```ts\n   * // Get top 5 posts by likes\n   * query\n   *   .from({ posts: postsCollection })\n   *   .orderBy(({posts}) => posts.likes, 'desc')\n   *   .limit(5)\n   * ```\n   */\n  limit(count: number): QueryBuilder<TContext> {\n    return new BaseQueryBuilder({\n      ...this.query,\n      limit: count,\n    }) as any\n  }\n\n  /**\n   * Skip a number of rows before returning results\n   * `orderBy` is required for `offset`\n   *\n   * @param count - Number of rows to skip\n   * @returns A QueryBuilder with the offset applied\n   *\n   * @example\n   * ```ts\n   * // Get second page of results\n   * query\n   *   .from({ posts: postsCollection })\n   *   .orderBy(({posts}) => posts.createdAt, 'desc')\n   *   .offset(page * pageSize)\n   *   .limit(pageSize)\n   * ```\n   */\n  offset(count: number): QueryBuilder<TContext> {\n    return new BaseQueryBuilder({\n      ...this.query,\n      offset: count,\n    }) as any\n  }\n\n  /**\n   * Specify that the query should return distinct rows.\n   * Deduplicates rows based on the selected columns.\n   * @returns A QueryBuilder with distinct enabled\n   *\n   * @example\n   * ```ts\n   * // Get countries our users are from\n   * query\n   *   .from({ users: usersCollection })\n   *   .select(({users}) => users.country)\n   *   .distinct()\n   * ```\n   */\n  distinct(): QueryBuilder<TContext> {\n    return new BaseQueryBuilder({\n      ...this.query,\n      distinct: true,\n    }) as any\n  }\n\n  // Helper methods\n  private _getCurrentAliases(): Array<string> {\n    const aliases: Array<string> = []\n\n    // Add the from alias\n    if (this.query.from) {\n      aliases.push(this.query.from.alias)\n    }\n\n    // Add join aliases\n    if (this.query.join) {\n      for (const join of this.query.join) {\n        aliases.push(join.from.alias)\n      }\n    }\n\n    return aliases\n  }\n\n  /**\n   * Functional variants of the query builder\n   * These are imperative function that are called for ery row.\n   * Warning: that these cannot be optimized by the query compiler, and may prevent\n   * some type of optimizations being possible.\n   * @example\n   * ```ts\n   * q.fn.select((row) => ({\n   *   name: row.user.name.toUpperCase(),\n   *   age: row.user.age + 1,\n   * }))\n   * ```\n   */\n  get fn() {\n    const builder = this\n    return {\n      /**\n       * Select fields using a function that operates on each row\n       * Warning: This cannot be optimized by the query compiler\n       *\n       * @param callback - A function that receives a row and returns the selected value\n       * @returns A QueryBuilder with functional selection applied\n       *\n       * @example\n       * ```ts\n       * // Functional select (not optimized)\n       * query\n       *   .from({ users: usersCollection })\n       *   .fn.select(row => ({\n       *     name: row.users.name.toUpperCase(),\n       *     age: row.users.age + 1,\n       *   }))\n       * ```\n       */\n      select<TFuncSelectResult>(\n        callback: (row: TContext[`schema`]) => TFuncSelectResult\n      ): QueryBuilder<WithResult<TContext, TFuncSelectResult>> {\n        return new BaseQueryBuilder({\n          ...builder.query,\n          select: undefined, // remove the select clause if it exists\n          fnSelect: callback,\n        })\n      },\n      /**\n       * Filter rows using a function that operates on each row\n       * Warning: This cannot be optimized by the query compiler\n       *\n       * @param callback - A function that receives a row and returns a boolean\n       * @returns A QueryBuilder with functional filtering applied\n       *\n       * @example\n       * ```ts\n       * // Functional where (not optimized)\n       * query\n       *   .from({ users: usersCollection })\n       *   .fn.where(row => row.users.name.startsWith('A'))\n       * ```\n       */\n      where(\n        callback: (row: TContext[`schema`]) => any\n      ): QueryBuilder<TContext> {\n        return new BaseQueryBuilder({\n          ...builder.query,\n          fnWhere: [\n            ...(builder.query.fnWhere || []),\n            callback as (row: NamespacedRow) => any,\n          ],\n        })\n      },\n      /**\n       * Filter grouped rows using a function that operates on each aggregated row\n       * Warning: This cannot be optimized by the query compiler\n       *\n       * @param callback - A function that receives an aggregated row and returns a boolean\n       * @returns A QueryBuilder with functional having filter applied\n       *\n       * @example\n       * ```ts\n       * // Functional having (not optimized)\n       * query\n       *   .from({ posts: postsCollection })\n       *   .groupBy(({posts}) => posts.userId)\n       *   .fn.having(row => row.count > 5)\n       * ```\n       */\n      having(\n        callback: (row: TContext[`schema`]) => any\n      ): QueryBuilder<TContext> {\n        return new BaseQueryBuilder({\n          ...builder.query,\n          fnHaving: [\n            ...(builder.query.fnHaving || []),\n            callback as (row: NamespacedRow) => any,\n          ],\n        })\n      },\n    }\n  }\n\n  _getQuery(): QueryIR {\n    if (!this.query.from) {\n      throw new QueryMustHaveFromClauseError()\n    }\n    return this.query as QueryIR\n  }\n}\n\n// Internal function to build a query from a callback\n// used by liveQueryCollectionOptions.query\nexport function buildQuery<TContext extends Context>(\n  fn: (builder: InitialQueryBuilder) => QueryBuilder<TContext>\n): QueryIR {\n  const result = fn(new BaseQueryBuilder())\n  return getQueryIR(result)\n}\n\n// Internal function to get the QueryIR from a builder\nexport function getQueryIR(\n  builder: BaseQueryBuilder | QueryBuilder<any> | InitialQueryBuilder\n): QueryIR {\n  return (builder as unknown as BaseQueryBuilder)._getQuery()\n}\n\n// Type-only exports for the query builder\nexport type InitialQueryBuilder = Pick<BaseQueryBuilder<Context>, `from`>\n\nexport type InitialQueryBuilderConstructor = new () => InitialQueryBuilder\n\nexport type QueryBuilder<TContext extends Context> = Omit<\n  BaseQueryBuilder<TContext>,\n  `from` | `_getQuery`\n>\n\n// Main query builder class alias with the constructor type modified to hide all\n// but the from method on the initial instance\nexport const Query: InitialQueryBuilderConstructor = BaseQueryBuilder\n\n// Helper type to extract context from a QueryBuilder\nexport type ExtractContext<T> =\n  T extends BaseQueryBuilder<infer TContext>\n    ? TContext\n    : T extends QueryBuilder<infer TContext>\n      ? TContext\n      : never\n\n// Export the types from types.ts for convenience\nexport type { Context, Source, GetResult } from \"./types.js\"\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../../src/query/builder/index.ts"],"sourcesContent":["import { CollectionImpl } from \"../../collection.js\"\nimport { CollectionRef, QueryRef } from \"../ir.js\"\nimport {\n  InvalidSourceError,\n  JoinConditionMustBeEqualityError,\n  OnlyOneSourceAllowedError,\n  QueryMustHaveFromClauseError,\n  SubQueryMustHaveFromClauseError,\n} from \"../../errors.js\"\nimport { createRefProxy, isRefProxy, toExpression } from \"./ref-proxy.js\"\nimport type { NamespacedRow } from \"../../types.js\"\nimport type {\n  Aggregate,\n  BasicExpression,\n  JoinClause,\n  OrderBy,\n  OrderByClause,\n  OrderByDirection,\n  QueryIR,\n} from \"../ir.js\"\nimport type {\n  CompareOptions,\n  Context,\n  GroupByCallback,\n  JoinOnCallback,\n  MergeContext,\n  MergeContextWithJoinType,\n  OrderByCallback,\n  OrderByOptions,\n  RefProxyForContext,\n  ResultTypeFromSelect,\n  SchemaFromSource,\n  SelectObject,\n  Source,\n  WhereCallback,\n  WithResult,\n} from \"./types.js\"\n\nexport class BaseQueryBuilder<TContext extends Context = Context> {\n  private readonly query: Partial<QueryIR> = {}\n\n  constructor(query: Partial<QueryIR> = {}) {\n    this.query = { ...query }\n  }\n\n  /**\n   * Creates a CollectionRef or QueryRef from a source object\n   * @param source - An object with a single key-value pair\n   * @param context - Context string for error messages (e.g., \"from clause\", \"join clause\")\n   * @returns A tuple of [alias, ref] where alias is the source key and ref is the created reference\n   */\n  private _createRefForSource<TSource extends Source>(\n    source: TSource,\n    context: string\n  ): [string, CollectionRef | QueryRef] {\n    if (Object.keys(source).length !== 1) {\n      throw new OnlyOneSourceAllowedError(context)\n    }\n\n    const alias = Object.keys(source)[0]!\n    const sourceValue = source[alias]\n\n    let ref: CollectionRef | QueryRef\n\n    if (sourceValue instanceof CollectionImpl) {\n      ref = new CollectionRef(sourceValue, alias)\n    } else if (sourceValue instanceof BaseQueryBuilder) {\n      const subQuery = sourceValue._getQuery()\n      if (!(subQuery as Partial<QueryIR>).from) {\n        throw new SubQueryMustHaveFromClauseError(context)\n      }\n      ref = new QueryRef(subQuery, alias)\n    } else {\n      throw new InvalidSourceError()\n    }\n\n    return [alias, ref]\n  }\n\n  /**\n   * Specify the source table or subquery for the query\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @returns A QueryBuilder with the specified source\n   *\n   * @example\n   * ```ts\n   * // Query from a collection\n   * query.from({ users: usersCollection })\n   *\n   * // Query from a subquery\n   * const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)\n   * query.from({ activeUsers })\n   * ```\n   */\n  from<TSource extends Source>(\n    source: TSource\n  ): QueryBuilder<{\n    baseSchema: SchemaFromSource<TSource>\n    schema: SchemaFromSource<TSource>\n    fromSourceName: keyof TSource & string\n    hasJoins: false\n  }> {\n    const [, from] = this._createRefForSource(source, `from clause`)\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      from,\n    }) as any\n  }\n\n  /**\n   * Join another table or subquery to the current query\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @param type - The type of join: 'inner', 'left', 'right', or 'full' (defaults to 'left')\n   * @returns A QueryBuilder with the joined table available\n   *\n   * @example\n   * ```ts\n   * // Left join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   *\n   * // Inner join with explicit type\n   * query\n   *   .from({ u: usersCollection })\n   *   .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId), 'inner')\n   * ```\n   *\n   * // Join with a subquery\n   * const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)\n   * query\n   *   .from({ activeUsers })\n   *   .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId))\n   */\n  join<\n    TSource extends Source,\n    TJoinType extends `inner` | `left` | `right` | `full` = `left`,\n  >(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >,\n    type: TJoinType = `left` as TJoinType\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, TJoinType>\n  > {\n    const [alias, from] = this._createRefForSource(source, `join clause`)\n\n    // Create a temporary context for the callback\n    const currentAliases = this._getCurrentAliases()\n    const newAliases = [...currentAliases, alias]\n    const refProxy = createRefProxy(newAliases) as RefProxyForContext<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n\n    // Get the join condition expression\n    const onExpression = onCallback(refProxy)\n\n    // Extract left and right from the expression\n    // For now, we'll assume it's an eq function with two arguments\n    let left: BasicExpression\n    let right: BasicExpression\n\n    if (\n      onExpression.type === `func` &&\n      onExpression.name === `eq` &&\n      onExpression.args.length === 2\n    ) {\n      left = onExpression.args[0]!\n      right = onExpression.args[1]!\n    } else {\n      throw new JoinConditionMustBeEqualityError()\n    }\n\n    const joinClause: JoinClause = {\n      from,\n      type,\n      left,\n      right,\n    }\n\n    const existingJoins = this.query.join || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      join: [...existingJoins, joinClause],\n    }) as any\n  }\n\n  /**\n   * Perform a LEFT JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the left joined table available\n   *\n   * @example\n   * ```ts\n   * // Left join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .leftJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  leftJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `left`>\n  > {\n    return this.join(source, onCallback, `left`)\n  }\n\n  /**\n   * Perform a RIGHT JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the right joined table available\n   *\n   * @example\n   * ```ts\n   * // Right join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .rightJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  rightJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `right`>\n  > {\n    return this.join(source, onCallback, `right`)\n  }\n\n  /**\n   * Perform an INNER JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the inner joined table available\n   *\n   * @example\n   * ```ts\n   * // Inner join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .innerJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  innerJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `inner`>\n  > {\n    return this.join(source, onCallback, `inner`)\n  }\n\n  /**\n   * Perform a FULL JOIN with another table or subquery\n   *\n   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery\n   * @param onCallback - A function that receives table references and returns the join condition\n   * @returns A QueryBuilder with the full joined table available\n   *\n   * @example\n   * ```ts\n   * // Full join users with posts\n   * query\n   *   .from({ users: usersCollection })\n   *   .fullJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))\n   * ```\n   */\n  fullJoin<TSource extends Source>(\n    source: TSource,\n    onCallback: JoinOnCallback<\n      MergeContext<TContext, SchemaFromSource<TSource>>\n    >\n  ): QueryBuilder<\n    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `full`>\n  > {\n    return this.join(source, onCallback, `full`)\n  }\n\n  /**\n   * Filter rows based on a condition\n   *\n   * @param callback - A function that receives table references and returns an expression\n   * @returns A QueryBuilder with the where condition applied\n   *\n   * @example\n   * ```ts\n   * // Simple condition\n   * query\n   *   .from({ users: usersCollection })\n   *   .where(({users}) => gt(users.age, 18))\n   *\n   * // Multiple conditions\n   * query\n   *   .from({ users: usersCollection })\n   *   .where(({users}) => and(\n   *     gt(users.age, 18),\n   *     eq(users.active, true)\n   *   ))\n   *\n   * // Multiple where calls are ANDed together\n   * query\n   *   .from({ users: usersCollection })\n   *   .where(({users}) => gt(users.age, 18))\n   *   .where(({users}) => eq(users.active, true))\n   * ```\n   */\n  where(callback: WhereCallback<TContext>): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const expression = callback(refProxy)\n\n    const existingWhere = this.query.where || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      where: [...existingWhere, expression],\n    }) as any\n  }\n\n  /**\n   * Filter grouped rows based on aggregate conditions\n   *\n   * @param callback - A function that receives table references and returns an expression\n   * @returns A QueryBuilder with the having condition applied\n   *\n   * @example\n   * ```ts\n   * // Filter groups by count\n   * query\n   *   .from({ posts: postsCollection })\n   *   .groupBy(({posts}) => posts.userId)\n   *   .having(({posts}) => gt(count(posts.id), 5))\n   *\n   * // Filter by average\n   * query\n   *   .from({ orders: ordersCollection })\n   *   .groupBy(({orders}) => orders.customerId)\n   *   .having(({orders}) => gt(avg(orders.total), 100))\n   *\n   * // Multiple having calls are ANDed together\n   * query\n   *   .from({ orders: ordersCollection })\n   *   .groupBy(({orders}) => orders.customerId)\n   *   .having(({orders}) => gt(count(orders.id), 5))\n   *   .having(({orders}) => gt(avg(orders.total), 100))\n   * ```\n   */\n  having(callback: WhereCallback<TContext>): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const expression = callback(refProxy)\n\n    const existingHaving = this.query.having || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      having: [...existingHaving, expression],\n    }) as any\n  }\n\n  /**\n   * Select specific columns or computed values from the query\n   *\n   * @param callback - A function that receives table references and returns an object with selected fields or expressions\n   * @returns A QueryBuilder that returns only the selected fields\n   *\n   * @example\n   * ```ts\n   * // Select specific columns\n   * query\n   *   .from({ users: usersCollection })\n   *   .select(({users}) => ({\n   *     name: users.name,\n   *     email: users.email\n   *   }))\n   *\n   * // Select with computed values\n   * query\n   *   .from({ users: usersCollection })\n   *   .select(({users}) => ({\n   *     fullName: concat(users.firstName, ' ', users.lastName),\n   *     ageInMonths: mul(users.age, 12)\n   *   }))\n   *\n   * // Select with aggregates (requires GROUP BY)\n   * query\n   *   .from({ posts: postsCollection })\n   *   .groupBy(({posts}) => posts.userId)\n   *   .select(({posts, count}) => ({\n   *     userId: posts.userId,\n   *     postCount: count(posts.id)\n   *   }))\n   * ```\n   */\n  select<TSelectObject extends SelectObject>(\n    callback: (refs: RefProxyForContext<TContext>) => TSelectObject\n  ): QueryBuilder<WithResult<TContext, ResultTypeFromSelect<TSelectObject>>> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const selectObject = callback(refProxy)\n\n    // Check if any tables were spread during the callback\n    const spreadSentinels = (refProxy as any).__spreadSentinels as Set<string>\n\n    // Convert the select object to use expressions, including spread sentinels\n    const select: Record<string, BasicExpression | Aggregate> = {}\n\n    // First, add spread sentinels for any tables that were spread\n    for (const spreadAlias of spreadSentinels) {\n      const sentinelKey = `__SPREAD_SENTINEL__${spreadAlias}`\n      select[sentinelKey] = toExpression(spreadAlias) // Use alias as a simple reference\n    }\n\n    // Then add the explicit select fields\n    for (const [key, value] of Object.entries(selectObject)) {\n      if (isRefProxy(value)) {\n        select[key] = toExpression(value)\n      } else if (\n        typeof value === `object` &&\n        `type` in value &&\n        (value.type === `agg` || value.type === `func`)\n      ) {\n        select[key] = value as BasicExpression | Aggregate\n      } else {\n        select[key] = toExpression(value)\n      }\n    }\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      select,\n      fnSelect: undefined, // remove the fnSelect clause if it exists\n    }) as any\n  }\n\n  /**\n   * Sort the query results by one or more columns\n   *\n   * @param callback - A function that receives table references and returns the field to sort by\n   * @param direction - Sort direction: 'asc' for ascending, 'desc' for descending (defaults to 'asc')\n   * @returns A QueryBuilder with the ordering applied\n   *\n   * @example\n   * ```ts\n   * // Sort by a single column\n   * query\n   *   .from({ users: usersCollection })\n   *   .orderBy(({users}) => users.name)\n   *\n   * // Sort descending\n   * query\n   *   .from({ users: usersCollection })\n   *   .orderBy(({users}) => users.createdAt, 'desc')\n   *\n   * // Multiple sorts (chain orderBy calls)\n   * query\n   *   .from({ users: usersCollection })\n   *   .orderBy(({users}) => users.lastName)\n   *   .orderBy(({users}) => users.firstName)\n   * ```\n   */\n  orderBy(\n    callback: OrderByCallback<TContext>,\n    options: OrderByDirection | OrderByOptions = `asc`\n  ): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const result = callback(refProxy)\n\n    const opts: CompareOptions =\n      typeof options === `string`\n        ? { direction: options, nulls: `first`, stringSort: `locale` }\n        : {\n            direction: options.direction ?? `asc`,\n            nulls: options.nulls ?? `first`,\n            stringSort: options.stringSort ?? `locale`,\n            locale:\n              options.stringSort === `locale` ? options.locale : undefined,\n            localeOptions:\n              options.stringSort === `locale`\n                ? options.localeOptions\n                : undefined,\n          }\n\n    // Create the new OrderBy structure with expression and direction\n    const orderByClause: OrderByClause = {\n      expression: toExpression(result),\n      compareOptions: opts,\n    }\n\n    const existingOrderBy: OrderBy = this.query.orderBy || []\n\n    return new BaseQueryBuilder({\n      ...this.query,\n      orderBy: [...existingOrderBy, orderByClause],\n    }) as any\n  }\n\n  /**\n   * Group rows by one or more columns for aggregation\n   *\n   * @param callback - A function that receives table references and returns the field(s) to group by\n   * @returns A QueryBuilder with grouping applied (enables aggregate functions in SELECT and HAVING)\n   *\n   * @example\n   * ```ts\n   * // Group by a single column\n   * query\n   *   .from({ posts: postsCollection })\n   *   .groupBy(({posts}) => posts.userId)\n   *   .select(({posts, count}) => ({\n   *     userId: posts.userId,\n   *     postCount: count()\n   *   }))\n   *\n   * // Group by multiple columns\n   * query\n   *   .from({ sales: salesCollection })\n   *   .groupBy(({sales}) => [sales.region, sales.category])\n   *   .select(({sales, sum}) => ({\n   *     region: sales.region,\n   *     category: sales.category,\n   *     totalSales: sum(sales.amount)\n   *   }))\n   * ```\n   */\n  groupBy(callback: GroupByCallback<TContext>): QueryBuilder<TContext> {\n    const aliases = this._getCurrentAliases()\n    const refProxy = createRefProxy(aliases) as RefProxyForContext<TContext>\n    const result = callback(refProxy)\n\n    const newExpressions = Array.isArray(result)\n      ? result.map((r) => toExpression(r))\n      : [toExpression(result)]\n\n    // Replace existing groupBy expressions instead of extending them\n    return new BaseQueryBuilder({\n      ...this.query,\n      groupBy: newExpressions,\n    }) as any\n  }\n\n  /**\n   * Limit the number of rows returned by the query\n   * `orderBy` is required for `limit`\n   *\n   * @param count - Maximum number of rows to return\n   * @returns A QueryBuilder with the limit applied\n   *\n   * @example\n   * ```ts\n   * // Get top 5 posts by likes\n   * query\n   *   .from({ posts: postsCollection })\n   *   .orderBy(({posts}) => posts.likes, 'desc')\n   *   .limit(5)\n   * ```\n   */\n  limit(count: number): QueryBuilder<TContext> {\n    return new BaseQueryBuilder({\n      ...this.query,\n      limit: count,\n    }) as any\n  }\n\n  /**\n   * Skip a number of rows before returning results\n   * `orderBy` is required for `offset`\n   *\n   * @param count - Number of rows to skip\n   * @returns A QueryBuilder with the offset applied\n   *\n   * @example\n   * ```ts\n   * // Get second page of results\n   * query\n   *   .from({ posts: postsCollection })\n   *   .orderBy(({posts}) => posts.createdAt, 'desc')\n   *   .offset(page * pageSize)\n   *   .limit(pageSize)\n   * ```\n   */\n  offset(count: number): QueryBuilder<TContext> {\n    return new BaseQueryBuilder({\n      ...this.query,\n      offset: count,\n    }) as any\n  }\n\n  /**\n   * Specify that the query should return distinct rows.\n   * Deduplicates rows based on the selected columns.\n   * @returns A QueryBuilder with distinct enabled\n   *\n   * @example\n   * ```ts\n   * // Get countries our users are from\n   * query\n   *   .from({ users: usersCollection })\n   *   .select(({users}) => users.country)\n   *   .distinct()\n   * ```\n   */\n  distinct(): QueryBuilder<TContext> {\n    return new BaseQueryBuilder({\n      ...this.query,\n      distinct: true,\n    }) as any\n  }\n\n  // Helper methods\n  private _getCurrentAliases(): Array<string> {\n    const aliases: Array<string> = []\n\n    // Add the from alias\n    if (this.query.from) {\n      aliases.push(this.query.from.alias)\n    }\n\n    // Add join aliases\n    if (this.query.join) {\n      for (const join of this.query.join) {\n        aliases.push(join.from.alias)\n      }\n    }\n\n    return aliases\n  }\n\n  /**\n   * Functional variants of the query builder\n   * These are imperative function that are called for ery row.\n   * Warning: that these cannot be optimized by the query compiler, and may prevent\n   * some type of optimizations being possible.\n   * @example\n   * ```ts\n   * q.fn.select((row) => ({\n   *   name: row.user.name.toUpperCase(),\n   *   age: row.user.age + 1,\n   * }))\n   * ```\n   */\n  get fn() {\n    const builder = this\n    return {\n      /**\n       * Select fields using a function that operates on each row\n       * Warning: This cannot be optimized by the query compiler\n       *\n       * @param callback - A function that receives a row and returns the selected value\n       * @returns A QueryBuilder with functional selection applied\n       *\n       * @example\n       * ```ts\n       * // Functional select (not optimized)\n       * query\n       *   .from({ users: usersCollection })\n       *   .fn.select(row => ({\n       *     name: row.users.name.toUpperCase(),\n       *     age: row.users.age + 1,\n       *   }))\n       * ```\n       */\n      select<TFuncSelectResult>(\n        callback: (row: TContext[`schema`]) => TFuncSelectResult\n      ): QueryBuilder<WithResult<TContext, TFuncSelectResult>> {\n        return new BaseQueryBuilder({\n          ...builder.query,\n          select: undefined, // remove the select clause if it exists\n          fnSelect: callback,\n        })\n      },\n      /**\n       * Filter rows using a function that operates on each row\n       * Warning: This cannot be optimized by the query compiler\n       *\n       * @param callback - A function that receives a row and returns a boolean\n       * @returns A QueryBuilder with functional filtering applied\n       *\n       * @example\n       * ```ts\n       * // Functional where (not optimized)\n       * query\n       *   .from({ users: usersCollection })\n       *   .fn.where(row => row.users.name.startsWith('A'))\n       * ```\n       */\n      where(\n        callback: (row: TContext[`schema`]) => any\n      ): QueryBuilder<TContext> {\n        return new BaseQueryBuilder({\n          ...builder.query,\n          fnWhere: [\n            ...(builder.query.fnWhere || []),\n            callback as (row: NamespacedRow) => any,\n          ],\n        })\n      },\n      /**\n       * Filter grouped rows using a function that operates on each aggregated row\n       * Warning: This cannot be optimized by the query compiler\n       *\n       * @param callback - A function that receives an aggregated row and returns a boolean\n       * @returns A QueryBuilder with functional having filter applied\n       *\n       * @example\n       * ```ts\n       * // Functional having (not optimized)\n       * query\n       *   .from({ posts: postsCollection })\n       *   .groupBy(({posts}) => posts.userId)\n       *   .fn.having(row => row.count > 5)\n       * ```\n       */\n      having(\n        callback: (row: TContext[`schema`]) => any\n      ): QueryBuilder<TContext> {\n        return new BaseQueryBuilder({\n          ...builder.query,\n          fnHaving: [\n            ...(builder.query.fnHaving || []),\n            callback as (row: NamespacedRow) => any,\n          ],\n        })\n      },\n    }\n  }\n\n  _getQuery(): QueryIR {\n    if (!this.query.from) {\n      throw new QueryMustHaveFromClauseError()\n    }\n    return this.query as QueryIR\n  }\n}\n\n// Internal function to build a query from a callback\n// used by liveQueryCollectionOptions.query\nexport function buildQuery<TContext extends Context>(\n  fn: (builder: InitialQueryBuilder) => QueryBuilder<TContext>\n): QueryIR {\n  const result = fn(new BaseQueryBuilder())\n  return getQueryIR(result)\n}\n\n// Internal function to get the QueryIR from a builder\nexport function getQueryIR(\n  builder: BaseQueryBuilder | QueryBuilder<any> | InitialQueryBuilder\n): QueryIR {\n  return (builder as unknown as BaseQueryBuilder)._getQuery()\n}\n\n// Type-only exports for the query builder\nexport type InitialQueryBuilder = Pick<BaseQueryBuilder<Context>, `from`>\n\nexport type InitialQueryBuilderConstructor = new () => InitialQueryBuilder\n\nexport type QueryBuilder<TContext extends Context> = Omit<\n  BaseQueryBuilder<TContext>,\n  `from` | `_getQuery`\n>\n\n// Main query builder class alias with the constructor type modified to hide all\n// but the from method on the initial instance\nexport const Query: InitialQueryBuilderConstructor = BaseQueryBuilder\n\n// Helper type to extract context from a QueryBuilder\nexport type ExtractContext<T> =\n  T extends BaseQueryBuilder<infer TContext>\n    ? TContext\n    : T extends QueryBuilder<infer TContext>\n      ? TContext\n      : never\n\n// Export the types from types.ts for convenience\nexport type { Context, Source, GetResult } from \"./types.js\"\n"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 import { CollectionImpl } from '../../collection.js';
-import { Aggregate, BasicExpression } from '../ir.js';
+import { Aggregate, BasicExpression, OrderByDirection } from '../ir.js';
 import { QueryBuilder } from './index.js';
+import { ResolveType } from '../../types.js';
 export interface Context {
     baseSchema: ContextSchema;
     schema: ContextSchema;
@@ -13,17 +14,37 @@ export type ContextSchema = Record<string, unknown>;
 export type Source = {
     [alias: string]: CollectionImpl<any, any> | QueryBuilder<Context>;
 };
-export type InferCollectionType<T> = T extends CollectionImpl<infer U> ? U : never;
+export type InferCollectionType<T> = T extends CollectionImpl<infer U, any, any, infer TSchema, any> ? ResolveType<U, TSchema, U> : never;
 export type SchemaFromSource<T extends Source> = Prettify<{
-    [K in keyof T]: T[K] extends CollectionImpl<infer U> ? U : T[K] extends QueryBuilder<infer TContext> ? GetResult<TContext> : never;
+    [K in keyof T]: T[K] extends CollectionImpl<any, any, any, any, any> ? InferCollectionType<T[K]> : T[K] extends QueryBuilder<infer TContext> ? GetResult<TContext> : never;
 }>;
 export type GetAliases<TContext extends Context> = keyof TContext[`schema`];
 export type WhereCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
 export type SelectObject<T extends Record<string, BasicExpression | Aggregate | RefProxy | RefProxyFor<any>> = Record<string, BasicExpression | Aggregate | RefProxy | RefProxyFor<any>>> = T;
 export type ResultTypeFromSelect<TSelectObject> = {
-    [K in keyof TSelectObject]: TSelectObject[K] extends RefProxy<infer T> ? T : TSelectObject[K] extends BasicExpression<infer T> ? T : TSelectObject[K] extends Aggregate<infer T> ? T : TSelectObject[K] extends RefProxyFor<infer T> ? T : never;
+    [K in keyof TSelectObject]: TSelectObject[K] extends RefProxy<infer T> ? T : TSelectObject[K] extends BasicExpression<infer T> ? T : TSelectObject[K] extends Aggregate<infer T> ? T : TSelectObject[K] extends RefProxyFor<infer T> ? T : TSelectObject[K] extends undefined ? undefined : TSelectObject[K] extends {
+        __type: infer U;
+    } ? U : never;
 };
 export type OrderByCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
+export type OrderByOptions = {
+    direction?: OrderByDirection;
+    nulls?: `first` | `last`;
+} & StringSortOpts;
+export type StringSortOpts = {
+    stringSort?: `lexical`;
+} | {
+    stringSort?: `locale`;
+    locale?: string;
+    localeOptions?: object;
+};
+export type CompareOptions = {
+    direction: OrderByDirection;
+    nulls: `first` | `last`;
+    stringSort: `lexical` | `locale`;
+    locale?: string;
+    localeOptions?: object;
+};
 export type GroupByCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
 export type JoinOnCallback<TContext extends Context> = (refs: RefProxyForContext<TContext>) => any;
 export type RefProxyForContext<TContext extends Context> = {
@@ -33,9 +54,9 @@ type IsExactlyUndefined<T> = [T] extends [undefined] ? true : false;
 type IsOptional<T> = undefined extends T ? true : false;
 type NonUndefined<T> = T extends undefined ? never : T;
 export type RefProxyFor<T> = OmitRefProxy<IsExactlyUndefined<T> extends true ? RefProxy<T> : IsOptional<T> extends true ? NonUndefined<T> extends Record<string, any> ? {
-    [K in keyof NonUndefined<T>]: NonUndefined<T>[K] extends Record<string, any> ? RefProxyFor<NonUndefined<T>[K] | undefined> & RefProxy<NonUndefined<T>[K] | undefined> : RefProxy<NonUndefined<T>[K] | undefined>;
+    [K in keyof NonUndefined<T>]-?: NonUndefined<T>[K] extends Record<string, any> ? RefProxyFor<NonUndefined<T>[K]> & RefProxy<NonUndefined<T>[K] | undefined> : RefProxy<NonUndefined<T>[K] | undefined>;
 } & RefProxy<T> : RefProxy<T> : T extends Record<string, any> ? {
-    [K in keyof T]: T[K] extends Record<string, any> ? RefProxyFor<T[K]> & RefProxy<T[K]> : RefProxy<T[K]>;
+    [K in keyof T]-?: undefined extends T[K] ? T[K] extends Record<string, any> ? RefProxyFor<T[K]> & RefProxy<T[K]> : RefProxy<T[K]> : T[K] extends Record<string, any> ? RefProxyFor<T[K]> & RefProxy<T[K]> : RefProxy<T[K]>;
 } & RefProxy<T> : RefProxy<T>>;
 export type Ref<T> = RefProxyFor<T>;
 type OmitRefProxy<T> = Omit<T, `__refProxy` | `__path` | `__type`>;

package/dist/esm/query/compiler/order-by.js

@@ -1,10 +1,10 @@
 import { orderByWithFractionalIndex } from "@tanstack/db-ivm";
-import { descComparator, ascComparator } from "../../utils/comparison.js";
+import { makeComparator, defaultComparator } from "../../utils/comparison.js";
 import { compileExpression } from "./evaluators.js";
 function processOrderBy(pipeline, orderByClause, limit, offset) {
   const compiledOrderBy = orderByClause.map((clause) => ({
     compiledExpression: compileExpression(clause.expression),
-    direction: clause.direction
+    compareOptions: clause.compareOptions
   }));
   const valueExtractor = (row) => {
     const orderByContext = { ...row };
@@ -21,29 +21,27 @@ function processOrderBy(pipeline, orderByClause, limit, offset) {
     }
     return null;
   };
-  const makeComparator = () => {
-    return (a, b) => {
-      if (orderByClause.length > 1) {
-        const arrayA = a;
-        const arrayB = b;
-        for (let i = 0; i < orderByClause.length; i++) {
-          const direction = orderByClause[i].direction;
-          const compareFn = direction === `desc` ? descComparator : ascComparator;
-          const result = compareFn(arrayA[i], arrayB[i]);
-          if (result !== 0) {
-            return result;
-          }
+  const comparator = (a, b) => {
+    if (orderByClause.length > 1) {
+      const arrayA = a;
+      const arrayB = b;
+      for (let i = 0; i < orderByClause.length; i++) {
+        const clause = orderByClause[i];
+        const compareFn = makeComparator(clause.compareOptions);
+        const result = compareFn(arrayA[i], arrayB[i]);
+        if (result !== 0) {
+          return result;
         }
-        return arrayA.length - arrayB.length;
-      }
-      if (orderByClause.length === 1) {
-        const direction = orderByClause[0].direction;
-        return direction === `desc` ? descComparator(a, b) : ascComparator(a, b);
       }
-      return ascComparator(a, b);
-    };
+      return arrayA.length - arrayB.length;
+    }
+    if (orderByClause.length === 1) {
+      const clause = orderByClause[0];
+      const compareFn = makeComparator(clause.compareOptions);
+      return compareFn(a, b);
+    }
+    return defaultComparator(a, b);
   };
-  const comparator = makeComparator();
   return pipeline.pipe(
     orderByWithFractionalIndex(valueExtractor, {
       limit,

package/dist/esm/query/compiler/order-by.js.map

@@ -1 +1 @@
-{"version":3,"file":"order-by.js","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { ascComparator, descComparator } from \"../../utils/comparison.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport type { OrderByClause } from \"../ir.js\"\nimport type { NamespacedAndKeyedStream, NamespacedRow } from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\n\n/**\n * Processes the ORDER BY clause\n * Works with the new structure that has both namespaced row data and __select_results\n * Always uses fractional indexing and adds the index as __ordering_index to the result\n */\nexport function processOrderBy(\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  limit?: number,\n  offset?: number\n): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {\n  // Pre-compile all order by expressions\n  const compiledOrderBy = orderByClause.map((clause) => ({\n    compiledExpression: compileExpression(clause.expression),\n    direction: clause.direction,\n  }))\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {\n    // For ORDER BY expressions, we need to provide access to both:\n    // 1. The original namespaced row data (for direct table column references)\n    // 2. The __select_results (for SELECT alias references)\n\n    // Create a merged context for expression evaluation\n    const orderByContext = { ...row }\n\n    // If there are select results, merge them at the top level for alias access\n    if (row.__select_results) {\n      // Add select results as top-level properties for alias access\n      Object.assign(orderByContext, row.__select_results)\n    }\n\n    if (orderByClause.length > 1) {\n      // For multiple orderBy columns, create a composite key\n      return compiledOrderBy.map((compiled) =>\n        compiled.compiledExpression(orderByContext)\n      )\n    } else if (orderByClause.length === 1) {\n      // For a single orderBy column, use the value directly\n      const compiled = compiledOrderBy[0]!\n      return compiled.compiledExpression(orderByContext)\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  // Create a multi-property comparator that respects the order and direction of each property\n  const makeComparator = () => {\n    return (a: unknown, b: unknown) => {\n      // If we're comparing arrays (multiple properties), compare each property in order\n      if (orderByClause.length > 1) {\n        const arrayA = a as Array<unknown>\n        const arrayB = b as Array<unknown>\n        for (let i = 0; i < orderByClause.length; i++) {\n          const direction = orderByClause[i]!.direction\n          const compareFn =\n            direction === `desc` ? descComparator : ascComparator\n          const result = compareFn(arrayA[i], arrayB[i])\n          if (result !== 0) {\n            return result\n          }\n        }\n        return arrayA.length - arrayB.length\n      }\n\n      // Single property comparison\n      if (orderByClause.length === 1) {\n        const direction = orderByClause[0]!.direction\n        return direction === `desc` ? descComparator(a, b) : ascComparator(a, b)\n      }\n\n      return ascComparator(a, b)\n    }\n  }\n\n  const comparator = makeComparator()\n\n  // Use fractional indexing and return the tuple [value, index]\n  return pipeline.pipe(\n    orderByWithFractionalIndex(valueExtractor, {\n      limit,\n      offset,\n      comparator,\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n"],"names":[],"mappings":";;;AAYO,SAAS,eACd,UACA,eACA,OACA,QAC4D;AAE5D,QAAM,kBAAkB,cAAc,IAAI,CAAC,YAAY;AAAA,IACrD,oBAAoB,kBAAkB,OAAO,UAAU;AAAA,IACvD,WAAW,OAAO;AAAA,EAAA,EAClB;AAGF,QAAM,iBAAiB,CAAC,QAAoD;AAM1E,UAAM,iBAAiB,EAAE,GAAG,IAAA;AAG5B,QAAI,IAAI,kBAAkB;AAExB,aAAO,OAAO,gBAAgB,IAAI,gBAAgB;AAAA,IACpD;AAEA,QAAI,cAAc,SAAS,GAAG;AAE5B,aAAO,gBAAgB;AAAA,QAAI,CAAC,aAC1B,SAAS,mBAAmB,cAAc;AAAA,MAAA;AAAA,IAE9C,WAAW,cAAc,WAAW,GAAG;AAErC,YAAM,WAAW,gBAAgB,CAAC;AAClC,aAAO,SAAS,mBAAmB,cAAc;AAAA,IACnD;AAGA,WAAO;AAAA,EACT;AAGA,QAAM,iBAAiB,MAAM;AAC3B,WAAO,CAAC,GAAY,MAAe;AAEjC,UAAI,cAAc,SAAS,GAAG;AAC5B,cAAM,SAAS;AACf,cAAM,SAAS;AACf,iBAAS,IAAI,GAAG,IAAI,cAAc,QAAQ,KAAK;AAC7C,gBAAM,YAAY,cAAc,CAAC,EAAG;AACpC,gBAAM,YACJ,cAAc,SAAS,iBAAiB;AAC1C,gBAAM,SAAS,UAAU,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AAC7C,cAAI,WAAW,GAAG;AAChB,mBAAO;AAAA,UACT;AAAA,QACF;AACA,eAAO,OAAO,SAAS,OAAO;AAAA,MAChC;AAGA,UAAI,cAAc,WAAW,GAAG;AAC9B,cAAM,YAAY,cAAc,CAAC,EAAG;AACpC,eAAO,cAAc,SAAS,eAAe,GAAG,CAAC,IAAI,cAAc,GAAG,CAAC;AAAA,MACzE;AAEA,aAAO,cAAc,GAAG,CAAC;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,aAAa,eAAA;AAGnB,SAAO,SAAS;AAAA,IACd,2BAA2B,gBAAgB;AAAA,MACzC;AAAA,MACA;AAAA,MACA;AAAA,IAAA,CACD;AAAA;AAAA,EAAA;AAGL;"}
+{"version":3,"file":"order-by.js","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { defaultComparator, makeComparator } from \"../../utils/comparison.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport type { OrderByClause } from \"../ir.js\"\nimport type { NamespacedAndKeyedStream, NamespacedRow } from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\n\n/**\n * Processes the ORDER BY clause\n * Works with the new structure that has both namespaced row data and __select_results\n * Always uses fractional indexing and adds the index as __ordering_index to the result\n */\nexport function processOrderBy(\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  limit?: number,\n  offset?: number\n): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {\n  // Pre-compile all order by expressions\n  const compiledOrderBy = orderByClause.map((clause) => ({\n    compiledExpression: compileExpression(clause.expression),\n    compareOptions: clause.compareOptions,\n  }))\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {\n    // For ORDER BY expressions, we need to provide access to both:\n    // 1. The original namespaced row data (for direct table column references)\n    // 2. The __select_results (for SELECT alias references)\n\n    // Create a merged context for expression evaluation\n    const orderByContext = { ...row }\n\n    // If there are select results, merge them at the top level for alias access\n    if (row.__select_results) {\n      // Add select results as top-level properties for alias access\n      Object.assign(orderByContext, row.__select_results)\n    }\n\n    if (orderByClause.length > 1) {\n      // For multiple orderBy columns, create a composite key\n      return compiledOrderBy.map((compiled) =>\n        compiled.compiledExpression(orderByContext)\n      )\n    } else if (orderByClause.length === 1) {\n      // For a single orderBy column, use the value directly\n      const compiled = compiledOrderBy[0]!\n      return compiled.compiledExpression(orderByContext)\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  // Create a multi-property comparator that respects the order and direction of each property\n  const comparator = (a: unknown, b: unknown) => {\n    // If we're comparing arrays (multiple properties), compare each property in order\n    if (orderByClause.length > 1) {\n      const arrayA = a as Array<unknown>\n      const arrayB = b as Array<unknown>\n      for (let i = 0; i < orderByClause.length; i++) {\n        const clause = orderByClause[i]!\n        const compareFn = makeComparator(clause.compareOptions)\n        const result = compareFn(arrayA[i], arrayB[i])\n        if (result !== 0) {\n          return result\n        }\n      }\n      return arrayA.length - arrayB.length\n    }\n\n    // Single property comparison\n    if (orderByClause.length === 1) {\n      const clause = orderByClause[0]!\n      const compareFn = makeComparator(clause.compareOptions)\n      return compareFn(a, b)\n    }\n\n    return defaultComparator(a, b)\n  }\n\n  // Use fractional indexing and return the tuple [value, index]\n  return pipeline.pipe(\n    orderByWithFractionalIndex(valueExtractor, {\n      limit,\n      offset,\n      comparator,\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n"],"names":[],"mappings":";;;AAYO,SAAS,eACd,UACA,eACA,OACA,QAC4D;AAE5D,QAAM,kBAAkB,cAAc,IAAI,CAAC,YAAY;AAAA,IACrD,oBAAoB,kBAAkB,OAAO,UAAU;AAAA,IACvD,gBAAgB,OAAO;AAAA,EAAA,EACvB;AAGF,QAAM,iBAAiB,CAAC,QAAoD;AAM1E,UAAM,iBAAiB,EAAE,GAAG,IAAA;AAG5B,QAAI,IAAI,kBAAkB;AAExB,aAAO,OAAO,gBAAgB,IAAI,gBAAgB;AAAA,IACpD;AAEA,QAAI,cAAc,SAAS,GAAG;AAE5B,aAAO,gBAAgB;AAAA,QAAI,CAAC,aAC1B,SAAS,mBAAmB,cAAc;AAAA,MAAA;AAAA,IAE9C,WAAW,cAAc,WAAW,GAAG;AAErC,YAAM,WAAW,gBAAgB,CAAC;AAClC,aAAO,SAAS,mBAAmB,cAAc;AAAA,IACnD;AAGA,WAAO;AAAA,EACT;AAGA,QAAM,aAAa,CAAC,GAAY,MAAe;AAE7C,QAAI,cAAc,SAAS,GAAG;AAC5B,YAAM,SAAS;AACf,YAAM,SAAS;AACf,eAAS,IAAI,GAAG,IAAI,cAAc,QAAQ,KAAK;AAC7C,cAAM,SAAS,cAAc,CAAC;AAC9B,cAAM,YAAY,eAAe,OAAO,cAAc;AACtD,cAAM,SAAS,UAAU,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AAC7C,YAAI,WAAW,GAAG;AAChB,iBAAO;AAAA,QACT;AAAA,MACF;AACA,aAAO,OAAO,SAAS,OAAO;AAAA,IAChC;AAGA,QAAI,cAAc,WAAW,GAAG;AAC9B,YAAM,SAAS,cAAc,CAAC;AAC9B,YAAM,YAAY,eAAe,OAAO,cAAc;AACtD,aAAO,UAAU,GAAG,CAAC;AAAA,IACvB;AAEA,WAAO,kBAAkB,GAAG,CAAC;AAAA,EAC/B;AAGA,SAAO,SAAS;AAAA,IACd,2BAA2B,gBAAgB;AAAA,MACzC;AAAA,MACA;AAAA,MACA;AAAA,IAAA,CACD;AAAA;AAAA,EAAA;AAGL;"}

package/dist/esm/query/ir.d.ts

@@ -1,3 +1,4 @@
+import { CompareOptions } from './builder/types.js';
 import { CollectionImpl } from '../collection.js';
 import { NamespacedRow } from '../types.js';
 export interface QueryIR {
@@ -32,7 +33,7 @@ export type Having = Where;
 export type OrderBy = Array<OrderByClause>;
 export type OrderByClause = {
     expression: BasicExpression;
-    direction: OrderByDirection;
+    compareOptions: CompareOptions;
 };
 export type OrderByDirection = `asc` | `desc`;
 export type Limit = number;