lognal 0.1.0

package/dist/core/layout/row-index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Keeps the number of rows of every visible entry, and answers which entry a row belongs to.
+ *
+ * Appending an entry and dropping entries from the front are cheap, which is what a log does
+ * almost all the time. Changing row counts in the middle marks the running totals after the
+ * first change as stale, and they are recomputed once, the next time a position is read, so
+ * many changes in a row cost one pass.
+ */
+export declare class RowIndex {
+    private counts;
+    /** `sums[i]` is the number of rows before item `i`. It has one more element than `counts`. */
+    private sums;
+    private start;
+    /** The first element of `sums` that is out of date, or `Infinity` when all are current. */
+    private staleFrom;
+    /** The number of items. */
+    get length(): number;
+    /** The number of rows of all items. */
+    get total(): number;
+    push(rows: number): void;
+    /** Removes items from the front. */
+    shift(count: number): void;
+    clear(): void;
+    /** Returns the number of rows of an item. */
+    get(index: number): number;
+    /** Changes the number of rows of an item. */
+    set(index: number, rows: number): void;
+    /** Returns the first row of an item. */
+    rowOf(index: number): number;
+    /** Returns the item that holds a row, or -1 when the row is past the end. */
+    find(row: number): number;
+    private refresh;
+}

package/dist/core/layout/row-index.js

@@ -0,0 +1,99 @@
+/** How many removed items the index tolerates at the front before it compacts its arrays. */
+const COMPACT_THRESHOLD = 4096;
+/**
+ * Keeps the number of rows of every visible entry, and answers which entry a row belongs to.
+ *
+ * Appending an entry and dropping entries from the front are cheap, which is what a log does
+ * almost all the time. Changing row counts in the middle marks the running totals after the
+ * first change as stale, and they are recomputed once, the next time a position is read, so
+ * many changes in a row cost one pass.
+ */
+export class RowIndex {
+    counts = [];
+    /** `sums[i]` is the number of rows before item `i`. It has one more element than `counts`. */
+    sums = [0];
+    start = 0;
+    /** The first element of `sums` that is out of date, or `Infinity` when all are current. */
+    staleFrom = Number.POSITIVE_INFINITY;
+    /** The number of items. */
+    get length() {
+        return this.counts.length - this.start;
+    }
+    /** The number of rows of all items. */
+    get total() {
+        this.refresh();
+        return this.sums[this.counts.length] - this.sums[this.start];
+    }
+    push(rows) {
+        this.refresh();
+        this.counts.push(rows);
+        this.sums.push(this.sums[this.sums.length - 1] + rows);
+    }
+    /** Removes items from the front. */
+    shift(count) {
+        this.refresh();
+        this.start = Math.min(this.counts.length, this.start + count);
+        if (this.start > COMPACT_THRESHOLD && this.start > this.counts.length / 2) {
+            const base = this.sums[this.start];
+            this.counts = this.counts.slice(this.start);
+            this.sums = this.sums.slice(this.start).map((sum) => sum - base);
+            this.start = 0;
+        }
+    }
+    clear() {
+        this.counts = [];
+        this.sums = [0];
+        this.start = 0;
+        this.staleFrom = Number.POSITIVE_INFINITY;
+    }
+    /** Returns the number of rows of an item. */
+    get(index) {
+        return this.counts[this.start + index] ?? 0;
+    }
+    /** Changes the number of rows of an item. */
+    set(index, rows) {
+        const position = this.start + index;
+        if (this.counts[position] === rows) {
+            return;
+        }
+        this.counts[position] = rows;
+        this.staleFrom = Math.min(this.staleFrom, position + 1);
+    }
+    /** Returns the first row of an item. */
+    rowOf(index) {
+        this.refresh();
+        return this.sums[this.start + index] - this.sums[this.start];
+    }
+    /** Returns the item that holds a row, or -1 when the row is past the end. */
+    find(row) {
+        if (row < 0 || row >= this.total) {
+            return -1;
+        }
+        const target = row + this.sums[this.start];
+        let low = this.start;
+        let high = this.counts.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if (this.sums[middle] <= target) {
+                low = middle;
+            }
+            else {
+                high = middle - 1;
+            }
+        }
+        // Skip items with no rows, which share their first row with the next item.
+        while (low < this.counts.length - 1 && this.counts[low] === 0) {
+            low++;
+        }
+        return low - this.start;
+    }
+    refresh() {
+        if (this.staleFrom === Number.POSITIVE_INFINITY) {
+            return;
+        }
+        for (let index = this.staleFrom; index < this.sums.length; index++) {
+            this.sums[index] = this.sums[index - 1] + this.counts[index - 1];
+        }
+        this.staleFrom = Number.POSITIVE_INFINITY;
+    }
+}

