nats_kv (enats v1.1.3)
View SourceSummary
Functions
Creates a key/value pair if the key does not exist with additional options.
Creates a KeyValue store bucket with the specified configuration and options.
Creates a KeyValue store bucket with the specified bucket name, configuration, and options.
Equivalent to delete(Conn, Bucket, Key, #{})
.
Deletes a key by placing a delete marker with additional options.
Equivalent to delete_bucket(Conn, Bucket, #{})
.
Deletes a KeyValue store bucket with the specified options.
Retrieves the latest value for a key.
Retrieves a specific revision of a key by sequence number, or the latest value with options.
Retrieves a specific revision of a key by sequence number with additional options.
Equivalent to get_bucket(Conn, Bucket, #{})
.
Retrieves the configuration of a KeyValue store bucket with additional options.
Retrieves all keys from the key value store with additional options.
Purges a key by placing a delete marker and removing all previous revisions.
Purges a key with additional options.
Puts a new value for a key into the store.
Equivalent to select_keys(Conn, Bucket, Keys, WatchOpts, #{})
.
Retrieves selected keys from the key value store with additional options.
Updates the value for a key if the latest revision matches the provided sequence number.
Updates an existing KeyValue store bucket with the specified configuration and options.
Updates an existing KeyValue store bucket with the specified bucket name, configuration, and options.
Starts a watcher process that monitors updates to keys matching the given Keys
pattern(s).
Starts a watcher process with additional start options for the watcher process.
Starts a watcher process that monitors all updates in the bucket.
Starts a watcher process that monitors all updates in the bucket with additional start options.
Types
-type config() :: #{bucket := iodata(), description => binary(), max_value_size => non_neg_integer(), history => 1..64, ttl => non_neg_integer(), max_bytes => non_neg_integer(), storage => memory | file, num_replicas => 1..5, placement => nats_stream:placement(), republish => nats_stream:republish(), mirror => nats_stream:stream_source(), sources => [nats_stream:stream_source()], compression => boolean()}.
Functions
-spec create(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Value :: iodata()) -> {ok, map()} | {error, term()}.
Equivalent to create(Conn, Bucket, Key, Value, #{})
.
-spec create(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Value :: iodata(), Opts :: map()) -> {ok, map()} | {error, term()}.
Creates a key/value pair if the key does not exist with additional options.
See create/4
for details on Conn
, Bucket
, Key
, and Value
.
Opts
allows specifying options, including return_existing
which, if true,
will return {error, {exists, OldObj}}
where OldObj
is the existing message details.
Returns {ok, map()}
or {error, Reason}
.
Equivalent to create_bucket(Conn, #{bucket => Bucket}, #{})
.
-spec create_bucket(Conn :: nats:conn(), Config :: config(), Opts :: map()) -> {ok, map()} | {error, term()}.
Creates a KeyValue store bucket with the specified configuration and options.
Config
is a map containing the bucket configuration (see config/0
).
Opts
allows specifying options for the underlying NATS request.
Returns {ok, map()}
on success or {error, Reason}
on failure.
-spec create_bucket(Conn :: nats:conn(), Bucket :: iodata(), Config :: map(), Opts :: map()) -> {ok, map()} | {error, term()}.
Creates a KeyValue store bucket with the specified bucket name, configuration, and options.
This is an alternative way to specify the bucket name alongside the configuration map.
Returns {ok, map()}
on success or {error, Reason}
on failure.
Equivalent to create_bucket(Conn, Config#{bucket => Bucket}, Opts)
.
-spec delete(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata()) -> {ok, map()} | {error, term()}.
Equivalent to delete(Conn, Bucket, Key, #{})
.
-spec delete(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Opts :: map()) -> {ok, map()} | {error, term()}.
Deletes a key by placing a delete marker with additional options.
This is a non-destructive operation; all previous revisions are kept.
A history of a deleted key can still be retrieved using get/4,5
with a specific revision
or by using a watcher without the ignore_deletes
option.
Opts
can include:
revision
: An integer sequence number. The delete will only succeed if the latest revision matches this number (conditional delete).purge
: Iftrue
, performs a purge instead of a regular delete (seepurge/3
). Returns{ok, map()}
or{error, Reason}
.
Equivalent to delete_bucket(Conn, Bucket, #{})
.
-spec delete_bucket(Conn :: nats:conn(), Bucket :: iodata(), Opts :: map()) -> {ok, map()} | {error, term()}.
Deletes a KeyValue store bucket with the specified options.
Allows specifying options for the underlying NATS request.
Returns {ok, map()}
on success or {error, Reason}
on failure.
-spec get(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata()) -> {ok, map()} | {deleted, #{message := #{hdrs := maybe_improper_list(), _ => _}, _ => _}} | {error, term()}.
Retrieves the latest value for a key.
Equivalent to get(Conn, Bucket, Key, last, #{})
.
-spec get(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), SeqNo :: integer() | last) -> {ok, map()} | {deleted, #{message := #{hdrs := maybe_improper_list(), _ => _}, _ => _}} | {error, term()}; (Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Opts :: map()) -> {ok, map()} | {deleted, #{message := #{hdrs := maybe_improper_list(), _ => _}, _ => _}} | {error, term()}.
Retrieves a specific revision of a key by sequence number, or the latest value with options.
get(Conn, Bucket, Key, SeqNo)
: Retrieves the value at a specificSeqNo
or thelast
revision.get(Conn, Bucket, Key, Opts)
: Retrieves the latest value with additionalOpts
.
If the key does not exist, an error indicating "Message Not Found" will be returned.
If the key has been deleted, {deleted, map()}
is returned.
Otherwise, {ok, binary()}
is returned with the key's value.
-spec get(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), SeqNo :: integer() | last, Opts :: map()) -> {ok, map()} | {deleted, #{message := #{hdrs := maybe_improper_list(), _ => _}, _ => _}} | {error, term()}.
Retrieves a specific revision of a key by sequence number with additional options.
This is the most general get
function.
SeqNo
can be an integer revision number or the atom last
.
Opts
allows specifying options for the underlying NATS request.
If the key does not exist or the specific revision is not found, an error indicating "Message Not Found" will be returned.
If the key at the specified revision has a delete or purge marker, {deleted, map()}
is returned.
Otherwise, {ok, map()}
is returned containing the message details.
Equivalent to get_bucket(Conn, Bucket, #{})
.
-spec get_bucket(Conn :: nats:conn(), Bucket :: iodata(), Opts :: map()) -> {ok, map()} | {error, term()}.
Retrieves the configuration of a KeyValue store bucket with additional options.
Allows specifying options for the underlying NATS request.
Returns {ok, Config}
or {error, Reason}
.
-spec list_keys(Conn :: nats:conn(), Bucket :: iodata(), WatchOpts :: map()) -> {ok, list()} | {error, term()}.
Equivalent to list_keys(Conn, Bucket, WatchOpts, #{})
.
-spec list_keys(Conn :: nats:conn(), Bucket :: iodata(), WatchOpts :: map(), Opts :: map()) -> {ok, list()} | {error, term()}.
Retrieves all keys from the key value store with additional options.
This is a convenience function equivalent to calling select_keys/4
with Keys
set to ~">"
.
WatchOpts
is a map of options for the watcher behavior (e.g., include_history
, meta_only
).
Note that ignore_deletes
is implicitly set to true
for this function.
Opts
allows specifying options for the underlying NATS request.
Returns {ok, List}
or {error, Reason}
.
-spec purge(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata()) -> {ok, map()} | {error, term()}.
Purges a key by placing a delete marker and removing all previous revisions.
This is a destructive operation. Only the latest revision (the purge marker)
will be preserved.
Returns {ok, map()}
containing the publish response details for the purge marker
or {error, Reason}
on failure.
-spec purge(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Opts :: map()) -> {ok, map()} | {error, term()}.
Purges a key with additional options.
See purge/3
for details on Conn
, Bucket
, and Key
.
Opts
can include:
revision
: An integer sequence number. The purge will only succeed if the latest revision matches this number (conditional purge). Returns{ok, map()}
or{error, Reason}
.
-spec put(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Value :: iodata()) -> {ok, map()} | {error, term()}.
Puts a new value for a key into the store.
If the key does not exist, it will be created. If the key exists, the value will be updated.
A key must consist of alphanumeric characters, dashes, underscores, equal signs, and dots.
Returns {ok, map()}
containing the publish response details or {error, Reason}
on failure.
-spec select_keys(Conn :: nats:conn(), Bucket :: iodata(), Keys :: binary() | [binary()], WatchOpts :: map()) -> {ok, list()} | {error, term()}.
Equivalent to select_keys(Conn, Bucket, Keys, WatchOpts, #{})
.
-spec select_keys(Conn :: nats:conn(), Bucket :: iodata(), Keys :: binary() | [binary()], WatchOpts :: map(), Opts :: map()) -> {ok, list()} | {error, term()}.
Retrieves selected keys from the key value store with additional options.
This function starts a temporary watcher process to fetch the current values
for keys matching the Keys
pattern(s). It waits for the initial values
and then stops the watcher.
Keys
can be a single binary subject or a list of binary subjects, potentially containing wildcards.
WatchOpts
is a map of options for the watcher behavior (e.g., include_history
, meta_only
).
Note that ignore_deletes
is implicitly set to true
for this function.
Opts
allows specifying options for the underlying NATS request.
Returns {ok, List}
where List
is a list of keys (binary()) or key-value pairs ({binary(), binary()}),
or {error, Reason}
on failure.
-spec update(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Value :: iodata(), SeqNo :: integer()) -> {ok, map()} | {error, term()}.
Updates the value for a key if the latest revision matches the provided sequence number.
This function performs a conditional update. If the current latest revision
of the key does not match SeqNo
, the update will fail with an error
indicating a wrong last sequence.
Returns {ok, map()}
containing the publish response details or {error, Reason}
on failure.
Equivalent to update_bucket(Conn, #{bucket => Bucket}, #{})
.
-spec update_bucket(Conn :: nats:conn(), Config :: config(), Opts :: map()) -> {ok, map()} | {error, term()}.
Updates an existing KeyValue store bucket with the specified configuration and options.
Config
is a map containing the bucket configuration (see config/0
).
Opts
allows specifying options for the underlying NATS request.
Returns {ok, map()}
on success or {error, Reason}
on failure.
-spec update_bucket(Conn :: nats:conn(), Bucket :: iodata(), Config :: map(), Opts :: map()) -> {ok, map()} | {error, term()}.
Updates an existing KeyValue store bucket with the specified bucket name, configuration, and options.
This is an alternative way to specify the bucket name alongside the configuration map.
Returns {ok, map()}
on success or {error, Reason}
on failure.
Equivalent to update_bucket(Conn, Config#{bucket => Bucket}, Opts)
.
-spec watch(Conn :: nats:conn(), Bucket :: iodata(), Keys :: binary() | [binary()], WatchOpts :: map(), Opts :: map()) -> {ok, pid()} | {error, term()}.
Starts a watcher process that monitors updates to keys matching the given Keys
pattern(s).
Keys
can be a single binary subject or a list of binary subjects, potentially containing wildcards.
WatchOpts
is a map of options for the watcher behavior (e.g., include_history
, ignore_deletes
, updates_only
, meta_only
, resume_from_revision
).
Opts
allows specifying options for the underlying NATS request.
The watcher process will send messages to the calling process's mailbox.
Returns {ok, Pid}
of the watcher process or {error, Reason}
on failure.
-spec watch(Conn :: nats:conn(), Bucket :: iodata(), Keys :: binary() | [binary()], WatchOpts :: map(), Opts :: map(), StartOpts :: [term()]) -> {ok, pid()} | {error, term()}.
Starts a watcher process with additional start options for the watcher process.
See watch/5
for details on Conn
, Bucket
, Keys
, WatchOpts
, and Opts
.
StartOpts
are options passed to proc_lib:spawn_opt/4
when starting the watcher process.
Returns {ok, Pid}
or {error, Reason}
.
-spec watch_all(Conn :: nats:conn(), Bucket :: iodata(), WatchOpts :: map(), Opts :: map()) -> {ok, pid()} | {error, term()}.
Starts a watcher process that monitors all updates in the bucket.
This is a convenience function equivalent to calling watch/5
with Keys
set to ~">"
.
WatchOpts
and Opts
are as described in watch/5
.
Returns {ok, Pid}
or {error, Reason}
.
-spec watch_all(Conn :: nats:conn(), Bucket :: iodata(), WatchOpts :: map(), Opts :: map(), StartOpts :: [term()]) -> {ok, pid()} | {error, term()}.
Starts a watcher process that monitors all updates in the bucket with additional start options.
See watch_all/4
for details on Conn
, Bucket
, WatchOpts
, and Opts
.
StartOpts
are options passed to proc_lib:spawn_opt/4
.
Returns {ok, Pid}
or {error, Reason}
.