lognal 0.1.0

package/dist/sources/console/snapshot.js

@@ -0,0 +1,547 @@
+export const DEFAULT_CAPTURE_OPTIONS = {
+    maxDepth: 5,
+    maxProperties: 100,
+    maxStringLength: 10000,
+    maxNodes: 2000
+};
+/** The most attributes captured from one element, and the longest attribute value. */
+const MAX_ATTRIBUTES = 20;
+const MAX_ATTRIBUTE_LENGTH = 200;
+const getterOf = (target, key) => {
+    if (!target) {
+        return undefined;
+    }
+    return Object.getOwnPropertyDescriptor(target, key)?.get;
+};
+/** Calls a built-in getter or method on a value, and returns `undefined` when it throws. */
+const callBuiltIn = (fn, value) => {
+    if (!fn) {
+        return undefined;
+    }
+    try {
+        return fn.call(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Returns whether a built-in accepts the value, which is how built-in types are told apart. */
+const accepts = (fn, value) => {
+    if (!fn) {
+        return false;
+    }
+    try {
+        fn.call(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const globals = globalThis;
+const TYPED_ARRAY_PROTOTYPE = Object.getPrototypeOf(Uint8Array.prototype);
+const TYPED_ARRAY_TAG = getterOf(TYPED_ARRAY_PROTOTYPE, Symbol.toStringTag);
+const TYPED_ARRAY_LENGTH = getterOf(TYPED_ARRAY_PROTOTYPE, 'length');
+const MAP_SIZE = getterOf(Map.prototype, 'size');
+const SET_SIZE = getterOf(Set.prototype, 'size');
+const ARRAY_BUFFER_LENGTH = getterOf(ArrayBuffer.prototype, 'byteLength');
+const REGEXP_SOURCE = getterOf(RegExp.prototype, 'source');
+const REGEXP_FLAGS = getterOf(RegExp.prototype, 'flags');
+const NODE_TYPE = getterOf(globals.Node?.prototype, 'nodeType');
+const WEAK_MAP_HAS = function () {
+    return WeakMap.prototype.has.call(this, {});
+};
+const WEAK_SET_HAS = function () {
+    return WeakSet.prototype.has.call(this, {});
+};
+const NATIVE_CODE = /\{\s*\[native code\]\s*\}\s*$/;
+const isNativeFunction = (fn) => {
+    try {
+        return typeof fn === 'function' && NATIVE_CODE.test(Function.prototype.toString.call(fn));
+    }
+    catch {
+        return false;
+    }
+};
+/** Looks a property up along the prototype chain without running user-defined getters. */
+const readProperty = (value, key) => {
+    let target = value;
+    let depth = 0;
+    while (target && depth < 32) {
+        let descriptor;
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(target, key);
+        }
+        catch {
+            return undefined;
+        }
+        if (descriptor) {
+            if ('value' in descriptor) {
+                return descriptor.value;
+            }
+            return isNativeFunction(descriptor.get) ? callBuiltIn(descriptor.get, value) : undefined;
+        }
+        try {
+            target = Object.getPrototypeOf(target);
+        }
+        catch {
+            return undefined;
+        }
+        depth++;
+    }
+    return undefined;
+};
+const classNameOf = (value) => {
+    let prototype;
+    try {
+        prototype = Object.getPrototypeOf(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!prototype) {
+        return undefined;
+    }
+    const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
+    if (typeof constructor !== 'function') {
+        return undefined;
+    }
+    const name = Object.getOwnPropertyDescriptor(constructor, 'name')?.value;
+    return typeof name === 'string' && name ? name : undefined;
+};
+const functionName = (fn) => {
+    const name = Object.getOwnPropertyDescriptor(fn, 'name')?.value;
+    return typeof name === 'string' ? name : '';
+};
+const isError = (value) => {
+    const isErrorCheck = Error.isError;
+    if (typeof isErrorCheck === 'function') {
+        return isErrorCheck(value);
+    }
+    return value instanceof Error;
+};
+/** Removes the `Name: message` header V8 puts at the top of a stack trace. */
+const stackWithoutHeader = (stack, name, message) => {
+    const header = message ? `${name}: ${message}` : name;
+    if (stack.startsWith(header)) {
+        return stack.slice(header.length).replace(/^\r?\n/, '');
+    }
+    return stack;
+};
+class Capture {
+    options;
+    nodes = 0;
+    path = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    value(value, depth) {
+        this.nodes++;
+        switch (typeof value) {
+            case 'undefined':
+                return { kind: 'undefined' };
+            case 'boolean':
+                return { kind: 'boolean', value: String(value) };
+            case 'number':
+                return { kind: 'number', value: Object.is(value, -0) ? '-0' : String(value) };
+            case 'bigint':
+                return {
+                    kind: 'bigint',
+                    value: String(callBuiltIn(BigInt.prototype.toString, value) ?? '')
+                };
+            case 'string':
+                return this.string(value);
+            case 'symbol':
+                return {
+                    kind: 'symbol',
+                    value: String(callBuiltIn(Symbol.prototype.toString, value) ?? 'Symbol()')
+                };
+            case 'function':
+                return this.function(value);
+            default:
+                break;
+        }
+        if (value === null) {
+            return { kind: 'null' };
+        }
+        const object = value;
+        if (this.path.has(object)) {
+            return { kind: 'circular' };
+        }
+        this.path.add(object);
+        try {
+            return this.object(object, depth);
+        }
+        finally {
+            this.path.delete(object);
+        }
+    }
+    string(value) {
+        const { maxStringLength } = this.options;
+        if (value.length <= maxStringLength) {
+            return { kind: 'string', value };
+        }
+        return {
+            kind: 'string',
+            value: value.slice(0, maxStringLength),
+            truncated: value.length - maxStringLength,
+            size: value.length
+        };
+    }
+    function(fn) {
+        let source = '';
+        try {
+            source = Function.prototype.toString.call(fn).slice(0, 6);
+        }
+        catch {
+            // A revoked proxy has no source.
+        }
+        return { kind: source.startsWith('class') ? 'class' : 'function', value: functionName(fn) };
+    }
+    /** Whether this value may capture its children, or is shown by name only. */
+    canDescend(depth) {
+        return depth < this.options.maxDepth && this.nodes < this.options.maxNodes;
+    }
+    object(value, depth) {
+        if (accepts(Date.prototype.getTime, value)) {
+            const time = Date.prototype.getTime.call(value);
+            return {
+                kind: 'date',
+                value: Number.isNaN(time) ? 'Invalid Date' : Date.prototype.toISOString.call(value)
+            };
+        }
+        if (accepts(REGEXP_SOURCE, value) && value !== RegExp.prototype) {
+            return {
+                kind: 'regexp',
+                value: `/${callBuiltIn(REGEXP_SOURCE, value)}/${callBuiltIn(REGEXP_FLAGS, value) ?? ''}`
+            };
+        }
+        if (isError(value)) {
+            return this.error(value, depth);
+        }
+        if (NODE_TYPE && accepts(NODE_TYPE, value)) {
+            return this.domNode(value, depth);
+        }
+        if (Array.isArray(value)) {
+            return this.array(value, depth);
+        }
+        if (ArrayBuffer.isView(value)) {
+            return this.typedArray(value, depth);
+        }
+        if (accepts(MAP_SIZE, value)) {
+            return this.map(value, depth);
+        }
+        if (accepts(SET_SIZE, value)) {
+            return this.set(value, depth);
+        }
+        if (accepts(WEAK_MAP_HAS, value)) {
+            return { kind: 'weak', className: 'WeakMap' };
+        }
+        if (accepts(WEAK_SET_HAS, value)) {
+            return { kind: 'weak', className: 'WeakSet' };
+        }
+        if (globals.WeakRef && accepts(globals.WeakRef.prototype.deref, value)) {
+            return { kind: 'weak', className: 'WeakRef' };
+        }
+        if (value instanceof Promise ||
+            (readProperty(value, Symbol.toStringTag) === 'Promise' &&
+                isNativeFunction(readProperty(value, 'then')))) {
+            return { kind: 'promise', className: classNameOf(value) ?? 'Promise' };
+        }
+        if (accepts(ARRAY_BUFFER_LENGTH, value)) {
+            return {
+                kind: 'object',
+                className: classNameOf(value) ?? 'ArrayBuffer',
+                children: [
+                    {
+                        key: 'byteLength',
+                        value: { kind: 'number', value: String(callBuiltIn(ARRAY_BUFFER_LENGTH, value)) }
+                    }
+                ]
+            };
+        }
+        return this.plainObject(value, depth);
+    }
+    plainObject(value, depth) {
+        const node = { kind: 'object', className: classNameOf(value) };
+        if (!this.canDescend(depth)) {
+            return node;
+        }
+        const { children, omitted } = this.properties(value, depth);
+        node.children = children;
+        if (omitted > 0) {
+            node.omitted = omitted;
+        }
+        return node;
+    }
+    properties(value, depth, skip) {
+        const children = [];
+        let keys;
+        let omitted = 0;
+        try {
+            keys = Reflect.ownKeys(value);
+        }
+        catch {
+            return { children, omitted };
+        }
+        for (const key of keys) {
+            if (typeof key === 'string' && skip?.(key)) {
+                continue;
+            }
+            let descriptor;
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(value, key);
+            }
+            catch {
+                continue;
+            }
+            if (!descriptor?.enumerable) {
+                continue;
+            }
+            if (children.length >= this.options.maxProperties || this.nodes >= this.options.maxNodes) {
+                omitted++;
+                continue;
+            }
+            const child = typeof key === 'symbol'
+                ? {
+                    key: String(callBuiltIn(Symbol.prototype.toString, key)),
+                    keyKind: 'symbol',
+                    value: { kind: 'undefined' }
+                }
+                : { key, keyKind: 'property', value: { kind: 'undefined' } };
+            child.value =
+                'value' in descriptor ? this.value(descriptor.value, depth + 1) : this.accessor(descriptor);
+            children.push(child);
+        }
+        return { children, omitted };
+    }
+    accessor(descriptor) {
+        this.nodes++;
+        const accessor = descriptor.get && descriptor.set ? 'get-set' : descriptor.set ? 'set' : 'get';
+        return { kind: 'accessor', accessor };
+    }
+    array(value, depth) {
+        let length = 0;
+        try {
+            length = value.length;
+        }
+        catch {
+            // A proxy trap threw.
+        }
+        const node = {
+            kind: 'array',
+            className: classNameOf(value) ?? 'Array',
+            size: length
+        };
+        if (!this.canDescend(depth)) {
+            return node;
+        }
+        const limit = Math.min(length, this.options.maxProperties);
+        const children = [];
+        for (let index = 0; index < limit; index++) {
+            if (this.nodes >= this.options.maxNodes) {
+                break;
+            }
+            let descriptor;
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(value, index);
+            }
+            catch {
+                descriptor = undefined;
+            }
+            const item = descriptor === undefined
+                ? { kind: 'undefined' }
+                : 'value' in descriptor
+                    ? this.value(descriptor.value, depth + 1)
+                    : this.accessor(descriptor);
+            children.push({ key: String(index), keyKind: 'index', value: item });
+        }
+        node.children = children;
+        if (length > children.length) {
+            node.omitted = length - children.length;
+        }
+        return node;
+    }
+    typedArray(value, depth) {
+        const className = String(callBuiltIn(TYPED_ARRAY_TAG, value) ?? classNameOf(value) ?? 'DataView');
+        const length = Number(callBuiltIn(TYPED_ARRAY_LENGTH, value) ?? value.byteLength);
+        const node = { kind: 'array', className, size: length };
+        if (!this.canDescend(depth) || className === 'DataView') {
+            return node;
+        }
+        const items = value;
+        const limit = Math.min(length, this.options.maxProperties);
+        const children = [];
+        for (let index = 0; index < limit; index++) {
+            children.push({
+                key: String(index),
+                keyKind: 'index',
+                value: this.value(items[index], depth + 1)
+            });
+        }
+        node.children = children;
+        if (length > limit) {
+            node.omitted = length - limit;
+        }
+        return node;
+    }
+    map(value, depth) {
+        const size = Number(callBuiltIn(MAP_SIZE, value) ?? 0);
+        const node = { kind: 'map', className: classNameOf(value) ?? 'Map', size };
+        if (!this.canDescend(depth)) {
+            return node;
+        }
+        const children = [];
+        try {
+            for (const [key, item] of Map.prototype.entries.call(value)) {
+                if (children.length >= this.options.maxProperties || this.nodes >= this.options.maxNodes) {
+                    break;
+                }
+                children.push({ keyValue: this.value(key, depth + 1), value: this.value(item, depth + 1) });
+            }
+        }
+        catch {
+            // The map changed while it was read, or a proxy trap threw.
+        }
+        node.children = children;
+        if (size > children.length) {
+            node.omitted = size - children.length;
+        }
+        return node;
+    }
+    set(value, depth) {
+        const size = Number(callBuiltIn(SET_SIZE, value) ?? 0);
+        const node = { kind: 'set', className: classNameOf(value) ?? 'Set', size };
+        if (!this.canDescend(depth)) {
+            return node;
+        }
+        const children = [];
+        try {
+            for (const item of Set.prototype.values.call(value)) {
+                if (children.length >= this.options.maxProperties || this.nodes >= this.options.maxNodes) {
+                    break;
+                }
+                children.push({ value: this.value(item, depth + 1) });
+            }
+        }
+        catch {
+            // The set changed while it was read, or a proxy trap threw.
+        }
+        node.children = children;
+        if (size > children.length) {
+            node.omitted = size - children.length;
+        }
+        return node;
+    }
+    error(value, depth) {
+        const name = readProperty(value, 'name');
+        const message = readProperty(value, 'message');
+        const stack = readProperty(value, 'stack');
+        const nameText = typeof name === 'string' && name ? name : (classNameOf(value) ?? 'Error');
+        const messageText = typeof message === 'string' ? message : '';
+        const node = { kind: 'error', className: nameText, value: messageText };
+        if (typeof stack === 'string' && stack) {
+            const trimmed = stackWithoutHeader(stack, nameText, messageText).trimEnd();
+            if (trimmed) {
+                node.stack = trimmed.slice(0, this.options.maxStringLength);
+            }
+        }
+        if (this.canDescend(depth)) {
+            const { children, omitted } = this.properties(value, depth, (key) => key === 'stack' || key === 'message');
+            const cause = Object.getOwnPropertyDescriptor(value, 'cause');
+            if (cause && 'value' in cause && !cause.enumerable) {
+                children.push({
+                    key: 'cause',
+                    keyKind: 'property',
+                    value: this.value(cause.value, depth + 1)
+                });
+            }
+            if (children.length > 0) {
+                node.children = children;
+            }
+            if (omitted > 0) {
+                node.omitted = omitted;
+            }
+        }
+        return node;
+    }
+    domNode(value, depth) {
+        const type = Number(callBuiltIn(NODE_TYPE, value));
+        const nodePrototype = globals.Node?.prototype;
+        const elementPrototype = globals.Element?.prototype;
+        if (type === 3) {
+            const text = String(callBuiltIn(getterOf(nodePrototype, 'textContent'), value) ?? '');
+            return { kind: 'text', value: text.slice(0, this.options.maxStringLength) };
+        }
+        if (type !== 1 && type !== 9 && type !== 11) {
+            return { kind: 'object', className: classNameOf(value) };
+        }
+        const tag = type === 9
+            ? '#document'
+            : type === 11
+                ? '#document-fragment'
+                : String(callBuiltIn(getterOf(elementPrototype, 'localName'), value) ?? 'element');
+        const node = { kind: 'element', value: tag };
+        if (type === 1) {
+            node.attributes = this.attributes(value);
+        }
+        if (!this.canDescend(depth)) {
+            return node;
+        }
+        const childNodes = callBuiltIn(getterOf(nodePrototype, 'childNodes'), value);
+        const children = [];
+        let omitted = 0;
+        for (let index = 0; childNodes && index < childNodes.length; index++) {
+            const child = childNodes[index];
+            const childType = Number(callBuiltIn(NODE_TYPE, child));
+            if (childType === 3) {
+                const text = String(callBuiltIn(getterOf(nodePrototype, 'textContent'), child) ?? '').trim();
+                if (!text) {
+                    continue;
+                }
+            }
+            else if (childType !== 1) {
+                continue;
+            }
+            if (children.length >= this.options.maxProperties || this.nodes >= this.options.maxNodes) {
+                omitted++;
+                continue;
+            }
+            const captured = this.value(child, depth + 1);
+            if (captured.kind === 'text') {
+                captured.value = captured.value?.trim();
+            }
+            children.push({ value: captured });
+        }
+        node.children = children;
+        if (omitted > 0) {
+            node.omitted = omitted;
+        }
+        return node;
+    }
+    attributes(value) {
+        const attributes = callBuiltIn(getterOf(globals.Element?.prototype, 'attributes'), value);
+        const attrPrototype = globals.Attr?.prototype;
+        const nameGetter = getterOf(attrPrototype, 'name');
+        const valueGetter = getterOf(attrPrototype, 'value');
+        const result = [];
+        for (let index = 0; attributes && index < Math.min(attributes.length, MAX_ATTRIBUTES); index++) {
+            const attribute = attributes[index];
+            const name = String(callBuiltIn(nameGetter, attribute) ?? '');
+            const text = String(callBuiltIn(valueGetter, attribute) ?? '');
+            result.push([name, text.slice(0, MAX_ATTRIBUTE_LENGTH)]);
+        }
+        return result;
+    }
+}
+/**
+ * Captures a value as plain data, at the moment of the call.
+ *
+ * Getters defined by the page are never run: an accessor property is recorded as an accessor.
+ * Built-in types are recognized with the engine's own methods rather than `instanceof`, so
+ * values from another frame are recognized too. Each limit in `options` bounds the work, and
+ * whatever it cuts is counted in the node's `omitted` field.
+ */
+export const snapshotValue = (value, options = {}) => {
+    return new Capture({ ...DEFAULT_CAPTURE_OPTIONS, ...options }).value(value, 0);
+};

package/dist/sources/console/table.d.ts

@@ -0,0 +1,9 @@
+import type { ValueNode } from '../../core/types.js';
+/**
+ * Draws a captured value as a text table with box-drawing characters, the way `console.table`
+ * shows it: one row per property or item, one column per key of the row values, and a
+ * `Values` column for rows that are not objects.
+ *
+ * Returns `null` when the value has no rows, in which case the caller logs it as usual.
+ */
+export declare const formatTable: (node: ValueNode, properties?: readonly string[]) => string | null;

package/dist/sources/console/table.js

@@ -0,0 +1,87 @@
+import { measureCells, padCells, truncateCells } from '../../core/text/measure.js';
+import { previewValue } from '../../core/value/preview.js';
+/** The most rows and columns a table shows, and the widest cell. */
+const MAX_ROWS = 100;
+const MAX_COLUMNS = 20;
+const MAX_CELL_CELLS = 40;
+const INDEX_COLUMN = '(index)';
+const VALUES_COLUMN = 'Values';
+const cellText = (node) => {
+    return previewValue(node, true)
+        .map((span) => span.text)
+        .join('');
+};
+const keyText = (entry) => {
+    if (entry.keyValue) {
+        return cellText(entry.keyValue);
+    }
+    return entry.key ?? '';
+};
+const isRowObject = (node) => {
+    return (node.kind === 'object' || node.kind === 'array') && node.children !== undefined;
+};
+/**
+ * Draws a captured value as a text table with box-drawing characters, the way `console.table`
+ * shows it: one row per property or item, one column per key of the row values, and a
+ * `Values` column for rows that are not objects.
+ *
+ * Returns `null` when the value has no rows, in which case the caller logs it as usual.
+ */
+export const formatTable = (node, properties) => {
+    if (!node.children || node.children.length === 0) {
+        return null;
+    }
+    const rows = node.children.slice(0, MAX_ROWS);
+    const columns = [];
+    let hasValues = false;
+    for (const row of rows) {
+        if (isRowObject(row.value)) {
+            for (const child of row.value.children ?? []) {
+                const key = child.key ?? '';
+                if (!columns.includes(key) && columns.length < MAX_COLUMNS) {
+                    columns.push(key);
+                }
+            }
+        }
+        else {
+            hasValues = true;
+        }
+    }
+    const shownColumns = properties ? properties.filter((key) => columns.includes(key)) : columns;
+    const header = [
+        INDEX_COLUMN,
+        ...shownColumns,
+        ...(hasValues && !properties ? [VALUES_COLUMN] : [])
+    ];
+    const body = rows.map((row) => {
+        const cells = [keyText(row)];
+        const children = isRowObject(row.value) ? (row.value.children ?? []) : [];
+        for (const key of shownColumns) {
+            const child = children.find((item) => item.key === key);
+            cells.push(child ? cellText(child.value) : '');
+        }
+        if (hasValues && !properties) {
+            cells.push(isRowObject(row.value) ? '' : cellText(row.value));
+        }
+        return cells.map((cell) => truncateCells(cell, MAX_CELL_CELLS));
+    });
+    const widths = header.map((title, column) => Math.max(measureCells(title), ...body.map((cells) => measureCells(cells[column]))));
+    const line = (left, middle, right) => {
+        return `${left}${widths.map((width) => '─'.repeat(width + 2)).join(middle)}${right}`;
+    };
+    const row = (cells) => {
+        return `│${cells.map((cell, column) => ` ${padCells(cell, widths[column])} `).join('│')}│`;
+    };
+    const lines = [
+        line('┌', '┬', '┐'),
+        row(header),
+        line('├', '┼', '┤'),
+        ...body.map(row),
+        line('└', '┴', '┘')
+    ];
+    const hidden = node.children.length - rows.length + (node.omitted ?? 0);
+    if (hidden > 0) {
+        lines.push(`… ${hidden} more`);
+    }
+    return lines.join('\n');
+};

package/dist/sources/text/encoding.d.ts

@@ -0,0 +1,11 @@
+/** Returns the legacy encoding for a language tag, such as `euc-kr` for `ko-KR`. */
+export declare const legacyEncodingFor: (locale: string | undefined) => string;
+/** Returns the encoding a byte order mark at the start of the bytes announces, if any. */
+export declare const encodingFromBom: (bytes: Uint8Array) => string | null;
+/** Returns whether the bytes are valid UTF-8. A sequence cut at the end still counts as valid. */
+export declare const isValidUtf8: (bytes: Uint8Array) => boolean;
+/**
+ * Picks the encoding of a file from its first bytes: the byte order mark if there is one,
+ * then UTF-8 if the bytes are valid UTF-8, and otherwise `fallback`.
+ */
+export declare const detectEncoding: (bytes: Uint8Array, fallback: string) => string;