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

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.');
    }

See all 6 lines

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.
DeleteObjectCommand
Sync Commands