btv.shada

btv.shada.plugin(dev_namespace)

btv.shada.plugin() -> an isolated, cross-session key/value store for the calling plugin. The handle persists into the current shada store (global, workspace, or remote — whichever this session uses), walled off from the core registers / marks / history and keyed apart from every other plugin’s namespace.

The namespace is assigned, not chosen: it is derived from where the calling code lives (its runtimepath / plugin directory), so a plugin can persist its own data and can never name — and so never read or clobber — another plugin’s slice. Calling it from anywhere in a plugin’s files resolves to that one plugin’s namespace. Code in the user’s config maps to the reserved user namespace.

It is the plugin’s opt-in: only a plugin that calls this gets shada storage. Values may be any JSON-able Lua value (table / string / number / boolean); get returns a fresh copy. Persistence rides the ordinary shada cadence (the debounced checkpoint + the clean-exit flush); with shada disabled the store still works in memory for the session but isn’t written, exactly like registers and marks.

A namespace is capped at 1 MiB (of serialized key+value bytes) so one plugin can’t bloat the shared store; a set that would cross the cap raises (the prior value is left intact). Keep it to small, structured state — settings, a recent list, a cursor table — not bulk data.

local store = btv.shada.plugin()       -- no argument: namespace is assigned
store:set("recent", { "a.txt", "b.txt" })
local recent = store:get("recent")    -- the table back, or nil
store:delete("recent")
for _, k in ipairs(store:keys()) do … end
store:clear()

dev_namespace is an escape hatch for a context whose code attributes to no runtimepath entry — a bare :lua, an RPC exec_lua, a test, or a deferred/async callback whose stack no longer carries the plugin chunk — where the namespace can’t be derived, so an explicit one is required.

_{Defined in stdlib.lua.}

btv.shada.namespaces()

btv.shada.namespaces() -> a sorted list of every plugin namespace currently stored (after a shada load that is all persisted namespaces, not just the ones a plugin opened this session). The audit primitive: a user can see what plugins have stowed away, and the package manager forgets a removed plugin’s namespace on :PluginClean.

_{Defined in stdlib.lua.}

btv.shada.forget(namespace)

btv.shada.forget(namespace) -> drop a whole namespace’s stored data (it stops being written at the next shada flush). The cross-session counterpart of a handle’s :clear(), but addressed by name — for pruning an orphan (e.g. an uninstalled plugin’s leftovers). Fails loud on a non-string / empty name.

_{Defined in stdlib.lua.}