@kikuchan/hexdump 0.1.0-alpha.3 → 0.1.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kikuchan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,53 @@
-# hexdump-js
+# @kikuchan/hexdump
+
+Tiny, configurable hex dump utility for Node.js and browsers.
 
 ## Install
 
 ```bash
-$ npm install -D @kikuchan/hexdump
+npm install -D @kikuchan/hexdump
+```
+
+## Usage
+
+```ts
+import { hexdump } from '@kikuchan/hexdump';
+
+const bytes = Uint8Array.from([
+  0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
+  0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
+]);
+
+hexdump.log(bytes);
+```
+
+output:
+
 ```
+00000000:  00 01 02 03 04 05 06 07  08 09 0a 0b 0c 0d 0e 0f  |................|
+00000010:                                                    |                |
+```
+
+## API
+
+### Basic Functions
+
+- `hexdump.log|warn|error(data, options?)`: outputs to `console.log|warn|error` respectively.
+- `hexdump(data, options?)`: returns the full string instead of printing.
+- `hexdump.create(printer)`: returns a hexdump function that prints to `printer` (a function that takes a string).
+
+### `data`
+- Binary-like data: `Uint8Array`, `Uint8ClampedArray`, `ArrayBufferLike` or `DataView`;
 
+### `options?`
+- `addrOffset: number` — Starting address for the first byte. Default `0`.
+- `addrLength: number` — Hex digits shown for the address. Default `8 - prefix.length` (clamped to `>= 0`).
+- `prefix: string` — Printed before the address (e.g. `"0x"`). Default `""`.
+- `foldSize: number` — Bytes per row. Default `16`.
+- `printChars: boolean` — Show the ASCII gutter at right. Default `true`.
+- `footer: boolean` — Print a trailing line showing the next address. Default `true`.
+- `color: boolean | 'simple' | 'html' | ((s: string, ctx: Context) => ColorizerOperation | undefined)` —
+  - `true` or `'simple'`: add ANSI colors in terminals.
+  - `'html'`: wrap parts with semantic spans like `hexdump-address`, `hexdump-ascii`, etc., and escape content.
+- `printer?: (line: string) => void | null` — Provide a per-line sink directly in options. Set to `null` to disable printing even if a default printer is configured.
+- `formatter: (s: string, ctx: Context) => string | undefined` — Transform each fragment before it is appended. Return `undefined` to drop that fragment.

package/package.json