package/dist/core/layout/types.d.ts

@@ -0,0 +1,128 @@
+import type { LogEntry, StyleToken, TextStyle } from '../types.js';
+/** What happens when a span is clicked. */
+export type LineAction = {
+    type: 'toggle-value';
+    path: string;
+} | {
+    type: 'toggle-group';
+};
+/** A run of text on a logical line. */
+export interface LineTextSpan {
+    text: string;
+    token?: StyleToken;
+    style?: TextStyle;
+    action?: LineAction;
+}
+/** A small drawn symbol that takes two cells, such as the triangle that expands a value. */
+export interface LineIconSpan {
+    icon: 'expander';
+    expanded: boolean;
+    action: LineAction;
+}
+export type LineSpan = LineTextSpan | LineIconSpan;
+/**
+ * One line of an entry before wrapping. An entry has one logical line per line of text, plus
+ * one for every visible row of an expanded value.
+ */
+export interface LogicalLine {
+    /** Cells of indentation before the content, repeated on every wrapped row. */
+    indent: number;
+    spans: LineSpan[];
+    /** `false` when the line holds a text part that must not wrap. */
+    wrap?: boolean;
+}
+/** How a cluster lets a wrapped row break next to it. */
+export declare const BREAK_NORMAL = 0;
+/** A space: a row may break after it. */
+export declare const BREAK_SPACE = 1;
+/** A wide character that allows breaks on both sides, such as a Han ideograph. */
+export declare const BREAK_WIDE = 2;
+/** A wide character that keeps words together, such as a Hangul syllable. */
+export declare const BREAK_KEEP = 3;
+/** A span after control characters and tabs were replaced for display. */
+export interface ShapedSpan {
+    text: string;
+    token?: StyleToken;
+    style?: TextStyle;
+    action?: LineAction;
+    icon?: 'expander';
+    expanded?: boolean;
+}
+/**
+ * A logical line split into grapheme clusters, each with its width in cells.
+ *
+ * Most log lines are plain ASCII. Such a line is kept as `text`, where every character is one
+ * cluster one cell wide, and the per-cluster arrays are left out to save memory.
+ */
+export interface ShapedLine {
+    indent: number;
+    spans: ShapedSpan[];
+    /** The index of the first cluster of every span. */
+    spanStarts: Uint32Array;
+    /** Whether every cluster is a single printable ASCII character. */
+    simple: boolean;
+    /** The whole line. For a simple line, character `i` is cluster `i`. */
+    text: string;
+    /** The clusters of a line that is not simple. */
+    clusters: string[] | null;
+    /** The width of every cluster of a line that is not simple. */
+    widths: Uint8Array | null;
+    /** One of the `BREAK_*` values for every cluster of a line that is not simple. */
+    breaks: Uint8Array | null;
+    /** The number of clusters. */
+    length: number;
+    /** Total width in cells, without the indentation. */
+    cells: number;
+    /** Whether the line may wrap. A line that holds a part with `wrap: false` never does. */
+    wrap: boolean;
+}
+/** How long lines are handled. */
+export type WrapMode = 'word' | 'char' | 'none';
+/** A run of clusters on one visual row that share a span. */
+export interface RowRun {
+    /** Column where the run starts, counted from the start of the content area. */
+    column: number;
+    /** Width in cells. */
+    cells: number;
+    /** The text of the run. */
+    text: string;
+    /** The clusters of the run, for runs that must be drawn one cluster at a time. */
+    clusters: string[];
+    /** The width of every cluster in `clusters`. */
+    widths: number[];
+    /** Whether the run is plain ASCII that can be drawn in one call. */
+    simple: boolean;
+    token?: StyleToken;
+    style?: TextStyle;
+    action?: LineAction;
+    icon?: 'expander';
+    expanded?: boolean;
+}
+/** One row of the screen. */
+export interface VisualRow {
+    entry: LogEntry;
+    /** Index of the logical line within the entry. */
+    line: number;
+    /** Index of the row within the logical line. */
+    lineRow: number;
+    /** Index of the row within the entry. */
+    entryRow: number;
+    /** Whether this is the first row of the entry. */
+    first: boolean;
+    /** Whether this is the last row of the entry. */
+    last: boolean;
+    /** Cells of indentation before the first run. */
+    indent: number;
+    /** Cell offset of the row's first cluster within the logical line, without indentation. */
+    startCell: number;
+    /** Width of the row's content in cells, without indentation. */
+    cells: number;
+    runs: RowRun[];
+}
+/** A position in the text of an entry, stable across wrapping. */
+export interface TextPosition {
+    entryId: number;
+    line: number;
+    /** Cell offset within the logical line, without indentation. */
+    cell: number;
+}

