@tanstack/db 0.5.33 → 0.6.0

package/dist/cjs/collection/change-events.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"change-events.cjs","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy'\nimport {\n  compileSingleRowExpression,\n  toBooleanPredicate,\n} from '../query/compiler/evaluators.js'\nimport {\n  findIndexForField,\n  optimizeExpressionWithIndexes,\n} from '../utils/index-optimization.js'\nimport { ensureIndexForField } from '../indexes/auto-index.js'\nimport { makeComparator } from '../utils/comparison.js'\nimport { buildCompareOptions } from '../query/compiler/order-by'\nimport type {\n  ChangeMessage,\n  CollectionLike,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from '../types'\nimport type { CollectionImpl } from './index.js'\nimport type { SingleRowRefProxy } from '../query/builder/ref-proxy'\nimport type { BasicExpression, OrderBy } from '../query/ir.js'\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter, orderBy, and limit\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active')\n * })\n *\n * // Get items ordered by name with limit\n * const topUsers = currentStateAsChanges(collection, {\n *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],\n *   limit: 10\n * })\n *\n * // Get active users ordered by score (highest score first)\n * const topActiveUsers = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active'),\n *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<T, TKey>,\n  options: CurrentStateAsChangesOptions = {},\n): Array<ChangeMessage<T>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: T) => boolean,\n  ): Array<ChangeMessage<T>> => {\n    const result: Array<ChangeMessage<T>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // Validate that limit without orderBy doesn't happen\n  if (options.limit !== undefined && !options.orderBy) {\n    throw new Error(`limit cannot be used without orderBy`)\n  }\n\n  // First check if orderBy is present (optionally with limit)\n  if (options.orderBy) {\n    // Create where filter function if present\n    const whereFilter = options.where\n      ? createFilterFunctionFromExpression(options.where)\n      : undefined\n\n    // Get ordered keys using index optimization when possible\n    const orderedKeys = getOrderedKeys(\n      collection,\n      options.orderBy,\n      options.limit,\n      whereFilter,\n      options.optimizedOnly,\n    )\n\n    if (orderedKeys === undefined) {\n      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use\n      return\n    }\n\n    // Convert keys to change messages\n    const result: Array<ChangeMessage<T>> = []\n    for (const key of orderedKeys) {\n      const value = collection.get(key)\n      if (value !== undefined) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // If no orderBy OR orderBy optimization failed, use where clause optimization\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection,\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<T>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,\n      error,\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any,\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return toBooleanPredicate(result)\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return toBooleanPredicate(result)\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>,\n): (item: T) => boolean {\n  // Compile expression once when filter function is created, not on every invocation\n  const evaluator = compileSingleRowExpression(expression)\n\n  return (item: T): boolean => {\n    try {\n      const result = evaluator(item as Record<string, unknown>)\n      return toBooleanPredicate(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<T extends object>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions,\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n\n/**\n * Gets ordered keys from a collection using index optimization when possible\n * @param collection - The collection to get keys from\n * @param orderBy - The order by clause\n * @param limit - Optional limit on number of keys to return\n * @param whereFilter - Optional filter function to apply while traversing\n * @returns Array of keys in sorted order\n */\nfunction getOrderedKeys<T extends object, TKey extends string | number>(\n  collection: CollectionLike<T, TKey>,\n  orderBy: OrderBy,\n  limit?: number,\n  whereFilter?: (item: T) => boolean,\n  optimizedOnly?: boolean,\n): Array<TKey> | undefined {\n  // For single-column orderBy on a ref expression, try index optimization\n  if (orderBy.length === 1) {\n    const clause = orderBy[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const propRef = orderByExpression\n      const fieldPath = propRef.path\n      const compareOpts = buildCompareOptions(clause, collection)\n\n      // Ensure index exists for this field\n      ensureIndexForField(\n        fieldPath[0]!,\n        fieldPath,\n        collection as CollectionImpl<T, TKey>,\n        compareOpts,\n      )\n\n      // Find the index\n      const index = findIndexForField(collection, fieldPath, compareOpts)\n\n      if (index && index.supports(`gt`)) {\n        // Use index optimization\n        const filterFn = (key: TKey): boolean => {\n          const value = collection.get(key)\n          if (value === undefined) {\n            return false\n          }\n          return whereFilter?.(value) ?? true\n        }\n\n        // Take the keys that match the filter and limit\n        // if no limit is provided `index.keyCount` is used,\n        // i.e. we will take all keys that match the filter\n        return index.takeFromStart(limit ?? index.keyCount, filterFn)\n      }\n    }\n  }\n\n  if (optimizedOnly) {\n    return\n  }\n\n  // Fallback: collect all items and sort in memory\n  const allItems: Array<{ key: TKey; value: T }> = []\n  for (const [key, value] of collection.entries()) {\n    if (whereFilter?.(value) ?? true) {\n      allItems.push({ key, value })\n    }\n  }\n\n  // Sort using makeComparator\n  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {\n    for (const clause of orderBy) {\n      const compareFn = makeComparator(clause.compareOptions)\n\n      // Extract values for comparison\n      const aValue = extractValueFromItem(a.value, clause.expression)\n      const bValue = extractValueFromItem(b.value, clause.expression)\n\n      const result = compareFn(aValue, bValue)\n      if (result !== 0) {\n        return result\n      }\n    }\n    return 0\n  }\n\n  allItems.sort(compare)\n  const sortedKeys = allItems.map((item) => item.key)\n\n  // Apply limit if provided\n  if (limit !== undefined) {\n    return sortedKeys.slice(0, limit)\n  }\n\n  // if no limit is provided, we will return all keys\n  return sortedKeys\n}\n\n/**\n * Helper function to extract a value from an item based on an expression\n */\nfunction extractValueFromItem(item: any, expression: BasicExpression): any {\n  if (expression.type === `ref`) {\n    const propRef = expression\n    let value = item\n    for (const pathPart of propRef.path) {\n      value = value?.[pathPart]\n    }\n    return value\n  } else if (expression.type === `val`) {\n    return expression.value\n  } else {\n    // It must be a function\n    const evaluator = compileSingleRowExpression(expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n}\n"],"names":["optimizeExpressionWithIndexes","compileSingleRowExpression","toBooleanPredicate","orderBy","buildCompareOptions","ensureIndexForField","findIndexForField","makeComparator"],"mappings":"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"}
+{"version":3,"file":"change-events.cjs","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy'\nimport {\n  compileSingleRowExpression,\n  toBooleanPredicate,\n} from '../query/compiler/evaluators.js'\nimport {\n  findIndexForField,\n  optimizeExpressionWithIndexes,\n} from '../utils/index-optimization.js'\nimport { ensureIndexForField } from '../indexes/auto-index.js'\nimport { makeComparator } from '../utils/comparison.js'\nimport { buildCompareOptions } from '../query/compiler/order-by'\nimport type {\n  ChangeMessage,\n  CollectionLike,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from '../types'\nimport type { CollectionImpl } from './index.js'\nimport type { SingleRowRefProxy } from '../query/builder/ref-proxy'\nimport type { BasicExpression, OrderBy } from '../query/ir.js'\nimport type { WithVirtualProps } from '../virtual-props.js'\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter, orderBy, and limit\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active')\n * })\n *\n * // Get items ordered by name with limit\n * const topUsers = currentStateAsChanges(collection, {\n *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],\n *   limit: 10\n * })\n *\n * // Get active users ordered by score (highest score first)\n * const topActiveUsers = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active'),\n *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<WithVirtualProps<T, TKey>, TKey>,\n  options: CurrentStateAsChangesOptions = {},\n): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: WithVirtualProps<T, TKey>) => boolean,\n  ): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> => {\n    const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // Validate that limit without orderBy doesn't happen\n  if (options.limit !== undefined && !options.orderBy) {\n    throw new Error(`limit cannot be used without orderBy`)\n  }\n\n  // First check if orderBy is present (optionally with limit)\n  if (options.orderBy) {\n    // Create where filter function if present\n    const whereFilter = options.where\n      ? createFilterFunctionFromExpression(options.where)\n      : undefined\n\n    // Get ordered keys using index optimization when possible\n    const orderedKeys = getOrderedKeys(\n      collection,\n      options.orderBy,\n      options.limit,\n      whereFilter,\n      options.optimizedOnly,\n    )\n\n    if (orderedKeys === undefined) {\n      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use\n      return\n    }\n\n    // Convert keys to change messages\n    const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []\n    for (const key of orderedKeys) {\n      const value = collection.get(key)\n      if (value !== undefined) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // If no orderBy OR orderBy optimization failed, use where clause optimization\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection,\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,\n      error,\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any,\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return toBooleanPredicate(result)\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return toBooleanPredicate(result)\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>,\n): (item: T) => boolean {\n  // Compile expression once when filter function is created, not on every invocation\n  const evaluator = compileSingleRowExpression(expression)\n\n  return (item: T): boolean => {\n    try {\n      const result = evaluator(item as Record<string, unknown>)\n      return toBooleanPredicate(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions<T, TKey>,\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n\n/**\n * Gets ordered keys from a collection using index optimization when possible\n * @param collection - The collection to get keys from\n * @param orderBy - The order by clause\n * @param limit - Optional limit on number of keys to return\n * @param whereFilter - Optional filter function to apply while traversing\n * @returns Array of keys in sorted order\n */\nfunction getOrderedKeys<T extends object, TKey extends string | number>(\n  collection: CollectionLike<T, TKey>,\n  orderBy: OrderBy,\n  limit?: number,\n  whereFilter?: (item: T) => boolean,\n  optimizedOnly?: boolean,\n): Array<TKey> | undefined {\n  // For single-column orderBy on a ref expression, try index optimization\n  if (orderBy.length === 1) {\n    const clause = orderBy[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const propRef = orderByExpression\n      const fieldPath = propRef.path\n      const compareOpts = buildCompareOptions(clause, collection)\n\n      // Ensure index exists for this field\n      ensureIndexForField(\n        fieldPath[0]!,\n        fieldPath,\n        collection as CollectionImpl<T, TKey>,\n        compareOpts,\n      )\n\n      // Find the index\n      const index = findIndexForField(collection, fieldPath, compareOpts)\n\n      if (index && index.supports(`gt`)) {\n        // Use index optimization\n        const filterFn = (key: TKey): boolean => {\n          const value = collection.get(key)\n          if (value === undefined) {\n            return false\n          }\n          return whereFilter?.(value) ?? true\n        }\n\n        // Take the keys that match the filter and limit\n        // if no limit is provided `index.keyCount` is used,\n        // i.e. we will take all keys that match the filter\n        return index.takeFromStart(limit ?? index.keyCount, filterFn)\n      }\n    }\n  }\n\n  if (optimizedOnly) {\n    return\n  }\n\n  // Fallback: collect all items and sort in memory\n  const allItems: Array<{ key: TKey; value: T }> = []\n  for (const [key, value] of collection.entries()) {\n    if (whereFilter?.(value) ?? true) {\n      allItems.push({ key, value })\n    }\n  }\n\n  // Sort using makeComparator\n  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {\n    for (const clause of orderBy) {\n      const compareFn = makeComparator(clause.compareOptions)\n\n      // Extract values for comparison\n      const aValue = extractValueFromItem(a.value, clause.expression)\n      const bValue = extractValueFromItem(b.value, clause.expression)\n\n      const result = compareFn(aValue, bValue)\n      if (result !== 0) {\n        return result\n      }\n    }\n    return 0\n  }\n\n  allItems.sort(compare)\n  const sortedKeys = allItems.map((item) => item.key)\n\n  // Apply limit if provided\n  if (limit !== undefined) {\n    return sortedKeys.slice(0, limit)\n  }\n\n  // if no limit is provided, we will return all keys\n  return sortedKeys\n}\n\n/**\n * Helper function to extract a value from an item based on an expression\n */\nfunction extractValueFromItem(item: any, expression: BasicExpression): any {\n  if (expression.type === `ref`) {\n    const propRef = expression\n    let value = item\n    for (const pathPart of propRef.path) {\n      value = value?.[pathPart]\n    }\n    return value\n  } else if (expression.type === `val`) {\n    return expression.value\n  } else {\n    // It must be a function\n    const evaluator = compileSingleRowExpression(expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n}\n"],"names":["optimizeExpressionWithIndexes","compileSingleRowExpression","toBooleanPredicate","orderBy","buildCompareOptions","ensureIndexForField","findIndexForField","makeComparator"],"mappings":"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"}

