lognal 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Data types shared by every part of lognal.
+ *
+ * Everything under `src/core` is plain data and logic with no dependency on the DOM or on a
+ * JavaScript-only API, so that it can be ported to other runtimes, such as Dart. Platform
+ * features the core needs, such as grapheme segmentation, are passed in rather than imported.
+ */
+/** Severity of an entry, from least to most severe. */
+export type LogLevel = 'debug' | 'log' | 'info' | 'warn' | 'error';
+/** Every level, ordered from least to most severe. */
+export declare const LOG_LEVELS: readonly LogLevel[];
+/**
+ * What an entry represents. The viewer marks each kind differently.
+ *
+ * - `message`: a regular log message.
+ * - `input`: a command the user typed into the input line.
+ * - `output`: the reply to a command.
+ * - `group`: the header of a group started with `console.group`.
+ * - `system`: a notice from the viewer itself, such as "Console was cleared".
+ */
+export type LogKind = 'message' | 'input' | 'output' | 'group' | 'system';
+/** Semantic colors, resolved by the renderer from the theme. */
+export type StyleToken = 'default' | 'muted' | 'string' | 'number' | 'boolean' | 'null' | 'key' | 'symbol' | 'function' | 'regexp' | 'date' | 'tag' | 'attribute' | 'error' | 'warn' | 'info' | 'accent';
+/**
+ * A color given directly rather than through a token.
+ *
+ * A number from 0 to 255 is an index into the ANSI palette; 0 to 15 follow the theme. A string
+ * is a CSS color such as `#ff0000` or `rgb(255 0 0)`.
+ */
+export type TextColor = number | string;
+/** Explicit styling, from `%c` in a console message or from ANSI escape codes. */
+export interface TextStyle {
+    color?: TextColor;
+    background?: TextColor;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}
+/** A run of text with one style. */
+export interface TextPart {
+    type: 'text';
+    text: string;
+    token?: StyleToken;
+    style?: TextStyle;
+    /**
+     * Set to `false` to keep every line of this part on one row, for text whose layout matters,
+     * such as a table. A line wider than the viewer then scrolls sideways instead of wrapping.
+     */
+    wrap?: boolean;
+}
+/** A captured value, displayed with type-aware formatting. */
+export interface ValuePart {
+    type: 'value';
+    value: ValueNode;
+}
+/** One piece of an entry's content. Parts are displayed one after another. */
+export type LogPart = TextPart | ValuePart;
+/** The kinds of value a snapshot can hold. */
+export type ValueKind = 'undefined' | 'null' | 'boolean' | 'number' | 'bigint' | 'string' | 'symbol' | 'function' | 'class' | 'date' | 'regexp' | 'error' | 'array' | 'object' | 'map' | 'set' | 'weak' | 'promise' | 'element' | 'text' | 'circular' | 'accessor';
+/**
+ * A snapshot of a value, taken when it was logged.
+ *
+ * The tree is plain data, so it can be passed through `postMessage` or saved as JSON. It never
+ * holds a reference to the original value.
+ */
+export interface ValueNode {
+    kind: ValueKind;
+    /**
+     * The text of a leaf value: the string itself, a number as text, a function name, a date in
+     * ISO format, a regular expression literal, an error message, or an element's tag name.
+     */
+    value?: string;
+    /** The constructor name of an object, such as `Map` or `User`. */
+    className?: string;
+    /** The length of an array or string, or the size of a map or set. */
+    size?: number;
+    /**
+     * The captured children of an object, array, map, set, error or element. `undefined` means
+     * the value has children that were not captured because the depth limit was reached.
+     */
+    children?: ValueEntry[];
+    /** How many children exist but were left out because of a limit. */
+    omitted?: number;
+    /** How many characters were cut from a long string. */
+    truncated?: number;
+    /** The stack trace of an error, without its first line. */
+    stack?: string;
+    /** The attributes of an element, as name and value pairs. */
+    attributes?: [string, string][];
+    /** For an accessor property, which parts are defined. */
+    accessor?: 'get' | 'set' | 'get-set';
+}
+/** A child of a value: a property, an array item, a map entry or a child node. */
+export interface ValueEntry {
+    /** The property name or index. Absent for set items and child nodes. */
+    key?: string;
+    /** How the key is displayed. */
+    keyKind?: 'property' | 'index' | 'symbol' | 'internal';
+    /** The key of a map entry. */
+    keyValue?: ValueNode;
+    value: ValueNode;
+}
+/** The fields a caller provides when adding an entry. */
+export interface LogEntryInit {
+    parts: LogPart[];
+    level?: LogLevel;
+    kind?: LogKind;
+    /** Epoch milliseconds. Defaults to the time the entry is added. */
+    time?: number;
+    /** Ids of the open groups this entry belongs to, outermost first. */
+    groups?: readonly number[];
+    /** For a group header, whether the group starts collapsed. */
+    collapsed?: boolean;
+}
+/** An entry held by a store. */
+export interface LogEntry {
+    readonly id: number;
+    readonly time: number;
+    readonly level: LogLevel;
+    readonly kind: LogKind;
+    readonly parts: readonly LogPart[];
+    readonly groups: readonly number[];
+    /** For a group header, whether its members are hidden. */
+    collapsed: boolean;
+    /** How many identical consecutive messages this entry stands for. */
+    repeat: number;
+    /** Increases whenever `collapsed` or `repeat` changes, so cached layouts can be refreshed. */
+    version: number;
+}

