Routes

A route is a named storage policy on your server. Each route owns its constraints, object keys, and enabled operations (upload, download, delete, and upload.multipart).

The browser sends a route name with each request. The server enforces file constraints, validates permissions, and generates object keys.

import { dimahS3, route } from "@dimah-s3/server";
import { awsS3 } from "./aws-s3";

export const s3 = dimahS3({
  client: awsS3,
  bucket: process.env.S3_BUCKET!,
  routes: {
    avatar: route({
      upload: {
        fileTypes: ["image/*"],
        maxFileSize: 2 * 1024 * 1024,
      },
      download: true,
      delete: true,
    }),
    document: route({
      upload: {
        fileTypes: ["application/pdf", "image/*"],
        maxFileSize: 10 * 1024 * 1024,
      },
      download: true,
      delete: true,
    }),
    video: route({
      upload: {
        fileTypes: ["video/*"],
        maxFileSize: 500 * 1024 * 1024,
        multipart: true,
      },
    }),
  },
});

awsS3 is the S3Client from Server Setup.

Combining operationsCopy Anchor Link

Enable operations on the same route when they manage the same objects. For example, if users upload, view, and remove their avatars:

avatar: route({
  upload: {
    fileTypes: ["image/*"],
    maxFileSize: 2 * 1024 * 1024,
  },
  download: true, 
  delete: true, 
}),

With the default keyPrefix (the route name), download and delete must target keys within that route's namespace. That is route isolation, not per-user ownership — see Security.

Key generation and object identityCopy Anchor Link

By default, the server generates object keys formatted as:

{keyPrefix}/{uuid}/{sanitizedName}

keyPrefix defaults to the route name (avatar → avatar/…, document → document/…). The same prefix is used twice:

1. Upload and multipart init — the server generates the key. The client sends a route name, not an object key. The key travels inside the upload ticket, so confirm and the later multipart calls never send it.
2. Download and delete — the client sends a key. The server accepts it only if it sits under that route's prefix.

So DELETE ?route=avatar&key=avatar/{uuid}/photo.jpg is valid, and DELETE ?route=avatar&key=document/{uuid}/cv.pdf returns KEY_INVALID. Two routes cannot share or nest prefixes (files and files/images); dimahS3() throws at startup.

To customize key generation or organize files by user or tenant, return keyFolder or key from upload.object:

avatar: route({
  upload: {
    fileTypes: ["image/*"],
    maxFileSize: 2 * 1024 * 1024,
    object: async ({ request }) => {
      const session = await getSession(request);
      return {
        keyFolder: `users/${session.userId}`, 
        // Results in: avatar/users/{userId}/{uuid}/{name}
      };
    },
  },
}),

object runs after the instance and route guards, so it can also read locals instead of loading the session again.

Keys are limited to 1024 UTF-8 bytes. A generated key turns ${ in the file name into _{. On a method: "POST" route, a key from object that contains ${filename} returns KEY_INVALID, so the presigned form always pins the exact key.

Route lifetimes and sizes (upload.expiresIn, upload.confirmWindow, upload.maxFileSize, upload.multipart.partSize, upload.multipart.ticketExpiresIn, and download.maxExpiresIn) must be positive integers. Any other value throws at dimahS3().

Type referenceCopy Anchor Link

import type {
  DimahS3RouteConfig,
  UploadConfig,
  DownloadConfig,
  DeleteConfig,
  MultipartConfig,
  UploadObjectInfo,
} from "@dimah-s3/server";

DimahS3RouteConfigCopy Anchor Link

UploadConfigCopy Anchor Link

UploadObjectInfoCopy Anchor Link

What upload.object returns.

DownloadConfigCopy Anchor Link

DeleteConfigCopy Anchor Link

Frequently asked questionsCopy Anchor Link

avatar: route({
  upload: {
    fileTypes: ["image/*"],
    maxFileSize: 2 * 1024 * 1024,
    object: async ({ request }) => {
      const session = await getSession(request);
      return {
        key: `avatars/${session.userId}/avatar.png`, 
      };
    },
  },
}),

avatar: route({
  upload: {
    fileTypes: ["image/*"],
    maxFileSize: 2 * 1024 * 1024,
    object: async ({ request }) => {
      const user = await getCurrentUser(request);
      return {
        keyFolder: `users/${user.id}`,
        previousKey: user.currentAvatarKey, 
      };
    },
  },
}),

avatar: route({
  upload: {
    fileTypes: ["image/*"],
    object: () => ({
      storageClass: "STANDARD_IA", 
      cacheControl: "max-age=31536000, immutable", 
      tagging: { purpose: "avatar" }, 
    }),
  },
}),

avatar: route({
  upload: {
    fileTypes: ["image/*"],
    maxFileSize: 2 * 1024 * 1024,
    checksum: true, 
  },
}),

avatar: route({
  upload: {
    fileTypes: ["image/png", "image/jpeg", "image/webp"],
    verifyContent: true, 
  },
}),

avatar: route({
  download: {
    mode: "proxy", 
  },
}),