@unikvs/cookies

How to use @unikvs/cookies, which stores strings and bytes in HTTP cookies.

Overview

@unikvs/cookies is a storage backed by HTTP cookies.

This storage converts strings and bytes into a cookie-storable form. Bytes are Base64-encoded, and keys and values are URL-encoded before storing.

• name is Cookies.
• isOpen is always true. open() checks cookie store availability.
• All operations are synchronous.
• delete throws KeyNotFoundError for a missing key.
• Stream reading and writing are not supported.

Install with:

npm install @unikvs/cookies

pnpm add @unikvs/cookies

yarn add @unikvs/cookies

bun add @unikvs/cookies

nub add @unikvs/cookies

aube add @unikvs/cookies

Usage

Cookies implements IStorage. Pass it to UniKvs with persist().

import { Cookies } from "@unikvs/cookies";

Cookies

Storage backed by cookies.

Constructor arguments:

The following example stores a value and reads it back.

import { Cookies } from "@unikvs/cookies";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  foo: unikvs.Value<string>;
}>()
  .persist(new Cookies())
  .build();

await kvs.open();
await kvs.set("foo", "hello");

const data = await kvs.get("foo");
console.log(data); // "hello"

await kvs.close();

Data types

| Operation | Supported data type | | ––––––– | ––––––––––––– | ———— | | write/read | Strings and bytes (string | Uint8Array) |

• Stores strings and bytes. Strings are stored with an s: prefix, bytes as Base64 with a b: prefix.
• Values whose raw size (UTF-8 bytes for strings, byte length for bytes) exceeds sizeLimitBytes cannot be stored.
• Even when the raw size is within the limit, a value cannot be stored when the size of the Set-Cookie string, including the URL-encoded name, value, and attributes, exceeds sizeLimitBytes.
• write throws a TypeError when the key is empty.
• Inject a CookieStoreLike as store in environments without document.cookie.
• Stream reading and writing are not supported.

Errors

This package throws the following errors.

CookieTooLargeError

Meaning

write throws it when the raw size (UTF-8 bytes for strings, byte length for bytes) exceeds sizeLimitBytes, or when the size of the serialized Set-Cookie string exceeds sizeLimitBytes. The serialized size includes the URL-encoded name, the URL-encoded value, and the attributes specified in cookieAttributes. Use meta.measurement to tell which size exceeded the limit.

How to fix

Make the value smaller or raise sizeLimitBytes. When only the serialized size exceeds the limit, shorten the key or value, or reduce the attributes. Browsers also impose their own cookie limits, so store large values in another storage.

CookieNotAvailableError

Meaning

Thrown when document.cookie is unavailable and no store was injected.

How to fix

Pass an implementation satisfying CookieStoreLike as store.

KeyNotFoundError

Meaning

read and delete throw it when the specified key does not exist. A shared error from @unikvs/core.

How to fix

Check with exists before reading or deleting.

Example

The following example catches KeyNotFoundError.

import { KeyNotFoundError } from "@unikvs/cookies";

try {
  const data = await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("Key not found");
  } else {
    throw ex;
  }
}