@apeleghq/sha2 0.1.1 → 0.1.3

package/README.md

@@ -35,33 +35,35 @@ yarn add @apeleghq/sha2
 
 ## 📦 Package contents
 
-- Compiled WebAssembly module (.wasm), transpiled to JavaScript
+- Compiled WebAssembly module (.wasm) in two versions:
+  * Transpiled to JavaScript
+  * As native WASM objects (`/wasm` export path)
 - JS/ESM glue to load the module
 - TypeScript declaration file (.d.ts) — the API described below
-- README, LICENSE
 
 ## 🔌 API Overview
 
-The module exports a single async default function that initialises the WASM module and returns factories for the enabled SHA-2 variants.
+The module exports a single async default function that initialises the WASM
+module and returns factories for the enabled SHA-2 variants.
 
-Signature (from the .d.ts):
+Signature (from the `.d.ts`):
 
 - Default export: `async function (): Promise<Sha2Factories<...>>`
 
 Returned object contains one property per enabled algorithm (examples: `sha256`, `sha512`, etc.). Each property is a constructor/factory function with these behaviours:
 
 Hash instance methods:
-- `update(data: ArrayBuffer | ArrayBufferView, scrub?: boolean): void`
-- `finalize(scrub?: boolean): ArrayBuffer`
+- `update(data: ArrayBufferLike | ArrayBufferView, scrub?: boolean): void`
+- `finalize(scrub?: boolean): ArrayBufferLike`
 - `reset(): void`
-- `digest(data: ArrayBuffer | ArrayBufferView, scrub?: boolean): ArrayBuffer` —
+- `digest(data: ArrayBufferLike | ArrayBufferView, scrub?: boolean): ArrayBuffer` —
   one-shot convenience (throws if instance is streaming)
 
-Optional (when serialize feature enabled):
-- `serialize(scrub?: boolean): ArrayBuffer`
+Optional (when `serialize` feature enabled):
+- `serialize(scrub?: boolean): ArrayBufferLike`
 
 Constructors may also accept a serialized state to resume:
-- `constructor(serializedData?: ArrayBuffer | ArrayBufferView | null, scrub?: boolean)`
+- `constructor(serializedData?: ArrayBufferLike | ArrayBufferView | null, scrub?: boolean)`
 
 See the bundled `.d.ts` for exact types.
 
@@ -94,7 +96,7 @@ h.reset(); // reuse
 Serialisation / resuming:
 
 ```javascript
-import sha2 from '@apeleghq/sha2';
+import sha2 from '@apeleghq/sha2/wasm';
 
 const factories = await sha2();
 const h = factories.sha256();
@@ -118,12 +120,18 @@ Apart from the main export at the root (`@apeleghq/sha2`), there are additional
 exports based on specific build-time features. This enables selecting just those
 features that are needed to reduce bundle size.
 
-#### Example
+#### WASM exports
+
+The `/wasm` export path prefix can be used to select native WASM instead of WASM
+transpiled to JS. For example:
 
+- `@apeleghq/sha2` -> `@apeleghq/sha2/wasm`
+- `@apeleghq/sha2/sha256+streaming` -> `@apeleghq/sha2/wasm/sha256+streaming`
+
+#### Example
 
 ```javascript
-// Just some 
-import sha2_ɑ from '@apeleghq/sha2/sha256+sha384+streaming';
+import sha2_ɑ from '@apeleghq/sha2/wasm/sha256+sha384+streaming';
 import sha2_β from '@apeleghq/sha2/sha384+deserialize+serialize+streaming';
 
 const factories_ɑ = await sha2_ɑ();
