ListObjectsCommand

The ListObjectsCommand is used to retrieve a list of objects, which can be files or directories, from a specified path within your DID Space. It offers flexibility through options for both flat (listing only immediate children) and recursive (listing all nested items) directory traversal.

This command is essential for applications that need to display folder contents, build a file browser, or iterate over all files in a specific part of the storage.

Use Case

Common scenarios for using ListObjectsCommand include:

Building a file explorer interface for users to navigate their stored files.
Synchronizing a local directory with a remote one by first listing the remote objects.
Performing batch operations on all files within a specific folder.
Verifying the contents of a directory after an upload or a series of file operations.

Input Parameters

The command constructor accepts an object with the following properties:

key string (default: /) — The path of the directory whose contents you want to list. If omitted, it defaults to the root directory ('/').
recursive boolean — If set to true, the command will list all objects under the given key recursively. If false or not provided, it performs a flat listing of only the immediate children.
ignoreDirectories boolean — If set to true, directories will be excluded from the result set. This option is only effective when 'recursive' is false.

Output

The send method returns a promise that resolves to an object containing the command's output.

statusCode number — The HTTP status code of the response. A value of 200 indicates success.
data Object[] — An array of objects representing the files and directories found at the specified key.
- key string — The full path and name of the object.
- type 'object' | 'directory' — The type of the item.
- size number — The size of the object in bytes. For directories, this is typically 0.
- lastModified string — An ISO 8601 formatted date string indicating when the object was last modified.

Example Response (Success)

Example Success Response

{
  "statusCode": 200,
  "data": [
    {
      "key": "/photos/summer/beach.jpg",
      "type": "object",
      "size": 2048576,
      "lastModified": "2023-10-27T10:00:00.000Z"
    },
    {
      "key": "/photos/summer/mountains/",
      "type": "directory",
      "size": 0,
      "lastModified": "2023-10-26T15:30:00.000Z"
    }
  ]
}

Code Example

This example demonstrates how to initialize the SpaceClient and use the ListObjectsCommand to list the contents of a directory.

Example

import { SpaceClient, ListObjectsCommand } 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 listMyFiles() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/', // Specify the directory to list
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully listed objects:');
    if (output.data.length > 0) {
      output.data.forEach((item) => {
        console.log(`- [${item.type}] ${item.key} (Size: ${item.size} bytes)`);
      });
    } else {
      console.log('The directory is empty.');
    }
  } else {
    console.error('Failed to list objects:', output);
  }
}

listMyFiles();

Recursive Listing

To list all files and subdirectories within /shared-documents/, set the recursive option to true.

Recursive Listing

async function listAllFilesRecursively() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/',
    recursive: true,
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('All nested objects:');
    output.data.forEach((item) => {
      console.log(`- ${item.key}`);
    });
  } else {
    console.error('Recursive listing failed:', output);
  }
}

listAllFilesRecursively();

Best Practices & Common Patterns

Performance: For large directories, avoid recursive listing unless necessary. A flat listing is significantly faster as it retrieves less data.
Building a File Tree: To construct a UI file tree, you can start with a non-recursive call for the root level. Then, make subsequent non-recursive calls for each subdirectory as the user expands them. Alternatively, a single recursive call can fetch the entire tree state at once if the total number of objects is manageable.
Filtering Files: If you only need to process files in a specific directory (and not subdirectories), combine a non-recursive call with ignoreDirectories: true for an efficient, file-only list.