Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit ca3c309

Browse filesBrowse files
Renegade334aduh95
Renegade334
authored and
aduh95
committed
doc: minor structural stream/iter edits
Signed-off-by: Renegade334 <contact.9a5d6388@renegade334.me.uk> PR-URL: #63089 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent ef08c50 commit ca3c309
Copy full SHA for ca3c309

4 files changed

+265-268Lines changed: 265 additions & 268 deletions

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎doc/api/index.md‎

Copy file name to clipboardExpand all lines: doc/api/index.md
+1-2Lines changed: 1 addition & 2 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,13 @@
3535
* [HTTPS](https.md)
3636
* [Inspector](inspector.md)
3737
* [Internationalization](intl.md)
38+
* [Iterable Streams API](stream_iter.md)
3839
* [Modules: CommonJS modules](modules.md)
3940
* [Modules: ECMAScript modules](esm.md)
4041
* [Modules: `node:module` API](module.md)
4142
* [Modules: Packages](packages.md)
4243
* [Modules: TypeScript](typescript.md)
4344
* [Net](net.md)
44-
* [Iterable Streams API](stream_iter.md)
4545
* [OS](os.md)
4646
* [Path](path.md)
4747
* [Performance hooks](perf_hooks.md)
@@ -71,7 +71,6 @@
7171
* [Web Streams API](webstreams.md)
7272
* [Worker threads](worker_threads.md)
7373
* [Zlib](zlib.md)
74-
* [Zlib Iterable Compression](zlib_iter.md)
7574

7675
<hr class="line"/>
7776

Collapse file

‎doc/api/stream_iter.md‎

Copy file name to clipboardExpand all lines: doc/api/stream_iter.md
+10-11Lines changed: 10 additions & 11 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -416,7 +416,7 @@ if (writer.endSync() < 0) await writer.end();
416416
writer.fail(err); // Always synchronous, no fallback needed
417417
```
418418

419-
### `writer.desiredSize`
419+
#### `writer.desiredSize`
420420

421421
* {number|null}
422422

@@ -425,7 +425,7 @@ Returns `null` if the writer is closed or the consumer has disconnected.
425425

426426
The value is always non-negative.
427427

428-
### `writer.end([options])`
428+
#### `writer.end([options])`
429429

430430
* `options` {Object}
431431
* `signal` {AbortSignal} Cancel just this operation. The signal cancels only
@@ -434,7 +434,7 @@ The value is always non-negative.
434434

435435
Signal that no more data will be written.
436436

437-
### `writer.endSync()`
437+
#### `writer.endSync()`
438438

439439
* Returns: {number} Total bytes written, or `-1` if the writer is not open.
440440

@@ -448,7 +448,7 @@ if (result < 0) {
448448
}
449449
```
450450

451-
### `writer.fail(reason)`
451+
#### `writer.fail(reason)`
452452

453453
* `reason` {any}
454454

@@ -457,7 +457,7 @@ or errored, this is a no-op. Unlike `write()` and `end()`, `fail()` is
457457
unconditionally synchronous because failing a writer is a pure state
458458
transition with no async work to perform.
459459

460-
### `writer.write(chunk[, options])`
460+
#### `writer.write(chunk[, options])`
461461

462462
* `chunk` {Uint8Array|string}
463463
* `options` {Object}
@@ -467,15 +467,15 @@ transition with no async work to perform.
467467

468468
Write a chunk. The promise resolves when buffer space is available.
469469

470-
### `writer.writeSync(chunk)`
470+
#### `writer.writeSync(chunk)`
471471

472472
* `chunk` {Uint8Array|string}
473473
* Returns: {boolean} `true` if the write was accepted, `false` if the
474474
buffer is full.
475475

476476
Synchronous write. Does not block; returns `false` if backpressure is active.
477477

478-
### `writer.writev(chunks[, options])`
478+
#### `writer.writev(chunks[, options])`
479479

480480
* `chunks` {Uint8Array\[]|string\[]}
481481
* `options` {Object}
@@ -485,7 +485,7 @@ Synchronous write. Does not block; returns `false` if backpressure is active.
485485

486486
Write multiple chunks as a single batch.
487487

488-
### `writer.writevSync(chunks)`
488+
#### `writer.writevSync(chunks)`
489489

490490
* `chunks` {Uint8Array\[]|string\[]}
491491
* Returns: {boolean} `true` if the write was accepted, `false` if the
@@ -1422,7 +1422,7 @@ added: v26.0.0
14221422

14231423
Compression and decompression transforms for use with `pull()`, `pullSync()`,
14241424
`pipeTo()`, and `pipeToSync()` are available via the [`node:zlib/iter`][]
1425-
module. See the [`node:zlib/iter` documentation][] for details.
1425+
module. See the [`node:zlib/iter` documentation][`node:zlib/iter`] for details.
14261426

