Upload Hooks

Enable upload operations on a named route with upload: true or an UploadConfig object.

import { S3Client } from "@aws-sdk/client-s3";
import { dimahS3, errors, route } from "@dimah-s3/server";

export const awsS3 = new S3Client({/* env */});

export const s3 = dimahS3({
  client: awsS3,
  bucket: process.env.S3_BUCKET!,
  routes: {
    avatar: route({
      upload: {
        fileTypes: ["image/*"],
        maxFileSize: 2 * 1024 * 1024,
        guard: async ({ request }) => {
          const session = await getSession(request);
          if (!session) throw errors.unauthorized();
        },
        onConfirmed: async ({ key, contentLength, request }) => {
          const session = await getSession(request); 
          await db.user.update({
            where: { id: session.userId }, 
            data: { avatarKey: key, avatarSize: contentLength }, 
          }); 
        }, 
      },
    }),
  },
});

Upload lifecycle flowCopy Anchor Link

1. route.guard: Evaluates session and permissions before key generation.
2. object: Computes destination folder, key, metadata, ACL, storage class, cache control, or tags.
3. upload.guard: Authorizes the upload after the server-owned key is assigned.
4. onPresigned: Fires after the presigned URL is created.
5. confirmGuard: Authorizes the confirmation request after bytes land in S3.
6. onConfirmed: Reads verified metadata from HeadObject and persists the record.

Type referenceCopy Anchor Link

import type {
  UploadGuardContext,
  UploadOnConfirmedContext,
  UploadConfirmGuardContext,
  UploadObjectContext,
} from "@dimah-s3/server";

UploadGuardContextCopy Anchor Link

Runs after upload.object assigns the key (and after global / route guards).

UploadOnConfirmedContextCopy Anchor Link

Runs after HeadObject validates the uploaded file size and content type.

UploadConfirmGuardContextCopy Anchor Link

Runs before HeadObject when confirming single-shot uploads or completing multipart uploads.

UploadObjectContextCopy Anchor Link

Input passed to upload.object to generate custom destination keys and metadata.

Frequently asked questionsCopy Anchor Link

avatar: route({
  upload: {
    object: async ({ request, file }) => ({
      folder: "avatars",
      metadata: {
        originalName: file.name, 
      }, 
    }),
  },
});