Resource.get(query) receives a RequestTarget: plain property access is silently undefined
Maintainers usually reply within 2 days
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 90/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- javascript, typescript
- Domain
- documentation
Research direction
Start in reference/resources/resource-api.md where get(query) is described, then check resources/RequestTarget.ts for the directly declared framework properties. Use the existing target.get('param1') example as context. Done means the reference explicitly identifies RequestTarget as extending URLSearchParams, explains query.get('name') for custom parameters and undefined plain-property access, and lists the direct properties.
Written by the indexing model from the issue text.
Description
Document that a custom Resource.get(query) receives a RequestTarget, so plain property access is silently undefined
The trap
In a custom Resource handler, query is a RequestTarget, which extends URLSearchParams:
static async get(query) {
const ids = query.ids; // undefined, always, for a custom param
const ids = query.get('ids'); // correct
}
resources/RequestTarget.ts:5 — class RequestTarget extends URLSearchParams — declares only a
fixed set of framework properties (conditions, limit, select, sort, … ~:24-100). Arbitrary
query parameters are never assigned as own properties: resources/search.ts:1370's
NEEDS_PARSER = /[()[\]|!<>.]|(=\w*=)/ gates the FIQL parser, so a plain ?ids=1,2,3 (no special
characters) takes parseQuery's else branch (search.ts:1381-1406) and simply returns query
untouched.
So query.ids is undefined and there is no error — the handler quietly behaves as if the caller
sent nothing.
Why it's worth a doc callout rather than a code change
It fails silently, and it fails the same way for everyone writing their first custom Resource. It
already bit our own QA fixture: a DirectHistory test resource read query.ids and the bug stayed
invisible only because that parameter's value happened to equal the handler's default.
HarperFast/documentation reference/resources/resource-api.md:67 already shows the right form
(target.get('param1')) in an example, but nowhere states that the plain-property form silently
yields undefined. An example a reader can copy correctly is not the same as a warning a reader can
avoid; the failure mode needs naming.
Ask
In the resource-api reference, where get(query) is described:
- State that
queryis aRequestTarget extends URLSearchParams. - State that custom query parameters must be read with
query.get('name'), and that plain property
access returnsundefinedwithout error. - Note which properties are available directly (the declared framework set:
conditions,limit,
select,sort, …), so the distinction is learnable rather than a rule to memorize.
Not this
HarperFast/harper#135 ("A target should have parsed query properties in static REST methods") is
CLOSED (2026-04-15, PR #124 "Immediately parse search/queries in URLs provided to RequestTarget").
That fix made the declared special-purpose properties parse eagerly in the constructor; it never
made arbitrary custom parameter names land as own properties, and was not intended to. So this is not
covered by #135's closure — re-verified on main 6d725818c.
— Claude Opus 5.5
- Dominant language
- MDX
- Stars
- 9
- Forks
- 9
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 16
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from HarperFast/documentation
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
HarperFast/documentation#677 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 Half a day Newbie friendliness 88/100
HarperFast/documentation#675 ·
Maintainers usually reply within 2 days
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
HarperFast/documentation#665 ·
Maintainers usually reply within 2 days
-
content
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
HarperFast/documentation#478 ·
Maintainers usually reply within 2 days
-
content
Difficulty 1/5 Under an hour Newbie friendliness 76/100
HarperFast/documentation#399 · 2 comments ·
Maintainers usually reply within 2 days
All issues in HarperFast/documentation
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
microsoft/onnxruntime#33018 ·
Maintainers usually reply within 2 days
-
missing content writing algorithms
Difficulty 1/5 Under an hour Newbie friendliness 88/100
QuantConnect/Documentation#2739 ·
Maintainers usually reply within 1 day
-
:watch: Not Triaged dotnet-target-version
Difficulty 1/5 Under an hour Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
copilot documentation
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 2 days
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
lichess-org/api#678 ·