buf-im — Buffer Improved

Ultra-fast 1-to-1 byte and value comparison with token-efficient return states (1, 0, -1) optimized for AI, heuristic algorithms, and data pipelines.

Why buf-im?

Standard JavaScript comparison returns true/false. When every token in a response matters — especially for AI agents, heuristic scoring, or state machines — a three-state signal packs more information into a single token:

| State | Meaning | |-------|---------| | 1 | Match (identical data and same constructor type) | | 0 | No match (data differs or invalid input) | | -1 | Partial match (data is identical, but constructors differ — or data differs with different types for ne/nev) |

Install

npm install buf-im

Usage

import { bufim } from 'buf-im';

const b = new bufim();

// TypedArray comparison
const a1 = new Uint8Array([1, 2, 3]);
const a2 = new Uint8Array([1, 2, 3]);
b.eq(a1, a2); // → 1 (identical bytes, same type)

// DataView comparison
const dv1 = new DataView(new ArrayBuffer(4));
const dv2 = new DataView(new ArrayBuffer(4));
b.eq(dv1, dv2); // → 1

// Different types, same bytes
const u8 = new Uint8Array([10, 20]);
const i8 = new Int8Array([10, 20]);
b.eq(u8, i8);  // → -1 (bytes match, constructors differ)
b.eqv(u8, i8); // → -1 (value-equivalent, different type)

// Array-like
b.eq([1, 2, 3], [1, 2, 3]); // → -1 (no ArrayBuffer, values match)
b.eq([1, 2], [1, 3]);       // → 0

API

All methods accept two arguments (a, b) and return 1, 0, or -1.

Strict byte-level comparison (ArrayBuffer views only)

| Method | 1 | 0 | -1 | |--------|-----|-----|------| | eq(a, b) | Bytes + constructors match | Bytes differ | Bytes match, but constructors differ | | ne(a, b) | Bytes differ, same constructor | Bytes + constructors match | Bytes differ, different constructors | | ge(a, b) | Bytes match (up to b.length) AND a.length >= b.length, same constructor | Condition fails | Data matches condition, but constructors differ | | le(a, b) | Bytes match (up to a.length) AND a.length <= b.length, same constructor | Condition fails | Data matches condition, but constructors differ |

Value-level comparison (works across all iterables, including DataView)

| Method | 1 | 0 | -1 | |--------|-----|-----|------| | eqv(a, b) | Values + constructors match | Values differ | Values match, but constructors differ | | nev(a, b) | Values differ, same constructor | Values + constructors match | Values differ, different constructors | | gev(a, b) | Values match (up to b.length) AND a.length >= b.length, same constructor | Condition fails | Data matches condition, but constructors differ | | lev(a, b) | Values match (up to a.length) AND a.length <= b.length, same constructor | Condition fails | Data matches condition, but constructors differ |

Design notes

• Raw byte mode (eq, ne, ge, le) — uses Uint8Array overlay over the underlying ArrayBuffer. Fast, no type coercion.
• Value mode (eqv, nev, gev, lev) — iterates via index access or DataView.getUint8(). Works across different buffer view types.
• Token-efficient — single-token return values (1, 0, -1) compress meaning for LLM/AI pipelines.
• Zero dependencies. Pure ES module. sideEffects: false.

License

Restricted MIT License (Non-AI/ML with Source Attribution & Georgian Governing Law). See LICENSE.md.