@rtorcato/api-upload 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Torcato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @rtorcato/api-upload
+
+Promise-based S3 file upload for Express via [multer-s3](https://github.com/anacronw/multer-s3) — public/private ACL, cache-control, deterministic keys, and errors normalized to [`@rtorcato/api-errors`](https://github.com/rtorcato/api-common/tree/main/packages/api-errors).
+
+## Install
+
+```sh
+pnpm add @rtorcato/api-upload @aws-sdk/client-s3 multer multer-s3 express
+```
+
+`@aws-sdk/client-s3`, `multer`, `multer-s3`, and `express` are peer dependencies — you bring your own versions and S3 client.
+
+## Usage
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3'
+import { uploader } from '@rtorcato/api-upload'
+
+const s3 = new S3Client({ region: 'us-east-1' })
+
+app.post('/avatar', async (req, res, next) => {
+  try {
+    const file = await uploader(req, res, {
+      s3,
+      bucket: 'avatars',
+      field: 'avatar',              // multipart form field
+      key: `users/${req.user.id}.png`,
+      isPublic: true,               // public-read ACL (default: private)
+      maxSizeBytes: 5 * 1024 * 1024,
+    })
+    res.json({ url: file.location })
+  } catch (err) {
+    next(err) // 413 / 400 HttpError → your error handler
+  }
+})
+```
+
+`key` can also be a function `(req, file) => string` for deterministic keys derived from the request.
+
+## Errors
+
+`uploader` rejects with an `HttpError` (from `@rtorcato/api-errors`) that drops straight into the `api-errors-express` handler:
+
+- **`413 file_too_large`** — the request `Content-Length` exceeds `maxSizeBytes`. Checked **before** anything streams to S3.
+- **`400 no_file`** — the field was empty.
+- **`400`** — any other multer error (e.g. unexpected field).
+
+## Notes
+
+- **ACL:** `isPublic` sets `public-read` / `private`. Buckets with Object Ownership set to *bucket-owner-enforced* reject ACLs — leave `isPublic` unset and control access with a bucket policy instead.
+- **Size limit:** enforced via `Content-Length` up front (which includes small multipart overhead) rather than multer's mid-stream limit — this avoids buffering oversized bodies and a multer-s3 hang when aborting an in-flight upload.
+
+Source: https://github.com/rtorcato/api-common/tree/main/packages/api-upload

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { Request, Response } from 'express';
+/** A file uploaded to S3 — the multer file plus the fields multer-s3 adds. */
+export interface UploadedFile {
+    fieldname: string;
+    originalname: string;
+    mimetype: string;
+    size: number;
+    /** Bucket the object was written to. */
+    bucket: string;
+    /** Object key. */
+    key: string;
+    /** Public URL / S3 location of the object. */
+    location: string;
+    etag: string;
+    contentType: string;
+}
+export interface UploadOptions {
+    /** S3 client the object is written with (you own its config/credentials). */
+    s3: S3Client;
+    /** Destination bucket. */
+    bucket: string;
+    /** Multipart form field holding the file. */
+    field: string;
+    /** Object key — a string, or a function of the request + file for deterministic keys. */
+    key: string | ((req: Request, file: Express.Multer.File) => string);
+    /** `public-read` ACL when true, otherwise `private`. Default: `false`. */
+    isPublic?: boolean;
+    /** `Cache-Control` stored on the object. Default: `max-age=31536000` (1 year). */
+    cacheControl?: string;
+    /** Extra object metadata. */
+    metadata?: Record<string, string>;
+    /** Max request size in bytes (checked against `Content-Length`); exceeding it rejects with a `413` before anything streams to S3. */
+    maxSizeBytes?: number;
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * app.post('/avatar', async (req, res, next) => {
+ *   try {
+ *     const file = await uploader(req, res, {
+ *       s3, bucket: 'avatars', field: 'avatar', key: `users/${req.user.id}.png`, isPublic: true,
+ *     })
+ *     res.json({ url: file.location })
+ *   } catch (err) { next(err) }
+ * })
+ * ```
+ */
+export declare function uploader(req: Request, res: Response, options: UploadOptions): Promise<UploadedFile>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAIhD,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC7B,6EAA6E;IAC7E,EAAE,EAAE,QAAQ,CAAA;IACZ,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAA;IACnE,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,qIAAqI;IACrI,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,YAAY,CAAC,CA0CvB"}

package/dist/index.js

@@ -0,0 +1,64 @@
+import { BadRequestError, HttpError } from '@rtorcato/api-errors';
+import multer from 'multer';
+import multerS3 from 'multer-s3';
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * app.post('/avatar', async (req, res, next) => {
+ *   try {
+ *     const file = await uploader(req, res, {
+ *       s3, bucket: 'avatars', field: 'avatar', key: `users/${req.user.id}.png`, isPublic: true,
+ *     })
+ *     res.json({ url: file.location })
+ *   } catch (err) { next(err) }
+ * })
+ * ```
+ */
+export async function uploader(req, res, options) {
+    // Reject oversized uploads up front via Content-Length — cheaper than
+    // buffering the body, and avoids a multer-s3 hang where aborting an in-flight
+    // upload on multer's own fileSize limit never settles the callback.
+    if (options.maxSizeBytes !== undefined) {
+        const contentLength = Number(req.headers['content-length']);
+        if (Number.isFinite(contentLength) && contentLength > options.maxSizeBytes) {
+            throw new HttpError(413, 'File too large', 'file_too_large');
+        }
+    }
+    const { key } = options;
+    const storage = multerS3({
+        s3: options.s3,
+        bucket: options.bucket,
+        acl: options.isPublic ? 'public-read' : 'private',
+        contentType: multerS3.AUTO_CONTENT_TYPE,
+        cacheControl: options.cacheControl ?? 'max-age=31536000',
+        metadata: (_req, _file, cb) => cb(null, options.metadata ?? {}),
+        key: typeof key === 'function'
+            ? (r, file, cb) => cb(null, key(r, file))
+            : (_r, _file, cb) => cb(null, key),
+    });
+    const middleware = multer({ storage }).single(options.field);
+    try {
+        await new Promise((resolve, reject) => {
+            middleware(req, res, (err) => (err ? reject(err) : resolve()));
+        });
+    }
+    catch (err) {
+        // e.g. LIMIT_UNEXPECTED_FILE when the field name doesn't match.
+        if (err instanceof multer.MulterError) {
+            throw new BadRequestError(err.message, err.code.toLowerCase());
+        }
+        throw err;
+    }
+    const file = req.file;
+    if (!file)
+        throw new BadRequestError('No file uploaded', 'no_file');
+    return file;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAEjE,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,QAAQ,MAAM,WAAW,CAAA;AAqChC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC7B,GAAY,EACZ,GAAa,EACb,OAAsB;IAEtB,sEAAsE;IACtE,8EAA8E;IAC9E,oEAAoE;IACpE,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAA;QAC3D,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAC5E,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,CAAA;QAC7D,CAAC;IACF,CAAC;IAED,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAA;IACvB,MAAM,OAAO,GAAG,QAAQ,CAAC;QACxB,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS;QACjD,WAAW,EAAE,QAAQ,CAAC,iBAAiB;QACvC,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,kBAAkB;QACxD,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QAC/D,GAAG,EACF,OAAO,GAAG,KAAK,UAAU;YACxB,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAY,EAAE,IAAI,CAAC,CAAC;YACpD,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;KACpC,CAAC,CAAA;IAEF,MAAM,UAAU,GAAG,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAE5D,IAAI,CAAC;QACJ,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QACxE,CAAC,CAAC,CAAA;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,gEAAgE;QAChE,IAAI,GAAG,YAAY,MAAM,CAAC,WAAW,EAAE,CAAC;YACvC,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;QAC/D,CAAC;QACD,MAAM,GAAG,CAAA;IACV,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAgC,CAAA;IACjD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAA;IACnE,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@rtorcato/api-upload",
+  "version": "0.2.0",
+  "description": "Promise-based S3 file upload for Express via multer-s3 — public/private ACL, cache-control, deterministic keys, typed errors.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Richard Torcato",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@rtorcato/api-errors": "0.2.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "express": "^4.18.0 || ^5.0.0",
+    "multer": "^2.0.0",
+    "multer-s3": "^3.0.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "aws-sdk-client-mock": "^4.1.0",
+    "@types/express": "^5.0.0",
+    "@types/multer": "^2.0.0",
+    "@types/supertest": "^7.2.0",
+    "express": "^5.1.0",
+    "multer": "^2.2.0",
+    "multer-s3": "^3.0.1",
+    "supertest": "^7.1.0",
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api",
+    "nodejs",
+    "typescript",
+    "express",
+    "s3",
+    "upload",
+    "multer",
+    "multer-s3",
+    "aws"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rtorcato/api-common.git",
+    "directory": "packages/api-upload"
+  },
+  "homepage": "https://github.com/rtorcato/api-common/tree/main/packages/api-upload#readme",
+  "bugs": {
+    "url": "https://github.com/rtorcato/api-common/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}