Migrate addon to N-API; add async & prebuilds

Migrate native addon from nan to node-addon-api and add a JS wrapper/ESM entry (index.js / index.mjs). Implement genAsync (worker-thread async) and make output length configurable (1–22, default 8) with input validation and a 64KB input limit. Replace hex-path with an optimized Base62 encoder, add thorough OpenSSL return-value checks, and update binding.gyp for N-API and Windows OpenSSL settings.

Add prebuild support (prebuildify + node-gyp-build), a prebuild CI workflow, and integrate prebuild download into the publish workflow so most users won't need a compiler. Expand CI to test Linux/macOS/Windows across Node 20/22/24. Update package.json (version → 1.2.0, exports field, scripts, deps/devDeps) and add bench.js, CLI length/version flags, TypeScript defs (index.d.ts), .editorconfig and ESLint config, README and CHANGELOG entries documenting the changes.

Author: youhide

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.cpp]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.eslintrc.cjs

@@ -0,0 +1,17 @@
+module.exports = {
+  env: {
+    node: true,
+    es2022: true
+  },
+  parserOptions: {
+    ecmaVersion: 2022
+  },
+  rules: {
+    'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    'no-undef': 'error',
+    'no-process-exit': 'off',
+    eqeqeq: ['error', 'always', { null: 'ignore' }],
+    'no-var': 'error',
+    'prefer-const': 'error'
+  }
+};

.github/workflows/ci.yml

@@ -2,36 +2,53 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   build:
-    runs-on: ubuntu-latest
-    
     strategy:
+      fail-fast: false
       matrix:
