A Go library providing an interface to lazily or eagerly cache generated content. It utilizes Go 1.24's new weak package to offer a memory-efficient WeakStore alongside a standard MemoryStore. This is great for managing ephemeral data, reducing garbage collection pressure, and maintaining efficient caching.

go get github.com/arran4/go-weak-content

Note: This library requires Go 1.24 or later due to its use of the standard library's weak package.

• Generics Support: Caches any type (Content[T any]) effectively.
• Weak Pointers: Leverage Go 1.24 weak pointers to automatically free cached memory when it is no longer referenced elsewhere.
• Thread-safe Loading: Implemented safely for concurrent reads/writes using sync.Mutex.
• Flexible Options: Highly configurable using functional options.
• Lazy or Eager Loading: Control when the content generation executes.

This is ideal for large datasets where you want the garbage collector to free memory when the content is no longer actively used elsewhere.

package main

import (
	"fmt"

	utils "github.com/arran4/go-weak-content"
)

func main() {
	// Create a new Content instance that lazily loads, and stores via weak references.
	fc := utils.NewContent[[]byte](
		utils.WithGenerator[[]byte](func() (*[]byte, error) {
			// This will be called on the first Data() call
			b := []byte("Hello from go-weak-content!")
			return &b, nil
		}),
		utils.UseWeakStorage[[]byte](true),
		utils.UseLazyLoading[[]byte](true),
	)

	// Generate and retrieve data
	data, err := fc.Data()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(*data))
}

If you need the data to be generated immediately and kept firmly in memory, you can use eager loading with memory storage (the default storage is memory storage).

package main

import (
	"fmt"

	utils "github.com/arran4/go-weak-content"
)

func main() {
	fc := utils.NewContent[string](
		utils.WithGenerator[string](func() (*string, error) {
			// Executed immediately
			str := "Eagerly loaded data!"
			return &str, nil
		}),
		utils.UseMemoryStorage[string](true),
		utils.UseEagerLoading[string](true),
	)

	fmt.Println(fc.String()) // "Eagerly loaded data!"
}

If the content is already available, you can initialize the cache directly.

package main

import (
	"fmt"

	utils "github.com/arran4/go-weak-content"
)

func main() {
	fc := utils.NewContent[string](utils.WithValue[string]("Pre-existing content"))
	fmt.Println(fc.String()) // "Pre-existing content"
}

The Content interface represents the core of the library, providing methods to interact with cached content:

• Data() (*T, error): Returns a pointer to the value containing the generated content. If the content hasn't been generated yet (lazy loading), it will generate it.
• Close() error: Clears the currently cached data from the underlying store and triggers the onClose callback if set.
• String() string: A convenience method that returns the generated content as a string. Suppresses errors and returns an empty string if data generation fails. If the type is string, []byte, or fmt.Stringer, it will natively format it.
• Error() error: Evaluates whether the content state is currently valid. Returns nil if valid, or an error detailing why it is invalid (e.g., failed validation check or missing content).
• HasContent() bool: Returns true if the underlying store currently holds a generated value.
• Invalidate() error: Explicitly clears the cached content from the underlying store and triggers the onInvalidate callback if set.

• Store[T any]: The interface defining how objects are stored and retrieved (Get(), Set(), Clear()).
• WeakStore[T any]: An implementation of Store[T any] utilizing Go 1.24 weak pointers.
• MemoryStore[T any]: A standard implementation of Store[T any] keeping a strong reference in memory.

The NewContent[T any](opts ...Option[T]) constructor accepts the following options:

• UseWeakStorage[T](bool): Uses a weak pointer (Go 1.24 weak package) for storage. The garbage collector may reclaim the cached data if it's not strongly referenced elsewhere.
• UseMemoryStorage[T](bool): Uses a strong reference for storage, keeping the object in memory until explicitly cleared (this is the default behavior).
• UseLazyLoading[T](bool): Delays the execution of the generator function until Data() or String() is first called (this is the default behavior).
• UseEagerLoading[T](bool): Immediately executes the generator function during the NewContent call.
• WithGenerator[T](func() (*T, error)): The function that supplies the content when needed.
• WithValidator[T](func() bool): Sets a function that determines whether the currently cached content is still valid.
• WithValue[T](T): Directly sets the content cache with the provided static value.
• WithOnGenerate[T](func(val *T, err error)): A callback executed immediately after a generation attempt.
• WithOnInvalidate[T](func()): A callback executed when content is cleared from the store due to invalidation.
• WithOnClose[T](func()): A callback executed when Close() is called.

This project is licensed under the BSD 3-Clause License. See LICENSE for more details.