jpeek 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bhusan
+
+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

@@ -0,0 +1,33 @@
+# jpeek
+
+Interactive fold/unfold JSON tree viewer for the terminal. Zero deps.
+
+## Install
+
+```sh
+npm install jpeek
+```
+
+## Usage
+
+```js
+const { jpeek } = require('jpeek');
+
+jpeek.interact('my data', { hello: 'world', list: [1, 2, 3] });
+```
+
+`jpeek.interact(name, data)` opens an interactive tree in the terminal. Blocks
+synchronously until you quit — no `await` needed.
+
+- `↑`/`↓` (or `j`/`k`) — move
+- `→`/`enter` — expand
+- `←` — collapse / go to parent
+- `space` — toggle
+- `q` / `esc` / `ctrl-c` — quit
+
+`jpeek.render(name, data)` prints a static, fully expanded tree instead —
+useful for one-shot dumps. Press `q` to quit.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,279 @@
+'use strict';
+
+const fs = require('fs');
+
+// ---- tiny ANSI palette (no deps) ----
+const C = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+  invert: '\x1b[7m',
+};
+
+const INTERACT_HINT = 'Up arrow/Down arrow navigate · Right arrow/enter expand · Left arrow collapse · space toggle · q quit';
+const RENDER_HINT = 'q to quit';
+
+function typeOf(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v; // object | string | number | boolean | undefined
+}
+
+function isContainer(v) {
+  const t = typeOf(v);
+  return t === 'object' || t === 'array';
+}
+
+function scalarText(v) {
+  const t = typeOf(v);
+  if (t === 'string') return JSON.stringify(v);
+  if (t === 'null') return 'null';
+  if (t === 'undefined') return 'undefined';
+  return String(v);
+}
+
+function scalarColored(v) {
+  const t = typeOf(v);
+  if (t === 'string') return C.green + JSON.stringify(v) + C.reset;
+  if (t === 'number') return C.yellow + v + C.reset;
+  if (t === 'boolean') return C.magenta + v + C.reset;
+  return C.gray + scalarText(v) + C.reset;
+}
+
+/**
+ * jpeek.interact(name, data)
+ * Opens an interactive fold/unfold tree in the terminal.
+ * Blocks the calling thread synchronously until the user quits (q / esc / ctrl-c) —
+ * no Promise, no await needed; call it as a plain statement.
+ * Keys: ↑/↓ (or j/k) move · →/enter expand · ← collapse/parent · space toggle · q quit
+ */
+function interact(name, data) {
+  const expanded = new Set(['$']); // root open, everything else collapsed
+  let cursor = 0;
+  let top = 0;
+
+  // Flatten current tree into visible rows based on `expanded`.
+  function build() {
+    const rows = [];
+    (function walk(value, key, path, depth) {
+      const container = isContainer(value);
+      const isOpen = expanded.has(path);
+      rows.push({ key, value, path, depth, container, isOpen });
+      if (container && isOpen) {
+        if (typeOf(value) === 'array') {
+          value.forEach((item, i) => walk(item, i, path + '.' + i, depth + 1));
+        } else {
+          Object.keys(value).forEach((k) => walk(value[k], k, path + '.' + k, depth + 1));
+        }
+      }
+    })(data, '$', '$', 0);
+    return rows;
+  }
+
+  function summaryText(value) {
+    return typeOf(value) === 'array'
+      ? `Array(${value.length})`
+      : `{${Object.keys(value).length}}`;
+  }
+
+  function renderRow(row, highlighted) {
+    const indent = '  '.repeat(row.depth);
+    const marker = row.container ? (row.isOpen ? '▼ ' : '▶ ') : '  ';
+    const keyText = row.key === '$' ? '' : row.key + ': ';
+    const valText = row.container ? summaryText(row.value) : scalarText(row.value);
+
+    if (highlighted) {
+      // Plain text only — embedded color resets would break the invert.
+      return C.invert + indent + marker + keyText + valText + C.reset;
+    }
+    const cKey = row.key === '$' ? '' : C.cyan + row.key + C.reset + ': ';
+    const cVal = row.container ? C.dim + valText + C.reset : scalarColored(row.value);
+    return indent + marker + cKey + cVal;
+  }
+
+  function render() {
+    const rows = build();
+    const headerLines = name ? 1 : 0;
+    const footerLines = 1;
+    const height = (process.stdout.rows || 24) - 1 - headerLines - footerLines;
+    if (cursor < 0) cursor = 0;
+    if (cursor > rows.length - 1) cursor = rows.length - 1;
+    if (cursor < top) top = cursor;
+    if (cursor >= top + height) top = cursor - height + 1;
+
+    let out = '\x1b[2J\x1b[H'; // clear + cursor home
+    if (name) out += C.invert + ' ' + name + ' ' + C.reset + '\n';
+    rows.slice(top, top + height).forEach((row, i) => {
+      out += renderRow(row, top + i === cursor) + '\n';
+    });
+    out += '\n' + C.gray + INTERACT_HINT + C.reset + '\n';
+    process.stdout.write(out);
+  }
+
+  function cleanup() {
+    process.stdout.write('\x1b[?25h'); // show cursor
+    process.stdout.write('\x1b[?1049l'); // leave alternate screen
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  }
+
+  // input -> one of: 'up' 'down' 'left' 'right' 'space' 'enter' 'quit' 'other'
+  function decode(chunk) {
+    if (chunk.includes('q') || chunk.includes('\x03') || chunk === '\x1b') return 'quit';
+    if (chunk === '\x1b[A' || chunk === 'k') return 'up';
+    if (chunk === '\x1b[B' || chunk === 'j') return 'down';
+    if (chunk === '\x1b[C' || chunk === 'l') return 'right';
+    if (chunk === '\x1b[D' || chunk === 'h') return 'left';
+    if (chunk === ' ') return 'space';
+    if (chunk === '\r' || chunk === '\n') return 'enter';
+    return 'other';
+  }
+
+  function onKey(action) {
+    const rows = build();
+    const node = rows[cursor];
+
+    if (action === 'quit') return true;
+    if (action === 'up') cursor--;
+    else if (action === 'down') cursor++;
+    else if (action === 'right' || action === 'enter') {
+      if (node.container && !node.isOpen) expanded.add(node.path);
+      else if (node.container && node.isOpen) cursor++; // step into first child
+    } else if (action === 'space') {
+      if (node.container) {
+        node.isOpen ? expanded.delete(node.path) : expanded.add(node.path);
+      }
+    } else if (action === 'left') {
+      if (node.container && node.isOpen) {
+        expanded.delete(node.path);
+      } else {
+        const parent = node.path.split('.').slice(0, -1).join('.');
+        const idx = rows.findIndex((r) => r.path === parent);
+        if (idx >= 0) cursor = idx;
+      }
+    }
+    render();
+    return false;
+  }
+
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+  process.stdout.write('\x1b[?1049h'); // alternate screen buffer
+  process.stdout.write('\x1b[?25l'); // hide cursor
+  render();
+
+  // Synchronous blocking read loop — no event loop, no Promise, no await needed.
+  const buf = Buffer.alloc(16);
+  let quit = false;
+  while (!quit) {
+    let n;
+    try {
+      n = fs.readSync(0, buf, 0, 16, null);
+    } catch (err) {
+      if (err.code === 'EAGAIN') continue;
+      if (err.code === 'EOF') break;
+      throw err;
+    }
+    if (n === 0) break; // EOF (e.g. piped stdin exhausted)
+    if (n < 0) continue;
+    quit = onKey(decode(buf.toString('utf8', 0, n)));
+  }
+
+  cleanup();
+}
+
+// Blocks synchronously (fs.readSync) until q / esc / ctrl-c. No Promise, no await.
+function waitForQuit() {
+  const buf = Buffer.alloc(16);
+  for (;;) {
+    let n;
+    try {
+      n = fs.readSync(0, buf, 0, 16, null);
+    } catch (err) {
+      if (err.code === 'EAGAIN') continue;
+      if (err.code === 'EOF') return;
+      throw err;
+    }
+    if (n === 0) return; // EOF (e.g. piped stdin exhausted)
+    if (n < 0) continue;
+    const chunk = buf.toString('utf8', 0, n);
+    if (chunk.includes('q') || chunk.includes('\x03') || chunk === '\x1b') return;
+  }
+}
+
+/**
+ * jpeek.render(name, data)
+ * Opens the alternate screen buffer and prints the full (already expanded)
+ * tree — no navigation, just a static view. Blocks (fs.readSync, no await
+ * needed) until q / esc / ctrl-c, then leaves the alt screen and returns,
+ * so the next jpeek call runs right after.
+ */
+function render(name, data) {
+  function summaryText(value) {
+    return typeOf(value) === 'array'
+      ? `Array(${value.length})`
+      : `{${Object.keys(value).length}}`;
+  }
+
+  function walk(value, key, depth, lines) {
+    const container = isContainer(value);
+    const indent = '  '.repeat(depth);
+    const keyText = key === '$' ? '' : C.cyan + key + C.reset + ': ';
+    const marker = container ? '▼ ' : '  ';
+
+    if (!container) {
+      lines.push(indent + marker + keyText + scalarColored(value));
+      return;
+    }
+    lines.push(indent + marker + keyText + C.dim + summaryText(value) + C.reset);
+    if (typeOf(value) === 'array') {
+      value.forEach((item, i) => walk(item, i, depth + 1, lines));
+    } else {
+      Object.keys(value).forEach((k) => walk(value[k], k, depth + 1, lines));
+    }
+  }
+
+  const lines = [];
+  walk(data, '$', 0, lines);
+
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+  process.stdout.write('\x1b[?1049h'); // alternate screen buffer
+  process.stdout.write('\x1b[?25l'); // hide cursor
+  let out = '\x1b[2J\x1b[H';
+  if (name) out += C.invert + ' ' + name + ' ' + C.reset + '\n';
+  out += lines.join('\n') + '\n';
+  out += '\n' + C.gray + RENDER_HINT + C.reset + '\n';
+  process.stdout.write(out);
+
+  waitForQuit();
+
+  process.stdout.write('\x1b[?25h'); // show cursor
+  process.stdout.write('\x1b[?1049l'); // leave alternate screen
+  if (process.stdin.isTTY) process.stdin.setRawMode(false);
+}
+
+const jpeek = { interact, render };
+module.exports = { jpeek };
+
+// Demo when run directly: `node jpeek.js`
+if (require.main === module) {
+  const sample = {
+    id: 42,
+    name: 'PortPro carrier',
+    active: true,
+    scac: null,
+    terminals: ['LAX', 'LGB', 'OAK'],
+    contact: { email: 'ops@example.com', phones: ['555-0100', '555-0101'] },
+    loads: [
+      { ref: 'L-001', finalAmount: 1250.5, stops: 2 },
+      { ref: 'L-002', finalAmount: 980, stops: 3 },
+    ],
+  };
+  jpeek.interact('sample', sample);
+  process.exit(0);
+}
+
+
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "jpeek",
+  "version": "1.0.0",
+  "description": "Interactive fold/unfold JSON tree viewer for the terminal — zero deps.",
+  "main": "index.js",
+  "files": [
+    "index.js"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "json",
+    "terminal",
+    "cli",
+    "tree",
+    "debug",
+    "inspect",
+    "viewer"
+  ],
+  "author": "bhusandotel <bhusandotel1@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  }
+}