package/dist/cjs/collection/change-events.d.cts

@@ -1,6 +1,7 @@
 import { ChangeMessage, CollectionLike, CurrentStateAsChangesOptions, SubscribeChangesOptions } from '../types.cjs';
 import { SingleRowRefProxy } from '../query/builder/ref-proxy.cjs';
 import { BasicExpression } from '../query/ir.js';
+import { WithVirtualProps } from '../virtual-props.js';
 /**
  * Returns the current state of the collection as an array of changes
  * @param collection - The collection to get changes from
@@ -32,7 +33,7 @@ import { BasicExpression } from '../query/ir.js';
  *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],
  * })
  */
-export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<T, TKey>, options?: CurrentStateAsChangesOptions): Array<ChangeMessage<T>> | void;
+export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<WithVirtualProps<T, TKey>, TKey>, options?: CurrentStateAsChangesOptions): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> | void;
 /**
  * Creates a filter function from a where callback
  * @param whereCallback - The callback function that defines the filter condition
@@ -51,4 +52,4 @@ export declare function createFilterFunctionFromExpression<T extends object>(exp
  * @param options - The subscription options containing the where clause
  * @returns A filtered callback function
  */
-export declare function createFilteredCallback<T extends object>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions): (changes: Array<ChangeMessage<T>>) => void;
+export declare function createFilteredCallback<T extends object, TKey extends string | number = string | number>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions<T, TKey>): (changes: Array<ChangeMessage<T>>) => void;