-        node-version: [20.x, 21.x, 22.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [20.x, 22.x, 24.x]
+
+    runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4
-      
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          
-      - name: Install OpenSSL
+
+      - name: Install OpenSSL (Ubuntu)
+        if: runner.os == 'Linux'
         run: |
           sudo apt-get update
           sudo apt-get install -y libssl-dev
-          
+
+      - name: Install OpenSSL (macOS)
+        if: runner.os == 'macOS'
+        run: brew install openssl
+
+      - name: Install OpenSSL (Windows)
+        if: runner.os == 'Windows'
+        run: choco install openssl -y
+        shell: cmd
+
+      - name: Set OpenSSL env (Windows)
+        if: runner.os == 'Windows'
+        run: echo "OPENSSL_ROOT=C:\Program Files\OpenSSL-Win64" >> $env:GITHUB_ENV
+        shell: pwsh
+
       - name: Install dependencies
         run: npm ci
-        
+
       - name: Build
         run: npm run build
-        
+
       - name: Test
         run: npm test

.github/workflows/prebuild.yml

@@ -0,0 +1,65 @@
+name: Prebuild
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  prebuild:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            arch: x64
+          - os: ubuntu-24.04-arm
+            arch: arm64
+          - os: macos-latest
+            arch: x64+arm64
+          - os: windows-latest
+            arch: x64
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
+      - name: Install OpenSSL (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libssl-dev
+
+      - name: Install OpenSSL (macOS)
+        if: runner.os == 'macOS'
+        run: brew install openssl
+
+      - name: Install OpenSSL (Windows)
+        if: runner.os == 'Windows'
+        run: choco install openssl -y
+        shell: cmd
+
+      - name: Set OpenSSL env (Windows)
+        if: runner.os == 'Windows'
+        run: echo "OPENSSL_ROOT=C:\Program Files\OpenSSL-Win64" >> $env:GITHUB_ENV
+        shell: pwsh
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Prebuild
+        run: npx prebuildify --napi --strip
+
+      - name: Upload prebuilds
+        uses: actions/upload-artifact@v4
+        with:
+          name: prebuilds-${{ matrix.os }}-${{ matrix.arch }}
+          path: prebuilds/

.github/workflows/publish.yml

@@ -1,12 +1,16 @@
 name: NPM Publish
 
 on:
-  # release:
-  #   types: [created]
+  release:
+    types: [created]
   workflow_dispatch:
 
 jobs:
+  prebuild:
+    uses: ./.github/workflows/prebuild.yml
+
   publish:
+    needs: prebuild
     runs-on: ubuntu-latest
 
     steps:
@@ -18,11 +22,20 @@ jobs:
           node-version: "20.x"
           registry-url: "https://registry.npmjs.org"
 
-      - name: Install dependencies
+      - name: Download all prebuilds
+        uses: actions/download-artifact@v4
+        with:
+          pattern: prebuilds-*
+          path: prebuilds/
+          merge-multiple: true
+
+      - name: Install OpenSSL
         run: |
           sudo apt-get update
           sudo apt-get install -y libssl-dev
-          npm ci
+
+      - name: Install dependencies
+        run: npm ci
 
       - name: Build
         run: npm run build

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 build/
+prebuilds/
 local.test.js

.npmignore

@@ -2,4 +2,8 @@
 build/
 test.js
 local.test.js
+bench.js
 CHANGELOG.md
+.editorconfig
+.eslintrc.cjs
+.gitignore

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-03-26
+
+### Added
+- `genAsync(input, length?)` — async version using worker threads for non-blocking operation
+- Configurable output length: `gen(input, length?)` with length 1-22 (default: 8)
+- ESM support via `index.mjs` and `"exports"` field in package.json
+- Prebuilt binaries via `prebuildify` — no compiler needed on most platforms
+- Input type validation — non-string arguments now throw `TypeError`
+- Input size limit (64KB) — oversized inputs throw `RangeError`
+- OpenSSL error checking — all EVP API return values are validated
+- Multi-platform CI testing (Linux, macOS, Windows)
+- CLI `--length` / `-l` option for custom output length
+- CLI `--version` / `-v` flag
+- `.editorconfig` and ESLint configuration
+- Benchmark script (`npm run bench`)
+- Collision probability documentation in README
+
+### Changed
+- Migrated from `nan` to `node-addon-api` (N-API) for ABI stability across Node.js versions
+- `install` script now uses `node-gyp-build` (tries prebuilt first, falls back to compile)
+- Entry point changed from `./build/Release/shortener.node` to `./index.js` (JS wrapper)
+- Performance: eliminated intermediate hex string conversion in SHA-256 → Base62 pipeline
+- Performance: optimized Base62 encoding (reverse-build instead of O(n²) prepend)
+- CI now tests Node.js 20, 22, 24 across Linux, macOS, and Windows
+- Publish workflow now builds prebuilt binaries before publishing
+- Updated Windows OpenSSL library reference
+
+### Removed
+- Removed `nan` dependency (replaced by `node-addon-api`)
+
 ## [1.1.0] - 2026-01-27
 
 ### Added

README.md

@@ -2,27 +2,64 @@
 
 # theShortener
 
-A fast string shortener that generates 8-character codes using SHA-256 and Base62 encoding, implemented as a native Node.js addon in C++.
+A fast string shortener that generates short codes using SHA-256 and Base62 encoding, implemented as a native Node.js addon in C++.
 
 ## Features
-- Fast native C++ implementation
-- Consistent 8-character outputs
+- Fast native C++ implementation (N-API)
+- Configurable output length (1-22 characters, default 8)
+- Async support (`genAsync`) for non-blocking operation
+- Prebuilt binaries for major platforms (no compiler needed)
 - Cryptographically secure using SHA-256
-- Base62 encoding (0-9, a-z, A-Z)
-- Deterministic results - same input produces same output
+- Base62 encoding (0-9, A-Z, a-z)
+- Deterministic results - same input always produces same output
+- ESM and CommonJS support
+- CLI included
 
 ## Installation
 ```bash
-npm install theshortener --save
+npm install theshortener
 ```
 
+Prebuilt binaries are included for Linux, macOS, and Windows. Falls back to compiling from source if no prebuild is available (requires C++ compiler + OpenSSL dev libraries).
+
 ## Usage
+
+### CommonJS
 ```javascript
 const shortener = require('theshortener');
 
-// Generate short code
-const shortCode = shortener.gen('https://google.com');
-console.log(shortCode); // Outputs: "Qhq1TQ2n"
+const code = shortener.gen('https://google.com');
+console.log(code); // "Qhq1TQ2n"
+
+// Custom length (1-22)
+const short = shortener.gen('https://google.com', 6);
+console.log(short); // "Qhq1TQ"
+```
+
+### ESM
+```javascript
+import { gen, genAsync } from 'theshortener';
+
+const code = gen('https://google.com');
+```
+
+### Async
+```javascript
+const { genAsync } = require('theshortener');
+
+const code = await genAsync('https://google.com');
+console.log(code); // "Qhq1TQ2n"
+
+// Custom length
+const long = await genAsync('https://google.com', 16);
+```
+
+### TypeScript
+```typescript
+import { gen, genAsync } from 'theshortener';
+
+const code: string = gen('https://google.com');
+const asyncCode: string = await genAsync('https://google.com', 12);
 ```
 
 ## CLI Usage
@@ -33,13 +70,33 @@ npm i -g theshortener
 Use from command line:
 ```bash
 theshortener https://google.com
-Qhq1TQ2n
+# Qhq1TQ2n
+
+theshortener --length 12 https://google.com
+
+theshortener --version
+theshortener --help
 ```
 
+## API
+
+### `gen(input: string, length?: number): string`
+
+Generate a short code synchronously.
+
+- **input** — String to shorten (max 64KB)
+- **length** — Output length, 1-22 (default: 8)
+- **returns** — Alphanumeric string of the specified length
+- **throws** — `TypeError` if input is missing, not a string, or empty; `RangeError` if input exceeds 64KB or length is out of range
+
+### `genAsync(input: string, length?: number): Promise<string>`
+
+Same as `gen()` but runs SHA-256 + Base62 encoding in a worker thread.
+
 ## Development
 #### Prerequisites:
 
-- Node.js
+- Node.js >= 20
 - C++ compiler
 - OpenSSL development libraries
 
@@ -53,18 +110,21 @@ npm run build
 npm test
 ```
 
-## TypeScript
-```typescript
-import shortener from 'theshortener';
-
-const code: string = shortener.gen('https://google.com');
+#### Run benchmarks:
+```bash
+npm run bench
 ```
 
+## Collision Probability
+
+The default 8-character output uses 64 bits of the SHA-256 hash, providing approximately 47.6 bits of entropy in Base62. By the birthday paradox, you can expect a ~50% collision probability after roughly 2³² (~4.3 billion) unique inputs. For fewer collisions, use a longer output length.
+
 ## Notes
 
-- The output is always 8 characters long
+- Uses N-API (Node-API) for ABI stability across Node.js versions
 - Uses OpenSSL for SHA-256 hashing
-- This is a one-way hashing implementation. Reverse lookups (getting original STR from short code) require storing STR-to-hash mappings in a database.
+- This is a one-way hashing implementation. Reverse lookups (getting original string from short code) require storing input-to-code mappings in a database
+- Shorter lengths are prefixes of longer outputs (same input)
 
 ## License
 MIT