Configuration options for sortBy #314

kevin-dp · 2025-07-24T07:31:01Z

Fixes #212 and fixes #229 by adding a configuration argument to orderBy:

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

type OrderByOptions = {
  direction?: OrderByDirection
  nulls?: `first` | `last`
} & StringSortOpts

type StringSortOpts =
  | {
      stringSort?: `lexical`
    }
  | {
      stringSort?: `locale`
      locale?: string
      localeOptions?: object
    }

changeset-bot · 2025-07-24T07:31:04Z

🦋 Changeset detected

Latest commit: 18b597a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@tanstack/db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/react-db	Patch
@tanstack/solid-db	Patch
@tanstack/svelte-db	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
@tanstack/db-example-react-todo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-07-24T07:32:04Z

@tanstack/db-example-react-todo • @tanstack/db-example-solid-todo

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@314

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@314

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@314

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@314

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@314

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@314

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@314

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@314

commit: 18b597a

github-actions · 2025-07-24T07:34:06Z

Size Change: +277 B (+0.48%)

Total Size: 58.4 kB

Filename	Size	Change
`./packages/db/dist/esm/indexes/btree-index.js`	1.47 kB	+1 B (+0.07%)
`./packages/db/dist/esm/query/builder/index.js`	3.79 kB	+122 B (+3.33%)
`./packages/db/dist/esm/query/compiler/order-by.js`	680 B	-25 B (-3.55%)
`./packages/db/dist/esm/utils/comparison.js`	718 B	+179 B (+33.21%)	🚨

ℹ️ View Unchanged

Filename	Size
`./packages/db/dist/esm/change-events.js`	1.13 kB
`./packages/db/dist/esm/collection.js`	9.8 kB
`./packages/db/dist/esm/deferred.js`	230 B
`./packages/db/dist/esm/errors.js`	2.98 kB
`./packages/db/dist/esm/index.js`	1.51 kB
`./packages/db/dist/esm/indexes/auto-index.js`	689 B
`./packages/db/dist/esm/indexes/base-index.js`	605 B
`./packages/db/dist/esm/indexes/lazy-index.js`	1.25 kB
`./packages/db/dist/esm/local-only.js`	827 B
`./packages/db/dist/esm/local-storage.js`	2.03 kB
`./packages/db/dist/esm/optimistic-action.js`	294 B
`./packages/db/dist/esm/proxy.js`	4.19 kB
`./packages/db/dist/esm/query/builder/functions.js`	575 B
`./packages/db/dist/esm/query/builder/ref-proxy.js`	890 B
`./packages/db/dist/esm/query/compiler/evaluators.js`	1.48 kB
`./packages/db/dist/esm/query/compiler/expressions.js`	631 B
`./packages/db/dist/esm/query/compiler/group-by.js`	2.04 kB
`./packages/db/dist/esm/query/compiler/index.js`	1.74 kB
`./packages/db/dist/esm/query/compiler/joins.js`	1.56 kB
`./packages/db/dist/esm/query/compiler/select.js`	657 B
`./packages/db/dist/esm/query/ir.js`	318 B
`./packages/db/dist/esm/query/live-query-collection.js`	2.45 kB
`./packages/db/dist/esm/query/optimizer.js`	2.44 kB
`./packages/db/dist/esm/SortedMap.js`	1.24 kB
`./packages/db/dist/esm/transactions.js`	2.28 kB
`./packages/db/dist/esm/utils.js`	419 B
`./packages/db/dist/esm/utils/btree.js`	5.93 kB
`./packages/db/dist/esm/utils/index-optimization.js`	1.62 kB

_{compressed-size-action::db-package-size}

github-actions · 2025-07-24T07:34:54Z

Size Change: 0 B

Total Size: 1.05 kB

ℹ️ View Unchanged

Filename	Size
`./packages/react-db/dist/esm/index.js`	152 B
`./packages/react-db/dist/esm/useLiveQuery.js`	902 B

_{compressed-size-action::react-db-package-size}

asabil · 2025-07-24T11:14:23Z

Would it make sense to mimic PostgreSQL's default ordering?

By default, null values sort as if larger than any non-null value; that is, NULLS FIRST is the default for DESC order, and NULLS LAST otherwise.

kevin-dp · 2025-07-24T11:25:09Z

Would it make sense to mimic PostgreSQL's default ordering?

By default, null values sort as if larger than any non-null value; that is, NULLS FIRST is the default for DESC order, and NULLS LAST otherwise.

I have been thinking about this. I didn't do that because that would be a breaking change, but we could certainly do that if we want. @KyleAMathews @samwillis any opinions on this?

samwillis · 2025-07-24T12:29:19Z

On the api design, I'm tempted to not add it as a third arg, but make the second arg either a string for direction, or an object for extended options:

interface OrderByOptions {
  direction: OrderByDirection = `asc`
  nulls: `first` | `last` = `first`
}

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

This makes it much more clear what the options are, and makes it mush easer to extend to option in future if we want to.

@kevin-dp what do you think?

kevin-dp · 2025-07-24T12:57:25Z

@samwillis agreed. Cleaner with a configuration object. I'm not sure about the union type OrderByDirection | OrderByOptions though. It's probably fine because most of the time one would only specify asc/desc order without specifying for nulls?

KyleAMathews · 2025-07-24T13:34:08Z

Yeah I like avoiding a third arg too. Union seems fine to me as yeah, 99% of time people will just specify the direction.

