docs: document static loadAsInstance in the v5 Resource API reference - #619
docs: document static loadAsInstance in the v5 Resource API reference#619kriszyp wants to merge 4 commits into
Conversation
The flag was dropped from the v5 docs without explanation, so AI coding agents copying older example code (e.g. engineering-metrics/DevLogin.ts) reintroduce it as if still required. Document that the v4 loadAsInstance=false behavior is unconditional in v5 and the flag is now a no-op. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation to reference/resources/resource-api.md regarding the deprecation of the static loadAsInstance property in v5. The reviewer suggested adding a VersionBadge component to properly document this behavior change in accordance with the repository's guidelines.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-619 This preview will update automatically when you push new commits. |
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-619 This preview will update automatically when you push new commits. |
…tic, methods Previous revision wrongly claimed the flag affected overridden static methods and was a v5 no-op that was safe to delete. Verified against resources/Resource.ts and resources/Table.ts: the flag is only read by Harper's built-in static dispatch when it calls a resource's *instance* methods, controlling arg order ((data, target) vs (target, data)), record pre-loading, get(string) semantics, and record freezing. An overridden static replaces that dispatch, so the flag never applies to it — which is why static methods are the recommended shape. The behavior is still live in v5, so the line cannot be removed unless the instance methods are converted too. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
kriszyp
changed the title
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-619 This preview will update automatically when you push new commits. |
Drop the per-behavior comparison table. The "records mutable vs frozen" row conflated two things: records are frozen regardless of the flag; what is mutable is the Resource instance the instance verbs are called on. Rather than restate mode internals in the v5 reference, link to the v4 doc's API Versions section, which already documents both modes in full. Keeps the v5 page focused on the actionable guidance: statics don't need the flag, and the line can't be deleted while REST-mirroring instance verbs remain. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-619 This preview will update automatically when you push new commits. |
2 participants
Summary
loadAsInstanceisn't mentioned anywhere in the v5 Resource API reference. With nothing in the reference to guide them, AI coding agents copying older example code (e.g.engineering-metrics/DevLogin.ts) reintroducestatic loadAsInstance = false;into fresh v5 resources and then argue it's required — see the Slack thread that prompted this.This adds a short
static loadAsInstance?: booleansubsection at the top of "Resource Static Methods", plus a cross-reference from the back-compat instance-method list. It deliberately does not restate the mode internals — the v4 reference's API Versions section already documents both modes in full, so the v5 page links there and stays focused on what a v5 author needs to decide.The two things worth documenting
Verified against
resources/Resource.tsandresources/Table.tsonmain:Overridden static methods are unaffected by the flag. It is only read inside Harper's built-in dispatch, at the point that dispatch instantiates the resource and calls the corresponding instance method. Defining
static get/static postreplaces that dispatch — including the code reading the flag — so a custom static always receives(target, data)regardless. This is a large part of why static methods are the recommended shape for custom endpoints, and it's the direct answer to the confusion in the thread.The flag is still live in v5, so the line is not safe to delete on its own. It still selects the argument order for REST-mirroring instance verbs. Removing
static loadAsInstance = false;from a resource that still defines those instance methods reverses their argument order and breaks them. It can only come out as part of converting them to statics.Notes for reviewers
VersionBadge. 641db8a (gemini-code-assist suggestion) added<VersionBadge type="changed" version="v5.0.0" />. That was premised on an earlier draft of mine which wrongly claimed v5 made the flag's behavior unconditional for static methods. The corrected text says the opposite — the instance-method behavior is unchanged and still live — so a "changed in v5.0.0" badge would be inaccurate. Happy to add a plain (non-changed) badge instead if we want one here.Test plan
resources/Resource.ts(theloadAsInstancebranches inside each verb'stransactionaldispatch) andresources/Table.ts(getResourcepreload,get(string)semantics, permission placement)npx prettier --write reference/resources/resource-api.md— clean#api-versions,#resource-instance-methods,#static-loadasinstance-boolean); repo uses generated slugs, not explicit heading idsreference_versioned_docs/version-v4/...matches the existing cross-version link already in this file🤖 Generated with Claude Code