Synchronizing Folders

Keeping a local directory in sync with a remote one in your DID Space is a common requirement for applications like static website hosting, data backup, or collaborative asset management. The DID Space Client SDK simplifies this process with two powerful, high-level commands: SyncFolderPushCommand and SyncFolderPullCommand.

This guide will walk you through practical examples of how to use these commands. For a detailed breakdown of all available parameters and options, please refer to the SyncFolderPushCommand and SyncFolderPullCommand API references.

How Synchronization Works

At its core, the synchronization process intelligently determines which files need to be transferred. When a sync command is executed, it performs a comparison between the source and target directories. A file is marked for synchronization if any of the following conditions are met:

By default, the sync commands will only add or update files. You can enable strictSync mode to also delete files in the target directory that do not exist in the source, ensuring an exact mirror.

Pushing a Local Folder to DID Space

Use SyncFolderPushCommand when you want to upload or update the contents of a local directory to a remote directory in your DID Space. This is perfect for deploying a static website or backing up local files.

Step 1: Initialize the Client and Command

First, set up your SpaceClient and import the SyncFolderPushCommand.

Initialize Client

import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// Initialize the wallet and client
const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...', // Use your Space endpoint
  wallet,
});

Step 2: Define Command Inputs

To push a folder, you need to specify the local source path and the remote target path.

Step 3: Execute the Push Command

Now, create an instance of the command with your inputs and send it using the client.

Push a Folder

async function pushMyWebsite() {
  const command = new SyncFolderPushCommand({
    source: './build/', // Path to your local build folder
    target: '/public/my-website/', // Destination in DID Space
    strictSync: true, // Mirror the local folder exactly
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? (completed / total) * 100 : 0;
      console.log(`Upload progress: ${percentage.toFixed(2)}%`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Push successful!');
    console.log(`Total files synced: ${output.data.count}`);
    console.log(`Total size: ${output.data.size} bytes`);
    console.log(`Duration: ${output.data.duration} seconds`);
  } else {
    console.error('Push failed:', output.statusMessage);
  }
}

pushMyWebsite();

This example uploads the contents of the local ./build/ directory to /public/my-website/ in your Space. Because strictSync is true, any files in the remote directory that aren't in ./build/ will be removed.

Pulling a Remote Folder from DID Space

Use SyncFolderPullCommand to download the contents of a remote directory from your DID Space to your local file system. This is useful for restoring a backup or retrieving a shared project.

Step 1: Define Command Inputs

The inputs for pulling are similar to pushing, but the roles of source and target are reversed.

Step 2: Execute the Pull Command

Create the SyncFolderPullCommand instance and send it.

Pull a Folder

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

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function pullMyBackup() {
  const command = new SyncFolderPullCommand({
    source: '/backups/latest/', // Path in your DID Space
    target: './restored-backup/', // Local destination folder
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? (completed / total) * 100 : 0;
      console.log(`Download progress: ${percentage.toFixed(2)}%`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Pull successful!');
    console.log(`Total files synced: ${output.data.count}`);
    console.log(`Total size: ${output.data.size} bytes`);
  } else {
    console.error('Pull failed:', output.statusMessage);
  }
}

pullMyBackup();

This script downloads files from /backups/latest/ in your Space to the local ./restored-backup/ directory. Note that even if strictSync were enabled, this command will not delete any extra files you might have in the local directory.

Best Practices

Next Steps

You now have a solid understanding of how to synchronize folders between your local machine and DID Space. To further enhance your application, you might want to explore how to manage folder appearances.