@@ -1,31 +1,16 @@
 {
   "name": "@kikuchan/hexdump",
-  "version": "0.1.0-alpha.3",
   "description": "hexdump",
-  "type": "module",
-  "main": "dist/hexdump.js",
-  "types": "dist/hexdump.d.ts",
-  "files": [
-    "dist/"
-  ],
-  "scripts": {
-    "build:types": "tsc",
-    "build": "pnpm run build:esm && pnpm run build:types",
-    "build:esm": "esbuild src/hexdump.ts --minify --outfile=dist/hexdump.js",
-    "lint": "biome lint ./src",
-    "lint:fix": "biome lint ./src --write",
-    "format": "biome format ./src",
-    "format:fix": "biome format ./src --write"
-  },
   "keywords": [
     "hexdump"
   ],
+  "version": "0.1.0-alpha.5",
+  "type": "module",
+  "main": "./src/index.ts",
   "author": "kikuchan <kikuchan98@gmail.com>",
-  "homepage": "https://github.com/kikuchan/hexdump-js#readme",
+  "homepage": "https://github.com/kikuchan/utils-on-npm#readme",
   "license": "MIT",
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "esbuild": "^0.24.2",
-    "typescript": "^5.7.3"
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1,278 @@
+export type BinaryLike = Uint8Array | Uint8ClampedArray | ArrayBufferLike | DataView;
+
+function hex(v: number, c: number) {
+  return Number(v).toString(16).padStart(c, '0');
+}
+
+type Context =
+  | {
+      type: 'hex-value' | 'hex-value-prefix' | 'hex-value-suffix' | 'character-value';
+      address: number;
+      value: number;
+    }
+  | {
+      type: 'address';
+      address: number;
+    }
+  | {
+      type:
+        | 'line-prefix'
+        | 'address-prefix'
+        | 'address-suffix'
+        | 'hex-dump-prefix'
+        | 'hex-group-prefix'
+        | 'hex-value-no-data'
+        | 'character-value-no-data'
+        | 'hex-gap'
+        | 'hex-group-gap'
+        | 'hex-group-suffix'
+        | 'hex-dump-suffix'
+        | 'character-prefix'
+        | 'character-suffix'
+        | 'line-suffix'
+        | 'flush';
+    };
+
+type ColorizerOperation = { enter: string; leave: string; escape?: (s: string) => string } | null;
+
+type Colorizer =
+  | boolean
+  | undefined
+  | 'simple'
+  | 'html'
+  | ((s: string, ctx: Context) => ColorizerOperation | undefined);
+type Formatter = undefined | ((s: string, ctx: Context) => string | undefined);
+
+type Options = {
+  addrOffset?: number;
+  addrLength?: number;
+  printer?: null | ((s: string) => void) /* for each line */;
+  formatter?: Formatter /* for each item */;
+  color?: Colorizer;
+  prefix?: string;
+  printChars?: boolean;
+  foldSize?: number;
+  footer?: boolean;
+};
+
+interface Hexdumper {
+  (buf: BinaryLike, options?: Options): string;
+  (buf: BinaryLike, len: number, options?: Options): string;
+}
+
+interface Hexdump extends Hexdumper {
+  log: Hexdumper;
+  warn: Hexdumper;
+  error: Hexdumper;
+  string: Hexdumper;
+
+  create: (printer: (s: string) => void) => Hexdumper;
+}
+
+const identity = <T>(s: T) => s;
+
+const htmlEscaper = (s: string) =>
+  s.replace(
+    /[&<>]/g,
+    (x) =>
+      ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+      })[x]!,
+  );
+
+const simpleColorizer = {
+  simple: {
+    address: { enter: '\x1b[38;5;238m', leave: '\x1b[m' },
+    separator: { enter: '\x1b[38;5;238m', leave: '\x1b[m' },
+    control: { enter: '\x1b[38;5;178m', leave: '\x1b[m' },
+    ascii: { enter: '\x1b[m', leave: '\x1b[m' },
+    exascii: { enter: '\x1b[38;5;209m', leave: '\x1b[m' },
+    null: { enter: '\x1b[38;5;244m', leave: '\x1b[m' },
+    normal: null,
+  },
+  html: {
+    address: { enter: '<span class="hexdump-address">', leave: '</span>', escape: htmlEscaper },
+    separator: { enter: '<span class="hexdump-separator">', leave: '</span>', escape: htmlEscaper },
+    control: { enter: '<span class="hexdump-control">', leave: '</span>', escape: htmlEscaper },
+    ascii: { enter: '<span class="hexdump-ascii">', leave: '</span>', escape: htmlEscaper },
+    exascii: { enter: '<span class="hexdump-exascii">', leave: '</span>', escape: htmlEscaper },
+    null: { enter: '<span class="hexdump-null">', leave: '</span>', escape: htmlEscaper },
+    normal: { enter: '', leave: '', escape: htmlEscaper },
+  },
+} as Record<
+  string,
+  {
+    address?: ColorizerOperation;
+    separator?: ColorizerOperation;
+    control?: ColorizerOperation;
+    ascii?: ColorizerOperation;
+    exascii?: ColorizerOperation;
+    null?: ColorizerOperation;
+    normal: ColorizerOperation;
+  }
+>;
+
+const create_colorizer = (colorizer: Colorizer) => {
+  let lastColor: ColorizerOperation | undefined = undefined;
+
+  if (!colorizer) return identity;
+  if (colorizer === true) colorizer = 'simple';
+
+  if (typeof colorizer === 'string') {
+    const defs = simpleColorizer[colorizer];
+    const separators = ['address-prefix', 'address-suffix', 'character-prefix', 'character-suffix'];
+
+    colorizer = function (s, ctx) {
+      if (!s.trim()) return undefined; // keep the last color context on empty
+
+      if (defs.address && ctx.type === 'address') return defs.address;
+      if (defs.separator && separators.includes(ctx.type)) return defs.separator;
+
+      if ((ctx.type === 'hex-value' || ctx.type === 'character-value') && typeof ctx.value === 'number') {
+        if (defs.null !== undefined && ctx.value === 0) return defs.null;
+        if (defs.control !== undefined && ctx.value < 0x20) return defs.control;
+        if (defs.ascii !== undefined && 0x20 <= ctx.value && ctx.value < 0x7f) return defs.ascii;
+        if (defs.exascii !== undefined && 0x80 <= ctx.value && ctx.value <= 0xff) return defs.exascii;
+      }
+
+      return defs.normal;
+    };
+  }
+
+  return (s: string, ctx: Context) => {
+    const color = ctx.type === 'flush' ? null : colorizer(s, ctx);
+
+    // If color changes, emit leave/enter tokens and escape content.
+    if (
+      color !== undefined &&
+      (lastColor?.enter !== color?.enter || lastColor?.leave !== color?.leave || lastColor?.escape !== color?.escape)
+    ) {
+      s = (lastColor?.leave || '') + (color?.enter || '') + (color?.escape || identity)(s);
+      lastColor = color;
+      return s;
+    }
+
+    // If color stays the same and provides an escaper, still escape content.
+    if (color && color.escape) {
+      return color.escape(s);
+    }
+
+    return s;
+  };
+};
+
+const create_formatter = (formatter: Formatter) => {
+  if (!formatter) formatter = identity;
+
+  return (s: string, ctx: Context) => {
+    return formatter(s, ctx) || '';
+  };
+};
+
+function create_hexdumper(printer: ((s: string) => void) | null): Hexdumper {
+  return (buf: BinaryLike, len?: number | Options, options?: Options) => {
+    const u8 = ArrayBuffer.isView(buf)
+      ? new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+      : new Uint8Array(buf);
+    if (typeof len !== 'number') {
+      options = len;
+      len = u8.length;
+    }
+    options = { ...(options ?? {}) };
+    if (len === undefined || len < 0) len = u8.length;
+
+    printer = options.printer === null ? null : (options.printer ?? printer);
+    const formatter = create_formatter(options.formatter);
+    const colorize = create_colorizer(options.color);
+
+    const foldSize = options.foldSize || 16;
+    const printChars = options.printChars !== false;
+
+    let address = options.addrOffset || 0;
+    const offset = address % foldSize;
+    const rows = (len ? Math.ceil(((offset % foldSize) + len) / foldSize) : 0) + (options.footer !== false ? 1 : 0);
+
+    const result: string[] = [];
+    let line = '';
+    const print = function (s: string, ctx: Context) {
+      line += colorize(formatter(s, ctx), ctx);
+    };
+
+    const prefix = options?.prefix || '';
+    const addrLength = Math.max(options?.addrLength ?? 8 - prefix.length, 0);
+
+    for (let i = 0; i < rows; i++) {
+      const addressBase = address;
+
+      print('', { type: 'line-prefix' });
+      print(prefix, { type: 'address-prefix' });
+      if (addrLength >= 1) print(hex(address, addrLength), { type: 'address', address });
+      print(': ', { type: 'address-suffix' });
+
+      print(' ', { type: 'hex-dump-prefix' });
+      print('', { type: 'hex-group-prefix' });
+      for (let j = 0; j < foldSize; j++) {
+        const idx = i * foldSize + j - offset;
+        if (j && j % 8 == 0) {
+          print('', { type: 'hex-group-suffix' });
+          print('  ', { type: 'hex-group-gap' });
+          print('', { type: 'hex-group-prefix' });
+        } else if (j) {
+          print(' ', { type: 'hex-gap' });
+        }
+
+        if (0 <= idx && idx < len) {
+          print('', { type: 'hex-value-prefix', address, value: u8[idx] });
+          print(hex(u8[idx], 2), { type: 'hex-value', address, value: u8[idx] });
+          print('', { type: 'hex-value-suffix', address, value: u8[idx] });
+          address++;
+        } else {
+          print('  ', { type: 'hex-value-no-data' });
+        }
+      }
+      print('', { type: 'hex-group-suffix' });
+      print(' ', { type: 'hex-dump-suffix' });
+
+      if (printChars) {
+        let address = addressBase;
+        print(' |', { type: 'character-prefix' });
+        for (let j = 0; j < foldSize; j++) {
+          const idx = i * foldSize + j - offset;
+
+          if (0 <= idx && idx < len) {
+            print(u8[idx] >= 0x20 && u8[idx] < 0x7f ? String.fromCharCode(u8[idx]) : '.', {
+              type: 'character-value',
+              address,
+              value: u8[idx],
+            });
+            address++;
+          } else {
+            print(' ', { type: 'character-value-no-data' });
+          }
+        }
+        print('|', { type: 'character-suffix' });
+      }
+      print('', { type: 'line-suffix' });
+      print('', { type: 'flush' });
+
+      printer?.(line);
+      result.push(line);
+      line = '';
+    }
+    return result.join('\n');
+  };
+}
+
+export const hexdump: Hexdump = Object.assign(create_hexdumper(null), {
+  create: create_hexdumper,
+
+  log: create_hexdumper((s) => console.log(s)),
+  warn: create_hexdumper((s) => console.warn(s)),
+  error: create_hexdumper((s) => console.error(s)),
+
+  string: create_hexdumper(null),
+});
+
+export default hexdump;

