Операции

API Deno KV предоставляет набор операций, которые могут быть выполнены над пространством ключей.

Существуют две операции, которые считывают данные из хранилища, и пять операций, которые записывают данные в хранилище.

Операции чтения могут выполняться в режиме сильной или слабой согласованности. Режим сильной согласованности гарантирует, что операция чтения вернёт последнее записанное значение. Режим слабой согласованности может вернуть устаревшее значение, но он быстрее.

Операции записи всегда выполняются в режиме сильной согласованности.

get

Операция get возвращает значение и отметку времени версии, связанные с заданным ключом. Если значение не существует, get возвращает значение null и отметку времени версии.

Существуют два API, которые могут быть использованы для выполнения операции get. API Deno.Kv.prototype.get(key, options?), который может быть использован для чтения одного ключа, и API Deno.Kv.prototype.getMany(keys, options?), который может быть использован для одновременного чтения нескольких ключей.

Операции get выполняются как «моментальный снимок» во всех режимах согласованности. Это означает, что при одновременном извлечении нескольких ключей возвращаемые значения будут согласованными друг с другом.

const res = await kv.get<string>(["config"]);
console.log(res); // { key: ["config"], value: "value", versionstamp: "000002fa526aaccb0000" }

const res = await kv.get<string>(["config"], { consistency: "eventual" });
console.log(res); // { key: ["config"], value: "value", versionstamp: "000002fa526aaccb0000" }

const [res1, res2, res3] = await kv.getMany<[string, string, string]>([
  ["users", "sam"],
  ["users", "taylor"],
  ["users", "alex"],
]);
console.log(res1); // { key: ["users", "sam"], value: "sam", versionstamp: "00e0a2a0f0178b270000" }
console.log(res2); // { key: ["users", "taylor"], value: "taylor", versionstamp: "0059e9035e5e7c5e0000" }
console.log(res3); // { key: ["users", "alex"], value: "alex", versionstamp: "00a44a3c3e53b9750000" }

list

Операция list возвращает список ключей, которые соответствуют заданному селектору. Также возвращаются связанные значения и отметки времени версий для этих ключей. Существуют 2 разных селектора, которые могут быть использованы для фильтрации соответствий ключей.

Селектор prefix соответствует всем ключам, которые начинаются с заданных частей префиксного ключа, но не включая точное совпадение ключа. К селектору префикса можно необязательно добавить start или end ключи, чтобы ограничить диапазон возвращаемых ключей. Ключ start включительно, а ключ end — исключающий.

Селектор range соответствует всем ключам, которые лексикографически находятся между заданными ключами start и end. Ключ start включительно, а ключ end — исключающий.

Примечание: в случае с селектором префикса ключ prefix должен состоять только из полных (а не частичных) частей ключа. Например, если ключ ["foo", "bar"] существует в хранилище, то селектор префикса ["foo"] будет соответствовать ему, но селектор префикса ["f"] — нет.

Операция list может необязательно получить limit для ограничения количества возвращаемых ключей.

Операции list могут быть выполнены с использованием метода Deno.Kv.prototype.list<string>(selector, options?). Этот метод возвращает Deno.KvListIterator, который может быть использован для итерации по возвращенным ключам. Это асинхронный итератор, который может использоваться с циклами for await.

// Return all users
const iter = kv.list<string>({ prefix: ["users"] });
const users = [];
for await (const res of iter) users.push(res);
console.log(users[0]); // { key: ["users", "alex"], value: "alex", versionstamp: "00a44a3c3e53b9750000" }
console.log(users[1]); // { key: ["users", "sam"], value: "sam", versionstamp: "00e0a2a0f0178b270000" }
console.log(users[2]); // { key: ["users", "taylor"], value: "taylor", versionstamp: "0059e9035e5e7c5e0000" }

// Return the first 2 users
const iter = kv.list<string>({ prefix: ["users"] }, { limit: 2 });
const users = [];
for await (const res of iter) users.push(res);
console.log(users[0]); // { key: ["users", "alex"], value: "alex", versionstamp: "00a44a3c3e53b9750000" }
console.log(users[1]); // { key: ["users", "sam"], value: "sam", versionstamp: "00e0a2a0f0178b270000" }

// Return all users lexicographically after "taylor"
const iter = kv.list<string>({ prefix: ["users"], start: ["users", "taylor"] });
const users = [];
for await (const res of iter) users.push(res);
console.log(users[0]); // { key: ["users", "taylor"], value: "taylor", versionstamp: "0059e9035e5e7c5e0000" }

// Return all users lexicographically before "taylor"
const iter = kv.list<string>({ prefix: ["users"], end: ["users", "taylor"] });
const users = [];
for await (const res of iter) users.push(res);
console.log(users[0]); // { key: ["users", "alex"], value: "alex", versionstamp: "00a44a3c3e53b9750000" }
console.log(users[1]); // { key: ["users", "sam"], value: "sam", versionstamp: "00e0a2a0f0178b270000" }

// Return all users starting with characters between "a" and "n"
const iter = kv.list<string>({ start: ["users", "a"], end: ["users", "n"] });
const users = [];
for await (const res of iter) users.push(res);
console.log(users[0]); // { key: ["users", "alex"], value: "alex", versionstamp: "00a44a3c3e53b9750000" }

Операция list считывает данные из хранилища по частям. Размер каждой части может быть контролируемым с помощью параметра batchSize. Размер части по умолчанию составляет 500 ключей. Данные внутри части читаются как единый моментальный снимок, поэтому значения согласованы друг с другом. Режимы согласованности применяются к каждой части считанных данных. Между частями данные не согласованы. Границы между частями не видны из API, так как итератор возвращает отдельные ключи.