package/dist/cjs/collection/changes.cjs

@@ -18,6 +18,7 @@ class CollectionChangesManager {
     this.sync = deps.sync;
     this.events = deps.events;
     this.collection = deps.collection;
+    this.state = deps.state;
   }
   /**
    * Emit an empty ready event to notify subscribers that the collection is ready
@@ -28,6 +29,13 @@ class CollectionChangesManager {
       subscription2.emitEvents([]);
     }
   }
+  /**
+   * Enriches a change message with virtual properties ($synced, $origin, $key, $collectionId).
+   * Uses the "add-if-missing" pattern to preserve virtual properties from upstream collections.
+   */
+  enrichChangeWithVirtualProps(change) {
+    return this.state.enrichChangeMessage(change);
+  }
   /**
    * Emit events either immediately or batch them for later emission
    */
@@ -36,19 +44,20 @@ class CollectionChangesManager {
       this.batchedEvents.push(...changes);
       return;
     }
-    let eventsToEmit = changes;
+    let rawEvents = changes;
     if (forceEmit) {
       if (this.batchedEvents.length > 0) {
-        eventsToEmit = [...this.batchedEvents, ...changes];
+        rawEvents = [...this.batchedEvents, ...changes];
       }
       this.batchedEvents = [];
       this.shouldBatchEvents = false;
     }
