AppSync GraphQL implementation checklist¶
Finite boundary audit (#192)¶
| Reviewed boundary | Evidence | Classification |
|---|---|---|
| Resolver/Router, single/custom/Query/Mutation/batch registration, inclusion and exception exports | Existing 114 resolver cases and native context/error tests | Verified for decoded maps and []Event; SDK structs require explicit JSON conversion |
| ID/date/time/datetime/timestamp helpers | Existing 91 scalar cases, 45 new actual clock/offset cases and UUID shape/uniqueness | Verified finite formatting and offset contract |
| Instants outside the Date domain, including Go UnixMilli overflow | TestScalarNativeRangeCannotWrapIntoDateDomain |
Reproduced and fixed: validate seconds before conversion; invalid date helpers retain upstream NaN components |
| Sub-millisecond Go inputs | TestScalarNativeNanosecondsUseUnixMillisecondFloor |
Deliberate Unix millisecond floor, including negative instants; JavaScript Date cannot retain nanoseconds |
| Native nil/scalar/map/empty slice/array/byte aggregate outputs | Eight TestBatchNativeOutputBoundaries rows |
Non-nil slices/arrays become top-level arrays; invalid types preserve framework exceptions |
GQL-COMPLETE/GQL-SERVICE retain exhaustive native/async/error forms, arbitrary serialization, service behavior and resource budgets. The finite audit adds no decorators and does not mutate caller events.
Implementation history¶
Reference: installed Powertools TypeScript v2.35.0 public AppSync GraphQL exports. Keep full service, type and language compatibility gates separate from core work.
- GQL-CORE: Map resolver/router/scalar exports, implement single/custom/Query/Mutation routing, registry inclusion and exact-name exception handling. Verify replacement ordering, framework exception bypass, original-error fallback and invalid event guards against actual TypeScript.
- GQL-BATCH: Implement default aggregation, sequential individual execution, graceful null results, first-failure abort and first-event route selection. Preserve reference empty-batch and invalid-response failures.
- GQL-SCALARS: Implement UUID v4 and date/time/timestamp helpers with explicit Go clock input, offset validation, fractional offsets and reference formatting. Verify 91 deterministic scalar cases and UUID shape/uniqueness.
- GQL-REFERENCE: Verify 114 actual TypeScript resolver scenarios, ordered diagnostics/calls/errors, 64 concurrent contexts, reentrant diagnostics, panic/error identity and native aggregate arrays with CGO disabled.
- GQL-LOCAL: Verify all 24 packaged modules and 21 standalone consumers, both CGO-disabled Linux architectures, the native Lambda example and Parser/Logger/OTel composition. Local acceptance passed 766/766 RIE, 95/95 streaming Runtime API and 14/14 saved Batch artifact checks (2026-09-22). Docker executed amd64; arm64 was cross-compiled. The verified GraphQL ZIP matches every current module file. Temporary resources were cleaned; no AWS resources were used.
- GQL-ERROR-TYPE: Preserve the concrete TypeError for empty batches so the Go Lambda SDK reflects the reference Runtime API error name. Verify its concrete type and the existing differential scenarios (2026-09-23).
- GQL-COMPLETE: Finish public declaration/native-type mapping, typed event adapters, malformed Unicode and serialization boundaries, decorator/scope/async mappings and scalar nanosecond/out-of-domain behavior. Audit remaining native Runtime API error forms. Document intentional Go differences without treating them as complete parity.
- GQL-SERVICE: Verify actual AppSync single/batch invocation, service response/error representation and authorization context when cloud testing is requested. Establish latency/allocation/payload budgets and complete publication requirements.