pompelmi 1.4.0 → 1.5.0

package/README.md

@@ -7,16 +7,33 @@
 <p align="center"><strong>ClamAV antivirus scanning for Node.js — clean, typed, zero dependencies.</strong></p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/dw/pompelmi" alt="npm weekly downloads"></a>
-  <a href="https://github.com/pompelmi/pompelmi"><img src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" alt="GitHub stars"></a>
-  <img src="https://img.shields.io/badge/docker-available-blue?logo=docker" alt="Docker available">
+  <img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version">
+  <img src="https://img.shields.io/npm/dw/pompelmi" alt="npm downloads">
   <img src="https://img.shields.io/badge/license-ISC-blue.svg" alt="license">
-  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies">
+</p>
+
+<p align="center">
   <img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="Node.js CI">
   <img src="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml/badge.svg" alt="npm publish">
 </p>
 
+<p align="center">
+  <img src="https://img.shields.io/badge/express-available-black?logo=express" alt="Express">
+  <img src="https://img.shields.io/badge/fastify-available-black?logo=fastify" alt="Fastify">
+  <img src="https://img.shields.io/badge/nestjs-available-red?logo=nestjs" alt="NestJS">
+  <img src="https://img.shields.io/badge/koa-available-lightgrey?logo=node.js" alt="Koa">
+  <img src="https://img.shields.io/badge/hono-available-orange" alt="Hono">
+  <img src="https://img.shields.io/badge/next.js-available-black?logo=next.js" alt="Next.js">
+  <img src="https://img.shields.io/badge/sveltekit-available-red?logo=svelte" alt="SvelteKit">
+  <img src="https://img.shields.io/badge/remix-available-black?logo=remix" alt="Remix">
+  <img src="https://img.shields.io/badge/docker-available-blue?logo=docker" alt="Docker">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" alt="GitHub stars">
+</p>
+
 ---
 
 ## Overview
@@ -45,6 +62,7 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - Single `scan(filePath, [options])` function — works locally or against a remote clamd instance
 - `scanBuffer(buffer, [options])` — scan in-memory Buffers directly, no temp file required in TCP mode
 - `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.
+- `scanDirectory(dirPath, [options])` — recursively scan every file in a directory, returns clean/malicious/errors arrays
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full TCP/clamd support via the INSTREAM protocol with configurable host, port, and timeout
 - Built-in helpers to install ClamAV and update virus definitions programmatically
@@ -216,6 +234,22 @@ const files    = ['/uploads/a.pdf', '/uploads/b.zip', '/uploads/c.png'];
 const results = await Promise.all(files.map((f) => scan(f)));
 ```
 
+### Scan a Directory
+
+```js
+const fs = require('fs');
+const { scanDirectory } = require('pompelmi');
+
+const results = await scanDirectory('/uploads');
+
+console.log('Clean:', results.clean);
+console.log('Malicious:', results.malicious);
+console.log('Errors:', results.errors);
+
+// Delete all malicious files
+results.malicious.forEach(f => fs.unlinkSync(f));
+```
+
 ### Scan a Buffer
 
 ```js
@@ -368,6 +402,34 @@ In TCP mode (`host` or `port` provided), the stream is piped directly to clamd v
 
 ---
 
+### `scanDirectory(dirPath, [options])`
+
+```ts
+scanDirectory(
+  dirPath: string,
+  options?: { host?: string; port?: number; timeout?: number }
+): Promise<{ clean: string[], malicious: string[], errors: string[] }>
+```
+
+Recursively scans every file in `dirPath` and returns three arrays of absolute paths.
+
+| Field | Type | Description |
+|---|---|---|
+| `clean` | `string[]` | Paths of files with no threats found |
+| `malicious` | `string[]` | Paths of files with a matched signature |
+| `errors` | `string[]` | Paths of files that could not be scanned |
+
+Per-file scan failures are caught and collected into `errors` — the function never throws because of an individual file.
+
+**Rejects** with an `Error` in these cases:
+
+| Condition | Error message |
+|---|---|
+| `dirPath` is not a string | `dirPath must be a string` |
+| Directory does not exist | `Directory not found: <path>` |
+
+---
+
 ### `ClamAVInstaller()` _(internal)_
 
 Installs ClamAV using the platform's native package manager. Resolves immediately if ClamAV is already installed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",
@@ -36,6 +36,9 @@
     "test": "node --test test/unit.test.js && node test/scan.test.js",
     "lint": "eslint src/"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {},
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/ClamAVScanner.js

@@ -4,6 +4,7 @@ const os   = require('os');
 const path = require('path');
 const { Readable }               = require('stream');
 const { SCAN_RESULTS }           = require('./config.js');
+const { Verdict }                = require('./verdicts.js');
 const { scanViaClamd }           = require('./ClamdScanner.js');
 const { scanBufferViaClamd }     = require('./BufferScanner.js');
 const { scanStreamViaClamd }     = require('./StreamScanner.js');
@@ -100,4 +101,40 @@ async function scanStream(stream, options = {}) {
     }
 }
 
-module.exports = { scan, scanBuffer, scanStream };
+async function scanDirectory(dirPath, options = {}) {
+    if (typeof dirPath !== 'string') {
+        throw new Error('dirPath must be a string');
+    }
+    if (!fs.existsSync(dirPath)) {
+        throw new Error(`Directory not found: ${dirPath}`);
+    }
+
+    const entries = fs.readdirSync(dirPath, { recursive: true });
+    const files = entries
+        .map(entry => path.join(dirPath, entry))
+        .filter(fullPath => fs.statSync(fullPath).isFile());
+
+    const results = await Promise.all(
+        files.map(async (filePath) => {
+            try {
+                return { filePath, verdict: await scan(filePath, options) };
+            } catch {
+                return { filePath, verdict: null };
+            }
+        })
+    );
+
+    const clean = [];
+    const malicious = [];
+    const errors = [];
+
+    for (const { filePath, verdict } of results) {
+        if (verdict === Verdict.Clean)     clean.push(filePath);
+        else if (verdict === Verdict.Malicious) malicious.push(filePath);
+        else                               errors.push(filePath);
+    }
+
+    return { clean, malicious, errors };
+}
+
+module.exports = { scan, scanBuffer, scanStream, scanDirectory };

package/src/index.js

@@ -1,4 +1,4 @@
-const { scan, scanBuffer, scanStream } = require('./ClamAVScanner.js');
-const { Verdict }                       = require('./verdicts.js');
+const { scan, scanBuffer, scanStream, scanDirectory } = require('./ClamAVScanner.js');
+const { Verdict }                                     = require('./verdicts.js');
 
-module.exports = { scan, scanBuffer, scanStream, Verdict };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict };