@litko/yara-x 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,5 @@
 # @litko/yara-x
 
-**v0.1.1**
-
 ## Features
 
 - High Performance: Built with [napi-rs](https://napi-rs.com) and [VirusTotal/yara-x](https://github.com/VirusTotal/yara-x)
@@ -246,11 +244,17 @@ const rules = compile(
     // Ignore specific modules
     ignoreModules: ["pe"],
 
-  :  // Error on potentially slow patterns
+    // Error on potentially slow patterns
     errorOnSlowPattern: true,
 
     // Error on potentially slow loops
     errorOnSlowLoop: true,
+
+    // Specify directories for include statements (v1.5.0+)
+    includeDirectories: ["./rules/includes", "./rules/common"],
+
+    // Enable or disable include statements (v1.5.0+)
+    enableIncludes: true,
   },
 );
 ```
@@ -361,33 +365,128 @@ if (warnings.length > 0) {
 }
 ```
 
+## Include Directories
+
+```javascript
+import { compile } from "@litko/yara-x";
+
+// Create a main rule that includes other rules
+const mainRule = `
+  include "common/strings.yar"
+  include "malware/pe_patterns.yar"
+
+  rule main_detection {
+    condition:
+      common_string_rule or pe_malware_rule
+  }
+`;
+
+// Compile with include directories
+const rules = compile(mainRule, {
+  includeDirectories: [
+    "./rules", // Base directory
+    "./rules/common", // Additional include path
+    "./rules/malware", // Another include path
+  ],
+});
+
+// Scan as usual
+const matches = rules.scan(Buffer.from("test data"));
+```
+
+## Scan Performance Options
+
+Control scanning behavior for better performance or safety.
+
+### Limiting Matches Per Pattern
+
+Prevent excessive memory usage by limiting the number of matches per pattern:
+
+```javascript
+import { compile } from "@litko/yara-x";
+
+const rules = compile(`
+  rule find_pattern {
+    strings:
+      $a = "pattern"
+    condition:
+      $a
+  }
+`);
+
+// Limit to 1000 matches per pattern
+rules.setMaxMatchesPerPattern(1000);
+
+// Scan data with many occurrences
+const data = Buffer.from("pattern ".repeat(10000));
+const matches = rules.scan(data);
+
+// Will only return up to 1000 matches per pattern
+console.log(`Found ${matches[0].matches.length} matches (limited to 1000)`);
+```
+
+### Memory-Mapped File Control
+
+Control whether to use memory-mapped files for scanning:
+
+```javascript
+import { compile } from "@litko/yara-x";
+
+const rules = compile(`
+  rule test {
+    strings:
+      $a = "test"
+    condition:
+      $a
+  }
+`);
+
+// Disable memory-mapped files for safer scanning
+// (slower but safer for untrusted files)
+rules.setUseMmap(false);
+
+// Scan file without memory mapping
+const matches = rules.scanFile("./sample.bin");
+```
+
 ## Performance Benchmarks
 
-**Test Setup:**
+`node-yara-x` delivers exceptional performance through intelligent scanner caching and optimized Rust implementation.
 
-- **Hardware:** MacBook Pro (M3 Max, 36GB RAM)
-- **Test Data:** Generated data of varying sizes (small: 64 bytes, medium: 100KB, large: 10MB). See `__test__/benchmark.mjs` for data generation and benchmarking code.
-- The Large test file (10MB) is auto-generated, to prevent bloating the size of the repository.
+### Benchmark Results
 
-**Key Metrics (Averages):**
+Test Environment: MacBook Pro M3 Max, 36GB RAM, Release build with LTO
+Methodology: Statistical analysis across multiple iterations with percentile reporting
 