thruflo

LGTM, thanks 🙏

packages/db/src/query/builder/index.ts

thruflo · 2025-07-24T17:41:40Z

N.b.: docs https://tanstack.com/db/latest/docs/live-queries#order-by-limit-and-offset

thruflo · 2025-07-24T17:50:08Z

Also, whilst we're considering the orderBy signature #316

thruflo

Just actually testing this with my app. I get an error because my schema is an optional(), not nullable().

Using this branch, I updated my code to:

const { data: events } = useLiveQuery(
  (query) => (
    query
      .from({ event: eventCollection })
      .orderBy(
        ({ event }) => event.inserted_at
        { direction: 'asc', nulls: 'last' }
      )
      .where(({ event }) => eq(event.thread_id, threadId))
  ),
  [threadId]
)

I get this error:

react-dom-client.production.js:5788 TypeError: Cannot read properties of undefined (reading 'inserted_at')
    at query.from.innerJoin.orderBy.direction (ChatArea.tsx:82:34)
    at BaseQueryBuilder.orderBy (index.js:349:20)
    at ChatArea.tsx:81:10
    at buildQuery (index.js:582:18)
    at liveQueryCollectionOptions (live-query-collection.js:9:54)
    at createLiveQueryCollection (live-query-collection.js:200:21)
    at useLiveQuery (useLiveQuery.js:16:33)
    at ChatArea (ChatArea.tsx:73:28)

I'm not sure if we should:

handle undefined fields / zod foo.optional()s
not handle them and require the property but allow foo.nullable()s

I think that the ability to support both would be ideal as people may well use optionals in their schema definitions. If not then we need to document the limitation.

kevin-dp · 2025-07-28T09:26:18Z

@thruflo i'll open an issue for ordering on an optional column. It's a separate issue that's best addressed with a separate PR.

kevin-dp · 2025-07-28T09:37:36Z

Would it make sense to mimic PostgreSQL's default ordering?

By default, null values sort as if larger than any non-null value; that is, NULLS FIRST is the default for DESC order, and NULLS LAST otherwise.

@asabil Since TanStack DB is backend-agnostic we decided to stick to JS semantics wrt how null values sort.

kevin-dp · 2025-07-28T09:48:07Z

@thruflo I think the problem is in your callback itself:

({ event }) => event.inserted_at

You're trying to access inserted_at but event is undefined. That's throwing the error you're seeing. Can you try replacing it by this:

({ event }) => event?.inserted_at

thruflo · 2025-07-28T17:58:39Z

Just trying to wrap my head around how event could be undefined?

kevin-dp · 2025-07-29T06:40:38Z

Just trying to wrap my head around how event could be undefined?

@thruflo could you console.log it just to confirm that event is undefined. Could be that we try to access inserted_at somewhere internally and that the error comes from there, but from the stack trace i got the impression it is the event that is undefined.

thruflo · 2025-07-30T19:13:21Z

Ok, I'm running the same code against this branch and it's now working, i.e.: I can use the inserted_at in the orderBy fine.

thruflo approved these changes Jul 24, 2025

View reviewed changes

thruflo reviewed Jul 24, 2025

View reviewed changes

packages/db/src/query/builder/index.ts Outdated Show resolved Hide resolved

thruflo requested changes Jul 24, 2025

View reviewed changes

kevin-dp mentioned this pull request Jul 28, 2025

Order by an optional column #319

Open

kevin-dp added 4 commits July 28, 2025 11:31

Support nulls first and nulls last ordering

c56fc8b

Changeset

cd159c6

Use options object on orderBy function

c7292dc

Comparator options for lexical and locale sorting

52ecb77

kevin-dp force-pushed the kevindp/null-ordering branch from 5d86583 to 52ecb77 Compare July 28, 2025 09:33

kevin-dp requested review from thruflo and samwillis July 28, 2025 09:35

Update changeset

18b597a

kevin-dp changed the title ~~Configurable sortBy order of null values~~ Configuration options for sortBy Jul 28, 2025

thruflo approved these changes Jul 30, 2025

View reviewed changes

Configuration options for sortBy #314

Are you sure you want to change the base?

Configuration options for sortBy #314

Uh oh!

Conversation

kevin-dp commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

asabil commented Jul 24, 2025

Uh oh!

kevin-dp commented Jul 24, 2025

Uh oh!

samwillis commented Jul 24, 2025

Uh oh!

kevin-dp commented Jul 24, 2025

Uh oh!

KyleAMathews commented Jul 24, 2025

Uh oh!

thruflo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thruflo commented Jul 24, 2025

Uh oh!

thruflo commented Jul 24, 2025

Uh oh!

thruflo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevin-dp commented Jul 28, 2025

Uh oh!

kevin-dp commented Jul 28, 2025

Uh oh!

kevin-dp commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thruflo commented Jul 28, 2025

Uh oh!

kevin-dp commented Jul 29, 2025

Uh oh!

thruflo commented Jul 30, 2025

Uh oh!

Uh oh!

kevin-dp commented Jul 24, 2025 •

edited

Loading

changeset-bot bot commented Jul 24, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 24, 2025 •

edited

Loading

github-actions bot commented Jul 24, 2025 •

edited

Loading

github-actions bot commented Jul 24, 2025 •

edited

Loading

thruflo left a comment •

edited

Loading

kevin-dp commented Jul 28, 2025 •

edited

Loading