-    if (eventsToEmit.length === 0) {
+    if (rawEvents.length === 0) {
       return;
     }
+    const enrichedEvents = rawEvents.map((change) => this.enrichChangeWithVirtualProps(change));
     for (const subscription2 of this.changeSubscriptions) {
-      subscription2.emitEvents(eventsToEmit);
+      subscription2.emitEvents(enrichedEvents);
     }
   }
   /**

package/dist/cjs/collection/changes.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"changes.cjs","sources":["../../../src/collection/changes.ts"],"sourcesContent":["import { NegativeActiveSubscribersError } from '../errors'\nimport {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy.js'\nimport { CollectionSubscription } from './subscription.js'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type { ChangeMessage, SubscribeChangesOptions } from '../types'\nimport type { CollectionLifecycleManager } from './lifecycle.js'\nimport type { CollectionSyncManager } from './sync.js'\nimport type { CollectionEventsManager } from './events.js'\nimport type { CollectionImpl } from './index.js'\n\nexport class CollectionChangesManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n\n  public activeSubscribersCount = 0\n  public changeSubscriptions = new Set<CollectionSubscription>()\n  public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []\n  public shouldBatchEvents = false\n\n  /**\n   * Creates a new CollectionChangesManager instance\n   */\n  constructor() {}\n\n  public setDeps(deps: {\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  }) {\n    this.lifecycle = deps.lifecycle\n    this.sync = deps.sync\n    this.events = deps.events\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an empty ready event to notify subscribers that the collection is ready\n   * This bypasses the normal empty array check in emitEvents\n   */\n  public emitEmptyReadyEvent(): void {\n    // Emit empty array directly to all subscribers\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents([])\n    }\n  }\n\n  /**\n   * Emit events either immediately or batch them for later emission\n   */\n  public emitEvents(\n    changes: Array<ChangeMessage<TOutput, TKey>>,\n    forceEmit = false,\n  ): void {\n    // Skip batching for user actions (forceEmit=true) to keep UI responsive\n    if (this.shouldBatchEvents && !forceEmit) {\n      // Add events to the batch\n      this.batchedEvents.push(...changes)\n      return\n    }\n\n    // Either we're not batching, or we're forcing emission (user action or ending batch cycle)\n    let eventsToEmit = changes\n\n    if (forceEmit) {\n      // Force emit is used to end a batch (e.g. after a sync commit). Combine any\n      // buffered optimistic events with the final changes so subscribers see the\n      // whole picture, even if the sync diff is empty.\n      if (this.batchedEvents.length > 0) {\n        eventsToEmit = [...this.batchedEvents, ...changes]\n      }\n      this.batchedEvents = []\n      this.shouldBatchEvents = false\n    }\n\n    if (eventsToEmit.length === 0) {\n      return\n    }\n\n    // Emit to all listeners\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents(eventsToEmit)\n    }\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   */\n  public subscribeChanges(\n    callback: (changes: Array<ChangeMessage<TOutput>>) => void,\n    options: SubscribeChangesOptions<TOutput> = {},\n  ): CollectionSubscription {\n    // Start sync and track subscriber\n    this.addSubscriber()\n\n    // Compile where callback to whereExpression if provided\n    if (options.where && options.whereExpression) {\n      throw new Error(\n        `Cannot specify both 'where' and 'whereExpression' options. Use one or the other.`,\n      )\n    }\n\n    const { where, ...opts } = options\n    let whereExpression = opts.whereExpression\n    if (where) {\n      const proxy = createSingleRowRefProxy<TOutput>()\n      const result = where(proxy)\n      whereExpression = toExpression(result)\n    }\n\n    const subscription = new CollectionSubscription(this.collection, callback, {\n      ...opts,\n      whereExpression,\n      onUnsubscribe: () => {\n        this.removeSubscriber()\n        this.changeSubscriptions.delete(subscription)\n      },\n    })\n\n    // Register status listener BEFORE requesting snapshot to avoid race condition.\n    // This ensures the listener catches all status transitions, even if the\n    // loadSubset promise resolves synchronously or very quickly.\n    if (options.onStatusChange) {\n      subscription.on(`status:change`, options.onStatusChange)\n    }\n\n    if (options.includeInitialState) {\n      subscription.requestSnapshot({\n        trackLoadSubsetPromise: false,\n        orderBy: options.orderBy,\n        limit: options.limit,\n        onLoadSubsetResult: options.onLoadSubsetResult,\n      })\n    } else if (options.includeInitialState === false) {\n      // When explicitly set to false (not just undefined), mark all state as \"seen\"\n      // so that all future changes (including deletes) pass through unfiltered.\n      subscription.markAllStateAsSeen()\n    }\n\n    // Add to batched listeners\n    this.changeSubscriptions.add(subscription)\n\n    return subscription\n  }\n\n  /**\n   * Increment the active subscribers count and start sync if needed\n   */\n  private addSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount++\n    this.lifecycle.cancelGCTimer()\n\n    // Start sync if collection was cleaned up\n    if (\n      this.lifecycle.status === `cleaned-up` ||\n      this.lifecycle.status === `idle`\n    ) {\n      this.sync.startSync()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Decrement the active subscribers count and start GC timer if needed\n   */\n  private removeSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount--\n\n    if (this.activeSubscribersCount === 0) {\n      this.lifecycle.startGCTimer()\n    } else if (this.activeSubscribersCount < 0) {\n      throw new NegativeActiveSubscribersError()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public cleanup(): void {\n    this.batchedEvents = []\n    this.shouldBatchEvents = false\n  }\n}\n"],"names":["subscription","createSingleRowRefProxy","toExpression","CollectionSubscription","NegativeActiveSubscribersError"],"mappings":";;;;;AAaO,MAAM,yBAKX;AAAA;AAAA;AAAA;AAAA,EAcA,cAAc;AARd,SAAO,yBAAyB;AAChC,SAAO,0CAA0B,IAAA;AACjC,SAAO,gBAAqD,CAAA;AAC5D,SAAO,oBAAoB;AAAA,EAKZ;AAAA,EAER,QAAQ,MAKZ;AACD,SAAK,YAAY,KAAK;AACtB,SAAK,OAAO,KAAK;AACjB,SAAK,SAAS,KAAK;AACnB,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,sBAA4B;AAEjC,eAAWA,iBAAgB,KAAK,qBAAqB;AACnD,MAAAA,cAAa,WAAW,EAAE;AAAA,IAC5B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,WACL,SACA,YAAY,OACN;AAEN,QAAI,KAAK,qBAAqB,CAAC,WAAW;AAExC,WAAK,cAAc,KAAK,GAAG,OAAO;AAClC;AAAA,IACF;AAGA,QAAI,eAAe;AAEnB,QAAI,WAAW;AAIb,UAAI,KAAK,cAAc,SAAS,GAAG;AACjC,uBAAe,CAAC,GAAG,KAAK,eAAe,GAAG,OAAO;AAAA,MACnD;AACA,WAAK,gBAAgB,CAAA;AACrB,WAAK,oBAAoB;AAAA,IAC3B;AAEA,QAAI,aAAa,WAAW,GAAG;AAC7B;AAAA,IACF;AAGA,eAAWA,iBAAgB,KAAK,qBAAqB;AACnD,MAAAA,cAAa,WAAW,YAAY;AAAA,IACtC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,iBACL,UACA,UAA4C,IACpB;AAExB,SAAK,cAAA;AAGL,QAAI,QAAQ,SAAS,QAAQ,iBAAiB;AAC5C,YAAM,IAAI;AAAA,QACR;AAAA,MAAA;AAAA,IAEJ;AAEA,UAAM,EAAE,OAAO,GAAG,KAAA,IAAS;AAC3B,QAAI,kBAAkB,KAAK;AAC3B,QAAI,OAAO;AACT,YAAM,QAAQC,SAAAA,wBAAA;AACd,YAAM,SAAS,MAAM,KAAK;AAC1B,wBAAkBC,SAAAA,aAAa,MAAM;AAAA,IACvC;AAEA,UAAMF,iBAAe,IAAIG,aAAAA,uBAAuB,KAAK,YAAY,UAAU;AAAA,MACzE,GAAG;AAAA,MACH;AAAA,MACA,eAAe,MAAM;AACnB,aAAK,iBAAA;AACL,aAAK,oBAAoB,OAAOH,cAAY;AAAA,MAC9C;AAAA,IAAA,CACD;AAKD,QAAI,QAAQ,gBAAgB;AAC1BA,qBAAa,GAAG,iBAAiB,QAAQ,cAAc;AAAA,IACzD;AAEA,QAAI,QAAQ,qBAAqB;AAC/BA,qBAAa,gBAAgB;AAAA,QAC3B,wBAAwB;AAAA,QACxB,SAAS,QAAQ;AAAA,QACjB,OAAO,QAAQ;AAAA,QACf,oBAAoB,QAAQ;AAAA,MAAA,CAC7B;AAAA,IACH,WAAW,QAAQ,wBAAwB,OAAO;AAGhDA,qBAAa,mBAAA;AAAA,IACf;AAGA,SAAK,oBAAoB,IAAIA,cAAY;AAEzC,WAAOA;AAAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKQ,gBAAsB;AAC5B,UAAM,0BAA0B,KAAK;AACrC,SAAK;AACL,SAAK,UAAU,cAAA;AAGf,QACE,KAAK,UAAU,WAAW,gBAC1B,KAAK,UAAU,WAAW,QAC1B;AACA,WAAK,KAAK,UAAA;AAAA,IACZ;AAEA,SAAK,OAAO;AAAA,MACV,KAAK;AAAA,MACL;AAAA,IAAA;AAAA,EAEJ;AAAA;AAAA;AAAA;AAAA,EAKQ,mBAAyB;AAC/B,UAAM,0BAA0B,KAAK;AACrC,SAAK;AAEL,QAAI,KAAK,2BAA2B,GAAG;AACrC,WAAK,UAAU,aAAA;AAAA,IACjB,WAAW,KAAK,yBAAyB,GAAG;AAC1C,YAAM,IAAII,OAAAA,+BAAA;AAAA,IACZ;AAEA,SAAK,OAAO;AAAA,MACV,KAAK;AAAA,MACL;AAAA,IAAA;AAAA,EAEJ;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,UAAgB;AACrB,SAAK,gBAAgB,CAAA;AACrB,SAAK,oBAAoB;AAAA,EAC3B;AACF;;"}
+{"version":3,"file":"changes.cjs","sources":["../../../src/collection/changes.ts"],"sourcesContent":["import { NegativeActiveSubscribersError } from '../errors'\nimport {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy.js'\nimport { CollectionSubscription } from './subscription.js'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type { ChangeMessage, SubscribeChangesOptions } from '../types'\nimport type { CollectionLifecycleManager } from './lifecycle.js'\nimport type { CollectionSyncManager } from './sync.js'\nimport type { CollectionEventsManager } from './events.js'\nimport type { CollectionImpl } from './index.js'\nimport type { CollectionStateManager } from './state.js'\nimport type { WithVirtualProps } from '../virtual-props.js'\n\nexport class CollectionChangesManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  public activeSubscribersCount = 0\n  public changeSubscriptions = new Set<CollectionSubscription>()\n  public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []\n  public shouldBatchEvents = false\n\n  /**\n   * Creates a new CollectionChangesManager instance\n   */\n  constructor() {}\n\n  public setDeps(deps: {\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.lifecycle = deps.lifecycle\n    this.sync = deps.sync\n    this.events = deps.events\n    this.collection = deps.collection\n    this.state = deps.state\n  }\n\n  /**\n   * Emit an empty ready event to notify subscribers that the collection is ready\n   * This bypasses the normal empty array check in emitEvents\n   */\n  public emitEmptyReadyEvent(): void {\n    // Emit empty array directly to all subscribers\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents([])\n    }\n  }\n\n  /**\n   * Enriches a change message with virtual properties ($synced, $origin, $key, $collectionId).\n   * Uses the \"add-if-missing\" pattern to preserve virtual properties from upstream collections.\n   */\n  private enrichChangeWithVirtualProps(\n    change: ChangeMessage<TOutput, TKey>,\n  ): ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey> {\n    return this.state.enrichChangeMessage(change)\n  }\n\n  /**\n   * Emit events either immediately or batch them for later emission\n   */\n  public emitEvents(\n    changes: Array<ChangeMessage<TOutput, TKey>>,\n    forceEmit = false,\n  ): void {\n    // Skip batching for user actions (forceEmit=true) to keep UI responsive\n    if (this.shouldBatchEvents && !forceEmit) {\n      // Add events to the batch\n      this.batchedEvents.push(...changes)\n      return\n    }\n\n    // Either we're not batching, or we're forcing emission (user action or ending batch cycle)\n    let rawEvents = changes\n\n    if (forceEmit) {\n      // Force emit is used to end a batch (e.g. after a sync commit). Combine any\n      // buffered optimistic events with the final changes so subscribers see the\n      // whole picture, even if the sync diff is empty.\n      if (this.batchedEvents.length > 0) {\n        rawEvents = [...this.batchedEvents, ...changes]\n      }\n      this.batchedEvents = []\n      this.shouldBatchEvents = false\n    }\n\n    if (rawEvents.length === 0) {\n      return\n    }\n\n    // Enrich all change messages with virtual properties\n    // This uses the \"add-if-missing\" pattern to preserve pass-through semantics\n    const enrichedEvents: Array<\n      ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey>\n    > = rawEvents.map((change) => this.enrichChangeWithVirtualProps(change))\n\n    // Emit to all listeners\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents(enrichedEvents)\n    }\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   */\n  public subscribeChanges(\n    callback: (\n      changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>,\n    ) => void,\n    options: SubscribeChangesOptions<TOutput, TKey> = {},\n  ): CollectionSubscription {\n    // Start sync and track subscriber\n    this.addSubscriber()\n\n    // Compile where callback to whereExpression if provided\n    if (options.where && options.whereExpression) {\n      throw new Error(\n        `Cannot specify both 'where' and 'whereExpression' options. Use one or the other.`,\n      )\n    }\n\n    const { where, ...opts } = options\n    let whereExpression = opts.whereExpression\n    if (where) {\n      const proxy = createSingleRowRefProxy<WithVirtualProps<TOutput, TKey>>()\n      const result = where(proxy)\n      whereExpression = toExpression(result)\n    }\n\n    const subscription = new CollectionSubscription(this.collection, callback, {\n      ...opts,\n      whereExpression,\n      onUnsubscribe: () => {\n        this.removeSubscriber()\n        this.changeSubscriptions.delete(subscription)\n      },\n    })\n\n    // Register status listener BEFORE requesting snapshot to avoid race condition.\n    // This ensures the listener catches all status transitions, even if the\n    // loadSubset promise resolves synchronously or very quickly.\n    if (options.onStatusChange) {\n      subscription.on(`status:change`, options.onStatusChange)\n    }\n\n    if (options.includeInitialState) {\n      subscription.requestSnapshot({\n        trackLoadSubsetPromise: false,\n        orderBy: options.orderBy,\n        limit: options.limit,\n        onLoadSubsetResult: options.onLoadSubsetResult,\n      })\n    } else if (options.includeInitialState === false) {\n      // When explicitly set to false (not just undefined), mark all state as \"seen\"\n      // so that all future changes (including deletes) pass through unfiltered.\n      subscription.markAllStateAsSeen()\n    }\n\n    // Add to batched listeners\n    this.changeSubscriptions.add(subscription)\n\n    return subscription\n  }\n\n  /**\n   * Increment the active subscribers count and start sync if needed\n   */\n  private addSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount++\n    this.lifecycle.cancelGCTimer()\n\n    // Start sync if collection was cleaned up\n    if (\n      this.lifecycle.status === `cleaned-up` ||\n      this.lifecycle.status === `idle`\n    ) {\n      this.sync.startSync()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Decrement the active subscribers count and start GC timer if needed\n   */\n  private removeSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount--\n\n    if (this.activeSubscribersCount === 0) {\n      this.lifecycle.startGCTimer()\n    } else if (this.activeSubscribersCount < 0) {\n      throw new NegativeActiveSubscribersError()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public cleanup(): void {\n    this.batchedEvents = []\n    this.shouldBatchEvents = false\n  }\n}\n"],"names":["subscription","createSingleRowRefProxy","toExpression","CollectionSubscription","NegativeActiveSubscribersError"],"mappings":"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"}

package/dist/cjs/collection/changes.d.cts

@@ -5,11 +5,14 @@ import { CollectionLifecycleManager } from './lifecycle.js';
 import { CollectionSyncManager } from './sync.js';
 import { CollectionEventsManager } from './events.js';
 import { CollectionImpl } from './index.js';
+import { CollectionStateManager } from './state.js';
+import { WithVirtualProps } from '../virtual-props.js';
 export declare class CollectionChangesManager<TOutput extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInput extends object = TOutput> {
     private lifecycle;
     private sync;
     private events;
     private collection;
+    private state;
     activeSubscribersCount: number;
     changeSubscriptions: Set<CollectionSubscription>;
     batchedEvents: Array<ChangeMessage<TOutput, TKey>>;
@@ -23,12 +26,18 @@ export declare class CollectionChangesManager<TOutput extends object = Record<st
         sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>;
         events: CollectionEventsManager;
         collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>;
+        state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
     }): void;
     /**
      * Emit an empty ready event to notify subscribers that the collection is ready
      * This bypasses the normal empty array check in emitEvents
      */
     emitEmptyReadyEvent(): void;
+    /**
+     * Enriches a change message with virtual properties ($synced, $origin, $key, $collectionId).
+     * Uses the "add-if-missing" pattern to preserve virtual properties from upstream collections.
+     */
+    private enrichChangeWithVirtualProps;
     /**
      * Emit events either immediately or batch them for later emission
      */
@@ -36,7 +45,7 @@ export declare class CollectionChangesManager<TOutput extends object = Record<st
     /**
      * Subscribe to changes in the collection
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<TOutput>>) => void, options?: SubscribeChangesOptions<TOutput>): CollectionSubscription;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>) => void, options?: SubscribeChangesOptions<TOutput, TKey>): CollectionSubscription;
     /**
      * Increment the active subscribers count and start sync if needed
      */

package/dist/cjs/collection/cleanup-queue.cjs

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const _CleanupQueue = class _CleanupQueue {
+  constructor() {
+    this.tasks = /* @__PURE__ */ new Map();
+    this.timeoutId = null;
+    this.microtaskScheduled = false;
+  }
+  static getInstance() {
+    if (!_CleanupQueue.instance) {
+      _CleanupQueue.instance = new _CleanupQueue();
+    }
+    return _CleanupQueue.instance;
+  }
+  /**
+   * Queues a cleanup task and defers timeout selection to a microtask so
+   * multiple synchronous registrations can share one root timer.
+   */
+  schedule(key, gcTime, callback) {
+    const executeAt = Date.now() + gcTime;
+    this.tasks.set(key, { executeAt, callback });
+    if (!this.microtaskScheduled) {
+      this.microtaskScheduled = true;
+      Promise.resolve().then(() => {
+        this.microtaskScheduled = false;
+        this.updateTimeout();
+      });
+    }
+  }
+  cancel(key) {
+    this.tasks.delete(key);
+  }
+  /**
+   * Keeps only one active timeout: whichever task is due next.
+   */
+  updateTimeout() {
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+    if (this.tasks.size === 0) {
+      return;
+    }
+    let earliestTime = Infinity;
+    for (const task of this.tasks.values()) {
+      if (task.executeAt < earliestTime) {
+        earliestTime = task.executeAt;
+      }
+    }
+    const delay = Math.max(0, earliestTime - Date.now());
+    this.timeoutId = setTimeout(() => this.process(), delay);
+  }
+  /**
+   * Runs every task whose deadline has passed, then schedules the next wakeup
+   * if there is still pending work.
+   */
+  process() {
+    this.timeoutId = null;
+    const now = Date.now();
+    for (const [key, task] of this.tasks.entries()) {
+      if (now >= task.executeAt) {
+        this.tasks.delete(key);
+        try {
+          task.callback();
+        } catch (error) {
+          console.error("Error in CleanupQueue task:", error);
+        }
+      }
+    }
+    if (this.tasks.size > 0) {
+      this.updateTimeout();
+    }
+  }
+  /**
+   * Resets the singleton instance for tests.
+   */
+  static resetInstance() {
+    if (_CleanupQueue.instance) {
+      if (_CleanupQueue.instance.timeoutId !== null) {
+        clearTimeout(_CleanupQueue.instance.timeoutId);
+      }
+      _CleanupQueue.instance = null;
+    }
+  }
+};
+_CleanupQueue.instance = null;
+let CleanupQueue = _CleanupQueue;
+exports.CleanupQueue = CleanupQueue;
+//# sourceMappingURL=cleanup-queue.cjs.map

package/dist/cjs/collection/cleanup-queue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-queue.cjs","sources":["../../../src/collection/cleanup-queue.ts"],"sourcesContent":["type CleanupTask = {\n  executeAt: number\n  callback: () => void\n}\n\n/**\n * Batches many GC registrations behind a single shared timeout.\n */\nexport class CleanupQueue {\n  private static instance: CleanupQueue | null = null\n\n  private tasks: Map<unknown, CleanupTask> = new Map()\n\n  private timeoutId: ReturnType<typeof setTimeout> | null = null\n  private microtaskScheduled = false\n\n  private constructor() {}\n\n  public static getInstance(): CleanupQueue {\n    if (!CleanupQueue.instance) {\n      CleanupQueue.instance = new CleanupQueue()\n    }\n    return CleanupQueue.instance\n  }\n\n  /**\n   * Queues a cleanup task and defers timeout selection to a microtask so\n   * multiple synchronous registrations can share one root timer.\n   */\n  public schedule(key: unknown, gcTime: number, callback: () => void): void {\n    const executeAt = Date.now() + gcTime\n    this.tasks.set(key, { executeAt, callback })\n\n    if (!this.microtaskScheduled) {\n      this.microtaskScheduled = true\n      Promise.resolve().then(() => {\n        this.microtaskScheduled = false\n        this.updateTimeout()\n      })\n    }\n  }\n\n  public cancel(key: unknown): void {\n    this.tasks.delete(key)\n  }\n\n  /**\n   * Keeps only one active timeout: whichever task is due next.\n   */\n  private updateTimeout(): void {\n    if (this.timeoutId !== null) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = null\n    }\n\n    if (this.tasks.size === 0) {\n      return\n    }\n\n    let earliestTime = Infinity\n    for (const task of this.tasks.values()) {\n      if (task.executeAt < earliestTime) {\n        earliestTime = task.executeAt\n      }\n    }\n\n    const delay = Math.max(0, earliestTime - Date.now())\n    this.timeoutId = setTimeout(() => this.process(), delay)\n  }\n\n  /**\n   * Runs every task whose deadline has passed, then schedules the next wakeup\n   * if there is still pending work.\n   */\n  private process(): void {\n    this.timeoutId = null\n    const now = Date.now()\n    for (const [key, task] of this.tasks.entries()) {\n      if (now >= task.executeAt) {\n        this.tasks.delete(key)\n        try {\n          task.callback()\n        } catch (error) {\n          console.error('Error in CleanupQueue task:', error)\n        }\n      }\n    }\n\n    if (this.tasks.size > 0) {\n      this.updateTimeout()\n    }\n  }\n\n  /**\n   * Resets the singleton instance for tests.\n   */\n  public static resetInstance(): void {\n    if (CleanupQueue.instance) {\n      if (CleanupQueue.instance.timeoutId !== null) {\n        clearTimeout(CleanupQueue.instance.timeoutId)\n      }\n      CleanupQueue.instance = null\n    }\n  }\n}\n"],"names":[],"mappings":";;AAQO,MAAM,gBAAN,MAAM,cAAa;AAAA,EAQhB,cAAc;AALtB,SAAQ,4BAAuC,IAAA;AAE/C,SAAQ,YAAkD;AAC1D,SAAQ,qBAAqB;AAAA,EAEN;AAAA,EAEvB,OAAc,cAA4B;AACxC,QAAI,CAAC,cAAa,UAAU;AAC1B,oBAAa,WAAW,IAAI,cAAA;AAAA,IAC9B;AACA,WAAO,cAAa;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,SAAS,KAAc,QAAgB,UAA4B;AACxE,UAAM,YAAY,KAAK,IAAA,IAAQ;AAC/B,SAAK,MAAM,IAAI,KAAK,EAAE,WAAW,UAAU;AAE3C,QAAI,CAAC,KAAK,oBAAoB;AAC5B,WAAK,qBAAqB;AAC1B,cAAQ,UAAU,KAAK,MAAM;AAC3B,aAAK,qBAAqB;AAC1B,aAAK,cAAA;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEO,OAAO,KAAoB;AAChC,SAAK,MAAM,OAAO,GAAG;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKQ,gBAAsB;AAC5B,QAAI,KAAK,cAAc,MAAM;AAC3B,mBAAa,KAAK,SAAS;AAC3B,WAAK,YAAY;AAAA,IACnB;AAEA,QAAI,KAAK,MAAM,SAAS,GAAG;AACzB;AAAA,IACF;AAEA,QAAI,eAAe;AACnB,eAAW,QAAQ,KAAK,MAAM,OAAA,GAAU;AACtC,UAAI,KAAK,YAAY,cAAc;AACjC,uBAAe,KAAK;AAAA,MACtB;AAAA,IACF;AAEA,UAAM,QAAQ,KAAK,IAAI,GAAG,eAAe,KAAK,KAAK;AACnD,SAAK,YAAY,WAAW,MAAM,KAAK,QAAA,GAAW,KAAK;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMQ,UAAgB;AACtB,SAAK,YAAY;AACjB,UAAM,MAAM,KAAK,IAAA;AACjB,eAAW,CAAC,KAAK,IAAI,KAAK,KAAK,MAAM,WAAW;AAC9C,UAAI,OAAO,KAAK,WAAW;AACzB,aAAK,MAAM,OAAO,GAAG;AACrB,YAAI;AACF,eAAK,SAAA;AAAA,QACP,SAAS,OAAO;AACd,kBAAQ,MAAM,+BAA+B,KAAK;AAAA,QACpD;AAAA,MACF;AAAA,IACF;AAEA,QAAI,KAAK,MAAM,OAAO,GAAG;AACvB,WAAK,cAAA;AAAA,IACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAc,gBAAsB;AAClC,QAAI,cAAa,UAAU;AACzB,UAAI,cAAa,SAAS,cAAc,MAAM;AAC5C,qBAAa,cAAa,SAAS,SAAS;AAAA,MAC9C;AACA,oBAAa,WAAW;AAAA,IAC1B;AAAA,EACF;AACF;AA/FE,cAAe,WAAgC;AAD1C,IAAM,eAAN;;"}

