utilium 3.5.1 → 3.6.0

package/dist/dom.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 // Copyright (c) 2025 James Prevett
 /* eslint-disable @typescript-eslint/no-unused-expressions */
+/// <reference lib="dom" />
 /**
  * Upload a file
  * @todo use Promise.withResolvers

package/dist/shell.d.ts

@@ -1,46 +1,56 @@
-import type { Terminal } from '@xterm/xterm';
 /**
  * Parse a line into arguments.
  * Supports single and double quoted strings as well as backslash escaping.
  */
 export declare function splitIntoArgs(input: string): string[];
+/** Where a shell reads keystrokes from, i.e. the parts of `NodeJS.ReadStream` it uses. */
+export interface ShellInput {
+    on(event: 'data', listener: (chunk: string | Uint8Array) => void): unknown;
+    off?(event: 'data', listener: (chunk: string | Uint8Array) => void): unknown;
+    /** Hand over keystrokes as they are typed, instead of a line at a time with editing and echo */
+    setRawMode?(raw: boolean): unknown;
+    resume?(): unknown;
+    pause?(): unknown;
+    readonly isTTY?: boolean;
+}
+/**
+ * Where a shell draws, i.e. the parts of `NodeJS.WriteStream` it uses.
+ */
+export interface ShellOutput {
+    write(data: string): unknown;
+    readonly columns?: number;
+    readonly rows?: number;
+}
 export interface ShellOptions {
     /**
-     * The terminal associated with the context
-     */
-    terminal: Terminal;
-    /**
-     * The prompt to use, can be a getter.
+     * The stream keystrokes are read from, e.g. `process.stdin`.
+     * The shell does its own line editing, so it is put into raw mode.
      */
+    stdin: ShellInput;
+    /** The stream the prompt and the line being edited are written to, e.g. `process.stdout`. */
+    stdout: ShellOutput;
+    /** The prompt to use, can be a getter. */
     readonly prompt?: string;
-    /**
-     * The length to use for the prompt. Useful if escape sequences are used in the prompt.
-     */
+    /** The length to use for the prompt. Useful if escape sequences are used in the prompt. */
     readonly promptLength?: number;
-    /**
-     * The handler for when a line is parsed
-     */
+    /** The handler for when a line is parsed */
     onLine?(this: void, line: string): unknown;
 }
 export interface ShellContext extends Required<ShellOptions> {
-    /**
-     * The input currently being shown
-     */
+    /** The input currently being shown */
     input: string;
-    /**
-     * The index for which input is being shown
-     */
+    /** Where the cursor is in `input`. */
+    cursor: number;
+    /** The index for which input is being shown */
     index: number;
-    /**
-     * The current, uncached input
-     */
+    /** The current, uncached input */
     currentInput: string;
-    /**
-     * array of previous inputs
-     */
+    /** array of previous inputs */
     inputs: string[];
+    /** Stop reading from `stdin` and put it back the way it was found */
+    close(): void;
 }
 /**
- * A simple wrapper for xterm.js that makes implementing shells easier.
+ * A simple wrapper for a pair of streams that makes implementing shells easier.
  */
 export declare function createShell(options: ShellOptions): ShellContext;

