@visulima/pail 3.1.0 → 3.2.1

package/dist/interactive/interactive-stream-hook.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Interactive Stream Hook.
+ *
+ * A utility class that hooks into Node.js WriteStreams to capture output
+ * for interactive terminal applications. It allows temporarily intercepting
+ * stream writes to enable features like progress bars and dynamic updates.
+ * @example
+ * ```typescript
+ * const hook = new InteractiveStreamHook(process.stdout);
+ * hook.active(); // Start capturing output
+ *
+ * // Output will be stored in history instead of being written to stdout
+ * console.log("This won't appear immediately");
+ *
+ * hook.inactive(); // Stop capturing and replay stored output
+ * ```
+ */
+declare class InteractiveStreamHook {
+    #private;
+    /** Constant indicating the stream write operation was successful */
+    static readonly DRAIN = true;
+    /**
+     * Creates a new InteractiveStreamHook for the given stream.
+     * @param stream The Node.js WriteStream to hook into (usually stdout or stderr)
+     */
+    constructor(stream: NodeJS.WriteStream);
+    /**
+     * Activates the stream hook.
+     *
+     * When active, all writes to the stream are captured in history instead of
+     * being written immediately. This allows for interactive features like
+     * progress bars that can update dynamically.
+     */
+    active(): void;
+    /**
+     * Erases the specified number of lines from the terminal.
+     *
+     * Uses ANSI escape sequences to remove lines from the current cursor position
+     * upwards, which is useful for clearing previous output in interactive applications.
+     * @param count Number of lines to erase (including the current line)
+     */
+    erase(count: number): void;
+    /**
+     * Deactivates the stream hook and replays captured output.
+     *
+     * Restores normal stream operation and outputs all captured history.
+     * Optionally adds a newline separator before replaying the history.
+     * @param separateHistory Whether to add a newline before replaying history
+     */
+    inactive(separateHistory?: boolean): void;
+    /**
+     * Renews the stream hook state.
+     *
+     * Restores the original stream write method and shows the cursor.
+     * This is typically called when temporarily suspending interactive mode.
+     */
+    renew(): void;
+    /**
+     * Writes a message directly to the underlying stream.
+     *
+     * Bypasses the hook mechanism and writes directly using the original
+     * stream write method. Useful for writing control sequences or
+     * messages that should not be captured in history.
+     * @param message The message to write to the stream
+     */
+    write(message: string): void;
+}
+export default InteractiveStreamHook;

package/dist/object-tree.d.ts

