README
¶
fcache
fcache is a simple and fast SQLite based cache that is designed for CLIs and other tools that need to temporarily cache and retrieve data.
Documentation
¶
Overview ¶
The fcache package provides a simple and fast SQLite based cache that is designed for CLIs and other tools that need to temporarily cache and retrieve data.
Index ¶
- type Cache
- func (c *Cache) Close() error
- func (c *Cache) Contains(key string) (bool, error)
- func (c *Cache) ContainsContext(ctx context.Context, key string) (bool, error)
- func (c *Cache) Count() (int64, error)
- func (c *Cache) CountContext(ctx context.Context) (int64, error)
- func (c *Cache) Database() string
- func (c *Cache) Delete(key string) (bool, error)
- func (c *Cache) DeleteContext(ctx context.Context, key string) (bool, error)
- func (c *Cache) Entries() ([]Entry, error)
- func (c *Cache) EntriesContext(ctx context.Context) ([]Entry, error)
- func (c *Cache) Entry(key string) (*Entry, error)
- func (c *Cache) EntryContext(ctx context.Context, key string) (*Entry, error)
- func (c *Cache) ExpiredCount() (int64, error)
- func (c *Cache) ExpiredCountContext(ctx context.Context) (int64, error)
- func (c *Cache) Keys() ([]string, error)
- func (c *Cache) KeysContext(ctx context.Context) ([]string, error)
- func (c *Cache) Load(key string, dst any) (bool, error)
- func (c *Cache) LoadContext(ctx context.Context, key string, dst any) (bool, error)
- func (c *Cache) Prune() error
- func (c *Cache) PruneContext(ctx context.Context) error
- func (c *Cache) Store(key string, v any, ttl time.Duration) error
- func (c *Cache) StoreContext(ctx context.Context, key string, val any, ttl time.Duration) error
- type Entry
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
A Cache is a fast SQLite based on-disk cache.
func Open ¶ added in v0.0.3
Open returns a new Cache with filename as the SQLite3 database path. If filename does not exist, it will be created (parent directories are not created).
It is allowed, but not always recommended to use ":memory:" as the filename, which will create an in-memory cache.
func OpenUserCache ¶ added in v0.0.3
OpenUserCache returns a new cache using the default cache directory for the current OS. The $XDG_CACHE_HOME environment variable is respected on all systems (not just Linux).
Name is the name of the directory to create under the user cache directory and the database name is always "cache.sqlite3".
On Linux this might be "$HOME/.cache/{NAME}/cache.sqlite3".
On macOS this might be "$HOME/Library/Caches/{NAME}/cache.sqlite3".
func (*Cache) Contains ¶ added in v0.0.2
Contains returns true if an entry exists for key. It does not check if the entry is expired.
func (*Cache) ContainsContext ¶ added in v0.0.2
ContainsContext returns true if an entry exists for key. It does not check if the entry is expired.
func (*Cache) CountContext ¶ added in v0.0.2
CountContext returns the number of entries in the cache.
func (*Cache) Delete ¶ added in v0.0.2
Delete deletes the entry with key from the cache and returns true if an entry with key was deleted. If no entry with key exists false is returned.
func (*Cache) DeleteContext ¶ added in v0.0.2
DeleteContext deletes the entry with key from the cache and returns true if an entry with key was deleted. If no entry with key exists false is returned.
func (*Cache) EntriesContext ¶
EntriesContext returns a slice of all the entries in the cache.
func (*Cache) Entry ¶ added in v0.0.2
Entry returns the Entry for key or ErrNoRows if it does not exist.
func (*Cache) EntryContext ¶ added in v0.0.2
EntryContext returns the Entry for key or ErrNoRows if it does not exist.
func (*Cache) ExpiredCount ¶ added in v0.0.2
ExpiredCount return the number of expired entries in the cache.
func (*Cache) ExpiredCountContext ¶ added in v0.0.2
ExpiredCountContext return the number of expired entries in the cache.
func (*Cache) KeysContext ¶ added in v0.0.2
KeysContext returns a sorted slice of all the keys in the cache.
func (*Cache) Load ¶
Load unmarshals the JSON encoded value stored in the cache for key into dst and returns true if an entry for key existed and is not expired.
An error is returned if there was an error querying the cache database or if there was an error unmarshaling the JSON value into dst.
If the DisallowUnknownFields option is enabled an error is returned when the destination is a struct and the input contains object keys which do not match any non-ignored, exported fields in the destination.
func (*Cache) LoadContext ¶
TODO: consider returning sql.ErrNoRows if an entry is not found. That way users can distinguish between an expired entry and a missing entry
LoadContext unmarshals the JSON encoded value stored in the cache for key into dst and returns true if an entry for key existed and is not expired.
An error is returned if there was an error querying the cache database or if there was an error unmarshaling the JSON value into dst.
If the DisallowUnknownFields option is enabled an error is returned when the destination is a struct and the input contains object keys which do not match any non-ignored, exported fields in the destination.
func (*Cache) Prune ¶
Prune prunes any expired entries from the cache and performs a VACUUM if any entries were removed.
func (*Cache) PruneContext ¶
PruneContext prunes any expired entries from the cache and performs a VACUUM if any entries were removed.
func (*Cache) Store ¶
Store encodes val to JSON and sets it as the value for key, replacing any existing value. If the value cannot be JSON encoded the returned error will unwrap to: json.UnsupportedTypeError.
The TTL controls when an entry expires and has millisecond resolution. A negative TTL never expires.
func (*Cache) StoreContext ¶
StoreContext encodes val to JSON and sets it as the value for key, replacing any existing value. If the value cannot be JSON encoded the returned error will unwrap to: json.UnsupportedTypeError.
The TTL controls when an entry expires and has millisecond resolution. A negative TTL never expires.
type Entry ¶
type Entry struct {
Key string `json:"key" db:"key"`
CreatedAt time.Time `json:"created_at" db:"created_at_unix_ms"`
// ExpiresAt is zero if the entry was created without a TTL.
ExpiresAt time.Time `json:"expires_at" db:"expires_at_unix_ms"`
Data json.RawMessage `json:"data" db:"data"`
}
An Entry is a cache entry.
type Option ¶ added in v0.0.2
type Option interface {
// contains filtered or unexported methods
}
An Option configures a Cache.
func BusyTimeout ¶ added in v0.0.2
WithBusyTimeout sets the busy timeout of the Cache.
In addition to SQLite3's busy timeout logic the Cache will also retry queries that fail with SQLITE_BUSY until the busy timeout expires. This is to handle the busy timeout setting of SQlite3 not always working as expected.
func DisallowUnknownFields ¶ added in v0.0.2
func DisallowUnknownFields() Option
DisallowUnknownFields causes the Cache's Decoder to return an error when the destination is a struct and the input contains object keys which do not match any non-ignored, exported fields in the destination.
Source Files