@oh-my-pi/pi-utils 17.2.9 → 17.2.11

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

@@ -0,0 +1,431 @@
+/** Behavior-compatible reimplementation of linkedom's used surface. */
+/** DOM node type constants. */
+export declare const enum NodeType {
+    ELEMENT = 1,
+    ATTRIBUTE = 2,
+    TEXT = 3,
+    COMMENT = 8,
+    DOCUMENT = 9,
+    DOCUMENT_FRAGMENT = 11
+}
+interface EventInit {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+}
+interface CustomEventInit<T> extends EventInit {
+    detail?: T;
+}
+interface ElementCreationOptions {
+    is?: string;
+}
+type FrameRequestCallback = (time: number) => void;
+/** Minimal browser event implementation. */
+export declare class Event {
+    #private;
+    type: string;
+    bubbles: boolean;
+    cancelable: boolean;
+    target: EventTarget | null;
+    currentTarget: EventTarget | null;
+    defaultPrevented: boolean;
+    constructor(type: string, init?: EventInit);
+    /** Initialize an event created through Document.createEvent. */
+    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+    /** Cancel this event when it is cancelable. */
+    preventDefault(): void;
+    /** Stop bubbling this event. */
+    stopPropagation(): void;
+    /** Whether propagation has been stopped. */
+    get propagationStopped(): boolean;
+}
+/** Browser custom event carrying a detail value. */
+export declare class CustomEvent<T = unknown> extends Event {
+    readonly detail: T | undefined;
+    constructor(type: string, init?: CustomEventInit<T>);
+}
+type EventListener = ((event: Event) => void) | {
+    handleEvent(event: Event): void;
+};
+/** Minimal event-target implementation used by DOM nodes and window. */
+export declare class EventTarget {
+    #private;
+    /** Register an event listener. */
+    addEventListener(type: string, listener: EventListener | null): void;
+    /** Remove an event listener. */
+    removeEventListener(type: string, listener: EventListener | null): void;
+    /** Dispatch an event to listeners and optionally through node ancestors. */
+    dispatchEvent(event: Event): boolean;
+}
+/** Base class for the implemented DOM tree. */
+export declare class Node extends EventTarget {
+    static readonly ELEMENT_NODE = NodeType.ELEMENT;
+    static readonly ATTRIBUTE_NODE = NodeType.ATTRIBUTE;
+    static readonly TEXT_NODE = NodeType.TEXT;
+    static readonly COMMENT_NODE = NodeType.COMMENT;
+    static readonly DOCUMENT_NODE = NodeType.DOCUMENT;
+    static readonly DOCUMENT_FRAGMENT_NODE = NodeType.DOCUMENT_FRAGMENT;
+    readonly nodeType: number;
+    readonly nodeName: string;
+    parentNode: Node | null;
+    ownerDocument: Document | null;
+    childNodes: Node[];
+    constructor(nodeType: number, nodeName: string, ownerDocument?: Document | null);
+    /** First child node, if present. */
+    get firstChild(): Node | null;
+    /** Last child node, if present. */
+    get lastChild(): Node | null;
+    /** Previous node with the same parent. */
+    get previousSibling(): Node | null;
+    /** Next node with the same parent. */
+    get nextSibling(): Node | null;
+    /** Connectedness to a document. */
+    get isConnected(): boolean;
+    /** Node value for character-data nodes. */
+    get nodeValue(): string | null;
+    set nodeValue(_value: string | null);
+    /** Text contained by this node. */
+    get textContent(): string | null;
+    set textContent(value: string | null);
+    /** Parent element, excluding document and fragments. */
+    get parentElement(): Element | null;
+    /** Append a node, moving it from its old parent. */
+    appendChild<T extends Node>(child: T): T;
+    /** Insert a node before a current child, or append for null. */
+    insertBefore<T extends Node>(child: T, reference: Node | null): T;
+    /** Replace a current child with another node. */
+    replaceChild<T extends Node>(child: Node, previous: T): T;
+    /** Remove a current child. */
+    removeChild<T extends Node>(child: T): T;
+    /** Replace all children with nodes or strings. */
+    replaceChildren(...children: Array<Node | string>): void;
+    /** Append nodes or strings. */
+    append(...children: Array<Node | string>): void;
+    /** Prepend nodes or strings. */
+    prepend(...children: Array<Node | string>): void;
+    /** Remove this node from its parent. */
+    remove(): void;
+    /** Replace this node in its parent. */
+    replaceWith(...nodes: Array<Node | string>): void;
+    /** Whether this node contains another node. */
+    contains(other: Node | null): boolean;
+    /** Clone this node, optionally including descendants. */
+    cloneNode(deep?: boolean): Node;
+    /** Compare tree position sufficiently for document-order consumers. */
+    compareDocumentPosition(other: Node): number;
+    setOwnerDocument(document: Document): void;
+    documentForCreation(): Document;
+}
+/** Text node. */
+export declare class Text extends Node {
+    data: string;
+    serializeRaw: boolean;
+    constructor(data: string, ownerDocument?: Document | null, serializeRaw?: boolean);
+    /** Number of UTF-16 code units. */
+    get length(): number;
+    get nodeValue(): string;
+    set nodeValue(value: string | null);
+    get textContent(): string;
+    set textContent(value: string | null);
+    /** Split this text node at an offset. */
+    splitText(offset: number): Text;
+    cloneNode(): Text;
+}
+/** Comment node. */
+export declare class Comment extends Text {
+    constructor(data: string, ownerDocument?: Document | null);
+    cloneNode(): Comment;
+}
+/** DOM attribute value object. */
+export declare class Attr extends Node {
+    readonly name: string;
+    value: string;
+    readonly namespaceURI: string | null;
+    constructor(name: string, value: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    get nodeValue(): string;
+    set nodeValue(value: string | null);
+    get textContent(): string;
+    set textContent(value: string | null);
+    cloneNode(): Attr;
+}
+/** Array-like attribute collection. */
+export declare class NamedNodeMap extends Array<Attr> {
+    /** Find an attribute case-insensitively. */
+    getNamedItem(name: string): Attr | null;
+    /** Set an attribute object and return the prior one. */
+    setNamedItem(attr: Attr): Attr | null;
+    /** Remove and return a named attribute. */
+    removeNamedItem(name: string): Attr;
+}
+/** Token-list view over an element class attribute. */
+export declare class DOMTokenList implements Iterable<string> {
+    #private;
+    constructor(element: Element);
+    /** Token count. */
+    get length(): number;
+    /** String representation. */
+    get value(): string;
+    set value(value: string);
+    /** Add class tokens. */
+    add(...tokens: string[]): void;
+    /** Remove class tokens. */
+    remove(...tokens: string[]): void;
+    /** Whether a class token exists. */
+    contains(token: string): boolean;
+    /** Toggle a class token. */
+    toggle(token: string, force?: boolean): boolean;
+    /** Replace one class token with another. */
+    replace(previous: string, next: string): boolean;
+    /** Token at an index. */
+    item(index: number): string | null;
+    [Symbol.iterator](): Iterator<string>;
+    toString(): string;
+}
+/** Mutable inline style declaration. */
+export declare class CSSStyleDeclaration {
+    #private;
+    /** Serialized declarations. */
+    get cssText(): string;
+    set cssText(value: string);
+    /** Read a CSS property. */
+    getPropertyValue(name: string): string;
+    /** Set a CSS property. */
+    setProperty(name: string, value: string | null, _priority?: string): void;
+    /** Remove and return a CSS property. */
+    removeProperty(name: string): string;
+}
+/** DOM element with attributes, selectors, and HTML serialization. */
+export declare class Element extends Node {
+    readonly localName: string;
+    readonly tagName: string;
+    readonly namespaceURI: string | null;
+    readonly qualifiedName: string;
+    readonly attributes: NamedNodeMap;
+    readonly classList: DOMTokenList;
+    readonly style: CSSStyleDeclaration;
+    constructor(tagName: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    /** Element children. */
+    get children(): Element[];
+    /** First element child. */
+    get firstElementChild(): Element | null;
+    /** Last element child. */
+    get lastElementChild(): Element | null;
+    /** Previous sibling that is an element. */
+    get previousElementSibling(): Element | null;
+    /** Next sibling that is an element. */
+    get nextElementSibling(): Element | null;
+    /** Attribute-backed element id. */
+    get id(): string;
+    set id(value: string);
+    /** Attribute-backed class string. */
+    get className(): string;
+    set className(value: string);
+    /** Data attributes exposed as camel-cased properties. */
+    get dataset(): Record<string, string>;
+    /** Linkedom-compatible legacy text property (only specialized elements define a value). */
+    get text(): string | undefined;
+    /** HTML contained inside this element. */
+    get innerHTML(): string;
+    set innerHTML(value: string);
+    /** Serialized element and descendants. */
+    get outerHTML(): string;
+    set outerHTML(value: string);
+    /** Read an attribute. */
+    getAttribute(name: string): string | null;
+    /** Read an attribute object. */
+    getAttributeNode(name: string): Attr | null;
+    /** Whether an attribute exists. */
+    hasAttribute(name: string): boolean;
+    /** Set an attribute. */
+    setAttribute(name: string, value: string): void;
+    /** Set a namespaced attribute. */
+    setAttributeNS(_namespace: string | null, name: string, value: string): void;
+    /** Remove an attribute. */
+    removeAttribute(name: string): void;
+    /** Find the first descendant matching a selector. */
+    querySelector(selector: string): Element | null;
+    /** Find all descendants matching a selector. */
+    querySelectorAll(selector: string): Element[];
+    /** Whether this element matches a selector. */
+    matches(selector: string): boolean;
+    /** Find the nearest matching ancestor including this element. */
+    closest(selector: string): Element | null;
+    /** Descendant elements with a tag name. */
+    getElementsByTagName(tagName: string): Element[];
+    /** Descendant elements containing all requested class tokens. */
+    getElementsByClassName(classNames: string): Element[];
+    /**
+     * Return a zero-sized rectangle because this parser DOM has no layout.
+     * Browser-side scripts only use this method's standard shape.
+     */
+    getBoundingClientRect(): {
+        x: number;
+        y: number;
+        bottom: number;
+        height: number;
+        left: number;
+        right: number;
+        top: number;
+        width: number;
+    };
+    /** Focus this element in its owner document. */
+    focus(): void;
+    /** Clear focus from this element. */
+    blur(): void;
+    /** Trigger a synthetic click event. */
+    click(): void;
+    cloneNode(deep?: boolean): Element;
+}
+/** HTML element implementation. */
+export declare class HTMLElement extends Element {
+    value: string;
+    checked: boolean;
+    selected: boolean;
+    disabled: boolean;
+    multiple: boolean;
+    defaultValue: string;
+    defaultChecked: boolean;
+    /** Reflected title attribute. */
+    get title(): string;
+    set title(value: string);
+    /** Reflected href attribute. */
+    get href(): string;
+    set href(value: string);
+    /** Reflected input type. */
+    get type(): string;
+    set type(value: string);
+    /** Reflected name. */
+    get name(): string;
+    set name(value: string);
+}
+/** HTML meta element with a reflected content attribute. */
+export declare class HTMLMetaElement extends HTMLElement {
+    /** Reflected metadata content. */
+    get content(): string;
+    set content(value: string);
+}
+/** SVG element marker used by React feature checks. */
+export declare class SVGElement extends Element {
+}
+/** Iframe element marker used by React selection restoration. */
+export declare class HTMLIFrameElement extends HTMLElement {
+}
+/** Document fragment. */
+export declare class DocumentFragment extends Node {
+    constructor(ownerDocument?: Document | null);
+    /** Element children. */
+    get children(): Element[];
+    /** First element child. */
+    get firstElementChild(): Element | null;
+    /** Last element child. */
+    get lastElementChild(): Element | null;
+    /** First matching descendant. */
+    querySelector(selector: string): Element | null;
+    /** All matching descendants. */
+    querySelectorAll(selector: string): Element[];
+    cloneNode(deep?: boolean): DocumentFragment;
+}
+/** HTML template whose parsed descendants live in a document fragment. */
+export declare class HTMLTemplateElement extends HTMLElement {
+    readonly content: DocumentFragment;
+    constructor(tagName: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    get innerHTML(): string;
+    set innerHTML(value: string);
+    get textContent(): string;
+    set textContent(value: string | null);
+    appendChild<T extends Node>(child: T): T;
+    insertBefore<T extends Node>(child: T, reference: Node | null): T;
+    replaceChild<T extends Node>(child: Node, previous: T): T;
+    removeChild<T extends Node>(child: T): T;
+    cloneNode(deep?: boolean): HTMLTemplateElement;
+}
+/** Minimal HTML document. */
+export declare class Document extends Node {
+    defaultView: DOMWindow | null;
+    URL: string;
+    activeElement: Element | null;
+    constructor();
+    /** Root element of the document. */
+    get documentElement(): Element | null;
+    /** Element children. */
+    get children(): Element[];
+    /** HTML body, or a detached empty body when absent like linkedom. */
+    get body(): HTMLElement;
+    /** HTML head, or a detached empty head when absent. */
+    get head(): HTMLElement;
+    /** Document title text. */
+    get title(): string;
+    set title(value: string);
+    get textContent(): null;
+    set textContent(_value: string | null);
+    /** Create an HTML element. */
+    createElement(tagName: string, _options?: ElementCreationOptions): HTMLElement;
+    /** Create a namespaced element. */
+    createElementNS(namespace: string | null, tagName: string): Element;
+    /** Create a text node. */
+    createTextNode(data: string): Text;
+    /** Create a comment. */
+    createComment(data: string): Comment;
+    /** Create an attribute. */
+    createAttribute(name: string): Attr;
+    /** Create a document fragment. */
+    createDocumentFragment(): DocumentFragment;
+    /** Find the first element by id. */
+    getElementById(id: string): HTMLElement | null;
+    /** Find the first matching descendant. */
+    querySelector(selector: string): Element | null;
+    /** Find all matching descendants. */
+    querySelectorAll(selector: string): Element[];
+    /** Descendant elements with a tag name. */
+    getElementsByTagName(tagName: string): Element[];
+    /** Descendant elements containing all class tokens. */
+    getElementsByClassName(classNames: string): Element[];
+    /** Adopt a node into this document. */
+    adoptNode<T extends Node>(node: T): T;
+    /** Import a cloned node into this document. */
+    importNode<T extends Node>(node: T, deep?: boolean): T;
+    /** Legacy event factory used by libraries. */
+    createEvent(_kind: string): Event;
+    cloneNode(deep?: boolean): Document;
+}
+/** Window shape returned by parseHTML. */
+export declare class DOMWindow extends EventTarget {
+    readonly document: Document;
+    readonly Node: typeof Node;
+    readonly Element: typeof Element;
+    readonly HTMLElement: typeof HTMLElement;
+    readonly HTMLIFrameElement: typeof HTMLIFrameElement;
+    readonly SVGElement: typeof SVGElement;
+    readonly Text: typeof Text;
+    readonly Comment: typeof Comment;
+    readonly Document: typeof Document;
+    readonly DocumentFragment: typeof DocumentFragment;
+    readonly Event: typeof Event;
+    readonly CustomEvent: typeof CustomEvent;
+    readonly navigator: {
+        userAgent: string;
+        platform: string;
+    };
+    readonly location: {
+        href: string;
+    };
+    readonly window: DOMWindow;
+    readonly self: DOMWindow;
+    readonly top: DOMWindow;
+    readonly parent: DOMWindow;
+    constructor(document: Document);
+    /** Browser-compatible computed style placeholder. */
+    getComputedStyle(element: Element): CSSStyleDeclaration;
+    /** Schedule an animation callback. */
+    requestAnimationFrame(callback: FrameRequestCallback): number;
+    /** Cancel an animation callback. */
+    cancelAnimationFrame(handle: number): void;
+    /** Empty selection object. */
+    getSelection(): {
+        rangeCount: number;
+        removeAllRanges(): void;
+    };
+}
+/** Serialize a DOM node as HTML. */
+export declare function serializeNode(node: Node): string;
+export {};

package/dist/types/dom/parser.d.ts

@@ -0,0 +1,7 @@
+import { Document, type DocumentFragment } from "./core.js";
+/** Decode common named entities and all valid numeric character references. */
+export declare function decodeEntities(value: string): string;
+/** Parse markup into a document fragment. */
+export declare function parseFragment(html: string, document: Document, contextTag?: string): DocumentFragment;
+/** Parse markup directly into a document. */
+export declare function parseDocument(html: string): Document;

package/dist/types/dom/selector.d.ts

@@ -0,0 +1,5 @@
+import { type Document, type DocumentFragment, Element } from "./core.js";
+/** Whether an element matches a CSS selector list. */
+export declare function matchesSelector(element: Element, selector: string): boolean;
+/** Query descendants of a node in document order. */
+export declare function querySelectorAllFrom(root: Document | DocumentFragment | Element, selector: string, includeRoot: boolean): Element[];

package/dist/types/dom.d.ts

@@ -0,0 +1,5 @@
+/** Behavior-compatible reimplementation of linkedom's used surface. */
+import { DOMWindow } from "./dom/core.js";
+export { Attr, Comment, CSSStyleDeclaration, CustomEvent, DOMTokenList, DOMWindow, Document, DocumentFragment, Element, Event, EventTarget, HTMLElement, HTMLIFrameElement, HTMLMetaElement, HTMLTemplateElement, NamedNodeMap, Node, NodeType, SVGElement, serializeNode, Text, } from "./dom/core.js";
+/** Parse HTML or XML-like markup into a lightweight window and document. */
+export declare function parseHTML(html: string): DOMWindow;

package/dist/types/frontmatter.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Recursively normalize object keys from kebab-case to camelCase — the
+ * representation convention for frontmatter consumed inside this codebase.
+ * Exported for loaders that parse with `rawKeys: true` to validate exact
+ * spec-defined keys, then normalize for storage.
+ */
+export declare function normalizeFrontmatterKeys<T>(obj: T): T;
 export declare class FrontmatterError extends Error {
     readonly source?: unknown;
     constructor(error: Error, source?: unknown);
@@ -14,6 +21,20 @@ export interface FrontmatterOptions {
     normalize?: boolean;
     /** Level of error handling */
     level?: "off" | "warn" | "fatal";
+    /**
+     * Attempt lenient recovery of near-miss input before failing: quote
+     * ambiguous plain scalars, replace tabs with spaces, and strip leading HTML
+     * comments ahead of the opening delimiter. Default `true`. Spec-conformant
+     * loaders set `false` so malformed input is rejected instead of silently
+     * repaired (CRLF newline normalization still applies).
+     */
+    repair?: boolean;
+    /**
+     * Preserve frontmatter keys verbatim instead of normalizing kebab-case to
+     * camelCase. Default `false`. Strict spec loaders use this so a standard
+     * key (e.g. `allowed-tools`) is never aliased with its camelCase form.
+     */
+    rawKeys?: boolean;
 }
 /**
  * Parse YAML frontmatter from markdown content

package/dist/types/headers.d.ts

@@ -0,0 +1,34 @@
+/** Behavior-compatible reimplementation of header-generator's used surface. */
+/** A browser family supported by the curated header profiles. */
+export type BrowserName = "chrome" | "firefox" | "safari";
+/** A desktop operating system supported by the curated header profiles. */
+export type OperatingSystem = "windows" | "macos" | "linux";
+/** Constructor and per-call constraints for header generation. */
+export interface HeaderGeneratorOptions {
+    /** Browser families eligible for a draw. */
+    browsers: BrowserName[];
+    /** Browser selection query; the supported `last 3 versions` query uses the curated versions. */
+    browserListQuery: string;
+    /** Desktop operating systems eligible for a draw. */
+    operatingSystems: OperatingSystem[];
+    /** Device classes eligible for a draw. */
+    devices: "desktop"[];
+    /** Ordered locales for the Accept-Language value. */
+    locales: string[];
+    /** HTTP protocol generation mode. */
+    httpVersion: "1" | "2";
+    /** Whether impossible constraints throw instead of relaxing to a coherent profile. */
+    strict: boolean;
+    /** Random source returning a value in the range from zero (inclusive) to one (exclusive). */
+    rng: () => number;
+}
+/** A generated HTTP request header map. */
+export type Headers = Record<string, string>;
+/** Generates coherent modern desktop browser navigation headers. */
+export declare class HeaderGenerator {
+    #private;
+    /** Creates a generator with reusable constraints and an optionally injectable RNG. */
+    constructor(options?: Partial<HeaderGeneratorOptions>);
+    /** Generates one header set, applying per-call constraints and request overrides. */
+    getHeaders(options?: Partial<HeaderGeneratorOptions>, overrides?: Headers): Headers;
+}

package/dist/types/logger/rotating-file.d.ts

@@ -0,0 +1,18 @@
+/** Configuration for a process-local rotating file sink. */
+export interface RotatingFileOptions {
+    readonly directory: string;
+    readonly filenamePrefix: string;
+    readonly filenameSuffix: string;
+    readonly auditFile: string;
+    readonly maxBytes: number;
+    readonly maxFiles: number;
+}
+/** Synchronous append sink with local-day and size rotation plus bounded retention. */
+export declare class RotatingFileSink {
+    #private;
+    constructor(options: RotatingFileOptions);
+    /** Append one already-formatted log record. */
+    write(line: string): void;
+    /** Stop accepting records. Synchronous writes require no drain phase. */
+    close(): void;
+}

package/dist/types/lru.d.ts

@@ -0,0 +1,46 @@
+/** Behavior-compatible reimplementation of lru-cache's used surface. */
+/** Why an entry left the cache. */
+export type DisposeReason = "evict" | "set" | "delete" | "expire";
+/** Options supported by {@link LRUCache}. */
+export interface LRUCacheOptions<K, V> {
+    /** Maximum number of retained entries. */
+    max?: number;
+    /** Maximum aggregate calculated size. */
+    maxSize?: number;
+    /** Maximum calculated size of one entry. */
+    maxEntrySize?: number;
+    /** Calculates an entry's size. */
+    sizeCalculation?: (value: V, key: K) => number;
+    /** Entry lifetime in milliseconds; zero disables expiry. */
+    ttl?: number;
+    /** Refreshes an entry's lifetime when it is read. */
+    updateAgeOnGet?: boolean;
+    /** Called synchronously before an entry is removed. */
+    dispose?: (value: V, key: K, reason: DisposeReason) => void;
+}
+/** A bounded least-recently-used cache with optional size and lifetime limits. */
+export declare class LRUCache<K, V> {
+    #private;
+    /** Creates an empty cache. */
+    constructor(options: LRUCacheOptions<K, V>);
+    /** Number of entries, including stale entries not yet removed by `get`. */
+    get size(): number;
+    /** Aggregate calculated size of retained entries. */
+    get calculatedSize(): number;
+    /** Stores a value and makes it most recently used. */
+    set(key: K, value: V | undefined): this;
+    /** Returns a value and makes a fresh entry most recently used. */
+    get(key: K): V | undefined;
+    /** Reports whether a fresh value is present without changing recency. */
+    has(key: K): boolean;
+    /** Returns a fresh value without changing recency or removing stale data. */
+    peek(key: K): V | undefined;
+    /** Removes a value, returning whether one was present. */
+    delete(key: K): boolean;
+    /** Removes every value from least to most recently used. */
+    clear(): void;
+    /** Iterates fresh keys from most to least recently used. */
+    keys(): Generator<K, void, unknown>;
+    /** Iterates fresh values from most to least recently used. */
+    values(): Generator<V, void, unknown>;
+}