Order of method calls matters for `orderBy`.

[thruflo]

To order by multiple columns, you currently make multiple orderBy calls. As per https://tanstack.com/db/latest/docs/live-queries#multiple-column-ordering

const sortedUsers = createLiveQueryCollection((q) =>
  q
    .from({ user: usersCollection })
    .orderBy(({ user }) => user.departmentId, 'asc')
    .orderBy(({ user }) => user.name, 'asc')
)

However, in the intro https://tanstack.com/db/latest/docs/live-queries#tanstack-db-live-queries the blurb says:

The query builder doesn't perform operations in the order of method calls - instead, it composes your query into an optimal incremental pipeline that gets compiled and executed efficiently

I assume that in the case of orderBy calls, the order of the function call is preserved and used by the query builder. However this jumped out as a possible source of confusion / inconsistency.

Could we consider (a) orderBy supporting an array of OrderByOptions? Or (b) perhaps an explicit note in the docs (maybe "except for orderBy" in the preamble blurb and an info/note in the orderBy section to state that order matters for orderBy method calls?

[samwillis]

Yes, order of orderBy calls is preserved. We should document this.

I considered having it take an array of options, but wasn't sold so left as is for now. Very happy to reconsider.

[kevin-dp]

It might be better to keep it as is and document it because this allows developers to define a base query with an orderBy clause, assign it to a variable, and then extend it with an additional orderBy clause. That wouldn't be possible if we're expecting a single orderBy that passes an array, or the 2nd orderBy would be overriding the first one but the DX of that doesn't seem optimal.