Skip to main content

@rtorcato/api-upload v1.0.0

Interfaces​

UploadedFile​

Defined in: index.ts:8

A file uploaded to S3 — the multer file plus the fields multer-s3 adds.

Properties​

fieldname​

fieldname: string

Defined in: index.ts:9

originalname​

originalname: string

Defined in: index.ts:10

mimetype​

mimetype: string

Defined in: index.ts:11

size​

size: number

Defined in: index.ts:12

bucket​

bucket: string

Defined in: index.ts:14

Bucket the object was written to.

key​

key: string

Defined in: index.ts:16

Object key.

location​

location: string

Defined in: index.ts:18

Public URL / S3 location of the object.

etag​

etag: string

Defined in: index.ts:19

contentType​

contentType: string

Defined in: index.ts:20

UploadOptions​

Defined in: index.ts:23

Properties​

s3​

s3: S3Client

Defined in: index.ts:25

S3 client the object is written with (you own its config/credentials).

bucket​

bucket: string

Defined in: index.ts:27

Destination bucket.

field​

field: string

Defined in: index.ts:29

Multipart form field holding the file.

key​

key: string | ((req, file) => string)

Defined in: index.ts:31

Object key — a string, or a function of the request + file for deterministic keys.

isPublic?​

optional isPublic?: boolean

Defined in: index.ts:33

public-read ACL when true, otherwise private. Default: false.

cacheControl?​

optional cacheControl?: string

Defined in: index.ts:35

Cache-Control stored on the object. Default: max-age=31536000 (1 year).

metadata?​

optional metadata?: Record<string, string>

Defined in: index.ts:37

Extra object metadata.

maxSizeBytes?​

optional maxSizeBytes?: number

Defined in: index.ts:39

Max request size in bytes (checked against Content-Length); exceeding it rejects with a 413 before anything streams to S3.

Functions​

uploadFile()​

uploadFile(req, res, options): Promise<UploadedFile>

Defined in: index.ts:62

Upload a single file from a multipart request straight to S3, resolving with the stored object's details.

Rejects with an HttpError (from @rtorcato/api-errors): 413 file_too_large when maxSizeBytes is exceeded, 400 no_file when the field is empty, and a 400 for any other multer error — so it slots into the error-handler middleware.

Parameters​

req​

Request

res​

Response

options​

UploadOptions

Returns​

Promise<UploadedFile>

Example​

app.post('/avatar', async (req, res, next) => {
  try {
    const file = await uploadFile(req, res, {
      s3, bucket: 'avatars', field: 'avatar', key: `users/${req.user.id}.png`, isPublic: true,
    })
    res.json({ url: file.location })
  } catch (err) { next(err) }
})