l0.DependencyControl.FileCache¶

MoonScriptLua

FileCache = require "l0.DependencyControl.FileCache"

local FileCache = require("l0.DependencyControl.FileCache")

FileCache ¶

A persistent, key-addressed cache of JSON blobs on disk. Each put is stored as a human-readable, timestamped snapshot file (which doubles as a history), indexed by a deterministic per-key meta file that names the latest snapshot and records when it was cached. An instance lives under <basePath>/<namespace>/<name>, so distinct caches (feeds, and others later) share one configurable cache base without colliding. Prefer the get factory over the constructor so instances are shared per directory. With a deserialize codec, get adds an in-memory L1 layer over the on-disk L2: it returns the parsed snapshot and memoizes it, keyed to the snapshot's cache time so a newer put (here or in another process) transparently supersedes the memo.

Constructor ¶

MoonScriptLua

fileCache = FileCache basePath, namespace, name, opts

local fileCache = FileCache(basePath, namespace, name, opts)

param	type	description
basePath	`string`	The cache root (the `paths.cache` setting, e.g. "?user/cache"); path-decoded here.
namespace	`string`	The owning script namespace (`constants.DEPCTRL_NAMESPACE` for DepCtrl's own caches).
name	`string`	A short subdirectory naming this cache's purpose (e.g. "feeds").
opts?	FileCacheOptions	Defaults for entry lifetime, retention, logging, clock, and the L1 codec.

Instance methods¶

getMeta ¶

MoonScriptLua

fileCache\getMeta key

fileCache:getMeta(key)

Reads the cache index entry for a key.

param	type	description
key	`string`

Returns:

meta FileCacheMeta? — nil when the key isn't cached.

isFresh ¶

MoonScriptLua

fileCache\isFresh meta

fileCache:isFresh(meta)

Whether a cache entry is still fresh, i.e. its expiry (fixed when it was written) hasn't passed and it hasn't been invalidated by expireAll. The expiry is intrinsic to the entry, so freshness is the same regardless of which instance asks or what its current maxAge is.

param	type	description
meta	FileCacheMeta?	A meta returned by getMeta.

Returns:

fresh boolean

getFile ¶

MoonScriptLua

fileCache\getFile key

fileCache:getFile(key)

Resolves the latest cached snapshot for a key. The snapshot may be stale; callers use isFresh on the returned meta to decide whether to serve it directly or only as an offline fallback.

param	type	description
key	`string`

Returns:

path string? — The snapshot file's path, or nil when the key isn't cached (or its file is gone).
meta FileCacheMeta? — The cache index entry (returned even when the snapshot file is missing).

expireAll ¶

MoonScriptLua

fileCache\expireAll before, purge

fileCache:expireAll(before, purge)

Marks every entry cached before the cut-off as stale, so the next get/isFresh reports it not fresh. The snapshot is kept as an offline fallback, and a later put makes the entry fresh again. When purging, the affected entries are instead dropped from the L1 memo and their on-disk snapshots and index deleted, to reclaim space or hard-reset.

param	type	description
before?	`integer`	Cut-off Unix time; entries cached strictly before it are affected (default: now).
purge?	`boolean`	Delete the affected entries (L1 + L2) instead of only marking them stale (default false).

put ¶

MoonScriptLua

fileCache\put key, content, label, expiresAfter

fileCache:put(key, content, label, expiresAfter)

Stores a blob under a readable, timestamped snapshot and repoints the index at it, then trims old snapshots. The snapshot name is <slug>-<label>-<utcTimestamp>-<rand>.json (slug first so a key's snapshots sort together).

param	type	description
key	`string`	The cache key.
content	`string`	The blob to persist verbatim.
label?	`string`	A human-readable name, used to make the snapshot file recognizable.
expiresAfter?	`integer`	Seconds until this entry expires, fixed into the index now (default: this cache's `maxAge`). Pass a per-resource lifetime to honor, e.g., an HTTP `max-age`.

Returns:

meta FileCacheMeta? — The written index entry, or nil on a filesystem error or a lock timeout.
err string?

Class methods¶

get ¶

MoonScriptLua

FileCache.get basePath, namespace, name, opts

FileCache.get(basePath, namespace, name, opts)

Returns the shared cache for a base/namespace/name, reusing the existing instance for that resolved directory rather than constructing a duplicate. Options apply only when the instance is first created.

param	type	description
basePath	`string`	The cache root (the `paths.cache` setting, e.g. "?user/cache"); path-decoded.
namespace	`string`	The owning script namespace (`constants.DEPCTRL_NAMESPACE` for DepCtrl's own caches).
name	`string`	A short name for this cache's purpose (e.g. "feeds").
opts?	FileCacheOptions	See new.

Returns:

FileCache

Fields¶

field	type	description
defaultMaxAge	`integer`
defaultMaxFiles	`integer`

Types¶

FileCacheMeta ¶

The per-key index entry FileCache persists next to each snapshot; returned by getMeta/getFile/get/put.

field	type	description
key	`string`	The cache key this entry indexes.
cachedAt	`integer`	Unix time the latest snapshot was written.
expiresAt	`integer`	Unix time the entry turns stale, fixed at write time.
latestFile	`string`	File name of the latest snapshot, relative to the cache directory.

FileCacheOptions ¶

Construction options for FileCache.

field	type	description
maxAge?	`integer`	Default entry lifetime in seconds, used when a put doesn't set its own (default 3600).
maxFiles?	`integer`	Snapshot files retained per cache before the oldest are trimmed (default 50).
logger?	Logger	Logger for cache operations.
now?	`fun(): integer`	Clock override returning Unix time; defaults to os.time (injected in tests).
deserialize?	`fun(content: string): any`	Codec turning stored content into the value get returns and memoizes; its presence enables the in-memory L1 layer.