@tanstack/db 0.0.14 → 0.0.16

package/src/query/builder/ref-proxy.ts

@@ -0,0 +1,156 @@
+import { PropRef, Value } from "../ir.js"
+import type { BasicExpression } from "../ir.js"
+
+export interface RefProxy<T = any> {
+  /** @internal */
+  readonly __refProxy: true
+  /** @internal */
+  readonly __path: Array<string>
+  /** @internal */
+  readonly __type: T
+}
+
+/**
+ * Creates a proxy object that records property access paths
+ * Used in callbacks like where, select, etc. to create type-safe references
+ */
+export function createRefProxy<T extends Record<string, any>>(
+  aliases: Array<string>
+): RefProxy<T> & T {
+  const cache = new Map<string, any>()
+  const spreadSentinels = new Set<string>() // Track which aliases have been spread
+
+  function createProxy(path: Array<string>): any {
+    const pathKey = path.join(`.`)
+    if (cache.has(pathKey)) {
+      return cache.get(pathKey)
+    }
+
+    const proxy = new Proxy({} as any, {
+      get(target, prop, receiver) {
+        if (prop === `__refProxy`) return true
+        if (prop === `__path`) return path
+        if (prop === `__type`) return undefined // Type is only for TypeScript inference
+        if (typeof prop === `symbol`) return Reflect.get(target, prop, receiver)
+
+        const newPath = [...path, String(prop)]
+        return createProxy(newPath)
+      },
+
+      has(target, prop) {
+        if (prop === `__refProxy` || prop === `__path` || prop === `__type`)
+          return true
+        return Reflect.has(target, prop)
+      },
+
+      ownKeys(target) {
+        // If this is a table-level proxy (path length 1), mark it as spread
+        if (path.length === 1) {
+          const aliasName = path[0]!
+          spreadSentinels.add(aliasName)
+        }
+        return Reflect.ownKeys(target)
+      },
+
+      getOwnPropertyDescriptor(target, prop) {
+        if (prop === `__refProxy` || prop === `__path` || prop === `__type`) {
+          return { enumerable: false, configurable: true }
+        }
+        return Reflect.getOwnPropertyDescriptor(target, prop)
+      },
+    })
+
+    cache.set(pathKey, proxy)
+    return proxy
+  }
+
+  // Create the root proxy with all aliases as top-level properties
+  const rootProxy = new Proxy({} as any, {
+    get(target, prop, receiver) {
+      if (prop === `__refProxy`) return true
+      if (prop === `__path`) return []
+      if (prop === `__type`) return undefined // Type is only for TypeScript inference
+      if (prop === `__spreadSentinels`) return spreadSentinels // Expose spread sentinels
+      if (typeof prop === `symbol`) return Reflect.get(target, prop, receiver)
+
+      const propStr = String(prop)
+      if (aliases.includes(propStr)) {
+        return createProxy([propStr])
+      }
+
+      return undefined
+    },
+
+    has(target, prop) {
+      if (
+        prop === `__refProxy` ||
+        prop === `__path` ||
+        prop === `__type` ||
+        prop === `__spreadSentinels`
+      )
+        return true
+      if (typeof prop === `string` && aliases.includes(prop)) return true
+      return Reflect.has(target, prop)
+    },
+
+    ownKeys(_target) {
+      return [...aliases, `__refProxy`, `__path`, `__type`, `__spreadSentinels`]
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      if (
+        prop === `__refProxy` ||
+        prop === `__path` ||
+        prop === `__type` ||
+        prop === `__spreadSentinels`
+      ) {
+        return { enumerable: false, configurable: true }
+      }
+      if (typeof prop === `string` && aliases.includes(prop)) {
+        return { enumerable: true, configurable: true }
+      }
+      return undefined
+    },
+  })
+
+  return rootProxy
+}
+
+/**
+ * Converts a value to an Expression
+ * If it's a RefProxy, creates a Ref, otherwise creates a Value
+ */
+export function toExpression<T = any>(value: T): BasicExpression<T>
+export function toExpression(value: RefProxy<any>): BasicExpression<any>
+export function toExpression(value: any): BasicExpression<any> {
+  if (isRefProxy(value)) {
+    return new PropRef(value.__path)
+  }
+  // If it's already an Expression (Func, Ref, Value) or Agg, return it directly
+  if (
+    value &&
+    typeof value === `object` &&
+    `type` in value &&
+    (value.type === `func` ||
+      value.type === `ref` ||
+      value.type === `val` ||
+      value.type === `agg`)
+  ) {
+    return value
+  }
+  return new Value(value)
+}
+
+/**
+ * Type guard to check if a value is a RefProxy
+ */
+export function isRefProxy(value: any): value is RefProxy {
+  return value && typeof value === `object` && value.__refProxy === true
+}
+
+/**
+ * Helper to create a Value expression from a literal
+ */
+export function val<T>(value: T): BasicExpression<T> {
+  return new Value(value)
+}

package/src/query/builder/types.ts

