refactor(nx2/api): unify return shapes, rename methods, add response helpers#480
Merged
Conversation
778eef4 to
6dfb954
Compare
6dfb954 to
52c9d7c
Compare
52c9d7c to
ea53ba7
Compare
…helpers
Consolidates the nx2 api surface around a single rule — every namespace method
returns a raw augmented `Response` — and aligns method/arg naming across
namespaces.
Renames (call sites updated):
- source.load -> source.get
- source.save({data}) -> source.save({body})
- config.put -> config.save
- snapshot.update -> snapshot.save (matches AEM's createSnapshot upsert)
Return-shape unification (raw Response everywhere except source.list):
- source.delete/copy/move: dropped wrapActionResp -> Response
- source.getMetadata: dropped {ok,status,headers} wrapper -> Response (caller
reads resp.headers for doc-id, last-modified, etc.)
- status.get: dropped parsed-JSON / undefined return -> Response
- aem.*: dropped returnJson flag, dropped 204 wrapper on unPreview/unPublish,
callPath returns Response directly.
- source.list is the documented exception: still returns {ok, items,
continuationToken, permissions} because it legitimately merges body +
header continuation token + normalized items.
New opt-in helpers (asJson, asText) — both return
{ ok, data, status, error } where data is the parsed body (populated even
on non-ok when parseable, matches axios), status is the HTTP code, and
error is null | 'no-response' | 'not-ok' | 'parse-failed'. No asOk —
const { ok } = await foo() does the same job.
Other fixes:
- snapshot.addPath/removePath auto-prepend `/` to path inputs (latent bug:
callers passing 'index.html' would build .../{id}index.html). New
normalizePath helper handles both string and array forms.
File layout reorganized so the public namespaces are at the top
(alphabetical), then response helpers, then low-level fetch primitives,
then internal helpers. Internal helpers converted from arrow-consts to
function declarations for hoisting.
Docs:
- api.d.ts: new UnwrapResult<T> type; method signatures tightened to
Promise<ApiResponse> with documented exceptions.
- api.md: rewrote return-values, error-handling, and aem/status sections;
added helpers section.
Tests: 90/90 pass. Notable: chai.deep.equal against a Response hangs Chrome
(traverses the body ReadableStream); switched the affected assertions to
expect(resp.ok)/expect(resp.status).
ea53ba7 to
cf65db1
Compare
auniverseaway
approved these changes
May 29, 2026
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
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.
Consolidates the nx2 api surface around a single rule — every namespace method
returns a raw augmented
Response— and aligns method/arg naming acrossnamespaces.
Renames (call sites updated):
Return-shape unification (raw Response everywhere except source.list):
reads resp.headers for doc-id, last-modified, etc.)
callPath returns Response directly.
continuationToken, permissions} because it legitimately merges body +
header continuation token + normalized items.
New opt-in helpers (asJson, asText) — both return
{ ok, data, status, error } where data is the parsed body (populated even
on non-ok when parseable, matches axios), status is the HTTP code, and
error is null | 'no-response' | 'not-ok' | 'parse-failed'. No asOk —
const { ok } = await foo() does the same job.
Other fixes:
/to path inputs (latent bug:callers passing 'index.html' would build .../{id}index.html). New
normalizePath helper handles both string and array forms.
File layout reorganized so the public namespaces are at the top
(alphabetical), then response helpers, then low-level fetch primitives,
then internal helpers. Internal helpers converted from arrow-consts to
function declarations for hoisting.
Docs:
Promise with documented exceptions.
added helpers section.
Tests: 90/90 pass. Notable: chai.deep.equal against a Response hangs Chrome
(traverses the body ReadableStream); switched the affected assertions to
expect(resp.ok)/expect(resp.status).