@chip/us-kv (0.0.2)
Installation
@chip:registry=npm install @chip/us-kv@0.0.2"@chip/us-kv": "0.0.2"About this package
The @chip/us-kv package provides a simple interface to the api.us.dev key-value
store. This store is intended to be used with simple data that needs to be shared
across multiple devices or users. It is not intended for large amounts of data or for
data that needs to be accessed frequently.
Usage
Installation
To install the package, add the registry to your project's .npmrc file:
@chip:registry=https://git.gg/api/packages/chip/npm/
Then, install the package using npm/yarn/pnpm:
npm install @chip/us-kv
yarn add @chip/us-kv
pnpm add @chip/us-kv
Registering a Namespace
The us-kv store is organized into namespaces, which are essentially top-level keys that can contain multiple key-value pairs. To use the store, you first need to register a namespace.
To register a namespace, you can use the attemptToRegisterNamespace function. This
function will attempt to register the namespace and return the initial auto-generated
secret key. If the namespace is already registered an exception is thrown.
import Kv from "@chip/us-kv";
const kv = new Kv("my-namespace");
const secretKey = await kv.attemptToRegisterNamespace();
console.log("Secret Key:", secretKey);
Connecting to a Registered Namespace
To connect to a registered namespace, provide the secret key for the namespace when
creating a new instance of the Kv class:
import Kv from "@chip/us-kv";
const secretKey = "your-secret-key";
const kv = new Kv("my-namespace", secretKey);
Changing the Secret Key
It is possible to change the secret key for a namespace after is is registered or you
have connected to it with a secret key. To change the secret key, use the changeSecretKey function. This will return another auto-generated secret key.
import Kv from "@chip/us-kv";
const secretKey = "your-secret-key";
const kv = new Kv("my-namespace", secretKey);
const newSecretKey = await kv.changeSecretKey();
console.log("New Secret Key:", newSecretKey);
Setting and Getting Values
Setting and getting values is possible with strings and objects that can be serialized
into JSON. To work with string values, use the setValue and getValue methods. For
objects, use the setObject and getObject methods.
import Kv from "@chip/us-kv";
const secretKey = "your-secret-key";
const kv = new Kv("my-namespace", secretKey);
// Setting and getting a string value
await kv.setValue("my-key", "my-value");
const value = await kv.getValue("my-key");
console.log("Value:", value);
// Setting and getting an object value
const myObject = { name: "Alice", age: 30 };
await kv.setObject("my-object-key", myObject);
const objectValue = await kv.getObject("my-object-key");
console.log("Object Value:", objectValue);
Dependencies
Development dependencies
| ID | Version |
|---|---|
| @types/jest | ^30.0.0 |
| jest | ^30.2.0 |
| ts-jest | ^29.4.5 |
| typedoc | ^0.28.14 |
| typescript | ^5.3.0 |