Операция list может быть выполнена в обратном порядке, установив параметр reverse в true. Это вернёт ключи в лексикографически убывающем порядке. Ключи start и end по-прежнему являются включительным и исключительным соответственно, и по-прежнему интерпретируются как лексикографически возрастающие.

// Return all users in reverse order, ending with "sam"
const iter = kv.list<string>({ prefix: ["users"], start: ["users", "sam"] }, {
  reverse: true,
});
const users = [];
for await (const res of iter) users.push(res);
console.log(users[0]); // { key: ["users", "taylor"], value: "taylor", versionstamp: "0059e9035e5e7c5e0000" }
console.log(users[1]); // { key: ["users", "sam"], value: "sam", versionstamp: "00e0a2a0f0178b270000" }

Примечание: в приведенном выше примере мы установили ключ start в ["users", "sam"], хотя первый возвращенный ключ — ["users", "taylor"]. Это потому, что ключи start и end всегда оцениваются в лексикографически возрастающем порядке, даже когда операция list выполняется в обратном порядке (что возвращает ключи в лексикографически убывающем порядке).

set

Операция set устанавливает значение ключа в хранилище. Если ключ не существует, он создается. Если ключ уже существует, его значение перезаписывается.

Операция set может быть выполнена с помощью метода Deno.Kv.prototype.set(key, value). Этот метод возвращает Promise , который разрешается в объект Deno.KvCommitResult, содержащий versionstamp коммита.

Операции set всегда выполняются в режиме сильной согласованности.

const res = await kv.set(["users", "alex"], "alex");
console.log(res.versionstamp); // "00a44a3c3e53b9750000"

delete

Операция delete удаляет ключ из хранилища. Если ключ не существует, операция игнорируется.

Операция delete может быть выполнена с помощью метода Deno.Kv.prototype.delete(key).

Операции удаления всегда выполняются в режиме сильной согласованности.

await kv.delete(["users", "alex"]);

sum

Операция sum атомарно добавляет значение к ключу в хранилище. Если ключ не существует, он создается со значением суммы. Если ключ уже существует, его значение добавляется к сумме.

Операция sum может быть выполнена только как часть атомарной операции. Метод Deno.AtomicOperation.prototype.mutate({ type: "sum", value }) может быть использован для добавления мутации суммы к атомарной операции.

Операция sum может быть выполнена только на значениях типа Deno.KvU64. И операнд, и значение в хранилище должны быть типа Deno.KvU64.

Если новое значение ключа больше 2^64 - 1 или меньше 0, операция sum переполняется. Например, если значение в хранилище — 2^64 - 1, а операнд — 1, то новое значение будет 0.

Операции sum всегда выполняются в режиме сильной согласованности.

await kv.atomic()
  .mutate({
    type: "sum",
    key: ["accounts", "alex"],
    value: new Deno.KvU64(100n),
  })
  .commit();

min

Операция min атомарно устанавливает ключ в минимальное значение из его текущего значения и заданного значения. Если ключ не существует, он создаётся со значением. Если ключ уже существует, его значение устанавливается в минимальное значение из текущего и заданного.

Операция min может быть выполнена только как часть атомарной операции. Метод Deno.AtomicOperation.prototype.mutate({ type: "min", value }) может быть использован для добавления мутации min к атомарной операции.

Операция min может быть выполнена только на значениях типа Deno.KvU64. И операнд, и значение в хранилище должны быть типа Deno.KvU64.

Операции min всегда выполняются в режиме сильной согласованности.

await kv.atomic()
  .mutate({
    type: "min",
    key: ["accounts", "alex"],
    value: new Deno.KvU64(100n),
  })
  .commit();

max

Операция max атомарно устанавливает ключ в максимальное значение из его текущего значения и заданного значения. Если ключ не существует, он создаётся со значением. Если ключ уже существует, его значение устанавливается в максимальное значение из текущего и заданного.

Операция max может быть выполнена только как часть атомарной операции. Метод Deno.AtomicOperation.prototype.mutate({ type: "max", value }) может быть использован для добавления мутации max к атомарной операции.

Операция max может быть выполнена только на значениях типа Deno.KvU64. И операнд, и значение в хранилище должны быть типа Deno.KvU64.

Операции max всегда выполняются в режиме сильной согласованности.

await kv.atomic()
  .mutate({
    type: "max",
    key: ["accounts", "alex"],
    value: new Deno.KvU64(100n),
  })
  .commit();

watch

Операция watch принимает массив ключей и возвращает ReadableStream, который генерирует новое значение всякий раз, когда любое из отслеживаемых ключей изменяет своё versionstamp. Возвращаемое значение — массив объектов Deno.KvEntryMaybe.

Обратите внимание, что возвращаемый поток не возвращает каждый промежуточный статус отслеживаемых ключей, а лишь поддерживает актуальность последнего статуса ключей. Это означает, что если ключ изменяется несколько раз быстро, вы можете не получить уведомление о каждом изменении, но получите последнее состояние ключа.

const db = await Deno.openKv();

const stream = db.watch([["foo"], ["bar"]]);
for await (const entries of stream) {
  entries[0].key; // ["foo"]
  entries[0].value; // "bar"
  entries[0].versionstamp; // "00000000000000010000"
  entries[1].key; // ["bar"]
  entries[1].value; // null
  entries[1].versionstamp; // null
}