データはコピーせず、名前で共有する。

利用している拡張機能

ほかの拡張機能を支える基盤です。

Named Data 自体のブロックはほとんどありません。価値は、データを持つ拡張機能どうしが 共有する registry にあります。別々にバンドルされた拡張機能も、固定キー Symbol.for('@kubohiroya/turbowarp-named-data/registry') で同じ registry を見つけるため、読み込み順やバンドル構成によって registry が分裂しません。

はじめに

有効にする、読み込む、確かめる。

registry は起動時に固定される機能で、既定では無効です。フラグは バンドルの起動時に一度だけ読まれるため、拡張機能を読み込む前に設定してください。

1. 機能フラグを有効にする

   ホストページで、または動作確認ならエディタのブラウザコンソールで設定します。

   globalThis.__TW_NAMED_DATA_FEATURE_FLAGS__ = {
     NAMED_DATA_REGISTRY_MVP: true
   };

2. 拡張機能を読み込む

   TurboWarp で 拡張機能を追加 → カスタム拡張機能 を選び、次のファイルを指定して サンドボックスなしで実行 を有効にします。

   https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-named-data@0.4.0/dist/named-data.js

3. 使えるか確かめる

   唯一の真偽ブロックで、共有 registry が導入されたことを確認できます。

   もし <named data registry available?> なら
     [ready] と言う

仕組み

registry は振り分けるだけ。データは provider が持つ。

registry が保持するのは、(namespace, kind) をキーにした provider の登録と、 現在開かれている本体の解放コールバックだけです。payload、保存、キャッシュはすべて 各 provider の中にとどまります。

参照に含まれるもの

provider が返すもの

Composition API

自作の拡張機能から提供・利用する。

ほかのパッケージは副作用のない ESM エントリポイントを import します。import しても TurboWarp 拡張機能は登録されず、契約、registry 関数、機能フラグの宣言だけが公開されます。

pnpm add --save-exact @kubohiroya/turbowarp-named-data@0.4.0

import {
  installNamedDataRegistry,
  type NamedDataProvider
} from '@kubohiroya/turbowarp-named-data/composition';

const registry = installNamedDataRegistry(runtime);
const provider: NamedDataProvider = {
  namespace: 'com.example.notes',
  kind: 'document',
  canResolve: (ref, rep) => rep === 'markdown',
  stat: (ref, rep, ctx) => ({ /* メタデータ */ }),
  openBody: (ref, rep, ctx) => ({ /* メタデータ, body, release */ }),
  release: () => {}
};
const registration = registry.registerProvider(provider);

import {getNamedDataRegistry}
  from '@kubohiroya/turbowarp-named-data/composition';

const registry = getNamedDataRegistry(runtime);
const opened = await registry?.openBody(
  {namespace: 'com.example.notes', name: 'intro',
   kind: 'document', scope: 'project'},
  'markdown',
  {project: projectIdentity}
);
try {
  // opened.body を読む
} finally {
  await opened?.release('complete');
}

型定義は dist/types/composition.d.ts から提供されます。通信で扱える参照の形は JSON Schema としても公開しています。

ライフサイクルと schema 識別子

停止で片付け、schema は名前で指定し推測しない。

プロジェクトを停止したとき

1. 開いているすべての本体ハンドルが解放されます。
2. セッション provider は登録解除され、解放されます。
3. 永続 provider は登録を保ったまま clearSession() を実行します。

{lifetime: 'persistent'} を指定しない登録はセッション単位です。解放処理は 冪等なので、provider を複数回解放しても安全です。

任意の schema 参照

structured 参照には schemaRef: {id, version} を付けられます。例： {id: 'com.example.profile', version: '1.2.0'}。provider はメタデータで まったく同じ識別子を返す必要があります。registry が運ぶのは識別子だけで、schema 文書、 バリデータ、JSON 値は provider と利用側の責任です。provider が schema 参照を公開するのは、 別の起動時フラグ NAMED_DATA_SCHEMA_REF が有効なとき（既定は無効）だけです。

リファレンス

ブロック・フラグ・エラーコード

ブロックの全仕様は英語版の完全なブロックリファレンスを参照してください。

エラーコード

トラブル対処

参照が解決できないとき