Documentation
¶
Overview ¶
Package jsonstore provides a generic JSON file-based key-value storage. It is designed for simple persistence needs where a full database is overkill.
Features:
- Thread-safe operations with read-write mutexes
- Atomic file writes (write to temp, then rename)
- In-memory caching for fast reads
- Dirty flag to only write when data changes
- Generic model support through type parameters
Example usage:
type MyModel struct {
Name string `json:"name"`
Count int `json:"count"`
}
store, err := jsonstore.New[MyModel]("data.json")
if err != nil {
log.Fatal(err)
}
defer store.Close()
// Set a value
err = store.Set("key1", &MyModel{Name: "test", Count: 42})
// Get a value
model, ok := store.Get("key1")
Index ¶
- type Model
- type Store
- func (s *Store[T]) Clear() error
- func (s *Store[T]) Close() error
- func (s *Store[T]) Count() int
- func (s *Store[T]) Delete(key string) bool
- func (s *Store[T]) ForceSave() error
- func (s *Store[T]) Get(key string) *T
- func (s *Store[T]) GetUpdated() time.Time
- func (s *Store[T]) GetVersion() int
- func (s *Store[T]) Has(key string) bool
- func (s *Store[T]) Keys() []string
- func (s *Store[T]) List() map[string]*T
- func (s *Store[T]) Set(key string, value *T) error
- func (s *Store[T]) Update(key string, fn func(*T) *T) error
- type StoreData
- type StoreOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Model ¶
type Model interface {
any // Allows any type as a model
}
Model is the interface that all models must implement. Use a pointer to your model type as the type parameter.
type Store ¶
type Store[T any] struct { // contains filtered or unexported fields }
Store manages JSON file-based storage with generic type support.
func New ¶
func New[T any](filePath string, opts ...StoreOption[T]) (*Store[T], error)
New creates a new JSON-based store for the given model type. If filePath doesn't exist, an empty store is created. If filePath exists, existing data is loaded.
The model type T must be a pointer type (e.g., *MyModel) to ensure consistent behavior when values are nil.
func (*Store[T]) Delete ¶
Delete removes a value from the store. Returns true if the key was found and removed, false otherwise.
func (*Store[T]) GetUpdated ¶
GetUpdated returns the last update time.
func (*Store[T]) GetVersion ¶
GetVersion returns the store version.
func (*Store[T]) List ¶
List returns all values in the store as a map. The returned map is a shallow copy; modifications won't affect the store.
func (*Store[T]) Set ¶
Set stores a value for the given key. The value is stored as a pointer to enable nil values.
func (*Store[T]) Update ¶
Update updates a value using the provided function. The function receives the current value (or nil if not found) and returns the new value. If the function returns nil, the key is deleted.
fn runs while the store's write lock is held so the read-modify-write is atomic. It MUST NOT call back into this store (Get, Set, Update, ...) — the lock is not reentrant and doing so deadlocks.
type StoreData ¶
type StoreData[T any] struct { Version int `json:"version"` Items map[string]*T `json:"items"` // Key: string, Value: pointer to model Updated time.Time `json:"updated"` }
StoreData represents the JSON file structure. Version allows for future schema migrations.
type StoreOption ¶
StoreOption is a function that configures a Store.
func WithVersion ¶
func WithVersion[T any](version int) StoreOption[T]
WithVersion sets the version for the store data.
Source Files