package/dist/cjs/collection/cleanup-queue.d.cts

@@ -0,0 +1,30 @@
+/**
+ * Batches many GC registrations behind a single shared timeout.
+ */
+export declare class CleanupQueue {
+    private static instance;
+    private tasks;
+    private timeoutId;
+    private microtaskScheduled;
+    private constructor();
+    static getInstance(): CleanupQueue;
+    /**
+     * Queues a cleanup task and defers timeout selection to a microtask so
+     * multiple synchronous registrations can share one root timer.
+     */
+    schedule(key: unknown, gcTime: number, callback: () => void): void;
+    cancel(key: unknown): void;
+    /**
+     * Keeps only one active timeout: whichever task is due next.
+     */
+    private updateTimeout;
+    /**
+     * Runs every task whose deadline has passed, then schedules the next wakeup
+     * if there is still pending work.
+     */
+    private process;
+    /**
+     * Resets the singleton instance for tests.
+     */
+    static resetInstance(): void;
+}

package/dist/cjs/collection/events.cjs

@@ -38,6 +38,20 @@ class CollectionEventsManager extends eventEmitter.EventEmitter {
       subscriberCount
     });
   }
+  emitIndexAdded(index) {
+    this.emit(`index:added`, {
+      type: `index:added`,
+      collection: this.collection,
+      index
+    });
+  }
+  emitIndexRemoved(index) {
+    this.emit(`index:removed`, {
+      type: `index:removed`,
+      collection: this.collection,
+      index
+    });
+  }
   cleanup() {
     this.clearListeners();
   }

