# `options.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

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

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

## Usage: Advanced

```ts
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.