vault

# Vault
[![CI](https://github.com/dimamik/vault/actions/workflows/ci.yml/badge.svg)](https://github.com/dimamik/vault/actions/workflows/ci.yml)
[![License](https://img.shields.io/hexpm/l/vault.svg)](https://github.com/dimamik/vault/blob/main/LICENSE)
[![Version](https://img.shields.io/hexpm/v/vault.svg)](https://hex.pm/packages/vault)
[![Hex Docs](https://img.shields.io/badge/documentation-gray.svg)](https://hexdocs.pm/vault)
<!-- MDOC -->
Vault is a lightweight Elixir library for immutable data storage within a process subtree.
Due to Elixir's actor model nature, it's common for a process to have global context that is valid for every function call inside of the process and its children.
For example, this context can include:
- A user when processing a user's request
- A tenant in a multi-tenant application
- Rate limiting buckets/quotas
- Cache namespaces
- API or client versions
- And many more, depending on your application domain
---
`Vault.init/1` provides you a guarantee that the context can only be defined once per existing process subtree, so you won't override it by accident. This makes it easy to reason about your context origination.
## Usage
```elixir
# Initialize vault in parent process
Vault.init(current_user: %{id: 1, first_name: "Alice", role: "admin"})
# Access data from any descendant process, even these not linked!
spawn(fn ->
  Vault.get(:current_user) # => %{id: 1, first_name: "Alice", role: "admin"}
  Vault.init(current_user: :user) # => raises, because the ancestor already has vault initialized
end)
# Access data from the parent process itself
Vault.get(:current_user) # => %{id: 1, first_name: "Alice", role: "admin"}
```
However, if for some reason you need to split initializations, you can use `Vault.unsafe_merge/1`, but the immutability is no longer guaranteed.
## Why Vault?
- Instead of **property-drilling context data through every function call**, Vault provides access to shared data across your process tree. When used for immutable data - this is a cleaner and more maintainable approach, simplifying cognitive load when reasoning about your code.
- The data is initialized only once and is immutable (unless you explicitly call `unsafe_*` functions).
- The API mirrors Elixir's `Map` module for familiar data access.
<!-- MDOC -->
## Credits
- This library relies on the [`ProcessTree`](https://github.com/jbsf2/process-tree) library by [JB Steadman](https://github.com/jbsf2), which does all the heavy lifting of traversing process trees and propagating data back. You can read more about how ancestors are fetched in [this amazing blog post](https://saltycrackers.dev/posts/how-to-get-the-parent-of-an-elixir-process/) by the library's author.
## Installation
```elixir
def deps do
  [
    {:vault, "~> 0.2.1"}
  ]
end
```