パイプラインコンテキスト

@unikvs/core のパイプラインコンテキスト。IPipelineContext による実行時変数の読み書きと操作ごとのコンテキスト一覧を説明します。

概要

パイプラインコンテキストは操作ごとに受け渡される実行時変数 (vars) を読み書きする窓口です。すべてのコンテキストが IPipelineContext を継承し、操作の種類ごとに key・signal・source などの情報が追加されます。

プラグイン作者はフックの引数として渡されるコンテキストからキーやシグナルを取り出し、vars から動作設定を読み取ります。

変数の読み書き

get・set・setReadonly の 3 メソッドで変数を扱います。set 系は this を返すため、メソッドチェーンできます。

import type { IPipelineContext } from "@unikvs/core";

declare const ctx: IPipelineContext<{ readonly count: number }>;

const count: number = ctx.get("count"); // 型付きで取得
const unknownValue: unknown = ctx.get("anything-else"); // 未登録のキーは unknown

ctx.set("count", 1).setReadonly("count", 2); // this を返すため連鎖できる

型引数で { count: number } のように宣言すると、そのキーの取得と設定が型付けされます。宣言にないキーは unknown として扱われ、誤った型の代入は型エラーになります。

// @ts-expect-error count は number のため文字列は渡せない
ctx.set("count", "not a number");

宣言マージ

グローバルな UniKvsPipelineContextTypes への宣言マージでも型を足せます。複数のプラグインが共有する変数名を一箇所で定義するときに使います。

declare global {
  interface UniKvsPipelineContextTypes {
    readonly "test:count": number;
  }
}

declare const ctx: IPipelineContext;

const count: number = ctx.get("test:count");
ctx.set("test:count", 1); // 文字列の代入は型エラー

型引数の宣言と UniKvsPipelineContextTypes の宣言マージは結合され、どちらかにあるキーは型付きで解決されます。どちらにもないキーは unknown です。

コンテキストの階層

コンテキストは層状に継承されます。下の層ほど操作が特定され、持つ情報が増えます。

コンテキストの一覧

操作の種類ごとに含まれる情報が決まっています。

キーとライフサイクル

IMapKeyContext はキー変換専用で key のみを持ちます (ミドルウェアの mapKey で使います)。signal は持ちません。

IActionContext は signal: AbortSignal と 10 種の action ("open" | "close" | "set" | "get" | "stream" | "has" | "delete" | "clear" | "copy" | "move") を持ちます。ILifecycleContext は "open" | "close" に絞られ、IOpenContext・ICloseContext はそれぞれ 1 種に絞られます。

キー操作

IKeyedActionContext は key: string を加え、action を "set" | "get" | "stream" | "has" | "delete" | "copy" | "move" の 7 種に絞ります。以降の ISetContext・IGetContext・IStreamContext・IHasContext・IDeleteContext は action を 1 種に固定します。ITransferContext は action を "copy" | "move" に絞り、コピー先・移動先の destinationKey を加えます。ICopyContext と IMoveContext はそれぞれ action を "copy"・"move" に固定します。IClearContext はキーを伴わないため IKeyedActionContext ではなく IActionContext を直接継承し、action は "clear" です。

ミドルウェアの use フックはこれら 8 種 (set・get・stream・has・delete・copy・move・clear) をまとめて受けます。action で絞り込むと、各操作の key や repair、destinationKey に型安全に触れます。

import type { IMiddleware } from "@unikvs/core";

export function describe(use: IMiddleware.UseContext): string {
  switch (use.action) {
    case "set":
    case "get":
    case "stream":
    case "has":
    case "delete":
    case "copy":
    case "move": {
      return `${use.action}: ${use.key}`;
    }
    case "clear": {
      return "clear";
    }
  }
}

変換

ITransformContext は変換前後の値を運びます。source が入力で、destination (任意) に変換結果を代入します。

データ変換 (ITransformDataContext 系) の source と destination は値そのものです。一方、ストリーム変換 (ITransformStreamContext 系) の source と destination は IReadableStream です。値かチャンクかを型引数で確認します。詳しくはストリームを参照してください。

書き戻し

IGetContext と IStreamContext は読み取り時の書き戻し (repair) 要求を持ちます。後段のストレージで見つかった値を前段へ書き戻すかどうかが入ります。

import type { IGetContext } from "@unikvs/core";

declare const ctx: IGetContext;

if (ctx.repair.enabled) {
  console.log(ctx.repair.targets); // readonly [string, ...string[]] (1 件以上)
} else {
  console.log(ctx.repair.targets); // readonly [] (空)
}

enabled が false のとき targets は空配列、true のとき 1 件以上の表示名の配列です。enabled で絞り込むと targets の中身に型安全に触れます。書き戻しが拒否された場合は RepairNotAllowedError が使われます。可否は @unikvs/allow-repair で制御します。

API リファレンス

シンボルごとのリファレンスです。各メンバーの行にも直接リンクできます。

IPipelineContext

実行時変数 (vars) を読み書きする窓口です。すべてのコンテキストが継承します。

IMapKeyContext

キー変換専用のコンテキストです。key のみを持ちます。

IActionContext

signal と 10 種の action を持つ、すべての操作に共通するコンテキストです。

ILifecycleContext

action を "open" | "close" に絞ったライフサイクル用コンテキストです。

IOpenContext

action を "open" に固定した初期化用コンテキストです。

ICloseContext

action を "close" に固定した終了処理用コンテキストです。

IKeyedActionContext

key を加え、action をキー操作の 7 種に絞ったコンテキストです。

ISetContext

action を "set" に固定した書き込み用コンテキストです。

IGetContext

action を "get" に固定した読み取り用コンテキストです。書き戻し (repair) 要求を持ちます。

IStreamContext

action を "stream" に固定したストリーム読み取り用コンテキストです。書き戻し (repair) 要求を持ちます。

IHasContext

action を "has" に固定した存在確認用コンテキストです。

IDeleteContext

action を "delete" に固定した削除用コンテキストです。

ITransferContext

コピー・移動に共通するコンテキストです。action は "copy" | "move" で、key がコピー元・移動元、destinationKey がコピー先・移動先です。

ICopyContext

action を "copy" に固定したコピー用コンテキストです。key と destinationKey は ITransferContext から継承します。

IMoveContext

action を "move" に固定した移動用コンテキストです。key と destinationKey は ITransferContext から継承します。

IClearContext

action を "clear" に固定した全削除用コンテキストです。キーを伴いません。

ITransformContext

変換前後の値を運ぶコンテキストです。source が入力で、destination に変換結果を代入します。

ITransformDataContext

値そのものを変換するデータ変換用コンテキストです。

IEncodeContext

action を "set" に固定したエンコード用コンテキストです。

IDecodeContext

action を "get" に固定したデコード用コンテキストです。

ITransformStreamContext

ストリームを変換するコンテキストです。source と destination は IReadableStream です。

IEncodeStreamContext

action を "set" に固定したストリームエンコード用コンテキストです。

IDecodeStreamContext

action を "stream" に固定したストリームデコード用コンテキストです。