[id='client-usage_{context}']
= {hr_js} client examples

After you install and configure your {hr_js} client, start using it by trying out some basic cache operations before moving on to more complex interactions with {brandname}.

== Hello world

Create a cache named "myCache" on {brandname} Server then add and retrieve an entry.

[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/hello-world.js[]
----

== Working with entries and retrieving cache statistics

Add, retrieve, remove single entries and view statistics for the cache.

[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/single-entries.js[]
----

== Working with multiple cache entries

Create multiple cache entries with simple recursive loops.

[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/multiple-entries.js[]
----

== Using Async and Await constructs

Node.js provides `async` and `await` constructs that can simplify cache operations.

.Single cache entries
[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/await-single-entries.js[]
----

.Multiple cache entries
[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/await-multiple-entries.js[]
----

== Running server-side scripts

You can add custom scripts to {brandname} Server and then run them from {hr_js} clients.

.Sample script
[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/sample-script.js[]
----

.Script execution
[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/sample-script-execute.js[]
----

== Registering event listeners

Event listeners notify {hr_js} clients when cache updates occur, including when entries are created, modified, removed, or expired.

[NOTE]
====
Events for entry creation and modification notify clients about keys and values.
Events for entry removal and expiration notify clients about keys only.
====

.Event listener registration
[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/register-event-listener.js[]
----

You can tune notifications from event listeners to avoid unnecessary roundtrips with the `key-value-with-previous-converter-factory` converter.
This allows you to, for example, find out values associated with keys within the event instead of retrieving them afterwards.

.Remote event converter
[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/key-value-converter.js[]
----

[TIP]
====
You can add custom converters to {brandname} Server.
See the link:{doc_home}[{brandname} documentation] for information.
====

== Using conditional operations

The Hot Rod protocol stores metadata about values in {brandname}.
This metadata provides a deterministic factor that lets you perform cache operations for certain conditions.
For example, if you want to replace the value of a key if the versions do not match.

Use the `getWithMetadata` method to retrieve metadata associated with the value for a key.

[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/conditional-operations.js[]
----

== Working with ephemeral data

Use the `getWithMetadata` and `size` methods expire cache entries.

[source,javascript,options="nowrap",subs=attributes+]
----
include::code_examples/ephemeral-data.js[]
----
