fastbloom 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# fastbloom
+
+A **blazingly fast** Bloom Filter for Node.js, implemented in Rust with native concurrency support.
+
+**~40x faster** than the popular `bloom-filters` npm package, thanks to Rust's performance and parallel processing capabilities.
+
+## Features
+
+- **Exceptionally Fast**: Built on top of the `fastbloom` Rust crate with atomic operations, achieving ~40x speedup compared to `bloom-filters` npm package
+- **Concurrent Operations**: Thread-safe implementation using `AtomicBloomFilter` - all operations can be called concurrently from multiple threads
+- **Parallel Bulk Operations**: Uses `rayon` for parallel processing of bulk additions, maximizing multi-core CPU utilization
+- **Optimal Sizing**: Automatically calculates the optimal bit array size and number of hash functions based on your desired capacity and false positive rate
+- **N-API**: Uses N-API for stable Node.js ABI compatibility across Node.js versions
+- **Zero-Cost Abstractions**: Direct Rust implementation with minimal JavaScript overhead
+
+## Installation
+
+```bash
+npm install
+```
+
+## Build
+
+You need to have Rust installed (`cargo`).
+
+```bash
+npm run build
+```
+
+This will compile the Rust code and generate the `index.js` binding file.
+
+## Usage
+
+```javascript
+const { BloomFilter } = require('./index.js');
+
+// 1. Initialize
+// Capacity: 1,000,000 items
+// False Positive Rate: 1% (0.01)
+const filter = new BloomFilter(1000000, 0.01);
+
+// 2. Add items (thread-safe)
+filter.add('hello');
+filter.add('world');
+
+// 3. Check for existence (thread-safe)
+console.log(filter.has('hello'));    // true
+console.log(filter.has('universe')); // false
+
+// 4. Bulk add (parallel processing for maximum performance)
+filter.bulk_add(['apple', 'banana', 'cherry', 'date', 'elderberry']);
+```
+
+## API
+
+### `new BloomFilter(capacity, false_positive_rate)`
+
+Creates a new Bloom Filter with the specified parameters.
+
+- **capacity** (`number`): The expected number of items to be stored (must be > 0)
+- **false_positive_rate** (`number`): The desired false positive rate between 0 and 1 (e.g., 0.01 for 1%)
+
+**Throws**: Error if capacity is not greater than 0 or if false positive rate is not between 0 and 1.
+
+### `add(item)`
+
+Adds an item to the Bloom Filter. **Thread-safe** - can be called concurrently.
+
+- **item** (`string`): The item to add
+
+### `has(item)`
+
+Checks if an item is possibly in the Bloom Filter. **Thread-safe** - can be called concurrently.
+
+- **item** (`string`): The item to check
+- **Returns**: `boolean` - `true` if the item is possibly in the filter, `false` if definitely not
+
+### `bulk_add(items)`
+
+Adds multiple items to the Bloom Filter using **parallel processing**. **Thread-safe** - can be called concurrently.
+
+- **items** (`string[]`): Array of items to add
+
+This method uses `rayon` for parallel iteration, making it significantly faster than calling `add()` repeatedly for large datasets.

package/index.d.ts

@@ -0,0 +1,33 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare class BloomFilter {
+  /**
+   * Creates a new Bloom Filter with the specified capacity and false positive rate.
+   * @param capacity - The expected number of items to be stored in the Bloom Filter.
+   * @param false_positive_rate - The desired false positive rate (between 0 and 1).
+   * @throws Will throw an error if the capacity is not greater than 0 or if the false positive rate is not between 0 and 1.
+   * @returns A new instance of the Bloom Filter.
+   */
+  constructor(capacity: number, falsePositiveRate: number)
+  /**
+   * Adds an item to the Bloom Filter. This method is thread-safe and can be called concurrently from multiple threads.
+   * @param item - The item to be added to the Bloom Filter.
+   * @returns void
+   */
+  add(item: string): void
+  /**
+   * Checks if an item is possibly in the Bloom Filter. This method is thread-safe and can be called concurrently from multiple threads.
+   * @param item - The item to be checked for membership in the Bloom Filter.
+   * @returns A boolean indicating whether the item is possibly in the Bloom Filter (true) or definitely not in the Bloom Filter (false).
+   */
+  has(item: string): boolean
+  /**
+   * Adds multiple items to the Bloom Filter in parallel. This method is thread-safe and can be called concurrently from multiple threads.
+   * @param items - An array of items to be added to the Bloom Filter.
+   * @returns void
+   */
+  bulkAdd(items: Array<string>): void
+}

package/index.js

@@ -0,0 +1,315 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'fastbloom.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.android-arm64.node')
+          } else {
+            nativeBinding = require('fastbloom-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'fastbloom.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('fastbloom-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'fastbloom.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('fastbloom-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'fastbloom.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('fastbloom-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'fastbloom.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('fastbloom-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'fastbloom.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./fastbloom.darwin-universal.node')
+      } else {
+        nativeBinding = require('fastbloom-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'fastbloom.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.darwin-x64.node')
+          } else {
+            nativeBinding = require('fastbloom-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'fastbloom.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.darwin-arm64.node')
+          } else {
+            nativeBinding = require('fastbloom-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'fastbloom.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./fastbloom.freebsd-x64.node')
+      } else {
+        nativeBinding = require('fastbloom-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'fastbloom.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./fastbloom.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('fastbloom-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'fastbloom.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./fastbloom.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('fastbloom-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { BloomFilter } = nativeBinding
+
+module.exports.BloomFilter = BloomFilter

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "fastbloom",
+	"version": "0.1.0",
+	"description": "High performance Bloom Filter implemented in Rust using fastbloom crate",
+	"main": "index.js",
+	"scripts": {
+		"build": "napi build --platform --release",
+		"test": "node test.js"
+	},
+	"dependencies": {
+		"@napi-rs/cli": "^2.18.0"
+	},
+	"files": [
+		"index.js",
+		"index.d.ts",
+		"*.node" 
+	],
+	"napi": {
+		"name": "fastbloom",
+		"triples": {
+			"defaults": true,
+			"additional": [
+				"x86_64-unknown-linux-musl",
+				"aarch64-unknown-linux-gnu",
+				"aarch64-apple-darwin",
+				"aarch64-pc-windows-msvc"
+			]
+		}
+	}
+}