@@ -0,0 +1,282 @@
+import type { CollectionImpl } from "../../collection.js"
+import type { Aggregate, BasicExpression } from "../ir.js"
+import type { QueryBuilder } from "./index.js"
+
+export interface Context {
+  // The collections available in the base schema
+  baseSchema: ContextSchema
+  // The current schema available (includes joined collections)
+  schema: ContextSchema
+  // the name of the source that was used in the from clause
+  fromSourceName: string
+  // Whether this query has joins
+  hasJoins?: boolean
+  // Mapping of table alias to join type for easy lookup
+  joinTypes?: Record<
+    string,
+    `inner` | `left` | `right` | `full` | `outer` | `cross`
+  >
+  // The result type after select (if select has been called)
+  result?: any
+}
+
+export type ContextSchema = Record<string, unknown>
+
+export type Source = {
+  [alias: string]: CollectionImpl<any, any> | QueryBuilder<Context>
+}
+
+// Helper type to infer collection type from CollectionImpl
+export type InferCollectionType<T> =
+  T extends CollectionImpl<infer U> ? U : never
+
+// Helper type to create schema from source
+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
+}>
+
+// Helper type to get all aliases from a context
+export type GetAliases<TContext extends Context> = keyof TContext[`schema`]
+
+// Callback type for where/having clauses
+export type WhereCallback<TContext extends Context> = (
+  refs: RefProxyForContext<TContext>
+) => any
+
+// Callback return type for select clauses
+export type SelectObject<
+  T extends Record<
+    string,
+    BasicExpression | Aggregate | RefProxy | RefProxyFor<any>
+  > = Record<string, BasicExpression | Aggregate | RefProxy | RefProxyFor<any>>,
+> = T
+
+// Helper type to get the result type from a select object
+export type ResultTypeFromSelect<TSelectObject> = {
+  [K in keyof TSelectObject]: TSelectObject[K] extends RefProxy<infer T>
+    ? // For RefProxy, preserve the type as-is (including optionality from joins)
+      T
+    : TSelectObject[K] extends BasicExpression<infer T>
+      ? T
+      : TSelectObject[K] extends Aggregate<infer T>
+        ? T
+        : TSelectObject[K] extends RefProxyFor<infer T>
+          ? // For RefProxyFor, preserve the type as-is (including optionality from joins)
+            T
+          : never
+}
+
+// Callback type for orderBy clauses
+export type OrderByCallback<TContext extends Context> = (
+  refs: RefProxyForContext<TContext>
+) => any
+
+// Callback type for groupBy clauses
+export type GroupByCallback<TContext extends Context> = (
+  refs: RefProxyForContext<TContext>
+) => any
+
+// Callback type for join on clauses
+export type JoinOnCallback<TContext extends Context> = (
+  refs: RefProxyForContext<TContext>
+) => any
+
+// Type for creating RefProxy objects based on context
+export type RefProxyForContext<TContext extends Context> = {
+  [K in keyof TContext[`schema`]]: RefProxyFor<TContext[`schema`][K]>
+}
+
+// Helper type to check if T is exactly undefined
+type IsExactlyUndefined<T> = [T] extends [undefined] ? true : false
+
+// Helper type to check if T includes undefined (is optional)
+type IsOptional<T> = undefined extends T ? true : false
+
+// Helper type to extract non-undefined type
+type NonUndefined<T> = T extends undefined ? never : T
+
+// Helper type to create RefProxy for a specific type with optionality passthrough
+// This is used to create the RefProxy object that is used in the query builder.
+// Much of the complexity here is due to the fact that we need to handle optionality
+// from joins. A left join will make the joined table optional, a right join will make
+// the main table optional etc. This is applied to the schema, with the new namespaced
+// source being `SourceType | undefined`.
+// We then follow this through the ref proxy system so that accessing a property on
+// and optional source will itsself be optional.
+// If for example we join in `joinedTable` with a left join, then
+// `where(({ joinedTable }) => joinedTable.name === `John`)`
+// we want the the type of `name` to be `RefProxy<string | undefined>` to indicate that
+// the `name` property is optional, as the joinedTable is also optional.
+export type RefProxyFor<T> = OmitRefProxy<
+  IsExactlyUndefined<T> extends true
+    ? // T is exactly undefined
+      RefProxy<T>
+    : IsOptional<T> extends true
+      ? // T is optional (T | undefined) but not exactly undefined
+        NonUndefined<T> extends Record<string, any>
+        ? {
+            // Properties are accessible and their types become optional
+            [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>
+          } & RefProxy<T>
+        : RefProxy<T>
+      : // T is not optional
+        T extends Record<string, any>
+        ? {
+            [K in keyof T]: T[K] extends Record<string, any>
+              ? RefProxyFor<T[K]> & RefProxy<T[K]>
+              : RefProxy<T[K]>
+          } & RefProxy<T>
+        : RefProxy<T>
+>
+
+// This is the public type that is exported from the query builder
+// and is used when constructing reusable query callbacks.
+export type Ref<T> = RefProxyFor<T>
+
+type OmitRefProxy<T> = Omit<T, `__refProxy` | `__path` | `__type`>
+
+// The core RefProxy interface
+export interface RefProxy<T = any> {
+  /** @internal */
+  readonly __refProxy: true
+  /** @internal */
+  readonly __path: Array<string>
+  /** @internal */
+  readonly __type: T
+}
+
+// Helper type to apply join optionality immediately when merging contexts
+export type MergeContextWithJoinType<
+  TContext extends Context,
+  TNewSchema extends ContextSchema,
+  TJoinType extends `inner` | `left` | `right` | `full` | `outer` | `cross`,
+> = {
+  baseSchema: TContext[`baseSchema`]
+  // Apply optionality immediately to the schema
+  schema: ApplyJoinOptionalityToMergedSchema<
+    TContext[`schema`],
+    TNewSchema,
+    TJoinType,
+    TContext[`fromSourceName`]
+  >
+  fromSourceName: TContext[`fromSourceName`]
+  hasJoins: true
+  // Track join types for reference
+  joinTypes: (TContext[`joinTypes`] extends Record<string, any>
+    ? TContext[`joinTypes`]
+    : {}) & {
+    [K in keyof TNewSchema & string]: TJoinType
+  }
+  result: TContext[`result`]
+}
+
+// Helper type to apply join optionality when merging new schema
+export type ApplyJoinOptionalityToMergedSchema<
+  TExistingSchema extends ContextSchema,
+  TNewSchema extends ContextSchema,
+  TJoinType extends `inner` | `left` | `right` | `full` | `outer` | `cross`,
+  TFromSourceName extends string,
+> = {
+  // Apply optionality to existing schema based on new join type
+  [K in keyof TExistingSchema]: K extends TFromSourceName
+    ? // Main table becomes optional if the new join is a right or full join
+      TJoinType extends `right` | `full`
+      ? TExistingSchema[K] | undefined
+      : TExistingSchema[K]
+    : // Other tables remain as they are (already have their optionality applied)
+      TExistingSchema[K]
+} & {
+  // Apply optionality to new schema based on join type
+  [K in keyof TNewSchema]: TJoinType extends `left` | `full`
+    ? // New table becomes optional for left and full joins
+      TNewSchema[K] | undefined
+    : // New table is required for inner and right joins
+      TNewSchema[K]
+}
+
+// Helper type to get the result type from a context
+export type GetResult<TContext extends Context> = Prettify<
+  TContext[`result`] extends object
+    ? TContext[`result`]
+    : TContext[`hasJoins`] extends true
+      ? // Optionality is already applied in the schema, just return it
+        TContext[`schema`]
+      : // Single table query - return the specific table
+        TContext[`schema`][TContext[`fromSourceName`]]
+>
+
+// Helper type to apply join optionality to the schema based on joinTypes
+export type ApplyJoinOptionalityToSchema<
+  TSchema extends ContextSchema,
+  TJoinTypes extends Record<string, string>,
+  TFromSourceName extends string,
+> = {
+  [K in keyof TSchema]: K extends TFromSourceName
+    ? // Main table (from source) - becomes optional if ANY right or full join exists
+      HasJoinType<TJoinTypes, `right` | `full`> extends true
+      ? TSchema[K] | undefined
+      : TSchema[K]
+    : // Joined table - check its specific join type AND if it's affected by subsequent joins
+      K extends keyof TJoinTypes
+      ? TJoinTypes[K] extends `left` | `full`
+        ? TSchema[K] | undefined
+        : // For inner/right joins, check if this table becomes optional due to subsequent right/full joins
+          // that don't include this table
+          IsTableMadeOptionalBySubsequentJoins<
+              K,
+              TJoinTypes,
+              TFromSourceName
+            > extends true
+          ? TSchema[K] | undefined
+          : TSchema[K]
+      : TSchema[K]
+}
+
+// Helper type to check if a table becomes optional due to subsequent joins
+type IsTableMadeOptionalBySubsequentJoins<
+  TTableAlias extends string | number | symbol,
+  TJoinTypes extends Record<string, string>,
+  TFromSourceName extends string,
+> = TTableAlias extends TFromSourceName
+  ? // Main table becomes optional if there are any right or full joins
+    HasJoinType<TJoinTypes, `right` | `full`>
+  : // Joined tables are not affected by subsequent joins in our current implementation
+    false
+
+// Helper type to check if any join has one of the specified types
+export type HasJoinType<
+  TJoinTypes extends Record<string, string>,
+  TTargetTypes extends string,
+> = true extends {
+  [K in keyof TJoinTypes]: TJoinTypes[K] extends TTargetTypes ? true : false
+}[keyof TJoinTypes]
+  ? true
+  : false
+
+// Helper type to merge contexts (for joins) - backward compatibility
+export type MergeContext<
+  TContext extends Context,
+  TNewSchema extends ContextSchema,
+> = MergeContextWithJoinType<TContext, TNewSchema, `left`>
+
+// Helper type for updating context with result type
+export type WithResult<TContext extends Context, TResult> = Prettify<
+  Omit<TContext, `result`> & {
+    result: Prettify<TResult>
+  }
+>
+
+// Helper type to simplify complex types for better editor hints
+export type Prettify<T> = {
+  [K in keyof T]: T[K]
+} & {}