Skip to content

refactor(nx2/api): unify return shapes, rename methods, add response helpers#480

Merged
chrischrischris merged 3 commits into
mainfrom
api-refactor
May 29, 2026
Merged

refactor(nx2/api): unify return shapes, rename methods, add response helpers#480
chrischrischris merged 3 commits into
mainfrom
api-refactor

Conversation

@chrischrischris
Copy link
Copy Markdown
Contributor

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 type; method signatures tightened to
    Promise 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).

@aem-code-sync
Copy link
Copy Markdown

aem-code-sync Bot commented May 28, 2026

Hello, I'm the AEM Code Sync Bot and I will run some actions to deploy your branch.
In case there are problems, just click the checkbox below to rerun the respective action.

  • Re-sync branch
Commits

…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).
@chrischrischris chrischrischris merged commit 0bf0f8c into main May 29, 2026
2 checks passed
@chrischrischris chrischrischris deleted the api-refactor branch May 29, 2026 19:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants