feat: apply the sort query parameter

[mvantellingen]

The problem

sort is accepted and typed on QueryParams (src/storage/abstract.ts:32) but never applied. query() goes from where-filtering straight to resources.slice(offset, offset + limit), so results come back in insertion order.

Where that bites is cursor paging:

sort: "id asc"
where: `id > "${lastId}"`

which is how consumers walk a collection larger than one page — iterateProductPages, getStores and similar helpers in downstream projects all use it. Against the mock the cursor is taken from the last row of an unsorted page, so it is not the maximum id seen and the next query skips resources. The same code is correct against the real API, so a test written against the mock passes or fails for the wrong reason. I hit both while writing a paging-heavy feature and had to demote the data-level assertions to request-level ones.

The fix

src/lib/sortParser.ts — parseSortClauses + applySort, called from both the in-memory and sqlite backends after where and before offset/limit.

Supports field, field asc, field desc, dot-separated paths (name.en-GB), and several clauses passed as an array (which is how a repeated sort parameter arrives). Numbers compare numerically — "10" < "2" as strings is the trap. Everything else compares as a string, which orders ISO timestamps correctly. Stable, so a secondary clause only breaks ties from the first.

Two decisions worth a look

Strings compare with < / >, not localeCompare. predicateParser compares with those same operators (src/lib/predicateParser.ts:313). If sorting and the where predicate disagreed on ordering, a cursor could step over resources — the exact bug being fixed here. There is a test asserting ["A", "B", "a", "b"] and that each element is > its predecessor.

A missing value counts as larger than any present one, so it sorts last ascending and first descending, as SQL does. I could not verify commercetools' actual rule for this, so I picked the one that yields a total, deterministic order and documented it rather than guessing at fidelity. Happy to change it if someone knows the real behaviour.

Testing

• src/lib/sortParser.test.ts — 17 tests: parsing, directions, dot paths, numeric vs string comparison, missing values, tie-breaking, stability, no input mutation, predicate agreement, ISO timestamps.
• src/storage/storage.test.ts — 6 tests in the existing query block, including one that pages 25 categories in fours with a cursor and asserts all 25 are seen exactly once, in order. Runs against both storage backends.
• All 784 tests pass (761 pre-existing, 23 new). biome check && tsc clean.

Changeset included as a minor.

[changeset-bot]

🦋 Changeset detected

Latest commit: 2b7b1ce

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

This PR includes changesets to release 1 package

Name	Type
@labdigital/commercetools-mock	Minor

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