Commands Reference

Push

The Push command in the DID Spaces SDK allows you to synchronize local folder changes and new files to your DID Space. This ensures that your remote DID Space content is always up-to-date with your local filesystem. It intelligently compares local and remote objects, only uploading or deleting what's necessary to achieve synchronization.
For an overview of synchronization commands, see the Sync section. To pull changes from your DID Space to a local folder, refer to Pull. For more efficient synchronization of large datasets, explore Incremental.
How It Works#The Push command orchestrates a series of steps to achieve efficient synchronization:
RemoteDIDSpaceLocalFSDIDSpaceSDKClientRemoteDIDSpaceLocalFSDIDSpaceSDKClientalt[For Each PUT Action][For Each DELETE Action]Call Push CommandInitialize Audit LogGet Local Objects MapGet Remote Objects MapCompare Objects & Determine Sync Actions(Concurrent) Process Sync ObjectsCopy Object to Temp DirectoryUpload Object (PutObjectCommand)Clean Up Temp ObjectDelete Object (DeleteObjectCommand)Update Audit LogClean Up Temporary Sync DirectoryReturn Sync Result

Audit Log Initialization: An audit log entry is created to track the synchronization process.
Local Scan: The command scans your specified local folder or source objects to build a map of all local files and their metadata (size, last modified time, hash).
Remote Retrieval: It then fetches a map of all objects currently present in your target DID Space.
Comparison and Action Determination: The core logic compares the local and remote maps to identify differences. It determines which objects need to be PUT (uploaded/updated) or DELETEd (removed from remote) based on factors like existence, size, last modification time, and content hash. If strictSync is enabled, local deletions will also trigger remote deletions.
Concurrent Synchronization: Identified PUT and DELETE actions are executed concurrently using a queue to optimize performance. For PUT operations, a temporary copy of the local file is made to ensure data integrity during upload.
Progress and Hooks: The command provides hooks (onProgress, onAfterUpload) to report real-time progress and allows for debug logging.
Audit Log Update: The audit log is updated with the final status, including total count, error count, size, and duration of the sync.
Cleanup: All temporary files and directories created during the sync process are removed.
SyncFolderPushCommand Class#The SyncFolderPushCommand class is the primary entry point for initiating a push synchronization operation. It extends SyncFolderBaseCommand, inheriting common synchronization logic and configuration options.
import { SpaceClient } from '@did-space/client';
import { SyncFolderPushCommand } from '@did-space/client/commands/sync/sync-folder-push';

const client = new SpaceClient({
  // client configuration
});

// Create and execute the command
const result = await client.send(new SyncFolderPushCommand(input));Parameters (SyncFolderPushCommandInput)#The SyncFolderPushCommandInput interface defines the parameters required to configure a push synchronization. It extends SyncFolderBaseCommandInput.
Specific Parameters#Name
Type
Description
metadata
ObjectMetadata
Optional metadata to associate with the target folder in DID Space.
preview
PreviewTemplate
Optional preview template data to associate with the target folder in DID Space.
Inherited Parameters (from SyncFolderBaseCommandInput)#Name
Type
Description
source
string | SourceObject[]
The source to be synchronized. If a string, it should be a path to a local folder (add a trailing slash for folders). If an array, it's a list of specific files or data objects to sync.
target
string
The target path in your DID Space where files will be pushed. This should be a folder path (ending with a trailing slash).
concurrency
number
Optional. The number of concurrent operations to run during synchronization. Defaults to 4, maximum is the number of CPU cores.
retryCount
number
Optional. The number of times to retry a failed operation. Defaults to 3, maximum is 10.
filter
(object: Object) => boolean
Optional. A function to filter which objects are included in the synchronization. Objects for which this function returns false will be ignored.
onProgress
(params: OnProgressInput) => Promise<void>
Optional. A callback function triggered during the synchronization process to report progress. params includes completed, total, and key (of the current object).
onAfterUpload
(params: OnAfterUploadInput) => Promise<void>
Optional. A callback function triggered after each object has been uploaded or deleted. params includes completed, total, and key (of the processed object).
debug
boolean
Optional. If true, enables verbose debug logging to the console, showing detailed progress and internal states.
tmpDir
string
Optional. A custom temporary directory path for storing intermediate files during synchronization. Defaults to a system-defined temporary directory if not provided.
strictSync
boolean
Optional. If true, enables strict synchronization, meaning if a local file is deleted, its corresponding remote object will also be deleted. Defaults to false.
Return Value (SyncFolderPushCommandOutput)#The SyncFolderPushCommandOutput interface represents the result of a push synchronization operation. It extends SyncFolderBaseCommandOutput.
Name
Type
Description
statusCode
number
The HTTP status code of the overall operation. A 200 indicates success, while other codes indicate errors.
statusMessage
string
A descriptive message about the status of the operation.
stack
string
The error stack trace, present only if an error occurred during the operation.
data
object
An object containing detailed statistics about the synchronization process.
data Properties#Name
Type
Description
size
number
The total size (in bytes) of all objects successfully uploaded.
errorCount
number
The number of objects that failed to synchronize.
count
number
The total number of objects processed (attempted synchronization).
duration
number
The total time taken for the synchronization operation, in seconds.
Examples#Pushing a Local Folder to DID Space#This example demonstrates how to push the contents of a local folder to a specified path in your DID Space. It includes progress tracking and debug logging.
import { SpaceClient } from '@did-space/client';
import { SyncFolderPushCommand } from '@did-space/client/commands/sync/sync-folder-push';
import path from 'path';

