@l1yp/file-viewer 0.1.0

package/dist/lib/hprof.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Streaming HPROF (JVM heap dump) parser — no dependency, no WASM, memory-bounded.
+ *
+ * An `.hprof` file is a header followed by self-describing top-level records; the big HEAP_DUMP /
+ * HEAP_DUMP_SEGMENT records hold an inner stream of sub-records (CLASS_DUMP / INSTANCE_DUMP / ARRAY_DUMP /
+ * GC roots) with NO length prefix, so those must be walked byte-exactly. Because a heap dump can be many GB,
+ * we never load the whole file into the JS heap:
+ *
+ *   - {@link ByteReader} pulls the file in 8 MB chunks off a {@link Blob} (the browser keeps the Blob itself,
+ *     possibly disk-backed); its `skip(n)` advances the cursor WITHOUT reading the skipped bytes into memory,
+ *     so the field data / array elements a preview never needs are never materialized.
+ *   - Pass A ({@link Hprof.parse}) makes ONE streaming sweep and keeps only *bounded* state: a per-class
+ *     histogram (instances + shallow bytes), the class → name / super / instance-field layout tables, and the
+ *     name string table. Nothing scales with the instance count.
+ *   - Pass B ({@link Hprof.collect}) answers "show me the objects of THIS class" with a second streaming sweep
+ *     that decodes only the target class's instances and collects at most {@link MAX_COLLECT} lightweight rows
+ *     (id + shallow size + decoded fields), skipping everything else. Memory stays ∝ the cap, independent of
+ *     how many instances the class actually has — the UI paginates the cap and, when a class overflows it,
+ *     re-runs Pass B with a field/id filter so search still spans the WHOLE file (see HprofViewer.vue).
+ *
+ * Shallow size only (field/element bytes + a ~2-pointer object-header estimate); retained size / dominator
+ * trees need the full reference graph (a second indexing pass, à la Eclipse MAT) and are out of scope.
+ *
+ * The record layout follows the JDK HPROF "binary dump format" (agent header + 1.0.2 segmented heap dumps).
+ */
+/** Thrown when the bytes aren't a recognizable HPROF file, or the stream ends mid-record. */
+export declare class HprofParseError extends Error {
+    constructor(message: string);
+}
+/** A resolved field slot in an instance's on-disk layout (this class's fields, then each superclass's). */
+export interface HprofField {
+    name: string;
+    type: number;
+}
+/** One decoded field value of an instance. `kind` styles the display (a plain value, or an object reference). */
+export interface HprofFieldValue {
+    name: string;
+    /** Display string: the primitive value, `'A'` for char, `null` / `#<id>` for object references. */
+    value: string;
+    kind: 'prim' | 'ref' | 'null';
+    /** For `kind==='ref'` (non-null): the bare target object id, so the UI can jump to / dereference it. */
+    refId?: string;
+}
+/**
+ * A best-effort content preview of an array object (bounded — at most {@link MAX_ARRAY_PREVIEW} elements /
+ * {@link MAX_DEREF_BYTES} bytes are ever read). `char[]` / printable `byte[]` decode to `text`; `byte[]` also
+ * carries `hex`; numeric arrays and object arrays list their elements (object elements are `#<id>` references).
+ */
+export interface HprofArrayPreview {
+    /** Basic-type tag for a primitive array; undefined for an object array. */
+    elemType?: number;
+    /** Element class name for an object array (e.g. `java/lang/String`). */
+    elemClassName?: string;
+    /** True element count (the preview may be shorter). */
+    length: number;
+    /** Decoded text (`char[]` big-endian UTF-16, or a printable `byte[]` as Latin-1). */
+    text?: string;
+    /** First bytes of a `byte[]` as hex. */
+    hex?: string;
+    /** Element renderings: numeric values, or `#<id>` object references (each may carry its own `refId`). */
+    elements?: HprofFieldValue[];
+    /** True when the preview is a prefix of the whole array. */
+    truncated: boolean;
+}
+/** One object of a class in the drill-in list. */
+export interface HprofInstance {
+    /** The instance's own object id (decimal string). */
+    id: string;
+    /** Shallow size estimate (field bytes + object-header estimate), matching the histogram. */
+    size: number;
+    /** Decoded instance fields in on-disk order; empty when the layout couldn't be resolved (or an array). */
+    fields: HprofFieldValue[];
+    /** Present when this "object" is actually an array — its bounded content preview. */
+    array?: HprofArrayPreview;
+}
+/** What {@link Hprof.collect} drills into: a real class, or an array pseudo-class keyed by element type/class. */
+export type CollectTarget = {
+    kind: 'class';
+    classObjId: string;
+} | {
+    kind: 'primArray';
+    elemType: number;
+} | {
+    kind: 'objArray';
+    elemClassId: string;
+};
+/** A class (or array pseudo-class) row of the histogram. */
+export interface HprofClassRow {
+    name: string;
+    count: number;
+    bytes: number;
+    /** Drill-in descriptor — present on every row (classes and arrays are both drillable). */
+    target?: CollectTarget;
+}
+/** The resolved view of a single object id, produced by {@link Hprof.resolveObjects} (jump / dereference). */
+export type HprofObjectView = {
+    id: string;
+    kind: 'instance';
+    className: string;
+    size: number;
+    fields: HprofFieldValue[];
+} | {
+    id: string;
+    kind: 'primArray';
+    className: string;
+    size: number;
+    length: number;
+    elemType: number;
+    /** Raw element bytes, capped at {@link MAX_DEREF_BYTES} — lets the caller decode with a String coder. */
+    rawBytes: Uint8Array;
+    array: HprofArrayPreview;
+} | {
+    id: string;
+    kind: 'objArray';
+    className: string;
+    size: number;
+    length: number;
+    array: HprofArrayPreview;
+} | {
+    id: string;
+    kind: 'class';
+    className: string;
+};
+export interface HprofSummary {
+    idSize: number;
+    /** Dump time — epoch milliseconds as a string (may exceed 2^53). */
+    timestamp: string;
+    fileSize: number;
+    recordCount: number;
+    classCount: number;
+    instanceCount: number;
+    gcRoots: number;
+    stringCount: number;
+    /** Total shallow bytes across all objects + arrays. */
+    heapBytes: number;
+    /** Histogram rows, sorted by shallow bytes descending. */
+    rows: HprofClassRow[];
+}
+/** Result of a per-class object collection (Pass B). */
+export interface HprofCollectResult {
+    /** Collected rows (≤ {@link MAX_COLLECT}); when filtering, only matches. */
+    rows: HprofInstance[];
+    /** Total instances of the class in the file (or, when filtering, total matches). */
+    total: number;
+    /** True when `total` exceeded the cap, so `rows` is a prefix — the UI should offer whole-file search. */
+    truncated: boolean;
+}
+export interface HprofProgress {
+    (pos: number, size: number): void;
+}
+interface CollectOptions {
+    /** Max rows to keep (default {@link MAX_COLLECT}). */
+    limit?: number;
+    /** Keep only instances whose id or any decoded field value contains this (case-insensitive) text. */
+    filter?: string;
+    onProgress?: HprofProgress;
+}
+/** Cap on rows Pass B keeps in memory for one class — bounds memory regardless of the real instance count. */
+export declare const MAX_COLLECT = 10000;
+/** Cap on array elements listed in one preview — bounds memory when an array (or String) is huge. */
+export declare const MAX_ARRAY_PREVIEW = 256;
+/** Cap on raw bytes read per array object when dereferencing (String text / byte[] hex) — bounds memory. */
+export declare const MAX_DEREF_BYTES = 8192;
+/**
+ * Decode a `java.lang.String`'s backing array bytes to text. Legacy `char[]` (Java 8) is big-endian UTF-16;
+ * Java 9+ `byte[]` is LATIN1 when `coder===0`, else in-memory UTF-16 (little-endian). `coder` comes from the
+ * String instance's own decoded `coder` field (null for the char[] layout).
+ */
+export declare function decodeStringValue(raw: Uint8Array, elemType: number, coder: number | null): string;
+/**
+ * A parsed heap dump. {@link parse} runs Pass A and returns this handle; {@link summary} feeds the histogram UI,
+ * and {@link collect} runs Pass B on demand for one class. The originating Blob + the bounded class/name tables
+ * are retained so drill-in needs no re-parse of Pass A.
+ */
+export declare class Hprof {
+    private readonly blob;
+    private readonly idSize;
+    private readonly classInfo;
+    private readonly classNames;
+    private readonly strings;
+    private readonly layoutCache;
+    readonly summary: HprofSummary;
+    private constructor();
+    /** Class name for an object id (falls back to a synthetic `<class#id>`). */
+    classNameOf(classObjId: string): string;
+    /**
+     * Resolve the on-disk instance-field layout: this class's declared fields, then each superclass's, up the
+     * chain (the order INSTANCE_DUMP lays field data out in). Cached. Returns null if a class in the chain has no
+     * CLASS_DUMP (can't compute the layout) — the caller then shows id + size only.
+     */
+    private resolveLayout;
+    static parse(blob: Blob, onProgress?: HprofProgress): Promise<Hprof>;
+    /**
+     * Pass B: stream the file again and collect the objects of one drill-in target — a class (its instances), a
+     * primitive-array type, or an object-array type. Decodes only matching objects (skipping everything else),
+     * keeping at most `limit` rows; with `filter`, keeps only rows whose id / field value / array content contains
+     * the (lower-cased) text — so a target that overflows the cap can still be searched across the WHOLE file.
+     * `total` counts every matching object even beyond the cap.
+     */
+    collect(target: CollectTarget, opts?: CollectOptions): Promise<HprofCollectResult>;
+    /** Read a bounded element-id preview of an object array (cursor just past its array-class id). */
+    private readObjArrayPreview;
+    /**
+     * Resolve a batch of object ids in ONE streaming sweep — the on-demand random access a preview needs to follow
+     * a reference (jump to an object) or dereference a value (a String's backing `byte[]`/`char[]`). Class-object
+     * ids resolve without scanning. Only ids actually found are returned (GC'd / unknown ids are absent). Bounded:
+     * array content is capped (see {@link MAX_ARRAY_PREVIEW} / {@link MAX_DEREF_BYTES}), so memory stays ∝ the batch.
+     */
+    resolveObjects(ids: Set<string>, onProgress?: HprofProgress): Promise<Map<string, HprofObjectView>>;
+}
+export {};