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.
3 subfields
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.
3 subfields

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.
4 subfields

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

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;

See all 19 lines

Example Response (Success)#

Response

{
  "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

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.

SyncFolderPushCommand
NFT Commands