Fix Resource post/put/patch data type + document search sort + content-type table#495
Draft
kriszyp wants to merge 1 commit into
Draft
Fix Resource post/put/patch data type + document search sort + content-type table#495kriszyp wants to merge 1 commit into
kriszyp wants to merge 1 commit into
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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