Signatur
Beschreibung
enqueue() ist die zentrale Methode, mit der eine zugrunde liegende Quelle eines Bytestroms (ein ReadableStream mit type: "bytes") Daten bereitstellt. Der übergebene Block muss ein ArrayBufferView sein, also ein Typed Array wie Uint8Array oder ein DataView. Ein reiner ArrayBuffer wird nicht akzeptiert.
Wartet gerade ein Leser auf Daten, reicht der Strom den Block sofort weiter. Das gilt auch, wenn ein BYOB-Leser (getReader({ mode: "byob" })) eine Anfrage offen hat: Die Bytes werden dann in dessen Puffer kopiert. Wartet niemand, landet der Block in der internen Warteschlange. Deren Füllstand sehen Sie über controller.desiredSize.
Wichtig: Der zugrunde liegende ArrayBuffer wird beim Einstellen übertragen (transferiert). Danach ist die ursprüngliche Ansicht abgekoppelt (detached), ihre byteLength ist 0. Sie dürfen denselben Puffer also nicht weiterverwenden. Brauchen Sie die Daten noch, übergeben Sie eine Kopie (z. B. view.slice()).
Typischer Einsatz: in start() oder pull() einer Bytequelle, etwa beim Umwandeln von Datei-, Netzwerk- oder Socket-Daten in einen Web-Stream. Fragt ein BYOB-Leser gerade Daten an, sind controller.byobRequest und respond() meist effizienter, weil dann keine Kopie nötig ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $chunk Pflicht | ArrayBufferView (TypedArray | DataView) | Der einzustellende Datenblock. Er darf nicht leer sein (byteLength > 0), und sein Puffer darf nicht bereits abgekoppelt sein. Der Puffer wird beim Aufruf übertragen. |
Rückgabewert
TypeError geworfen.Beispiele
Einfacher Bytestrom mit festem Inhalt
const daten = new TextEncoder().encode("Hallo Bytestrom");
const stream = new ReadableStream({
type: "bytes",
start(controller) {
controller.enqueue(daten); // Uint8Array einstellen
controller.close();
}
});
const reader = stream.getReader();
const { value } = await reader.read();
console.log(value instanceof Uint8Array, value.byteLength);
console.log(new TextDecoder().decode(value));Pull-Quelle mit BYOB-Unterstützung und enqueue()-Rückfall
const quelle = new Uint8Array(1000).map((_, i) => i % 256);
let offset = 0;
const stream = new ReadableStream({
type: "bytes",
pull(controller) {
if (offset >= quelle.length) {
controller.close();
controller.byobRequest?.respond(0); // offene BYOB-Anfrage abschließen
return;
}
const request = controller.byobRequest;
if (request) {
// Direkt in den Puffer des Lesers schreiben (ohne Kopie)
const ziel = new Uint8Array(request.view.buffer, request.view.byteOffset, request.view.byteLength);
const n = Math.min(ziel.byteLength, quelle.length - offset);
ziel.set(quelle.subarray(offset, offset + n));
offset += n;
request.respond(n);
} else {
// Normaler Leser: eigenen Block einstellen
const n = Math.min(256, quelle.length - offset);
controller.enqueue(quelle.slice(offset, offset + n));
offset += n;
}
}
});
const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(300);
let gesamt = 0;
while (true) {
const { value, done } = await reader.read(new Uint8Array(buffer));
if (done) break;
gesamt += value.byteLength;
buffer = value.buffer; // übertragenen Puffer wiederverwenden
}
console.log(`${gesamt} Bytes gelesen`);Fallstrick: Puffer wird nach enqueue() abgekoppelt
const block = new Uint8Array([1, 2, 3, 4]);
new ReadableStream({
type: "bytes",
start(controller) {
const kopie = block.slice(); // Kopie behält die Daten
controller.enqueue(block);
console.log(block.byteLength); // Original ist jetzt abgekoppelt
console.log(kopie.byteLength);
}
});