package/dist/core/types.js

@@ -0,0 +1,9 @@
+/**
+ * Data types shared by every part of lognal.
+ *
+ * Everything under `src/core` is plain data and logic with no dependency on the DOM or on a
+ * JavaScript-only API, so that it can be ported to other runtimes, such as Dart. Platform
+ * features the core needs, such as grapheme segmentation, are passed in rather than imported.
+ */
+/** Every level, ordered from least to most severe. */
+export const LOG_LEVELS = ['debug', 'log', 'info', 'warn', 'error'];

package/dist/core/value/preview.d.ts

@@ -0,0 +1,16 @@
+import type { LineTextSpan } from '../layout/types.js';
+import type { ValueEntry, ValueNode } from '../types.js';
+/** The most cells a one-line preview of an object, array, map or set takes before it is cut. */
+export declare const PREVIEW_CELLS = 100;
+/** Returns whether a value can be expanded to show its children. */
+export declare const isExpandable: (node: ValueNode) => boolean;
+/** Formats a property key the way it would be written in an object literal. */
+export declare const formatKey: (entry: ValueEntry) => LineTextSpan;
+/** `TypeError: message`, or just the name when there is no message. */
+export declare const errorTitle: (node: ValueNode) => string;
+/**
+ * Returns a one-line preview of a value, such as `{id: 1, name: 'lognal'}` or
+ * `(3) [1, 2, 3]`. Objects inside the preview are shown by name only, and the preview is cut
+ * with `…` once it passes `PREVIEW_CELLS`.
+ */
+export declare const previewValue: (node: ValueNode, nested?: boolean) => LineTextSpan[];

package/dist/core/value/preview.js

