@unikvs/memcached

Node.js から Memcached にバイト列を保存する @unikvs/memcached の使い方を説明します。

概要

@unikvs/memcached は Memcached にバイト列を保存するストレージプラグインです。Node.js 専用 複数ノードで共有するキャッシュの保存に使います。

• name は "Memcached" で、isOpen で開閉状態を確認します。
• open() で接続を確認し、使い終わったら close() で解放します。
• このストレージは、キーに既定で "unikvs:" の接頭辞を付与します。
• 接続先を省略した場合は、MEMCACHED_SERVERS（なければ MEMCACHIER_SERVERS、MEMCACHE_SERVERS）環境変数を使い、未設定のときは "127.0.0.1:11211" に接続します。

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

npm install @unikvs/memcached

pnpm add @unikvs/memcached

yarn add @unikvs/memcached

bun add @unikvs/memcached

nub add @unikvs/memcached

aube add @unikvs/memcached

別途 Memcached サーバーが必要です。

使い方

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

import { Memcached } from "@unikvs/memcached";

Memcached

Memcached に保存するストレージです。利用者は open() で開き、使い終わったら close() で閉じます。

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

MemcachedStorageOptions

Memcached のコンストラクターオプションです。

MemcachedClientLike

注入できる Memcached クライアントの最小形状です。memjs の Client はこの形状を満たします。

MemcachedServers

servers 引数として受け付ける形状です。文字列 ("host:port,host:port") またはその配列です。

MemcachedGetResult

get の戻り値として受け付ける形状です。

MemcachedGetResultValue

get の戻り値として受け付ける値の形状です。memjs は { value: Buffer | null, flags } を返します。

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

import { Memcached } from "@unikvs/memcached";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.PlainValue<Uint8Array> }>()
  .persist(new Memcached("127.0.0.1:11211"))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

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

await kvs.close();

データ型

• write・read にはバイト列 (Uint8Array<ArrayBuffer>) を使います。
• 値は Base64 でエンコードした文字列として保存します。
• ストリームの読み書きには対応していません。
• clear() はキー列挙の手段がないため、サーバー上の全キーを削除します。

エラー

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

InvalidTtlSecondsError

コンストラクターの ttlSeconds が 0 以上の有限数ではないときに投げます。

意味

ttlSeconds に 0 以上の有限数以外が指定されました。

対処方法

ttlSeconds に 0 以上の有限数 (秒) を指定してください。

InvalidConnectTimeoutError

コンストラクターの connectTimeout が有限の正数ではないときに投げます。

意味

connectTimeout に有限の正数 (ミリ秒) 以外が指定されました。

対処方法

connectTimeout に有限の正数 (ミリ秒) を指定してください。

ConnectTimeoutError

open() 時の接続確認がタイムアウトしたときに投げます。

意味

Memcached への接続確認が connectTimeout (既定値は 5000 ミリ秒) を超えても終わりませんでした。

対処方法

サーバーの起動状態と接続先を確認し、必要に応じて connectTimeout を延ばしてください。

KeyNotFoundError

@unikvs/core の共通エラーです。存在しないキーを読み取ったときに投げます。

意味

指定したキーが存在しません。@unikvs/core の共通エラーです。

対処方法

exists で確認してから読み出してください。

例

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

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

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