async function pushLocalFolder() {
  const client = new SpaceClient({
    // Replace with your DID Space endpoint and wallet credentials
    endpoint: 'https://your-did-space-node.com/api',
    wallet: yourWalletInstance,
  });

  const localPath = path.resolve('./my-local-data/');
  const remotePath = '/my-space/data/';

  try {
    console.log(`Starting push from ${localPath} to ${remotePath}`);
    const result = await client.send(new SyncFolderPushCommand({
      source: localPath,
      target: remotePath,
      concurrency: 8, // Adjust concurrency as needed
      debug: true, // Enable debug logs for detailed progress
      onProgress: ({ completed, total, key }) => {
        console.log(`Progress: ${completed}/${total} - Processing ${key}`);
      },
      onAfterUpload: ({ completed, total, key }) => {
        console.log(`Completed: ${completed}/${total} - Uploaded/Deleted ${key}`);
      },
      metadata: { // Optional: Add metadata to the target folder
        'description': 'Data synced from local folder'
      },
      preview: { // Optional: Add preview template data
        'title': 'My Synced Data',
        'description': 'Files synchronized from local machine'
      }
    }));

    if (result.statusCode === 200) {
      console.log('Push completed successfully!');
      console.log(`Total objects processed: ${result.data.count}`);
      console.log(`Errors: ${result.data.errorCount}`);
      console.log(`Total size synced: ${result.data.size} bytes`);
      console.log(`Duration: ${result.data.duration} seconds`);
    } else {
      console.error('Push failed:', result.statusMessage);
      console.error('Stack:', result.stack);
    }
  } catch (error) {
    console.error('An unexpected error occurred during push:', error);
  }
}

pushLocalFolder();Pushing Specific Files (Source Objects) to DID Space#This example shows how to push specific files defined as SourceObject array, allowing fine-grained control over what is synchronized.
import { SpaceClient } from '@did-space/client';
import { SyncFolderPushCommand } from '@did-space/client/commands/sync/sync-folder-push';
import { readFileSync } from 'fs';
import path from 'path';

