feat(typed): add Typed[T,V] wrapper for compile-time type-safe cache access#105
Merged
feat(typed): add Typed[T,V] wrapper for compile-time type-safe cache access#105
Conversation
…access Implements RFC 0002 – Option A: a thin, zero-breaking-change wrapper over HyperCache[T] that eliminates caller-side type assertions on every Get. Changes: - Add hypercache.Typed[T, V] with Set, Get, GetTyped, GetOrSet, GetWithInfo, GetMultiple, Remove, and Clear; GetTyped surfaces ErrTypeMismatch vs ErrKeyNotFound for callers that need the distinction - Add sentinel.ErrTypeMismatch for wrong-type stored values - Add full test suite covering pointer/primitive round-trips, miss semantics, fail-soft type-mismatch on Get, explicit-error GetTyped, GetOrSet both branches + wrong-type guard, GetMultiple dual-map shape, and shared-underlying-cache composition pattern - Add docs/rfcs/0001-backend-owned-eviction.md: closed/rejected design artifact documenting the Item-embedded eviction spike, benchmark results (+11% Set, +53% Get regression), and lessons learned - Add docs/rfcs/0002-generic-item-typing.md: live RFC driving this change; sketches the v3 deep-generics path conditional on v2.x usage
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an opt-in, compile-time typed wrapper around HyperCache[T] to remove caller-side type assertions while keeping the existing untyped API intact, plus supporting docs and tests.
Changes:
- Introduce
hypercache.Typed[T, V]wrapper with typedSet/Get/GetTyped/GetOrSet/GetWithInfo/GetMultiple/Remove/Clear. - Add
internal/sentinel.ErrTypeMismatchand a comprehensive typed-wrapper test suite. - Add RFC documentation for the typing approach (RFC 0002) and archive a rejected eviction design (RFC 0001); update cspell dictionary.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
internal/sentinel/sentinel.go |
Adds ErrTypeMismatch sentinel used by the typed wrapper. |
hypercache_typed.go |
Implements the new Typed[T, V] wrapper API over HyperCache[T]. |
hypercache_typed_test.go |
Adds tests validating typed round-trips, miss/mismatch semantics, and shared-cache composition. |
docs/rfcs/0002-generic-item-typing.md |
Documents the motivation/options for typed access (including this wrapper approach). |
docs/rfcs/0001-backend-owned-eviction.md |
Adds a closed/rejected RFC capturing eviction spike results and lessons learned. |
cspell.config.yaml |
Adds domain terms used in the new RFCs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+12
to
+16
| // Typed is a thin wrapper around HyperCache that adds compile-time | ||
| // type-safety on Set/Get/GetOrSet/GetMultiple/GetWithInfo without | ||
| // breaking the existing untyped API. Internally Item.Value is still | ||
| // stored as any; the wrapper performs a single type assertion on read | ||
| // and rejects cross-typed entries as ErrTypeMismatch. |
Comment on lines
+80
to
+91
| func (t *Typed[T, V]) GetTyped(ctx context.Context, key string) (V, error) { | ||
| var zero V | ||
|
|
||
| raw, ok := t.hc.Get(ctx, key) | ||
| if !ok { | ||
| return zero, sentinel.ErrKeyNotFound | ||
| } | ||
|
|
||
| v, ok := raw.(V) | ||
| if !ok { | ||
| return zero, sentinel.ErrTypeMismatch | ||
| } |
| session, ok := val.(*Session) // unsafe in general; tedious | ||
| ``` | ||
|
|
||
| Wrong type assertions panic at runtime. There is no compile-time guarantee that what was Set as `*Session` is what Get returns. In a high-stakes financial environment this is a class of latent bug the type system *can* prevent — generics are the right tool. |
Comment on lines
+239
to
+244
| ## Implementation plan (Option A, v2.x) | ||
|
|
||
| 1. Add `hypercache_typed.go` with `Typed[T, V]`. Wrap each public method on `HyperCache[T]` (Set, Get, GetOrSet, GetWithInfo, GetMultiple, Remove, Clear, List). | ||
| 1. `GetMultiple` returns `map[string]V` and `map[string]error` — wrong-type entries land in the error map under a new sentinel `ErrTypeMismatch`. | ||
| 1. Document the wrapper as the recommended access pattern in the package doc. Examples in [`__examples/typed/`](../../__examples/typed/) (new). | ||
| 1. Tests: confirm the wrapper round-trips Set→Get cleanly for several V types ([]byte, struct, pointer, slice, map). Confirm cross-typed read returns miss without panic. |
| "github.com/stretchr/testify/require" | ||
|
|
||
| "github.com/hyp3rd/hypercache" | ||
| "github.com/hyp3rd/hypercache/internal/sentinel" |
Introduce CHANGELOG.md capturing the full v2.0.0 release history: breaking changes, performance wins (sharded eviction, iter.Seq2 migration, xxhash consolidation), new features, and removed items. Update README.md to document v2.0.0 additions: - Sharded eviction section with WithEvictionShardCount guidance - Type-safe access (Typed[V]) section with usage example - WithDistHTTPLimits and WithDistHTTPAuth options in the reference table - Transport hardening section covering TLS, bearer-token auth, body limits, lifecycle context, and LastServeError - Roadmap table: mark TLS/auth as done since v2.0.0
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements RFC 0002 – Option A: a thin, zero-breaking-change wrapper over HyperCache[T] that eliminates caller-side type assertions on every Get.
Changes: