ByteStream

ByteStream API Reference

Overview

The ByteStream utility is a class designed for managing and manipulating byte streams in Salesforce Commerce Cloud (SFCC). It provides a range of methods for reading, moving, and comparing byte sequences, making it particularly useful when working with binary data, such as file uploads, downloads, and streaming operations.

---

Constructor

ByteStream(source: dw.util.Bytes)

Description: Creates a new ByteStream instance with the specified source of bytes.

• Parameters:
  • source (dw.util.Bytes): The source of bytes for the stream.
• Throws:
  • TypeError: If the source is not an instance of dw.util.Bytes.

Usage Example:

var Bytes = require('dw/util/Bytes');
var ByteStream = require('*/cartridge/scripts/util/ByteStream');

var byteData = new Bytes('example data');
var stream = new ByteStream(byteData);

---

Static Methods

ByteStream.equal(a: dw.util.Bytes, b: dw.util.Bytes)

Description: Compares two byte arrays for equality.

• Parameters:
  • a (dw.util.Bytes): The first byte array.
  • b (dw.util.Bytes): The second byte array.
• Returns:
  • boolean: True if the byte arrays are equal, false otherwise.

Usage Example:

var Bytes = require('dw/util/Bytes');
var ByteStream = require('*/cartridge/scripts/util/ByteStream');

var bytes1 = new Bytes('data1');
var bytes2 = new Bytes('data1');

if (ByteStream.equal(bytes1, bytes2)) {
    console.log('The byte arrays are equal.');
}

---

Instance Methods

eos()

Description: Checks if the end of the stream has been reached.

• Returns:
  • boolean: True if the end of the stream has been reached, false otherwise.

Usage Example:

if (stream.eos()) {
    console.log('End of stream reached');
}

---

move(offset: number)

Description: Moves the position within the stream by a specified offset.

• Parameters:
  • offset (number): The number of bytes to move the position by.
• Throws:
  • TypeError: If the offset is not a number.
  • RangeError: If the resulting position is out of bounds.

Usage Example:

stream.move(5); // Moves the position 5 bytes forward

---

peek(offset?: number)

Description: Peeks at a byte in the stream at the current position plus an optional offset without advancing the position.

• Parameters:
  • offset (number, optional): The offset from the current position to peek at. Defaults to 0.
• Returns:
  • number: The byte at the specified position.
• Throws:
  • TypeError: If the offset is out of bounds.

Usage Example:

var byte = stream.peek(); // Peek at the current position

---

slice(start?: number, end?: number)

Description: Slices a portion of the stream into a new byte array.

• Parameters:
  • start (number, optional): The starting position of the slice. Defaults to 0.
  • end (number, optional): The ending position of the slice. Defaults to the end of the stream.
• Returns:
  • dw.util.Bytes: The sliced bytes.

Usage Example:

var slicedBytes = stream.slice(0, 10); // Slices the first 10 bytes

---

readN(n: number)

Description: Reads a specified number of bytes from the stream.

• Parameters:
  • n (number): The number of bytes to read.
• Returns:
  • dw.util.Bytes|null: The read bytes, or null if the end of the stream has been reached.
• Throws:
  • TypeError: If n is not a non-negative number.

Usage Example:

var bytes = stream.readN(5); // Reads the next 5 bytes

---

read()

Description: Reads a single byte from the stream and advances the position.

• Returns:
  • number|null: The read byte, or null if the end of the stream has been reached.

Usage Example:

var byte = stream.read(); // Reads the next byte

---

readLine()

Description: Reads a line from the stream, ending at a newline character.

• Returns:
  • dw.util.Bytes|null: The read line, or null if the end of the stream has been reached.

Usage Example:

var line = stream.readLine(); // Reads a line of bytes until a newline character is encountered

---

readUntil(sequence: dw.util.Bytes)

Description: Reads bytes from the stream until a specified sequence is encountered.

• Parameters:
  • sequence (dw.util.Bytes): The sequence of bytes to read until.
• Returns:
  • dw.util.Bytes|null: The read bytes, or null if the end of the stream has been reached.
• Throws:
  • TypeError: If sequence is not an instance of dw.util.Bytes.

Usage Example:

var Bytes = require('dw/util/Bytes');
var sequence = new Bytes('--Boundary');

var dataUntilBoundary = stream.readUntil(sequence); // Reads bytes until the specified sequence is encountered

---

Character Codes

ByteStream.charCode

Description: Contains character codes for common control characters.

• CR: Carriage return ('\r', code 13)
• LF: Line feed ('\n', code 10)
• HN: Hyphen ('-', code 45)

Usage Example:

if (byte === ByteStream.charCode.LF) {
    console.log('Line feed encountered');
}