zod-nest 3.0.2 → 3.1.0

package/README.md

@@ -499,6 +499,27 @@ A compact, link-out index. Type signatures and detailed semantics live in the co
 
 See [`docs/recipes/custom-openapi-overrides.md`](docs/recipes/custom-openapi-overrides.md) for the full catalog and usage patterns.
 
+**File uploads** (subpaths: `zod-nest/express`, `zod-nest/fastify`) — [`docs/file-uploads.md`](docs/file-uploads.md)
+
+Dedicated helpers per multipart parser, because multer and `@fastify/multipart` disagree on where files land, what they're named, and whether a size is even reported.
+
+- **Express / multer**: `multerMemoryFile(options?)`, `multerDiskFile(options?)`, `MulterMemoryFileSchema`, `MulterDiskFileSchema`, `MulterMemoryFileLike`, `MulterDiskFileLike`, `MulterFileOptions`
+- **Fastify / `@fastify/multipart`**: `fastifyMultipartFile(options?)`, `FastifyMultipartFileSchema`, `FastifyMultipartFileLike`, `FastifyMultipartFileOptions` (no `maxSize` — a `MultipartFile` reports no size)
+- **Decorators**: `@ZodMultipart(shape, options?)` declares the whole body and is the source of truth for `@ZodUploadedFile(name)`, `@ZodUploadedFiles(name?)`, and `@ZodMultipartBody()`
+
+```ts
+@Post('avatar')
+@UseInterceptors(FileInterceptor('avatar'))
+@ZodMultipart({
+  avatar: multerMemoryFile({ maxSize: 2 * 1024 * 1024, mimeTypes: ['image/png'] }),
+  name: z.string(),
+})
+upload(
+  @ZodUploadedFile('avatar') avatar: MulterMemoryFileLike,
+  @ZodMultipartBody() body: { name: string },
+) {}
+```
+
 ## Documentation
 
 | Topic                                      | Doc                                                          |
