Class BaseQueryBuilder

packages/db/src/query/builder/index.ts:78–943

const UNION_ALL_SOURCE_CONTEXT = `unionAll clause` satisfies SourceClauseContext

export class BaseQueryBuilder<TContext extends Context = Context> {
  private readonly query: Partial<QueryIR> = {}

  constructor(query: Partial<QueryIR> = {}) {
    this.query = { ...query }
  }

  /**
   * Creates a CollectionRef or QueryRef from a source object
   * @param source - An object with a single key-value pair
   * @param context - Context string for error messages (e.g., "from clause", "join clause")
   * @returns A tuple of [alias, ref] where alias is the source key and ref is the created reference
   */
  private _createRefForSource<TSource extends Source>(
    source: TSource,
    context: SourceClauseContext,
  ): [string, CollectionRef | QueryRef] {
    const refs = this._createRefsForSource(source, context)
    if (refs.length !== 1) {
      throw new OnlyOneSourceAllowedError(context)
    }
    return refs[0]!
  }

  private _createRefsForSource<TSource extends Source>(
    source: TSource,
    context: SourceClauseContext,
  ): Array<[string, CollectionRef | QueryRef]> {
    if (typeof source === `string`) {
      throw new InvalidSourceTypeError(context, `string`)
    }

    // Validate source is a plain object (not null, array, string, etc.)
    // We use try-catch to handle null/undefined gracefully
    let keys: Array<string>
    try {
      keys = Object.keys(source)
    } catch {
      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
      const type = source === null ? `null` : `undefined`
      throw new InvalidSourceTypeError(context, type)
    }

    // Check if it's an array (arrays pass Object.keys but aren't valid sources)
    if (Array.isArray(source)) {
      throw new InvalidSourceTypeError(context, `array`)
    }

    if (keys.length === 0) {
      throw new InvalidSourceTypeError(context, `empty object`)
    }

    if (context !== UNION_ALL_SOURCE_CONTEXT && keys.length !== 1) {
      throw new OnlyOneSourceAllowedError(context)
    }

    const refs: Array<[string, CollectionRef | QueryRef]> = []
    for (const alias of keys) {