Skip to main content

SyncFolderPullCommand

The SyncFolderPullCommand is a high-level command designed to synchronize a remote directory from a DID Space to a local folder. It intelligently compares the files between the remote source and the local target, downloading only new or updated files. This ensures your local directory is an up-to-date mirror of the remote data efficiently.

This command is the counterpart to the SyncFolderPushCommand, which is used for uploading local changes to a remote directory.

Use Case

This command is ideal for scenarios where you need to retrieve a collection of files from a user's Space. Common use cases include:

  • Downloading a user's photo gallery to a local application.
  • Restoring a backup of application data from the Space to a local machine.
  • Keeping a local workspace synchronized with a master version stored in the Space.

Input Parameters

The command's constructor accepts a single object with the following fields:

  • source string (required) — The source directory path in your DID Space from which to pull files. The path should end with a '/'.
  • target string (required) — The destination path on your local file system where files will be downloaded. The command will automatically create this directory if it does not exist.
  • concurrency number (default: 4) — The number of files to download in parallel. Increasing this value can speed up the process for directories with many small files. The maximum value is capped by the number of available CPU cores.
  • retryCount number (default: 3) — The number of times to retry a failed download for a specific file before marking it as an error. The maximum value is 10.
  • filter (object: Object) => boolean — A function that is called for each remote object. Return true to include the object in the sync process, or false to skip it. This is useful for selectively downloading files based on their properties, like name or size.
  • onProgress (params: OnProgressInput) => void — A callback function that is triggered as each file begins its download process. It receives an object with the current progress.
    • completed number — The number of files that have started downloading.
    • total number — The total number of files to be downloaded.
    • key string — The key (relative path) of the file currently being processed.
  • onAfterUpload (params: OnAfterUploadInput) => void — A callback function that is triggered after each file is successfully downloaded. Note: Despite the name 'onAfterUpload', for a pull command, it signifies the completion of a download.
    • completed number — The number of files successfully downloaded so far.
    • total number — The total number of files to be downloaded.
    • key string — The key (relative path) of the file that just finished downloading.
  • debug boolean (default: false) — Set to true to enable verbose logging in the console, which can be helpful for debugging the synchronization process.
  • strictSync boolean (default: false) — This parameter has no effect for SyncFolderPullCommand. The command is designed to be non-destructive to the local directory and will not delete local files that are absent from the remote source.

Output

The spaceClient.send() method returns a promise that resolves to an object containing the result of the operation.

  • statusCode number — Indicates the outcome of the request. A value of 200 means the entire sync operation completed successfully.
  • data object — An object containing a summary of the sync operation.
    • count number — The total number of files that were scheduled for download.
    • errorCount number — The number of files that failed to download after all retries.
    • size number — The total size in bytes of all successfully downloaded files.
    • duration number — The total time taken for the operation, in seconds.
  • statusMessage string — An error message if the entire command failed to execute (e.g., due to authentication issues).
  • stack string — The stack trace if an unrecoverable error occurred.

Example

Here's how to use SyncFolderPullCommand to download a remote directory to a local folder and track its progress.

Example

typescript
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. Initialize SpaceClient
  const wallet = getWallet();
  const spaceClient = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  // 2. Prepare local directory for the download
  const localTarget = path.join(__dirname, 'my-pulled-assets');
  removeSync(localTarget); // Clean up previous runs for this example
  ensureDirSync(localTarget);
  console.log(`Downloading files to: ${localTarget}`);

  // 3. Create and send the command
  const command = new SyncFolderPullCommand({
    source: '/shared-media/', // The directory in your Space to pull from
    target: localTarget, // The local directory to download to
    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. Handle the output
  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);

Example Response (Success)

Response

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

Best Practices

Filtering Files

To save bandwidth and time, use the filter function to download only the files you need. For instance, to download only JPEG and PNG images:

Filtering Example

javascript
const command = new SyncFolderPullCommand({
  source: '/photos/',
  target: './downloaded_images',
  filter: (object) => {
    // Skip directories and non-image files
    if (object.isDir) return false;
    const lowerCaseKey = object.key.toLowerCase();
    return lowerCaseKey.endsWith('.jpg') || lowerCaseKey.endsWith('.png');
  },
});

Understanding Sync Logic

SyncFolderPullCommand performs a safe, one-way synchronization. It compares files based on size and last modification time. If a remote file is newer or has a different size than its local counterpart, it will be downloaded. If a file exists remotely but not locally, it will be created locally. Crucially, this command will not delete any local files, even if they don't exist in the remote source directory. This makes it a non-destructive way to keep a local folder up-to-date.