fastify-xstorage
exists / getMetadata
Check file existence via HeadObject, or retrieve content type, size, timestamps, and custom metadata without downloading.
exists / getMetadata
exists checks whether a file is present using HeadObject — returns false for missing files rather than throwing. getMetadata retrieves content type, size, timestamps, and custom metadata headers without downloading the file body.
Signatures
fastify.xStorage.exists(key: string): Promise<boolean>
fastify.xStorage.getMetadata(key: string): Promise<FileMetadata>
interface FileMetadata {
contentType: string
contentLength: number // bytes
lastModified: Date
etag: string
metadata: Record<string, string> // custom S3 metadata headers
}
Params
Both methods take a single param:
| Name | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Storage key of the file to inspect |
Returns
exists→boolean—trueif the file exists,falseif it returns 404.getMetadata→FileMetadataobject.
Throws
| Error | When |
|---|---|
[xStorage] key is required and must be a string | key is missing or not a string |
[xStorage] Failed to get metadata for "<key>": <reason> | S3 HeadObject error (except 404, which exists swallows) |
Examples
Guard a download route — return 404 if file is missing
fastify.get("/files/:key", async (request, reply) => {
const key = decodeURIComponent(request.params.key);
if (!await fastify.xStorage.exists(key)) {
return reply.code(404).send({ error: "File not found" });
}
const buffer = await fastify.xStorage.download(key);
const { contentType } = await fastify.xStorage.getMetadata(key);
return reply.header("Content-Type", contentType).send(buffer);
});
Display file info in an admin panel without downloading
fastify.get("/admin/storage/:key/info", async (request, reply) => {
const key = decodeURIComponent(request.params.key);
const meta = await fastify.xStorage.getMetadata(key);
return {
key,
contentType: meta.contentType,
sizeKb: Math.round(meta.contentLength / 1024),
lastModified: meta.lastModified,
etag: meta.etag,
};
});
See Also
- download — Download the file body
- list / listAll — Enumerate files by prefix
AI Context
package: "@xenterprises/fastify-xstorage"
methods: fastify.xStorage.exists(key) | fastify.xStorage.getMetadata(key)
use-when: Check file existence (returns false on 404, does not throw) or retrieve content type, size, timestamps, and custom metadata without downloading the file
returns: exists → boolean | getMetadata → { contentType, size, lastModified, etag, metadata }