Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Destino de WritableStream: start, write, close y abort

Cuatro métodos opcionales definen cómo un flujo de escritura prepara su destino, escribe fragmentos, finaliza correctamente o libera recursos tras un aborto.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

new WritableStream()
new WritableStream(underlyingSink)
new WritableStream(underlyingSink, queuingStrategy)

// Optional methods on underlyingSink:
const underlyingSink = {
  start(controller) { /* initialize the destination */ },
  write(chunk, controller) { /* write one chunk */ },
  close() { /* finalize successful output */ },
  abort(reason) { /* clean up after an abort request */ },
};

WritableStream pertenece a la API Web Streams, no a ECMAScript 2024; su disponibilidad depende del entorno de ejecución. underlyingSink, el primer argumento opcional del constructor, es un objeto cuyos métodos invoca el flujo. El segundo argumento opcional, queuingStrategy, define cómo se mide el tamaño de la cola para aplicar contrapresión (backpressure).

start(controller) se ejecuta una vez durante la construcción. Una excepción síncrona hace fallar la construcción; una promesa rechazada deja el flujo creado en estado de error. El flujo espera a que la inicialización termine correctamente antes de entregar fragmentos al destino. write(chunk, controller) procesa un fragmento a la vez, en el orden de envío. Devuelve una promesa que represente la escritura asíncrona real para que el flujo pueda esperarla y propagar los fallos.

close() no recibe argumentos. Tras una solicitud de cierre, solo se ejecuta cuando todas las escrituras aceptadas han terminado correctamente. Úsalo para vaciar los búferes del destino y liberar recursos. abort(reason) realiza la limpieza tras una solicitud de aborto; el motivo puede ser cualquier valor de JavaScript. Se rechazan las escrituras que aún no han empezado, pero una operación en curso no se detiene automáticamente y las escrituras completadas no se deshacen. Ambos métodos pueden devolver promesas; no des por hecho que abort se ejecutará ante cualquier error o después del cierre.

start y write reciben el mismo WritableStreamDefaultController. controller.signal permite que una operación en curso responda a una solicitud de aborto si admite la cancelación. controller.error(error) notifica un fallo del flujo; no solicita un aborto ni sustituye la limpieza.

El productor llama a getWriter(), que bloquea el flujo para un único escritor. Gestiona las promesas de writer.write(), writer.close() y writer.abort(); las llamadas directas a stream.close() y stream.abort() devuelven promesas rechazadas mientras el flujo está bloqueado. writer.releaseLock() libera el bloqueo sin finalizar el flujo.

Ejemplos

(async () => {
  const log = [];
  const reason = new Error("stop");

  async function run(label, shouldAbort) {
    const stream = new WritableStream({
      start() {
        log.push(`${label}: start`);
      },
      async write(chunk) {
        await Promise.resolve();
        log.push(`${label}: write ${chunk}`);
      },
      close() {
        log.push(`${label}: close`);
      },
      abort(received) {
        log.push(`${label}: abort (${received === reason})`);
      },
    });

    const writer = stream.getWriter();
    try {
      await writer.write("A");
      if (shouldAbort) {
        await writer.abort(reason);
      } else {
        await writer.close();
      }
    } finally {
      writer.releaseLock();
    }
  }

  await run("normal", false);
  await run("interrupted", true);
  console.log(log.join("\n"));
})().catch(console.error);

Resultado

normal: start
normal: write A
normal: close
interrupted: start
interrupted: write A
interrupted: abort (true)

El ejemplo usa dos flujos distintos. Ambos terminan de escribir `A`; el primero se cierra y el segundo se aborta. `true` indica que el destino recibió exactamente el mismo objeto `Error`.

Lecciones relacionadas

  • JavaScript · Lección 4 · Avanzado · Versión: 4

Fuentes