@unikvs/cookies

HTTP Cookie に文字列とバイト列を保存する @unikvs/cookies の使い方を説明します。

概要

@unikvs/cookies は HTTP Cookie をバックエンドに使うストレージです。

このストレージは文字列とバイト列を Cookie に保存できる形へ変換します。バイト列は Base64 化し、キーと値は URL エンコードして保存します。

• name は Cookies です。
• isOpen は常に true です。open() は Cookie ストアの利用可否を確認します。
• すべての操作は同期実装です。
• delete は存在しないキーを指定した場合は KeyNotFoundError を投げます。
• ストリームの読み書きには対応していません。

インストールは次のコマンドで行います。

npm install @unikvs/cookies

pnpm add @unikvs/cookies

yarn add @unikvs/cookies

bun add @unikvs/cookies

nub add @unikvs/cookies

aube add @unikvs/cookies

使い方

Cookies は IStorage を実装しています。UniKvs には persist() で渡します。

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

Cookies

Cookie をバックエンドに使うストレージです。

コンストラクターの引数は次のとおりです。

以下は、値を保存して読み戻す例です。

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();

データ型

• 文字列とバイト列を保存できます。文字列には s:、バイト列には Base64 化した値に b: の接頭辞を付けて保存します。
• 値の生サイズ (文字列は UTF-8 バイト数、バイト列はバイト数) が sizeLimitBytes を超えると保存できません。
• 生サイズが上限内でも、URL エンコードした名前と値に属性を加えた Set-Cookie 文字列のサイズが sizeLimitBytes を超える場合は保存できません。
• 空のキーを指定すると write が TypeError を投げます。
• document.cookie が使えない環境では store に CookieStoreLike を注入します。
• ストリームの読み書きには対応していません。

エラー

このパッケージが投げるエラーは次のとおりです。

CookieTooLargeError

意味

生サイズ (文字列は UTF-8 バイト数、バイト列はバイト数) が sizeLimitBytes を超えた場合、またはシリアル化後の Set-Cookie 文字列のサイズが sizeLimitBytes を超えた場合に write が投げます。シリアル化後のサイズには、URL エンコードした名前と値、および cookieAttributes で指定した属性が含まれます。どちらのサイズで超過したかは meta.measurement で判別できます。

対処方法

値を小さくするか、sizeLimitBytes を大きくしてください。シリアル化後のサイズだけが上限を超える場合は、キーや値を短くするか、属性を減らしてください。Cookie にはブラウザーごとの上限もあるため、大きな値は別のストレージに保存してください。

CookieNotAvailableError

意味

document.cookie が使えず store の注入もないときに投げます。

対処方法

store に CookieStoreLike を満たす実装を渡します。

KeyNotFoundError

意味

指定したキーが存在しないときに read・delete が投げます。@unikvs/core の共通エラーです。

対処方法

exists で確認してから読み出すか削除します。

例

以下は、KeyNotFoundError を捕捉する例です。

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

try {
  const data = await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("キーが見つかりません");
  } else {
    throw ex;
  }
}