/** * Copyright (c) Meta Platforms, Inc. and affiliates. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. * * @format * @lightSyntaxTransform * @oncall memory_lab */ import type { IHeapSnapshot, RawHeapSnapshot } from './Types'; /** * A file writer that owns exactly one buffer for its lifetime. * * `fs.writeSync` rather than a write stream on purpose: a stream would need * backpressure handling on every one of ~42M appends, and the only thing that * buys is overlapping I/O with a loop that is already I/O-bound. The reader * side (`StringLoader`) is shaped the same way, so the two are symmetric. * * @internal */ export declare class ChunkedFileWriter { private fd; private buf; private len; constructor(file: string, bufferSize?: number); /** * Append ASCII-only text. Callers use this for numbers and punctuation, * where byte length equals character length, so the capacity check needs no * `Buffer.byteLength` call — that check is otherwise the hot cost in a loop * that runs once per array element. */ writeAscii(text: string): void; /** Append arbitrary text, measured in bytes rather than characters. */ write(text: string): void; private flush; close(): void; } /** Numeric arrays reach us as typed arrays from the parser or plain arrays. */ type NumericArrayLike = ArrayLike; /** * Append `"field":[a,b,c]` without ever materializing the array as a string. * * @param writer the open writer to append to * @param field the JSON field name to emit * @param values the numeric values of the field, typed array or plain array * * @internal */ export declare function writeNumericArrayField(writer: ChunkedFileWriter, field: string, values: NumericArrayLike): void; /** * Append `"strings":[...]`, escaping one entry at a time. * * `JSON.stringify` is called per element rather than on the array so the * largest transient string is one heap string, not the whole table. Escaping * is delegated to it rather than hand-rolled because the table routinely holds * lone surrogates and control characters that a naive escaper corrupts into a * file Chrome DevTools will not open. * * @param writer the open writer to append to * @param field the JSON field name to emit * @param values the string table entries, in index order * * @internal */ export declare function writeStringArrayField(writer: ChunkedFileWriter, field: string, values: ArrayLike): void; /** * Serialize a `RawHeapSnapshot` to `outputFile`. * * The `snapshot` header is the one field stringified whole — it is a few * hundred bytes, and doing so preserves any key V8 added that * `HeapSnapshotInfo` does not model (`extra_native_bytes` is already one such). * * @param raw the raw snapshot data to write * @param outputFile absolute path of the `.heapsnapshot` file to create, * overwritten if it already exists * * @internal */ export declare function serializeRawHeapSnapshot(raw: RawHeapSnapshot, outputFile: string): void; /** * Write a parsed (and possibly modified) heap snapshot to a `.heapsnapshot` * file that Chrome DevTools, memlab and any other V8 snapshot reader can open. * * This is the inverse of parsing, and it makes "load a snapshot, change it, * save it" a supported workflow — {@link anonymizeHeapSnapshot} is one such * consumer. * * Edits made through the snapshot's underlying data are picked up * automatically: node names are read out of the string table on every access * rather than cached, so a rewritten string table is already what the * in-memory snapshot reports. * * The file is streamed out through a single fixed buffer, one array element at * a time. That is a hard requirement rather than an optimization: V8 caps a * string at 512 MB (`buffer.constants.MAX_STRING_LENGTH`), so building the * document — or even one of its larger arrays — as a string throws * `RangeError: Invalid string length` on a large capture instead of merely * running slowly. * * @param snapshot the heap snapshot to write, as returned by * `getFullHeapFromFile` or {@link takeNodeMinimalHeap} * @param outputFile absolute path of the file to create; an existing file at * that path is overwritten * @returns this API returns void; the snapshot is written to `outputFile` * * * **Examples**: * ```typescript * import type {IHeapSnapshot} from '@memlab/core'; * import {dumpNodeHeapSnapshot, serializeHeapSnapshot} from '@memlab/core'; * import {getFullHeapFromFile} from '@memlab/heap-analysis'; * * (async function () { * const file = dumpNodeHeapSnapshot(); * const heap: IHeapSnapshot = await getFullHeapFromFile(file); * * // ... modify the heap snapshot in memory ... * * serializeHeapSnapshot(heap, '/tmp/modified.heapsnapshot'); * })(); * ``` */ export declare function serializeHeapSnapshot(snapshot: IHeapSnapshot, outputFile: string): void; export {}; //# sourceMappingURL=HeapSerializer.d.ts.map