package/dist/shell.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (c) 2026 James Prevett
 /**
  * Parse a line into arguments.
  * Supports single and double quoted strings as well as backslash escaping.
@@ -35,75 +37,94 @@ export function splitIntoArgs(input) {
         args.push(current);
     return args;
 }
-async function handleData($, data) {
+/**
+ * One key press: a CSI or SS3 escape sequence, or a single character.
+ * A read can come back with more than one key in it, e.g. when text is pasted,
+ * and an escape sequence must not be taken for the characters it is made of.
+ */
+// eslint-disable-next-line no-control-regex
+const keyPattern = /\x1b\[[0-?]*[ -\/]*[@-~]|\x1bO[@-~]|[\s\S]/gu;
+async function handleKey($, key) {
     if ($.index == -1) {
         $.currentInput = $.input;
     }
-    function clear() {
-        $.terminal.write('\x1b[2K\r' + $.prompt);
+    /** Redraw the whole line, for when the input is replaced rather than edited */
+    function redraw() {
+        $.stdout.write('\x1b[2K\r' + $.prompt + $.input);
+        $.cursor = $.input.length;
     }
-    const x = $.terminal.buffer.active.cursorX - $.promptLength;
-    switch (data) {
+    switch (key) {
         case 'ArrowUp':
         case '\x1b[A':
-            clear();
             if ($.index < $.inputs.length - 1) {
                 $.input = $.inputs[++$.index];
             }
-            $.terminal.write($.input);
+            redraw();
             break;
         case 'ArrowDown':
         case '\x1b[B':
-            clear();
             if ($.index >= 0) {
                 $.input = $.index-- == 0 ? $.currentInput : $.inputs[$.index];
             }
-            $.terminal.write($.input);
+            redraw();
             break;
         case '\x1b[D':
-            if (x > 0) {
-                $.terminal.write(data);
+            if ($.cursor > 0) {
+                $.cursor--;
+                $.stdout.write(key);
             }
             break;
         case '\x1b[C':
-            if (x < $.input.length) {
-                $.terminal.write(data);
+            if ($.cursor < $.input.length) {
+                $.cursor++;
+                $.stdout.write(key);
             }
             break;
         case '\x1b[F':
-            $.terminal.write(`\x1b[${$.promptLength + $.input.length + 1}G`);
+            $.cursor = $.input.length;
+            $.stdout.write(`\x1b[${$.promptLength + $.cursor + 1}G`);
             break;
         case '\x1b[H':
-            $.terminal.write(`\x1b[${$.promptLength + 1}G`);
+            $.cursor = 0;
+            $.stdout.write(`\x1b[${$.promptLength + 1}G`);
             break;
         case '\x7f':
-            if (x <= 0) {
+            if ($.cursor <= 0) {
                 return;
             }
-            $.terminal.write('\b\x1b[P');
-            $.input = $.input.slice(0, x - 1) + $.input.slice(x);
+            $.input = $.input.slice(0, $.cursor - 1) + $.input.slice($.cursor);
+            $.cursor--;
+            $.stdout.write('\b\x1b[P');
             break;
         case '\r':
             if ($.input != $.inputs[0]) {
                 $.inputs.unshift($.input);
             }
-            $.terminal.write('\r\n');
+            $.stdout.write('\r\n');
             await $.onLine($.input);
             $.index = -1;
             $.input = '';
-            $.terminal.write($.prompt);
+            $.cursor = 0;
+            $.stdout.write($.prompt);
             break;
-        default:
-            $.terminal.write(data);
-            $.input = $.input.slice(0, x) + data + $.input.slice(x);
+        default: {
+            if (key.startsWith('\x1b') || key < ' ')
+                return;
+            $.input = $.input.slice(0, $.cursor) + key + $.input.slice($.cursor);
+            $.cursor += key.length;
+            const rest = $.input.slice($.cursor);
+            $.stdout.write(key + rest + (rest ? `\x1b[${rest.length}D` : ''));
+        }
     }
 }
 /**
- * A simple wrapper for xterm.js that makes implementing shells easier.
+ * A simple wrapper for a pair of streams that makes implementing shells easier.
  */
 export function createShell(options) {
+    const decoder = new TextDecoder();
     const context = {
-        terminal: options.terminal,
+        stdin: options.stdin,
+        stdout: options.stdout,
         get prompt() {
             return options.prompt ?? '';
         },
@@ -112,10 +133,26 @@ export function createShell(options) {
         },
         onLine: options.onLine ?? (() => { }),
         input: '',
+        cursor: 0,
         index: -1,
         currentInput: '',
         inputs: [],
+        close() {
+            options.stdin.off?.('data', listener);
+            options.stdin.setRawMode?.(false);
+            options.stdin.pause?.();
+        },
+    };
+    let pending = Promise.resolve();
+    const listener = (chunk) => {
+        const data = typeof chunk == 'string' ? chunk : decoder.decode(chunk, { stream: true });
+        pending = pending.then(async () => {
+            for (const [key] of data.matchAll(keyPattern))
+                await handleKey(context, key);
+        });
     };
-    options.terminal.onData(data => handleData(context, data));
+    options.stdin.setRawMode?.(true);
+    options.stdin.on('data', listener);
+    options.stdin.resume?.();
     return context;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "utilium",
-	"version": "3.5.1",
+	"version": "3.6.0",
 	"description": "Typescript utilities",
 	"funding": {
 		"type": "individual",
@@ -42,27 +42,18 @@
 	"homepage": "https://github.com/james-pre/utilium#readme",
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
-		"@types/node": "^24.7.0",
+		"@types/node": "^26.0.0",
 		"eslint": "^10.1.0",
 		"globals": "^17.8.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.1",
 		"typedoc": "^0.28.18",
 		"typescript": "^6.0.0",
-		"typescript-eslint": "^8.58.0",
-		"@xterm/xterm": "^6.0.0"
+		"typescript-eslint": "^8.58.0"
 	},
 	"dependencies": {
 		"eventemitter3": "^5.0.1"
 	},
-	"peerDependencies": {
-		"@xterm/xterm": "^6.0.0"
-	},
-	"peerDependenciesMeta": {
-		"@xterm/xterm": {
-			"optional": true
-		}
-	},
 	"engines": {
 		"node": ">=22.0.0"
 	},