---
title: "@unikvs/cookies"
description: "How to use @unikvs/cookies, which stores strings and bytes in HTTP cookies."
---

## Overview [#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:

```package-install
npm install @unikvs/cookies
```

## Usage [#usage]

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

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

### `Cookies` [#cookies]

Storage backed by cookies.

Constructor arguments:

| Prop | Type | Default | Description |
| - | - | - | - |
| `cookieAttributes?` | `[#cookies-cookie-attributes] CookieAttributes` | - | Attributes attached to every cookie. Specify path, domain, secure, sameSite, and maxAge. |
| `sizeLimitBytes?` | `[#cookies-size-limit-bytes] number` | `4096` | Maximum size (bytes) applied to both the raw value size and the serialized size. |
| `store?` | `[#cookies-store] CookieStoreLike` | - | Store used to read and write cookies. Uses document.cookie when omitted. |

The following example stores a value and reads it back.

```ts
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 [#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 [#errors]

This package throws the following errors.

### CookieTooLargeError [#error-cookie-too-large]

| Prop | Type | Default | Description |
| - | - | - | - |
| `key` | `[#error-cookie-too-large-key] string` | - | The key being written. |
| `actual` | `[#error-cookie-too-large-actual] number` | - | The size (bytes) that exceeded the limit. |
| `limit` | `[#error-cookie-too-large-limit] number` | - | The applied sizeLimitBytes. |
| `measurement` | `[#error-cookie-too-large-measurement] "raw" \| "serialized"` | - | Whether actual is the raw size or the serialized size. Defaults to "raw" when omitted from the constructor. |

#### 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 [#error-cookie-not-available]

#### Meaning

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

#### How to fix

Pass an implementation satisfying `CookieStoreLike` as `store`.

### KeyNotFoundError [#error-key-not-found]

#### 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`.

```ts
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;
  }
}
```