+Group: WHATWG +Status: RD +Date: 2025-11-05 +H1: Compression +Shortname: compression +Text Macro: TWITTER compressionapi +Text Macro: LATESTRD 2025-11 +Abstract: This document defines a set of JavaScript APIs to compress and decompress streams of binary data. +Translation: zh-Hans https://htmlspecs.com/compression/ +Translation: ja https://jp.htmlspecs.com/compression/ +Translation: ko https://ko.htmlspecs.com/compression/ +Indent: 2 +Markup Shorthands: markdown yes ++ +# Introduction # {#introduction} + +*This section is non-normative.* + +The APIs specified in this specification are used to compress and decompress streams of data. They support "deflate", "deflate-raw" and "gzip" as compression algorithms. They are widely used by web developers. + +# Infrastructure # {#infrastructure} + +This specification depends on Infra. [[!INFRA]] + +A chunk is a piece of data. In the case of CompressionStream and DecompressionStream, the output chunk type is Uint8Array. They accept any {{BufferSource}} type as input. + +A stream represents an ordered sequence of chunks. The terms {{ReadableStream}} and {{WritableStream}} are defined in Streams. [[!STREAMS]] + +A compression context is the internal state maintained by a compression or decompression algorithm. The contents of a compression context depend on the format, algorithm and implementation in use. From the point of view of this specification, it is an opaque object. A compression context is initially in a start state such that it anticipates the first byte of input. + +# Supported formats # {#supported-formats} + +: {{CompressionFormat/deflate}} +:: "ZLIB Compressed Data Format" [[!RFC1950]] + + Note: This format is referred to as "deflate" for consistency with HTTP Content-Encodings. See [[RFC7230 obsolete]] section 4.2.2. + + * Implementations must be "compliant" as described in [[!RFC1950]] section 2.3. + * Field values described as invalid in [[!RFC1950]] must not be created by CompressionStream, and are errors for DecompressionStream. + * The only valid value of the `CM` (Compression method) part of the `CMF` field is 8. + * The `FDICT` flag is not supported by these APIs, and will error the stream if set. + * The `FLEVEL` flag is ignored by DecompressionStream. + * It is an error for DecompressionStream if the `ADLER32` checksum is not correct. + * It is an error if there is additional input data after the `ADLER32` checksum. + +: {{CompressionFormat/deflate-raw}} +:: "The DEFLATE algorithm" [[!RFC1951]] + + * Implementations must be "compliant" as described in [[!RFC1951]] section 1.4. + * Non-[[!RFC1951]]-conforming blocks must not be created by CompressionStream, and are errors for DecompressionStream. + * It is an error if there is additional input data after the final block indicated by the `BFINAL` flag. + +: {{CompressionFormat/gzip}} +:: "GZIP file format" [[!RFC1952]] + + * Implementations must be "compliant" as described in [[!RFC1952]] section 2.3.1.2. + * Field values described as invalid in [[!RFC1952]] must not be created by CompressionStream, and are errors for DecompressionStream. + * The only valid value of the `CM` (Compression Method) field is 8. + * The `FTEXT` flag must be ignored by DecompressionStream. + * If the `FHCRC` field is present, it is an error for it to be incorrect. + * The contents of any `FEXTRA`, `FNAME` and `FCOMMENT` fields must be ignored by DecompressionStream, except to verify that they are terminated correctly. + * The contents of the `MTIME`, `XFL` and `OS` fields must be ignored by DecompressionStream. + * It is an error if `CRC32` or `ISIZE` do not match the decompressed data. + * A `gzip` stream may only contain one "member". + * It is an error if there is additional input data after the end of the "member". + +# Interface `CompressionStream` # {#compression-stream} + +
+enum CompressionFormat {
+ "deflate",
+ "deflate-raw",
+ "gzip",
+};
+
+[Exposed=*]
+interface CompressionStream {
+ constructor(CompressionFormat format);
+};
+CompressionStream includes GenericTransformStream;
+
+
+A {{CompressionStream}} has an associated format and compression context context.
+
+new CompressionStream(|format|) steps are:
+ 1. If |format| is unsupported in {{CompressionStream}}, then throw a {{TypeError}}.
+ 1. Set [=this=]'s format to |format|.
+ 1. Let |transformAlgorithm| be an algorithm which takes a |chunk| argument and runs the compress and enqueue a chunk algorithm with [=this=] and |chunk|.
+ 1. Let |flushAlgorithm| be an algorithm which takes no argument and runs the compress flush and enqueue algorithm with [=this=].
+ 1. Set [=this=]'s [=GenericTransformStream/transform=] to a [=new=] {{TransformStream}}.
+ 1. [=TransformStream/Set up=] [=this=]'s [=GenericTransformStream/transform=] with [=TransformStream/set up/transformAlgorithm=] set to |transformAlgorithm| and [=TransformStream/set up/flushAlgorithm=] set to |flushAlgorithm|.
+
+[Exposed=*]
+interface DecompressionStream {
+ constructor(CompressionFormat format);
+};
+DecompressionStream includes GenericTransformStream;
+
+
+A {{DecompressionStream}} has an associated format and compression context context.
+
+new DecompressionStream(|format|) steps are:
+ 1. If |format| is unsupported in {{DecompressionStream}}, then throw a {{TypeError}}.
+ 1. Set [=this=]'s format to |format|.
+ 1. Let |transformAlgorithm| be an algorithm which takes a |chunk| argument and runs the decompress and enqueue a chunk algorithm with [=this=] and |chunk|.
+ 1. Let |flushAlgorithm| be an algorithm which takes no argument and runs the decompress flush and enqueue algorithm with [=this=].
+ 1. Set [=this=]'s [=GenericTransformStream/transform=] to a [=new=] {{TransformStream}}.
+ 1. [=TransformStream/Set up=] [=this=]'s [=GenericTransformStream/transform=] with [=TransformStream/set up/transformAlgorithm=] set to |transformAlgorithm| and [=TransformStream/set up/flushAlgorithm=] set to |flushAlgorithm|.
+
+const compressedReadableStream
+ = inputReadableStream.pipeThrough(new CompressionStream('gzip'));
+
+
+async function compressArrayBuffer(input) {
+ const cs = new CompressionStream('deflate');
+
+ const writer = cs.writable.getWriter();
+ writer.write(input);
+ writer.close();
+
+ const output = [];
+ let totalSize = 0;
+ for (const chunk of cs.readable) {
+ output.push(value);
+ totalSize += value.byteLength;
+ }
+
+ const concatenated = new Uint8Array(totalSize);
+ let offset = 0;
+ for (const array of output) {
+ concatenated.set(array, offset);
+ offset += array.byteLength;
+ }
+
+ return concatenated;
+}
+
+
+function decompressBlob(blob) {
+ const ds = new DecompressionStream('gzip');
+ const decompressionStream = blob.stream().pipeThrough(ds);
+ return new Response(decompressionStream).blob();
+}
+
+This Living Standard was originally developed in the W3C WICG, where it was available under the [W3C Software and Document License](https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document).