@litko/yara-x 0.2.0 → 0.2.1

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)
@@ -363,31 +361,42 @@ if (warnings.length > 0) {
 
 ## Performance Benchmarks
 
-**Test Setup:**
+`node-yara-x` delivers exceptional performance through intelligent scanner caching and optimized Rust implementation.
+
+### Benchmark Results
+
+Test Environment: MacBook Pro M3 Max, 36GB RAM, Release build with LTO
+Methodology: Statistical analysis across multiple iterations with percentile reporting
+
+#### Scanner Creation Performance
 
-- **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.
+| Rule Type      | Mean   | p50    | p95    | p99    |
+| -------------- | ------ | ------ | ------ | ------ |
+| Simple Rule    | 2.44ms | 2.42ms | 2.67ms | 3.00ms |
+| Complex Rule   | 2.79ms | 2.78ms | 3.00ms | 3.26ms |
+| Regex Rule     | 8.63ms | 8.63ms | 8.91ms | 9.34ms |
+| Multiple Rules | 2.42ms | 2.39ms | 2.69ms | 3.07ms |
 
-**Key Metrics (Averages):**
+#### Scanning Performance by Data Size
 
-| 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 |
+| Data Size | Rule Type      | Mean  | Throughput |
+| --------- | -------------- | ----- | ---------- |
+| 64 bytes  | Simple         | 3μs   | ~21 MB/s   |
+| 100KB     | Simple         | 6μs   | ~16.7 GB/s |
+| 100KB     | Complex        | 71μs  | ~1.4 GB/s  |
+| 100KB     | Regex          | 7μs   | ~14.3 GB/s |
+| 100KB     | Multiple Rules | 71μs  | ~1.4 GB/s  |
+| 10MB      | Simple         | 196μs | ~51 GB/s   |
 
-# API Reference
+#### Advanced Features Performance
+
+| Feature           | Mean | Notes                      |
+| ----------------- | ---- | -------------------------- |
+| Variable Scanning | 1μs  | Pre-compiled variables     |
+| Runtime Variables | 2μs  | Variables set at scan time |
+| Async Scanning    | 12μs | Non-blocking operations    |
+
+## API Reference
 
 ### Functions
 
@@ -395,7 +404,7 @@ 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
@@ -409,10 +418,7 @@ 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.
 
 ## Licenses
 

package/index.d.ts

@@ -1,73 +1,25 @@
 /* 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.
- *
- * See [yara_x::Rules](https://docs.rs/yara-x/latest/yara_x/struct.Rules.html) for more details.
- */
+/** YaraX struct represents the YARA rules and their associated data. */
 export declare class YaraX {
   getWarnings(): Array<CompilerWarning>
-  /**
-   * 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.
-   */
+  /** Scans the provided data using the compiled YARA 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.
-   */
+  /** Scans a file using the compiled YARA 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.
-   */
+  /** Emits a WASM file from the compiled YARA rules. */
   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.
-   */
+  /** Scans the provided data asynchronously using the compiled YARA rules. */
   scanAsync(data: Buffer, variables?: object | undefined | null): Promise<unknown>
-  /**
-   * 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.
-   */
+  /** Scans a file asynchronously using the compiled YARA rules. */
   scanFileAsync(filePath: string, variables?: object | undefined | null): Promise<unknown>
-  /**
-   * 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.
-   */
+  /** Emits a WASM file asynchronously from the compiled YARA rules. */
   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.
-   */
+  /** Adds a rule source to the YARA compiler. */
   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.
-   */
+  /** Adds a rule file to the YARA compiler. */
   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.
-   */
+  /** Defines a variable for the YARA compiler. */
   defineVariable(name: string, value: string): void
 }
 
@@ -81,41 +33,13 @@ export interface BannedModule {
   errorMessage: string
 }
 
-/**
- * Compiles a YARA rule source string and returns a YaraX instance with the compiled rules.
- *
- * Exported as `compile` in the NAPI interface.
- *
- * Example
- *
- * ```javascript
- * const { compile } = require('your_yara_module');
- * const yarax = compile('rule example { strings: $a = "example" condition: $a }');
- * ```
- */
+/** Compiles a YARA rule source string and returns a YaraX instance with the compiled rules. */
 export declare function compile(ruleSource: string, options?: CompilerOptions | undefined | null): YaraX
 
-/**
- * Compiles a YARA rule file to a WASM file.
- *
- * Exported as `compileFileToWasm` in the NAPI interface.
- *
- * Example
- *
- * ```javascript
- * const { compileFileToWasm } = require('your_yara_module');
- * compileFileToWasm('path/to/rule_file.yar', 'output.wasm');
- * ```
- */
+/** Compiles a YARA rule file to a WASM file. */
 export declare function compileFileToWasm(rulePath: string, outputPath: string, options?: CompilerOptions | undefined | null): void
 
-/**
- * CompilerError struct represents 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.
- */
+/** CompilerError struct represents an error generated by the YARA compiler. */
 export interface CompilerError {
   /** The code of the error. */
   code: string
@@ -129,10 +53,7 @@ export interface CompilerError {
   column?: number
 }
 
-/**
- * CompileResult struct represents the result of compiling YARA rules.
- * It contains any warnings or errors generated during the compilation process.
- */
+/** CompileResult struct represents the result of compiling YARA rules. */
 export interface CompileResult {
   /** Any warnings generated during the compilation process. */
   warnings: Array<CompilerWarning>
@@ -140,12 +61,7 @@ export interface CompileResult {
   errors: Array<CompilerError>
 }
 
-/**
- * CompilerOptions struct represents the options for the YARA compiler.
- *
- * See [yara_x::Compiler](https://docs.rs/yara-x/latest/yara_x/struct.Compiler.html) for more
- * details.
- */
+/** CompilerOptions struct represents the options for the YARA compiler. */
 export interface CompilerOptions {
   /** Defines global variables for the YARA rules. */
   defineVariables?: object
@@ -165,12 +81,7 @@ export interface CompilerOptions {
   errorOnSlowLoop?: boolean
 }
 
-/**
- * CompilerWarning struct represents 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.
- */
+/** CompilerWarning struct represents a warning generated by the YARA compiler. */
 export interface CompilerWarning {
   /** The code of the warning. */
   code: string
@@ -184,52 +95,13 @@ export interface CompilerWarning {
   column?: number
 }
 
-/**
- * Compiles a YARA rule source string to a WASM file.
- *
- * Exported as `compileToWasm` in the NAPI interface.
- *
- * Example
- *
- * ```javascript
- * const { compileToWasm } = require('your_yara_module');
- * compileToWasm('rule example { strings: $a = "example" condition: $a }', 'output.wasm');
- * ```
- */
+/** Compiles a YARA rule source string to a WASM file. */
 export declare function compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptions | 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
- *
- * yarax.addRuleSource('rule example { strings: $a = "example" condition: $a }');
- * yarax.addRuleFile('path/to/rule_file.yar');
- * yarax.defineVariable('myVar', 'myValue');
- * ```
- */
+/** Creates a new YaraX instance with empty rules and no source code. */
 export declare function create(): YaraX
 
-/**
- * Creates a new YaraX instance from a file containing YARA rules.
- *
- * Exported as `fromFile` in the NAPI interface.
- *
- * Example
- *
- * ```javascript
- * const { fromFile } = require('your_yara_module');
- * const yarax = fromFile('path/to/rule_file.yar');
- * ```
- */
+/** Creates a new YaraX instance from a file containing YARA rules. */
 export declare function fromFile(rulePath: string, options?: CompilerOptions | undefined | null): YaraX
 
 /** MatchData struct represents a match found by a YARA rule. */
@@ -244,11 +116,7 @@ export interface MatchData {
   identifier: string
 }
 
-/**
- * RuleMatch struct represents a matching rule found during scanning.
- *
- * See [yara_::Match](https://docs.rs/yara-x/latest/yara_x/struct.Match.html) for more details.
- */
+/** RuleMatch struct represents a matching rule found during scanning. */
 export interface RuleMatch {
   /** The identifier of the rule that matched. */
   ruleIdentifier: string
@@ -265,14 +133,5 @@ export interface RuleMatch {
 /**
  * Compiles a YARA rule source string and returns any warnings or errors generated during the
  * compilation process.
- *
- * Exported as `validate` in the NAPI interface.
- *
- * Example
- *
- * ```javascript
- * const { validate } = require('your_yara_module');
- * const result = validate('rule example { strings: $a = "example" condition: $a }');
- * ```
  */
 export declare function validate(ruleSource: string, options?: CompilerOptions | undefined | null): CompileResult

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litko/yara-x",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "main": "index.js",
   "types": "index.d.ts",
   "packageManager": "pnpm@10.13.1",
@@ -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.2.1",
+    "@litko/yara-x-darwin-arm64": "0.2.1",
+    "@litko/yara-x-linux-x64-gnu": "0.2.1"
   }
 }