@tanstack/db 0.5.32 → 0.6.0

package/src/indexes/index-registry.ts

@@ -0,0 +1,174 @@
+/**
+ * Index Dev Mode - Helps developers identify when indexes would improve performance
+ *
+ * Dev mode suggestions are ON by default in non-production builds.
+ */
+
+// Dev mode detection settings - ON by default in non-production
+let devModeConfig: IndexDevModeConfig = {
+  enabled: true,
+  collectionSizeThreshold: 1000,
+  slowQueryThresholdMs: 10,
+  onSuggestion: null,
+}
+
+export interface IndexDevModeConfig {
+  /** Enable dev mode index suggestions */
+  enabled: boolean
+  /** Suggest indexes when collection has more than this many items */
+  collectionSizeThreshold: number
+  /** Suggest indexes when queries take longer than this (ms) */
+  slowQueryThresholdMs: number
+  /** Custom handler for index suggestions */
+  onSuggestion: ((suggestion: IndexSuggestion) => void) | null
+}
+
+export interface IndexSuggestion {
+  type: `collection-size` | `slow-query` | `frequent-field`
+  collectionId: string
+  fieldPath: Array<string>
+  message: string
+  collectionSize?: number
+  queryTimeMs?: number
+  queryCount?: number
+}
+
+// Track query patterns for dev mode
+const queryPatterns = new Map<
+  string,
+  {
+    fieldPath: Array<string>
+    queryCount: number
+    totalTimeMs: number
+    avgTimeMs: number
+  }
+>()
+
+/**
+ * Configure dev mode for index suggestions
+ */
+export function configureIndexDevMode(
+  config: Partial<IndexDevModeConfig>,
+): void {
+  devModeConfig = { ...devModeConfig, ...config }
+}
+
+/**
+ * Get current dev mode configuration
+ */
+export function getIndexDevModeConfig(): IndexDevModeConfig {
+  return devModeConfig
+}
+
+/**
+ * Check if dev mode is enabled
+ */
+export function isDevModeEnabled(): boolean {
+  return devModeConfig.enabled && process.env.NODE_ENV !== `production`
+}
+
+/**
+ * Emit an index suggestion (dev mode only)
+ */
+export function emitIndexSuggestion(suggestion: IndexSuggestion): void {
+  if (!isDevModeEnabled()) return
+
+  if (devModeConfig.onSuggestion) {
+    try {
+      devModeConfig.onSuggestion(suggestion)
+    } catch {
+      // Don't let a buggy callback crash query execution
+    }
+  } else {
+    // Default: log to console with helpful formatting
+    console.warn(
+      `[TanStack DB] Index suggestion for "${suggestion.collectionId}":\n` +
+        `  ${suggestion.message}\n` +
+        `  Field: ${suggestion.fieldPath.join(`.`)}\n` +
+        `  Add index: collection.createIndex((row) => row.${suggestion.fieldPath.join(`.`)})`,
+    )
+  }
+}
+
+/**
+ * Track a query for dev mode analysis
+ */
+export function trackQuery(
+  collectionId: string,
+  fieldPath: Array<string>,
+  executionTimeMs: number,
+): void {
+  if (!isDevModeEnabled()) return
+
+  const key = `${collectionId}:${fieldPath.join(`.`)}`
+  const existing = queryPatterns.get(key)
+
+  if (existing) {
+    existing.queryCount++
+    existing.totalTimeMs += executionTimeMs
+    existing.avgTimeMs = existing.totalTimeMs / existing.queryCount
+  } else {
+    queryPatterns.set(key, {
+      fieldPath,
+      queryCount: 1,
+      totalTimeMs: executionTimeMs,
+      avgTimeMs: executionTimeMs,
+    })
+  }
+
+  // Check if we should suggest an index
+  const pattern = queryPatterns.get(key)!
+  if (pattern.avgTimeMs > devModeConfig.slowQueryThresholdMs) {
+    emitIndexSuggestion({
+      type: `slow-query`,
+      collectionId,
+      fieldPath,
+      message: `Queries on "${fieldPath.join(`.`)}" are slow (avg ${pattern.avgTimeMs.toFixed(1)}ms). Consider adding an index.`,
+      queryTimeMs: pattern.avgTimeMs,
+      queryCount: pattern.queryCount,
+    })
+  }
+}
+
+/**
+ * Check collection size and suggest index if needed (dev mode)
+ */
+export function checkCollectionSizeForIndex(
+  collectionId: string,
+  collectionSize: number,
+  fieldPath: Array<string>,
+): void {
+  if (!isDevModeEnabled()) return
+
+  if (collectionSize > devModeConfig.collectionSizeThreshold) {
+    emitIndexSuggestion({
+      type: `collection-size`,
+      collectionId,
+      fieldPath,
+      message: `Collection has ${collectionSize} items. Queries on "${fieldPath.join(`.`)}" may benefit from an index.`,
+      collectionSize,
+    })
+  }
+}
+
+/**
+ * Clear query pattern tracking (useful for tests)
+ */
+export function clearQueryPatterns(): void {
+  queryPatterns.clear()
+}
+
+/**
+ * Get query patterns (useful for debugging/testing)
+ */
+export function getQueryPatterns(): Map<
+  string,
+  {
+    fieldPath: Array<string>
+    queryCount: number
+    totalTimeMs: number
+    avgTimeMs: number
+  }
+> {
+  return new Map(queryPatterns)
+}

