From cb3cad61c1635a9b096d34d440ee033388b708c9 Mon Sep 17 00:00:00 2001 From: Dominik Fuerst <35500723+justDMNK@users.noreply.github.com> Date: Sat, 14 Dec 2024 16:01:35 +0000 Subject: [PATCH 1/2] Improve clarity around cache key function usage --- examples/basic/main.go | 4 ++-- examples/batch/main.go | 3 ++- examples/buffering/main.go | 2 +- examples/permutations/main.go | 2 +- keys.go | 8 ++++---- 5 files changed, 10 insertions(+), 9 deletions(-) diff --git a/examples/basic/main.go b/examples/basic/main.go index a31bd66..5c0391f 100644 --- a/examples/basic/main.go +++ b/examples/basic/main.go @@ -60,8 +60,8 @@ func demonstrateGetOrFetchBatch(cacheClient *sturdyc.Client[int]) { {"11", "12", "13", "14", "15"}, } - // We'll use a cache key function to add a prefix to the IDs. If we only used - // the IDs, we wouldn't be able to fetch the same IDs from multiple data sources. + // We are going use a cache key function that prefixes each id with the provided prefix and "-ID-". + // If we only used the IDs, we wouldn't be able to fetch the same IDs from multiple data sources. keyPrefixFn := cacheClient.BatchKeyFn("my-data-source") // Request the keys for each batch. diff --git a/examples/batch/main.go b/examples/batch/main.go index 0140612..58b1ebc 100644 --- a/examples/batch/main.go +++ b/examples/batch/main.go @@ -20,11 +20,12 @@ func NewAPI(c *sturdyc.Client[string]) *API { } func (a *API) GetBatch(ctx context.Context, ids []string) (map[string]string, error) { - // We are going to pass the cache a key function that prefixes each id. + // We are going to pass the cache a key function that prefixes each id with the provided prefix and "-ID-". // This makes it possible to save the same id for different data sources. cacheKeyFn := a.BatchKeyFn("some-prefix") // The fetchFn is only going to retrieve the IDs that are not in the cache. + // The cacheMisses will contain the missing IDs without the prefix. fetchFn := func(_ context.Context, cacheMisses []string) (map[string]string, error) { log.Printf("Cache miss. Fetching ids: %s\n", strings.Join(cacheMisses, ", ")) // Batch functions should return a map where the key is the id of the record. diff --git a/examples/buffering/main.go b/examples/buffering/main.go index 567c40d..c698453 100644 --- a/examples/buffering/main.go +++ b/examples/buffering/main.go @@ -23,7 +23,7 @@ func NewOrderAPI(client *sturdyc.Client[string]) *OrderAPI { } func (a *OrderAPI) OrderStatus(ctx context.Context, ids []string, opts OrderOptions) (map[string]string, error) { - // We use the PermutedBatchKeyFn when an ID isn't enough to uniquely identify a + // We use the PermutedBatchKeyFn when an ID isn't enough to uniquely identify a // record. The cache is going to store each id once per set of options. In a more // realistic scenario, the opts would be query params or arguments to a DB query. cacheKeyFn := a.PermutatedBatchKeyFn("key", opts) diff --git a/examples/permutations/main.go b/examples/permutations/main.go index 5826fc2..5312a88 100644 --- a/examples/permutations/main.go +++ b/examples/permutations/main.go @@ -23,7 +23,7 @@ func NewOrderAPI(c *sturdyc.Client[string]) *OrderAPI { } func (a *OrderAPI) OrderStatus(ctx context.Context, ids []string, opts OrderOptions) (map[string]string, error) { - // We use the PermutedBatchKeyFn when an ID isn't enough to uniquely identify a + // We use the PermutedBatchKeyFn when an ID isn't enough to uniquely identify a // record. The cache is going to store each id once per set of options. In a more // realistic scenario, the opts would be query params or arguments to a DB query. cacheKeyFn := a.PermutatedBatchKeyFn("key", opts) diff --git a/keys.go b/keys.go index fd41153..d710e0f 100644 --- a/keys.go +++ b/keys.go @@ -158,8 +158,8 @@ func (c *Client[T]) PermutatedKey(prefix string, permutationStruct interface{}) } // BatchKeyFn provides a function that can be used in conjunction with -// "GetOrFetchBatch". It takes in a prefix and returns a function that will -// append the ID as a suffix for each item. +// "GetOrFetchBatch". It takes in a prefix and returns a function that will format +// a string with the prefix and id seperated by "-ID-" for each item. // // Parameters: // @@ -167,7 +167,7 @@ func (c *Client[T]) PermutatedKey(prefix string, permutationStruct interface{}) // // Returns: // -// A function that takes an ID and returns a cache key string with the given prefix and ID. +// A function that takes an ID and returns a cache key string with the given prefix and ID seperated by "-ID-". func (c *Client[T]) BatchKeyFn(prefix string) KeyFn { return func(id string) string { return fmt.Sprintf("%s-ID-%s", prefix, id) @@ -189,7 +189,7 @@ func (c *Client[T]) BatchKeyFn(prefix string) KeyFn { // // Returns: // -// A function that takes an ID and returns a cache key string with the given prefix, permutation struct fields, and ID. +// A function that takes an ID and returns a cache key string with the given prefix and permutation struct fields followed by "-ID-" and the ID. func (c *Client[T]) PermutatedBatchKeyFn(prefix string, permutationStruct interface{}) KeyFn { return func(id string) string { key := c.PermutatedKey(prefix, permutationStruct) From 767f7d3e1630ed7b5d93382ceb375eb908689fdf Mon Sep 17 00:00:00 2001 From: Dominik Fuerst <35500723+justDMNK@users.noreply.github.com> Date: Sat, 14 Dec 2024 16:12:50 +0000 Subject: [PATCH 2/2] Improve clarity of BatchKeyFn in README --- README.md | 5 +++-- examples/batch/main.go | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 572f323..881c913 100644 --- a/README.md +++ b/README.md @@ -317,7 +317,7 @@ IDs each: IDs can often be fetched from multiple data sources. Hence, we'll want to prefix the ID in order to make the cache key unique. The package provides more functionality for this that we'll see later on, but for now we'll use the most -simple version which adds a string prefix to every ID: +simple version which adds a string prefix together with a seperator to every ID: ```go keyPrefixFn := cacheClient.BatchKeyFn("my-data-source") @@ -803,11 +803,12 @@ func NewAPI(c *sturdyc.Client[string]) *API { } func (a *API) GetBatch(ctx context.Context, ids []string) (map[string]string, error) { - // We are going to use a cache a key function that prefixes each id. + // We are going to pass the cache a key function that prefixes each id with the provided prefix and "-ID-". // This makes it possible to save the same id for different data sources. cacheKeyFn := a.BatchKeyFn("some-prefix") // The fetchFn is only going to retrieve the IDs that are not in the cache. + // The cacheMisses will contain the missing IDs and not the formatted keys. fetchFn := func(_ context.Context, cacheMisses []string) (map[string]string, error) { log.Printf("Cache miss. Fetching ids: %s\n", strings.Join(cacheMisses, ", ")) // Batch functions should return a map where the key is the id of the record. diff --git a/examples/batch/main.go b/examples/batch/main.go index 58b1ebc..282ab20 100644 --- a/examples/batch/main.go +++ b/examples/batch/main.go @@ -25,7 +25,7 @@ func (a *API) GetBatch(ctx context.Context, ids []string) (map[string]string, er cacheKeyFn := a.BatchKeyFn("some-prefix") // The fetchFn is only going to retrieve the IDs that are not in the cache. - // The cacheMisses will contain the missing IDs without the prefix. + // The cacheMisses will contain the missing IDs and not the formatted keys. fetchFn := func(_ context.Context, cacheMisses []string) (map[string]string, error) { log.Printf("Cache miss. Fetching ids: %s\n", strings.Join(cacheMisses, ", ")) // Batch functions should return a map where the key is the id of the record.