Dictionary
Defined in: next/api.d.ts:395
A zstd or brotli dictionary, prepared once for every call that compresses
or decompresses with it, as the dictionary option of compress,
decompress and their *Sync variants.
zstd digests the bytes of a dictionary before it compresses or decompresses the first frame with them, which costs far more than a small message: a call with the bytes of a dictionary digests them every time, a Dictionary once. A zstd Dictionary is digested when it is created, for its compression level and for decompression. A brotli Dictionary is hashed for compression when it is created, for every level, which brotli otherwise does on every call with dictionaries of more than 256 KiB, and with more than 4 others on the same thread: 0.3 ms for a dictionary of 4 KiB, 2 to 4 ms for 256 KiB and 12 to 32 ms for 2 MiB. brotli decompression takes the bytes as they are.
A Dictionary holds memory outside the JavaScript heap. For zstd, that is
a copy of the bytes, a digest for decompression of about their size, and
a digest for each compression level that it keeps, which grows with the
level: 0.8 MB in all at level 3 for a dictionary of 110 KiB, and 2 MB at
level 19. For brotli, that is a copy of the bytes and about 270 KB of
tables, plus 4 bytes for each byte of the dictionary. The garbage collector frees it with the Dictionary;
Dictionary.close frees it earlier. [Symbol.dispose]() is
close(), for using declarations.
A Dictionary is for its Dictionary.format alone: with any other
format, the functions fail with ERR_COMPRS_INVALID_ARG, such as “this
Dictionary is for zstd”. Data compressed with a Dictionary decompresses
with its bytes too, and the other way round.
Extends
Section titled “Extends”Disposal
Properties
Section titled “Properties”[dispose]
Section titled “[dispose]”[dispose]: () =>
void
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”Disposal.[dispose]
byteLength
Section titled “byteLength”
readonlybyteLength:number
Defined in: next/api.d.ts:432
The size of the dictionary, in bytes.
format
Section titled “format”
readonlyformat:"zstd"|"brotli"
Defined in: next/api.d.ts:430
The format that the dictionary is for.
Methods
Section titled “Methods”close()
Section titled “close()”close():
void
Defined in: next/api.d.ts:465
Free the memory of the dictionary now, rather than when the garbage
collector collects it. Calls that already started with the dictionary
finish with it. Later calls with it, and Dictionary.toBytes,
fail with ERR_COMPRS_INVALID_ARG (“this Dictionary is closed”);
closing it again does nothing.
Returns
Section titled “Returns”void
toBytes()
Section titled “toBytes()”toBytes():
Uint8Array
Defined in: next/api.d.ts:457
A copy of the bytes of the dictionary, which decompress what the dictionary compressed, and compress what it decompresses.
Returns
Section titled “Returns”Uint8Array
Throws
Section titled “Throws”A TypeError with the code ERR_COMPRS_INVALID_ARG once the
dictionary is closed.
from()
Section titled “from()”
staticfrom(bytes,options):Dictionary
Defined in: next/api.d.ts:449
Prepare a dictionary for options.format from bytes, which may be any
bytes but must not be empty, such as a zstd dictionary that
trainDictionary trained. A zstd dictionary is digested for
compression at options.level and for decompression.
The bytes are copied, so changing them afterwards does not change the dictionary.
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”Dictionary
The dictionary.
Throws
Section titled “Throws”An error with an ErrorCode as code:
ERR_COMPRS_INVALID_ARG for invalid arguments, a level for a brotli
dictionary included, and ERR_COMPRS_OPERATION_FAILED for bytes that
zstd cannot digest, such as a trained dictionary cut short.