package/src/local-only.ts

@@ -314,9 +314,16 @@ function createLocalOnlySync<T extends object, TKey extends string | number>(
       syncWrite = write
       syncCommit = commit
       collection = params.collection
+      params.collection._state.isLocalOnly = true
 
       // Apply initial data if provided
       if (initialData && initialData.length > 0) {
+        // Mark initial data as local so $origin is 'local' for local-only collections
+        for (const item of initialData) {
+          const key = params.collection.getKeyFromItem(item)
+          params.collection._state.pendingLocalChanges.add(key)
+        }
+
         begin()
         initialData.forEach((item) => {
           write({

package/src/query/builder/functions.ts

@@ -2,7 +2,13 @@ import { Aggregate, Func } from '../ir'
 import { toExpression } from './ref-proxy.js'
 import type { BasicExpression } from '../ir'
 import type { RefProxy } from './ref-proxy.js'
-import type { RefLeaf } from './types.js'
+import type {
+  Context,
+  GetRawResult,
+  RefLeaf,
+  StringifiableScalar,
+} from './types.js'
+import type { QueryBuilder } from './index.js'
 
 type StringRef =
   | RefLeaf<string>
@@ -37,8 +43,20 @@ type ComparisonOperandPrimitive<T extends string | number | boolean> =
   | undefined
   | null
 
-// Helper type for any expression-like value
-type ExpressionLike = BasicExpression | RefProxy<any> | RefLeaf<any> | any
+// Helper type for values that can be lowered to expressions.
+type ExpressionLike =
+  | Aggregate
+  | BasicExpression
+  | RefProxy<any>
+  | RefLeaf<any>
+  | string
+  | number
+  | boolean
+  | bigint
+  | Date
+  | null
+  | undefined
+  | Array<unknown>
 
 // Helper type to extract the underlying type from various expression types
 type ExtractType<T> =
@@ -276,20 +294,61 @@ export function length<T extends ExpressionLike>(
   return new Func(`length`, [toExpression(arg)]) as NumericFunctionReturnType<T>
 }
 
+export function concat<T extends StringifiableScalar>(
+  arg: ToArrayWrapper<T>,
+): ConcatToArrayWrapper<T>
+export function concat(...args: Array<ExpressionLike>): BasicExpression<string>
 export function concat(
-  ...args: Array<ExpressionLike>
-): BasicExpression<string> {
+  ...args: Array<ExpressionLike | ToArrayWrapper<any>>
+): BasicExpression<string> | ConcatToArrayWrapper<any> {
+  const toArrayArg = args.find(
+    (arg): arg is ToArrayWrapper<any> => arg instanceof ToArrayWrapper,
+  )
+
+  if (toArrayArg) {
+    if (args.length !== 1) {
+      throw new Error(
+        `concat(toArray(...)) currently supports only a single toArray(...) argument`,
+      )
+    }
+    return new ConcatToArrayWrapper(toArrayArg.query)
+  }
+
   return new Func(
     `concat`,
     args.map((arg) => toExpression(arg)),
   )
 }
 
-export function coalesce(...args: Array<ExpressionLike>): BasicExpression<any> {
+// Helper type for coalesce: extracts non-nullish value types from all args
+type CoalesceArgTypes<T extends Array<ExpressionLike>> = {
+  [K in keyof T]: NonNullable<ExtractType<T[K]>>
+}[number]
+
+// Whether any arg in the tuple is statically guaranteed non-null (i.e., does not include null | undefined)
+type HasGuaranteedNonNull<T extends Array<ExpressionLike>> = {
+  [K in keyof T]: null extends ExtractType<T[K]>
+    ? false
+    : undefined extends ExtractType<T[K]>
+      ? false
+      : true
+}[number] extends false
+  ? false
+  : true
+
+// coalesce() return type: union of all non-null arg types; null included unless a guaranteed non-null arg exists
+type CoalesceReturnType<T extends Array<ExpressionLike>> =
+  HasGuaranteedNonNull<T> extends true
+    ? BasicExpression<CoalesceArgTypes<T>>
+    : BasicExpression<CoalesceArgTypes<T> | null>
+
+export function coalesce<T extends [ExpressionLike, ...Array<ExpressionLike>]>(
+  ...args: T
+): CoalesceReturnType<T> {
   return new Func(
     `coalesce`,
     args.map((arg) => toExpression(arg)),
-  )
+  ) as CoalesceReturnType<T>
 }
 
 export function add<T1 extends ExpressionLike, T2 extends ExpressionLike>(
@@ -376,3 +435,21 @@ export const operators = [
 ] as const
 
 export type OperatorName = (typeof operators)[number]
+
+export class ToArrayWrapper<_T = unknown> {
+  declare readonly _type: `toArray`
+  declare readonly _result: _T
+  constructor(public readonly query: QueryBuilder<any>) {}
+}
+
+export class ConcatToArrayWrapper<_T = unknown> {
+  declare readonly _type: `concatToArray`
+  declare readonly _result: _T
+  constructor(public readonly query: QueryBuilder<any>) {}
+}
+
+export function toArray<TContext extends Context>(
+  query: QueryBuilder<TContext>,
+): ToArrayWrapper<GetRawResult<TContext>> {
+  return new ToArrayWrapper(query)
+}