-| Operation                                       | Average Time | Iterations |      p50 |      p95 |      p99 |
-| :---------------------------------------------- | -----------: | ---------: | -------: | -------: | -------: |
-| Scanner Creation (Simple Rule)                  |     1.675 ms |        100 | 1.547 ms | 2.318 ms | 2.657 ms |
-| Scanner Creation (Complex Rule)                 |     1.878 ms |        100 | 1.848 ms | 2.005 ms | 2.865 ms |
-| Scanner Creation (Regex Rule)                   |     2.447 ms |        100 | 2.444 ms | 2.473 ms | 2.569 ms |
-| Scanner Creation (Multiple Rules)               |     1.497 ms |        100 | 1.488 ms | 1.547 ms | 1.819 ms |
-| Scanning Small Data (64 bytes, Simple Rule)     |     0.145 ms |       1000 | 0.143 ms | 0.156 ms | 0.169 ms |
-| Scanning Medium Data (100KB, Simple Rule)       |     0.151 ms |        100 | 0.146 ms | 0.179 ms | 0.205 ms |
-| Scanning Large Data (10MB, Simple Rule)         |     0.347 ms |         10 | 0.340 ms | 0.394 ms | 0.394 ms |
-| Scanning Medium Data (100KB, Complex Rule)      |     0.219 ms |        100 | 0.215 ms | 0.254 ms | 0.269 ms |
-| Scanning Medium Data (100KB, Regex Rule)        |     0.156 ms |        100 | 0.152 ms | 0.182 ms | 0.210 ms |
-| Scanning Medium Data (100KB, Multiple Rules)    |     0.218 ms |        100 | 0.212 ms | 0.261 ms | 0.353 ms |
-| Async Scanning Medium Data (100KB, Simple Rule) |     0.012 ms |        100 | 0.011 ms | 0.016 ms |  0.027ms |
-| Scanning with Variables                         |     0.143 ms |       1000 | 0.140 ms | 0.155 ms | 0.166 ms |
-| Scanning with Variables (Override at Scan Time) |     0.144 ms |       1000 | 0.142 ms | 0.158 ms | 0.175 ms |
+#### Scanner Creation Performance
 
-# API Reference
+| Rule Type      | Mean   | p50    | p95    | p99    |
+| -------------- | ------ | ------ | ------ | ------ |
+| Simple Rule    | 2.43ms | 2.41ms | 2.87ms | 3.11ms |
+| Complex Rule   | 2.57ms | 2.52ms | 2.96ms | 3.06ms |
+| Regex Rule     | 7.57ms | 7.47ms | 8.29ms | 8.70ms |
+| Multiple Rules | 2.05ms | 2.03ms | 2.24ms | 2.42ms |
+
+#### Scanning Performance by Data Size
+
+| Data Size | Rule Type      | Mean  | Throughput |
+| --------- | -------------- | ----- | ---------- |
+| 64 bytes  | Simple         | 3μs   | ~21 MB/s   |
+| 100KB     | Simple         | 6μs   | ~16.7 GB/s |
+| 100KB     | Complex        | 73μs  | ~1.4 GB/s  |
+| 100KB     | Regex          | 7μs   | ~14.3 GB/s |
+| 100KB     | Multiple Rules | 73μs  | ~1.4 GB/s  |
+| 10MB      | Simple         | 204μs | ~49 GB/s   |
+
+#### Advanced Features Performance
+
+| Feature           | Mean | Notes                      |
+| ----------------- | ---- | -------------------------- |
+| Variable Scanning | 1μs  | Pre-compiled variables     |
+| Runtime Variables | 2μs  | Variables set at scan time |
+| Async Scanning    | 11μs | Non-blocking operations    |
+
+## API Reference
 
 ### Functions
 