async function pushSpecificFiles() {
  const client = new SpaceClient({
    // Replace with your DID Space endpoint and wallet credentials
    endpoint: 'https://your-did-space-node.com/api',
    wallet: yourWalletInstance,
  });

  const remoteBasePath = '/my-space/documents/';

  const filesToPush = [
    { // Push a local file by its absolute path
      key: 'report.pdf',
      absolutePath: path.resolve('./local-files/report.pdf'),
    },
    { // Push data directly from memory
      key: 'config.json',
      data: Buffer.from(JSON.stringify({ setting: 'value', version: '1.0' }), 'utf-8'),
    },
    { // Another local file
      key: 'image.png',
      absolutePath: path.resolve('./local-files/assets/image.png'),
    },
  ];

  try {
    console.log(`Starting push of specific files to ${remoteBasePath}`);
    const result = await client.send(new SyncFolderPushCommand({
      source: filesToPush,
      target: remoteBasePath,
      concurrency: 4,
      onProgress: ({ completed, total, key }) => {
        console.log(`Processing file: ${key} (${completed}/${total})`);
      },
      // Enable strictSync to delete remote files if they are not in the 'filesToPush' array
      strictSync: true
    }));

    if (result.statusCode === 200) {
      console.log('Specific files push completed successfully!');
      console.log(`Total objects processed: ${result.data.count}`);
      console.log(`Errors: ${result.data.errorCount}`);
    } else {
      console.error('Specific files push failed:', result.statusMessage);
      console.error('Stack:', result.stack);
    }
  } catch (error) {
    console.error('An unexpected error occurred during specific files push:', error);
  }
}

pushSpecificFiles();Conclusion#The Push command is a powerful tool for maintaining synchronization between your local data and DID Spaces. By understanding its parameters and behavior, you can effectively manage your content and ensure data consistency. For pulling data from DID Spaces to your local environment, explore the Pull command, or learn about Incremental synchronization for large datasets.

Name	Type	Description
`source`	`string \| SourceObject[]`	The source to be synchronized. If a string, it should be a path to a local folder (add a trailing slash for folders). If an array, it's a list of specific files or data objects to sync.
`target`	`string`	The target path in your DID Space where files will be pushed. This should be a folder path (ending with a trailing slash).
`concurrency`	`number`	Optional. The number of concurrent operations to run during synchronization. Defaults to `4`, maximum is the number of CPU cores.
`retryCount`	`number`	Optional. The number of times to retry a failed operation. Defaults to `3`, maximum is `10`.
`filter`	`(object: Object) => boolean`	Optional. A function to filter which objects are included in the synchronization. Objects for which this function returns `false` will be ignored.
`onProgress`	`(params: OnProgressInput) => Promise<void>`	Optional. A callback function triggered during the synchronization process to report progress. `params` includes `completed`, `total`, and `key` (of the current object).
`onAfterUpload`	`(params: OnAfterUploadInput) => Promise<void>`	Optional. A callback function triggered after each object has been uploaded or deleted. `params` includes `completed`, `total`, and `key` (of the processed object).
`debug`	`boolean`	Optional. If `true`, enables verbose debug logging to the console, showing detailed progress and internal states.
`tmpDir`	`string`	Optional. A custom temporary directory path for storing intermediate files during synchronization. Defaults to a system-defined temporary directory if not provided.
`strictSync`	`boolean`	Optional. If `true`, enables strict synchronization, meaning if a local file is deleted, its corresponding remote object will also be deleted. Defaults to `false`.

Name	Type	Description
`statusCode`	`number`	The HTTP status code of the overall operation. A `200` indicates success, while other codes indicate errors.
`statusMessage`	`string`	A descriptive message about the status of the operation.
`stack`	`string`	The error stack trace, present only if an error occurred during the operation.
`data`	`object`	An object containing detailed statistics about the synchronization process.

Name	Type	Description
`size`	`number`	The total size (in bytes) of all objects successfully uploaded.
`errorCount`	`number`	The number of objects that failed to synchronize.
`count`	`number`	The total number of objects processed (attempted synchronization).
`duration`	`number`	The total time taken for the synchronization operation, in seconds.

Overview

Quick Start

Core Concepts

Commands Reference

Utilities

Push

How It Works#

`SyncFolderPushCommand` Class#

Parameters (`SyncFolderPushCommandInput`)#

Specific Parameters#

Inherited Parameters (from `SyncFolderBaseCommandInput`)#

Return Value (`SyncFolderPushCommandOutput`)#

`data` Properties#

Examples#

Pushing a Local Folder to DID Space#

Pushing Specific Files (Source Objects) to DID Space#

Conclusion#

Sync

Pull

Name	Type	Description
`metadata`	`ObjectMetadata`	Optional metadata to associate with the target folder in DID Space.
`preview`	`PreviewTemplate`	Optional preview template data to associate with the target folder in DID Space.