@tgsnake/bytesio 2.0.1 → 2.1.0-browser.0

package/dist/src/BytesIO.d.ts

@@ -8,6 +8,14 @@
  * it under the terms of the MIT License as published.
  */
 import { Buffer } from './deps.js';
+/**
+ * Standard seek origin flags matching POSIX and Python's `io` module.
+ */
+export declare enum SeekOrigin {
+    SEEK_SET = 0,
+    SEEK_CUR = 1,
+    SEEK_END = 2
+}
 /**
  * A versatile in-memory binary stream class utilizing Node.js `Buffer`s.
  * Mimics the behavior of Python's built-in `io.BytesIO` module, providing a stream-like
@@ -39,7 +47,7 @@ import { Buffer } from './deps.js';
  * const stream = BytesIO.from('Hello, World!', 'utf-8');
  *
  * // Seek to position 7 (from the beginning of the buffer)
- * stream.seek(7, 0);
+ * stream.seek(7, BytesIO.SEEK_SET);
  *
  * // Read remaining bytes
  * const msg = stream.read().toString('utf-8');
@@ -47,6 +55,18 @@ import { Buffer } from './deps.js';
  * ```
  */
 export declare class BytesIO {
+    /**
+     * Seek relative to the beginning of the stream. Offset must be >= 0.
+     */
+    static readonly SEEK_SET: number;
+    /**
+     * Seek relative to the current stream position.
+     */
+    static readonly SEEK_CUR: number;
+    /**
+     * Seek relative to the end of the stream.
+     */
+    static readonly SEEK_END: number;
     /**
      * The raw internal Node.js Buffer instance where binary data is stored.
      * @private
@@ -56,45 +76,108 @@ export declare class BytesIO {
      * The current internal read/write pointer position (byte offset).
      * @private
      */
-    private _post;
+    private _pos;
+    /**
+     * Indicates whether the stream has been closed.
+     * @private
+     */
+    private _closed;
     /**
      * Initializes a new instance of the `BytesIO` class.
      *
      * @param buffer - The initial binary buffer to populate the `BytesIO` instance with. Defaults to an empty buffer.
      */
-    constructor(buffer?: Buffer);
+    constructor(buffer?: Buffer | Uint8Array);
+    /**
+     * Internal helper to verify that the stream has not been closed.
+     * @private
+     */
+    private _checkClosed;
     /**
      * Adjusts the position of the internal read/write pointer (offset cursor).
      *
      * @param offset - The byte offset relative to the reference point defined by `whence`.
-     *                 - If `whence` is `0`, must be 0 or positive.
-     *                 - If `whence` is `2`, must be less than 0.
+     *                 - If `whence` is `0`, must be 0 or a positive number.
+     *                 - If `whence` is `1`, relative to the current position.
+     *                 - If `whence` is `2`, relative to the end of the buffer (supports 0 for EOF, negative offsets, and clamps underflow to 0).
      * @param whence - The reference point for the seek operation:
-     *                 - `0` (default): Absolute positioning from the start of the buffer.
-     *                 - `1`: Relative positioning from the current pointer position.
-     *                 - `2`: Relative positioning from the end of the buffer (expects a negative `offset`).
+     *                 - `0` (`SEEK_SET`, default): Absolute positioning from the start of the buffer.
+     *                 - `1` (`SEEK_CUR`): Relative positioning from the current pointer position.
+     *                 - `2` (`SEEK_END`): Relative positioning from the end of the buffer.
      * @returns The new pointer position (relative to the start of the buffer).
      * @throws {Error} If `whence` is `0` and `offset` is negative.
-     * @throws {Error} If `whence` is `2` and `offset` is non-negative.
-     * @throws {Error} If `whence` is `2` and the absolute seek location would be less than 0.
      * @throws {Error} If `whence` is not `0`, `1`, or `2`.
      */
     seek(offset: number, whence?: number): number;
+    /**
+     * Returns the current stream position (cursor offset).
+     * Parity with Python's `BytesIO.tell()`.
+     *
+     * @returns Current byte offset.
+     */
+    tell(): number;
+    /**
+     * Flushes the stream buffers (no-op for in-memory streams, provided for stream parity).
+     */
+    flush(): void;
+    /**
+     * Returns whether this stream is readable.
+     */
+    readable(): boolean;
+    /**
+     * Returns whether this stream is writable.
+     */
+    writable(): boolean;
+    /**
+     * Returns whether this stream supports random access / seeking.
+     */
+    seekable(): boolean;
+    /**
+     * Flushes and closes the stream. Once closed, any further read, write, or seek operations will throw an error.
+     */
+    close(): void;
+    /**
+     * Returns a copy of the entire buffer contents.
+     * Parity with Python's `BytesIO.getvalue()`.
+     *
+     * @returns An independent `Buffer` copy containing the full stream contents.
+     */
+    getvalue(): Buffer;
+    /**
+     * Returns a direct view of the underlying buffer without copying memory.
+     * Parity with Python's `BytesIO.getbuffer()`.
+     *
+     * @returns The underlying `Buffer` instance.
+     */
+    getbuffer(): Buffer;
+    /**
+     * Truncates the stream to the specified size (in bytes).
+     * If `size` is omitted, it defaults to the current pointer position.
+     * If the new size is larger than the current buffer, it is padded with null bytes (`0x00`).
+     * The current stream position is not changed.
+     *
+     * @param size - The target size in bytes. Defaults to current cursor position.
+     * @returns The new size.
+     */
+    truncate(size?: number): number;
+    /**
+     * Returns bytes from the current stream position without advancing the pointer.
+     *
+     * @param size - Number of bytes to peek. If omitted or <= 0, peeks all remaining bytes.
+     * @returns A `Buffer` containing the peeked bytes.
+     */
+    peek(size?: number): Buffer;
     /**
      * Returns a new `BytesIO` instance populated with a subarray/slice of the current buffer.
-     * The slice is created using the standard `Buffer.subarray` method, meaning it shares the same
+     * The slice is created using `Buffer.subarray`, meaning it shares the same
      * allocated memory as the original buffer.
      *
      * @param args - Arguments passed directly to the underlying `Buffer.subarray` method.
-     *               Typically `[start[, end]]`, where `start` is the starting index (default 0) and
-     *               `end` is the ending index (exclusive, default buffer length).
      * @returns A new `BytesIO` instance containing the sliced view of the buffer.
      */
     slice(...args: Array<any>): BytesIO;
     /**
      * Returns a JSON representation of the underlying buffer.
-     * This is useful for serializing the binary data, representing it as an object
-     * containing a `type` property (typically `"Buffer"`) and a `data` array of byte values.
      *
      * @returns An object representing the buffer in JSON format.
      */
@@ -106,10 +189,6 @@ export declare class BytesIO {
      * Decodes the underlying buffer to a string according to the specified encoding.
      *
      * @param args - Arguments passed directly to the underlying `Buffer.toString` method.
-     *               Typically `[encoding[, start[, end]]]`, where:
-     *               - `encoding` is the character encoding to use (e.g., `'utf8'`, `'hex'`, `'base64'`).
-     *               - `start` is the byte offset to start decoding (default 0).
-     *               - `end` is the byte offset to stop decoding (exclusive, default buffer length).
      * @returns The decoded string representation of the buffer.
      */
     toString(...args: Array<any>): string;
@@ -118,17 +197,54 @@ export declare class BytesIO {
      * Advances the internal pointer by the number of bytes successfully read.
      *
      * @param length - The number of bytes to read.
-     *                 - If `undefined` or not provided, reads all remaining bytes from the current pointer to the end of the buffer.
+     *                 - If `undefined` or negative (e.g. `-1`), reads all remaining bytes to the end of the buffer.
      *                 - If provided, reads at most `length` bytes from the current pointer position.
-     * @returns A new `Buffer` containing the read bytes. If the pointer is out of bounds or `length` is less than 1, returns an empty buffer.
+     * @returns A new `Buffer` containing the read bytes. If the pointer is at or past EOF, returns an empty buffer.
      */
     read(length?: number): Buffer;
+    /**
+     * Writes binary data at the current stream pointer position.
+     *
+     * @remarks
+     * If the current pointer is before the end of the buffer, existing bytes are overwritten in-place.
+     * If the current pointer is beyond the end of the buffer, the buffer is padded with null bytes (`0x00`) up to the pointer.
+     * Advances the pointer by the number of bytes written.
+     *
+     * @param data - The `Buffer`, `Uint8Array`, or `string` containing the data to write.
+     * @param encoding - The character encoding if `data` is a string. Defaults to `'utf-8'`.
+     * @returns The current `BytesIO` instance, enabling method chaining.
+     */
+    write(data: Buffer | Uint8Array | string, encoding?: BufferEncoding): this;
+    /**
+     * Reads a signed 8-bit integer from the current pointer position.
+     */
+    readInt8(size?: number): number;
+    /**
+     * Reads an unsigned 8-bit integer from the current pointer position.
+     */
+    readUInt8(size?: number): number;
+    /**
+     * Reads a signed 16-bit integer in little-endian format (`Int16LE`).
+     */
+    readInt16LE(size?: number): number;
+    /**
+     * Reads a signed 16-bit integer in big-endian format (`Int16BE`).
+     */
+    readInt16BE(size?: number): number;
+    /**
+     * Reads an unsigned 16-bit integer in little-endian format (`UInt16LE`).
+     */
+    readUInt16LE(size?: number): number;
+    /**
+     * Reads an unsigned 16-bit integer in big-endian format (`UInt16BE`).
+     */
+    readUInt16BE(size?: number): number;
     /**
      * Reads a signed 32-bit integer in little-endian format (`Int32LE`) from the current pointer position.
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `4`.
-     * @returns The read signed 32-bit integer (value ranges from -2,147,483,648 to 2,147,483,647).
+     * @returns The read signed 32-bit integer.
      */
     readInt32LE(size?: number): number;
     /**
@@ -136,7 +252,7 @@ export declare class BytesIO {
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `4`.
-     * @returns The read signed 32-bit integer (value ranges from -2,147,483,648 to 2,147,483,647).
+     * @returns The read signed 32-bit integer.
      */
     readInt32BE(size?: number): number;
     /**
@@ -144,7 +260,7 @@ export declare class BytesIO {
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `4`.
-     * @returns The read unsigned 32-bit integer (value ranges from 0 to 4,294,967,295).
+     * @returns The read unsigned 32-bit integer.
      */
     readUInt32LE(size?: number): number;
     /**
@@ -160,7 +276,7 @@ export declare class BytesIO {
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `8`.
-     * @returns The read signed 64-bit BigInt (value ranges from -9,223,372,036,854,775,808n to 9,223,372,036,854,775,807n).
+     * @returns The read signed 64-bit BigInt.
      */
     readBigInt64LE(size?: number): bigint;
     /**
@@ -168,7 +284,7 @@ export declare class BytesIO {
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `8`.
-     * @returns The read signed 64-bit BigInt (value ranges from -9,223,372,036,854,775,808n to 9,223,372,036,854,775,807n).
+     * @returns The read signed 64-bit BigInt.
      */
     readBigInt64BE(size?: number): bigint;
     /**
@@ -176,7 +292,7 @@ export declare class BytesIO {
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `8`.
-     * @returns The read unsigned 64-bit BigInt (value ranges from 0n to 18,446,744,073,709,551,615n).
+     * @returns The read unsigned 64-bit BigInt.
      */
     readBigUInt64LE(size?: number): bigint;
     /**
@@ -184,11 +300,11 @@ export declare class BytesIO {
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `8`.
-     * @returns The read unsigned 64-bit BigInt (value ranges from 0n to 18,446,744,073,709,551,615n).
+     * @returns The read unsigned 64-bit BigInt.
      */
     readBigUInt64BE(size?: number): bigint;
     /**
-     * Reads a 64-bit double-precision floating-point number in little-endian format (`DoubleLE`) from the current pointer position.
+     * Reads a 64-bit double-precision floating-point number in little-endian format (`DoubleLE`).
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `8`.
@@ -196,7 +312,7 @@ export declare class BytesIO {
      */
     readDoubleLE(size?: number): number;
     /**
-     * Reads a 64-bit double-precision floating-point number in big-endian format (`DoubleBE`) from the current pointer position.
+     * Reads a 64-bit double-precision floating-point number in big-endian format (`DoubleBE`).
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `8`.
@@ -204,7 +320,7 @@ export declare class BytesIO {
      */
     readDoubleBE(size?: number): number;
     /**
-     * Reads a 32-bit single-precision floating-point number in little-endian format (`FloatLE`) from the current pointer position.
+     * Reads a 32-bit single-precision floating-point number in little-endian format (`FloatLE`).
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `4`.
@@ -212,7 +328,7 @@ export declare class BytesIO {
      */
     readFloatLE(size?: number): number;
     /**
-     * Reads a 32-bit single-precision floating-point number in big-endian format (`FloatBE`) from the current pointer position.
+     * Reads a 32-bit single-precision floating-point number in big-endian format (`FloatBE`).
      * Automatically advances the pointer by the specified `size` of bytes.
      *
      * @param size - The number of bytes to advance the pointer after reading. Defaults to `4`.
@@ -220,16 +336,77 @@ export declare class BytesIO {
      */
     readFloatBE(size?: number): number;
     /**
-     * Appends the provided binary data to the absolute end of the underlying buffer.
-     *
-     * @remarks
-     * This operation concatenates the new data to the existing buffer, increasing its total length.
-     * Note that this method does not modify or advance the current pointer position (`post`).
-     *
-     * @param data - The `Buffer` containing the binary data to append.
-     * @returns The current `BytesIO` instance, enabling method chaining.
+     * Writes a signed 8-bit integer at the current stream pointer position.
+     */
+    writeInt8(value: number): this;
+    /**
+     * Writes an unsigned 8-bit integer at the current stream pointer position.
+     */
+    writeUInt8(value: number): this;
+    /**
+     * Writes a signed 16-bit integer in little-endian format at the current stream pointer position.
+     */
+    writeInt16LE(value: number): this;
+    /**
+     * Writes a signed 16-bit integer in big-endian format at the current stream pointer position.
+     */
+    writeInt16BE(value: number): this;
+    /**
+     * Writes an unsigned 16-bit integer in little-endian format at the current stream pointer position.
+     */
+    writeUInt16LE(value: number): this;
+    /**
+     * Writes an unsigned 16-bit integer in big-endian format at the current stream pointer position.
+     */
+    writeUInt16BE(value: number): this;
+    /**
+     * Writes a signed 32-bit integer in little-endian format at the current stream pointer position.
+     */
+    writeInt32LE(value: number): this;
+    /**
+     * Writes a signed 32-bit integer in big-endian format at the current stream pointer position.
+     */
+    writeInt32BE(value: number): this;
+    /**
+     * Writes an unsigned 32-bit integer in little-endian format at the current stream pointer position.
+     */
+    writeUInt32LE(value: number): this;
+    /**
+     * Writes an unsigned 32-bit integer in big-endian format at the current stream pointer position.
+     */
+    writeUInt32BE(value: number): this;
+    /**
+     * Writes a signed 64-bit BigInt in little-endian format at the current stream pointer position.
+     */
+    writeBigInt64LE(value: bigint): this;
+    /**
+     * Writes a signed 64-bit BigInt in big-endian format at the current stream pointer position.
+     */
+    writeBigInt64BE(value: bigint): this;
+    /**
+     * Writes an unsigned 64-bit BigInt in little-endian format at the current stream pointer position.
      */
-    write(data: Buffer): BytesIO;
+    writeBigUInt64LE(value: bigint): this;
+    /**
+     * Writes an unsigned 64-bit BigInt in big-endian format at the current stream pointer position.
+     */
+    writeBigUInt64BE(value: bigint): this;
+    /**
+     * Writes a 32-bit single-precision floating-point number in little-endian format at the current stream pointer position.
+     */
+    writeFloatLE(value: number): this;
+    /**
+     * Writes a 32-bit single-precision floating-point number in big-endian format at the current stream pointer position.
+     */
+    writeFloatBE(value: number): this;
+    /**
+     * Writes a 64-bit double-precision floating-point number in little-endian format at the current stream pointer position.
+     */
+    writeDoubleLE(value: number): this;
+    /**
+     * Writes a 64-bit double-precision floating-point number in big-endian format at the current stream pointer position.
+     */
+    writeDoubleBE(value: number): this;
     /**
      * Allocates a new `BytesIO` instance populated with a zero-filled buffer of the specified size.
      *
@@ -242,17 +419,17 @@ export declare class BytesIO {
      *
      * @param input - The input data. Can be a `Buffer`, `Uint8Array`, `ArrayBuffer`, `SharedArrayBuffer`,
      *                an `Array` of numbers, a `string`, or an object with a `valueOf` or `Symbol.toPrimitive` method.
-     * @param encode - The character encoding to use if the `input` is a string (e.g., `'utf8'`, `'hex'`, `'base64'`).
+     * @param encode - The character encoding to use if the `input` is a string.
      * @returns A new `BytesIO` instance initialized with the parsed input data.
      */
-    static from(input: any, encode?: any): BytesIO;
+    static from(input: any, encode?: BufferEncoding): BytesIO;
     /**
-     * Concatenates an array of `Buffer` instances into a single `BytesIO` instance.
+     * Concatenates an array of `Buffer` or `Uint8Array` instances into a single `BytesIO` instance.
      *
-     * @param data - An array of `Buffer` objects to be joined together in order.
+     * @param data - An array of `Buffer` or `Uint8Array` objects to be joined together in order.
      * @returns A new `BytesIO` instance containing the concatenated binary data.
      */
-    static concat(data: Array<Buffer>): BytesIO;
+    static concat(data: Array<Buffer | Uint8Array>): BytesIO;
     /**
      * Gets the total size of the underlying buffer in bytes.
      *
@@ -270,5 +447,9 @@ export declare class BytesIO {
      *
      * @returns The current pointer position.
      */
-    get post(): number;
+    get pos(): number;
+    /**
+     * Gets whether the stream has been closed.
+     */
+    get closed(): boolean;
 }