@@ -395,10 +494,10 @@ if (warnings.length > 0) {
 - `compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptions)` - Compiles yara rules from a string to WASM file.
 - `compileFileToWasm(rulesPath: string, outputPath: string, options?: CompilerOptions)` - Compiles yara rules from a file to WASM file.
 - `validate(ruleSource: string, options?: CompilerOptions)` - Validates yara rules without executing them.
-- `create(options?: CompilerOptions)` - Creates an empty rules scanner to add rules incrementally.
+- `create()` - Creates an empty rules scanner to add rules incrementally.
 - `fromFile(rulePath: string, options?: CompilerOptions)` - Compiles yara rules from a file.
 
-### yarax Methods
+### YaraX Methods
 
 - `getWarnings()` - Get compiler warnings.
 - `scan(data: Buffer, variables?: Record<string, string | number>)` - Scan a buffer.
@@ -409,10 +508,22 @@ if (warnings.length > 0) {
 - `emitWasmFileAsync(filePath: string)` - Emit compiled rules to WASM file asynchronously.
 - `addRuleSource(rules: string)` - Add rules from a string to an existing scanner.
 - `addRuleFile(filePath: string)` - Add rules from a file to an existing scanner.
-
-### Rule Validation
-
-- `validate(rules: string, options?: CompilerOptions)` - Validate yara rules without executing them.
+- `defineVariable(name: string, value: string)` - Define a variable for the YARA compiler.
+- `setMaxMatchesPerPattern(maxMatches: number)` - **(v1.7.0+)** Set the maximum number of matches per pattern.
+- `setUseMmap(useMmap: boolean)` - **(v1.6.0+)** Enable or disable memory-mapped files for scanning.
+
+### CompilerOptions
+
+- `defineVariables?: object` - Define global variables for the YARA rules.
+- `ignoreModules?: string[]` - List of module names to ignore during compilation.
+- `bannedModules?: BannedModule[]` - List of banned modules that cannot be used.
+- `features?: string[]` - List of features to enable for the YARA rules.
+- `relaxedReSyntax?: boolean` - Use relaxed regular expression syntax.
+- `conditionOptimization?: boolean` - Optimize conditions in the YARA rules.
+- `errorOnSlowPattern?: boolean` - Raise an error on slow patterns.
+- `errorOnSlowLoop?: boolean` - Raise an error on slow loops.
+- `includeDirectories?: string[]` - **(v1.5.0+)** Directories where the compiler should look for included files.
+- `enableIncludes?: boolean` - **(v1.5.0+)** Enable or disable include statements in YARA rules.
 
 ## Licenses
 

package/index.d.ts

@@ -1,77 +1,153 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 /**
- * YaraX struct represents the YARA rules and their associated data.
- * It contains the compiled rules, source code, warnings, and variables.
+ * The main YARA-X scanner struct.
  *
- * See [yara_x::Rules](https://docs.rs/yara-x/latest/yara_x/struct.Rules.html) for more details.
+ * This struct represents compiled YARA rules and provides methods for scanning
+ * data and files. It includes performance optimizations like scanner caching.
  */
 export declare class YaraX {
+  /** Returns the compiler warnings generated during the compilation process. */
   getWarnings(): Array<CompilerWarning>
+  /**
+   * Sets the maximum number of matches per pattern.
+   *
+   * # Arguments
+   *
+   * * `max_matches` - The maximum number of matches per pattern
+   */
+  setMaxMatchesPerPattern(maxMatches: number): void
+  /**
+   * Sets whether to use memory-mapped files for scanning.
+   *
+   * # Arguments
+   *
+   * * `use_mmap` - Whether to use memory-mapped files
+   */
+  setUseMmap(useMmap: boolean): void
   /**
    * Scans the provided data using the compiled YARA rules.
-   * This function takes the scanned data and an optional object of variables,
-   * and returns a vector of RuleMatch representing the matching rules found during the scan.
+   *
+   * # Arguments
+   *
+   * * `env` - The N-API environment
+   * * `data` - The data to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * A vector of matching rules
    */
   scan(data: Buffer, variables?: Record<string, string | number>): Array<RuleMatch>
   /**
    * Scans a file using the compiled YARA rules.
-   * This function takes the file path and an optional object of variables,
-   * and returns a vector of RuleMatch representing the matching rules found during the scan.
+   *
+   * # Arguments
+   *
+   * * `env` - The N-API environment
+   * * `file_path` - Path to the file to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * A vector of matching rules
    */
   scanFile(filePath: string, variables?: Record<string, string | number>): Array<RuleMatch>
   /**
    * Emits a WASM file from the compiled YARA rules.
-   * This function takes the output path and writes the compiled rules to a WASM file.
+   *
+   * # Arguments
+   *
+   * * `output_path` - Path where the WASM file should be written
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if emission fails
    */
   emitWasmFile(outputPath: string): void
   /**
    * Scans the provided data asynchronously using the compiled YARA rules.
-   * This function takes the scanned data and an optional object of variables,
-   * and returns an AsyncTask that will resolve to a vector of RuleMatch representing the matching
-   * rules found during the scan.
    *
-   * This allows for non-blocking scanning of data, which can be useful for large datasets or
-   * performance-critical applications.
+   * # Arguments
+   *
+   * * `data` - The data to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * An async task that resolves to a vector of matching rules
    */
-  scanAsync(data: Buffer, variables?: object | undefined | null): Promise<unknown>
+  scanAsync(data: Buffer, variables?: object | undefined | null): Promise<Array<RuleMatch>>
   /**
    * Scans a file asynchronously using the compiled YARA rules.
-   * This function takes the file path and an optional object of variables,
-   * and returns an AsyncTask that will resolve to a vector of RuleMatch representing the matching
-   * rules found during the scan.
    *
-   * This allows for non-blocking scanning of files, which can be useful for large files or
-   * performance-critical applications.
+   * # Arguments
+   *
+   * * `file_path` - Path to the file to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * An async task that resolves to a vector of matching rules
    */
-  scanFileAsync(filePath: string, variables?: object | undefined | null): Promise<unknown>
+  scanFileAsync(filePath: string, variables?: object | undefined | null): Promise<Array<RuleMatch>>
   /**
    * Emits a WASM file asynchronously from the compiled YARA rules.
-   * This function takes the output path
-   * and returns an AsyncTask that will resolve when the WASM file is successfully emitted.
+   *
+   * # Arguments
+   *
+   * * `output_path` - Path where the WASM file should be written
+   *
+   * # Returns
+   *
+   * An async task that completes when the WASM file is written
    */
   emitWasmFileAsync(outputPath: string): Promise<unknown>
   /**
    * Adds a rule source to the YARA compiler.
-   * This function takes a rule source string,
-   * compiles it, and updates the YaraX instance with the new rules.
+   *
+   * # Arguments
+   *
+   * * `rule_source` - The YARA rule source code to add
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if compilation fails
    */
   addRuleSource(ruleSource: string): void
   /**
    * Adds a rule file to the YARA compiler.
-   * This function takes a file path,
-   * reads the file content, and adds it to the YaraX instance.
+   *
+   * # Arguments
+   *
+   * * `file_path` - Path to the file containing YARA rules
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if reading or compilation fails
    */
   addRuleFile(filePath: string): void
   /**
    * Defines a variable for the YARA compiler.
-   * This function takes a variable name and value,
-   * and adds it to the YaraX instance.
+   *
+   * # Arguments
+   *
+   * * `name` - The variable name
+   * * `value` - The variable value
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if compilation fails
    */
   defineVariable(name: string, value: string): void
 }
 
-/** BannedModule struct represents a module that is banned from being used in YARA rules. */
+/**
+ * Represents a module that is banned from being used in YARA rules.
+ *
+ * When a banned module is encountered, compilation will fail with the
+ * specified error message.
+ */
 export interface BannedModule {
   /** The name of the banned module. */
   name: string
@@ -84,37 +160,37 @@ export interface BannedModule {
 /**
  * Compiles a YARA rule source string and returns a YaraX instance with the compiled rules.
  *
- * Exported as `compile` in the NAPI interface.
+ * # Arguments
+ *
+ * * `rule_source` - The YARA rule source code
+ * * `options` - Optional compiler options
  *
- * Example
+ * # Returns
  *
- * ```javascript
- * const { compile } = require('your_yara_module');
- * const yarax = compile('rule example { strings: $a = "example" condition: $a }');
- * ```
+ * A YaraX instance with compiled rules
  */
-export declare function compile(ruleSource: string, options?: CompilerOptions | undefined | null): YaraX
+export declare function compile(ruleSource: string, options?: CompilerOptionsType | undefined | null): YaraXImpl
 
 /**
  * Compiles a YARA rule file to a WASM file.
  *
- * Exported as `compileFileToWasm` in the NAPI interface.
+ * # Arguments
  *
- * Example
+ * * `rule_path` - Path to the file containing YARA rules
+ * * `output_path` - Path where the WASM file should be written
+ * * `options` - Optional compiler options
  *
- * ```javascript
- * const { compileFileToWasm } = require('your_yara_module');
- * compileFileToWasm('path/to/rule_file.yar', 'output.wasm');
- * ```
+ * # Returns
+ *
+ * Ok(()) on success, or an error if reading, compilation, or emission fails
  */
-export declare function compileFileToWasm(rulePath: string, outputPath: string, options?: CompilerOptions | undefined | null): void
+export declare function compileFileToWasm(rulePath: string, outputPath: string, options?: CompilerOptionsType | undefined | null): void
 
 /**
- * CompilerError struct represents an error generated by the YARA compiler.
+ * An error generated by the YARA compiler.
  *
- * See
- * [yara_x::CompileError](https://docs.rs/yara-x/latest/yara_x/errors/enum.CompileError.html)
- * for more details.
+ * Errors prevent successful compilation and must be resolved before
+ * the rules can be used.
  */
 export interface CompilerError {
   /** The code of the error. */
@@ -130,8 +206,10 @@ export interface CompilerError {
 }
 
 /**
- * CompileResult struct represents the result of compiling YARA rules.
- * It contains any warnings or errors generated during the compilation process.
+ * The result of compiling YARA rules.
+ *
+ * Contains any warnings or errors generated during the compilation process.
+ * If errors are present, the compilation failed.
  */
 export interface CompileResult {
   /** Any warnings generated during the compilation process. */
@@ -141,10 +219,10 @@ export interface CompileResult {
 }
 
 /**
- * CompilerOptions struct represents the options for the YARA compiler.
+ * Options for configuring the YARA compiler.
  *
- * See [yara_x::Compiler](https://docs.rs/yara-x/latest/yara_x/struct.Compiler.html) for more
- * details.
+ * These options control various aspects of rule compilation including
+ * module handling, optimization, and feature flags.
  */
 export interface CompilerOptions {
   /** Defines global variables for the YARA rules. */
@@ -163,13 +241,17 @@ export interface CompilerOptions {
   errorOnSlowPattern?: boolean
   /** Whether to raise an error on slow loops. */
   errorOnSlowLoop?: boolean
+  /** A list of directories where the compiler should look for included files. */
+  includeDirectories?: Array<string>
+  /** Whether to enable include statements in YARA rules. */
+  enableIncludes?: boolean
 }
 
 /**
- * CompilerWarning struct represents a warning generated by the YARA compiler.
+ * A warning generated by the YARA compiler.
  *
- * See [yara_x::CompilerWarning](https://docs.rs/yara-x/latest/yara_x/warnings/enum.Warning.html)
- * for more details.
+ * Warnings indicate potential issues that don't prevent compilation
+ * but may indicate problems with the rules.
  */
 export interface CompilerWarning {
   /** The code of the warning. */
@@ -187,52 +269,46 @@ export interface CompilerWarning {
 /**
  * Compiles a YARA rule source string to a WASM file.
  *
- * Exported as `compileToWasm` in the NAPI interface.
+ * # Arguments
  *
- * Example
+ * * `rule_source` - The YARA rule source code
+ * * `output_path` - Path where the WASM file should be written
+ * * `options` - Optional compiler options
  *
- * ```javascript
- * const { compileToWasm } = require('your_yara_module');
- * compileToWasm('rule example { strings: $a = "example" condition: $a }', 'output.wasm');
- * ```
+ * # Returns
+ *
+ * Ok(()) on success, or an error if compilation or emission fails
  */
-export declare function compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptions | undefined | null): void
+export declare function compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptionsType | undefined | null): void
 
 /**
  * Creates a new YaraX instance with empty rules and no source code.
  *
- * Exported as `create` in the NAPI interface.
- *
- * Example
- *
- * ```javascript
- * const { create } = require('your_yara_module');
- * const yarax = create();
- *
- * // Now you can add rules or compile them later
+ * # Returns
  *
- * yarax.addRuleSource('rule example { strings: $a = "example" condition: $a }');
- * yarax.addRuleFile('path/to/rule_file.yar');
- * yarax.defineVariable('myVar', 'myValue');
- * ```
+ * A new YaraX instance with empty rules
  */
-export declare function create(): YaraX
+export declare function create(): YaraXImpl
 
 /**
  * Creates a new YaraX instance from a file containing YARA rules.
  *
- * Exported as `fromFile` in the NAPI interface.
+ * # Arguments
  *
- * Example
+ * * `rule_path` - Path to the file containing YARA rules
+ * * `options` - Optional compiler options
  *
- * ```javascript
- * const { fromFile } = require('your_yara_module');
- * const yarax = fromFile('path/to/rule_file.yar');
- * ```
+ * # Returns
+ *
+ * A YaraX instance with compiled rules from the file
  */
-export declare function fromFile(rulePath: string, options?: CompilerOptions | undefined | null): YaraX
+export declare function fromFile(rulePath: string, options?: CompilerOptionsType | undefined | null): YaraXImpl
 
-/** MatchData struct represents a match found by a YARA rule. */
+/**
+ * Represents a match found by a YARA rule pattern.
+ *
+ * Contains information about where the match occurred and what data was matched.
+ */
 export interface MatchData {
   /** The offset of the match in the scanned data. */
   offset: number
@@ -245,9 +321,9 @@ export interface MatchData {
 }
 
 /**
- * RuleMatch struct represents a matching rule found during scanning.
+ * Represents a matching rule found during scanning.
  *
- * See [yara_::Match](https://docs.rs/yara-x/latest/yara_x/struct.Match.html) for more details.
+ * Contains the rule's metadata, tags, and all pattern matches.
  */
 export interface RuleMatch {
   /** The identifier of the rule that matched. */
@@ -262,17 +338,32 @@ export interface RuleMatch {
   matches: Array<MatchData>
 }
 
+/**
+ * Options for configuring scanning operations.
+ *
+ * These options control resource usage and performance characteristics
+ * during rule scanning.
+ */
+export interface ScanOptions {
+  /** Maximum number of matches per pattern. When a pattern reaches this limit, it won't produce more matches. */
+  maxMatchesPerPattern?: number
+  /** Whether to use memory-mapped files for scanning. Disabling this is safer but slower. */
+  useMmap?: boolean
+}
+
 /**
  * Compiles a YARA rule source string and returns any warnings or errors generated during the
  * compilation process.
  *
- * Exported as `validate` in the NAPI interface.
+ * This function validates YARA rules without creating a scanner instance.
+ *
+ * # Arguments
+ *
+ * * `rule_source` - The YARA rule source code
+ * * `options` - Optional compiler options
  *
- * Example
+ * # Returns
  *
- * ```javascript
- * const { validate } = require('your_yara_module');
- * const result = validate('rule example { strings: $a = "example" condition: $a }');
- * ```
+ * A CompileResult containing any warnings and errors
  */
-export declare function validate(ruleSource: string, options?: CompilerOptions | undefined | null): CompileResult
+export declare function validate(ruleSource: string, options?: CompilerOptionsType | undefined | null): CompileResult

package/index.js

@@ -66,7 +66,7 @@ const isMuslFromChildProcess = () => {
 function requireNative() {
   if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
     try {
-      nativeBinding = require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
+      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
     } catch (err) {
       loadErrors.push(err)
     }
@@ -78,7 +78,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-android-arm64')
+        const binding = require('@litko/yara-x-android-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-android-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -89,7 +94,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-android-arm-eabi')
+        const binding = require('@litko/yara-x-android-arm-eabi')
+        const bindingPackageVersion = require('@litko/yara-x-android-arm-eabi/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -98,16 +108,39 @@ function requireNative() {
     }
   } else if (process.platform === 'win32') {
     if (process.arch === 'x64') {
+      if (process.report?.getReport?.()?.header?.osName?.startsWith?.('MINGW')) {
+        try {
+        return require('./yara-x.win32-x64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
       try {
+        const binding = require('@litko/yara-x-win32-x64-gnu')
+        const bindingPackageVersion = require('@litko/yara-x-win32-x64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      } else {
+        try {
         return require('./yara-x.win32-x64-msvc.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-win32-x64-msvc')
+        const binding = require('@litko/yara-x-win32-x64-msvc')
+        const bindingPackageVersion = require('@litko/yara-x-win32-x64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
+      }
     } else if (process.arch === 'ia32') {
       try {
         return require('./yara-x.win32-ia32-msvc.node')
@@ -115,7 +148,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-win32-ia32-msvc')
+        const binding = require('@litko/yara-x-win32-ia32-msvc')
+        const bindingPackageVersion = require('@litko/yara-x-win32-ia32-msvc/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -126,7 +164,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-win32-arm64-msvc')
+        const binding = require('@litko/yara-x-win32-arm64-msvc')
+        const bindingPackageVersion = require('@litko/yara-x-win32-arm64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -140,7 +183,12 @@ function requireNative() {
       loadErrors.push(e)
     }
     try {
-      return require('@litko/yara-x-darwin-universal')
+      const binding = require('@litko/yara-x-darwin-universal')
+      const bindingPackageVersion = require('@litko/yara-x-darwin-universal/package.json').version
+      if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      }
+      return binding
     } catch (e) {
       loadErrors.push(e)
     }
@@ -151,7 +199,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-darwin-x64')
+        const binding = require('@litko/yara-x-darwin-x64')
+        const bindingPackageVersion = require('@litko/yara-x-darwin-x64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -162,7 +215,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-darwin-arm64')
+        const binding = require('@litko/yara-x-darwin-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-darwin-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -177,7 +235,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-freebsd-x64')
+        const binding = require('@litko/yara-x-freebsd-x64')
+        const bindingPackageVersion = require('@litko/yara-x-freebsd-x64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -188,7 +251,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-freebsd-arm64')
+        const binding = require('@litko/yara-x-freebsd-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-freebsd-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -204,7 +272,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-x64-musl')
+          const binding = require('@litko/yara-x-linux-x64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-x64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -215,7 +288,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-x64-gnu')
+          const binding = require('@litko/yara-x-linux-x64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -228,7 +306,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm64-musl')
+          const binding = require('@litko/yara-x-linux-arm64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -239,7 +322,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm64-gnu')
+          const binding = require('@litko/yara-x-linux-arm64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -252,7 +340,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm-musleabihf')
+          const binding = require('@litko/yara-x-linux-arm-musleabihf')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm-musleabihf/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -263,7 +356,46 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm-gnueabihf')
+          const binding = require('@litko/yara-x-linux-arm-gnueabihf')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm-gnueabihf/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'loong64') {
+      if (isMusl()) {
+        try {
+          return require('./yara-x.linux-loong64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@litko/yara-x-linux-loong64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-loong64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./yara-x.linux-loong64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@litko/yara-x-linux-loong64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-loong64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -276,7 +408,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-riscv64-musl')
+          const binding = require('@litko/yara-x-linux-riscv64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-riscv64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -287,7 +424,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-riscv64-gnu')
+          const binding = require('@litko/yara-x-linux-riscv64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-riscv64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -299,7 +441,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-ppc64-gnu')
+        const binding = require('@litko/yara-x-linux-ppc64-gnu')
+        const bindingPackageVersion = require('@litko/yara-x-linux-ppc64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -310,7 +457,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-s390x-gnu')
+        const binding = require('@litko/yara-x-linux-s390x-gnu')
+        const bindingPackageVersion = require('@litko/yara-x-linux-s390x-gnu/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -320,34 +472,49 @@ function requireNative() {
   } else if (process.platform === 'openharmony') {
     if (process.arch === 'arm64') {
       try {
-        return require('./yara-x.linux-arm64-ohos.node')
+        return require('./yara-x.openharmony-arm64.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-arm64-ohos')
+        const binding = require('@litko/yara-x-openharmony-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-openharmony-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
     } else if (process.arch === 'x64') {
       try {
-        return require('./yara-x.linux-x64-ohos.node')
+        return require('./yara-x.openharmony-x64.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-x64-ohos')
+        const binding = require('@litko/yara-x-openharmony-x64')
+        const bindingPackageVersion = require('@litko/yara-x-openharmony-x64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
     } else if (process.arch === 'arm') {
       try {
-        return require('./yara-x.linux-arm-ohos.node')
+        return require('./yara-x.openharmony-arm.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-arm-ohos')
+        const binding = require('@litko/yara-x-openharmony-arm')
+        const bindingPackageVersion = require('@litko/yara-x-openharmony-arm/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -362,22 +529,32 @@ function requireNative() {
 nativeBinding = requireNative()
 
 if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
+  let wasiBinding = null
+  let wasiBindingError = null
   try {
-    nativeBinding = require('./yara-x.wasi.cjs')
+    wasiBinding = require('./yara-x.wasi.cjs')
+    nativeBinding = wasiBinding
   } catch (err) {
     if (process.env.NAPI_RS_FORCE_WASI) {
-      loadErrors.push(err)
+      wasiBindingError = err
     }
   }
   if (!nativeBinding) {
     try {
-      nativeBinding = require('@litko/yara-x-wasm32-wasi')
+      wasiBinding = require('@litko/yara-x-wasm32-wasi')
+      nativeBinding = wasiBinding
     } catch (err) {
       if (process.env.NAPI_RS_FORCE_WASI) {
+        wasiBindingError.cause = err
         loadErrors.push(err)
       }
     }
   }
+  if (process.env.NAPI_RS_FORCE_WASI === 'error' && !wasiBinding) {
+    const error = new Error('WASI binding not found and NAPI_RS_FORCE_WASI is set to error')
+    error.cause = wasiBindingError
+    throw error
+  }
 }
 
 if (!nativeBinding) {
@@ -386,7 +563,12 @@ if (!nativeBinding) {
       `Cannot find native binding. ` +
         `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
         'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
-      { cause: loadErrors }
+      {
+        cause: loadErrors.reduce((err, cur) => {
+          cur.cause = err
+          return cur
+        }),
+      },
     )
   }
   throw new Error(`Failed to load native binding`)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@litko/yara-x",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "index.js",
   "types": "index.d.ts",
-  "packageManager": "pnpm@10.13.1",
+  "packageManager": "pnpm@10.18.0",
   "napi": {
     "binaryName": "yara-x",
     "targets": [
@@ -14,9 +14,9 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@napi-rs/cli": "^3.0.0",
-    "@napi-rs/wasm-runtime": "^1.0.0",
-    "@types/node": "^22.13.10"
+    "@napi-rs/cli": "^3.3.0",
+    "@napi-rs/wasm-runtime": "^1.0.6",
+    "@types/node": "^24.6.2"
   },
   "engines": {
     "node": ">= 20"
@@ -41,7 +41,10 @@
     "universal": "napi universal",
     "version": "napi version",
     "test": "node --test __test__/index.spec.mjs",
-    "benchmark": "node __test__/benchmark.mjs"
+    "benchmark": "node __test__/benchmark.mjs",
+    "profile": "node --expose-gc __test__/run-profiling.mjs",
+    "profile:baseline": "node --expose-gc __test__/run-profiling.mjs --baseline",
+    "profile:compare": "node --expose-gc __test__/run-profiling.mjs --compare __test__/baseline-performance.json"
   },
   "files": [
     "index.js",
@@ -56,8 +59,8 @@
     "rust"
   ],
   "optionalDependencies": {
-    "@litko/yara-x-darwin-x64": "0.2.0",
-    "@litko/yara-x-darwin-arm64": "0.2.0",
-    "@litko/yara-x-linux-x64-gnu": "0.2.0"
+    "@litko/yara-x-darwin-x64": "0.3.0",
+    "@litko/yara-x-darwin-arm64": "0.3.0",
+    "@litko/yara-x-linux-x64-gnu": "0.3.0"
   }
 }