# pompelmi

> ClamAV antivirus scanning for Node.js — clean, typed, zero dependencies.

pompelmi is a minimal Node.js wrapper around ClamAV that exposes async functions for scanning files, buffers, streams, and directories for malware. It returns typed Symbol verdicts and has zero runtime dependencies.

## API

- `scan(filePath, [options])` — scan a file by path
- `scanBuffer(buffer, [options])` — scan an in-memory Buffer
- `scanStream(stream, [options])` — scan a Readable stream
- `scanDirectory(dirPath, [options])` — recursively scan a directory

All functions return `Promise<symbol>` resolving to one of:
- `Verdict.Clean` — no threats found
- `Verdict.Malicious` — known malware signature matched
- `Verdict.ScanError` — scan failed, treat as untrusted

Options: `{ host?: string, port?: number, timeout?: number }`
- Local mode: spawns `clamscan`, maps exit codes to verdicts
- TCP mode: streams to clamd via INSTREAM protocol (set `host`)

## Framework integrations

Official packages for popular frameworks:

- `@pompelmi/nestjs` — NestJS module (`PompelmiModule`, `PompelmiService`, `PompelmiInterceptor`)
- `@pompelmi/fastify` — Fastify plugin (decorates `fastify.pompelmi` with scan/preHandler)
- `@pompelmi/hono` — Hono middleware (`pompelmiMiddleware`) for Node.js, Bun, Cloudflare Workers
- `@pompelmi/remix` — Remix upload handler (`pompelmiUploadHandler` for `unstable_parseMultipartFormData`)
- `@pompelmi/sveltekit` — SvelteKit helper (`scanUpload`, `scanFormData` for +page.server.ts and +server.ts)
- `@pompelmi/nextjs` — Next.js App Router / Pages Router helpers
- `@pompelmi/testing` — test utilities (`mockClean`, `mockInfected`, `withMockedPompelmi`)

## Installation

npm install pompelmi

ClamAV must be installed separately: `brew install clamav && freshclam`

## Links

- npm: https://www.npmjs.com/package/pompelmi
- GitHub: https://github.com/pompelmi/pompelmi
- Docs: https://pompelmi.app