@@ -171,23 +179,168 @@ const digest = h.digest(new TextEncoder().encode('hello'));
 console.log(Buffer.from(digest).toString('hex'));
 ```
 
+## Benchmark
+
+<details>
+<summary>
+Benchmark results comparing various NPM packages and `SubtleCrypto`
+</summary>
+
+Generated using the project under the `ecmascript/benchmark` directory in
+Node.js v24.14.0. Like all benchmarks, results are estimative and dependent on
+the specific environment they're generated in.
+
+> [!IMPORTANT]
+> All results are experimental and should not be used for production
+> decision-making.
+
+### Critical limitations
+
+- **Environment-Specific**: Results were measured on:
+  - Hardware: Google Axion (Arm64) -- `c4a-standard-2` (2 vCPUs, 8 GB memory)
+  - OS: Debian GNU/Linux 13 (trixie)
+  - Node.js: v24.14.1
+- **Methodology**:
+  - Tests ran with `4096 iterations` per method:
+    * 32 trials of 128 runs (plus 64 warm up runs)
+  - Measured using `benchmark/src/index.js`
+- **Key Caveats**:
+  1. Results **do not account for real-world network delays or memory constraints**.
+  2. This benchmark focuses on *raw execution speed*, not security or
+     correctness.
+  3. Results do not account for conversions between different output formats
+     (for example, from `Uint8Array` to `string`).
+
+### Results
+
+```
+================================================================================
+SHA-256 BENCHMARK RESULTS                          (All values in ms)
+================================================================================
+
+Buffer Size: 1.00 KiB | Iterations: 4096
+--------------------------------------------------------------------------------
+Package                     Time (ms)       Ops/s       MiB/s      Relative
+--------------------------------------------------------------------------------
+hash-wasm                     17.753         230719.25   225.31     1.00      ⭐
+@apeleghq/sha2 (WASM)         20.588         198949.70   194.29     1.16
+sha256-uint8array             23.341         175483.48   171.37     1.31
+fast-sha256                   27.349         149768.12   146.26     1.54
+@apeleghq/sha2 (ES)           33.844         121026.92   118.19     1.91
+@aws-crypto/sha256-js         42.635          96070.89    93.82     2.40
+sha.js                        51.790          79087.98    77.23     2.92
+js-sha256                     52.268          78365.01    76.53     2.94
+SubtleCrypto.digest           68.663          59653.84    58.26     3.87
+jssha                        102.478          39969.55    39.03     5.77
+================================================================================
+
+Buffer Size: 8.00 KiB | Iterations: 4096
+--------------------------------------------------------------------------------
+Package                     Time (ms)       Ops/s       MiB/s      Relative
+--------------------------------------------------------------------------------
+SubtleCrypto.digest           96.141         42603.93    332.84     1.00      ⭐
+hash-wasm                    115.893         35342.83    276.12     1.21
+@apeleghq/sha2 (WASM)        124.304         32951.59    257.43     1.29
+fast-sha256                  152.721         26820.07    209.53     1.59
+sha256-uint8array            168.277         24340.83    190.16     1.75
+@apeleghq/sha2 (ES)          226.813         18058.93    141.09     2.36
+@aws-crypto/sha256-js        248.146         16506.41    128.96     2.58
+sha.js                       376.289         10885.26     85.04     3.91
+js-sha256                    378.601         10818.77     84.52     3.94
+jssha                        657.563          6229.06     48.66     6.84
+================================================================================
+
+Buffer Size: 64.00 KiB | Iterations: 4096
+--------------------------------------------------------------------------------
+Package                     Time (ms)       Ops/s       MiB/s      Relative
+--------------------------------------------------------------------------------
+SubtleCrypto.digest           211.157        19397.90    1212.37     1.00     ⭐
+hash-wasm                     906.215         4519.90     282.49     4.29
+@apeleghq/sha2 (WASM)         966.743         4236.91     264.81     4.58
+fast-sha256                  1158.363         3536.02     221.00     5.49
+sha256-uint8array            1331.600         3076.00     192.25     6.31
+@apeleghq/sha2 (ES)          1779.562         2301.69     143.86     8.43
+@aws-crypto/sha256-js        1923.719         2129.21     133.08     9.11
+sha.js                       2978.650         1375.12      85.94    14.11
+js-sha256                    2996.032         1367.14      85.45    14.19
+jssha                        5391.971          759.65      47.48    25.54
+================================================================================
+
+Buffer Size: 128.00 KiB | Iterations: 4096
+--------------------------------------------------------------------------------
+Package                     Time (ms)       Ops/s       MiB/s      Relative
+--------------------------------------------------------------------------------
+SubtleCrypto.digest            359.274       11400.77    1425.10     1.00     ⭐
+hash-wasm                     1808.039        2265.44     283.18     5.03
+@apeleghq/sha2 (WASM)         1929.769        2122.53     265.32     5.37
+fast-sha256                   2306.780        1775.64     221.95     6.42
+sha256-uint8array             2660.531        1539.54     192.44     7.41
+@apeleghq/sha2 (ES)           3546.149        1155.06     144.38     9.87
+@aws-crypto/sha256-js         3889.897        1052.98     131.62    10.83
+sha.js                        5951.984         688.17      86.02    16.57
+js-sha256                     5987.387         684.10      85.51    16.67
+jssha                        10723.736         381.96      47.74    29.85
+================================================================================
+
+Buffer Size: 1.00 MiB | Iterations: 4096
+--------------------------------------------------------------------------------
+Package                     Time (ms)       Ops/s       MiB/s      Relative
+--------------------------------------------------------------------------------
+SubtleCrypto.digest           2458.762       1665.88     1665.88     1.00     ⭐
+hash-wasm                    14453.914        283.38      283.38     5.88
+@apeleghq/sha2 (WASM)        15421.658        265.60      265.60     6.27
+fast-sha256                  18399.600        222.61      222.61     7.48
+sha256-uint8array            21265.097        192.62      192.62     8.65
+@apeleghq/sha2 (ES)          28366.398        144.40      144.40    11.54
+@aws-crypto/sha256-js        30942.575        132.37      132.37    12.58
+sha.js                       47629.494         86.00       86.00    19.37
+js-sha256                    47870.311         85.56       85.56    19.47
+jssha                        89912.620         45.56       45.56    36.57
+================================================================================
+
+Buffer Size: 8.00 MiB | Iterations: 4096
+--------------------------------------------------------------------------------
+Package                     Time (ms)       Ops/s       MiB/s      Relative
+--------------------------------------------------------------------------------
+SubtleCrypto.digest           19917.685      205.65      1645.17     1.00     ⭐
+hash-wasm                    116757.365       35.08       280.65     5.86
+@apeleghq/sha2 (WASM)        124076.017       33.01       264.10     6.23
+fast-sha256                  147128.769       27.84       222.72     7.39
+sha256-uint8array            170127.878       24.08       192.61     8.54
+@apeleghq/sha2 (ES)          227447.728       18.01       144.07    11.42
+@aws-crypto/sha256-js        246919.825       16.59       132.71    12.40
+sha.js                       380766.733       10.76        86.06    19.12
+js-sha256                    382639.567       10.70        85.64    19.21
+jssha                        689309.321        5.94        47.54    34.61
+================================================================================
+
+================================================================================
+SUMMARY: Fastest package by buffer size
+================================================================================
+Buffer Size          Fastest Package
+--------------------------------------------------------------------------------
+1.00 KiB             hash-wasm
+8.00 KiB             SubtleCrypto.digest
+64.00 KiB            SubtleCrypto.digest
+128.00 KiB           SubtleCrypto.digest
+1.00 MiB             SubtleCrypto.digest
+8.00 MiB             SubtleCrypto.digest
+================================================================================
+```
+</details>
+
 ## ⚙️ Build features
 
 Build-time feature flags (available via `import.meta.features` in the bundling
 environment) control which algorithms and optional capabilities are compiled in:
 
 - `sha224`, `sha256`, `sha384`, `sha512`, `sha512_256`
-- `serialize`, `deserialize` — enables `serialize`/`deserialize` APIs
-  (for importing and exporting the hasher state)
+- `serialize`, `deserialize` — enables `serialize` / `deserialize` APIs,
+  respectively (for importing and exporting the hasher state)
 
 The TypeScript declaration mirrors which factories are present according to the
 build features.
 
-## 📦 Distribution targets
-
-- ESM (recommended)
-- Node.js and browser-compatible WASM + light JS loader included
-
 ## 🤝 Contributing
 
 Contributions welcome. Open issues or pull requests in the repository.