:help lib.nvim-store

*lib.nvim-store.txt*          Project-scoped persistent state

lib.nvim.store                                              *lib.nvim-store*

Persistent-storage namespace. Currently ships one submodule, project.

---

CONTENTS *lib.nvim-store-contents*

  1. Design ...................................... |lib.nvim-store-design|
  2. Usage ........................................ |lib.nvim-store-usage|
  3. Functions .................................... |lib.nvim-store-functions|
       project.root ......................... |lib.nvim-store-project.root|
       project.save ......................... |lib.nvim-store-project.save|
       project.load ......................... |lib.nvim-store-project.load|
       project.clear ........................ |lib.nvim-store-project.clear|
       project.stats ........................ |lib.nvim-store-project.stats|

---

1. DESIGN *lib.nvim-store-design*

project persists state **keyed by project**, so reopening the same project
— even on a different machine, via synced dotfiles/config — finds the same
state again. This is what lib.nvim.cache.disk does not provide: it is
keyed by a caller-chosen namespace with no notion of "which project is
this".

project adds nothing but root resolution on top of two existing
primitives:
  - lib.nvim.fs.project_key — git root of the given/current path (falls
    back to the path itself outside a work-tree), normalized, cached.
  - lib.nvim.cache.disk — namespaced JSON persistence with TTL,
    pcall-guarded read/write. All actual IO is delegated here unchanged.

---

2. USAGE *lib.nvim-store-usage*

    local store = require("lib.nvim.store.project")

    store.save("cascade/anchors", { version = 1, files = {} })
    local data = store.load("cascade/anchors")
    store.clear("cascade/anchors")

Also reachable via the namespace table:

    local store = require("lib.nvim.store")
    store.project.save("cascade/anchors", { version = 1 })

---

3. FUNCTIONS *lib.nvim-store-functions*

---

project.root({opts}) *lib.nvim-store-project.root*

The resolved, normalized project root backing key's storage for the
current (or opts.path) project. Exposed for diagnostics/tests.

    local root = store.root()

---

project.save({key}, {data}, {opts}) *lib.nvim-store-project.save*

Persist data under key, namespaced to the current project. Returns
ok, err.

    local ok, err = store.save("settings", { theme = "dark" })

---

project.load({key}, {opts}) *lib.nvim-store-project.load*

Load the value saved under key for the current project, or nil if
missing, unreadable, or expired (per opts.ttl_seconds).

    local data = store.load("settings", { ttl_seconds = 3600 })

---

project.clear({key}, {opts}) *lib.nvim-store-project.clear*

Remove the stored value for key in the current project. Returns ok.

    store.clear("settings")

---

project.stats({key}, {opts}) *lib.nvim-store-project.stats*

Report on-disk state for key without decoding the full payload — same
shape as lib.nvim.cache.disk's stats.

    local st = store.stats("settings")
    -- { exists, saved_at, age_seconds, size_bytes }

Options

    path          string    path to resolve the project root from (default
                             cwd); affects WHICH project's storage is used
    dir           string    override the parent storage directory (default
                             stdpath("cache") .. "/lib.nvim/store/project")
    ttl_seconds   integer   load only: treat entries older than this as
                             expired

---