@kikuchan/hexdump 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -0,0 +1,53 @@
+# @kikuchan/hexdump
+
+Tiny, configurable hex dump utility for Node.js and browsers.
+
+## Install
+
+```bash
+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/index.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,`__esModule`,{value:!0});function e(e,t){return Number(e).toString(16).padStart(t,`0`)}const t=e=>e,n=e=>e.replace(/[&<>]/g,e=>({"&":`&amp;`,"<":`&lt;`,">":`&gt;`})[e]),r={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:n},separator:{enter:`<span class="hexdump-separator">`,leave:`</span>`,escape:n},control:{enter:`<span class="hexdump-control">`,leave:`</span>`,escape:n},ascii:{enter:`<span class="hexdump-ascii">`,leave:`</span>`,escape:n},exascii:{enter:`<span class="hexdump-exascii">`,leave:`</span>`,escape:n},null:{enter:`<span class="hexdump-null">`,leave:`</span>`,escape:n},normal:{enter:``,leave:``,escape:n}}},i=e=>{let n;if(!e)return t;if(e===!0&&(e=`simple`),typeof e==`string`){let t=r[e],n=[`address-prefix`,`address-suffix`,`character-prefix`,`character-suffix`];e=function(e,r){if(e.trim()){if(t.address&&r.type===`address`)return t.address;if(t.separator&&n.includes(r.type))return t.separator;if((r.type===`hex-value`||r.type===`character-value`)&&typeof r.value==`number`){if(t.null!==void 0&&r.value===0)return t.null;if(t.control!==void 0&&r.value<32)return t.control;if(t.ascii!==void 0&&32<=r.value&&r.value<127)return t.ascii;if(t.exascii!==void 0&&128<=r.value&&r.value<=255)return t.exascii}return t.normal}}}return(r,i)=>{let a=i.type===`flush`?null:e(r,i);return a!==void 0&&(n?.enter!==a?.enter||n?.leave!==a?.leave||n?.escape!==a?.escape)?(r=(n?.leave||``)+(a?.enter||``)+(a?.escape||t)(r),n=a,r):a&&a.escape?a.escape(r):r}},a=e=>(e||=t,(t,n)=>e(t,n)||``);function o(t){return(n,r,o)=>{let s=ArrayBuffer.isView(n)?new Uint8Array(n.buffer,n.byteOffset,n.byteLength):new Uint8Array(n);typeof r!=`number`&&(o=r,r=s.length),o={...o??{}},(r===void 0||r<0)&&(r=s.length),t=o.printer===null?null:o.printer??t;let c=a(o.formatter),l=i(o.color),u=o.foldSize||16,d=o.printChars!==!1,f=o.addrOffset||0,p=f%u,m=(r?Math.ceil((p%u+r)/u):0)+(o.footer===!1?0:1),h=[],g=``,_=function(e,t){g+=l(c(e,t),t)},v=o?.prefix||``,y=Math.max(o?.addrLength??8-v.length,0);for(let n=0;n<m;n++){let i=f;_(``,{type:`line-prefix`}),_(v,{type:`address-prefix`}),y>=1&&_(e(f,y),{type:`address`,address:f}),_(`: `,{type:`address-suffix`}),_(` `,{type:`hex-dump-prefix`}),_(``,{type:`hex-group-prefix`});for(let t=0;t<u;t++){let i=n*u+t-p;t&&t%8==0?(_(``,{type:`hex-group-suffix`}),_(`  `,{type:`hex-group-gap`}),_(``,{type:`hex-group-prefix`})):t&&_(` `,{type:`hex-gap`}),0<=i&&i<r?(_(``,{type:`hex-value-prefix`,address:f,value:s[i]}),_(e(s[i],2),{type:`hex-value`,address:f,value:s[i]}),_(``,{type:`hex-value-suffix`,address:f,value:s[i]}),f++):_(`  `,{type:`hex-value-no-data`})}if(_(``,{type:`hex-group-suffix`}),_(` `,{type:`hex-dump-suffix`}),d){let e=i;_(` |`,{type:`character-prefix`});for(let t=0;t<u;t++){let i=n*u+t-p;0<=i&&i<r?(_(s[i]>=32&&s[i]<127?String.fromCharCode(s[i]):`.`,{type:`character-value`,address:e,value:s[i]}),e++):_(` `,{type:`character-value-no-data`})}_(`|`,{type:`character-suffix`})}_(``,{type:`line-suffix`}),_(``,{type:`flush`}),t?.(g),h.push(g),g=``}return h.join(`
+`)}}const s=Object.assign(o(null),{create:o,log:o(e=>console.log(e)),warn:o(e=>console.warn(e)),error:o(e=>console.error(e)),string:o(null)});var c=s;exports.default=c,exports.hexdump=s;

package/index.d.cts

@@ -0,0 +1,44 @@
+//#region src/index.d.ts
+type BinaryLike = Uint8Array | Uint8ClampedArray | ArrayBufferLike | DataView;
+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);
+  formatter?: Formatter;
+  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;
+}
+declare const hexdump: Hexdump;
+//#endregion
+export { BinaryLike, hexdump as default, hexdump };

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "hexdump"
   ],
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "type": "module",
   "main": "./index.js",
   "author": "kikuchan <kikuchan98@gmail.com>",
@@ -14,7 +14,8 @@
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.js"
+      "import": "./index.js",
+      "require": "./index.cjs"
     }
   },
   "repository": {