SyncFolderPullCommand

SyncFolderPullCommandは、DID Spaceからローカルフォルダにリモートディレクトリを同期するために設計された高レベルのコマンドです。リモートのソースとローカルのターゲット間のファイルをインテリジェントに比較し、新しいファイルまたは更新されたファイルのみをダウンロードします。これにより、ローカルディレクトリがリモートデータの最新のミラーであることが効率的に保証されます。

このコマンドは、ローカルの変更をリモートディレクトリにアップロードするために使用されるSyncFolderPushCommandの対となるものです。

ユースケース

このコマンドは、ユーザーのSpaceからファイルのコレクションを取得する必要があるシナリオに最適です。一般的なユースケースは次のとおりです。

ユーザーの写真ギャラリーをローカルアプリケーションにダウンロードする。
Spaceからローカルマシンにアプリケーションデータのバックアップを復元する。
ローカルのワークスペースをSpaceに保存されているマスターバージョンと同期し続ける。

入力パラメータ

コマンドのコンストラクタは、以下のフィールドを持つ単一のオブジェクトを受け入れます。

source string (required) — ファイルを取得するDID Space内のソースディレクトリパスです。パスは「/」で終わる必要があります。
target string (required) — ファイルがダウンロードされるローカルファイルシステム上の保存先パスです。このディレクトリが存在しない場合、コマンドは自動的に作成します。
concurrency number (default: 4) — 並行してダウンロードするファイルの数です。この値を増やすと、多数の小さなファイルがあるディレクトリの処理速度が向上する可能性があります。最大値は利用可能なCPUコア数によって制限されます。
retryCount number (default: 3) — 特定のファイルのダウンロードが失敗した場合に、エラーとしてマークする前に再試行する回数です。最大値は10です。
filter (object: Object) => boolean — 各リモートオブジェクトに対して呼び出される関数です。オブジェクトを同期プロセスに含める場合はtrueを、スキップする場合はfalseを返します。これは、名前やサイズなどのプロパティに基づいてファイルを選択的にダウンロードする場合に便利です。
onProgress (params: OnProgressInput) => void — 各ファイルがダウンロードプロセスを開始するたびにトリガーされるコールバック関数です。現在の進捗状況を含むオブジェクトを受け取ります。
- completed number — ダウンロードを開始したファイルの数です。
- total number — ダウンロードされるファイルの総数です。
- key string — 現在処理中のファイルのキー（相対パス）です。
onAfterUpload (params: OnAfterUploadInput) => void — 各ファイルが正常にダウンロードされた後にトリガーされるコールバック関数です。注意：名前は「onAfterUpload」ですが、プルコマンドの場合、これはダウンロードの完了を意味します。
- completed number — これまでに正常にダウンロードされたファイルの数です。
- total number — ダウンロードされるファイルの総数です。
- key string — ダウンロードが完了したばかりのファイルのキー（相対パス）です。
debug boolean (default: false) — trueに設定すると、コンソールでの詳細なログ記録が有効になり、同期プロセスのデバッグに役立ちます。
strictSync boolean (default: false) — このパラメータはSyncFolderPullCommandには影響しません。このコマンドはローカルディレクトリに対して非破壊的であるように設計されており、リモートソースに存在しないローカルファイルを削除することはありません。

出力

spaceClient.send()メソッドは、操作の結果を含むオブジェクトに解決されるPromiseを返します。

statusCode number — リクエストの結果を示します。値200は、同期操作全体が正常に完了したことを意味します。
data object — 同期操作の概要を含むオブジェクトです。
- count number — ダウンロードがスケジュールされたファイルの総数です。
- errorCount number — すべての再試行後にダウンロードに失敗したファイルの数です。
- size number — 正常にダウンロードされたすべてのファイルの合計サイズ（バイト単位）です。
- duration number — 操作にかかった合計時間（秒単位）です。
statusMessage string — コマンド全体の実行に失敗した場合（例：認証の問題など）のエラーメッセージです。
stack string — 回復不可能なエラーが発生した場合のスタックトレースです。

例

SyncFolderPullCommandを使用してリモートディレクトリをローカルフォルダにダウンロードし、その進捗を追跡する方法は次のとおりです。

例

import { SpaceClient, SyncFolderPullCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import { ensureDirSync, removeSync } from 'fs-extra';
import path from 'path';

const main = async () => {
  // 1. SpaceClientを初期化
  const wallet = getWallet();
  const spaceClient = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  // 2. ダウンロード用のローカルディレクトリを準備
  const localTarget = path.join(__dirname, 'my-pulled-assets');
  removeSync(localTarget); // この例のために以前の実行をクリーンアップ
  ensureDirSync(localTarget);
  console.log(`Downloading files to: ${localTarget}`);

  // 3. コマンドを作成して送信
  const command = new SyncFolderPullCommand({
    source: '/shared-media/', // Spaceからプルするディレクトリ
    target: localTarget, // ダウンロード先のローカルディレクトリ
    onProgress: ({ completed, total, key }) => {
      const progress = total > 0 ? ((completed / total) * 100).toFixed(2) : 0;
      console.log(`Progress: ${progress}% (${completed}/${total}) - Starting download for: ${key}`);
    },
  });

  const output = await spaceClient.send(command);

  // 4. 出力を処理
  if (output.statusCode === 200) {
    console.log('\nFolder pull completed successfully!');
    console.log(`Total files synchronized: ${output.data.count}`);
    console.log(`Total size: ${(output.data.size / 1024).toFixed(2)} KB`);
    console.log(`Duration: ${output.data.duration.toFixed(2)}s`);
    console.log(`Errors: ${output.data.errorCount}`);
  } else {
    console.error(`Folder pull failed with status ${output.statusCode}:`, output.statusMessage);
  }
};

main().catch(console.error);

応答の例（成功）

応答

{
  "statusCode": 200,
  "data": {
    "errorCount": 0,
    "count": 15,
    "duration": 5.432,
    "size": 2048576
  }
}

ベストプラクティス

ファイルのフィルタリング

帯域幅と時間を節約するには、filter関数を使用して必要なファイルのみをダウンロードします。例えば、JPEGとPNG画像のみをダウンロードするには：

フィルタリングの例

const command = new SyncFolderPullCommand({
  source: '/photos/',
  target: './downloaded_images',
  filter: (object) => {
    // ディレクトリと画像以外のファイルはスキップ
    if (object.isDir) return false;
    const lowerCaseKey = object.key.toLowerCase();
    return lowerCaseKey.endsWith('.jpg') || lowerCaseKey.endsWith('.png');
  },
});

同期ロジックの理解

SyncFolderPullCommandは安全な一方向の同期を実行します。サイズと最終更新時刻に基づいてファイルを比較します。リモートファイルがローカルの対応するファイルよりも新しいか、サイズが異なる場合、ダウンロードされます。ファイルがリモートに存在し、ローカルに存在しない場合、ローカルに作成されます。重要なことに、このコマンドは、リモートのソースディレクトリに存在しない場合でも、ローカルファイルを削除しません。これにより、ローカルフォルダを最新の状態に保つための非破壊的な方法となります。