@fuman/io 0.0.2 → 0.0.3

package/bits/reader.cjs

@@ -6,6 +6,7 @@ class BitReader {
   #readable;
   #currentByte = 0;
   #currentBitIdx = 0;
+  /** @param readable  fuman readable stream */
   constructor(readable) {
     this.#readable = readable;
   }
@@ -41,6 +42,7 @@ class BitReader {
     }
     return result;
   }
+  /** read a number of bits from the stream, and return them as a number */
   readBits(size) {
     let result = 0;
     if (this.#currentBitIdx !== 0) {
@@ -71,6 +73,7 @@ class BitReader {
     }
     return result;
   }
+  /** read a number of bits from the stream, and return them as a bigint */
   readBitsBig(size) {
     let result = 0n;
     if (this.#currentBitIdx !== 0) {
@@ -102,6 +105,7 @@ class BitReader {
     }
     return result;
   }
+  /** skip a number of bits from the stream */
   skipBits(size) {
     if (size % 8 === 0) {
       const buf = strings.exactly(this.#readable, size / 8);

package/bits/reader.d.ts

@@ -1,6 +1,8 @@
 import { ISyncReadable } from '../types.js';
+/** a bit reader that reads bits from a byte-aligned stream */
 export declare class BitReader implements ISyncReadable {
     #private;
+    /** @param readable  fuman readable stream */
     constructor(readable: ISyncReadable);
     /** Whether the reader is currently aligned on a byte boundary */
     get isAligned(): boolean;
@@ -9,7 +11,10 @@ export declare class BitReader implements ISyncReadable {
     /** The current bit position within the last consumed byte */
     get bitPosition(): number;
     readSync(bytes: number): Uint8Array;
+    /** read a number of bits from the stream, and return them as a number */
     readBits(size: number): number;
+    /** read a number of bits from the stream, and return them as a bigint */
     readBitsBig(size: number): bigint;
+    /** skip a number of bits from the stream */
     skipBits(size: number): void;
 }

package/bits/reader.js

@@ -4,6 +4,7 @@ class BitReader {
   #readable;
   #currentByte = 0;
   #currentBitIdx = 0;
+  /** @param readable  fuman readable stream */
   constructor(readable) {
     this.#readable = readable;
   }
@@ -39,6 +40,7 @@ class BitReader {
     }
     return result;
   }
+  /** read a number of bits from the stream, and return them as a number */
   readBits(size) {
     let result = 0;
     if (this.#currentBitIdx !== 0) {
@@ -69,6 +71,7 @@ class BitReader {
     }
     return result;
   }
+  /** read a number of bits from the stream, and return them as a bigint */
   readBitsBig(size) {
     let result = 0n;
     if (this.#currentBitIdx !== 0) {
@@ -100,6 +103,7 @@ class BitReader {
     }
     return result;
   }
+  /** skip a number of bits from the stream */
   skipBits(size) {
     if (size % 8 === 0) {
       const buf = exactly(this.#readable, size / 8);

package/buf-reader.cjs

@@ -9,9 +9,6 @@ class BufReader {
   #readPos = 0;
   #writePos = 0;
   #eof = false;
-  static create(readable, size = DEFAULT_BUF_SIZE) {
-    return new BufReader(readable, size);
-  }
   constructor(readable, size = DEFAULT_BUF_SIZE) {
     if (size < MIN_BUF_SIZE) {
       size = MIN_BUF_SIZE;
@@ -19,9 +16,11 @@ class BufReader {
     this.#buffer = utils.u8.alloc(size);
     this.#readable = readable;
   }
+  /** the size of the buffer */
   get bufferSize() {
     return this.#buffer.byteLength;
   }
+  /** the number of bytes that are currently buffered */
   get buffered() {
     return this.#writePos - this.#readPos;
   }

package/buf-reader.d.ts

@@ -1,9 +1,10 @@
 import { IReadable } from './types.js';
 export declare class BufReader implements IReadable {
     #private;
-    static create(readable: IReadable, size?: number): BufReader;
     constructor(readable: IReadable, size?: number);
+    /** the size of the buffer */
     get bufferSize(): number;
+    /** the number of bytes that are currently buffered */
     get buffered(): number;
     read(into: Uint8Array): Promise<number>;
 }

package/buf-reader.js

@@ -7,9 +7,6 @@ class BufReader {
   #readPos = 0;
   #writePos = 0;
   #eof = false;
-  static create(readable, size = DEFAULT_BUF_SIZE) {
-    return new BufReader(readable, size);
-  }
   constructor(readable, size = DEFAULT_BUF_SIZE) {
     if (size < MIN_BUF_SIZE) {
       size = MIN_BUF_SIZE;
@@ -17,9 +14,11 @@ class BufReader {
     this.#buffer = u8.alloc(size);
     this.#readable = readable;
   }
+  /** the size of the buffer */
   get bufferSize() {
     return this.#buffer.byteLength;
   }
+  /** the number of bytes that are currently buffered */
   get buffered() {
     return this.#writePos - this.#readPos;
   }

package/bytes.cjs

@@ -3,11 +3,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const utils = require("@fuman/utils");
 const _utils = require("./_utils.cjs");
 class Bytes {
-  /** Underlying buffer */
   #buffer;
-  /** Position of the write cursor (should always be >= {@link #readPos}) */
   #writePos = 0;
-  /** Position of the read cursor */
   #readPos = 0;
   #preferredCapacity;
   constructor(buf) {
@@ -80,8 +77,14 @@ class Bytes {
     this.writeSync(bytes.length).set(bytes);
     this.disposeWriteSync();
   }
+  /**
+   * get the "result" of the buffer, i.e. everything that has been written so far,
+   * but not yet read
+   *
+   * **Note**: this method returns a view into the underlying buffer, and does advance the read cursor
+   */
   result() {
-    return this.#buffer.subarray(0, this.#writePos);
+    return this.#buffer.subarray(this.#readPos, this.#writePos);
   }
   /** Reclaim memory by only keeping the yet-unread data */
   reclaim() {
@@ -106,6 +109,7 @@ class Bytes {
     }
     this.#readPos -= n;
   }
+  /** reset the read/write cursors */
   reset() {
     this.#readPos = 0;
     this.#writePos = 0;

package/bytes.d.ts

@@ -1,4 +1,5 @@
 import { IReadable, ISyncReadable, ISyncWritable, IWritable } from './types.js';
+/** a byte buffer implementing fuman readable/writable streams */
 export declare class Bytes implements IReadable, IWritable, ISyncReadable, ISyncWritable {
     #private;
     constructor(buf: Uint8Array);
@@ -15,10 +16,17 @@ export declare class Bytes implements IReadable, IWritable, ISyncReadable, ISync
     writeSync(size: number): Uint8Array;
     disposeWriteSync(written?: number): void;
     write(bytes: Uint8Array): Promise<void>;
+    /**
+     * get the "result" of the buffer, i.e. everything that has been written so far,
+     * but not yet read
+     *
+     * **Note**: this method returns a view into the underlying buffer, and does advance the read cursor
+     */
     result(): Uint8Array;
     /** Reclaim memory by only keeping the yet-unread data */
     reclaim(): void;
     /** Mark last n bytes as unread */
     rewind(n: number): void;
+    /** reset the read/write cursors */
     reset(): void;
 }

package/bytes.js

@@ -1,11 +1,8 @@
 import { u8 } from "@fuman/utils";
 import { nextPowerOfTwo } from "./_utils.js";
 class Bytes {
-  /** Underlying buffer */
   #buffer;
-  /** Position of the write cursor (should always be >= {@link #readPos}) */
   #writePos = 0;
-  /** Position of the read cursor */
   #readPos = 0;
   #preferredCapacity;
   constructor(buf) {
@@ -78,8 +75,14 @@ class Bytes {
     this.writeSync(bytes.length).set(bytes);
     this.disposeWriteSync();
   }
+  /**
+   * get the "result" of the buffer, i.e. everything that has been written so far,
+   * but not yet read
+   *
+   * **Note**: this method returns a view into the underlying buffer, and does advance the read cursor
+   */
   result() {
-    return this.#buffer.subarray(0, this.#writePos);
+    return this.#buffer.subarray(this.#readPos, this.#writePos);
   }
   /** Reclaim memory by only keeping the yet-unread data */
   reclaim() {
@@ -104,6 +107,7 @@ class Bytes {
     }
     this.#readPos -= n;
   }
+  /** reset the read/write cursors */
   reset() {
     this.#readPos = 0;
     this.#writePos = 0;

package/codec/delimiter.cjs

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const utils = require("@fuman/utils");
 class DelimiterCodec {
+  /**
+   * @param delimiter  delimiter to use
+   * @param options  options
+   */
   constructor(delimiter, options) {
     this.delimiter = delimiter;
     this.options = options;

package/codec/delimiter.d.ts

@@ -1,6 +1,7 @@
 import { Bytes } from '../bytes.js';
 import { ISyncWritable } from '../types.js';
 import { IFrameDecoder, IFrameEncoder } from './types.js';
+/** options for {@link DelimiterCodec} */
 export interface DelimiterCodecOptions {
     /**
      * Strategy for handling delimiter.
@@ -8,13 +9,20 @@ export interface DelimiterCodecOptions {
      *  - `discard` - delimiter is discarded
      *
      * Ignored for encoding (delimiter is always appended after the frame)
+     *
+     * @default 'discard'
      */
     strategy?: 'keep' | 'discard';
 }
+/** a simple frame codec that uses a delimiter to separate frames */
 export declare class DelimiterCodec implements IFrameDecoder, IFrameEncoder {
     #private;
     readonly delimiter: Uint8Array;
     readonly options?: DelimiterCodecOptions | undefined;
+    /**
+     * @param delimiter  delimiter to use
+     * @param options  options
+     */
     constructor(delimiter: Uint8Array, options?: DelimiterCodecOptions | undefined);
     decode(buf: Bytes, eof: boolean): Uint8Array | null;
     encode(data: Uint8Array, into: ISyncWritable): void;

package/codec/delimiter.js

@@ -1,5 +1,9 @@
 import { typed } from "@fuman/utils";
 class DelimiterCodec {
+  /**
+   * @param delimiter  delimiter to use
+   * @param options  options
+   */
   constructor(delimiter, options) {
     this.delimiter = delimiter;
     this.options = options;

package/codec/length-delimited.d.ts

@@ -1,10 +1,22 @@
 import { Bytes } from '../bytes.js';
 import { ISyncWritable } from '../types.js';
 import { IFrameDecoder, IFrameEncoder } from './types.js';
+/** options for {@link LengthDelimitedCodec} */
 export interface LengthDelimitedCodecOptions {
+    /**
+     * function that will be called to read the length of the frame
+     *
+     * @example  `read.uint32le`
+     */
     read?: (r: Bytes) => number | null;
+    /**
+     * function that will be called to write the length of the frame
+     *
+     * @example  `write.uint32le`
+     */
     write?: (w: ISyncWritable, n: number) => void;
 }
+/** a simple frame codec that uses a length prefix to separate frames */
 export declare class LengthDelimitedCodec implements IFrameDecoder, IFrameEncoder {
     #private;
     constructor(options: LengthDelimitedCodecOptions);

package/codec/reader.cjs

@@ -8,12 +8,18 @@ class FramedReader {
   #readChunkSize;
   #eof = false;
   #canDecode = false;
+  /**
+   * @param readable  fuman readable stream to read from
+   * @param decoder  frame decoder
+   * @param options  extra options
+   */
   constructor(readable, decoder, options) {
     this.#readable = readable;
     this.#decoder = decoder;
     this.#buffer = bytes.Bytes.alloc(options?.initialBufferSize ?? 1024 * 16);
     this.#readChunkSize = options?.readChunkSize ?? 1024 * 16;
   }
+  /** read a next frame from the stream, or `null` if the stream ended */
   async read() {
     while (true) {
       if (this.#canDecode) {
@@ -36,6 +42,7 @@ class FramedReader {
       }
     }
   }
+  /** create an async iterator that yields frames */
   [Symbol.asyncIterator]() {
     return {
       next: async () => {

package/codec/reader.d.ts

@@ -1,12 +1,21 @@
 import { IReadable } from '../types.js';
 import { IFrameDecoder } from './types.js';
+/** options for {@link FramedReader} */
 export interface FramedReaderOptions {
     initialBufferSize?: number;
     readChunkSize?: number;
 }
+/** a reader that decodes frames one by one from a readable stream */
 export declare class FramedReader<Frame> {
     #private;
+    /**
+     * @param readable  fuman readable stream to read from
+     * @param decoder  frame decoder
+     * @param options  extra options
+     */
     constructor(readable: IReadable, decoder: IFrameDecoder<Frame>, options?: FramedReaderOptions);
+    /** read a next frame from the stream, or `null` if the stream ended */
     read(): Promise<Frame | null>;
+    /** create an async iterator that yields frames */
     [Symbol.asyncIterator](): AsyncIterator<Frame>;
 }

package/codec/reader.js

@@ -6,12 +6,18 @@ class FramedReader {
   #readChunkSize;
   #eof = false;
   #canDecode = false;
+  /**
+   * @param readable  fuman readable stream to read from
+   * @param decoder  frame decoder
+   * @param options  extra options
+   */
   constructor(readable, decoder, options) {
     this.#readable = readable;
     this.#decoder = decoder;
     this.#buffer = Bytes.alloc(options?.initialBufferSize ?? 1024 * 16);
     this.#readChunkSize = options?.readChunkSize ?? 1024 * 16;
   }
+  /** read a next frame from the stream, or `null` if the stream ended */
   async read() {
     while (true) {
       if (this.#canDecode) {
@@ -34,6 +40,7 @@ class FramedReader {
       }
     }
   }
+  /** create an async iterator that yields frames */
   [Symbol.asyncIterator]() {
     return {
       next: async () => {

package/codec/text-delimiter.d.ts

@@ -2,6 +2,7 @@ import { Bytes } from '../bytes.js';
 import { ISyncWritable } from '../types.js';
 import { DelimiterCodecOptions } from './delimiter.js';
 import { IFrameDecoder, IFrameEncoder } from './types.js';
+/** wrapper over {@link DelimiterCodec} that handles text frames */
 export declare class TextDelimiterCodec implements IFrameDecoder<string>, IFrameEncoder<string> {
     #private;
     constructor(delimiter: Uint8Array | string, options?: DelimiterCodecOptions);

package/codec/types.d.ts

@@ -5,12 +5,14 @@ export interface IFrameDecoder<Frame = Uint8Array> {
     /**
      * Decode a frame from a buffer
      *
-     * > **Important**: When returning byte arrays, make sure that the returned array is **not**
+     * > **Important implementation notice**: When returning byte arrays, make sure that the returned array is **not**
      * > a view into the original buffer, as the underlying buffer may get invalidated
      */
     decode: (buf: Bytes, eof: boolean) => MaybePromise<Frame | null>;
 }
 export interface IFrameEncoder<Frame = Uint8Array> {
+    /** Encode a frame into a writable stream */
     encode: (frame: Frame, into: ISyncWritable) => MaybePromise<void>;
+    /** Reset the encoder, should it have any internal state */
     reset: () => void;
 }

package/codec/writer.cjs

@@ -6,12 +6,18 @@ class FramedWriter {
   #encoder;
   #buffer;
   #highWaterMark;
+  /**
+   * @param writable  fuman writable stream to write to
+   * @param encoder  frame encoder
+   * @param options  extra options
+   */
   constructor(writable, encoder, options) {
     this.#writable = writable;
     this.#encoder = encoder;
     this.#highWaterMark = options?.initialBufferSize ?? 1024;
     this.#buffer = bytes.Bytes.alloc(this.#highWaterMark);
   }
+  /** write a frame to the stream */
   async write(frame) {
     await this.#encoder.encode(frame, this.#buffer);
     const buffer = this.#buffer.result();

package/codec/writer.d.ts

@@ -1,10 +1,18 @@
 import { IWritable } from '../types.js';
 import { IFrameEncoder } from './types.js';
+/** options for {@link FramedWriter} */
 export interface FramedWriterOptions {
     initialBufferSize?: number;
 }
+/** a writer that encodes frames one by one into a writable stream */
 export declare class FramedWriter<Frame = Uint8Array> {
     #private;
+    /**
+     * @param writable  fuman writable stream to write to
+     * @param encoder  frame encoder
+     * @param options  extra options
+     */
     constructor(writable: IWritable, encoder: IFrameEncoder<Frame>, options?: FramedWriterOptions);
+    /** write a frame to the stream */
     write(frame: Frame): Promise<void>;
 }

package/codec/writer.js

@@ -4,12 +4,18 @@ class FramedWriter {
   #encoder;
   #buffer;
   #highWaterMark;
+  /**
+   * @param writable  fuman writable stream to write to
+   * @param encoder  frame encoder
+   * @param options  extra options
+   */
   constructor(writable, encoder, options) {
     this.#writable = writable;
     this.#encoder = encoder;
     this.#highWaterMark = options?.initialBufferSize ?? 1024;
     this.#buffer = Bytes.alloc(this.#highWaterMark);
   }
+  /** write a frame to the stream */
   async write(frame) {
     await this.#encoder.encode(frame, this.#buffer);
     const buffer = this.#buffer.result();

package/errors.d.ts

@@ -4,6 +4,9 @@
  * The part that was read is available in the `part` property.
  */
 export declare class PartialReadError extends RangeError {
+    /** the part that was read */
     readonly part: Uint8Array;
-    constructor(part: Uint8Array, expectedLength: number);
+    constructor(
+    /** the part that was read */
+    part: Uint8Array, expectedLength: number);
 }

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@fuman/io",
     "type": "module",
-    "version": "0.0.2",
+    "version": "0.0.3",
     "description": "experimental i/o abstractions",
     "license": "MIT",
     "scripts": {},
     "dependencies": {
-        "@fuman/utils": "^0.0.1"
+        "@fuman/utils": "^0.0.3"
     },
     "exports": {
         ".": {

package/read/adapters.d.ts

@@ -1,4 +1,7 @@
 import { IClosable, IReadable, ISyncReadable } from '../types.js';
+/** create an async readable stream from a sync readable stream */
 export declare function fumanSyncReadableToAsync(readable: ISyncReadable): IReadable;
+/** convert a web ReadableStream to a fuman readable stream */
 export declare function webReadableToFuman(readable: ReadableStream<Uint8Array>): IReadable & IClosable;
+/** convert a fuman readable stream to a web ReadableStream */
 export declare function fumanReadableToWeb(readable: IReadable): ReadableStream<Uint8Array>;

package/read/async/strings.d.ts

@@ -1,3 +1,18 @@
 import { IReadable } from '../../types.js';
+/**
+ * read exactly N bytes from the source
+ *
+ * @param readable  fuman readable stream
+ * @param length  length of the buffer to read, or a buffer to read into (when a number is passed, a new buffer will be allocated)
+ * @param onEof  what to do when the end of the stream is reached
+ *  - `error` - throw an {@link PartialReadError}
+ *  - `truncate` - truncate the buffer to the number of bytes that were read. note that this might return 0 bytes
+ */
 export declare function exactly(readable: IReadable, length: number | Uint8Array, onEof?: 'error' | 'truncate'): Promise<Uint8Array>;
+/**
+ * read the source until it ends, and return the buffer
+ *
+ * @param readable  fuman readable stream
+ * @param chunkSize  size of the chunks to read
+ */
 export declare function untilEnd(readable: IReadable, chunkSize?: number): Promise<Uint8Array>;

package/read/numbers.d.ts

@@ -1,27 +1,53 @@
 import { ISyncReadable } from '../types.js';
+/** read a uint8 from the source */
 export declare function uint8(readable: ISyncReadable): number;
+/** read an int8 from the source (fuman readable stream or a buffer) */
 export declare function int8(readable: ISyncReadable | Uint8Array): number;
+/** read a uint16 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function uint16le(readable: ISyncReadable | Uint8Array): number;
+/** read a uint16 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function uint16be(readable: ISyncReadable | Uint8Array): number;
+/** read a uint24 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function uint24le(readable: ISyncReadable | Uint8Array): number;
+/** read a uint24 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function uint24be(readable: ISyncReadable | Uint8Array): number;
+/** read a uint32 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function uint32le(readable: ISyncReadable | Uint8Array): number;
+/** read a uint32 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function uint32be(readable: ISyncReadable | Uint8Array): number;
+/** read a uint64 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function uint64le(readable: ISyncReadable | Uint8Array): bigint;
+/** read a uint64 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function uint64be(readable: ISyncReadable | Uint8Array): bigint;
+/** read an int16 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function int16le(readable: ISyncReadable | Uint8Array): number;
+/** read an int16 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function int16be(readable: ISyncReadable | Uint8Array): number;
+/** read an int24 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function int24le(readable: ISyncReadable | Uint8Array): number;
+/** read an int24 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function int24be(readable: ISyncReadable | Uint8Array): number;
+/** read an int32 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function int32le(readable: ISyncReadable | Uint8Array): number;
+/** read an int32 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function int32be(readable: ISyncReadable | Uint8Array): number;
+/** read an int64 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function int64le(readable: ISyncReadable | Uint8Array): bigint;
+/** read an int64 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function int64be(readable: ISyncReadable | Uint8Array): bigint;
+/** read a variable-size uint (little endian) from the source (fuman readable stream or a buffer) */
 export declare function uintle(readable: ISyncReadable | Uint8Array, size: number): bigint;
+/** read a variable-size uint (big endian) from the source (fuman readable stream or a buffer) */
 export declare function uintbe(readable: ISyncReadable | Uint8Array, size: number): bigint;
+/** read a variable-size int (big endian) from the source (fuman readable stream or a buffer) */
 export declare function intbe(readable: ISyncReadable | Uint8Array, size: number): bigint;
+/** read a variable-size int (little endian) from the source (fuman readable stream or a buffer) */
 export declare function intle(readable: ISyncReadable | Uint8Array, size: number): bigint;
+/** read a float32 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function float32le(readable: ISyncReadable | Uint8Array): number;
+/** read a float32 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function float32be(readable: ISyncReadable | Uint8Array): number;
+/** read a float64 (little endian) from the source (fuman readable stream or a buffer) */
 export declare function float64le(readable: ISyncReadable | Uint8Array): number;
+/** read a float64 (big endian) from the source (fuman readable stream or a buffer) */
 export declare function float64be(readable: ISyncReadable | Uint8Array): number;

package/reader-with-final.cjs

@@ -17,6 +17,7 @@ class ReaderWithFinal {
     this.#buf1 = this.#buf2;
     this.#buf2 = tmp;
   }
+  /** read a chunk of data, and whether it is the last one */
   async readWithFinal(into) {
     if (this.#ended) {
       return {

package/reader-with-final.d.ts

@@ -1,13 +1,21 @@
 import { IReadable } from './types.js';
+/** result of {@link ReaderWithFinal#readWithFinal} */
 export interface ReaderWithFinalResult {
+    /** number of bytes read */
     readonly nread: number;
+    /** whether this was the last chunk */
     readonly final: boolean;
 }
+/**
+ * a reader that reads one read ahead, allowing the caller to know
+ * whether the chunk being read is the last one
+ */
 export declare class ReaderWithFinal implements IReadable {
     #private;
     constructor(readable: IReadable, params?: {
         internalBufferSize?: number;
     });
+    /** read a chunk of data, and whether it is the last one */
     readWithFinal(into: Uint8Array): Promise<ReaderWithFinalResult>;
     read(into: Uint8Array): Promise<number>;
 }

package/reader-with-final.js

@@ -15,6 +15,7 @@ class ReaderWithFinal {
     this.#buf1 = this.#buf2;
     this.#buf2 = tmp;
   }
+  /** read a chunk of data, and whether it is the last one */
   async readWithFinal(into) {
     if (this.#ended) {
       return {

package/types.d.ts

@@ -1,6 +1,4 @@
-/**
- * An interface for reading bytes synchronously from somewhere.
- */
+/** A synchronous readable stream */
 export interface ISyncReadable {
     /**
      * Read the specified number of bytes from the source
@@ -17,6 +15,7 @@ export interface ISyncReadable {
      */
     readSync: (bytes: number) => Uint8Array;
 }
+/** A readable stream */
 export interface IReadable {
     /**
      * Read data from the underlying source into the provided Uint8Array,
@@ -31,12 +30,14 @@ export interface IReadable {
      */
     read: (into: Uint8Array) => Promise<number>;
 }
+/** Something that can be closed */
 export interface IClosable {
     /**
      * Close the underlying source.
      */
     close: () => void;
 }
+/** A synchronous writable stream */
 export interface ISyncWritable {
     /**
      * Write the specified number of bytes to the underlying source.
@@ -61,6 +62,8 @@ export interface ISyncWritable {
      */
     disposeWriteSync: (written?: number) => void;
 }
+/** A writable stream */
 export interface IWritable {
+    /** Write bytes to the underlying stream, resolving once the write is complete */
     write: (bytes: Uint8Array) => Promise<void>;
 }

package/write/numbers.d.ts

@@ -1,27 +1,53 @@
 import { ISyncWritable } from '../types.js';
+/** write a uint8 to the target (fuman writable stream or a buffer) */
 export declare function uint8(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int8 to the target (fuman writable stream or a buffer) */
 export declare function int8(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint16 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function uint16le(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint16 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function uint16be(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int16 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function int16le(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int16 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function int16be(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint24 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function uint24le(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint24 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function uint24be(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int24 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function int24le(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int24 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function int24be(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint32 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function uint32le(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint32 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function uint32be(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int32 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function int32le(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write an int32 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function int32be(writable: ISyncWritable | Uint8Array, value: number, noAssert?: boolean): void;
+/** write a uint64 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function uint64le(writable: ISyncWritable | Uint8Array, value: bigint, noAssert?: boolean): void;
+/** write a uint64 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function uint64be(writable: ISyncWritable | Uint8Array, value: bigint, noAssert?: boolean): void;
+/** write an int64 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function int64le(writable: ISyncWritable | Uint8Array, value: bigint, noAssert?: boolean): void;
+/** write an int64 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function int64be(writable: ISyncWritable | Uint8Array, value: bigint, noAssert?: boolean): void;
+/** write a variable-size uint (little endian) to the target (fuman writable stream or a buffer) */
 export declare function uintle(writable: ISyncWritable | Uint8Array, size: number, value: bigint, noAssert?: boolean): void;
+/** write a variable-size uint (big endian) to the target (fuman writable stream or a buffer) */
 export declare function uintbe(writable: ISyncWritable | Uint8Array, size: number, value: bigint, noAssert?: boolean): void;
+/** write a variable-size int (little endian) to the target (fuman writable stream or a buffer) */
 export declare function intle(writable: ISyncWritable | Uint8Array, size: number, value: bigint, noAssert?: boolean): void;
+/** write a variable-size int (big endian) to the target (fuman writable stream or a buffer) */
 export declare function intbe(writable: ISyncWritable | Uint8Array, size: number, value: bigint, noAssert?: boolean): void;
+/** write a float32 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function float32le(writable: ISyncWritable | Uint8Array, value: number): void;
+/** write a float32 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function float32be(writable: ISyncWritable | Uint8Array, value: number): void;
+/** write a float64 (little endian) to the target (fuman writable stream or a buffer) */
 export declare function float64le(writable: ISyncWritable | Uint8Array, value: number): void;
+/** write a float64 (big endian) to the target (fuman writable stream or a buffer) */
 export declare function float64be(writable: ISyncWritable | Uint8Array, value: number): void;

package/write/pipe.d.ts

@@ -1,2 +1,3 @@
 import { IReadable, IWritable } from '../types.js';
+/** pipe the contents of a readable stream (until it ends) into a writable stream */
 export declare function pipe(into: IWritable, readable: IReadable): Promise<void>;

package/write/strings.d.ts

@@ -1,6 +1,11 @@
 import { ISyncWritable } from '../types.js';
+/** write a buffer to the stream */
 export declare function bytes(writable: ISyncWritable, bytes: Uint8Array): void;
+/** write a buffer to the stream, but in reverse order */
 export declare function bytesReversed(writable: ISyncWritable, bytes: Uint8Array): void;
+/** write a raw string to the stream (`.charCodeAt` is used to get the codepoints) */
 export declare function rawString(writable: ISyncWritable, str: string): void;
+/** write a utf8-encoded string to the stream */
 export declare function utf8String(writable: ISyncWritable, str: string): void;
+/** write a utf8-encoded string to the stream, with a null terminator */
 export declare function cUtf8String(writable: ISyncWritable, str: string): void;