pompelmi 1.9.0 → 1.10.0

package/README.md

@@ -27,6 +27,7 @@
 |-------|-------------|
 | [Getting Started](./docs/getting-started.md) | Installation, prerequisites, quickstart examples |
 | [API Reference](./docs/api.md) | Full function signatures, options, verdicts, error conditions |
+| [S3 Integration](./docs/s3.md) | Scan S3 objects directly, IAM setup, Lambda pattern |
 | [Docker / Remote Scanning](./docs/docker.md) | TCP sidecar, UNIX socket mount, docker-compose patterns |
 | [GitHub Action](./docs/github-action.md) | CI scanning, inputs/outputs, caching, example workflows |
 
@@ -59,6 +60,10 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - `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
+- `scanS3(params, [options])` — scan S3 objects by streaming directly from AWS S3, no disk I/O
+- `createPool([options])` — persistent connection pool for high-throughput clamd scanning
+- `watch(dirPath, [options], callbacks)` — watch a directory and auto-scan new/modified files (300 ms debounce)
+- Auto-retry on connection error — `retries` and `retryDelay` options on every scan function
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full clamd support via the INSTREAM protocol — TCP (`host`/`port`) or UNIX socket (`socket`) with configurable timeout
 - Built-in helpers to install ClamAV and update virus definitions programmatically
@@ -296,12 +301,14 @@ See **[docs/docker.md](./docs/docker.md)** for Docker Compose examples, UNIX soc
 
 pompelmi has no configuration file or environment variables. All options are passed directly to `scan()`.
 
-| Option    | Type     | Default         | Description                            |
-|-----------|----------|-----------------|----------------------------------------|
-| `socket`  | `string` | —               | Path to a clamd UNIX domain socket (e.g. `/run/clamav/clamd.sock`). Takes precedence over `host`/`port` when set. |
-| `host`    | `string` | —               | clamd hostname. Enables TCP mode when set. |
-| `port`    | `number` | `3310`          | clamd port.                            |
-| `timeout` | `number` | `15000`         | Socket idle timeout in milliseconds (clamd mode only). |
+| Option       | Type     | Default | Description                            |
+|--------------|----------|---------|----------------------------------------|
+| `socket`     | `string` | —       | Path to a clamd UNIX domain socket (e.g. `/run/clamav/clamd.sock`). Takes precedence over `host`/`port` when set. |
+| `host`       | `string` | —       | clamd hostname. Enables TCP mode when set. |
+| `port`       | `number` | `3310`  | clamd port.                            |
+| `timeout`    | `number` | `15000` | Socket idle timeout in milliseconds (clamd mode only). |
+| `retries`    | `number` | `0`     | Automatic retry attempts on connection error. |
+| `retryDelay` | `number` | `1000`  | Milliseconds to wait between retries. |
 
 When none of `socket`, `host`, or `port` is provided, pompelmi spawns `clamscan --no-summary <filePath>` locally.
 
@@ -313,12 +320,15 @@ See **[docs/api.md](./docs/api.md)** for the full reference: function signatures
 
 **Quick summary:**
 
-| Function | Input | clamd mode disk I/O |
-|----------|-------|---------------------|
-| `scan(filePath, [options])` | File path on disk | None (streamed) |
+| Function | Input | Disk I/O |
+|----------|-------|----------|
+| `scan(filePath, [options])` | File path on disk | None in clamd mode (streamed) |
 | `scanBuffer(buffer, [options])` | `Buffer` | None (streamed) |
 | `scanStream(stream, [options])` | Node.js `Readable` | None (streamed) |
-| `scanDirectory(dirPath, [options])` | Directory path | None (streamed) |
+| `scanDirectory(dirPath, [options])` | Directory path | None in clamd mode |
+| `scanS3(params, [options])` | S3 bucket + key | None (streamed from S3) |
+| `createPool([options])` | — | Returns a `ClamdPool` |
+| `watch(dirPath, [options], callbacks)` | Directory path | None in clamd mode |
 
 All four functions accept the same `options` object and resolve to the same three verdict Symbols:
 
@@ -473,7 +483,6 @@ Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing. To r
 
 ## Coming soon
 
-- [ ] AWS S3 integration — scan objects directly from S3 without downloading
 - [ ] Cloudflare Workers support — edge-native scanning via the clamd TCP protocol
 - [ ] NestJS official module — `PompelmiModule.forRoot()` with injectable `PompelmiService`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.9.0",
+  "version": "1.10.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",

package/src/BufferScanner.js

@@ -26,45 +26,59 @@ function parseClamdResponse(raw) {
  * @param {number} [options.timeout=15000]
  * @returns {Promise<symbol>}
  */
-function scanBufferViaClamd(buffer, { host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = {}) {
-    return new Promise((resolve, reject) => {
-        const connOpts = socketPath ? { path: socketPath } : { host, port };
-        const conn     = net.createConnection(connOpts);
-        const chunks   = [];
-        let   settled  = false;
+function scanBufferViaClamd(buffer, options = {}) {
+    const { retries = 0, retryDelay = 1000, host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = options;
 
-        function settle(fn, value) {
-            if (settled) return;
-            settled = true;
-            conn.destroy();
-            fn(value);
-        }
+    function attempt() {
+        return new Promise((resolve, reject) => {
+            const connOpts = socketPath ? { path: socketPath } : { host, port };
+            const conn     = net.createConnection(connOpts);
+            const chunks   = [];
+            let   settled  = false;
 
-        conn.setTimeout(timeout);
-        conn.on('timeout', () =>
-            settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
-        );
-        conn.on('error', (err) => settle(reject, err));
-        conn.on('data',  (chunk) => chunks.push(chunk));
-        conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
+            function settle(fn, value) {
+                if (settled) return;
+                settled = true;
+                conn.destroy();
+                fn(value);
+            }
 
-        conn.on('connect', () => {
-            conn.write(CLAMD_INSTREAM);
+            conn.setTimeout(timeout);
+            conn.on('timeout', () =>
+                settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
+            );
+            conn.on('error', (err) => settle(reject, err));
+            conn.on('data',  (chunk) => chunks.push(chunk));
+            conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
 
-            let offset = 0;
-            while (offset < buffer.length) {
-                const chunk  = buffer.slice(offset, offset + CHUNK_SIZE);
-                const header = Buffer.allocUnsafe(4);
-                header.writeUInt32BE(chunk.length, 0);
-                conn.write(header);
-                conn.write(chunk);
-                offset += chunk.length;
-            }
+            conn.on('connect', () => {
+                conn.write(CLAMD_INSTREAM);
+
+                let offset = 0;
+                while (offset < buffer.length) {
+                    const chunk  = buffer.slice(offset, offset + CHUNK_SIZE);
+                    const header = Buffer.allocUnsafe(4);
+                    header.writeUInt32BE(chunk.length, 0);
+                    conn.write(header);
+                    conn.write(chunk);
+                    offset += chunk.length;
+                }
 
-            conn.write(Buffer.alloc(4)); // terminating zero-length chunk
-            conn.end();
+                conn.write(Buffer.alloc(4)); // terminating zero-length chunk
+                conn.end();
+            });
         });
-    });
+    }
+
+    function run(left) {
+        return attempt().catch(async (err) => {
+            if (left <= 0) throw err;
+            await new Promise(r => setTimeout(r, retryDelay));
+            return run(left - 1);
+        });
+    }
+
+    return run(retries);
 }
 
 module.exports = { scanBufferViaClamd };

package/src/ClamdPool.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const net  = require('net');
+const fs   = require('fs');
+const { Verdict } = require('./verdicts.js');
+
+const CLAMD_INSTREAM = Buffer.from('zINSTREAM\0');
+const CHUNK_SIZE     = 64 * 1024;
+
+function parseClamdResponse(raw) {
+    const text = raw.toString('utf8').replace(/\0/g, '').trim();
+    if (text === 'stream: OK')   return Verdict.Clean;
+    if (text.endsWith(' FOUND')) return Verdict.Malicious;
+    return Verdict.ScanError;
+}
+
+// One INSTREAM scan on a persistent socket. Does NOT call sock.end() — connection stays open.
+// Detects end-of-response via the null terminator sent by clamd (z-prefix protocol).
+function scanOnSocket(sock, sendPayload) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let   done   = false;
+
+        function settle(fn, val) {
+            if (done) return;
+            done = true;
+            sock.removeListener('data',  onData);
+            sock.removeListener('end',   onEnd);
+            sock.removeListener('error', onError);
+            fn(val);
+        }
+
+        function onData(chunk) {
+            chunks.push(chunk);
+            const buf = Buffer.concat(chunks);
+            if (buf.includes(0)) settle(resolve, parseClamdResponse(buf));
+        }
+        function onEnd()      { settle(resolve, parseClamdResponse(Buffer.concat(chunks))); }
+        function onError(err) { settle(reject, err); }
+
+        sock.on('data',  onData);
+        sock.on('end',   onEnd);
+        sock.on('error', onError);
+
+        sock.write(CLAMD_INSTREAM);
+        sendPayload(sock, (err) => settle(reject, err));
+    });
+}
+
+function openConnection(connOpts, timeout) {
+    return new Promise((resolve, reject) => {
+        const sock = net.createConnection(connOpts);
+        let   done = false;
+        function settle(err) {
+            if (done) return;
+            done = true;
+            if (err) { sock.destroy(); reject(err); }
+            else resolve(sock);
+        }
+        sock.setTimeout(timeout);
+        sock.on('timeout', () => settle(new Error(`clamd connect timed out after ${timeout}ms`)));
+        sock.once('error',   (err) => settle(err));
+        sock.once('connect', () => { sock.setTimeout(0); settle(null); });
+    });
+}
+
+/**
+ * Create a pool of `size` persistent clamd connections.
+ *
+ * @param {object} [options]
+ * @param {string} [options.host='127.0.0.1']
+ * @param {number} [options.port=3310]
+ * @param {string} [options.socket]   - UNIX socket path (takes precedence over host/port)
+ * @param {number} [options.size=5]   - Maximum number of concurrent connections
+ * @param {number} [options.timeout=15000]
+ * @returns {{ scan, scanBuffer, scanStream, destroy }}
+ */
+function createPool({ host = '127.0.0.1', port = 3310, socket: socketPath, size = 5, timeout = 15_000 } = {}) {
+    const connOpts = socketPath ? { path: socketPath } : { host, port };
+    const slots    = Array.from({ length: size }, () => ({ socket: null, busy: false }));
+    const queue    = [];
+
+    function dequeue(slot) {
+        slot.busy = false;
+        if (queue.length > 0) {
+            const { fn, resolve, reject } = queue.shift();
+            runOnSlot(slot, fn).then(resolve, reject);
+        }
+    }
+
+    async function ensureConnected(slot) {
+        if (slot.socket && !slot.socket.destroyed && slot.socket.readyState === 'open') return;
+        if (slot.socket && !slot.socket.destroyed) slot.socket.destroy();
+        slot.socket = await openConnection(connOpts, timeout);
+        const sock = slot.socket;
+        sock.on('error', () => { if (slot.socket === sock) slot.socket = null; });
+    }
+
+    async function runOnSlot(slot, fn) {
+        slot.busy = true;
+        try {
+            await ensureConnected(slot);
+            return await fn(slot.socket);
+        } catch (err) {
+            if (slot.socket) { slot.socket.destroy(); slot.socket = null; }
+            throw err;
+        } finally {
+            dequeue(slot);
+        }
+    }
+
+    function enqueue(fn) {
+        return new Promise((resolve, reject) => {
+            const free = slots.find(s => !s.busy);
+            if (free) {
+                runOnSlot(free, fn).then(resolve, reject);
+            } else {
+                queue.push({ fn, resolve, reject });
+            }
+        });
+    }
+
+    return {
+        scan(filePath) {
+            if (typeof filePath !== 'string')
+                return Promise.reject(new Error('filePath must be a string'));
+            if (!fs.existsSync(filePath))
+                return Promise.reject(new Error(`File not found: ${filePath}`));
+            return enqueue((sock) => scanOnSocket(sock, (s, onErr) => {
+                const stream = fs.createReadStream(filePath, { highWaterMark: CHUNK_SIZE });
+                stream.on('error', onErr);
+                stream.on('data', (chunk) => {
+                    const hdr = Buffer.allocUnsafe(4);
+                    hdr.writeUInt32BE(chunk.length, 0);
+                    s.write(hdr);
+                    s.write(chunk);
+                });
+                stream.on('end', () => s.write(Buffer.alloc(4)));
+            }));
+        },
+
+        scanBuffer(buffer) {
+            return enqueue((sock) => scanOnSocket(sock, (s) => {
+                let offset = 0;
+                while (offset < buffer.length) {
+                    const chunk = buffer.subarray(offset, offset + CHUNK_SIZE);
+                    const hdr   = Buffer.allocUnsafe(4);
+                    hdr.writeUInt32BE(chunk.length, 0);
+                    s.write(hdr);
+                    s.write(chunk);
+                    offset += chunk.length;
+                }
+                s.write(Buffer.alloc(4));
+            }));
+        },
+
+        scanStream(stream) {
+            return enqueue((sock) => scanOnSocket(sock, (s, onErr) => {
+                stream.on('error', onErr);
+                stream.on('data', (chunk) => {
+                    const hdr = Buffer.allocUnsafe(4);
+                    hdr.writeUInt32BE(chunk.length, 0);
+                    s.write(hdr);
+                    s.write(chunk);
+                });
+                stream.on('end', () => s.write(Buffer.alloc(4)));
+            }));
+        },
+
+        destroy() {
+            for (const slot of slots) {
+                if (slot.socket) { slot.socket.destroy(); slot.socket = null; }
+                slot.busy = false;
+            }
+            while (queue.length > 0) {
+                const { reject } = queue.shift();
+                reject(new Error('Pool destroyed'));
+            }
+        },
+    };
+}
+
+module.exports = { createPool };

package/src/ClamdScanner.js

@@ -31,55 +31,69 @@ function parseClamdResponse(raw) {
  * @param {number} [options.timeout=15000]  - Socket idle timeout in ms.
  * @returns {Promise<'Clean'|'Malicious'|'ScanError'>}
  */
-function scanViaClamd(filePath, { host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = {}) {
-    return new Promise((resolve, reject) => {
-        if (typeof filePath !== 'string') {
-            return reject(new Error('filePath must be a string'));
-        }
-        if (!fs.existsSync(filePath)) {
-            return reject(new Error(`File not found: ${filePath}`));
-        }
-
-        const connOpts   = socketPath ? { path: socketPath } : { host, port };
-        const conn       = net.createConnection(connOpts);
-        const chunks     = [];
-        let   settled    = false;
-
-        function settle(fn, value) {
-            if (settled) return;
-            settled = true;
-            conn.destroy();
-            fn(value);
-        }
-
-        conn.setTimeout(timeout);
-        conn.on('timeout', () =>
-            settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
-        );
-        conn.on('error', (err) => settle(reject, err));
-        conn.on('data',  (chunk) => chunks.push(chunk));
-        conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
-
-        conn.on('connect', () => {
-            conn.write(CLAMD_INSTREAM);
-
-            const fileStream = fs.createReadStream(filePath, { highWaterMark: CHUNK_SIZE });
-
-            fileStream.on('error', (err) => settle(reject, err));
-
-            fileStream.on('data', (chunk) => {
-                const header = Buffer.allocUnsafe(4);
-                header.writeUInt32BE(chunk.length, 0);
-                conn.write(header);
-                conn.write(chunk);
-            });
+function scanViaClamd(filePath, options = {}) {
+    const { retries = 0, retryDelay = 1000, host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = options;
+
+    function attempt() {
+        return new Promise((resolve, reject) => {
+            if (typeof filePath !== 'string') {
+                return reject(new Error('filePath must be a string'));
+            }
+            if (!fs.existsSync(filePath)) {
+                return reject(new Error(`File not found: ${filePath}`));
+            }
+
+            const connOpts   = socketPath ? { path: socketPath } : { host, port };
+            const conn       = net.createConnection(connOpts);
+            const chunks     = [];
+            let   settled    = false;
+
+            function settle(fn, value) {
+                if (settled) return;
+                settled = true;
+                conn.destroy();
+                fn(value);
+            }
+
+            conn.setTimeout(timeout);
+            conn.on('timeout', () =>
+                settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
+            );
+            conn.on('error', (err) => settle(reject, err));
+            conn.on('data',  (chunk) => chunks.push(chunk));
+            conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
+
+            conn.on('connect', () => {
+                conn.write(CLAMD_INSTREAM);
 
-            fileStream.on('end', () => {
-                conn.write(Buffer.alloc(4)); // terminating zero-length chunk
-                conn.end();
+                const fileStream = fs.createReadStream(filePath, { highWaterMark: CHUNK_SIZE });
+
+                fileStream.on('error', (err) => settle(reject, err));
+
+                fileStream.on('data', (chunk) => {
+                    const header = Buffer.allocUnsafe(4);
+                    header.writeUInt32BE(chunk.length, 0);
+                    conn.write(header);
+                    conn.write(chunk);
+                });
+
+                fileStream.on('end', () => {
+                    conn.write(Buffer.alloc(4)); // terminating zero-length chunk
+                    conn.end();
+                });
             });
         });
-    });
+    }
+
+    function run(left) {
+        return attempt().catch(async (err) => {
+            if (left <= 0) throw err;
+            await new Promise(r => setTimeout(r, retryDelay));
+            return run(left - 1);
+        });
+    }
+
+    return run(retries);
 }
 
 module.exports = { scanViaClamd };

package/src/S3Scanner.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { scanStream } = require('./ClamAVScanner.js');
+const { Readable }   = require('stream');
+
+/**
+ * Scan an S3 object by streaming it directly to clamd — no disk I/O.
+ *
+ * Requires @aws-sdk/client-s3: npm install @aws-sdk/client-s3
+ *
+ * @param {{ bucket: string, key: string, region?: string, credentials?: object }} s3Params
+ * @param {object} [options] - Same options as scanStream (host, port, socket, timeout, retries, retryDelay)
+ * @returns {Promise<symbol>}
+ */
+async function scanS3({ bucket, key, region, credentials } = {}, options = {}) {
+    let S3Client, GetObjectCommand;
+    try {
+        ({ S3Client, GetObjectCommand } = require('@aws-sdk/client-s3'));
+    } catch {
+        throw new Error('Install AWS SDK: npm install @aws-sdk/client-s3');
+    }
+
+    const clientOpts = {};
+    if (region)      clientOpts.region      = region;
+    if (credentials) clientOpts.credentials = credentials;
+
+    const client   = new S3Client(clientOpts);
+    const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+
+    const body = response.Body;
+    const stream = body instanceof Readable
+        ? body
+        : (Readable.fromWeb ? Readable.fromWeb(body) : body);
+
+    return scanStream(stream, options);
+}
+
+module.exports = { scanS3 };

package/src/StreamScanner.js

@@ -25,46 +25,60 @@ function parseClamdResponse(raw) {
  * @param {number} [options.timeout=15000]
  * @returns {Promise<symbol>}
  */
-function scanStreamViaClamd(stream, { host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = {}) {
-    return new Promise((resolve, reject) => {
-        const connOpts = socketPath ? { path: socketPath } : { host, port };
-        const conn     = net.createConnection(connOpts);
-        const chunks   = [];
-        let   settled  = false;
+function scanStreamViaClamd(stream, options = {}) {
+    const { retries = 0, retryDelay = 1000, host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = options;
 
-        function settle(fn, value) {
-            if (settled) return;
-            settled = true;
-            conn.destroy();
-            fn(value);
-        }
+    function attempt() {
+        return new Promise((resolve, reject) => {
+            const connOpts = socketPath ? { path: socketPath } : { host, port };
+            const conn     = net.createConnection(connOpts);
+            const chunks   = [];
+            let   settled  = false;
 
-        conn.setTimeout(timeout);
-        conn.on('timeout', () =>
-            settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
-        );
-        conn.on('error', (err) => settle(reject, err));
-        conn.on('data',  (chunk) => chunks.push(chunk));
-        conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
+            function settle(fn, value) {
+                if (settled) return;
+                settled = true;
+                conn.destroy();
+                fn(value);
+            }
 
-        conn.on('connect', () => {
-            conn.write(CLAMD_INSTREAM);
+            conn.setTimeout(timeout);
+            conn.on('timeout', () =>
+                settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
+            );
+            conn.on('error', (err) => settle(reject, err));
+            conn.on('data',  (chunk) => chunks.push(chunk));
+            conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
 
-            stream.on('error', (err) => settle(reject, err));
+            conn.on('connect', () => {
+                conn.write(CLAMD_INSTREAM);
 
-            stream.on('data', (chunk) => {
-                const header = Buffer.allocUnsafe(4);
-                header.writeUInt32BE(chunk.length, 0);
-                conn.write(header);
-                conn.write(chunk);
-            });
+                stream.on('error', (err) => settle(reject, err));
+
+                stream.on('data', (chunk) => {
+                    const header = Buffer.allocUnsafe(4);
+                    header.writeUInt32BE(chunk.length, 0);
+                    conn.write(header);
+                    conn.write(chunk);
+                });
 
-            stream.on('end', () => {
-                conn.write(Buffer.alloc(4)); // terminating zero-length chunk
-                conn.end();
+                stream.on('end', () => {
+                    conn.write(Buffer.alloc(4)); // terminating zero-length chunk
+                    conn.end();
+                });
             });
         });
-    });
+    }
+
+    function run(left) {
+        return attempt().catch(async (err) => {
+            if (left <= 0) throw err;
+            await new Promise(r => setTimeout(r, retryDelay));
+            return run(left - 1);
+        });
+    }
+
+    return run(retries);
 }
 
 module.exports = { scanStreamViaClamd };

package/src/Watcher.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { scan }    = require('./ClamAVScanner.js');
+const { Verdict } = require('./verdicts.js');
+
+const DEBOUNCE_MS = 300;
+
+/**
+ * Watch a directory for new/modified files and scan each one automatically.
+ * Uses fs.watch (no dependencies) with a 300 ms debounce.
+ *
+ * @param {string} dirPath
+ * @param {object} [options] - Passed to scan() (host, port, socket, timeout, retries, retryDelay)
+ * @param {{ onClean?: Function, onMalicious?: Function, onError?: Function }} [callbacks]
+ * @returns {import('fs').FSWatcher}
+ */
+function watch(dirPath, options = {}, { onClean, onMalicious, onError } = {}) {
+    const timers = new Map();
+
+    return fs.watch(dirPath, { recursive: true }, (_eventType, filename) => {
+        if (!filename) return;
+
+        const fullPath = path.join(dirPath, filename);
+
+        if (timers.has(fullPath)) clearTimeout(timers.get(fullPath));
+
+        timers.set(fullPath, setTimeout(async () => {
+            timers.delete(fullPath);
+
+            if (!fs.existsSync(fullPath)) return;
+
+            let stat;
+            try { stat = fs.statSync(fullPath); } catch { return; }
+            if (!stat.isFile()) return;
+
+            try {
+                const verdict = await scan(fullPath, options);
+                if (verdict === Verdict.Clean)          onClean     && onClean(fullPath);
+                else if (verdict === Verdict.Malicious) onMalicious && onMalicious(fullPath);
+                else                                    onError     && onError(new Error(`ScanError for ${fullPath}`), fullPath);
+            } catch (err) {
+                onError && onError(err, fullPath);
+            }
+        }, DEBOUNCE_MS));
+    });
+}
+
+module.exports = { watch };

package/src/index.js

@@ -1,5 +1,8 @@
 const { scan, scanBuffer, scanStream, scanDirectory } = require('./ClamAVScanner.js');
 const { Verdict }                                     = require('./verdicts.js');
 const { middleware }                                  = require('./middleware.js');
+const { scanS3 }                                      = require('./S3Scanner.js');
+const { createPool }                                  = require('./ClamdPool.js');
+const { watch }                                       = require('./Watcher.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch };

package/types/index.d.ts

@@ -1,4 +1,5 @@
 import { Readable } from 'stream';
+import { FSWatcher } from 'fs';
 import { IncomingMessage, ServerResponse } from 'http';
 
 /** Options passed to any scan function */
@@ -11,6 +12,10 @@ export interface ScanOptions {
   socket?: string;
   /** Socket idle timeout in milliseconds, clamd mode only (default: 15000) */
   timeout?: number;
+  /** Number of retry attempts on connection error (default: 0) */
+  retries?: number;
+  /** Delay in milliseconds between retries (default: 1000) */
+  retryDelay?: number;
 }
 
 /** Options for the Express/Fastify middleware */
@@ -80,3 +85,70 @@ export declare function scanDirectory(
  * Call after multer, before your route handler.
  */
 export declare function middleware(options?: MiddlewareOptions): RequestHandler;
+
+/** Parameters for scanS3 */
+export interface S3ScanParams {
+  /** S3 bucket name */
+  bucket: string;
+  /** S3 object key */
+  key: string;
+  /** AWS region */
+  region?: string;
+  /** AWS credentials object */
+  credentials?: object;
+}
+
+/**
+ * Scan an S3 object by streaming it directly via GetObjectCommand — no disk I/O.
+ * Requires @aws-sdk/client-s3 to be installed separately.
+ */
+export declare function scanS3(params: S3ScanParams, options?: ScanOptions): Promise<VerdictValue>;
+
+/** Options for createPool */
+export interface PoolOptions {
+  host?: string;
+  port?: number;
+  socket?: string;
+  /** Number of persistent connections to maintain (default: 5) */
+  size?: number;
+  timeout?: number;
+}
+
+/** A pool of persistent clamd connections */
+export interface ClamdPool {
+  /** Scan a file by path using a pooled connection */
+  scan(filePath: string): Promise<VerdictValue>;
+  /** Scan an in-memory Buffer using a pooled connection */
+  scanBuffer(buffer: Buffer): Promise<VerdictValue>;
+  /** Scan a Readable stream using a pooled connection */
+  scanStream(stream: Readable): Promise<VerdictValue>;
+  /** Destroy all pooled connections and reject any queued requests */
+  destroy(): void;
+}
+
+/**
+ * Create a pool of persistent clamd connections for high-throughput scanning.
+ * Queues requests when all connections are busy.
+ */
+export declare function createPool(options?: PoolOptions): ClamdPool;
+
+/** Callbacks for the watch() function */
+export interface WatchCallbacks {
+  /** Called when a scanned file is clean */
+  onClean?: (filePath: string) => void;
+  /** Called when a scanned file is malicious */
+  onMalicious?: (filePath: string) => void;
+  /** Called on scan error or infrastructure failure */
+  onError?: (err: Error, filePath?: string) => void;
+}
+
+/**
+ * Watch a directory for new/modified files and scan each automatically.
+ * Uses fs.watch with a 300 ms debounce. No dependencies.
+ * Returns an FSWatcher; call .close() to stop watching.
+ */
+export declare function watch(
+  dirPath: string,
+  options?: ScanOptions,
+  callbacks?: WatchCallbacks
+): FSWatcher;