package/tests/hexdump.spec.ts

@@ -0,0 +1,388 @@
+import hexdumpDefault, { hexdump } from '@kikuchan/hexdump';
+import { describe, expect, it } from 'vitest';
+
+const u8 = (arr: number[]) => new Uint8Array(arr);
+
+describe('hexdump basics', () => {
+  it('prints a basic hexdump', () => {
+    const out = hexdump(u8([0x00, 0x20, 0x41, 0x7e, 0x7f, 0x80, 0xff]));
+    expect(out).toBe(
+      [
+        `00000000:  00 20 41 7e 7f 80 ff                              |. A~...         |`,
+        `00000007:                                                    |                |`,
+      ].join('\n'),
+    );
+  });
+
+  it('prints a single footer line for empty input', () => {
+    const out = hexdump(u8([]), {
+      foldSize: 8,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:                          '].join('\n'));
+  });
+
+  it('prints bytes and a footer line', () => {
+    const out = hexdump(u8([0x41, 0x42, 0x43]), {
+      foldSize: 4,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:  41 42 43    ', '0003:              '].join('\n'));
+  });
+});
+
+describe('hexdump printer integration', () => {
+  it('invokes custom printer for each line', () => {
+    const lines: string[] = [];
+    const dump = hexdump.create((s) => lines.push(s));
+    const out = dump(new Uint8Array([0x41, 0x42, 0x43]), {
+      foldSize: 2,
+      printChars: false,
+      addrLength: 4,
+    });
+
+    const outLines = out.split('\n');
+    expect(lines.join('\n')).toBe(out);
+    expect(lines.length).toBe(outLines.length);
+    expect(lines[0]).toContain('0000:');
+    expect(lines[0]).toContain('41 42');
+  });
+});
+
+describe('hexdump HTML colorizer escaping', () => {
+  it('escapes <, >, & in ascii region', () => {
+    const out = hexdump(new TextEncoder().encode('<&>'), {
+      foldSize: 8,
+      printChars: true,
+      addrLength: 2,
+      color: 'html',
+    });
+    expect(out).toContain('&lt;');
+    expect(out).toContain('&gt;');
+    expect(out).toContain('&amp;');
+  });
+});
+
+describe('hexdump hex value prefix/suffix', () => {
+  it('wraps each hex byte with custom markers', () => {
+    const bytes = new Uint8Array([0x41, 0x42]);
+    const out = hexdump(bytes, {
+      foldSize: 2,
+      printChars: false,
+      addrLength: 2,
+      color: (_s, ctx) => {
+        if (ctx.type === 'hex-value-prefix') return { enter: '{', leave: '' };
+        if (ctx.type === 'hex-value-suffix') return { enter: '', leave: '}' };
+        return undefined;
+      },
+    });
+    const firstLine = out.split('\n')[0] || '';
+    const opens = (firstLine.match(/\{/g) || []).length;
+    const closes = (firstLine.match(/\}/g) || []).length;
+    expect(opens).toBe(2);
+    expect(closes).toBe(2);
+    expect(firstLine).toContain('{41');
+    expect(firstLine).toContain('{42');
+  });
+});
+
+describe('hexdump flush handling', () => {
+  it('appends leave token at end of line on flush', () => {
+    const out = hexdump(new Uint8Array([0x00]), {
+      foldSize: 1,
+      printChars: false,
+      addrLength: 2,
+      color: (_s, ctx) => {
+        if (ctx.type === 'line-prefix') return { enter: '<', leave: '>' };
+        return undefined;
+      },
+    });
+    const first = out.split('\n')[0] || '';
+    expect(first.endsWith('>')).toBe(true);
+  });
+});
+
+describe('hexdump options', () => {
+  it('respects addrOffset and computes footer address', () => {
+    const out = hexdump(u8([0xaa, 0xbb]), {
+      addrOffset: 1,
+      foldSize: 4,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0001:     aa bb    ', '0003:              '].join('\n'));
+  });
+
+  it('applies a custom formatter to hex values', () => {
+    const out = hexdump(u8([0x00, 0x20, 0x41]), {
+      foldSize: 4,
+      printChars: false,
+      addrLength: 4,
+      formatter: (s, ctx) => (ctx.type === 'hex-value' ? `[${s}]` : s),
+    });
+    expect(out).toBe(['0000:  [00] [20] [41]    ', '0003:              '].join('\n'));
+  });
+
+  it("adds ANSI codes when color is 'simple'", () => {
+    const out = hexdump(u8([0x00]), {
+      foldSize: 1,
+      printChars: false,
+      addrLength: 2,
+      color: 'simple',
+    });
+
+    expect(/\x1b\[[0-9;]*m/.test(out)).toBe(true);
+  });
+
+  it("applies 'control' color for <0x20 (simple)", () => {
+    const out = hexdump(u8([0x01]), {
+      foldSize: 1,
+      printChars: false,
+      addrLength: 2,
+      color: 'simple',
+    });
+    expect(/\x1b\[38;5;178m/.test(out)).toBe(true);
+  });
+
+  it("escapes ASCII with color:'html' and emits span", () => {
+    const out = hexdump(u8([0x3c, 0x20]), {
+      foldSize: 2,
+      printChars: true,
+      addrLength: 2,
+      color: 'html',
+    });
+    expect(out).toContain('hexdump-ascii');
+    expect(out).toContain('&lt;');
+  });
+
+  it("assigns exascii class for >=0x80 with color:'html'", () => {
+    const out = hexdump(u8([0x80]), {
+      foldSize: 1,
+      printChars: true,
+      addrLength: 2,
+      color: 'html',
+    });
+    expect(out).toContain('hexdump-exascii');
+  });
+
+  it("uses 'normal' branch for DEL (0x7f) with color:'html'", () => {
+    const out = hexdump(u8([0x7f]), {
+      foldSize: 1,
+      printChars: true,
+      addrLength: 2,
+      color: 'html',
+    });
+    expect(out).not.toContain('hexdump-ascii');
+    expect(out).not.toContain('hexdump-control');
+    expect(out).not.toContain('hexdump-exascii');
+  });
+
+  it('respects footer:false (no footer line)', () => {
+    const out = hexdump(u8([0x41, 0x42, 0x43]), {
+      foldSize: 8,
+      printChars: false,
+      addrLength: 4,
+      footer: false,
+    });
+    const lines = out.split(/\n/);
+    expect(lines.length).toBe(1);
+  });
+
+  it('derives addrLength from prefix when not set', () => {
+    const out = hexdump(u8([]), {
+      foldSize: 8,
+      printChars: false,
+      prefix: '0x',
+    });
+    expect(out).toBe(['0x000000:                          '].join('\n'));
+  });
+
+  it('clamps addrLength to 0 when prefix is long (address hidden)', () => {
+    const out = hexdump(u8([]), {
+      foldSize: 8,
+      printChars: false,
+      prefix: '012345678',
+    });
+    expect(out).toBe(['012345678:                          '].join('\n'));
+  });
+
+  it('color:true behaves like simple (ANSI on)', () => {
+    const out = hexdump(u8([0x41]), {
+      foldSize: 1,
+      printChars: false,
+      addrLength: 2,
+      color: true,
+    });
+    expect(/\x1b\[[0-9;]*m/.test(out)).toBe(true);
+  });
+
+  it('custom colorizer wraps line with markers and flush closes it', () => {
+    const out = hexdump(u8([0x41, 0x42]), {
+      foldSize: 2,
+      printChars: false,
+      addrLength: 2,
+      color: (s) => {
+        if (!s.trim()) return undefined;
+        return { enter: '[', leave: ']' };
+      },
+    });
+    expect(out).toBe(['[00:  41 42 ]', '[02:        ]'].join('\n'));
+  });
+});
+
+describe('printer callbacks', () => {
+  it('calls the printer once per rendered line', () => {
+    const lines: string[] = [];
+    const dump = hexdump.create((s) => lines.push(s));
+
+    const out = dump(u8([1, 2, 3, 4, 5]), {
+      foldSize: 4,
+      printChars: false,
+      addrLength: 4,
+    });
+
+    const split = out.split(/\n/);
+    expect(lines.length).toBe(split.length);
+    expect(lines[0]).toBe(split[0]);
+  });
+
+  it('disables printer when options.printer is null', () => {
+    const dump = hexdump.create((s) => {
+      throw new Error('should not be called');
+    });
+    const out = dump(u8([0x41]), { foldSize: 1, printChars: false, addrLength: 2, printer: null });
+    expect(out.includes('41')).toBe(true);
+  });
+});
+
+describe('characters view', () => {
+  it('shows ASCII and dots for non-printables', () => {
+    const out = hexdump(u8([0x00, 0x41, 0x7f, 0x80]), {
+      foldSize: 4,
+      printChars: true,
+      addrLength: 2,
+    });
+    expect(out).toBe(['00:  00 41 7f 80  |.A..|', '04:               |    |'].join('\n'));
+  });
+});
+
+describe('overloads and inputs', () => {
+  it('accepts len overload to limit bytes', () => {
+    const out = hexdump(u8([0, 1, 2, 3]), 2, {
+      foldSize: 8,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:  00 01                   ', '0002:                          '].join('\n'));
+  });
+
+  it('treats negative len as full length', () => {
+    const out = hexdump(u8([1, 2, 3]), -1, {
+      foldSize: 8,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:  01 02 03                ', '0003:                          '].join('\n'));
+  });
+
+  it('accepts DataView input', () => {
+    const arr = u8([0xde, 0xad, 0xbe, 0xef]);
+    const view = new DataView(arr.buffer);
+    const out = hexdump(view, {
+      foldSize: 8,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:  de ad be ef             ', '0004:                          '].join('\n'));
+  });
+
+  it('accepts ArrayBuffer input', () => {
+    const arr = u8([0xde, 0xad]);
+    const out = hexdump(arr.buffer, {
+      foldSize: 8,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:  de ad                   ', '0002:                          '].join('\n'));
+  });
+});
+
+describe('grouping and gaps', () => {
+  it('inserts a double-space between groups of 8', () => {
+    const bytes = Array.from({ length: 10 }, (_, i) => i);
+    const out = hexdump(u8(bytes), {
+      foldSize: 10,
+      printChars: false,
+      addrLength: 4,
+    });
+    expect(out).toBe(['0000:  00 01 02 03 04 05 06 07  08 09 ', '000a:                                 '].join('\n'));
+  });
+});
+
+describe('predefined printers', () => {
+  it('warn printer emits to console and returns string', () => {
+    const orig = console.warn;
+    const captured: string[] = [];
+    console.warn = (s: string) => void captured.push(s);
+    try {
+      const out = hexdump.warn(u8([0x11, 0x22]), {
+        foldSize: 8,
+        printChars: false,
+        addrLength: 4,
+      });
+      expect(out).toBe(['0000:  11 22                   ', '0002:                          '].join('\n'));
+      expect(captured.length).toBeGreaterThan(0);
+      expect(captured[0]).toBe(out.split(/\n/)[0]);
+    } finally {
+      console.warn = orig;
+    }
+  });
+
+  it('log printer emits to console.log', () => {
+    const orig = console.log;
+    const captured: string[] = [];
+    console.log = (s: string) => void captured.push(s);
+    try {
+      const out = hexdump.log(u8([0xaa]), { foldSize: 8, printChars: false, addrLength: 4 });
+      expect(out).toBe(['0000:  aa                      ', '0001:                          '].join('\n'));
+      expect(captured.length).toBeGreaterThan(0);
+      expect(captured[0]).toBe(out.split(/\n/)[0]);
+    } finally {
+      console.log = orig;
+    }
+  });
+
+  it('error printer emits to console.error', () => {
+    const orig = console.error;
+    const captured: string[] = [];
+    console.error = (s: string) => void captured.push(s);
+    try {
+      const out = hexdump.error(u8([0xbb]), { foldSize: 8, printChars: false, addrLength: 4 });
+      expect(out).toBe(['0000:  bb                      ', '0001:                          '].join('\n'));
+      expect(captured.length).toBeGreaterThan(0);
+      expect(captured[0]).toBe(out.split(/\n/)[0]);
+    } finally {
+      console.error = orig;
+    }
+  });
+
+  it('string and default produce identical output', () => {
+    const buf = u8([0, 1, 2]);
+    const opts = { foldSize: 8, printChars: false, addrLength: 4 } as const;
+    const a = hexdump(buf, opts);
+    const b = hexdump.string(buf, opts);
+    expect(a).toBe(b);
+  });
+});
+
+describe('default export', () => {
+  it('exposes hexdump equivalent to named export', () => {
+    const buf = u8([0x01, 0x02]);
+    const opts = { foldSize: 8, printChars: false, addrLength: 4 } as const;
+    const a = hexdump(buf, opts);
+    const b = hexdumpDefault(buf, opts);
+    expect(a).toBe(b);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.common.json" }

package/dist/hexdump.d.ts

@@ -1,44 +0,0 @@
-type Context = {
-    type: 'hex-value' | 'hex-value-prefix' | 'hex-value-suffix' | 'character-value';
-    address: number;
-    value: number;
-} | {
-    type: 'address';
-    address: number;
-} | {
-    type: 'line-prefix' | 'address-prefix' | 'address-suffix' | 'hex-dump-prefix' | 'hex-group-prefix' | 'hex-value-no-data' | 'character-value-no-data' | 'hex-gap' | 'hex-group-gap' | 'hex-group-suffix' | 'hex-dump-suffix' | 'character-prefix' | 'character-suffix' | 'line-suffix' | 'flush';
-};
-type ColorizerOperation = {
-    enter: string;
-    leave: string;
-    escape?: (s: string) => string;
-} | null;
-type Colorizer = boolean | undefined | 'simple' | 'html' | ((s: string, ctx: Context) => ColorizerOperation | undefined);
-type Formatter = undefined | ((s: string, ctx: Context) => string | undefined);
-type Options = {
-    addrOffset?: number;
-    addrLength?: number;
-    printer?: false | ((s: string) => void);
-    formatter?: Formatter;
-    color?: Colorizer;
-    prefix?: string;
-    printChars?: boolean;
-    foldSize?: number;
-    footer?: boolean;
-};
-interface Hexdumper {
-    (buf: ArrayLike<number> | ArrayBuffer | DataView, options?: Options): string;
-    (buf: ArrayLike<number> | ArrayBuffer | DataView, len: number, options?: Options): string;
-}
-interface Hexdump extends Hexdumper {
-    log: Hexdumper;
-    warn: Hexdumper;
-    error: Hexdumper;
-    string: Hexdumper;
-    create: (printer: (s: string) => void) => Hexdumper;
-}
-export declare const hexdump: Hexdump;
-declare const _default: {
-    hexdump: Hexdump;
-};
-export default _default;

package/dist/hexdump.js

@@ -1,2 +0,0 @@
-"use strict";function C(t,n){return Number(t).toString(16).padStart(n,"0")}const g=t=>t,f=t=>t.replace(/[&<>]/g,n=>({"&":"&amp;","<":"&lt;",">":"&gt;"})[n]),A={simple:{address:{enter:"\x1B[38;5;238m",leave:"\x1B[m"},separator:{enter:"\x1B[38;5;238m",leave:"\x1B[m"},control:{enter:"\x1B[38;5;178m",leave:"\x1B[m"},ascii:{enter:"\x1B[m",leave:"\x1B[m"},exascii:{enter:"\x1B[38;5;209m",leave:"\x1B[m"},null:{enter:"\x1B[38;5;244m",leave:"\x1B[m"},normal:null},html:{address:{enter:'<span class="hexdump-address">',leave:"</span>",escape:f},separator:{enter:'<span class="hexdump-separator">',leave:"</span>",escape:f},control:{enter:'<span class="hexdump-control">',leave:"</span>",escape:f},ascii:{enter:'<span class="hexdump-ascii">',leave:"</span>",escape:f},exascii:{enter:'<span class="hexdump-exascii">',leave:"</span>",escape:f},null:{enter:'<span class="hexdump-null">',leave:"</span>",escape:f},normal:{enter:"",leave:"",escape:f}}},L=t=>{let n;if(!t)return g;if(t===!0&&(t="simple"),typeof t=="string"){const e=A[t],s=["address-prefix","address-suffix","character-prefix","character-suffix"];t=function(a,i){if(a.trim())return e.address&&i.type==="address"?e.address:e.separator&&s.includes(i.type)?e.separator:(i.type==="hex-value"||i.type==="character-value")&&typeof i.value=="number"?e.null!==void 0&&i.value===0?e.null:e.control!==void 0&&i.value<32?e.control:e.ascii!==void 0&&32<=i.value&&i.value<127?e.ascii:e.exascii!==void 0&&128<=i.value&&i.value<=255?e.exascii:e.normal:e.normal}}return(e,s)=>{const a=s.type==="flush"?null:t(e,s);return a!==void 0&&(n?.enter!==a?.enter||n?.leave!==a?.leave||n?.escape!==a?.escape)&&(e=(n?.leave||"")+(a?.enter||"")+(a?.escape||g)(e),n=a),e}},S=t=>(t||(t=g),(n,e)=>t(n,e)||"");function c(t){return(n,e,s)=>{const a=ArrayBuffer.isView(n)?new Uint8Array(n.buffer,n.byteOffset,n.byteLength):new Uint8Array(n);typeof e!="number"&&(s=e,e=a.length),s={...s??{}},(e===void 0||e<0)&&(e=a.length),t=s.printer||t;const i=S(s.formatter),O=L(s.color),l=s.foldSize||16,z=s.printChars!==!1;let p=s.addrOffset||0;const y=p%l,w=(e?Math.ceil((y%l+e)/l):0)+(s.footer!==!1?1:0),v=[];let m="";const r=function(d,h){m+=O(i(d,h),h)},b=s?.prefix||"",H=s?.addrLength??8-b.length;for(let d=0;d<w;d++){const h=p;r("",{type:"line-prefix"}),r(b,{type:"address-prefix"}),r(C(p,H),{type:"address",address:p}),r(": ",{type:"address-suffix"}),r(" ",{type:"hex-dump-prefix"}),r("",{type:"hex-group-prefix"});for(let o=0;o<l;o++){const u=d*l+o-y;o&&o%8==0?(r("",{type:"hex-group-suffix"}),r("  ",{type:"hex-group-gap"}),r("",{type:"hex-group-prefix"})):o&&r(" ",{type:"hex-gap"}),0<=u&&u<e?(r("",{type:"hex-value-prefix",address:p,value:a[u]}),r(C(a[u],2),{type:"hex-value",address:p,value:a[u]}),r("",{type:"hex-value-suffix",address:p,value:a[u]}),p++):r("  ",{type:"hex-value-no-data"})}if(r("",{type:"hex-group-suffix"}),r(" ",{type:"hex-dump-suffix"}),z){let o=h;r(" |",{type:"character-prefix"});for(let u=0;u<l;u++){const x=d*l+u-y;0<=x&&x<e?(r(a[x]>=32&&a[x]<127?String.fromCharCode(a[x]):".",{type:"character-value",address:o,value:a[x]}),o++):r(" ",{type:"character-value-no-data"})}r("|",{type:"character-suffix"})}r("",{type:"line-suffix"}),r("",{type:"flush"}),t?.(m),v.push(m),m=""}return v.join(`
-`)}}export const hexdump=Object.assign(c(null),{create:c,log:c(console.log),warn:c(console.warn),error:c(console.error),string:c(null)});export default{hexdump};