package/dist/cjs/collection/events.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.cjs","sources":["../../../src/collection/events.ts"],"sourcesContent":["import { EventEmitter } from '../event-emitter.js'\nimport type { Collection } from './index.js'\nimport type { CollectionStatus } from '../types.js'\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\n/**\n * Event emitted when the collection's loading more state changes\n */\nexport interface CollectionLoadingSubsetChangeEvent {\n  type: `loadingSubset:change`\n  collection: Collection<any, any, any, any, any>\n  isLoadingSubset: boolean\n  previousIsLoadingSubset: boolean\n  loadingSubsetTransition: `start` | `end`\n}\n\n/**\n * Event emitted when the collection is truncated (all data cleared)\n */\nexport interface CollectionTruncateEvent {\n  type: `truncate`\n  collection: Collection<any, any, any, any, any>\n}\n\nexport type AllCollectionEvents = {\n  'status:change': CollectionStatusChangeEvent\n  'subscribers:change': CollectionSubscribersChangeEvent\n  'loadingSubset:change': CollectionLoadingSubsetChangeEvent\n  truncate: CollectionTruncateEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n  | CollectionLoadingSubsetChangeEvent\n  | CollectionTruncateEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T],\n) => void\n\nexport class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {\n  private collection!: Collection<any, any, any, any, any>\n\n  constructor() {\n    super()\n  }\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an event to all listeners\n   * Public API for emitting collection events\n   */\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T],\n  ): void {\n    this.emitInner(event, eventPayload)\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus,\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number,\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  cleanup() {\n    this.clearListeners()\n  }\n}\n"],"names":["EventEmitter"],"mappings":";;;AAyEO,MAAM,gCAAgCA,aAAAA,aAAkC;AAAA,EAG7E,cAAc;AACZ,UAAA;AAAA,EACF;AAAA,EAEA,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KACE,OACA,cACM;AACN,SAAK,UAAU,OAAO,YAAY;AAAA,EACpC;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,eAAA;AAAA,EACP;AACF;;"}
+{"version":3,"file":"events.cjs","sources":["../../../src/collection/events.ts"],"sourcesContent":["import { EventEmitter } from '../event-emitter.js'\nimport type { Collection } from './index.js'\nimport type { CollectionStatus } from '../types.js'\nimport type { BasicExpression } from '../query/ir.js'\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\n/**\n * Event emitted when the collection's loading more state changes\n */\nexport interface CollectionLoadingSubsetChangeEvent {\n  type: `loadingSubset:change`\n  collection: Collection<any, any, any, any, any>\n  isLoadingSubset: boolean\n  previousIsLoadingSubset: boolean\n  loadingSubsetTransition: `start` | `end`\n}\n\n/**\n * Event emitted when the collection is truncated (all data cleared)\n */\nexport interface CollectionTruncateEvent {\n  type: `truncate`\n  collection: Collection<any, any, any, any, any>\n}\n\nexport type CollectionIndexSerializableValue =\n  | string\n  | number\n  | boolean\n  | null\n  | Array<CollectionIndexSerializableValue>\n  | {\n      [key: string]: CollectionIndexSerializableValue\n    }\n\nexport interface CollectionIndexResolverMetadata {\n  kind: `constructor` | `async`\n  name?: string\n}\n\nexport interface CollectionIndexMetadata {\n  /**\n   * Version for the signature serialization contract.\n   */\n  signatureVersion: 1\n  /**\n   * Stable signature derived from expression + serializable options.\n   * Non-serializable option fields are intentionally omitted.\n   */\n  signature: string\n  indexId: number\n  name?: string\n  expression: BasicExpression\n  resolver: CollectionIndexResolverMetadata\n  options?: CollectionIndexSerializableValue\n}\n\nexport interface CollectionIndexAddedEvent {\n  type: `index:added`\n  collection: Collection<any, any, any, any, any>\n  index: CollectionIndexMetadata\n}\n\nexport interface CollectionIndexRemovedEvent {\n  type: `index:removed`\n  collection: Collection<any, any, any, any, any>\n  index: CollectionIndexMetadata\n}\n\nexport type AllCollectionEvents = {\n  'status:change': CollectionStatusChangeEvent\n  'subscribers:change': CollectionSubscribersChangeEvent\n  'loadingSubset:change': CollectionLoadingSubsetChangeEvent\n  truncate: CollectionTruncateEvent\n  'index:added': CollectionIndexAddedEvent\n  'index:removed': CollectionIndexRemovedEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n  | CollectionLoadingSubsetChangeEvent\n  | CollectionTruncateEvent\n  | CollectionIndexAddedEvent\n  | CollectionIndexRemovedEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T],\n) => void\n\nexport class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {\n  private collection!: Collection<any, any, any, any, any>\n\n  constructor() {\n    super()\n  }\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an event to all listeners\n   * Public API for emitting collection events\n   */\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T],\n  ): void {\n    this.emitInner(event, eventPayload)\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus,\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number,\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  emitIndexAdded(index: CollectionIndexMetadata) {\n    this.emit(`index:added`, {\n      type: `index:added`,\n      collection: this.collection,\n      index,\n    })\n  }\n\n  emitIndexRemoved(index: CollectionIndexMetadata) {\n    this.emit(`index:removed`, {\n      type: `index:removed`,\n      collection: this.collection,\n      index,\n    })\n  }\n\n  cleanup() {\n    this.clearListeners()\n  }\n}\n"],"names":["EventEmitter"],"mappings":";;;AA0HO,MAAM,gCAAgCA,aAAAA,aAAkC;AAAA,EAG7E,cAAc;AACZ,UAAA;AAAA,EACF;AAAA,EAEA,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KACE,OACA,cACM;AACN,SAAK,UAAU,OAAO,YAAY;AAAA,EACpC;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,eAAe,OAAgC;AAC7C,SAAK,KAAK,eAAe;AAAA,MACvB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,iBAAiB,OAAgC;AAC/C,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,eAAA;AAAA,EACP;AACF;;"}

