nats_kv (enats v1.1.3)

View Source

Summary

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.

Deletes a key by placing a delete marker with additional options.

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.

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.

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

config()

-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

create(Conn, Bucket, Key, Value)

-spec create(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata(), Value :: iodata()) ->
                {ok, map()} | {error, term()}.

Equivalent to create(Conn, Bucket, Key, Value, #{}).

create(Conn, Bucket, Key, Value, Opts)

-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}.

create_bucket(Conn, Bucket)

-spec create_bucket(Conn :: nats:conn(), Bucket :: iodata()) -> {ok, map()} | {error, term()}.

Equivalent to create_bucket(Conn, #{bucket => Bucket}, #{}).

create_bucket(Conn, Config, Opts)

-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.

create_bucket(Conn, Bucket, Config, Opts)

-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).

delete(Conn, Bucket, Key)

-spec delete(Conn :: nats:conn(), Bucket :: iodata(), Key :: iodata()) -> {ok, map()} | {error, term()}.

Equivalent to delete(Conn, Bucket, Key, #{}).

delete(Conn, Bucket, Key, Opts)

-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: If true, performs a purge instead of a regular delete (see purge/3). Returns {ok, map()} or {error, Reason}.

delete_bucket(Conn, Bucket)

-spec delete_bucket(Conn :: nats:conn(), Bucket :: iodata()) -> {ok, map()} | {error, term()}.

Equivalent to delete_bucket(Conn, Bucket, #{}).

delete_bucket(Conn, Bucket, Opts)

-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.

get(Conn, Bucket, Key)

-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, #{}).

get/4

-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 specific SeqNo or the last revision.
  • get(Conn, Bucket, Key, Opts): Retrieves the latest value with additional Opts.

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.

get(Conn, Bucket, Key, SeqNo, Opts)

-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.

get_bucket(Conn, Bucket)

-spec get_bucket(Conn :: nats:conn(), Bucket :: iodata()) -> {ok, map()} | {error, term()}.

Equivalent to get_bucket(Conn, Bucket, #{}).

get_bucket(Conn, Bucket, Opts)

-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}.

get_msg/4

list_keys(Conn, Bucket, WatchOpts)

-spec list_keys(Conn :: nats:conn(), Bucket :: iodata(), WatchOpts :: map()) ->
                   {ok, list()} | {error, term()}.

Equivalent to list_keys(Conn, Bucket, WatchOpts, #{}).

list_keys(Conn, Bucket, WatchOpts, Opts)

-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}.

purge(Conn, Bucket, Key)

-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.

purge(Conn, Bucket, Key, Opts)

-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}.

put(Conn, Bucket, Key, Value)

-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.

select_keys(Conn, Bucket, Keys, WatchOpts)

-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, #{}).

select_keys(Conn, Bucket, Keys, WatchOpts, Opts)

-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.

update(Conn, Bucket, Key, Value, SeqNo)

-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.

update_bucket(Conn, Bucket)

-spec update_bucket(Conn :: nats:conn(), Bucket :: iodata()) -> {ok, map()} | {error, term()}.

Equivalent to update_bucket(Conn, #{bucket => Bucket}, #{}).

update_bucket(Conn, Config, Opts)

-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.

update_bucket(Conn, Bucket, Config, Opts)

-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).

watch(Conn, Bucket, Keys, WatchOpts, 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.

watch(Conn, Bucket, Keys, WatchOpts, Opts, StartOpts)

-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}.

watch_all(Conn, Bucket, WatchOpts, Opts)

-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}.

watch_all(Conn, Bucket, WatchOpts, Opts, StartOpts)

-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}.