@unikvs/readonly

How to use @unikvs/readonly, which rejects writes to make storage read-only.

Overview

@unikvs/readonly Middleware rejects writes to make storage read-only.

It rejects write-direction operations (set / copy / move / encode) and passes reads through. When allowDelete is false, it also rejects deletion.

• name is ReadOnly.
• isOpen is always true.
• allowDelete defaults to false.

Install with:

npm install @unikvs/readonly

pnpm add @unikvs/readonly

yarn add @unikvs/readonly

bun add @unikvs/readonly

nub add @unikvs/readonly

aube add @unikvs/readonly

Usage

ReadOnly implements IMiddleware. Pass it to UniKvs with use().

import { ReadOnly } from "@unikvs/readonly";

ReadOnly

Middleware that rejects writes to make storage read-only.

Constructor arguments:

The following reads back stored values:

import { Memory } from "@unikvs/memory";
import { ReadOnly } from "@unikvs/readonly";
import * as unikvs from "unikvs";

const storage = new Memory();
const writer = new unikvs.Builder<{
  foo: unikvs.Value<Uint8Array>;
}>()
  .persist(storage)
  .build();

await writer.open();
await writer.set("foo", new Uint8Array([0, 1, 2]));
await writer.close();

const kvs = new unikvs.Builder<{
  foo: unikvs.Value<Uint8Array>;
}>()
  .use(new ReadOnly())
  .persist(storage)
  .build();

await kvs.open();

const data = await kvs.get("foo");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();

Data types

• The write direction always fails; the read direction performs no conversion and passes through.
• copy and move are rejected because they write to the destination key.
• Deletion is controlled by use(): when allowDelete is false, delete and clear are rejected.

Errors

Errors thrown by this package:

ReadOnlySetNotAllowedError

Meaning

Thrown when a write-direction operation (set / copy / move / encode) is called.

How to fix

Do not use this middleware when writes are needed.

Example

Catching ReadOnlySetNotAllowedError:

import { ReadOnlySetNotAllowedError } from "@unikvs/readonly";

try {
  await kvs.set("foo", new Uint8Array([0, 1, 2]));
} catch (ex) {
  if (ex instanceof ReadOnlySetNotAllowedError) {
    console.log("writes are not allowed");
  } else {
    throw ex;
  }
}

ReadOnlyDeleteNotAllowedError

Meaning

Thrown when delete is called while allowDelete is false.

How to fix

Pass allowDelete: true when deletion is needed.

ReadOnlyClearNotAllowedError

Meaning

Thrown when clear is called while allowDelete is false.

How to fix

Pass allowDelete: true when clearing everything is needed.