Fix Resource post/put/patch data type + document search sort + content-type table#495
Conversation
…tent-type behaviour * `data` parameter on `post` / `put` / `patch` is the deserialized request body, not a `Promise<object>` — the example showing `let data = await promisedData;` is misleading because the deserializer returns synchronously for every built-in content type. Update the signatures and the example. * Add a content-type → `data`-shape table so users know what to expect on non-JSON requests. * Document the indexed-attribute + matching-condition requirement for `sort` and give the workaround that returned the only error message users see today: "X is not indexed and not combined with any other conditions". Tracks harper #774 (long-fetch abort docs) and #773 (sort error).
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-495 This preview will update automatically when you push new commits. |
The previous revision regressed two facts: - post/put/patch receive `data` as a Promise<object> (REST.ts deserializes the body via the streaming deserializer, which returns a promise). Reading fields without `await` yields undefined. Restore the Promise signature and the `await data` in every example; also fix the put/patch examples that mixed `await data` with un-awaited `data.status`. - sort does not require a same-attribute condition. An `@indexed` sort attribute needs no condition at all; a non-indexed attribute only needs at least one condition on *any* attribute. Only (non-indexed attribute + zero conditions) throws. Document `allowFullScan` and clarify the bare `@primaryKey` case. Also correct the content-type table: msgpack is `application/x-msgpack`, and ndjson is registered as both `application/x-ndjson` and `application/ndjson`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-495 This preview will update automatically when you push new commits. |
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-495 This preview will update automatically when you push new commits. |
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
LGTM — verified all three sections against harper main (the promise-of-data behavior in REST.ts, every row of the content-type table, and the sort/index logic in Table.ts) and they all check out.
Two non-blocking notes: the PR description still argues the pre-revision thesis (drop the await) — worth refreshing so the merge commit doesn't memorialize it; and the greater_than/'' workaround example only works for string primary keys (numeric ids won't compare above ''). Neither blocks — merging.
sent with Claude Fable 5
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
3 participants
Summary
Three corrections / clarifications to
reference/resources/resource-api.mdbased on real friction I hit while building harper-celebrity-match and harper-roadmap demos.1.
post/put/patchdatatype is wrongThe page documents the signature as
data: Promise<object>and the example showslet data = await promisedData;. That's not what the runtime actually passes. In server/REST.tsrequest.datais assigned the synchronous return value of the deserializer — forapplication/jsonrequests that's the parsed value, not a Promise.Result: every user initially writes
const data = await promisedData, sees it work becauseawaitof a non-thenable just resolves to itself, then copy-pastes that into other handlers. Eventually they findSearch.js/Import.jsin our example components doingconst { foo } = dataand rewrite — the docs should match the example.Fixed signature:
data: object. Example updated to drop theawait.2. Content-type →
data-shape tableAdded a small table explaining what
datais for the built-in deserializers (JSON, CBOR, MessagePack, NDJSON, plain text).3.
sortrequires a matching indexed conditionThe current sort docs imply
sort: { attribute: 'id' }should just work becauseidis the primary key. It doesn't — Harper's query planner requires the sort attribute to be both@indexedAND narrowed by aconditionsentry. The error message you get is "id is not indexed and not combined with any other conditions" which is misleading (id IS indexed). Documented the actual requirement + the workaround.Tracks:
🤖 Generated with Claude Code