# `nupp.compression`
Compressing and decompressing a stream of bytes.
Ask for a format, then use its one-shot helpers or wrap a `nupp.io` reader or
writer:
```nupp:fragment
local compression = require("nupp.compression")
const gzip = compression.format("gzip")
const encoded = gzip:newWriter(destination, {
gzip = {level = 6},
})
encoded:write("hello")
assert(encoded:finish())
```
A factory consumes the reader or writer it wraps. A compression writer has to
end in `finish()`; closing or dropping one unfinished aborts the stream and
raises, because a truncated member is worse than a loud failure.
Adapter policy and format options are separate, which is why the options table
is keyed by format name.
## Built-in formats
| Name | Container | Writer options | Reader options |
| --- | --- | --- | --- |
| `gzip` | RFC 1952 gzip | `gzip = { level = 0..9 }` | `gzip = { concatenatedMembers = boolean }` |
| `zlib` | RFC 1950 zlib | `zlib = { level = 0..9 }` | none |
| `deflate-raw` | RFC 1951 raw DEFLATE | `deflateRaw = { level = 0..9 }` | none |
All three take levels zero through nine. Gzip checks its CRC and size trailers
and reads concatenated members by default, zlib checks its Adler-32 trailer, and
raw DEFLATE has no checksum at all. Trailing bytes are rejected in every case.
A provider-added format keys its options by its own canonical name;
`deflateRaw` above is the built-in ergonomic spelling of `deflate-raw`.
## Submodules
| Module | Description |
| --- | --- |
| `nupp.compression.spi` | Implementation interfaces for compression stream catalogs. |
## Types
### `CompressionWriter` _interface_
```nupp
interface CompressionWriter is io.Writer ...
```
An ordinary writer whose consuming `finish` emits the final trailer.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`close`](#nupp.compression.CompressionWriter.close) | method | Aborts an unfinished stream and raises after releasing owned resources. |
| [`finish`](#nupp.compression.CompressionWriter.finish) | method | Completes the stream, flushes and closes the owned destination. |
#### `close` _method_
```nupp
close: @nosuspend function(takes self: CompressionWriter): nil
```
Aborts an unfinished stream and raises after releasing owned resources.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `takes self` | `CompressionWriter` | |
##### Returns
| Type | Description |
| --- | --- |
| `nil` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | whenever the stream was not consumed by `finish` |
#### `finish` _method_
```nupp
finish: function(takes self: CompressionWriter): (boolean, string?)
```
Completes the stream, flushes and closes the owned destination.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `takes self` | `CompressionWriter` | |
##### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
| `string?` | |
### `DeflateRawWriterOptions` _interface_
```nupp
interface DeflateRawWriterOptions ...
```
Options in the `deflateRaw` block passed to a compression writer.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`level`](#nupp.compression.DeflateRawWriterOptions.level) | field | Compression level from zero through nine; six by default. |
#### `level` _field_
```nupp
level: integer?
```
Compression level from zero through nine; six by default.
### `Format` _record_
```nupp
record Format ...
```
Retained compression format descriptor.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`name`](#nupp.compression.Format.name) | field | Canonical format name. |
| [`implementation`](#nupp.compression.Format.implementation) | field | |
| [`newReader`](#nupp.compression.Format.newReader) | method | Wraps and owns a reader, validating the stream before EOF. |
| [`newWriter`](#nupp.compression.Format.newWriter) | method | Wraps and owns a writer. |
| [`compress`](#nupp.compression.Format.compress) | method | Compresses a borrowed span into a destination buffer. |
| [`compress`](#nupp.compression.Format.compress) | method | Compresses a string into a destination buffer. |
| [`compress`](#nupp.compression.Format.compress) | method | Compresses a borrowed span into a new string. |
| [`compress`](#nupp.compression.Format.compress) | method | Compresses a string into a new string. |
| [`decompress`](#nupp.compression.Format.decompress) | method | Decompresses a borrowed span into a destination buffer. |
| [`decompress`](#nupp.compression.Format.decompress) | method | Decompresses a string into a destination buffer. |
| [`decompress`](#nupp.compression.Format.decompress) | method | Decompresses a borrowed span into a new string with a 64 MiB default cap. |
| [`decompress`](#nupp.compression.Format.decompress) | method | Decompresses a string into a new string with a 64 MiB default cap. |
#### `name` _field_
```nupp
name: string
```
`@readonly`
Canonical format name.
#### `implementation` _field_
```nupp
implementation: provider.Format
```
`@private`
#### `newReader` _method_
```nupp
newReader: function newReader(self, takes source: io.Reader, options: ReaderOptions?): io.Reader
```
Wraps and owns a reader, validating the stream before EOF.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `takes source` | `io.Reader` | |
| `options` | `ReaderOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `io.Reader` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid or a format block does not match |
#### `newWriter` _method_
```nupp
newWriter: function newWriter(self, takes destination: io.Writer, options: WriterOptions?): CompressionWriter
```
Wraps and owns a writer. Consume the result with `finish()`.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `takes destination` | `io.Writer` | |
| `options` | `WriterOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `CompressionWriter` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid or a format block does not match |
#### `compress` _method_
```nupp
compress: function compress(self, borrows bytes: span.ByteSpan, exclusive destination: io.Buffer, options: WriterOptions?): nil
```
Compresses a borrowed span into a destination buffer.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `borrows bytes` | `span.ByteSpan` | |
| `exclusive destination` | `io.Buffer` | |
| `options` | `WriterOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `nil` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid or compression fails |
#### `compress` _method_
```nupp
compress: function compress(self, bytes: string, exclusive destination: io.Buffer, options: WriterOptions?): nil
```
Compresses a string into a destination buffer.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `bytes` | `string` | |
| `exclusive destination` | `io.Buffer` | |
| `options` | `WriterOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `nil` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid or compression fails |
#### `compress` _method_
```nupp
compress: function compress(self, borrows bytes: span.ByteSpan, options: WriterOptions?): string
```
Compresses a borrowed span into a new string.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `borrows bytes` | `span.ByteSpan` | |
| `options` | `WriterOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid or compression fails |
#### `compress` _method_
```nupp
compress: function compress(self, bytes: string, options: WriterOptions?): string
```
Compresses a string into a new string.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `bytes` | `string` | |
| `options` | `WriterOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid or compression fails |
#### `decompress` _method_
```nupp
decompress: function decompress(self, borrows bytes: span.ByteSpan, exclusive destination: io.Buffer, options: ReaderOptions?): nil
```
Decompresses a borrowed span into a destination buffer.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `borrows bytes` | `span.ByteSpan` | |
| `exclusive destination` | `io.Buffer` | |
| `options` | `ReaderOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `nil` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid, the stream is invalid or a limit is exceeded |
#### `decompress` _method_
```nupp
decompress: function decompress(self, bytes: string, exclusive destination: io.Buffer, options: ReaderOptions?): nil
```
Decompresses a string into a destination buffer.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `bytes` | `string` | |
| `exclusive destination` | `io.Buffer` | |
| `options` | `ReaderOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `nil` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid, the stream is invalid or a limit is exceeded |
#### `decompress` _method_
```nupp
decompress: function decompress(self, borrows bytes: span.ByteSpan, options: ReaderOptions?): string
```
Decompresses a borrowed span into a new string with a 64 MiB default cap.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `borrows bytes` | `span.ByteSpan` | |
| `options` | `ReaderOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid, the stream is invalid or a limit is exceeded |
#### `decompress` _method_
```nupp
decompress: function decompress(self, bytes: string, options: ReaderOptions?): string
```
Decompresses a string into a new string with a 64 MiB default cap.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `bytes` | `string` | |
| `options` | `ReaderOptions?` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when options are invalid, the stream is invalid or a limit is exceeded |
### `GzipReaderOptions` _interface_
```nupp
interface GzipReaderOptions ...
```
Options in the `gzip` block passed to a decompression reader.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`concatenatedMembers`](#nupp.compression.GzipReaderOptions.concatenatedMembers) | field | Whether to decode concatenated gzip members; true by default. |
#### `concatenatedMembers` _field_
```nupp
concatenatedMembers: boolean?
```
Whether to decode concatenated gzip members; true by default.
### `GzipWriterOptions` _interface_
```nupp
interface GzipWriterOptions ...
```
Options in the `gzip` block passed to a compression writer.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`level`](#nupp.compression.GzipWriterOptions.level) | field | Compression level from zero through nine; six by default. |
#### `level` _field_
```nupp
level: integer?
```
Compression level from zero through nine; six by default.
### `ReaderOptions` _interface_
```nupp
interface ReaderOptions ...
```
Common decompression-reader policy.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`workspaceBytes`](#nupp.compression.ReaderOptions.workspaceBytes) | field | Provider workspace in bytes; 65536 by default. |
| [`maxOutputBytes`](#nupp.compression.ReaderOptions.maxOutputBytes) | field | Most decompressed bytes to produce; 64 MiB by default. |
| [`maxExpansionRatio`](#nupp.compression.ReaderOptions.maxExpansionRatio) | field | Maximum output-to-input ratio after a 1 KiB input allowance. |
| [`unbounded`](#nupp.compression.ReaderOptions.unbounded) | field | Explicitly removes the default output cap. |
| [`gzip`](#nupp.compression.ReaderOptions.gzip) | field | Gzip-specific options, accepted only by the gzip descriptor. |
#### `workspaceBytes` _field_
```nupp
workspaceBytes: integer?
```
Provider workspace in bytes; 65536 by default.
#### `maxOutputBytes` _field_
```nupp
maxOutputBytes: integer?
```
Most decompressed bytes to produce; 64 MiB by default.
#### `maxExpansionRatio` _field_
```nupp
maxExpansionRatio: number?
```
Maximum output-to-input ratio after a 1 KiB input allowance.
#### `unbounded` _field_
```nupp
unbounded: boolean?
```
Explicitly removes the default output cap.
#### `gzip` _field_
```nupp
gzip: GzipReaderOptions?
```
Gzip-specific options, accepted only by the gzip descriptor.
### `WriterOptions` _interface_
```nupp
interface WriterOptions ...
```
Common compression-writer policy.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`workspaceBytes`](#nupp.compression.WriterOptions.workspaceBytes) | field | Provider workspace in bytes; 65536 by default. |
| [`gzip`](#nupp.compression.WriterOptions.gzip) | field | Gzip-specific options, accepted only by the gzip descriptor. |
| [`zlib`](#nupp.compression.WriterOptions.zlib) | field | Zlib-specific options, accepted only by the zlib descriptor. |
| [`deflateRaw`](#nupp.compression.WriterOptions.deflateRaw) | field | Raw-DEFLATE-specific options, accepted only by the deflate-raw descriptor. |
#### `workspaceBytes` _field_
```nupp
workspaceBytes: integer?
```
Provider workspace in bytes; 65536 by default.
#### `gzip` _field_
```nupp
gzip: GzipWriterOptions?
```
Gzip-specific options, accepted only by the gzip descriptor.
#### `zlib` _field_
```nupp
zlib: ZlibWriterOptions?
```
Zlib-specific options, accepted only by the zlib descriptor.
#### `deflateRaw` _field_
```nupp
deflateRaw: DeflateRawWriterOptions?
```
Raw-DEFLATE-specific options, accepted only by the deflate-raw descriptor.
### `ZlibWriterOptions` _interface_
```nupp
interface ZlibWriterOptions ...
```
Options in the `zlib` block passed to a compression writer.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`level`](#nupp.compression.ZlibWriterOptions.level) | field | Compression level from zero through nine; six by default. |
#### `level` _field_
```nupp
level: integer?
```
Compression level from zero through nine; six by default.
## Functions
### `format` _function_
```nupp
function format(name: string): Format
```
Acquires a retained format descriptor or raises when unavailable.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `Format` | |
### `formats` _function_
```nupp
function formats(): {string}
```
Lists available canonical format names in ascending order.
#### Returns
| Type | Description |
| --- | --- |
| `{string}` | |