14271427
## Classic stream interop
14281428

@@ -2069,8 +2069,7 @@ console.log(textSync(stream)); // 'hello world'
20692069
[`bytes()`]: #bytessource-options
20702070
[`from()`]: #frominput
20712071
[`fromSync()`]: #fromsyncinput
2072-
[`node:zlib/iter`]: zlib_iter.md
2073-
[`node:zlib/iter` documentation]: zlib_iter.md
2072+
[`node:zlib/iter`]: zlib.md#iterable-compression
20742073
[`pipeTo()`]: #pipetosource-transforms-writer-options
20752074
[`pull()`]: #pullsource-transforms-options
20762075
[`pullSync()`]: #pullsyncsource-transforms-options
Collapse file

‎doc/api/zlib.md‎

Copy file name to clipboardExpand all lines: doc/api/zlib.md
+254-1Lines changed: 254 additions & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -1746,11 +1746,261 @@ added:
17461746

17471747
Decompress a chunk of data with [`ZstdDecompress`][].
17481748

1749+
## Iterable Compression
1750+
1751+
<!-- YAML
1752+
added: v25.9.0
1753+
-->
1754+
1755+
> Stability: 1 - Experimental
1756+
1757+
The `node:zlib/iter` module provides compression and decompression transforms
1758+
for use with the [`node:stream/iter`][] iterable streams API.
1759+
1760+
This module is available only when the `--experimental-stream-iter` CLI flag
1761+
is enabled.
1762+
1763+
Each algorithm has both an async variant (stateful async generator, for use
1764+
with [`pull()`][] and [`pipeTo()`][]) and a sync variant (stateful sync
1765+
generator, for use with `pullSync()` and `pipeToSync()`).
1766+
1767+
The async transforms run compression on the libuv threadpool, overlapping
1768+
I/O with JavaScript execution. The sync transforms run compression directly
1769+
on the main thread.
1770+
1771+
> Note: The defaults for these transforms are tuned for streaming throughput,
1772+
> and differ from the defaults in `node:zlib`. In particular, gzip/deflate
1773+
> default to level 4 (not 6) and memLevel 9 (not 8), and Brotli defaults to
1774+
> quality 6 (not 11). These choices match common HTTP server configurations
1775+
> and provide significantly faster compression with only a small reduction in
1776+
> compression ratio. All defaults can be overridden via options.
1777+
1778+
```mjs
1779+
import { from, pull, bytes, text } from 'node:stream/iter';
1780+
import { compressGzip, decompressGzip } from 'node:zlib/iter';
1781+
1782+
// Async round-trip
1783+
const compressed = await bytes(pull(from('hello'), compressGzip()));
1784+
const original = await text(pull(from(compressed), decompressGzip()));
1785+
console.log(original); // 'hello'
1786+
```
1787+
1788+
```cjs
1789+
const { from, pull, bytes, text } = require('node:stream/iter');
1790+
const { compressGzip, decompressGzip } = require('node:zlib/iter');
1791+
1792+
async function run() {
1793+
const compressed = await bytes(pull(from('hello'), compressGzip()));
1794+
const original = await text(pull(from(compressed), decompressGzip()));
1795+
console.log(original); // 'hello'
1796+
}
1797+
1798+
run().catch(console.error);
1799+
```
1800+
1801+
```mjs
1802+
import { fromSync, pullSync, textSync } from 'node:stream/iter';
1803+
import { compressGzipSync, decompressGzipSync } from 'node:zlib/iter';
1804+
1805+
// Sync round-trip
1806+
const compressed = pullSync(fromSync('hello'), compressGzipSync());
1807+
const original = textSync(pullSync(compressed, decompressGzipSync()));
1808+
console.log(original); // 'hello'
1809+
```
1810+
1811+
```cjs
1812+
const { fromSync, pullSync, textSync } = require('node:stream/iter');
1813+
const { compressGzipSync, decompressGzipSync } = require('node:zlib/iter');
1814+
1815+
const compressed = pullSync(fromSync('hello'), compressGzipSync());
1816+
const original = textSync(pullSync(compressed, decompressGzipSync()));
1817+
console.log(original); // 'hello'
1818+
```
1819+
1820+
### `compressBrotli([options])`
1821+
1822+
### `compressBrotliSync([options])`
1823+
1824+
<!-- YAML
1825+
added: v25.9.0
1826+
-->
1827+
1828+
* `options` {Object}
1829+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1830+
* `params` {Object} Key-value object where keys and values are
1831+
`zlib.constants` entries. The most important compressor parameters are:
1832+
* `BROTLI_PARAM_MODE` -- `BROTLI_MODE_GENERIC` (default),
1833+
`BROTLI_MODE_TEXT`, or `BROTLI_MODE_FONT`.
1834+
* `BROTLI_PARAM_QUALITY` -- ranges from `BROTLI_MIN_QUALITY` to
1835+
`BROTLI_MAX_QUALITY`. **Default:** `6` (not `BROTLI_DEFAULT_QUALITY`
1836+
which is 11). Quality 6 is appropriate for streaming; quality 11 is
1837+
intended for offline/build-time compression.
1838+
* `BROTLI_PARAM_SIZE_HINT` -- expected input size. **Default:** `0`
1839+
(unknown).
1840+
* `BROTLI_PARAM_LGWIN` -- window size (log2). **Default:** `20` (1 MB).
1841+
The Brotli library default is 22 (4 MB); the reduced default saves
1842+
memory without significant compression impact for streaming workloads.
1843+
* `BROTLI_PARAM_LGBLOCK` -- input block size (log2).
1844+
See the [Brotli compressor options][] in the zlib documentation for the
1845+
full list.
1846+
* `dictionary` {Buffer|TypedArray|DataView}
1847+
* Returns: {Object} A stateful transform.
1848+
1849+
Create a Brotli compression transform. Output is compatible with
1850+
`zlib.brotliDecompress()` and `decompressBrotli()`/`decompressBrotliSync()`.
1851+
1852+
### `compressDeflate([options])`
1853+
1854+
### `compressDeflateSync([options])`
1855+
1856+
<!-- YAML
1857+
added: v25.9.0
1858+
-->
1859+
1860+
* `options` {Object}
1861+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1862+
* `level` {number} Compression level (`0`-`9`). **Default:** `4`.
1863+
* `windowBits` {number} **Default:** `Z_DEFAULT_WINDOWBITS` (15).
1864+
* `memLevel` {number} **Default:** `9`.
1865+
* `strategy` {number} **Default:** `Z_DEFAULT_STRATEGY`.
1866+
* `dictionary` {Buffer|TypedArray|DataView}
1867+
* Returns: {Object} A stateful transform.
1868+
1869+
Create a deflate compression transform. Output is compatible with
1870+
`zlib.inflate()` and `decompressDeflate()`/`decompressDeflateSync()`.
1871+
1872+
### `compressGzip([options])`
1873+
1874+
### `compressGzipSync([options])`
1875+
1876+
<!-- YAML
1877+
added: v25.9.0
1878+
-->
1879+
1880+
* `options` {Object}
1881+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1882+
* `level` {number} Compression level (`0`-`9`). **Default:** `4`.
1883+
* `windowBits` {number} **Default:** `Z_DEFAULT_WINDOWBITS` (15).
1884+
* `memLevel` {number} **Default:** `9`.
1885+
* `strategy` {number} **Default:** `Z_DEFAULT_STRATEGY`.
1886+
* `dictionary` {Buffer|TypedArray|DataView}
1887+
* Returns: {Object} A stateful transform.
1888+
1889+
Create a gzip compression transform. Output is compatible with `zlib.gunzip()`
1890+
and `decompressGzip()`/`decompressGzipSync()`.
1891+
1892+
### `compressZstd([options])`
1893+
1894+
### `compressZstdSync([options])`
1895+
1896+
<!-- YAML
1897+
added: v25.9.0
1898+
-->
1899+
1900+
* `options` {Object}
1901+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1902+
* `params` {Object} Key-value object where keys and values are
1903+
`zlib.constants` entries. The most important compressor parameters are:
1904+
* `ZSTD_c_compressionLevel` -- **Default:** `ZSTD_CLEVEL_DEFAULT` (3).
1905+
* `ZSTD_c_checksumFlag` -- generate a checksum. **Default:** `0`.
1906+
* `ZSTD_c_strategy` -- compression strategy. Values include
1907+
`ZSTD_fast`, `ZSTD_dfast`, `ZSTD_greedy`, `ZSTD_lazy`,
1908+
`ZSTD_lazy2`, `ZSTD_btlazy2`, `ZSTD_btopt`, `ZSTD_btultra`,
1909+
`ZSTD_btultra2`.
1910+
See the [Zstd compressor options][] in the zlib documentation for the
1911+
full list.
1912+
* `pledgedSrcSize` {number} Expected uncompressed size (optional hint).
1913+
* `dictionary` {Buffer|TypedArray|DataView}
1914+
* Returns: {Object} A stateful transform.
1915+
1916+
Create a Zstandard compression transform. Output is compatible with
1917+
`zlib.zstdDecompress()` and `decompressZstd()`/`decompressZstdSync()`.
1918+
1919+
### `decompressBrotli([options])`
1920+
1921+
### `decompressBrotliSync([options])`
1922+
1923+
<!-- YAML
1924+
added: v25.9.0
1925+
-->
1926+
1927+
* `options` {Object}
1928+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1929+
* `params` {Object} Key-value object where keys and values are
1930+
`zlib.constants` entries. Available decompressor parameters:
1931+
* `BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION` -- boolean
1932+
flag affecting internal memory allocation.
1933+
* `BROTLI_DECODER_PARAM_LARGE_WINDOW` -- boolean flag enabling "Large
1934+
Window Brotli" mode (not compatible with [RFC 7932][]).
1935+
See the [Brotli decompressor options][] in the zlib documentation for
1936+
details.
1937+
* `dictionary` {Buffer|TypedArray|DataView}
1938+
* Returns: {Object} A stateful transform.
1939+
1940+
Create a Brotli decompression transform.
1941+
1942+
### `decompressDeflate([options])`
1943+
1944+
### `decompressDeflateSync([options])`
1945+
1946+
<!-- YAML
1947+
added: v25.9.0
1948+
-->
1949+
1950+
* `options` {Object}
1951+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1952+
* `windowBits` {number} **Default:** `Z_DEFAULT_WINDOWBITS` (15).
1953+
* `dictionary` {Buffer|TypedArray|DataView}
1954+
* Returns: {Object} A stateful transform.
1955+
1956+
Create a deflate decompression transform.
1957+
1958+
### `decompressGzip([options])`
1959+
1960+
### `decompressGzipSync([options])`
1961+
1962+
<!-- YAML
1963+
added: v25.9.0
1964+
-->
1965+
1966+
* `options` {Object}
1967+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1968+
* `windowBits` {number} **Default:** `Z_DEFAULT_WINDOWBITS` (15).
1969+
* `dictionary` {Buffer|TypedArray|DataView}
1970+
* Returns: {Object} A stateful transform.
1971+
1972+
Create a gzip decompression transform.
1973+
1974+
### `decompressZstd([options])`
1975+
1976+
### `decompressZstdSync([options])`
1977+
1978+
<!-- YAML
1979+
added: v25.9.0
1980+
-->
1981+
1982+
* `options` {Object}
1983+
* `chunkSize` {number} Output buffer size. **Default:** `65536` (64 KB).
1984+
* `params` {Object} Key-value object where keys and values are
1985+
`zlib.constants` entries. Available decompressor parameters:
1986+
* `ZSTD_d_windowLogMax` -- maximum window size (log2) the decompressor
1987+
will allocate. Limits memory usage against malicious input.
1988+
See the [Zstd decompressor options][] in the zlib documentation for
1989+
details.
1990+
* `dictionary` {Buffer|TypedArray|DataView}
1991+
* Returns: {Object} A stateful transform.
1992+
1993+
Create a Zstandard decompression transform.
1994+
1995+
[Brotli compressor options]: #compressor-options
1996+
[Brotli decompressor options]: #decompressor-options
17491997
[Brotli parameters]: #brotli-constants
17501998
[Cyclic redundancy check]: https://en.wikipedia.org/wiki/Cyclic_redundancy_check
17511999
[Memory usage tuning]: #memory-usage-tuning
1752-
[RFC 7932]: https://www.rfc-editor.org/rfc/rfc7932.txt
2000+
[RFC 7932]: https://www.rfc-editor.org/rfc/rfc7932.html
17532001
[Streams API]: stream.md
2002+
[Zstd compressor options]: #compressor-options-1
2003+
[Zstd decompressor options]: #decompressor-options-1
17542004
[Zstd parameters]: #zstd-constants
17552005
[`.flush()`]: #zlibflushkind-callback
17562006
[`Accept-Encoding`]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
@@ -1769,6 +2019,9 @@ Decompress a chunk of data with [`ZstdDecompress`][].
17692019
[`ZstdDecompress`]: #class-zlibzstddecompress
17702020
[`buffer.kMaxLength`]: buffer.md#bufferkmaxlength
17712021
[`deflateInit2` and `inflateInit2`]: https://zlib.net/manual.html#Advanced
2022+
[`node:stream/iter`]: stream_iter.md
2023+
[`pipeTo()`]: stream_iter.md#pipetosource-transforms-writer-options
2024+
[`pull()`]: stream_iter.md#pullsource-transforms-options
17722025
[`stream.Transform`]: stream.md#class-streamtransform
17732026
[convenience methods]: #convenience-methods
17742027
[zlib documentation]: https://zlib.net/manual.html#Constants

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.