@@ -0,0 +1,207 @@
+/** The most cells a one-line preview of an object, array, map or set takes before it is cut. */
+export const PREVIEW_CELLS = 100;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** Returns whether a value can be expanded to show its children. */
+export const isExpandable = (node) => {
+    if (node.kind === 'error') {
+        return Boolean(node.stack) || (node.children?.length ?? 0) > 0;
+    }
+    if (node.kind !== 'object' &&
+        node.kind !== 'array' &&
+        node.kind !== 'map' &&
+        node.kind !== 'set' &&
+        node.kind !== 'element') {
+        return false;
+    }
+    return node.children !== undefined && (node.children.length > 0 || (node.omitted ?? 0) > 0);
+};
+const quote = (text) => {
+    const escaped = text
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    return `'${escaped}'`;
+};
+/** The longest string shown in full inside another value's preview. */
+const NESTED_STRING_LENGTH = 50;
+const stringText = (node, nested = false) => {
+    const value = node.value ?? '';
+    if (nested && value.length > NESTED_STRING_LENGTH) {
+        return `${quote(value.slice(0, NESTED_STRING_LENGTH))}…`;
+    }
+    return `${quote(value)}${node.truncated ? '…' : ''}`;
+};
+/** Formats a property key the way it would be written in an object literal. */
+export const formatKey = (entry) => {
+    const key = entry.key ?? '';
+    if (entry.keyKind === 'symbol') {
+        return { text: key, token: 'symbol' };
+    }
+    if (entry.keyKind === 'internal') {
+        return { text: key, token: 'muted' };
+    }
+    if (entry.keyKind === 'index' || IDENTIFIER.test(key)) {
+        return { text: key, token: 'key' };
+    }
+    return { text: quote(key), token: 'key' };
+};
+/** The name shown before an object's contents, such as `User` or `Map(2)`. */
+const labelOf = (node) => {
+    const size = node.size ?? node.children?.length ?? 0;
+    switch (node.kind) {
+        case 'array':
+            return node.className && node.className !== 'Array'
+                ? `${node.className}(${size})`
+                : `(${size})`;
+        case 'map':
+        case 'set':
+            return `${node.className ?? (node.kind === 'map' ? 'Map' : 'Set')}(${size})`;
+        case 'object':
+            return node.className && node.className !== 'Object' ? node.className : '';
+        default:
+            return node.className ?? '';
+    }
+};
+/** A short name for a nested object, used inside another preview. */
+const shortLabel = (node) => {
+    const size = node.size ?? node.children?.length ?? 0;
+    switch (node.kind) {
+        case 'array':
+            return `${node.className && node.className !== 'Array' ? node.className : 'Array'}(${size})`;
+        case 'map':
+        case 'set':
+            return labelOf(node);
+        case 'object':
+            return node.className && node.className !== 'Object' ? node.className : '{…}';
+        default:
+            return node.className ?? '';
+    }
+};
+const elementText = (node, withAttributes) => {
+    const tag = node.value ?? 'element';
+    if (!withAttributes || !node.attributes?.length) {
+        return `<${tag}>`;
+    }
+    const attributes = node.attributes
+        .map(([name, value]) => (value === '' ? name : `${name}="${value}"`))
+        .join(' ');
+    return `<${tag} ${attributes}>`;
+};
+/** Spans for a leaf value, or a short label for a container nested inside a preview. */
+const leafSpans = (node, nested) => {
+    switch (node.kind) {
+        case 'undefined':
+            return [{ text: 'undefined', token: 'null' }];
+        case 'null':
+            return [{ text: 'null', token: 'null' }];
+        case 'boolean':
+            return [{ text: node.value ?? 'false', token: 'boolean' }];
+        case 'number':
+            return [{ text: node.value ?? 'NaN', token: 'number' }];
+        case 'bigint':
+            return [{ text: `${node.value ?? '0'}n`, token: 'number' }];
+        case 'string':
+            return [{ text: stringText(node, nested), token: 'string' }];
+        case 'symbol':
+            return [{ text: node.value ?? 'Symbol()', token: 'symbol' }];
+        case 'function':
+            return [
+                { text: 'ƒ ', token: 'function' },
+                { text: `${node.value ?? ''}()`, token: 'default' }
+            ];
+        case 'class':
+            return [
+                { text: 'class ', token: 'function' },
+                { text: node.value ?? '', token: 'default' }
+            ];
+        case 'date':
+            return [{ text: node.value ?? 'Invalid Date', token: 'date' }];
+        case 'regexp':
+            return [{ text: node.value ?? '/(?:)/', token: 'regexp' }];
+        case 'error':
+            return [{ text: errorTitle(node), token: 'error' }];
+        case 'weak':
+            return [{ text: node.className ?? 'WeakMap', token: 'default' }];
+        case 'promise':
+            return [{ text: node.className ?? 'Promise', token: 'default' }];
+        case 'element':
+            return [{ text: elementText(node, !nested), token: 'tag' }];
+        case 'text':
+            return [{ text: stringText(node), token: 'string' }];
+        case 'circular':
+            return [{ text: '[Circular]', token: 'muted' }];
+        case 'accessor':
+            return [
+                {
+                    text: node.accessor === 'set'
+                        ? '[Setter]'
+                        : node.accessor === 'get-set'
+                            ? '[Getter/Setter]'
+                            : '[Getter]',
+                    token: 'muted'
+                }
+            ];
+        default:
+            return [{ text: shortLabel(node), token: 'default' }];
+    }
+};
+/** `TypeError: message`, or just the name when there is no message. */
+export const errorTitle = (node) => {
+    const name = node.className ?? 'Error';
+    return node.value ? `${name}: ${node.value}` : name;
+};
+const isContainer = (node) => {
+    return (node.kind === 'object' || node.kind === 'array' || node.kind === 'map' || node.kind === 'set');
+};
+const measure = (spans) => {
+    let cells = 0;
+    for (const span of spans) {
+        cells += span.text.length;
+    }
+    return cells;
+};
+/**
+ * Returns a one-line preview of a value, such as `{id: 1, name: 'lognal'}` or
+ * `(3) [1, 2, 3]`. Objects inside the preview are shown by name only, and the preview is cut
+ * with `…` once it passes `PREVIEW_CELLS`.
+ */
+export const previewValue = (node, nested = false) => {
+    if (!isContainer(node) || nested) {
+        return leafSpans(node, nested);
+    }
+    const label = labelOf(node);
+    const spans = [];
+    if (label) {
+        spans.push({ text: `${label} `, token: node.kind === 'object' ? 'default' : 'muted' });
+    }
+    if (node.children === undefined) {
+        spans.push({ text: node.kind === 'array' ? '[…]' : '{…}', token: 'default' });
+        return spans;
+    }
+    const isArray = node.kind === 'array';
+    spans.push({ text: isArray ? '[' : '{', token: 'default' });
+    let shown = 0;
+    for (const child of node.children) {
+        if (measure(spans) > PREVIEW_CELLS) {
+            break;
+        }
+        if (shown > 0) {
+            spans.push({ text: ', ', token: 'default' });
+        }
+        if (node.kind === 'map' && child.keyValue) {
+            spans.push(...leafSpans(child.keyValue, true), { text: ' => ', token: 'default' });
+        }
+        else if (!isArray && node.kind !== 'set' && child.key !== undefined) {
+            spans.push(formatKey(child), { text: ': ', token: 'default' });
+        }
+        spans.push(...leafSpans(child.value, true));
+        shown++;
+    }
+    if (shown < node.children.length || (node.omitted ?? 0) > 0) {
+        spans.push({ text: shown > 0 ? ', …' : '…', token: 'muted' });
+    }
+    spans.push({ text: isArray ? ']' : '}', token: 'default' });
+    return spans;
+};

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export type { LogEntry, LogEntryInit, LogKind, LogLevel, LogPart, StyleToken, TextColor, TextPart, TextStyle, ValueEntry, ValueKind, ValueNode, ValuePart } from './core/types.js';
+export { LOG_LEVELS } from './core/types.js';
+export { DEFAULT_STORE_OPTIONS, LogStore, type LogStoreOptions, type StoreChange, type StoreListener, type WriteOptions } from './core/store.js';
+export { compileFilter, entrySearchText, type CompiledFilter, type LogFilter } from './core/filter.js';
+export { DEFAULT_LAYOUT_OPTIONS, LogLayout, type LayoutOptions } from './core/layout/layout.js';
+export type { LineAction, LineIconSpan, LineSpan, LineTextSpan, LogicalLine, RowRun, TextPosition, VisualRow, WrapMode } from './core/layout/types.js';
+export { formatTimestamp, type TimestampFormat } from './core/time.js';
+export { AnsiParser, stripAnsi } from './core/text/ansi.js';
+export { LineSplitter, splitLines } from './core/text/line-splitter.js';
+export { measureCells, truncateCells } from './core/text/measure.js';
+export { setGraphemeSplitter, splitGraphemes, type GraphemeSplitter } from './core/text/graphemes.js';
+export { clusterWidth, codePointWidth, type AmbiguousWidth } from './core/text/width.js';
+export { UNICODE_VERSION } from './core/text/unicode-width-data.js';
+export { previewValue } from './core/value/preview.js';
+export { CONSOLE_METHODS, ConsoleRecorder, type ConsoleMethod, type RecorderOptions } from './sources/console/recorder.js';
+export { createConsole, hookConsole, type HookConsoleOptions, type LognalConsole } from './sources/console/hook.js';
+export { applyFormat, formatArguments, parseConsoleCss, type ValueCapture } from './sources/console/format.js';
+export { DEFAULT_CAPTURE_OPTIONS, snapshotValue, type CaptureOptions } from './sources/console/snapshot.js';
+export { detectEncoding, legacyEncodingFor } from './sources/text/encoding.js';
+export { readTextFile, TextLineWriter, type ReadTextOptions, type ReadTextResult } from './sources/text/read-file.js';
+export { followTextFile, type FileHandleLike, type FollowHandle, type FollowTextOptions } from './sources/text/follow-file.js';
+export type { CellMetrics, FontSettings, RenderFrame, RenderTheme, Renderer, RowDecoration } from './renderer/types.js';
+export { CanvasRenderer } from './renderer/canvas/canvas-renderer.js';
+export { DEFAULT_RENDER_THEME } from './renderer/theme.js';
+export { LogViewer, type CoreOptions, type InputOptions, type LogViewerEvents, type LogViewerOptions, type ToolbarOptions } from './viewer/viewer.js';
+export { EN_LABELS, KO_LABELS, labelsFor, type ViewerLabels } from './viewer/labels.js';
+export { DEFAULT_FONT, readFont, readTheme, type ThemeMode } from './viewer/theme.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+export { LOG_LEVELS } from './core/types.js';
+export { DEFAULT_STORE_OPTIONS, LogStore } from './core/store.js';
+export { compileFilter, entrySearchText } from './core/filter.js';
+export { DEFAULT_LAYOUT_OPTIONS, LogLayout } from './core/layout/layout.js';
+export { formatTimestamp } from './core/time.js';
+export { AnsiParser, stripAnsi } from './core/text/ansi.js';
+export { LineSplitter, splitLines } from './core/text/line-splitter.js';
+export { measureCells, truncateCells } from './core/text/measure.js';
+export { setGraphemeSplitter, splitGraphemes } from './core/text/graphemes.js';
+export { clusterWidth, codePointWidth } from './core/text/width.js';
+export { UNICODE_VERSION } from './core/text/unicode-width-data.js';
+export { previewValue } from './core/value/preview.js';
+export { CONSOLE_METHODS, ConsoleRecorder } from './sources/console/recorder.js';
+export { createConsole, hookConsole } from './sources/console/hook.js';
+export { applyFormat, formatArguments, parseConsoleCss } from './sources/console/format.js';
+export { DEFAULT_CAPTURE_OPTIONS, snapshotValue } from './sources/console/snapshot.js';
+export { detectEncoding, legacyEncodingFor } from './sources/text/encoding.js';
+export { readTextFile, TextLineWriter } from './sources/text/read-file.js';
+export { followTextFile } from './sources/text/follow-file.js';
+export { CanvasRenderer } from './renderer/canvas/canvas-renderer.js';
+export { DEFAULT_RENDER_THEME } from './renderer/theme.js';
+export { LogViewer } from './viewer/viewer.js';
+export { EN_LABELS, KO_LABELS, labelsFor } from './viewer/labels.js';
+export { DEFAULT_FONT, readFont, readTheme } from './viewer/theme.js';