Skip to content

feat(javascript): add WithHTTPInfo methods - #6682

Merged
eric-zaharia merged 7 commits into
mainfrom
port/added-withhttpinfo-methods-20260706/javascript
Jul 13, 2026
Merged

eric-zaharia merged 7 commits into
mainfrom
port/added-withhttpinfo-methods-20260706/javascript

Conversation

@eric-zaharia

@eric-zaharia eric-zaharia commented Jul 6, 2026 •

Copy link
Copy Markdown
Contributor

🧭 What and Why

🎟 JIRA Ticket: API-144

Mirrors #5852 for the JavaScript client: every generated operation gets a {method}WithHTTPInfo sibling that resolves with the full HTTP response — status code, headers (when the requester captures them), raw body and deserialized data — so callers can inspect HTTP metadata (status code, rate-limit headers, …) without writing a custom requester. Plain method signatures, return values and caching behavior are unchanged.

Changes included:

  • New AlgoliaHttpResponse<TData> type in client-common ({ status, headers?, content, data }), name aligned with the C# AlgoliaHttpResponse wrapper.
  • New transporter.requestWithHttpInfo verb next to request/requestStream, sharing the same retry/failover path and throwing the exact same ApiError/DetailedApiError on non-2xx. It bypasses both the requests and the responses caches, so the returned status and headers always reflect an actual API call — including for cacheable operations like search. The verb is declared on a new TransporterWithHttpInfo type (Transporter & { requestWithHttpInfo }) returned by createTransporter; declaring it on Transporter itself would be a type-level breaking change for hand-written implementations and test mocks of that type, so Transporter is untouched and they all remain type-valid.
  • Optional headers?: Record<string, string> field on the requester Response type, populated (lower-cased names) by all four requesters: requester-node-http, requester-fetch, requester-browser-xhr and requester-testing. User-supplied custom requesters remain type-valid without changes; the wrapper's headers is simply undefined for them. The echo requester echoes the request headers as response headers — consistent with its contract that everything it returns is the serialized request — so tests doing exact-equality assertions on full echo Response objects need to account for the new field.
  • templates/javascript/clients/api-single.mustache emits the {{nickname}}WithHTTPInfo sibling per operation (same parameter handling, validation, legacy-signature support and timeouts as the plain method), following the existing StreamRaw/requestStream pattern. Each sibling gets its own JSDoc via a dedicated jsdocWithHttpInfo.mustache partial (mustache partials take no parameters, so the extra return/cache-bypass paragraph can't be injected into the shared jsdoc partial): the operation description plus the full-HTTP-response return and cache-bypass behavior, keeping the ACL list, @deprecated flags and param docs. The algoliasearch fat client and the lite client pick the methods up automatically. Suffix spelling WithHTTPInfo matches the Java/C#/Go/Swift clients.
  • Request building is extracted into a shared buildRequest.mustache partial used by each method and its WithHTTPInfo sibling, so the two can't drift; generated output for the plain methods is unchanged. Validation and legacy-signature blocks stay per-method because validateRequired must report the calling method's name.
  • Fix (user-visible): on operations with spec-level timeouts (push, pushTask, validateSource, validateSourceBeforeUpdate, discoverSource), user-supplied requestOptions other than timeouts — extra headers, query parameters, cacheable — were silently discarded; they are now preserved and merged with the spec-default timeouts, matching the other language clients. The fix lands in the shared partial, covering both the plain methods and the new siblings.
  • Raised the bundlewatch budgets for the five bundles that outgrew them with the new per-operation method surface (algoliasearch 17→21KB, client-search 9→10KB, ingestion 8→10KB, client-analytics 6→7KB, composition 6→7KB); the others are unchanged. Budgets measure gzipped size, and extracting a shared per-operation request builder was measured to produce larger gzipped bundles — gzip backreferences already deduplicate the near-identical method bodies, while the indirection adds entropy — so the duplicated emission is kept and the remaining growth is the irreducible per-operation surface (method names, signatures, validation strings). Delegating the plain method to its sibling is not an option either: requestWithHttpInfo bypasses the caches, so delegation would silently disable caching for cacheable operations.

Usage

const response = await client.searchWithHTTPInfo({ requests: [{ indexName: 'products', query: 'phone' }] });

console.log(response.status); // 200
console.log(response.headers?.['x-ratelimit-remaining']);
console.log(response.data.results); // same payload `search` resolves with

Fully backwards compatible: additive methods and optional fields only.

🧪 Test

  • New client-common vitest suite for requestWithHttpInfo: parity with request on success, undefined data on 204/empty bodies, identical ApiError/DetailedApiError on failures, headers left undefined for requesters that don't capture them, and cache bypass for cacheable requests.
  • algoliasearch bundle test asserts the transporter exposes the new verb and smoke-tests searchWithHTTPInfo end to end against the echo requester.

@algolia-api-clients-automation-bot

algolia-api-clients-automation-bot Bot commented Jul 6, 2026 •

Copy link
Copy Markdown
Contributor

✔️ Code generated!

Name Link
🪓 Triggered by 81403dbf29e25f106b89613b88acd162a10ecd42
🍃 Generated commit cc4f9d5e7fa10000a5a2a169a281a5a0425bfe51
🌲 Generated branch generated/port/added-withhttpinfo-methods-20260706/javascript
📊 Benchmark results

Benchmarks performed on the method using a mock server, the results might not reflect the real-world performance.

Language Req/s
javascript 2237

@eric-zaharia
eric-zaharia marked this pull request as ready for review July 8, 2026 07:38
@eric-zaharia
eric-zaharia requested a review from a team as a code owner July 8, 2026 07:38
@eric-zaharia eric-zaharia self-assigned this Jul 8, 2026
@eric-zaharia
eric-zaharia merged commit 8a5ab6f into main Jul 13, 2026
30 of 34 checks passed
@eric-zaharia
eric-zaharia deleted the port/added-withhttpinfo-methods-20260706/javascript branch July 13, 2026 07:39
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.

2 participants