# `nupp.compression.spi` Implementation interfaces for compression stream catalogs. Providers expose retained format descriptors. A descriptor creates independent encoder and decoder state, and every state operation is span based. Input steps return input consumed, output written and one of the integer status constants below. Flush and finalization steps return output written and a status. A failed step returns nil numeric fields and a reason. Providers retain neither span and perform no SPI lookup from a state operation. The facade chooses the unique highest-priority catalog during initialization. Each format name agrees with its catalog key. Selected formats replace native formats with the same names and may add others. Discovery order never selects a provider. ## Types ### `Decoder` _interface_ ```nupp interface Decoder is nupp.Closeable ... ``` Independent incremental decompression state. #### Members | Name | Kind | Description | | --- | --- | --- | | [`close`](#nupp.compression.spi.Decoder.close) | method | Releases decoder state. | | [`read`](#nupp.compression.spi.Decoder.read) | method | Consumes input and produces output. | | [`finishInput`](#nupp.compression.spi.Decoder.finishInput) | method | Reports source EOF. | #### `close` _method_ ```nupp close: @nosuspend function(takes self: Decoder): nil ``` Releases decoder state. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Decoder` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `read` _method_ ```nupp read: function( exclusive self: Decoder, borrows input: ByteSpan, exclusive output: ByteWriteSpan ): (integer?, integer?, integer?, string?) ``` Consumes input and produces output. `NEED_INPUT` consumes the whole input; `NEED_OUTPUT` fills the output; `FINISHED` completes the stream. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Decoder` | | | `borrows input` | `ByteSpan` | | | `exclusive output` | `ByteWriteSpan` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | | `integer?` | | | `integer?` | | | `string?` | | #### `finishInput` _method_ ```nupp finishInput: function(exclusive self: Decoder, exclusive output: ByteWriteSpan): (integer?, integer?, string?) ``` Reports source EOF. `FINISHED` completes the stream, `NEED_OUTPUT` fills the output and `NEED_INPUT` reports a truncated stream. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Decoder` | | | `exclusive output` | `ByteWriteSpan` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | | `integer?` | | | `string?` | | ### `Encoder` _interface_ ```nupp interface Encoder is nupp.Closeable ... ``` Independent incremental compression state. #### Members | Name | Kind | Description | | --- | --- | --- | | [`close`](#nupp.compression.spi.Encoder.close) | method | Releases encoder state without producing a trailer. | | [`write`](#nupp.compression.spi.Encoder.write) | method | Consumes input and produces output. | | [`flush`](#nupp.compression.spi.Encoder.flush) | method | Flushes pending output. | | [`finish`](#nupp.compression.spi.Encoder.finish) | method | Produces the trailer. | #### `close` _method_ ```nupp close: @nosuspend function(takes self: Encoder): nil ``` Releases encoder state without producing a trailer. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Encoder` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `write` _method_ ```nupp write: function( exclusive self: Encoder, borrows input: ByteSpan, exclusive output: ByteWriteSpan ): (integer?, integer?, integer?, string?) ``` Consumes input and produces output. `NEED_INPUT` consumes the whole input; `NEED_OUTPUT` fills the whole output span. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Encoder` | | | `borrows input` | `ByteSpan` | | | `exclusive output` | `ByteWriteSpan` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | | `integer?` | | | `integer?` | | | `string?` | | #### `flush` _method_ ```nupp flush: function(exclusive self: Encoder, exclusive output: ByteWriteSpan): (integer?, integer?, string?) ``` Flushes pending output. `NEED_INPUT` completes the flush; `NEED_OUTPUT` fills the whole output span. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Encoder` | | | `exclusive output` | `ByteWriteSpan` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | | `integer?` | | | `string?` | | #### `finish` _method_ ```nupp finish: function(exclusive self: Encoder, exclusive output: ByteWriteSpan): (integer?, integer?, string?) ``` Produces the trailer. `FINISHED` completes the stream; `NEED_OUTPUT` fills the whole output span and requires another call. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Encoder` | | | `exclusive output` | `ByteWriteSpan` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | | `integer?` | | | `string?` | | ### `Format` _interface_ ```nupp interface Format ... ``` Immutable format identity and state factories. #### Members | Name | Kind | Description | | --- | --- | --- | | [`name`](#nupp.compression.spi.Format.name) | field | Canonical format name, matching the catalog map key. | | [`createEncoder`](#nupp.compression.spi.Format.createEncoder) | method | Creates independent encoder state for checked format options. | | [`createDecoder`](#nupp.compression.spi.Format.createDecoder) | method | Creates independent decoder state for checked format options. | #### `name` _field_ ```nupp name: string ``` `@readonly` Canonical format name, matching the catalog map key. #### `createEncoder` _method_ ```nupp createEncoder: function(self: Format, options: FormatOptions?): Encoder ``` Creates independent encoder state for checked format options. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Format` | | | `options` | `FormatOptions?` | | ##### Returns | Type | Description | | --- | --- | | `Encoder` | | #### `createDecoder` _method_ ```nupp createDecoder: function(self: Format, options: FormatOptions?): Decoder ``` Creates independent decoder state for checked format options. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Format` | | | `options` | `FormatOptions?` | | ##### Returns | Type | Description | | --- | --- | | `Decoder` | | ### `FormatOptions` _type_ ```nupp type FormatOptions = {@readonly [string]: any} ``` The selected format's structural option block. ### `Provider` _interface_ ```nupp interface Provider ... ``` A selectable implementation catalog. #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.compression.spi.Provider.priority) | field | | | [`formats`](#nupp.compression.spi.Provider.formats) | field | Canonical names mapped to checked, independent-state factories. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `formats` _field_ ```nupp formats: {[string]: Format} ``` `@readonly` Canonical names mapped to checked, independent-state factories. ## Values ### `FINISHED` _variable_ ```nupp const FINISHED ``` The complete stream and its wrapper trailer have been processed. ### `NEED_INPUT` _variable_ ```nupp const NEED_INPUT ``` The step needs another input chunk. ### `NEED_OUTPUT` _variable_ ```nupp const NEED_OUTPUT ``` The step filled its output and must be called with more space.