🖼️ Avatar
Avatar provides reusable blocks for converting stored avatar references into signed download URLs in API responses and removing an obsolete file after replacement. It has no Avatar feature, handler, route, validator, or service export.
Start here
Owning domains compose these exports into their own pipelines. Persist the stored avatarSchema value, normalize it before returning an owner, and clean up a replaced file after updating that owner. The fragment below assumes the host has already configured fileStorageDriver.
Supply a FileStorageDriver to every Avatar block. normalizeAvatarOfOwner generates a signed URL for objectId + '.' + extension(type); normalizeAvatarsOfOwners performs the same conversion per owner; and deleteAvatarIfReplaced deletes that key only when the prior and replacement object IDs differ. A null avatar remains null. The storage driver's signed-URL lifetime and provider configuration belong to the file-storage driver.
import { blocks } from '@nodeblocks/backend-sdk';
const storedAvatar = {
objectId: '550e8400-e29b-41d4-a716-446655440000',
type: 'image/png',
};
// `schemas.avatarSchema` is the persisted-reference contract.
const result = await blocks.normalizeAvatarOfOwner(fileStorageDriver, {
id: 'owner-id',
avatar: storedAvatar,
});
if (result.isErr()) throw result.error;
// result.value.avatar is {type: 'image/png', url: '<signed download URL>'}
The original stored objectId is not returned in the normalized avatar. Signing failure produces Err<AvatarBlockError> rather than throwing from the block. See file-storage drivers for driver setup and error handling for failed Result values.
Common tasks
| Task | Start with | Contract |
|---|---|---|
| Persist an avatar reference | avatarSchema | Stored { objectId, type } contract in avatarSchema |
| Return one owner safely | normalizeAvatarOfOwner | Signed response URL via normalizeAvatarOfOwner |
| Return many owners | normalizeAvatarsOfOwners | Concurrent normalization via normalizeAvatarsOfOwners |
| Replace an avatar without orphaning the old file | deleteAvatarIfReplaced | Conditional cleanup via deleteAvatarIfReplaced |
Reference map
| Page | Purpose |
|---|---|
| Blocks | Normalization, cleanup, result, and error contracts. |
| Schemas | Stored avatar-reference validation. |
Related modules
Use the file-storage driver for FileStorageDriver setup and the file-storage blocks for delegated signed-download and deletion operations. The Profile service consumes every Avatar block. getOrganizationFollowersRoute and getProductLikersRoute also map AvatarBlockError to 500 while normalizing follower data.