Skip to content

fix: make default JSON serializer contract explicit#50

Draft
lan17 wants to merge 1 commit into
mainfrom
agent/honest-json-default-contract
Draft

fix: make default JSON serializer contract explicit#50
lan17 wants to merge 1 commit into
mainfrom
agent/honest-json-default-contract

Conversation

@lan17

@lan17 lan17 commented Jul 16, 2026

Copy link
Copy Markdown
Owner

Summary

Make DialCache's default JSON serializer contract honest without adding a validation pass or changing runtime serialization behavior.

The default serializer now advertises unknown rather than allowing callers to claim arbitrary lossless T round trips. The README documents the exact JSON-compatible domain, representative lossy transformations, native failures, and the custom serializer escape hatch.

Architecture and design

  • Keep JSON.stringify/JSON.parse as the default wire codec.
  • Treat Serializer<T> as a trusted codec boundary: DialCache does not perform an additional serialize/deserialize validation round trip.
  • Preserve the existing top-level undefined sentinel.
  • Preserve fail-open behavior for actual serializer exceptions.
  • Leave silent native JSON transformations as an explicit caller precondition rather than adding per-cache-write CPU overhead.

API impact

  • JsonSerializer is no longer generic; it implements Serializer<unknown>.
  • JsonSerializer.load() returns Promise<unknown>.
  • Existing code using new JsonSerializer<MyType>() must use new JsonSerializer() and narrow the decoded value, or provide a typed custom Serializer<MyType>.
  • The custom Serializer<T> interface remains available and unchanged for types such as Date.

There are no Redis key, frame, Lua, adapter, or stored-payload format changes.

Operational behavior

This adds no runtime validation and no extra serialization pass, so the cache hot path has no new CPU overhead. Existing JSON-compatible cached values remain wire-compatible.

The documented default domain includes JSON-stable primitives, arrays, and plain objects. Values such as Date, Map, Set, class instances, non-finite numbers, nested undefined, symbols, functions, bigint, cycles, prototypes, and shared object identity may be rejected or changed by native JSON semantics.

Validation

  • corepack pnpm typecheck
  • Unit and coverage suite: 103 tests passed
  • Focused serializer and Redis tests: 20 tests passed
  • Release tests: 5 tests passed
  • Build and declaration emission
  • Packed-package consumer test on Node 20.17.0
  • Integration suite: 46 tests passed
  • git diff --check

Tracking

Closes #16

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.

Make the default JSON serializer contract honest and enforceable

1 participant