@unikvs/expiry

絶対時刻で有効期限を付与し、期限切れの読み取りを欠落として扱うミドルウェアです。

概要

Expiry は書き込んだ値に絶対時刻の有効期限を付与し、期限切れの読み取りを欠落として扱います。Middleware

期限付きのキャッシュや一時的なデータの保持に使います。期限切れの検出時には通知を受け取れます。

• name は Expiry です。
• isOpen は常に true です。
• 期限の指定は操作ごとの変数 @unikvs/expiry:expiresAt と、既定値 defaultExpiresAt で行います。
• 期限切れの get とストリーム読み取りは KeyNotFoundError として失敗します。

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

npm install @unikvs/expiry

pnpm add @unikvs/expiry

yarn add @unikvs/expiry

bun add @unikvs/expiry

nub add @unikvs/expiry

aube add @unikvs/expiry

使い方

Expiry は IMiddleware を実装しています。UniKvs には use() で渡します。

import { Expiry } from "@unikvs/expiry";

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

以下は、書き込みごとに有効期限を指定し、期限切れの読み取りを欠落として扱う例です。

import { Expiry } from "@unikvs/expiry";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ report: unikvs.PlainValue<string> }>()
  .use(new Expiry())
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("report", "hello", {
  vars: { "@unikvs/expiry:expiresAt": Date.now() + 60_000 },
});
console.log(await kvs.get("report")); // "hello"
await kvs.close();

Expiry

有効期限付きのエンベロープで値を包み、読み出し時に期限切れを判定するミドルウェアです。

ExpiryOptions

Expiry のコンストラクターが受け取るオプションです。既定値と時刻取得、通知を指定できます。

ExpiresAtInput

有効期限として指定できる値です。Date は絶対失効時刻、number は epoch ミリ秒、string は ISO 8601 形式の絶対失効時刻です。

ExpiryExpiredInfo

期限切れを検出したときに通知される情報です。

データ型

• encode は入力を { "@unikvs/expiry": 1, expiresAt: number | null, data: unknown } の形に包みます。指定も既定値もないときは expiresAt を null にします。
• decode はエンベロープを剥がして元の値を返し、包まれていない値はそのまま返します。
• decode と decodeStream は expiresAt が現在時刻以下のときに KeyNotFoundError を投げ、onExpire を呼び出します。
• ストリームではチャンクごとに 1 対 1 で包みと剥がしを行い、順序を保ちます。

エラー

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

ExpiryInvalidExpiresAtError

意味

expiresAt が Date・エポックミリ秒・ISO 8601 文字列のいずれでもないときに、このエラーが投げられます。コンストラクターの defaultExpiresAt と書き込みごとの変数の両方が検証対象です。

対処方法

Date、有限の数値 (epoch ミリ秒)、または Date.parse で解釈できる ISO 8601 文字列を指定してください。NaN や無限大、true などの値は受け付けません。

例

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

import { ExpiryInvalidExpiresAtError } from "@unikvs/expiry";

try {
  await kvs.set("report", "hello", { vars: { "@unikvs/expiry:expiresAt": "not-a-date" } });
} catch (ex) {
  if (ex instanceof ExpiryInvalidExpiresAtError) {
    console.log(ex.meta); // { key: "report", actual: "not-a-date" }
  } else {
    throw ex;
  }
}

期限切れの読み取りは @unikvs/core の KeyNotFoundError として失敗します。詳細はエラーを参照してください。