コンポーネントと状態のユーティリティ

@blocklet/metaライブラリは、BlockletStateオブジェクトとの対話を簡素化するために設計された、包括的なユーティリティ関数のスイートを提供します。Blocklet、特に複合Blockletは、コンポーネントのツリーとして表現されます。これらのユーティリティは、このツリーを走査し、特定のコンポーネントを見つけ、その状態を確認し、ランタイム操作、UIレンダリング、および管理タスクのための重要な情報を抽出するための強力で効率的な方法を提供します。

このセクションでは、ツリー走査、コンポーネント検索、状態確認、設定管理、および情報抽出のための関数について説明します。

ツリー走査

これらの関数を使用すると、Blockletアプリケーションのコンポーネントツリーを反復処理できます。これらは、すべてのコンポーネントに操作を適用したり、データを集約したりするための基本です。

forEachBlocklet & forEachBlockletSync

中心となる走査関数です。forEachBlockletは非同期で、直列（デフォルト）または並列で実行できます。一方、forEachBlockletSyncはその同期版です。

Function Signature

function forEachBlocklet(
  blocklet: TComponentPro,
  cb: (blocklet: TComponentPro, context: object) => any,
  options?: {
    parallel?: boolean;
    concurrencyLimit?: number;
    sync?: boolean;
  }
): Promise<any> | null;

function forEachBlockletSync(
  blocklet: any,
  cb: Function
): void;

コールバック関数 cb は、現在のコンポーネントと { parent, root, level, ancestors, id } を含むコンテキストオブジェクトを受け取ります。

例：すべてのコンポーネントDIDを収集する

import { forEachBlockletSync } from '@blocklet/meta/lib/util';

const appState = {
  meta: { did: 'z1' },
  children: [
    { meta: { did: 'z2' } },
    {
      meta: { did: 'z3' },
      children: [{ meta: { did: 'z4' } }],
    },
  ],
};

const allDids = [];
forEachBlockletSync(appState, (component) => {
  if (component.meta?.did) {
    allDids.push(component.meta.did);
  }
});

console.log(allDids);
// Output: ['z1', 'z2', 'z3', 'z4']

forEachChild & forEachChildSync

これらは forEachBlocklet のラッパーであり、ルートBlocklet自体（level > 0 の場合）をスキップして、Blockletのすべての子孫を便利に反復処理します。

コンポーネントの検索とフィルタリング

状態ツリー内で特定のコンポーネントを見つけることは一般的な要件です。これらの関数は、さまざまな基準に基づいて1つ以上のコンポーネントを見つけるためのさまざまな方法を提供します。

findComponent

コンポーネントツリーを走査し、提供された述語関数を満たす最初のコンポーネントを返す汎用検索関数です。

Function Signature

function findComponent(
  blocklet: TComponent,
  isEqualFn: (component: TComponent, context: { ancestors: Array<TComponent> }) => boolean
): TComponent | null;

例：bundleNameでコンポーネントを検索する

import { findComponent } from '@blocklet/meta/lib/util';

const appState = {
  meta: { did: 'z1', bundleName: 'app' },
  children: [
    { meta: { did: 'z2', bundleName: 'component-a' } },
    { meta: { did: 'z3', bundleName: 'component-b' } },
  ],
};

const componentB = findComponent(
  appState,
  (component) => component.meta?.bundleName === 'component-b'
);

console.log(componentB.meta.did);
// Output: 'z3'

findComponentById

findComponent の特化版で、一意の複合ID（例： app-did/component-did）でコンポーネントを検索します。

Function Signature

function findComponentById(
  blocklet: TComponent,
  componentId: string | string[]
): TComponent | null;

filterComponentsV2

アプリの直接の子を反復処理し、述語関数を満たすすべてのコンポーネントの配列を返します。

IDと命名

これらのユーティリティは、アプリケーションの状態内のコンポーネントのさまざまな識別子と名前を生成および取得するのに役立ちます。

設定と状態管理

設定の管理は、特に設定を共有できる複合Blockletにおいて重要です。これらのヘルパーはそのプロセスを簡素化します。

getSharedConfigObj

アプリケーション内の特定のコンポーネントの共有設定オブジェクトを計算します。親アプリケーションと shared: true とマークされた兄弟コンポーネントからの設定をインテリジェントにマージします。

getAppMissingConfigs & getComponentMissingConfigs

これらの関数は検証に不可欠です。アプリケーションまたは単一のコンポーネントをスキャンし、required: true とマークされているが、直接または共有設定メカニズムを介して値が割り当てられていないすべての設定のリストを返します。

例：不足している設定の確認

import { getAppMissingConfigs } from '@blocklet/meta/lib/util';

const appWithMissingConfig = {
  meta: { did: 'z1' },
  children: [
    {
      meta: { did: 'z2' },
      configs: [
        { key: 'API_KEY', required: true, value: null, description: 'Service API Key' },
      ],
    },
  ],
};

const missing = getAppMissingConfigs(appWithMissingConfig);

console.log(missing);
// Output: [{ did: 'z2', key: 'API_KEY', description: 'Service API Key' }]

wipeSensitiveData

Blockletの状態オブジェクトのディープクローンを作成し、すべての機密情報を編集するセキュリティ重視のユーティリティです。secure: true とマークされたフィールドの値と、特定の機密環境変数（BLOCKLET_APP_SKなど）の値を __encrypted__ に置き換えます。

状態チェック

これらのブール関数は、生のステータスコードを直接処理することなく、Blockletまたはコンポーネントの現在の状態を確認する簡単な方法を提供します。

インターフェースとサービスの検出

Blockletのメタデータで定義されたインターフェースとサービスを見つけるためのユーティリティです。

情報抽出

これらの関数は、生のBlocklet状態から特定の処理済み情報を抽出します。

getComponentsInternalInfo

この関数はBlockletアプリケーションを走査し、各コンポーネントの主要な内部詳細を含む構造化された配列を返します。これはシステム管理やサービス間通信に非常に便利です。

戻り値

getMountPoints

コンポーネントツリー全体をスキャンし、マウントポイントを持つすべてのコンポーネントの構造化されたリストを返します。これにより、ナビゲーションやルーティングテーブルの構築が容易になります。

getAppUrl

site.domainAliases を分析して、Blockletアプリケーションのプライマリなユーザー向けURLを決定します。アクセス可能で保護されていないURLを優先するようにドメインをインテリジェントにソートします。

その他のユーティリティ

その他の便利なチェックとヘルパーのコレクション。