fastify-xstorage
list / listAll
List files under a key prefix — single page up to maxKeys, or auto-paginated full listing.
list / listAll
list returns a single page of files under a key prefix (up to maxKeys items). listAll automatically follows ContinuationToken until every matching file is returned.
Signatures
fastify.xStorage.list(
prefix?: string,
maxKeys?: number,
): Promise<StorageItem[]>
fastify.xStorage.listAll(prefix?: string): Promise<StorageItem[]>
interface StorageItem {
key: string
url: string
size: number // bytes
lastModified: Date
etag: string
}
Params
| Name | Type | Default | Description |
|---|---|---|---|
prefix | string | "" | Key prefix to filter by (e.g. "users/123/") |
maxKeys (list only) | number | 1000 | Maximum number of results in a single page |
Returns
StorageItem[] — empty array if no files match the prefix.
Throws
| Error | When |
|---|---|
[xStorage] Failed to list files with prefix "<prefix>": <reason> | S3 API error |
Examples
List all avatar files for a user
fastify.get("/users/:id/files", async (request, reply) => {
const files = await fastify.xStorage.list(`users/${request.params.id}/`);
return {
count: files.length,
files: files.map((f) => ({ key: f.key, url: f.url, sizeKb: Math.round(f.size / 1024) })),
};
});
List all files in a folder and delete old ones
async function pruneOldFiles(prefix, olderThanDays = 30) {
const cutoff = new Date(Date.now() - olderThanDays * 86400_000);
const files = await fastify.xStorage.listAll(prefix);
const stale = files.filter((f) => f.lastModified < cutoff);
if (stale.length === 0) return { pruned: 0 };
const { deleted, errors } = await fastify.xStorage.deleteMultiple(
stale.map((f) => f.key),
);
return { pruned: deleted, errors };
}
See Also
- delete / deleteMultiple — Remove files returned by list
- exists / getMetadata — Inspect a specific file
AI Context
package: "@xenterprises/fastify-xstorage"
methods: fastify.xStorage.list(prefix?, maxKeys?) | fastify.xStorage.listAll(prefix?)
use-when: List files under a key prefix — list() returns one page up to maxKeys; listAll() auto-paginates to return all matching files
returns: Array<{ key, size, lastModified, contentType }>