Home

Awesome

Nostr-Key-Value

NOTE: This README is translated by DeepL.

This is a project that wants to use Nostr as a Key-Value DB. JavaScript/TypeScript support.

->日本語のREADMEはこちら (to Japanese)

This library uses NIP-78, which is a system that provides something like remoteStorage. NIP-78 is a system that provides something like remoteStorage; it is a post with Kind: 30078 and extends NIP-33 (Kind: 3xxxx).

-> NIP-78

Who made it

Shino3 (Shino-san) from:🇯🇵

License

MIT applies to this library.

Data configuration

This project is intended to be used to create KeyValue storage as follows.
The content of the value can be anything, but it must be a string. For example, you can set up a JSON-format object, but it must be encoded as a string.

Installation

You can install it with the following command:

npm install nostr-key-value

How to use

After installing via npm in your project, use the following code.

GET

GET the specified object from the kind: 30078 stored on the Nostr relay.

getAll

Get all kind: 30078 that Author has.

getTable

Get the object whose table name matches from kind: 30078 which Author has.

getSingle

Searches a table from kind: 30078 which Author has, and gets the specified key of the table.

import { getAll, getTable, getSingle } from "nostr-key-value";

async () => {
  const all = await getAll([relayUrl], npub, 10);
  console.log(all);

  const table = await getTable([relayUrl], npub, "test_table");
  console.log("table", table);

  const single = await getSingle([relayUrl], npub, "test_table", "key1");
  console.log("single", single);
};

CREATE

This function returns the JSON required to create a new table.
The table creation is complete when the JSON is signed and submitted to the relay.

Please use nostr-tools or other tools to sign and submit the JSON. This library does not support it. Note: If an identical table already exists on the relay, it will be overwritten.

createTable

import { createTable } from "nostr-key-value";

const table_ev = createTable("table_name", "table_title");
post(table_ev);

// use: nostr-tools methods
const relayUrl = "wss://your-relay-url";
const relay = relayInit(relayUrl);
const post = async (ev) => {
  return new Promise((resolve, reject) => {
    const data = finishEvent(ev, nsec);
    const pub = relay.publish(data);
    pub.on("ok", () => {
      resolve("success");
    });
    pub.on("failed", () => {
      reject("failed");
    });
  });
};

createTableExists

Checks for the existence of a table before creating it. Returns null if the table already exists. If null, new creation of the table is protected.

import { createTable } from "nostr-key-value";

const table_ev = createTableExists(
  [relayUrl],
  npub,
  "table_name",
  "table_title"
);
// use: nostr-tools post methods.
if(table_ev) post(table_ev);

INSERT, UPDATE

This function returns the JSON required to add or update data to a table.
The table update is complete when the JSON is signed and sent to the relay.

JSON should be signed and submitted using nostr-tools or similar. This is not supported by this library. Note that note rollback is not available.

upsertTable

import { upsertTable } from "nostr-key-value";

const options = [
  ["option_key0", "value"],
  ["option_key1", "value"],
  ["option_key2", "value"],
];
const values = [
  ["data_key0", "value"],
  ["data_key1", "value"],
  ["data_key2", "value"],
  ["data_key3", "value"],
  ["data_key4", "value"],
];

const table_ev = upsertTable([relayUrl], npub, "table_name", options, values);
// use nostr tools posts;
post(table_ev);

upsertTableOrCreate

If the tables do not match, a new one is created and records are inserted.

import { upsertTable } from "nostr-key-value";

const options = [
  ["option_key0", "value"],
  ["option_key1", "value"],
  ["option_key2", "value"],
];
const values = [
  ["data_key0", "value"],
  ["data_key1", "value"],
  ["data_key2", "value"],
  ["data_key3", "value"],
  ["data_key4", "value"],
];

const table_ev = upsertTableOrCreate(
  [relayUrl],
  npub,
  "table_name",
  "table_title",
  options,
  values
);
// use nostr tools posts;
post(table_ev);

CLEAR

This function returns JSON to clear the data in the table.
The table update is complete when the JSON is signed and sent to the relay.

Please use nostr-tools or other tools to sign and submit the JSON. This is not supported by this library. Note that note rollback is not available.

clearTable

import { upsertTable } from "nostr-key-value";

const options = [
  ["option_key0", "value"],
  ["option_key1", "value"],
  ["option_key2", "value"],
];
const table_ev = upsertTable([relayUrl], npub, "table_name", options.length);
// use nostr tools posts;
post(table_ev);

ユーティリティ

Useful items are provided. The following functions are provided

utilKeyValueArrayToObject

import { utilKeyValueArrayToObject } from "nostr-key-value";
const values = [
  ["data_key0", "value"],
  ["data_key1", "value"],
  ["data_key2", "value"],
  ["data_key3", "value"],
  ["data_key4", "value"],
];
const objects = utilKeyValueArrayToObject(values);

utilObjectToKeyValueArray

import { utilObjectToKeyValueArray } from "nostr-key-value";
const object = {
  data_key0: "value",
  data_key1: "value",
  data_key2: "value",
  data_key3: "value",
  data_key4: "value",
};
const values = utilObjectToKeyValueArray(values);