List
This section guides you through listing objects and their metadata within a specified directory in your DID Space. This is crucial for navigating your stored data and understanding its structure. For operations like uploading, retrieving content, or deleting objects, refer to Put, Get, and Delete respectively. If you need to synchronize entire folders, see the Sync commands.
List Objects Command#
Use the ListObjectsCommand to retrieve a paginated list of objects and their metadata within a specified directory in your DID Space. This command supports options for recursive listing and ignoring directory entries.
Parameters#
Name | Type | Description |
|---|---|---|
|
| The path to the directory whose contents you want to list. Use an empty string |
|
| Optional. If |
|
| Optional. If |
Returns#
Name | Type | Description |
|---|---|---|
|
| An array of |
|
| The current page number of the results. |
|
| The maximum number of items returned per page. |
|
| The total number of objects matching the listing criteria. |
Example: Listing Objects in a Directory#
This example demonstrates how to list all objects, including files and subdirectories, within a specific path in your DID Space.
import { SpaceClient } from '@did-spaces/client';
import { ListObjectsCommand } from '@did-spaces/client/commands/object';
async function listMyDirectoryContents(client, directoryKey) {
try {
const command = new ListObjectsCommand({
key: directoryKey,
recursive: false, // Only list direct children
ignoreDirectories: false, // Include both files and directories
});
const result = await client.send(command);
console.log(`Listing contents of '${directoryKey}':`);
result.data.forEach(obj => {
console.log(`- ${obj.key} (Type: ${obj.type}, Size: ${obj.size || 0} bytes)`);
});
console.log(`Total objects: ${result.total}`);
return result.data;
} catch (error) {
console.error(`Error listing objects: ${error.message}`);
throw error;
}
}
// Example usage (assuming client is already initialized)
// const client = new SpaceClient({ endpoint: 'YOUR_SPACE_ENDPOINT', wallet: 'YOUR_WALLET' });
// listMyDirectoryContents(client, 'my-folder');This code snippet initializes a ListObjectsCommand with the desired key (the directory path) and then sends it through the SpaceClient. The result will contain an array of Object metadata, which is then iterated to log the key, type, and size of each item. The recursive and ignoreDirectories options are set to false to list only immediate children and include both files and subdirectories.
Example: Listing All Files Recursively#
This example shows how to list all files, including those in subdirectories, from the root of your DID Space.
import { SpaceClient } from '@did-spaces/client';
import { ListObjectsCommand } from '@did-spaces/client/commands/object';
async function listAllFilesRecursively(client) {
try {
const command = new ListObjectsCommand({
key: '', // List from the root
recursive: true, // List objects in subdirectories
ignoreDirectories: true, // Only return file objects
});
const result = await client.send(command);
console.log('Listing all files recursively:');
result.data.forEach(obj => {
console.log(`- ${obj.key} (Size: ${obj.size || 0} bytes)`);
});
console.log(`Total files: ${result.total}`);
return result.data;
} catch (error) {
console.error(`Error listing all files: ${error.message}`);
throw error;
}
}
// Example usage (assuming client is already initialized)
// const client = new SpaceClient({ endpoint: 'YOUR_SPACE_ENDPOINT', wallet: 'YOUR_WALLET' });
// listAllFilesRecursively(client);This example demonstrates how to set key to an empty string to list from the root, recursive to true to traverse subdirectories, and ignoreDirectories to true to only include file objects in the result. This is useful for obtaining a comprehensive list of all stored files.
Listing Workflow#
This sequence diagram illustrates the flow of listing objects using the DID Spaces SDK. Your application initiates the command, which the SDK prepares and signs before sending an HTTP GET request to the DID Space service. The service then returns the requested object metadata, which the SDK processes and returns to your application.
This section provided a detailed overview of how to list objects and directories in your DID Space using the ListObjectsCommand. You've learned how to specify the path, control recursion, and filter by object type. For more advanced object management, consider exploring how to Sync your local folders with your DID Space.