@linxiraos/pi-utils 1.1.7 → 1.1.9

package/dist/types/postmortem.d.ts

@@ -1,174 +0,0 @@
-/**
- * Cleanup and postmortem handler utilities.
- *
- * This module provides a system for registering and running cleanup callbacks
- * in response to process exit, signals, or fatal exceptions. It is intended to
- * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
- */
-export declare enum Reason {
-    PRE_EXIT = "pre_exit",// Pre-exit phase (not used by default)
-    EXIT = "exit",// Normal process exit
-    SIGINT = "sigint",// Ctrl-C or SIGINT
-    SIGTERM = "sigterm",// SIGTERM
-    SIGHUP = "sighup",// SIGHUP
-    UNCAUGHT_EXCEPTION = "uncaught_exception",// Fatal exception
-    UNHANDLED_REJECTION = "unhandled_rejection",// Unhandled promise rejection
-    MANUAL = "manual"
-}
-/**
- * Symbol stamped by the extension-load guard onto the throwing replacement it
- * installs over `process.exit` / `process.reallyExit`, carrying the native
- * primitive that replacement shadows.
- *
- * Host-owned shutdown ({@link exitProcess}) reads through it so a signal that
- * lands while the guard is active still terminates the process (#6488), while
- * a signal that lands after the guard has restored the native exit also
- * terminates cleanly (#7393). `Symbol.for` so it survives duplicate module
- * instances across bundles/realms.
- */
-export declare const NATIVE_PROCESS_EXIT: unique symbol;
-/** User-facing command printed before fatal cleanup so interrupted work can be resumed. */
-export interface FatalRecoveryHint {
-    /** Stable label identifying the recoverable session or process. */
-    label: string;
-    /** Complete shell command the user can execute to resume the interrupted work. */
-    command: string;
-}
-type FatalRecoveryHintProvider = () => FatalRecoveryHint | undefined;
-/** Origin of an EPIPE raised by a process communication channel. */
-export type BrokenPipeSource = "ipc-send" | "stdio-write";
-/**
- * Classify EPIPE errors from worker IPC and stdio without treating unrelated
- * broken pipes as globally recoverable.
- */
-export declare function classifyBrokenPipe(err: Error): BrokenPipeSource | undefined;
-/** Whether an EPIPE came from an IPC `send()` to an optional worker. */
-export declare function isIpcSendEpipe(err: Error): boolean;
-/**
- * Whether an uncaught error is Bun's asynchronous `ERR_SOCKET_CLOSED` thrown
- * from inside `node:net` internals with no application frames on the stack.
- *
- * Bun ≥1.4 can fire the close callback of an already-closed `node:net` socket
- * on a fresh stack; the throw bypasses every callsite try/catch and surfaces
- * here as a process-level uncaughtException. Closing an already-closed socket
- * is inherently a no-op — the socket owner's own `error`/`close` handlers
- * still drive recovery — so tearing the session down for it is pure loss.
- * Only frameless internal stacks qualify: an `ERR_SOCKET_CLOSED` raised
- * through application code keeps the fatal path.
- */
-export declare function isInternalSocketClosedError(err: unknown): boolean;
-/**
- * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
- *
- * When a worker subprocess spawned with `serialization: "advanced"` sends a
- * malformed or truncated frame, Bun raises the decode failure as a
- * process-level `uncaughtException` in the *parent* rather than routing it to
- * the channel's `ipc()` callback (oven-sh/bun#37287). The error is a bare
- * `TypeError: Unable to deserialize data.` whose only own property is `message`
- * — it carries no `code`, no `syscall`, and no `stack`. Matching all four traits
- * keeps unrelated application `TypeError`s (which always carry a populated
- * multi-frame stack) on the fatal path, so a genuine bug is never silently
- * swallowed.
- *
- * Every advanced-serialization channel in this process is an optional worker
- * subsystem (TTS, STT, tiny-title, mnemopi embeddings, JS eval), so one
- * worker's bad frame must fault only that worker — via its own `onExit`/error
- * path — never tear down the whole session. Callers log-and-continue instead of
- * taking the fatal path. Mirrors {@link classifyBrokenPipe} for the send side
- * (#2997, #9158).
- */
-export declare function isWorkerIpcDeserializeError(err: unknown): boolean;
-/**
- * Register a fault/recycle callback for an active advanced-serialization worker
- * IPC channel.
- *
- * Bun surfaces a malformed frame as a process-global `uncaughtException`
- * ({@link isWorkerIpcDeserializeError}) with no way to attribute it to a
- * specific channel, so when one fires every registered handler is invoked to
- * conservatively fault its worker — reject in-flight requests and recycle the
- * subprocess — instead of leaving pending work to await forever. Returns an
- * unregister function; callers MUST unregister when the worker exits.
- */
-export declare function registerWorkerIpcFaultHandler(handler: (err: Error) => void): () => void;
-/**
- * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
- *
- * Stdio protocol servers call this for their process lifetime so a closed
- * client pipe runs registered cleanup callbacks instead of the fatal path.
- * The returned callback removes the registration.
- */
-export declare function registerStdioDisconnectHandling(): () => void;
-/**
- * Mark an error as expected cleanup fallout so the global fatal handlers
- * downgrade it to a log line instead of tearing down the process. Use for
- * abort reasons fired by routine resource teardown (browser run end, tab
- * close) whose rejections may surface on fire-and-forget promises with no
- * consumer. Returns the same error for inline use at the `abort()` callsite.
- */
-export declare function markExpectedCleanupError<T extends object>(reason: T): T;
-/**
- * Whether `reason` (or any object in its bounded `cause` chain) was explicitly
- * marked via {@link markExpectedCleanupError}. Runtime error names and codes
- * are intentionally insufficient: unmarked `AbortError` and socket failures
- * can originate from application code and must remain fatal when unhandled.
- */
-export declare function isExpectedCleanupError(reason: unknown): boolean;
-/**
- * Register an interceptor consulted before an unhandled rejection tears the
- * process down. A consuming interceptor owns reporting and keeps the process alive.
- */
-export declare function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void;
-/**
- * Register a synchronous recovery command to print when the process exits
- * through an uncaught exception or unhandled rejection.
- */
-export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
-/** Controls when a registered cleanup callback participates in cleanup passes. */
-export interface CleanupRegistrationOptions {
-    /**
-     * Run only on a real exit, never during a manual keep-alive cleanup.
-     * The registration remains armed when a keep-alive pass skips it.
-     */
-    exitOnly?: boolean;
-}
-/**
- * Registers a cleanup callback for shutdown, signals, fatal errors, and
- * repeatable manual cleanup passes.
- *
- * Registrations persist across keep-alive {@link cleanup} passes and run at
- * most once per pass. Set `exitOnly` for resources the continuing process still
- * holds (open databases, cached handles): keep-alive passes skip the callback
- * without consuming its registration, while the eventual real exit runs it.
- *
- * A callback registered during a running keep-alive pass joins future passes;
- * normal callbacks also run immediately for the current pass. Registrations
- * made during a real exit run immediately.
- *
- * Returns a function that permanently cancels the registration.
- */
-export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>, options?: CleanupRegistrationOptions): () => void;
-/**
- * Runs all cleanup callbacks without exiting, then re-arms the system so
- * resources opened afterwards are still cleaned at the eventual real exit.
- * Use this in workers or when you need to clean up but continue execution.
- */
-export declare function cleanup(): Promise<void>;
-/** Controls how manual process shutdown handles terminal output. */
-export interface QuitOptions {
-    /** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
-    drainStdout?: boolean;
-}
-/**
- * Waits (bounded) for buffered stdout to reach the terminal. Used before
- * process exit and before an exec-replace, where unflushed output would be
- * lost with the process image.
- */
-export declare function drainStdout(): Promise<void>;
-/**
- * Runs all cleanup callbacks and exits through the current `process.exit`.
- *
- * In main thread: waits for stdout drain unless disabled, then calls `process.exit()`.
- * In workers: runs cleanup only (process.exit would kill entire process).
- */
-export declare function quit(code?: number, options?: QuitOptions): Promise<void>;
-export {};

package/dist/types/process-name.d.ts

@@ -1,7 +0,0 @@
-/**
- * Set both the JS `process.title` and — on Linux — the kernel `comm` name.
- *
- * Never throws: `bun:ffi` unavailability or a failed syscall degrades silently
- * to the `process.title`-only behavior, so it is safe to call at startup.
- */
-export declare function setProcessName(name: string): void;

package/dist/types/procmgr.d.ts

@@ -1,74 +0,0 @@
-import type { Subprocess } from "bun";
-export interface ShellConfig {
-    shell: string;
-    args: string[];
-    env: Record<string, string>;
-    prefix: string | undefined;
-}
-/** Identifies the settings source users should edit when shell resolution fails. */
-export interface ShellConfigOptions {
-    /** File path or runtime layer that supplied the active shell setting. */
-    configSource?: string;
-}
-/**
- * Check if a shell binary is executable.
- */
-export declare function isExecutable(path: string): boolean;
-/**
- * Get shell args for the resolved shell.
- * cmd.exe takes `/c`; PowerShell (powershell.exe / pwsh) takes
- * `-NoLogo -Command`, with `-NoProfile` when PI_BASH_NO_LOGIN /
- * CLAUDE_BASH_NO_LOGIN is set (profile scripts are PowerShell's login-shell
- * analog); POSIX shells take `-c`, with `-l` unless the same env is set.
- *
- * Exported for tests; `env` overrides the process env gate.
- */
-export declare function getShellArgs(shell: string, env?: Record<string, string | undefined>): string[];
-/** Whether the shell is Windows cmd.exe (spawn paths must use `/c`, not `-c`). */
-export declare function isCmdShell(shell: string): boolean;
-/**
- * Whether the shell is Windows PowerShell or PowerShell Core (pwsh). Spawn
- * paths must use `-Command`: passing the POSIX `-l -c` pair makes PowerShell
- * parse `-l` as the command and fail with `The term '-l' is not recognized`.
- */
-export declare function isPowerShell(shell: string): boolean;
-/**
- * Resolve a basic shell (bash or sh) as fallback.
- */
-export declare function resolveBasicShell(): string | undefined;
-/**
- * Resolve the external shell to advertise on Windows.
- *
- * A host bash is OPTIONAL: bash tool commands always execute in the embedded
- * brush-core shell. The resolved binary only serves the spawn-a-shell paths
- * (interactive PTY sessions, ACP client terminals, SHELL env), so this
- * prefers a real Git Bash when one exists and otherwise falls back to
- * cmd.exe — it never fails.
- *
- * Search order:
- * 1. Git for Windows install roots (machine + per-user installers)
- * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
- *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
- * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
- * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
- *    bash.exe when present)
- * 5. cmd.exe from ComSpec
- *
- * Exported for tests; `env` overrides Bun.env-based discovery.
- */
-export declare function resolveWindowsShell(env?: Record<string, string | undefined>): string;
-/**
- * Get shell configuration based on platform.
- * Resolution order:
- * 1. User-specified shellPath from the active settings source
- * 2. On Windows: Git Bash / bash / sh discovery, then cmd.exe (see
- *    {@link resolveWindowsShell}) — never fails
- * 3. On Unix: $SHELL if bash/zsh, then fallback paths
- * 4. Fallback: sh
- */
-export declare function getShellConfig(customShellPath?: string, options?: ShellConfigOptions): ShellConfig;
-/**
- * Check if a process is running.
- */
-export declare function isPidRunning(pid: number | Subprocess): boolean;
-export declare function onProcessExit(proc: Subprocess | number, abortSignal?: AbortSignal): Promise<boolean>;

package/dist/types/prompt.d.ts

@@ -1,18 +0,0 @@
-import type { HelperDelegate, Template } from "./template.js";
-export type { HelperDelegate, HelperOptions, Template, TemplateDelegate } from "./template.js";
-export type PromptRenderPhase = "pre-render" | "post-render";
-export interface PromptFormatOptions {
-    renderPhase?: PromptRenderPhase;
-    replaceAsciiSymbols?: boolean;
-    normalizeRfc2119?: boolean;
-}
-export declare function format(content: string, options?: PromptFormatOptions): string;
-export interface TemplateContext extends Record<string, unknown> {
-    args?: string[];
-    ARGUMENTS?: string;
-    arguments?: string;
-}
-export declare function registerHelper(name: string, fn: HelperDelegate): void;
-export declare function registerPartial(name: string, fn: Template): void;
-export declare function compile(template: string): (context: TemplateContext) => string;
-export declare function render(template: string, context?: TemplateContext): string;

package/dist/types/ptree.d.ts

@@ -1,124 +0,0 @@
-/**
- * Process tree management utilities for Bun subprocesses.
- *
- * - Track managed child processes for cleanup on shutdown (postmortem).
- * - Drain stdout/stderr to avoid subprocess pipe deadlocks.
- * - Cross-platform tree kill for process groups (Windows taskkill, Unix -pid).
- * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
- */
-import type { Spawn, Subprocess } from "bun";
-type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
-/** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
-type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
-/**
- * Build the Linux child-subreaper entrypoint.
- *
- * @internal Exported so tests can force a missing first libc soname and verify
- * the loader continues to the next candidate.
- */
-export declare function createLinuxSubreaperScript(libcCandidates?: readonly string[]): string;
-/**
- * Base for all exceptions representing child process nonzero exit, killed, or
- * cancellation.
- */
-export declare abstract class Exception extends Error {
-    readonly exitCode: number;
-    readonly stderr: string;
-    constructor(message: string, exitCode: number, stderr: string);
-    abstract readonly aborted: boolean;
-}
-/** Exception for nonzero exit codes (not cancellation). */
-export declare class NonZeroExitError extends Exception {
-    static readonly MAX_TRACE: number;
-    constructor(exitCode: number, stderr: string);
-    get aborted(): boolean;
-}
-/** Exception for explicit process abortion (via signal). */
-export declare class AbortError extends Exception {
-    readonly reason: unknown;
-    constructor(reason: unknown, stderr: string);
-    get aborted(): boolean;
-}
-/** Exception for process timeout. */
-export declare class TimeoutError extends AbortError {
-    constructor(timeout: number, stderr: string);
-}
-/** Options for waiting for process exit and capturing output. */
-export interface WaitOptions {
-    allowNonZero?: boolean;
-    allowAbort?: boolean;
-    /** `full` requires upfront capture; `exec` enables it, while direct `spawn` callers pass `stderr: "full"`. */
-    stderr?: "full" | "buffer";
-}
-/** Result from wait and exec. */
-export interface ExecResult {
-    stdout: string;
-    stderr: string;
-    exitCode: number | null;
-    ok: boolean;
-    exitError?: Exception;
-}
-/**
- * ChildProcess wraps a managed subprocess, capturing stderr tail, providing
- * cross-platform kill/detach logic plus AbortSignal integration.
- *
- * Stdout is exposed directly from the underlying Bun subprocess; consumers
- * must read it (via text(), wait(), etc.) to prevent pipe deadlock.
- * Stderr is eagerly drained into an internal buffer.
- */
-export declare class ChildProcess<In extends InMask = InMask> {
-    #private;
-    readonly proc: PipedSubprocess<In>;
-    readonly exposeStderr: boolean;
-    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean, terminateGroup?: boolean, hardKillTree?: boolean);
-    get pid(): number;
-    get exited(): Promise<number>;
-    get exitCode(): number | null;
-    get exitReason(): Exception | undefined;
-    get killed(): boolean;
-    get stdin(): Bun.SpawnOptions.WritableToIO<In>;
-    /** Raw stdout stream. Must be consumed to prevent pipe deadlock. */
-    get stdout(): ReadableStream<Uint8Array<ArrayBuffer>>;
-    /** Optional stderr stream (only when requested in spawn options). */
-    get stderr(): ReadableStream<Uint8Array<ArrayBufferLike>> | undefined;
-    get exitedCleanly(): Promise<number>;
-    /** Returns the truncated stderr tail (last 32KB). */
-    peekStderr(): string;
-    nothrow(): this;
-    kill(reason?: Exception, gracefulMs?: number): void;
-    text(): Promise<string>;
-    blob(): Promise<Blob>;
-    json(): Promise<unknown>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    bytes(): Promise<Uint8Array>;
-    wait(opts?: WaitOptions): Promise<ExecResult>;
-    attachSignal(signal: AbortSignal): void;
-    attachTimeout(ms: number): void;
-    [Symbol.dispose](): void;
-}
-/** Options for child spawn. Always pipes stdout/stderr. */
-type ChildSpawnOptions<In extends InMask = InMask> = Omit<Spawn.SpawnOptions<In, "pipe", "pipe">, "stdout" | "stderr" | "detached"> & {
-    signal?: AbortSignal;
-    detached?: boolean;
-    /**
-     * On Linux, supervise the command from a child subreaper so descendants
-     * remain reachable after changing session and reparenting. Other platforms
-     * ignore this option. macOS process groups cannot retain a daemonized
-     * descendant that creates a new session and reparents to launchd.
-     */
-    subreaper?: boolean;
-    /** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
-    stderr?: "full" | null;
-};
-/** Spawn a child process with piped stdout/stderr. */
-export declare function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In>;
-/** Options for exec. */
-export interface ExecOptions extends Omit<ChildSpawnOptions, "stderr" | "stdin">, WaitOptions {
-    input?: string | Buffer | Uint8Array;
-}
-/** Spawn, wait, and return captured output. */
-export declare function exec(cmd: string[], opts?: ExecOptions): Promise<ExecResult>;
-type SignalValue = AbortSignal | number | null | undefined;
-/** Combine AbortSignals and timeout values into a single signal. */
-export declare function combineSignals(...signals: SignalValue[]): AbortSignal | undefined;
-export {};

package/dist/types/readability/readability.d.ts

@@ -1,9 +0,0 @@
-/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
-import type { ReadabilityArticle, ReadabilityDocument, ReadabilityOptions } from "./types.js";
-/** Extracts the article body and metadata from a standards-shaped document. */
-export declare class Readability<T = string> {
-    #private;
-    constructor(document: ReadabilityDocument, options?: ReadabilityOptions<T>);
-    /** Runs extraction once; the supplied document is consumed and should not be reused. */
-    parse(): ReadabilityArticle<T> | null;
-}

package/dist/types/readability/readerable.d.ts

@@ -1,10 +0,0 @@
-/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
-import type { ReadabilityDocument, ReadabilityNode } from "./types.js";
-/** Options for the inexpensive readerability estimate. */
-export interface ReaderableOptions {
-    minContentLength?: number;
-    minScore?: number;
-    visibilityChecker?: (node: ReadabilityNode) => boolean;
-}
-/** Estimates whether a document contains enough prose for article extraction. */
-export declare function isProbablyReaderable(document: ReadabilityDocument, options?: ReaderableOptions | ((node: ReadabilityNode) => boolean)): boolean;

package/dist/types/readability/types.d.ts

@@ -1,70 +0,0 @@
-/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
-/** Minimal standards-shaped DOM node accepted by the readability extractor. */
-export interface ReadabilityNode {
-    readonly nodeType: number;
-    readonly nodeName: string;
-    readonly tagName?: string;
-    readonly ownerDocument?: ReadabilityDocument | null;
-    parentNode: ReadabilityNode | null;
-    readonly children?: ArrayLike<ReadabilityElement>;
-    readonly childNodes: ArrayLike<ReadabilityNode>;
-    readonly firstChild: ReadabilityNode | null;
-    readonly textContent: string | null;
-    appendChild(node: ReadabilityNode): ReadabilityNode;
-    cloneNode(deep?: boolean): ReadabilityNode;
-    remove(): void;
-}
-/** Minimal standards-shaped DOM element accepted by the readability extractor. */
-export interface ReadabilityElement extends ReadabilityNode {
-    readonly children: ArrayLike<ReadabilityElement>;
-    readonly tagName: string;
-    id: string;
-    className: string;
-    innerHTML: string;
-    readonly attributes: ArrayLike<{
-        readonly name: string;
-        readonly value: string;
-    }>;
-    getAttribute(name: string): string | null;
-    hasAttribute(name: string): boolean;
-    setAttribute(name: string, value: string): void;
-    removeAttribute(name: string): void;
-    getElementsByTagName(name: string): ArrayLike<ReadabilityElement>;
-    querySelector(selector: string): ReadabilityElement | null;
-    querySelectorAll(selector: string): ArrayLike<ReadabilityElement>;
-}
-/** Minimal standards-shaped document accepted by the readability extractor. */
-export interface ReadabilityDocument extends ReadabilityNode {
-    title: string;
-    readonly body: ReadabilityElement | null;
-    readonly documentElement: ReadabilityElement | null;
-    createElement(name: string): ReadabilityElement;
-    getElementsByTagName(name: string): ArrayLike<ReadabilityElement>;
-    querySelector(selector: string): ReadabilityElement | null;
-    querySelectorAll(selector: string): ArrayLike<ReadabilityElement>;
-}
-/** Configuration for article extraction. */
-export interface ReadabilityOptions<T = string> {
-    debug?: boolean;
-    maxElemsToParse?: number;
-    nbTopCandidates?: number;
-    charThreshold?: number;
-    classesToPreserve?: string[];
-    keepClasses?: boolean;
-    serializer?: (node: ReadabilityNode) => T;
-    disableJSONLD?: boolean;
-    allowedVideoRegex?: RegExp;
-}
-/** Extracted article and metadata. */
-export interface ReadabilityArticle<T = string> {
-    title: string | null | undefined;
-    content: T | null | undefined;
-    textContent: string | null | undefined;
-    length: number | null | undefined;
-    excerpt: string | null | undefined;
-    byline: string | null | undefined;
-    dir: string | null | undefined;
-    siteName: string | null | undefined;
-    lang: string | null | undefined;
-    publishedTime: string | null | undefined;
-}

package/dist/types/readability.d.ts

@@ -1,4 +0,0 @@
-/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
-export { Readability } from "./readability/readability.js";
-export { isProbablyReaderable, type ReaderableOptions } from "./readability/readerable.js";
-export type { ReadabilityArticle, ReadabilityDocument, ReadabilityElement, ReadabilityNode, ReadabilityOptions, } from "./readability/types.js";

package/dist/types/ring.d.ts

@@ -1,93 +0,0 @@
-/**
- * A fixed-capacity circular buffer that supports efficient push/pop/shift/unshift operations.
- * When the buffer is full, adding new items overwrites the oldest items (FIFO behavior).
- *
- * @template T The type of elements stored in the buffer.
- */
-export declare class RingBuffer<T> {
-    #private;
-    readonly capacity: number;
-    /**
-     * Creates a new ring buffer with the specified capacity.
-     *
-     * @param capacity - The maximum number of elements the buffer can hold. Must be positive.
-     */
-    constructor(capacity: number);
-    /**
-     * The number of elements currently in the buffer.
-     */
-    get length(): number;
-    /**
-     * Whether the buffer is at full capacity.
-     */
-    get isFull(): boolean;
-    /**
-     * Whether the buffer is empty (contains no elements).
-     */
-    get isEmpty(): boolean;
-    /**
-     * Adds an item to the end of the buffer.
-     * If the buffer is full, the oldest item is overwritten and returned.
-     *
-     * @param item - The item to add.
-     * @returns The overwritten item if the buffer was full, otherwise `undefined`.
-     */
-    push(item: T): T | undefined;
-    /**
-     * Removes and returns the first (oldest) item from the buffer.
-     *
-     * @returns The removed item, or `undefined` if the buffer is empty.
-     */
-    shift(): T | undefined;
-    /**
-     * Removes and returns the last (newest) item from the buffer.
-     *
-     * @returns The removed item, or `undefined` if the buffer is empty.
-     */
-    pop(): T | undefined;
-    /**
-     * Adds an item to the beginning of the buffer.
-     * If the buffer is full, the newest item is overwritten and returned.
-     *
-     * @param item - The item to add.
-     * @returns The overwritten item if the buffer was full, otherwise `undefined`.
-     */
-    unshift(item: T): T | undefined;
-    /**
-     * Returns the element at the specified index without removing it.
-     * Supports negative indices (e.g., `-1` for the last element).
-     *
-     * @param index - The zero-based index, or negative index from the end.
-     * @returns The element at the index, or `undefined` if the index is out of bounds.
-     */
-    at(index: number): T | undefined;
-    /**
-     * Returns the first (oldest) element without removing it.
-     *
-     * @returns The first element, or `undefined` if the buffer is empty.
-     */
-    peek(): T | undefined;
-    /**
-     * Returns the last (newest) element without removing it.
-     *
-     * @returns The last element, or `undefined` if the buffer is empty.
-     */
-    peekBack(): T | undefined;
-    /**
-     * Removes all elements from the buffer, resetting it to an empty state.
-     */
-    clear(): void;
-    /**
-     * Returns an iterator that yields elements in logical order (oldest to newest).
-     * Allows the buffer to be used with `for...of` loops and spread syntax.
-     *
-     * @yields Elements in FIFO order.
-     */
-    [Symbol.iterator](): Iterator<T>;
-    /**
-     * Creates a new array containing all elements in logical order (oldest to newest).
-     *
-     * @returns A new array with all buffer elements.
-     */
-    toArray(): T[];
-}