@@ -1,17 +1,75 @@
-type TreeRenderFunction = (node: unknown) => string | undefined;
-type TreeSortFunction = (a: string, b: string) => number;
-interface ObjectTreeOptions {
+/**
+ * Function to render a node value for display
+ * @param node The node to render
+ * @returns A string representation or undefined if should not render
+ */
+export type TreeRenderFunction = (node: unknown) => string | undefined;
+/**
+ * Function to sort keys during tree traversal
+ * @param a First key for comparison
+ * @param b Second key for comparison
+ * @returns Negative if a < b, positive if a > b, 0 if equal
+ */
+export type TreeSortFunction = (a: string, b: string) => number;
+/**
+ * Configuration options for object tree rendering
+ */
+export interface ObjectTreeOptions {
+    /** Text to display for circular references (default: " (circular ref.)") */
     breakCircularWith?: string | null | undefined;
+    /** Whether to return as single string or array of lines (default: true) */
     joined?: boolean;
+    /** Connector for neighbor keys (default: "├─ ") */
     keyNeighbour?: string;
+    /** Connector for non-neighbor keys (default: "└─ ") */
     keyNoNeighbour?: string;
+    /** Function to render node values (default: renders primitives) */
     renderFn?: TreeRenderFunction;
+    /** Separator between key and value (default: ": ") */
     separator?: string;
+    /** Function to sort object keys (default: natural order) */
     sortFn?: TreeSortFunction | undefined;
+    /** Spacer for neighbor branches (default: "│  ") */
     spacerNeighbour?: string;
+    /** Spacer for non-neighbor branches (default: "   ") */
     spacerNoNeighbour?: string;
 }
-declare const renderObjectTree: (tree: Record<string, unknown> | unknown[], options?: ObjectTreeOptions) => string | string[];
-
-export { renderObjectTree as default, renderObjectTree };
-export type { ObjectTreeOptions, TreeRenderFunction, TreeSortFunction };
+/**
+ * Renders an object as an ASCII tree structure.
+ * @param tree The object to render as a tree
+ * @param options Configuration options for tree rendering
+ * @returns Formatted tree as string or array of lines
+ * @example
+ * ```typescript
+ * const obj = {
+ *   name: "John",
+ *   age: 30,
+ *   address: {
+ *     street: "Main St",
+ *     city: "New York"
+ *   }
+ * };
+ *
+ * // Default output as string
+ * console.log(renderObjectTree(obj));
+ *
+ * // Custom rendering
+ * console.log(renderObjectTree(obj, {
+ *   sortFn: (a, b) => a.localeCompare(b),
+ *   renderFn: (node) => {
+ *     if (typeof node === 'string') return node.toUpperCase();
+ *     return ['boolean', 'string', 'number'].includes(typeof node)
+ *       ? String(node)
+ *       : undefined;
+ *   }
+ * }));
+ *
+ * // Get as array of lines
+ * const lines = renderObjectTree(obj, { joined: false });
+ * ```
+ */
+export declare const renderObjectTree: (tree: Record<string, unknown> | unknown[], options?: ObjectTreeOptions) => string | string[];
+/**
+ * Default export for CommonJS compatibility
+ */
+export default renderObjectTree;

package/dist/object-tree.js

@@ -1,2 +1,89 @@
-var O=Object.defineProperty;var y=(o,r)=>O(o,"name",{value:r,configurable:!0});var m=Object.defineProperty,a=y((o,r)=>m(o,"name",{value:r,configurable:!0}),"s");const j=a(o=>{const r={breakCircularWith:" (circular ref.)",joined:!0,keyNeighbour:"├─ ",keyNoNeighbour:"└─ ",renderFn:a(t=>{if(["boolean","number","string"].includes(typeof t))return String(t)},"renderFn"),separator:": ",sortFn:void 0,spacerNeighbour:"│  ",spacerNoNeighbour:"   ",...o};if(typeof r.joined!="boolean")throw new TypeError('Option "joined" must be a boolean');if(typeof r.spacerNoNeighbour!="string")throw new TypeError('Option "spacerNoNeighbour" must be a string');if(typeof r.spacerNeighbour!="string")throw new TypeError('Option "spacerNeighbour" must be a string');if(typeof r.keyNoNeighbour!="string")throw new TypeError('Option "keyNoNeighbour" must be a string');if(typeof r.keyNeighbour!="string")throw new TypeError('Option "keyNeighbour" must be a string');if(typeof r.separator!="string")throw new TypeError('Option "separator" must be a string');if(typeof r.renderFn!="function")throw new TypeError('Option "renderFn" must be a function');if(r.sortFn!==void 0&&typeof r.sortFn!="function")throw new TypeError('Option "sortFn" must be a function or undefined');if(r.breakCircularWith!==null&&typeof r.breakCircularWith!="string")throw new TypeError('Option "breakCircularWith" must be a string or null');return r},"buildContext"),T=a((o,r)=>{const t=j(r),s=[],b=t.renderFn(o);b!==void 0&&s.push(String(b));const l=a(e=>t.sortFn===void 0?e:e.toSorted((n,u)=>t?.sortFn?.(u,n)??0),"sort"),p=[],i=l(Object.keys(o)).map(e=>[e]),h=[o];for(;i.length>0;){const e=i.pop()??[],n=h[e.length-1][e[e.length-1]??""],u=t.breakCircularWith!==null&&h.slice(0,e.length).includes(n);p[e.length-1]=i.length>0&&(i[i.length-1]?.length??0)===e.length;const f=p.slice(0,e.length-1).map(g=>g?t.spacerNeighbour:t.spacerNoNeighbour).join(""),d=p[e.length-1]?t.keyNeighbour:t.keyNoNeighbour,N=e[e.length-1],c=t.renderFn(n),w=c===void 0?"":`${t.separator}${c}`,k=u?t.breakCircularWith:"";s.push(`${f}${d}${N}${w}${k}`),n!==null&&typeof n=="object"&&!Array.isArray(n)&&!u&&(i.push(...l(Object.keys(n)).map(g=>[...e,g])),h[e.length]=n)}return t.joined===!0?s.join(`
-`):s},"renderObjectTree");export{T as default,T as renderObjectTree};
+const buildContext = (options) => {
+  const context = {
+    breakCircularWith: " (circular ref.)",
+    joined: true,
+    keyNeighbour: "├─ ",
+    keyNoNeighbour: "└─ ",
+    renderFn: (node) => {
+      if (["boolean", "number", "string"].includes(typeof node)) {
+        return String(node);
+      }
+      return void 0;
+    },
+    separator: ": ",
+    sortFn: void 0,
+    spacerNeighbour: "│  ",
+    spacerNoNeighbour: "   ",
+    ...options
+  };
+  if (typeof context.joined !== "boolean") {
+    throw new TypeError('Option "joined" must be a boolean');
+  }
+  if (typeof context.spacerNoNeighbour !== "string") {
+    throw new TypeError('Option "spacerNoNeighbour" must be a string');
+  }
+  if (typeof context.spacerNeighbour !== "string") {
+    throw new TypeError('Option "spacerNeighbour" must be a string');
+  }
+  if (typeof context.keyNoNeighbour !== "string") {
+    throw new TypeError('Option "keyNoNeighbour" must be a string');
+  }
+  if (typeof context.keyNeighbour !== "string") {
+    throw new TypeError('Option "keyNeighbour" must be a string');
+  }
+  if (typeof context.separator !== "string") {
+    throw new TypeError('Option "separator" must be a string');
+  }
+  if (typeof context.renderFn !== "function") {
+    throw new TypeError('Option "renderFn" must be a function');
+  }
+  if (context.sortFn !== void 0 && typeof context.sortFn !== "function") {
+    throw new TypeError('Option "sortFn" must be a function or undefined');
+  }
+  if (context.breakCircularWith !== null && typeof context.breakCircularWith !== "string") {
+    throw new TypeError('Option "breakCircularWith" must be a string or null');
+  }
+  return context;
+};
+const renderObjectTree = (tree, options) => {
+  const context = buildContext(options);
+  const result = [];
+  const rootRendered = context.renderFn(tree);
+  if (rootRendered !== void 0) {
+    result.push(String(rootRendered));
+  }
+  const sort = (input) => {
+    if (context.sortFn === void 0) {
+      return input;
+    }
+    return input.toSorted((a, b) => context?.sortFn?.(b, a) ?? 0);
+  };
+  const neighbours = [];
+  const keys = sort(Object.keys(tree)).map((k) => [k]);
+  const lookup = [tree];
+  while (keys.length > 0) {
+    const key = keys.pop() ?? [];
+    const node = lookup[key.length - 1][key[key.length - 1] ?? ""];
+    const isCircular = context.breakCircularWith !== null && lookup.slice(0, key.length).includes(node);
+    neighbours[key.length - 1] = keys.length > 0 && (keys[keys.length - 1]?.length ?? 0) === key.length;
+    const indent = neighbours.slice(0, key.length - 1).map((n) => {
+      if (n) {
+        return context.spacerNeighbour;
+      }
+      return context.spacerNoNeighbour;
+    }).join("");
+    const connector = neighbours[key.length - 1] ? context.keyNeighbour : context.keyNoNeighbour;
+    const keyName = key[key.length - 1];
+    const nodeRendered = context.renderFn(node);
+    const value = nodeRendered === void 0 ? "" : `${context.separator}${nodeRendered}`;
+    const circular = isCircular ? context.breakCircularWith : "";
+    result.push(`${indent}${connector}${keyName}${value}${circular}`);
+    if (node !== null && typeof node === "object" && !Array.isArray(node) && !isCircular) {
+      keys.push(...sort(Object.keys(node)).map((k) => [...key, k]));
+      lookup[key.length] = node;
+    }
+  }
+  return context.joined === true ? result.join("\n") : result;
+};
+
+export { renderObjectTree as default, renderObjectTree };

package/dist/packem_shared/AbstractJsonReporter-intFdT_A.js

@@ -0,0 +1,204 @@
+import { E as EMPTY_SYMBOL } from './constants-DfDr4MHC.js';
+
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return (prototype === null || prototype === Object.prototype || Object.getPrototypeOf(prototype) === null) && !(Symbol.toStringTag in value) && !(Symbol.iterator in value);
+}
+
+const ErrorProto = Object.create(
+  {},
+  {
+    cause: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    code: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    errors: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    message: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    name: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    stack: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    }
+  }
+);
+const toJsonWasCalled = /* @__PURE__ */ new WeakSet();
+const toJSON = (from) => {
+  toJsonWasCalled.add(from);
+  const json = from.toJSON();
+  toJsonWasCalled.delete(from);
+  return json;
+};
+const serializeValue = (value, seen, depth, options) => {
+  if (value && value instanceof Uint8Array && value.constructor.name === "Buffer") {
+    return "[object Buffer]";
+  }
+  if (value !== null && typeof value === "object" && typeof value.pipe === "function") {
+    return "[object Stream]";
+  }
+  if (value instanceof Error) {
+    if (seen.includes(value)) {
+      return "[Circular]";
+    }
+    depth += 1;
+    return _serialize(value, options, seen, depth);
+  }
+  if (options.useToJSON && typeof value.toJSON === "function") {
+    return value.toJSON();
+  }
+  if (typeof value === "object" && value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "function") {
+    return `[Function: ${value.name || "anonymous"}]`;
+  }
+  if (isPlainObject(value)) {
+    depth += 1;
+    if (options.maxDepth && depth >= options.maxDepth) {
+      return {};
+    }
+    const plainObject = {};
+    for (const key in value) {
+      plainObject[key] = serializeValue(value[key], seen, depth, options);
+    }
+    return plainObject;
+  }
+  try {
+    return value;
+  } catch {
+    return "[Not Available]";
+  }
+};
+const _serialize = (error, options, seen, depth) => {
+  seen.push(error);
+  if (options.maxDepth === 0) {
+    return {};
+  }
+  if (options.useToJSON && typeof error.toJSON === "function" && !toJsonWasCalled.has(error)) {
+    return toJSON(error);
+  }
+  const protoError = Object.create(ErrorProto);
+  protoError.name = Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name;
+  protoError.message = error.message;
+  protoError.stack = error.stack;
+  if (Array.isArray(error.errors)) {
+    const aggregateErrors = [];
+    for (const aggregateError of error.errors) {
+      if (!(aggregateError instanceof Error)) {
+        throw new TypeError("All errors in the 'errors' property must be instances of Error");
+      }
+      if (seen.includes(aggregateError)) {
+        protoError.errors = [];
+        return protoError;
+      }
+      aggregateErrors.push(_serialize(aggregateError, options, seen, depth));
+    }
+    protoError.errors = aggregateErrors;
+  }
+  if (error.cause instanceof Error && !seen.includes(error.cause)) {
+    protoError.cause = _serialize(error.cause, options, seen, depth);
+  }
+  for (const key in error) {
+    if (protoError[key] === void 0) {
+      const value = error[key];
+      protoError[key] = serializeValue(value, seen, depth, options);
+    }
+  }
+  if (Array.isArray(options.exclude) && options.exclude.length > 0) {
+    for (const key of options.exclude) {
+      try {
+        delete protoError[key];
+      } catch {
+      }
+    }
+  }
+  return protoError;
+};
+const serialize = (error, options = {}) => _serialize(
+  error,
+  {
+    exclude: options.exclude ?? [],
+    maxDepth: options.maxDepth ?? Number.POSITIVE_INFINITY,
+    useToJSON: options.useToJSON ?? false
+  },
+  [],
+  0
+);
+
+class AbstractJsonReporter {
+  /** Custom stringify function for object serialization */
+  stringify;
+  /** Error serialization options */
+  errorOptions;
+  /**
+   * Creates a new AbstractJsonReporter instance.
+   * @param options Configuration options for JSON formatting and error handling
+   */
+  constructor(options = {}) {
+    this.errorOptions = options.error ?? {};
+  }
+  /**
+   * Sets a custom stringify function for object serialization.
+   * @param function_ The stringify function to use for serialization
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+  setStringify(function_) {
+    this.stringify = function_;
+  }
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  log(meta) {
+    const { context, error, file, message, type, ...rest } = meta;
+    if (rest.label) {
+      rest.label = rest.label.trim();
+    }
+    if (file) {
+      rest.file = `${file.name}:${file.line}${file.column ? `:${file.column}` : ""}`;
+    }
+    if (message === EMPTY_SYMBOL) {
+      rest.message = void 0;
+    } else {
+      rest.message = message;
+    }
+    if (error) {
+      rest.error = serialize(error, this.errorOptions);
+    }
+    if (context) {
+      const newContext = [];
+      for (const item of context) {
+        if (item === EMPTY_SYMBOL) {
+          continue;
+        }
+        if (item instanceof Error) {
+          newContext.push(serialize(item, this.errorOptions));
+        } else {
+          newContext.push(item);
+        }
+      }
+      rest.context = newContext;
+    }
+    this._log(this.stringify(rest), type.level);
+  }
+}
+
+export { AbstractJsonReporter };

package/dist/packem_shared/InteractiveManager-CZ85hGNW.js

@@ -0,0 +1,172 @@
+import { t as terminalSize, w as wordWrap, W as WrapMode } from './index-DqKWykfa.js';
+
+class InteractiveManager {
+  #stream;
+  #isActive = false;
+  #isSuspended = false;
+  #lastLength = 0;
+  #outside = 0;
+  /**
+   * Creates a new InteractiveManager with the given stream hooks.
+   * @param stdout Hook for stdout stream
+   * @param stderr Hook for stderr stream
+   */
+  constructor(stdout, stderr) {
+    this.#stream = {
+      stderr,
+      stdout
+    };
+  }
+  /**
+   * Last printed rows count.
+   *
+   * Tracks the number of rows that were last written to the terminal.
+   * Used internally for managing cursor positioning and output updates.
+   */
+  get lastLength() {
+    return this.#lastLength;
+  }
+  /**
+   * Rows count outside editable area.
+   *
+   * Tracks the number of rows that extend beyond the current terminal height.
+   * Used for managing scrolling and ensuring all output remains visible.
+   */
+  get outside() {
+    return this.#outside;
+  }
+  /**
+   * Hook activity status.
+   *
+   * Indicates whether the interactive hooks are currently active.
+   * When true, streams are being intercepted for interactive output.
+   */
+  get isHooked() {
+    return this.#isActive;
+  }
+  /**
+   * Suspend status for active hooks.
+   *
+   * Indicates whether interactive mode is temporarily suspended.
+   * When suspended, external output can be written without interference.
+   */
+  get isSuspended() {
+    return this.#isSuspended;
+  }
+  /**
+   * Removes lines from the terminal output.
+   *
+   * Erases the specified number of lines from the bottom of the output,
+   * moving the cursor up and clearing the lines. Useful for removing
+   * previous interactive output before displaying new content.
+   * @param stream The stream to erase lines from ("stdout" or "stderr")
+   * @param count Number of lines to remove (defaults to lastLength)
+   * @throws {TypeError} If the specified stream is not available
+   */
+  erase(stream, count = this.#lastLength) {
+    if (this.#stream[stream] === void 0) {
+      throw new TypeError(`Stream "${stream}" is not available`);
+    }
+    this.#stream[stream].erase(count);
+  }
+  /**
+   * Hook stdout and stderr streams.
+   * @returns Success status
+   */
+  hook() {
+    if (!this.#isActive) {
+      Object.values(this.#stream).forEach((hook) => hook.active());
+      this.#clear(true);
+    }
+    return this.#isActive;
+  }
+  /**
+   * Resume suspend hooks.
+   * @param stream Stream to resume
+   * @param eraseRowCount erase output rows count
+   */
+  resume(stream, eraseRowCount) {
+    if (this.#isSuspended) {
+      this.#isSuspended = false;
+      if (eraseRowCount) {
+        this.erase(stream, eraseRowCount);
+      }
+      this.#lastLength = 0;
+      Object.values(this.#stream).forEach((hook) => hook.active());
+    }
+  }
+  /**
+   * Suspend active hooks for external output.
+   * @param stream Stream to suspend
+   * @param erase erase output
+   */
+  suspend(stream, erase = true) {
+    if (!this.#isSuspended) {
+      this.#isSuspended = true;
+      if (erase) {
+        this.erase(stream);
+      }
+      Object.values(this.#stream).forEach((hook) => hook.renew());
+    }
+  }
+  /**
+   * Unhooks both stdout and stderr streams and print their story of logs.
+   * @param separateHistory If `true`, will add an empty line to the history output for individual recorded lines and console logs
+   * @returns Success status
+   */
+  unhook(separateHistory = true) {
+    if (this.#isActive) {
+      Object.values(this.#stream).forEach((hook) => hook.inactive(separateHistory));
+      this.#clear();
+    }
+    return !this.#isActive;
+  }
+  /**
+   * Update output.
+   * @param stream Stream to write to
+   * @param rows Text lines to write to standard output
+   * @param from Index of the line starting from which the contents of the terminal are being overwritten
+   */
+  update(stream, rows, from = 0) {
+    if (rows.length > 0) {
+      if (this.#stream[stream] === void 0) {
+        throw new TypeError(`Stream "${stream}" is not available`);
+      }
+      const hook = this.#stream[stream];
+      const { columns: width, rows: height } = terminalSize();
+      const position = from > height ? height - 1 : Math.max(0, Math.min(height - 1, from));
+      const actualLength = this.lastLength - position;
+      const outside = Math.max(actualLength - height, this.outside);
+      let output = rows.reduce(
+        (accumulator, row) => [
+          ...accumulator,
+          wordWrap(row, {
+            trim: false,
+            width,
+            wrapMode: WrapMode.STRICT_WIDTH
+          })
+        ],
+        []
+      );
+      if (height <= actualLength) {
+        hook.erase(height);
+        if (position < outside) {
+          output = output.slice(outside - position + 1);
+        }
+      } else if (actualLength) {
+        hook.erase(actualLength);
+      }
+      hook.write(`${output.join("\n")}
+`);
+      this.#lastLength = outside ? outside + output.length + 1 : output.length;
+      this.#outside = Math.max(this.lastLength - height, this.outside);
+    }
+  }
+  #clear(status = false) {
+    this.#isActive = status;
+    this.#lastLength = 0;
+    this.#outside = 0;
+  }
+}
+
+export { InteractiveManager as default };

package/dist/packem_shared/InteractiveStreamHook-DiSubbJ1.js

@@ -0,0 +1,21 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+
+export { I as default } from './interactive-stream-hook-DG4BtN12.js';