package/dist/core/layout/types.js

@@ -0,0 +1,8 @@
+/** How a cluster lets a wrapped row break next to it. */
+export const BREAK_NORMAL = 0;
+/** A space: a row may break after it. */
+export const BREAK_SPACE = 1;
+/** A wide character that allows breaks on both sides, such as a Han ideograph. */
+export const BREAK_WIDE = 2;
+/** A wide character that keeps words together, such as a Hangul syllable. */
+export const BREAK_KEEP = 3;

package/dist/core/store.d.ts

@@ -0,0 +1,96 @@
+import { AnsiParser } from './text/ansi.js';
+import type { LogEntry, LogEntryInit, LogKind, LogLevel, StyleToken, TextStyle } from './types.js';
+export interface LogStoreOptions {
+    /**
+     * The most entries the store keeps. Once it is full, the oldest entry is dropped for every
+     * new one. Use `Infinity` to keep everything.
+     */
+    maxEntries: number;
+    /**
+     * Whether a message identical to the one before it increases that entry's repeat count
+     * instead of adding a new entry. Only entries of the `message` kind are merged, and only when
+     * every part is text or a value that cannot be expanded; an error is never merged.
+     */
+    mergeRepeats: boolean;
+}
+export declare const DEFAULT_STORE_OPTIONS: LogStoreOptions;
+/** A change to the contents of a store. */
+export type StoreChange = {
+    type: 'append';
+    entries: readonly LogEntry[];
+} | {
+    type: 'update';
+    entry: LogEntry;
+} | {
+    type: 'trim';
+    count: number;
+} | {
+    type: 'clear';
+};
+export type StoreListener = (change: StoreChange) => void;
+/** Options for adding plain text. */
+export interface WriteOptions {
+    level?: LogLevel;
+    kind?: LogKind;
+    time?: number;
+    groups?: readonly number[];
+    token?: StyleToken;
+    style?: TextStyle;
+    /** Set to `false` to keep every line on one row, for text such as a table. */
+    wrap?: boolean;
+    /**
+     * Whether ANSI escape codes in the text are turned into styles. Pass a parser to keep the
+     * style running across several calls. Defaults to `false`.
+     */
+    ansi?: boolean | AnsiParser;
+}
+/**
+ * Holds log entries in the order they were added.
+ *
+ * The store knows nothing about how entries are displayed, so one store can feed several
+ * viewers, or collect messages before any viewer exists.
+ */
+export declare class LogStore {
+    private options;
+    private items;
+    private start;
+    private nextId;
+    private oldestId;
+    private lastSignature;
+    private readonly listeners;
+    constructor(options?: Partial<LogStoreOptions>);
+    /** The number of entries held. */
+    get size(): number;
+    /** The id of the oldest entry held. When the store is empty, the id the next entry gets. */
+    get firstId(): number;
+    /** The id of the newest entry held, or `firstId - 1` when the store is empty. */
+    get lastId(): number;
+    getOptions(): Readonly<LogStoreOptions>;
+    setOptions(options: Partial<LogStoreOptions>): void;
+    /** Returns the entry at a position, where 0 is the oldest entry held. */
+    at(index: number): LogEntry | undefined;
+    /** Returns the entry with an id, if the store still holds it. */
+    get(id: number): LogEntry | undefined;
+    /** Returns every entry, oldest first. */
+    toArray(): LogEntry[];
+    [Symbol.iterator](): Iterator<LogEntry>;
+    /**
+     * Adds one entry or several, and returns the entries that were created. A message merged into
+     * the entry before it only raises that entry's `repeat` count and is not returned.
+     */
+    append(init: LogEntryInit | readonly LogEntryInit[]): LogEntry[];
+    /** Adds text as one entry. Line breaks stay inside the entry. */
+    write(text: string, options?: WriteOptions): LogEntry | undefined;
+    /** Adds text as one entry per line. */
+    writeLines(text: string, options?: WriteOptions): LogEntry[];
+    /** Removes every entry. */
+    clear(): void;
+    /** Collapses or expands a group header and hides or shows its members. */
+    setCollapsed(id: number, collapsed: boolean): void;
+    /** Calls a listener for every change. Returns a function that removes the listener. */
+    subscribe(listener: StoreListener): () => void;
+    private initOf;
+    private textParts;
+    private trimToLimit;
+    private emit;
+}