@@ -510,6 +531,7 @@ See [`docs/recipes/custom-openapi-overrides.md`](docs/recipes/custom-openapi-ove
 | Module options reference                   | [`docs/module-options.md`](docs/module-options.md)           |
 | Validation logging                         | [`docs/logging.md`](docs/logging.md)                         |
 | Swagger integration & custom emission      | [`docs/swagger-integration.md`](docs/swagger-integration.md) |
+| File uploads (multipart/form-data)         | [`docs/file-uploads.md`](docs/file-uploads.md)               |
 | Composition (experimental)                 | [`docs/composition.md`](docs/composition.md)                 |
 | Exception classes                          | [`docs/exceptions.md`](docs/exceptions.md)                   |
 | Recipes                                    | [`docs/recipes/`](docs/recipes/)                             |

package/dist/express/index.d.mts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { B as BaseFileOptions, a as MultipartShape, b as ZodMultipartOptions } from '../zod-multipart.decorator-CxS2KuSv.mjs';
+export { M as MULTIPART_CONTENT_TYPE, Z as ZodMultipartBody, c as ZodUploadedFile, d as ZodUploadedFiles } from '../zod-multipart.decorator-CxS2KuSv.mjs';
+import '@nestjs/common';
+import '../registry-C9xStKa6.mjs';
+
+/**
+ * Shape multer hands you under **memory storage** (`FileInterceptor`'s
+ * default). `buffer` holds the whole file; there is no `path`.
+ */
+interface MulterMemoryFileLike {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    buffer: Buffer;
+}
+/**
+ * Shape multer hands you under **disk storage**. The bytes are on disk at
+ * `path`; there is no `buffer`, so byte-level validation isn't possible.
+ */
+interface MulterDiskFileLike {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    destination: string;
+    filename: string;
+    path: string;
+}
+/**
+ * Options for the multer file helpers. `maxSize` is checked against multer's
+ * reported `size` **after** the file has been read — it documents the limit
+ * and adds defence in depth, but the guard that actually stops a large upload
+ * is multer's own `limits.fileSize`.
+ *
+ * `mimeTypes` and `extensions` match the client-supplied values. They are not
+ * content sniffing; use `@nestjs/common`'s `FileTypeValidator` when you need
+ * magic-number checks.
+ */
+interface MulterFileOptions extends BaseFileOptions {
+    readonly maxSize?: number;
+}
+/** Multer memory-storage file, constrained by `options` and emitted as `format: 'binary'`. */
+declare const multerMemoryFile: (options?: MulterFileOptions) => z.ZodType<MulterMemoryFileLike, MulterMemoryFileLike>;
+/** Multer disk-storage file, constrained by `options` and emitted as `format: 'binary'`. */
+declare const multerDiskFile: (options?: MulterFileOptions) => z.ZodType<MulterDiskFileLike, MulterDiskFileLike>;
+/** Unconstrained {@link multerMemoryFile}, for shapes that need no per-field checks. */
+declare const MulterMemoryFileSchema: z.ZodType<MulterMemoryFileLike, MulterMemoryFileLike, z.core.$ZodTypeInternals<MulterMemoryFileLike, MulterMemoryFileLike>>;
+/** Unconstrained {@link multerDiskFile}, for shapes that need no per-field checks. */
+declare const MulterDiskFileSchema: z.ZodType<MulterDiskFileLike, MulterDiskFileLike, z.core.$ZodTypeInternals<MulterDiskFileLike, MulterDiskFileLike>>;
+/**
+ * Declares an endpoint's whole `multipart/form-data` body. Emits the flat
+ * inline `requestBody` Swagger UI's try-it-out form needs, sets
+ * `multipart/form-data` as the consumed type, and is the schema source for
+ * `@ZodUploadedFile` / `@ZodUploadedFiles` / `@ZodMultipartBody`.
+ */
+declare const ZodMultipart: (shape: MultipartShape, options?: ZodMultipartOptions) => MethodDecorator;
+
+export { type MulterDiskFileLike, MulterDiskFileSchema, type MulterFileOptions, type MulterMemoryFileLike, MulterMemoryFileSchema, MultipartShape, ZodMultipart, ZodMultipartOptions, multerDiskFile, multerMemoryFile };

package/dist/express/index.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { B as BaseFileOptions, a as MultipartShape, b as ZodMultipartOptions } from '../zod-multipart.decorator-CjiQkmkR.js';
+export { M as MULTIPART_CONTENT_TYPE, Z as ZodMultipartBody, c as ZodUploadedFile, d as ZodUploadedFiles } from '../zod-multipart.decorator-CjiQkmkR.js';
+import '@nestjs/common';
+import '../registry-C9xStKa6.js';
+
+/**
+ * Shape multer hands you under **memory storage** (`FileInterceptor`'s
+ * default). `buffer` holds the whole file; there is no `path`.
+ */
+interface MulterMemoryFileLike {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    buffer: Buffer;
+}
+/**
+ * Shape multer hands you under **disk storage**. The bytes are on disk at
+ * `path`; there is no `buffer`, so byte-level validation isn't possible.
+ */
+interface MulterDiskFileLike {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    destination: string;
+    filename: string;
+    path: string;
+}
+/**
+ * Options for the multer file helpers. `maxSize` is checked against multer's
+ * reported `size` **after** the file has been read — it documents the limit
+ * and adds defence in depth, but the guard that actually stops a large upload
+ * is multer's own `limits.fileSize`.
+ *
+ * `mimeTypes` and `extensions` match the client-supplied values. They are not
+ * content sniffing; use `@nestjs/common`'s `FileTypeValidator` when you need
+ * magic-number checks.
+ */
+interface MulterFileOptions extends BaseFileOptions {
+    readonly maxSize?: number;
+}
+/** Multer memory-storage file, constrained by `options` and emitted as `format: 'binary'`. */
+declare const multerMemoryFile: (options?: MulterFileOptions) => z.ZodType<MulterMemoryFileLike, MulterMemoryFileLike>;
+/** Multer disk-storage file, constrained by `options` and emitted as `format: 'binary'`. */
+declare const multerDiskFile: (options?: MulterFileOptions) => z.ZodType<MulterDiskFileLike, MulterDiskFileLike>;
+/** Unconstrained {@link multerMemoryFile}, for shapes that need no per-field checks. */
+declare const MulterMemoryFileSchema: z.ZodType<MulterMemoryFileLike, MulterMemoryFileLike, z.core.$ZodTypeInternals<MulterMemoryFileLike, MulterMemoryFileLike>>;
+/** Unconstrained {@link multerDiskFile}, for shapes that need no per-field checks. */
+declare const MulterDiskFileSchema: z.ZodType<MulterDiskFileLike, MulterDiskFileLike, z.core.$ZodTypeInternals<MulterDiskFileLike, MulterDiskFileLike>>;
+/**
+ * Declares an endpoint's whole `multipart/form-data` body. Emits the flat
+ * inline `requestBody` Swagger UI's try-it-out form needs, sets
+ * `multipart/form-data` as the consumed type, and is the schema source for
+ * `@ZodUploadedFile` / `@ZodUploadedFiles` / `@ZodMultipartBody`.
+ */
+declare const ZodMultipart: (shape: MultipartShape, options?: ZodMultipartOptions) => MethodDecorator;
+
+export { type MulterDiskFileLike, MulterDiskFileSchema, type MulterFileOptions, type MulterMemoryFileLike, MulterMemoryFileSchema, MultipartShape, ZodMultipart, ZodMultipartOptions, multerDiskFile, multerMemoryFile };