Skip to content

feat(guilds): add getGuildConfigBatch for batched guild configuration lookups - #436

Merged
Lakes41 merged 1 commit into
Adamantine-guild:mainfrom
XxHugheadxX:feat/389-guild-config-batch
Jul 29, 2026
Merged

feat(guilds): add getGuildConfigBatch for batched guild configuration lookups#436
Lakes41 merged 1 commit into
Adamantine-guild:mainfrom
XxHugheadxX:feat/389-guild-config-batch

Conversation

@XxHugheadxX

Copy link
Copy Markdown
Contributor

Closes #389.

Two things settled before writing code

BatchItemResult could not carry a GuildConfig as written. src/contracts/contract.types.ts:83
declared result?: string, documented as raw hex from the contract batch methods. Reusing it —
which the issue asks for — means making it generic:

export type BatchItemResult<T = string> = {
  status: 'success' | 'error';
  result?: T;
  error?: string;
};

The string default leaves every existing contract call site and every consumer's type
source-compatible; only methods resolving richer values parameterise it.

A batch added only to the service would have silently bypassed the cache.
GuildPassClient wraps getGuildConfig in withCache, but getGuildConfigBatch calls
this.getGuildConfig internally — against the raw service, so nothing would be cached and a
follow-up single lookup would refetch. checkAccessBatch already solved this with a
neverCoalesce proxy that still caches per item but opts out of in-flight dedup, and this
mirrors it: coalescing inside a batch would let one caller's abort or failure affect an
unrelated caller sharing a key. Three tests pin the wiring.

Also worth noting

The issue lists src/services/guilds.ts and tests/services.test.ts. GuildsService actually
lives in src/guilds/guilds.service.ts, and tests/guilds.service.test.ts is where its tests
are, so those are the files touched. tests/fixtures/api-contract.json:131 already pins
/guilds/guild_1/config, so a client-side fan-out needs no new fixture shape.

Implementation

getGuildConfigBatch(params, options?) returns BatchItemResult<GuildConfig>[], one entry per
input ID in input order, with per-guild failure isolation matching getGuildOwnersBatch.

It is a client-side fan-out over the existing GET /guilds/:id/config endpoint — no batch
endpoint is assumed — issued through a bounded worker pool rather than all at once. Each worker
claims its index before awaiting, so results land at their own input position regardless of
response order. concurrency defaults to 5 and caps at 50, matching checkAccessBatch;
there is no shared batch helper in the repo to reuse, so this follows the same inline
worker-pool shape AccessService already uses.

includeMeta is dropped for the inner calls: per-item metadata has nowhere to live in
BatchItemResult.

Tests

+13, no existing test modified.

tests/guilds.service.test.ts (+9): order preservation; order preserved when responses resolve
out of order (the slow-first case, which a naive push would reorder); single-guild failure
isolation; INVALID_INPUT for empty, missing, non-array and undefined guildIds;
out-of-range concurrency; an observed in-flight peak proving the concurrency bound; duplicate
IDs each getting their own slot; and an invalid guild ID surfacing as a per-item error rather
than throwing the batch.

tests/cache.test.ts (+4): a batch call populating the per-guild cache; a later single lookup
served from it without a second request; the batch reading through entries a previous call
stored (only the uncached guild hits the network); and the no-adapter path still working.

Verification

before:  Test Files  71 passed (71)   Tests  1421 passed (1421)
after:   Test Files  71 passed (71)   Tests  1434 passed (1434)

No failures before or after. pnpm build exits 0. ESLint reports 0 errors on the touched files
(the no-explicit-any warnings are pre-existing and none are on changed lines).

Note on the api-report diff

api-report/guildpass-sdk.api.md was regenerated with pnpm build && pnpm api-report. Beyond
the BatchItemResult<T> and getGuildConfigBatch entries, the regenerated report also picks up
AuthenticationProvider, ApiKeyAuthenticationProvider and the circuit-breaker hooks from the
feat/auth-providers merge (add30e4), which landed without refreshing the report. Those lines
are not part of this change; they appear because the report was stale on main.

@Lakes41
Lakes41 merged commit dda4254 into Adamantine-guild:main Jul 29, 2026
4 checks passed
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.

Add getGuildConfigBatch method for batched guild configuration lookups

2 participants