package/dist/core/store.js

@@ -0,0 +1,204 @@
+import { AnsiParser } from './text/ansi.js';
+import { splitLines } from './text/line-splitter.js';
+export const DEFAULT_STORE_OPTIONS = {
+    maxEntries: 10000,
+    mergeRepeats: true
+};
+/** How many dropped slots the store tolerates before it compacts its array. */
+const COMPACT_THRESHOLD = 4096;
+const MERGE_SEPARATOR = String.fromCharCode(0);
+/** Returns a string that is equal for two messages that should be merged, or `null`. */
+const signatureOf = (init, level, kind) => {
+    if (kind !== 'message') {
+        return null;
+    }
+    const pieces = [level, (init.groups ?? []).join(',')];
+    for (const part of init.parts) {
+        if (part.type === 'text') {
+            pieces.push(`t${part.wrap === false ? 'n' : ''}${part.text}${part.token ?? ''}${part.style ? JSON.stringify(part.style) : ''}`);
+            continue;
+        }
+        const { value } = part;
+        if (value.children !== undefined || value.kind === 'error') {
+            return null;
+        }
+        pieces.push(`v${value.kind}:${value.value ?? ''}:${value.className ?? ''}`);
+    }
+    return pieces.join(MERGE_SEPARATOR);
+};
+/**
+ * Holds log entries in the order they were added.
+ *
+ * The store knows nothing about how entries are displayed, so one store can feed several
+ * viewers, or collect messages before any viewer exists.
+ */
+export class LogStore {
+    options;
+    items = [];
+    start = 0;
+    nextId = 1;
+    oldestId = 1;
+    lastSignature = null;
+    listeners = new Set();
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_STORE_OPTIONS, ...options };
+    }
+    /** The number of entries held. */
+    get size() {
+        return this.items.length - this.start;
+    }
+    /** The id of the oldest entry held. When the store is empty, the id the next entry gets. */
+    get firstId() {
+        return this.oldestId;
+    }
+    /** The id of the newest entry held, or `firstId - 1` when the store is empty. */
+    get lastId() {
+        return this.nextId - 1;
+    }
+    getOptions() {
+        return this.options;
+    }
+    setOptions(options) {
+        this.options = { ...this.options, ...options };
+        this.trimToLimit();
+    }
+    /** Returns the entry at a position, where 0 is the oldest entry held. */
+    at(index) {
+        if (index < 0 || index >= this.size) {
+            return undefined;
+        }
+        return this.items[this.start + index];
+    }
+    /** Returns the entry with an id, if the store still holds it. */
+    get(id) {
+        return this.at(id - this.oldestId);
+    }
+    /** Returns every entry, oldest first. */
+    toArray() {
+        return this.items.slice(this.start);
+    }
+    [Symbol.iterator]() {
+        return this.toArray()[Symbol.iterator]();
+    }
+    /**
+     * Adds one entry or several, and returns the entries that were created. A message merged into
+     * the entry before it only raises that entry's `repeat` count and is not returned.
+     */
+    append(init) {
+        const inits = Array.isArray(init) ? init : [init];
+        const created = [];
+        for (const item of inits) {
+            const level = item.level ?? 'log';
+            const kind = item.kind ?? 'message';
+            const signature = this.options.mergeRepeats ? signatureOf(item, level, kind) : null;
+            const last = this.at(this.size - 1);
+            if (signature !== null && last && signature === this.lastSignature) {
+                last.repeat++;
+                last.version++;
+                this.emit({ type: 'update', entry: last });
+                continue;
+            }
+            const entry = {
+                id: this.nextId++,
+                time: item.time ?? Date.now(),
+                level,
+                kind,
+                parts: item.parts,
+                groups: item.groups ?? [],
+                collapsed: item.collapsed ?? false,
+                repeat: 1,
+                version: 0
+            };
+            this.items.push(entry);
+            this.lastSignature = signature;
+            created.push(entry);
+        }
+        if (created.length > 0) {
+            this.emit({ type: 'append', entries: created });
+            this.trimToLimit();
+        }
+        return created;
+    }
+    /** Adds text as one entry. Line breaks stay inside the entry. */
+    write(text, options = {}) {
+        const parts = this.textParts(text, options);
+        return this.append({ ...this.initOf(options), parts })[0] ?? this.at(this.size - 1);
+    }
+    /** Adds text as one entry per line. */
+    writeLines(text, options = {}) {
+        const parser = options.ansi instanceof AnsiParser ? options.ansi : options.ansi ? new AnsiParser() : null;
+        const base = this.initOf(options);
+        return this.append(splitLines(text).map((line) => ({
+            ...base,
+            parts: this.textParts(line, { ...options, ansi: parser ?? false })
+        })));
+    }
+    /** Removes every entry. */
+    clear() {
+        this.items = [];
+        this.start = 0;
+        this.oldestId = this.nextId;
+        this.lastSignature = null;
+        this.emit({ type: 'clear' });
+    }
+    /** Collapses or expands a group header and hides or shows its members. */
+    setCollapsed(id, collapsed) {
+        const entry = this.get(id);
+        if (!entry || entry.collapsed === collapsed) {
+            return;
+        }
+        entry.collapsed = collapsed;
+        entry.version++;
+        this.emit({ type: 'update', entry });
+    }
+    /** Calls a listener for every change. Returns a function that removes the listener. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    initOf(options) {
+        return { level: options.level, kind: options.kind, time: options.time, groups: options.groups };
+    }
+    textParts(text, options) {
+        if (options.ansi) {
+            const parser = options.ansi instanceof AnsiParser ? options.ansi : new AnsiParser();
+            return parser.parse(text).map((part) => ({
+                ...part,
+                token: part.token ?? options.token,
+                ...(options.wrap === false ? { wrap: false } : {})
+            }));
+        }
+        return [
+            {
+                type: 'text',
+                text,
+                token: options.token,
+                style: options.style,
+                ...(options.wrap === false ? { wrap: false } : {})
+            }
+        ];
+    }
+    trimToLimit() {
+        const excess = this.size - this.options.maxEntries;
+        if (!(excess > 0)) {
+            return;
+        }
+        this.start += excess;
+        this.oldestId += excess;
+        if (this.start > COMPACT_THRESHOLD && this.start > this.items.length / 2) {
+            this.items = this.items.slice(this.start);
+            this.start = 0;
+        }
+        if (this.size === 0) {
+            this.lastSignature = null;
+        }
+        this.emit({ type: 'trim', count: excess });
+    }
+    emit(change) {
+        for (const listener of this.listeners) {
+            listener(change);
+        }
+    }
+}

package/dist/core/text/ansi.d.ts

@@ -0,0 +1,20 @@
+import type { TextPart } from '../types.js';
+/**
+ * Turns text with ANSI escape codes into styled parts.
+ *
+ * Select Graphic Rendition codes (colors, bold, italic, underline and so on) become styles.
+ * Every other escape sequence, such as cursor movement or an OSC hyperlink wrapper, is removed
+ * so it cannot show up as stray characters. The style carries over between calls, the way a
+ * terminal keeps it from one line to the next.
+ */
+export declare class AnsiParser {
+    private style;
+    /** Parses one piece of text, usually a line. */
+    parse(text: string): TextPart[];
+    /** Forgets the current style. */
+    reset(): void;
+    private createPart;
+    private applySgr;
+}
+/** Removes every ANSI escape sequence from text. */
+export declare const stripAnsi: (text: string) => string;