@fuman/io 0.0.1

package/bytes.d.ts

@@ -0,0 +1,24 @@
+import { IReadable, ISyncReadable, ISyncWritable, IWritable } from './types.js';
+export declare class Bytes implements IReadable, IWritable, ISyncReadable, ISyncWritable {
+    #private;
+    constructor(buf: Uint8Array);
+    static alloc(capacity?: number): Bytes;
+    static from(data: Uint8Array): Bytes;
+    /** Total number of bytes in the underlying buffer */
+    get capacity(): number;
+    /** Number of bytes available to be read */
+    get available(): number;
+    /** Number of bytes written */
+    get written(): number;
+    readSync(bytes: number): Uint8Array;
+    read(into: Uint8Array): Promise<number>;
+    writeSync(size: number): Uint8Array;
+    disposeWriteSync(written?: number): void;
+    write(bytes: Uint8Array): Promise<void>;
+    result(): Uint8Array;
+    /** Reclaim memory by only keeping the yet-unread data */
+    reclaim(): void;
+    /** Mark last n bytes as unread */
+    rewind(n: number): void;
+    reset(): void;
+}

package/bytes.js

@@ -0,0 +1,114 @@
+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) {
+    this.#buffer = buf;
+    this.#preferredCapacity = buf.length;
+  }
+  static alloc(capacity = 1024 * 16) {
+    const bytes = new Bytes(u8.alloc(capacity));
+    return bytes;
+  }
+  static from(data) {
+    const bytes = new Bytes(data);
+    bytes.#writePos = data.length;
+    return bytes;
+  }
+  /** Total number of bytes in the underlying buffer */
+  get capacity() {
+    return this.#buffer.byteLength;
+  }
+  /** Number of bytes available to be read */
+  get available() {
+    return this.#writePos - this.#readPos;
+  }
+  /** Number of bytes written */
+  get written() {
+    return this.#writePos;
+  }
+  #sharedRead = new Uint8Array(1);
+  readSync(bytes) {
+    if (this.#readPos >= this.#writePos) {
+      return u8.empty;
+    }
+    if (bytes === 1) {
+      this.#sharedRead[0] = this.#buffer[this.#readPos++];
+      return this.#sharedRead;
+    }
+    const end = Math.min(this.#writePos, this.#readPos + bytes);
+    const result = this.#buffer.subarray(this.#readPos, end);
+    this.#readPos = end;
+    return result;
+  }
+  async read(into) {
+    const size = Math.min(into.length, this.#writePos - this.#readPos);
+    into.set(this.#buffer.subarray(this.#readPos, this.#readPos + size));
+    this.#readPos += size;
+    return size;
+  }
+  #lastWriteSize = 0;
+  writeSync(size) {
+    this.#lastWriteSize = size;
+    const newPos = this.#writePos + size;
+    if (newPos > this.#buffer.length) {
+      const newBuffer = u8.alloc(nextPowerOfTwo(newPos));
+      newBuffer.set(this.#buffer);
+      this.#buffer = newBuffer;
+    }
+    const slice = this.#buffer.subarray(this.#writePos, newPos);
+    this.#writePos = newPos;
+    return slice;
+  }
+  disposeWriteSync(written) {
+    if (written !== void 0) {
+      if (written > this.#lastWriteSize) {
+        throw new RangeError(`written exceeds last write size: ${written} > ${this.#lastWriteSize}`);
+      }
+      this.#writePos -= this.#lastWriteSize - written;
+    }
+  }
+  async write(bytes) {
+    this.writeSync(bytes.length).set(bytes);
+    this.disposeWriteSync();
+  }
+  result() {
+    return this.#buffer.subarray(0, this.#writePos);
+  }
+  /** Reclaim memory by only keeping the yet-unread data */
+  reclaim() {
+    if (this.#readPos === 0) return;
+    const remaining = this.#writePos - this.#readPos;
+    if (remaining > 0) {
+      if (remaining < this.#preferredCapacity && this.capacity > this.#preferredCapacity) {
+        const newBuffer = u8.alloc(this.#preferredCapacity);
+        newBuffer.set(this.#buffer.subarray(this.#readPos, this.#writePos));
+        this.#buffer = newBuffer;
+      } else {
+        this.#buffer.copyWithin(0, this.#readPos, this.#writePos);
+      }
+    }
+    this.#writePos = remaining;
+    this.#readPos = 0;
+  }
+  /** Mark last n bytes as unread */
+  rewind(n) {
+    if (n > this.#readPos) {
+      throw new RangeError(`rewind: ${n} > ${this.#readPos}`);
+    }
+    this.#readPos -= n;
+  }
+  reset() {
+    this.#readPos = 0;
+    this.#writePos = 0;
+  }
+}
+export {
+  Bytes
+};

package/codec/delimiter.cjs

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+class DelimiterCodec {
+  constructor(delimiter, options) {
+    this.delimiter = delimiter;
+    this.options = options;
+    this.#strategy = options?.strategy ?? "discard";
+  }
+  #strategy;
+  decode(buf, eof) {
+    const { delimiter } = this;
+    const data = buf.readSync(buf.available);
+    if (eof && data.length === 0) {
+      return null;
+    }
+    const delimiterIdx = utils.typed.indexOfArray(data, delimiter);
+    if (delimiterIdx === -1) {
+      if (eof) {
+        return data;
+      }
+      buf.rewind(data.length);
+      return null;
+    }
+    buf.rewind(data.length - delimiterIdx - delimiter.length);
+    const frameEnd = this.#strategy === "keep" ? delimiterIdx + delimiter.length : delimiterIdx;
+    return data.slice(0, frameEnd);
+  }
+  encode(data, into) {
+    const buf = into.writeSync(data.length + this.delimiter.length);
+    buf.set(data);
+    buf.set(this.delimiter, data.length);
+    into.disposeWriteSync();
+  }
+  reset() {
+  }
+}
+exports.DelimiterCodec = DelimiterCodec;

package/codec/delimiter.d.ts

@@ -0,0 +1,22 @@
+import { Bytes } from '../bytes.js';
+import { ISyncWritable } from '../types.js';
+import { IFrameDecoder, IFrameEncoder } from './types.js';
+export interface DelimiterCodecOptions {
+    /**
+     * Strategy for handling delimiter.
+     *  - `keep` - delimiter is kept at the end of each frame
+     *  - `discard` - delimiter is discarded
+     *
+     * Ignored for encoding (delimiter is always appended after the frame)
+     */
+    strategy?: 'keep' | 'discard';
+}
+export declare class DelimiterCodec implements IFrameDecoder, IFrameEncoder {
+    #private;
+    readonly delimiter: Uint8Array;
+    readonly options?: DelimiterCodecOptions | undefined;
+    constructor(delimiter: Uint8Array, options?: DelimiterCodecOptions | undefined);
+    decode(buf: Bytes, eof: boolean): Uint8Array | null;
+    encode(data: Uint8Array, into: ISyncWritable): void;
+    reset(): void;
+}

package/codec/delimiter.js

@@ -0,0 +1,38 @@
+import { typed } from "@fuman/utils";
+class DelimiterCodec {
+  constructor(delimiter, options) {
+    this.delimiter = delimiter;
+    this.options = options;
+    this.#strategy = options?.strategy ?? "discard";
+  }
+  #strategy;
+  decode(buf, eof) {
+    const { delimiter } = this;
+    const data = buf.readSync(buf.available);
+    if (eof && data.length === 0) {
+      return null;
+    }
+    const delimiterIdx = typed.indexOfArray(data, delimiter);
+    if (delimiterIdx === -1) {
+      if (eof) {
+        return data;
+      }
+      buf.rewind(data.length);
+      return null;
+    }
+    buf.rewind(data.length - delimiterIdx - delimiter.length);
+    const frameEnd = this.#strategy === "keep" ? delimiterIdx + delimiter.length : delimiterIdx;
+    return data.slice(0, frameEnd);
+  }
+  encode(data, into) {
+    const buf = into.writeSync(data.length + this.delimiter.length);
+    buf.set(data);
+    buf.set(this.delimiter, data.length);
+    into.disposeWriteSync();
+  }
+  reset() {
+  }
+}
+export {
+  DelimiterCodec
+};

package/codec/index.d.ts

@@ -0,0 +1,6 @@
+export * from './delimiter.js';
+export * from './length-delimited.js';
+export * from './reader.js';
+export * from './text-delimiter.js';
+export * from './types.js';
+export * from './writer.js';

package/codec/length-delimited.cjs

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+class LengthDelimitedCodec {
+  #read;
+  #write;
+  constructor(options) {
+    this.#read = options.read;
+    this.#write = options.write;
+  }
+  #pendingLength = null;
+  decode(buf) {
+    if (!this.#read) {
+      throw new Error("LengthDelimitedCodec: read function not provided");
+    }
+    if (this.#pendingLength !== null) {
+      const pendingLength = this.#pendingLength;
+      if (buf.available < pendingLength) {
+        return null;
+      }
+      const data = buf.readSync(pendingLength);
+      this.#pendingLength = null;
+      return utils.u8.allocWith(data);
+    }
+    const length = this.#read(buf);
+    if (length === null) return null;
+    this.#pendingLength = length;
+    return this.decode(buf);
+  }
+  encode(frame, into) {
+    if (!this.#write) {
+      throw new Error("LengthDelimitedCodec: write function not provided");
+    }
+    this.#write(into, frame.length);
+    into.writeSync(frame.length).set(frame);
+    into.disposeWriteSync();
+  }
+  reset() {
+    this.#pendingLength = null;
+  }
+}
+exports.LengthDelimitedCodec = LengthDelimitedCodec;

package/codec/length-delimited.d.ts

@@ -0,0 +1,14 @@
+import { Bytes } from '../bytes.js';
+import { ISyncWritable } from '../types.js';
+import { IFrameDecoder, IFrameEncoder } from './types.js';
+export interface LengthDelimitedCodecOptions {
+    read?: (r: Bytes) => number | null;
+    write?: (w: ISyncWritable, n: number) => void;
+}
+export declare class LengthDelimitedCodec implements IFrameDecoder, IFrameEncoder {
+    #private;
+    constructor(options: LengthDelimitedCodecOptions);
+    decode(buf: Bytes): Uint8Array | null;
+    encode(frame: Uint8Array, into: ISyncWritable): void;
+    reset(): void;
+}

package/codec/length-delimited.js

@@ -0,0 +1,42 @@
+import { u8 } from "@fuman/utils";
+class LengthDelimitedCodec {
+  #read;
+  #write;
+  constructor(options) {
+    this.#read = options.read;
+    this.#write = options.write;
+  }
+  #pendingLength = null;
+  decode(buf) {
+    if (!this.#read) {
+      throw new Error("LengthDelimitedCodec: read function not provided");
+    }
+    if (this.#pendingLength !== null) {
+      const pendingLength = this.#pendingLength;
+      if (buf.available < pendingLength) {
+        return null;
+      }
+      const data = buf.readSync(pendingLength);
+      this.#pendingLength = null;
+      return u8.allocWith(data);
+    }
+    const length = this.#read(buf);
+    if (length === null) return null;
+    this.#pendingLength = length;
+    return this.decode(buf);
+  }
+  encode(frame, into) {
+    if (!this.#write) {
+      throw new Error("LengthDelimitedCodec: write function not provided");
+    }
+    this.#write(into, frame.length);
+    into.writeSync(frame.length).set(frame);
+    into.disposeWriteSync();
+  }
+  reset() {
+    this.#pendingLength = null;
+  }
+}
+export {
+  LengthDelimitedCodec
+};

package/codec/reader.cjs

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const bytes = require("../bytes.cjs");
+class FramedReader {
+  #readable;
+  #decoder;
+  #buffer;
+  #readChunkSize;
+  #eof = false;
+  #canDecode = false;
+  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;
+  }
+  async read() {
+    while (true) {
+      if (this.#canDecode) {
+        const frame = await this.#decoder.decode(this.#buffer, this.#eof);
+        this.#buffer.reclaim();
+        if (frame !== null) {
+          return frame;
+        }
+      }
+      if (this.#eof) {
+        return null;
+      }
+      const into = this.#buffer.writeSync(this.#readChunkSize);
+      const read = await this.#readable.read(into);
+      this.#buffer.disposeWriteSync(read);
+      if (read === 0) {
+        this.#eof = true;
+      } else {
+        this.#canDecode = true;
+      }
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const res = await this.read();
+        if (res === null) {
+          return { done: true, value: void 0 };
+        }
+        return { done: false, value: res };
+      }
+    };
+  }
+}
+exports.FramedReader = FramedReader;

package/codec/reader.d.ts

@@ -0,0 +1,12 @@
+import { IReadable } from '../types.js';
+import { IFrameDecoder } from './types.js';
+export interface FramedReaderOptions {
+    initialBufferSize?: number;
+    readChunkSize?: number;
+}
+export declare class FramedReader<Frame> {
+    #private;
+    constructor(readable: IReadable, decoder: IFrameDecoder<Frame>, options?: FramedReaderOptions);
+    read(): Promise<Frame | null>;
+    [Symbol.asyncIterator](): AsyncIterator<Frame>;
+}

package/codec/reader.js

@@ -0,0 +1,51 @@
+import { Bytes } from "../bytes.js";
+class FramedReader {
+  #readable;
+  #decoder;
+  #buffer;
+  #readChunkSize;
+  #eof = false;
+  #canDecode = false;
+  constructor(readable, decoder, options) {
+    this.#readable = readable;
+    this.#decoder = decoder;
+    this.#buffer = Bytes.alloc(options?.initialBufferSize ?? 1024 * 16);
+    this.#readChunkSize = options?.readChunkSize ?? 1024 * 16;
+  }
+  async read() {
+    while (true) {
+      if (this.#canDecode) {
+        const frame = await this.#decoder.decode(this.#buffer, this.#eof);
+        this.#buffer.reclaim();
+        if (frame !== null) {
+          return frame;
+        }
+      }
+      if (this.#eof) {
+        return null;
+      }
+      const into = this.#buffer.writeSync(this.#readChunkSize);
+      const read = await this.#readable.read(into);
+      this.#buffer.disposeWriteSync(read);
+      if (read === 0) {
+        this.#eof = true;
+      } else {
+        this.#canDecode = true;
+      }
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const res = await this.read();
+        if (res === null) {
+          return { done: true, value: void 0 };
+        }
+        return { done: false, value: res };
+      }
+    };
+  }
+}
+export {
+  FramedReader
+};

package/codec/text-delimiter.cjs

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+const delimiter = require("./delimiter.cjs");
+class TextDelimiterCodec {
+  #inner;
+  constructor(delimiter$1, options) {
+    if (typeof delimiter$1 === "string") {
+      delimiter$1 = utils.utf8.encoder.encode(delimiter$1);
+    }
+    this.#inner = new delimiter.DelimiterCodec(delimiter$1, options);
+  }
+  decode(buf, eof) {
+    const data = this.#inner.decode(buf, eof);
+    return data === null ? null : utils.utf8.decoder.decode(data);
+  }
+  encode(data, into) {
+    this.#inner.encode(utils.utf8.encoder.encode(data), into);
+  }
+  reset() {
+    this.#inner.reset();
+  }
+}
+exports.TextDelimiterCodec = TextDelimiterCodec;

package/codec/text-delimiter.d.ts

@@ -0,0 +1,11 @@
+import { Bytes } from '../bytes.js';
+import { ISyncWritable } from '../types.js';
+import { DelimiterCodecOptions } from './delimiter.js';
+import { IFrameDecoder, IFrameEncoder } from './types.js';
+export declare class TextDelimiterCodec implements IFrameDecoder<string>, IFrameEncoder<string> {
+    #private;
+    constructor(delimiter: Uint8Array | string, options?: DelimiterCodecOptions);
+    decode(buf: Bytes, eof: boolean): string | null;
+    encode(data: string, into: ISyncWritable): void;
+    reset(): void;
+}

package/codec/text-delimiter.js

@@ -0,0 +1,24 @@
+import { utf8 } from "@fuman/utils";
+import { DelimiterCodec } from "./delimiter.js";
+class TextDelimiterCodec {
+  #inner;
+  constructor(delimiter, options) {
+    if (typeof delimiter === "string") {
+      delimiter = utf8.encoder.encode(delimiter);
+    }
+    this.#inner = new DelimiterCodec(delimiter, options);
+  }
+  decode(buf, eof) {
+    const data = this.#inner.decode(buf, eof);
+    return data === null ? null : utf8.decoder.decode(data);
+  }
+  encode(data, into) {
+    this.#inner.encode(utf8.encoder.encode(data), into);
+  }
+  reset() {
+    this.#inner.reset();
+  }
+}
+export {
+  TextDelimiterCodec
+};

package/codec/types.d.ts

@@ -0,0 +1,16 @@
+import { MaybePromise } from '@fuman/utils';
+import { Bytes } from '../bytes.js';
+import { ISyncWritable } from '../types.js';
+export interface IFrameDecoder<Frame = Uint8Array> {
+    /**
+     * Decode a frame from a buffer
+     *
+     * > **Important**: 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: (frame: Frame, into: ISyncWritable) => MaybePromise<void>;
+    reset: () => void;
+}

package/codec/writer.cjs

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const bytes = require("../bytes.cjs");
+class FramedWriter {
+  #writable;
+  #encoder;
+  #buffer;
+  #highWaterMark;
+  constructor(writable, encoder, options) {
+    this.#writable = writable;
+    this.#encoder = encoder;
+    this.#highWaterMark = options?.initialBufferSize ?? 1024;
+    this.#buffer = bytes.Bytes.alloc(this.#highWaterMark);
+  }
+  async write(frame) {
+    await this.#encoder.encode(frame, this.#buffer);
+    const buffer = this.#buffer.result();
+    if (buffer.length > 0) {
+      this.#buffer.reset();
+      await this.#writable.write(buffer);
+    }
+  }
+}
+exports.FramedWriter = FramedWriter;

package/codec/writer.d.ts

@@ -0,0 +1,10 @@
+import { IWritable } from '../types.js';
+import { IFrameEncoder } from './types.js';
+export interface FramedWriterOptions {
+    initialBufferSize?: number;
+}
+export declare class FramedWriter<Frame = Uint8Array> {
+    #private;
+    constructor(writable: IWritable, encoder: IFrameEncoder<Frame>, options?: FramedWriterOptions);
+    write(frame: Frame): Promise<void>;
+}

package/codec/writer.js

@@ -0,0 +1,24 @@
+import { Bytes } from "../bytes.js";
+class FramedWriter {
+  #writable;
+  #encoder;
+  #buffer;
+  #highWaterMark;
+  constructor(writable, encoder, options) {
+    this.#writable = writable;
+    this.#encoder = encoder;
+    this.#highWaterMark = options?.initialBufferSize ?? 1024;
+    this.#buffer = Bytes.alloc(this.#highWaterMark);
+  }
+  async write(frame) {
+    await this.#encoder.encode(frame, this.#buffer);
+    const buffer = this.#buffer.result();
+    if (buffer.length > 0) {
+      this.#buffer.reset();
+      await this.#writable.write(buffer);
+    }
+  }
+}
+export {
+  FramedWriter
+};

package/errors.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class PartialReadError extends RangeError {
+  constructor(part, expectedLength) {
+    super(`expected to read ${expectedLength} bytes, but only ${part.length} are available`);
+    this.part = part;
+  }
+}
+exports.PartialReadError = PartialReadError;

package/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown when trying to read more bytes than available.
+ *
+ * The part that was read is available in the `part` property.
+ */
+export declare class PartialReadError extends RangeError {
+    readonly part: Uint8Array;
+    constructor(part: Uint8Array, expectedLength: number);
+}

package/errors.js

@@ -0,0 +1,9 @@
+class PartialReadError extends RangeError {
+  constructor(part, expectedLength) {
+    super(`expected to read ${expectedLength} bytes, but only ${part.length} are available`);
+    this.part = part;
+  }
+}
+export {
+  PartialReadError
+};

package/index.cjs

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const index = require("./read/index.cjs");
+const index$1 = require("./write/index.cjs");
+const bufReader = require("./buf-reader.cjs");
+const bytes = require("./bytes.cjs");
+const errors = require("./errors.cjs");
+const adapters = require("./read/adapters.cjs");
+const readerWithFinal = require("./reader-with-final.cjs");
+const adapters$1 = require("./write/adapters.cjs");
+const reader = require("./bits/reader.cjs");
+const utils = require("./bits/utils.cjs");
+const delimiter = require("./codec/delimiter.cjs");
+const lengthDelimited = require("./codec/length-delimited.cjs");
+const reader$1 = require("./codec/reader.cjs");
+const textDelimiter = require("./codec/text-delimiter.cjs");
+const writer = require("./codec/writer.cjs");
+exports.read = index;
+exports.write = index$1;
+exports.BufReader = bufReader.BufReader;
+exports.Bytes = bytes.Bytes;
+exports.PartialReadError = errors.PartialReadError;
+exports.fumanReadableToWeb = adapters.fumanReadableToWeb;
+exports.fumanSyncReadableToAsync = adapters.fumanSyncReadableToAsync;
+exports.webReadableToFuman = adapters.webReadableToFuman;
+exports.ReaderWithFinal = readerWithFinal.ReaderWithFinal;
+exports.fumanSyncWritableToAsync = adapters$1.fumanSyncWritableToAsync;
+exports.fumanWritableToWeb = adapters$1.fumanWritableToWeb;
+exports.webWritableToFuman = adapters$1.webWritableToFuman;
+exports.BitReader = reader.BitReader;
+exports.reverse8Bits = utils.reverse8Bits;
+exports.reverseBits = utils.reverseBits;
+exports.reverseBitsAll = utils.reverseBitsAll;
+exports.reverseBitsBig = utils.reverseBitsBig;
+exports.DelimiterCodec = delimiter.DelimiterCodec;
+exports.LengthDelimitedCodec = lengthDelimited.LengthDelimitedCodec;
+exports.FramedReader = reader$1.FramedReader;
+exports.TextDelimiterCodec = textDelimiter.TextDelimiterCodec;
+exports.FramedWriter = writer.FramedWriter;