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]) Get ¶
Get retrieves a value by key. Returns the value and true if found, nil and 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.
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