package/dist/cjs/collection/events.d.cts

@@ -1,6 +1,7 @@
 import { EventEmitter } from '../event-emitter.js';
 import { Collection } from './index.js';
 import { CollectionStatus } from '../types.js';
+import { BasicExpression } from '../query/ir.js';
 /**
  * Event emitted when the collection status changes
  */
@@ -45,15 +46,50 @@ export interface CollectionTruncateEvent {
     type: `truncate`;
     collection: Collection<any, any, any, any, any>;
 }
+export type CollectionIndexSerializableValue = string | number | boolean | null | Array<CollectionIndexSerializableValue> | {
+    [key: string]: CollectionIndexSerializableValue;
+};
+export interface CollectionIndexResolverMetadata {
+    kind: `constructor` | `async`;
+    name?: string;
+}
+export interface CollectionIndexMetadata {
+    /**
+     * Version for the signature serialization contract.
+     */
+    signatureVersion: 1;
+    /**
+     * Stable signature derived from expression + serializable options.
+     * Non-serializable option fields are intentionally omitted.
+     */
+    signature: string;
+    indexId: number;
+    name?: string;
+    expression: BasicExpression;
+    resolver: CollectionIndexResolverMetadata;
+    options?: CollectionIndexSerializableValue;
+}
+export interface CollectionIndexAddedEvent {
+    type: `index:added`;
+    collection: Collection<any, any, any, any, any>;
+    index: CollectionIndexMetadata;
+}
+export interface CollectionIndexRemovedEvent {
+    type: `index:removed`;
+    collection: Collection<any, any, any, any, any>;
+    index: CollectionIndexMetadata;
+}
 export type AllCollectionEvents = {
     'status:change': CollectionStatusChangeEvent;
     'subscribers:change': CollectionSubscribersChangeEvent;
     'loadingSubset:change': CollectionLoadingSubsetChangeEvent;
     truncate: CollectionTruncateEvent;
+    'index:added': CollectionIndexAddedEvent;
+    'index:removed': CollectionIndexRemovedEvent;
 } & {
     [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>;
 };
-export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent | CollectionLoadingSubsetChangeEvent | CollectionTruncateEvent;
+export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent | CollectionLoadingSubsetChangeEvent | CollectionTruncateEvent | CollectionIndexAddedEvent | CollectionIndexRemovedEvent;
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (event: AllCollectionEvents[T]) => void;
 export declare class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
     private collection;
@@ -68,5 +104,7 @@ export declare class CollectionEventsManager extends EventEmitter<AllCollectionE
     emit<T extends keyof AllCollectionEvents>(event: T, eventPayload: AllCollectionEvents[T]): void;
     emitStatusChange<T extends CollectionStatus>(status: T, previousStatus: CollectionStatus): void;
     emitSubscribersChange(subscriberCount: number, previousSubscriberCount: number): void;
+    emitIndexAdded(index: CollectionIndexMetadata): void;
+    emitIndexRemoved(index: CollectionIndexMetadata): void;
     cleanup(): void;
 }