Method orderBy

packages/db/src/query/builder/index.ts:629–675

* Sort the query results by one or more columns * * @param callback - A function that receives table references and returns the field to sort by * @param direction - Sort direction: 'asc' for ascending, 'desc' for descending (defaults to 'asc') * @returns A QueryBuilder with the ordering

(
    callback: OrderByCallback<TContext>,
    options: OrderByDirection | OrderByOptions = `asc`,
  )

   * ```
   */
  orderBy(
    callback: OrderByCallback<TContext>,
    options: OrderByDirection | OrderByOptions = `asc`,
  ): QueryBuilder<TContext> {
    const aliases = this._getCurrentAliases()
    // Add $selected namespace if SELECT clause exists (either regular or functional)
    const refProxy = (
      this.query.select || this.query.fnSelect
        ? createRefProxyWithSelected(aliases)
        : createRefProxy(aliases)
    ) as RefsForContext<TContext>
    const result = callback(refProxy)

    const opts: CompareOptions =
      typeof options === `string`
        ? { direction: options, nulls: `first` }
        : {
            direction: options.direction ?? `asc`,
            nulls: options.nulls ?? `first`,
            stringSort: options.stringSort,
            locale:
              options.stringSort === `locale` ? options.locale : undefined,
            localeOptions:
              options.stringSort === `locale`
                ? options.localeOptions
                : undefined,
          }

    const makeOrderByClause = (res: any) => {
      return {
        expression: toExpression(res),
        compareOptions: opts,
      }
    }

    // Create the new OrderBy structure with expression and direction
    const orderByClauses = Array.isArray(result)
      ? result.map((r) => makeOrderByClause(r))
      : [makeOrderByClause(result)]

    const existingOrderBy: OrderBy = this.query.orderBy || []

    return new BaseQueryBuilder({
      ...this.query,
      orderBy: [...existingOrderBy, ...orderByClauses],
    }) as any
  }

  /**
   * Group rows by one or more columns for aggregation