@pid7/ashwa 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,4 @@
 [![npm](https://img.shields.io/npm/v/@pid7/ashwa?style=flat-square&logo=npm)](https://www.npmjs.com/package/@pid7/ashwa)
-[![Crates.io](https://img.shields.io/crates/v/ashwa?style=flat-square&logo=rust)](https://crates.io/crates/ashwa)
 [![Tests](https://img.shields.io/github/actions/workflow/status/pid7-org/ashwa/tests.yaml?style=flat-square&logo=github&label=tests)](https://github.com/pid7-org/ashwa/actions/workflows/tests.yaml)
 [![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue?style=flat-square)](../LICENSE-MIT)
 
@@ -7,99 +6,196 @@
 
 Hardware accelerated routines for single substring search
 
-> [!TIP]
-> Package is supported in both Node.js and browser environments.
+> 💡 TIP: `@pid7/ashwa` runs seamlessly across Node.js, Bun, Deno, and modern browser / WebWorker environments.
 
-> [!NOTE]
-> The optimal backend (native SIMD bindings for Node / Bun / Deno or WebAssembly SIMD for browsers) is
-> automatically selected at runtime.
+> ℹ️ NOTE: The optimal execution backend (native N-API SIMD bindings for Node / Bun / Deno or WebAssembly
+> SIMD for browsers) is automatically detected and selected at runtime with zero manual configuration.
+
+## Index
+
+- [Supported Platforms](#supported-platforms)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Node](#node)
+  - [Browser](#browser)
+- [API Reference](#api-reference)
+  - [`searchOne`](#searchone)
+  - [`searchTwo`](#searchtwo)
+  - [`init`](#init)
+  - [`initSync`](#initsync)
+  - [`isNative`](#isnative)
+- [Benchmarks](#benchmarks)
+  - [`searchOne`](#searchone-1)
+  - [`searchTwo`](#searchtwo-1)
 
 ## Supported Platforms
 
-| Architecture    | Target Platform                              | Hardware Acceleration                | Fallback    |
-|:----------------|:---------------------------------------------|:-------------------------------------|:------------|
-| x86_64          | Linux, macOS, Windows                        | AVX-512BW, AVX2, SSE4.2, SSSE3, SSE2 | 64-bit SWAR |
-| AArch64 (ARM64) | Apple Silicon, Linux ARM64                   | 128-bit ARM NEON                     | 64-bit SWAR |
-| WebAssembly     | Browsers, Node.js (`wasm32`)                 | WASM SIMD128 (`simd128`)             | 32-bit SWAR |
+| Architecture    | Target Platform                        | Target ISA                           | Fallback    |
+|:----------------|:---------------------------------------|:-------------------------------------|:------------|
+| x86_64          | Linux, macOS, Windows                  | AVX-512BW, AVX2, SSE4.2, SSSE3, SSE2 | 64-bit SWAR |
+| AArch64 (ARM64) | Apple Silicon, Linux ARM64             | 128-bit ARM NEON                     | 64-bit SWAR |
+| WebAssembly     | Browsers, WebWorkers, Node.js (wasm32) | WASM SIMD128 (`simd128`)             | 32-bit SWAR |
 
-## Usage
+## Installation
 
-Install `@pid7/ashwa` via npm:
+Install `@pid7/ashwa` using your preferred package manager:
 
 ```bash
 npm install @pid7/ashwa
 ```
 
-## Example
+## Usage
 
-### ESM & CommonJS (Node.js, Bun, Deno)
+### Node
 
-```javascript
-import { searchOne } from '@pid7/ashwa';
+Native N-API bindings execute _synchronously_ with zero overhead and full hardware SIMD acceleration,
 
-const haystack = new TextEncoder().encode("Hello, World! Fast SIMD Search.");
-const needle = "W".charCodeAt(0);
+```js
+import { searchOne, searchTwo } from '@pid7/ashwa';
 
-const index = searchOne(haystack, needle);
-console.log(`Found 'W' at byte index: ${index}`);
+const haystack = new TextEncoder().encode("The quick brown fox jumps over the lazy dog");
+const indexOne = searchOne(haystack, "f".charCodeAt(0));
+console.log(`Found 'f' at byte index: ${indexOne}`); // 16
 ```
 
-### WASM (Browser / WebWorker)
+### Browser
 
-> **INFO:**
-> In browser/WebWorker environments, WASM automatically initializes on the first call.
+In browser and WebWorker runtimes, WebAssembly SIMD (`simd128`) is used. The WASM module automatically initializes asynchronously on the first search call, or can be pre-warmed during application startup:
 
-```javascript
-import { init, searchOne } from '@pid7/ashwa';
+```js
+import { init, searchOne, searchTwo } from '@pid7/ashwa';
 
-// Optional pre-initialization of WASM module during app startup
+// Optional pre-init
 await init();
 
-const index = searchOne(haystack, needle);
+const haystack = new TextEncoder().encode("The quick brown fox jumps over the lazy dog");
+const index = await searchOne(haystack, "f".charCodeAt(0));
+console.log(`Found 'f' at byte index: ${index}`); // 16
 ```
 
+## API Reference
+
+### `searchOne(haystack, needle)`
+
+```ts
+function searchOne(
+  haystack: Uint8Array,
+  needle: number,
+): number | null | Promise<number | null>;
+```
+
+Searches for the first occurrence of `needle` (byte value `0`–`255`) within `haystack`.
+
+- Parameters:
+  - `haystack`: `Uint8Array` / `Buffer` — The byte sequence to search.
+  - `needle`: `number` — The target byte value (`0`–`255`) to locate.
+- Returns:
+  - In Node.js / Bun / Deno: `number | null` (synchronous 0-based byte index, or `null` if not found).
+  - In Browser / WebWorker: `Promise<number | null>` (resolves to 0-based byte index, or `null` if not found).
+
+### `searchTwo(haystack, needle)`
+
+```ts
+function searchTwo(
+  haystack: Uint8Array,
+  needle: Uint8Array | [number, number] | number[],
+): number | null | Promise<number | null>;
+```
+
+Searches for the first occurrence of a two-byte `needle` within `haystack`.
+
+- Parameters:
+  - `haystack`: `Uint8Array` / `Buffer` — The byte sequence to search.
+  - `needle`: `Uint8Array | [number, number] | number[]` — A 2-byte sequence to locate.
+- Returns:
+  - In Node.js / Bun / Deno: `number | null` (synchronous 0-based byte index, or `null` if not found).
+  - In Browser / WebWorker: `Promise<number | null>` (resolves to 0-based byte index, or `null` if not found).
+
+### `init(moduleOrPath?)`
+
+```typescript
+function init(moduleOrPath?: any): Promise<void>;
+```
+
+Asynchronously pre-initializes the WebAssembly module backend for Browser / WebWorker environments. In native Node.js environments (`isNative === true`), this is a no-op that resolves immediately.
+
+- Parameters:
+  - `moduleOrPath` *(optional)*: `WebAssembly.Module | Response | ArrayBuffer | string` — Custom WASM source or URL.
+
+### `initSync(bytesOrModule?)`
+
+```ts
+function initSync(bytesOrModule?: any): void;
+```
+
+Synchronously initializes the WebAssembly module backend with pre-compiled bytes or a `WebAssembly.Module`. In native Node.js environments, this is a no-op.
+
+- Parameters:
+  - `bytesOrModule` *(optional)*: `ArrayBuffer | Uint8Array | WebAssembly.Module` — Pre-loaded WASM binary or module.
+
+### `isNative`
+
+```typescript
+const isNative: boolean;
+```
+
+Boolean flag indicating whether `@pid7/ashwa` is executing via native N-API bindings (`true`) or WebAssembly SIMD (`false`).
+
 ## Benchmarks
 
-- [`searchOne`](#searchone)
+- [`searchOne`](#searchone-1)
+- [`searchTwo`](#searchtwo-1)
+
+> Benchmarks are evaluated across dedicated AWS EC2 hardware environments on Node.js `v22.23.2`,
+>
+> * x86_64 (_x64_)
+>   * Instance: Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz (8C/16T)
+>   * ISA: _AVX-512BW_ (`+nightly`) · _WASM SIMD128_ (stable)
+>   * Cache: L1d: 384 KiB · L1i: 256 KiB · L2: 10 MiB · L3: 54 MiB
+>   * STREAM Triad: 20.94 GiB/s
+>
+> * AArch64 (_arm64_)
+>   * Instance: AWS Graviton3 ARM Neoverse-V1 (16C/16T)
+>   * ISA: _NEON_ (stable)
+>   * Cache: L1d: 1 MiB · L1i: 1 MiB · L2: 16 MiB · L3: 32 MiB
+>   * STREAM Triad: 75.12 GiB/s
 
 ### `searchOne`
 
 #### Native Node.js (V8 N-API)
 
-For _x86_64_ machine targeting _AVX-512BW_ SIMD ISA,
+| Level      | Payload   | Latency (x64) | Latency (arm64) | Throughput (x64) | Throughput (arm64) |
+|:-----------|:----------|:--------------|:----------------|:-----------------|:-------------------|
+| L1 Cache   | 32 KiB    | 346.28 ns     | 743.33 ns       | 88.13 GiB/s      | 41.06 GiB/s        |
+| L2 Cache   | 512 KiB   | 10.17 µs      | 11.25 µs        | 47.99 GiB/s      | 43.42 GiB/s        |
+| L3 Cache   | 16 MiB    | 552.74 µs     | 381.99 µs       | 28.27 GiB/s      | 40.90 GiB/s        |
+| RAM        | 256 MiB   | 20.22 ms      | 9.96 ms         | 12.36 GiB/s      | 25.10 GiB/s        |
 
-| Level      | Payload   | Latency   | Throughput   |
-|:-----------|:----------|:----------|:-------------|
-| L1 Cache   | 32 KiB    | 640.15 ns | 47.67 GiB/s  |
-| L2 Cache   | 512 KiB   | 10.07 µs  | 48.51 GiB/s  |
-| L3 Cache   | 16 MiB    | 540.35 µs | 28.92 GiB/s  |
-| RAM        | 256 MiB   | 23.88 ms  | 10.47 GiB/s  |
+#### WebAssembly (WASM SIMD128)
 
-Benchmarked using Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz (8C/16T) · L1d: 384 KiB, L1i: 256 KiB, L2: 10 MiB, L3: 54 MiB ·
-STREAM Triad: 20.63 GB/s · Node.js v22.23.2
+| Level      | Payload   | Latency (x64) | Throughput (x64) |
+|:-----------|:----------|:--------------|:-----------------|
+| L1 Cache   | 32 KiB    | 1.62 µs       | 18.82 GiB/s      |
+| L2 Cache   | 512 KiB   | 27.88 µs      | 17.51 GiB/s      |
+| L3 Cache   | 16 MiB    | 1.86 ms       | 8.38 GiB/s       |
+| RAM        | 256 MiB   | 44.56 ms      | 5.61 GiB/s       |
 
-For _aarch64_ machine targeting _NEON_ SIMD ISA,
+### `searchTwo`
 
-| Level      | Payload   | Latency   | Throughput   |
-|:-----------|:----------|:----------|:-------------|
-| L1 Cache   | 32 KiB    | 743.33 ns | 41.06 GiB/s  |
-| L2 Cache   | 512 KiB   | 11.25 µs  | 43.42 GiB/s  |
-| L3 Cache   | 16 MiB    | 381.99 µs | 40.90 GiB/s  |
-| RAM        | 256 MiB   | 9.96 ms   | 25.10 GiB/s  |
+#### Native Node.js (V8 N-API)
 
-Benchmarked using ARM Neoverse-V1 (16C/16T) · L1d: 1 MiB, L1i: 1 MiB, L2: 16 MiB, L3: 32 MiB ·
-STREAM Triad: 75.12 GB/s · Node.js v22.23.2
+| Level      | Payload   | Latency (x64) | Latency (arm64) | Throughput (x64) | Throughput (arm64) |
+|:-----------|:----------|:--------------|:----------------|:-----------------|:-------------------|
+| L1 Cache   | 32 KiB    | 647.01 ns     | 1.57 µs         | 47.17 GiB/s      | 19.44 GiB/s        |
+| L2 Cache   | 512 KiB   | 17.41 µs      | 24.37 µs        | 28.04 GiB/s      | 20.03 GiB/s        |
+| L3 Cache   | 16 MiB    | 657.09 µs     | 788.85 µs       | 23.78 GiB/s      | 19.81 GiB/s        |
+| RAM        | 256 MiB   | 22.50 ms      | 13.13 ms        | 11.11 GiB/s      | 19.04 GiB/s        |
 
 #### WebAssembly (WASM SIMD128)
 
-For _x86_64_ machine targeting _WASM SIMD128_ ISA,
-
-| Level      | Payload   | Latency   | Throughput   |
-|:-----------|:----------|:----------|:-------------|
-| L1 Cache   | 32 KiB    | 1.62 µs   | 18.79 GiB/s  |
-| L2 Cache   | 512 KiB   | 26.81 µs  | 18.21 GiB/s  |
-| L3 Cache   | 16 MiB    | 1.81 ms   | 8.63 GiB/s   |
-| RAM        | 256 MiB   | 44.63 ms  | 5.60 GiB/s   |
-
-Benchmarked using Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz (8C/16T) ·
-L1d: 384 KiB, L1i: 256 KiB, L2: 10 MiB, L3: 54 MiB · STREAM Triad: 20.63 GB/s · Node.js v22.23.2
+| Level      | Payload   | Latency (x64) | Throughput (x64) |
+|:-----------|:----------|:--------------|:-----------------|
+| L1 Cache   | 32 KiB    | 2.17 µs       | 14.06 GiB/s      |
+| L2 Cache   | 512 KiB   | 35.10 µs      | 13.91 GiB/s      |
+| L3 Cache   | 16 MiB    | 3.69 ms       | 4.23 GiB/s       |
+| RAM        | 256 MiB   | 51.67 ms      | 4.84 GiB/s       |

package/browser.js

@@ -4,8 +4,8 @@
  * @module @pid7/ashwa/browser
  */
 
-const fs = require("fs");
-const path = require("path");
+const { readFileSync } = require("fs");
+const { join } = require("path");
 
 let wasmModule = null;
 let initPromise = null;
@@ -27,8 +27,8 @@ async function init(moduleOrPath) {
       process.versions != null &&
       process.versions.node != null
     ) {
-      const wasmPath = path.join(__dirname, "./wasm/pkg/ashwa_wasm_bg.wasm");
-      input = fs.readFileSync(wasmPath);
+      const wasmPath = join(__dirname, "./wasm/pkg/ashwa_wasm_bg.wasm");
+      input = readFileSync(wasmPath);
     }
     const initOptions = input ? { module_or_path: input } : undefined;
     initPromise = Promise.resolve(wasm.default(initOptions)).then(() => {
@@ -54,8 +54,8 @@ function initSync(bytesOrModule) {
     process.versions != null &&
     process.versions.node != null
   ) {
-    const wasmPath = path.join(__dirname, "./wasm/pkg/ashwa_wasm_bg.wasm");
-    input = fs.readFileSync(wasmPath);
+    const wasmPath = join(__dirname, "./wasm/pkg/ashwa_wasm_bg.wasm");
+    input = readFileSync(wasmPath);
   }
   wasm.initSync(input);
   wasmModule = wasm;
@@ -77,6 +77,26 @@ async function searchOne(haystack, needle) {
   return res !== undefined && res !== null ? Number(res) : null;
 }
 
+/**
+ * Searches for the first occurrence of a two-byte `needle` in `haystack` via WebAssembly SIMD.
+ * Automatically initializes WASM if not already loaded.
+ *
+ * @param {Uint8Array} haystack - Byte array to search.
+ * @param {Uint8Array|number[]} needle - 2-byte sequence to locate.
+ * @returns {Promise<number|null>} Resolves to 0-based matching index or null if not found.
+ */
+async function searchTwo(haystack, needle) {
+  const n = Array.isArray(needle) ? new Uint8Array(needle) : needle;
+  if (n == null || n.length !== 2) {
+    throw new TypeError("needle must be a 2-byte sequence");
+  }
+  if (!wasmModule) {
+    await init();
+  }
+  const res = wasmModule.searchTwo(haystack, n);
+  return res !== undefined && res !== null ? Number(res) : null;
+}
+
 module.exports = {
   /**
    * `false` indicating WebAssembly execution mode.
@@ -85,4 +105,5 @@ module.exports = {
   init,
   initSync,
   searchOne,
+  searchTwo,
 };

package/browser.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import initWasm, {
   initSync as wasmInitSync,
   searchOne as wasmSearchOne,
+  searchTwo as wasmSearchTwo,
 } from "./wasm/pkg/ashwa_wasm.js";
 
 let isInitialized = false;
@@ -36,15 +37,17 @@ export async function init(moduleOrPath) {
       process.versions.node != null
     ) {
       const wasmPath = fileURLToPath(
-        new URL("./wasm/pkg/ashwa_wasm_bg.wasm", import.meta.url)
+        new URL("./wasm/pkg/ashwa_wasm_bg.wasm", import.meta.url),
       );
       input = fs.readFileSync(wasmPath);
     }
+
     const options = input ? { module_or_path: input } : undefined;
     initPromise = initWasm(options).then(() => {
       isInitialized = true;
     });
   }
+
   await initPromise;
 }
 
@@ -62,10 +65,12 @@ export function initSync(bytesOrModule) {
     process.versions.node != null
   ) {
     const wasmPath = fileURLToPath(
-      new URL("./wasm/pkg/ashwa_wasm_bg.wasm", import.meta.url)
+      new URL("./wasm/pkg/ashwa_wasm_bg.wasm", import.meta.url),
     );
+
     input = fs.readFileSync(wasmPath);
   }
+
   wasmInitSync(input);
   isInitialized = true;
 }
@@ -82,6 +87,29 @@ export async function searchOne(haystack, needle) {
   if (!isInitialized) {
     await init();
   }
+
   const res = wasmSearchOne(haystack, needle);
   return res !== undefined && res !== null ? Number(res) : null;
 }
+
+/**
+ * Searches for the first occurrence of a two-byte `needle` in `haystack` via WebAssembly SIMD.
+ * Automatically initializes WASM if not already loaded.
+ *
+ * @param {Uint8Array} haystack - Byte array to search.
+ * @param {Uint8Array|number[]} needle - 2-byte sequence to locate.
+ * @returns {Promise<number|null>} Resolves to 0-based matching index or null if not found.
+ */
+export async function searchTwo(haystack, needle) {
+  const n = Array.isArray(needle) ? new Uint8Array(needle) : needle;
+  if (n == null || n.length !== 2) {
+    throw new TypeError("needle must be a 2-byte sequence");
+  }
+
+  if (!isInitialized) {
+    await init();
+  }
+
+  const res = wasmSearchTwo(haystack, n);
+  return res !== undefined && res !== null ? Number(res) : null;
+}

package/index.d.ts

@@ -26,7 +26,33 @@
  */
 export function searchOne(
   haystack: Uint8Array,
-  needle: number
+  needle: number,
+): number | null | Promise<number | null>;
+
+/**
+ * Searches for the first occurrence of a two-byte `needle` within `haystack` (Uint8Array / Buffer).
+ *
+ * Execution backend:
+ * - **Node.js / Bun / Deno**: Executes synchronously via N-API native bindings with SIMD vectorization (AVX-512BW, AVX2, SSE4.2, SSSE3, SSE2, ARM NEON).
+ * - **Browser / WebWorker**: Executes via WebAssembly SIMD (`simd128`), automatically initializing the WASM module on first invocation if not already loaded.
+ *
+ * @param haystack - The byte array/buffer to search.
+ * @param needle - A 2-byte sequence (`Uint8Array`, `Buffer`, or `[number, number]` / `number[]`) to locate.
+ * @returns The 0-based byte index of the first occurrence of `needle`, or `null` if not found.
+ *
+ * @example
+ * ```javascript
+ * import { searchTwo } from '@pid7/ashwa';
+ *
+ * const haystack = new TextEncoder().encode("Hello, World!");
+ * const needle = new Uint8Array(["W".charCodeAt(0), "o".charCodeAt(0)]);
+ * const index = await searchTwo(haystack, needle);
+ * console.log(index); // 7
+ * ```
+ */
+export function searchTwo(
+  haystack: Uint8Array,
+  needle: Uint8Array | [number, number] | number[],
 ): number | null | Promise<number | null>;
 
 /**

package/index.js

@@ -41,6 +41,23 @@ if (isNode) {
       const res = native.searchOne(haystack, needle);
       return res !== undefined && res !== null ? Number(res) : null;
     },
+
+    /**
+     * Searches for the first occurrence of a two-byte `needle` in `haystack`.
+     *
+     * @param {Uint8Array} haystack - Byte array to search.
+     * @param {Uint8Array|number[]} needle - 2-byte sequence to locate.
+     * @returns {number|null} 0-based index or null if not found.
+     */
+    searchTwo(haystack, needle) {
+      const n = Array.isArray(needle) ? new Uint8Array(needle) : needle;
+      if (n == null || n.length !== 2) {
+        throw new TypeError("needle must be a 2-byte sequence");
+      }
+
+      const res = native.searchTwo(haystack, n);
+      return res !== undefined && res !== null ? Number(res) : null;
+    },
   };
 } else {
   module.exports = require("./browser.js");

package/index.mjs

@@ -36,3 +36,20 @@ export function searchOne(haystack, needle) {
   const res = native.searchOne(haystack, needle);
   return res !== undefined && res !== null ? Number(res) : null;
 }
+
+/**
+ * Searches for the first occurrence of a two-byte `needle` in `haystack`.
+ *
+ * @param {Uint8Array} haystack - Byte array to search.
+ * @param {Uint8Array|number[]} needle - 2-byte sequence to locate.
+ * @returns {number|null} 0-based index or null if not found.
+ */
+export function searchTwo(haystack, needle) {
+  const n = Array.isArray(needle) ? new Uint8Array(needle) : needle;
+  if (n == null || n.length !== 2) {
+    throw new TypeError("needle must be a 2-byte sequence");
+  }
+
+  const res = native.searchTwo(haystack, n);
+  return res !== undefined && res !== null ? Number(res) : null;
+}

package/native/index.d.ts

@@ -1,3 +1,33 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
-export declare function searchOne(haystack: Uint8Array, needle: number): number | null
+/**
+ * Searches for the first occurrence of `needle` in `haystack`.
+ *
+ * # Arguments
+ * * `haystack` - A byte slice (`&[u8]`) to search within.
+ * * `needle` - The byte (`u8`) to find.
+ *
+ * # Returns
+ * * `Some(index)` - The 0-based byte index of the first match.
+ * * `None` - If `needle` is not found.
+ */
+export declare function searchOne(
+  haystack: Uint8Array,
+  needle: number,
+): number | null;
+
+/**
+ * Searches for the first occurrence of a two-byte `needle` in `haystack`.
+ *
+ * # Arguments
+ * * `haystack` - A byte slice (`&[u8]`) to search within.
+ * * `needle` - A 2-byte slice (`&[u8]`) to locate.
+ *
+ * # Returns
+ * * `Some(index)` - The 0-based byte index of the first match.
+ * * `None` - If `needle` is not found.
+ */
+export declare function searchTwo(
+  haystack: Uint8Array,
+  needle: Uint8Array,
+): number | null;