`options.ts`

(no submodules)

Purpose

Defines the Zod schema validating caller-supplied FileUploadPluginOptions. Invalid input — wrong type, malformed basePath, non-positive limits, non-conforming storage/sessionStore shapes — throws FileUploadError(UPLOAD.INVALID_INPUT) at the createFileUploadPlugin boundary so misconfiguration fails fast at boot rather than at first request.

Features

basePath regex matches Hono's mount rules: starts with /, never ends with / except the root.
Default singleShotLimitBytes of 10 MiB, maxFileSizeBytes of 1 GiB, defaultChunkSize of 5 MiB, sessionTtlMs of 24 h.
Default MIME denylist covers common native-executable formats so a default-configured deployment refuses obvious malware delivery vectors.
storage, sessionStore, and logger validated structurally via z.custom (they are runtime objects).
Exports both the input shape (what callers pass) and the resolved shape (what the descriptor stores).

Usage: Basic

import { FileUploadPluginOptionsSchema } from "@suaveplan/api-plugin-file-upload/schemas/options";

const config = FileUploadPluginOptionsSchema.parse({ basePath: "/files" });

Usage: Advanced

import { FileUploadPluginOptionsSchema } from "@suaveplan/api-plugin-file-upload";
import { MemoryUploadStorage } from "@suaveplan/api-plugin-file-upload/storage/memory";

const config = FileUploadPluginOptionsSchema.parse({
    basePath: "/api/v1/uploads",
    singleShotLimitBytes: 5 * 1024 * 1024,
    allowedMimeTypes: ["image/png", "image/jpeg", "application/pdf"],
    storage: new MemoryUploadStorage(),
});

API Reference

FileUploadPluginOptionsSchema — Zod object schema.
FileUploadPluginOptionsInput — z.input type, what callers may pass.
FileUploadPluginOptionsResolved — z.output type, post-default shape.

Implementation Notes

The schema applies defaults rather than rejecting missing fields — calling createFileUploadPlugin({}) is a valid (development) configuration. The defaults match the hardening baseline (executable denylist on, generous size caps, 24 h TTL).
allowedMimeTypes empty defaults to "no allow-list" (everything except the denylist). Setting any value flips to "exclusive allow" semantics — the validator rejects anything not in the array.
The z.custom structural checks for storage/sessionStore/logger accept any object exposing the expected duck-typed methods; full interface conformance is enforced at the consumer call site by TypeScript when the package's exported types are imported.

2.6 KiB Raw Blame History

options.ts