#flate

#Install

moon add moonbit-community/flate

#Quick start

///|
test "README raw DEFLATE round-trip" {
  let source = b"runtime-agnostic streaming compression"
  let compressed = @flate.deflate_all(source)
  @test.assert_eq(@flate.inflate_all(compressed), source)
}

///|
test "README caller-buffer DEFLATE" {
  let source = b"direct input and caller-owned output"
  let compressor = @flate.Compressor(level=6)
  let compressed_buffer = FixedArray::make(
    @flate.deflate_bound(source.length()),
    b'\x00',
  )
  guard compressor.compress_into(source, compressed_buffer)
    is Some(compressed_len) else {
    @test.fail("deflate_bound was too small")
  }
  let compressed = Bytes::from_array(compressed_buffer[:compressed_len])
  let decompressor = @flate.Decompressor()
  let output = FixedArray::make(source.length(), b'\x00')
  let decoded_len = decompressor.decompress_into(compressed, output)
  @test.assert_eq(Bytes::from_array(output[:decoded_len]), source)
}

///|
test "README prefix decode" {
  // A record: a raw DEFLATE stream, then whatever follows it.
  let payload = b"the stream ends with its final block"
  let record = @flate.deflate_all(payload) + b"what follows"
  let decompressor = @flate.Decompressor()
  @test.assert_eq(decompressor.decompress(record), payload)
  let rest = record[decompressor.last_consumed():]
  @test.assert_eq(rest.to_owned(), b"what follows")
}

///|
test "README streaming Deflater" {
  let source = b"small buffers exercise suspension and resume"
  let encoder = @flate.Deflater()
  let chunk = FixedArray::make(3, b'\x00')
  let compressed = @buffer.Buffer()
  let mut first = true
  for ;; {
    let input = if first { source[:] } else { b"" }
    let status = encoder.step(
      input,
      chunk.mut_view(),
      action=if first { Finish } else { Continue },
    )
    let consumed = encoder.last_consumed()
    let produced = encoder.last_produced()
    @test.assert_eq(consumed, if first { source.length() } else { 0 })
    first = false
    for i in 0..<produced {
      compressed.write_byte(chunk[i])
    }
    if status is Done {
      break
    }
  }
  @test.assert_eq(@flate.inflate_all(compressed.to_bytes()), source)
}

#State-machine contract

• step returns the state-machine Status; last_consumed() and last_produced() describe exactly the prefixes accepted and written by that call. Drop only input[:consumed]; large input views may be partially consumed when output is backpressured, keeping internal memory bounded.
• NeedMoreOutput preserves all pending work. Resume with another non-empty output view; one byte is sufficient.
• Inflater owns the bounded tail of an incomplete atomic unit. On NeedMoreInput, feed the next non-overlapping chunk; no growing replay window is required.
• Encoders take one DeflateAction: Continue, SyncFlush, or Finish. Pass the requested action with the final input of that batch. If consumed < input.length(), re-present that suffix with the same action. Once the complete view is accepted, the request remains latched across output backpressure.
• Inflater::step_into(input, output) accepts a complete FixedArray[Byte] and uses bulk window copies. It has the same consumption and backpressure semantics as step, which accepts arbitrary mutable output views. Both release caller buffers after each call.
• gzip and zlib Decoder::step_into(input, output) accept a complete FixedArray[Byte] and checksum decoded output in batches. Use it when the caller owns a fixed output buffer; step accepts arbitrary mutable views. Both drain pending body input before accepting more, so output can be produced while last_consumed() is zero. Re-present the unaccepted input on the next call.
• Raw Inflater::step(..., end=true) and the container decoders turn physical EOF before Done into a stable truncation error. After any decoder error, discard or reset the raw engine; container decoder instances stably rethrow the same error.
• Once Done is returned, new input is not consumed; reset the raw engine or the zlib Encoder (reset(dictionary?)), or create a new wrapper, before reuse. A reset encoder produces exactly the bytes of a freshly constructed one with the same options and driving schedule, while reusing its workspace.
• Configure a raw preset dictionary through Deflater(...)/Inflater(...), or while starting a fresh stream through reset(dictionary=...); dictionary selection cannot be mutated after a stream begins.
• gzip/zlib decoders may accept transport read-ahead beyond their trailer; after Done, recover that suffix with unused_input() before parsing the next protocol frame. For an exact one-member gzip boundary, construct the decoder with multistream=false.
• Raw failures expose a stable InflateErrorKind (Truncated, Corrupt, TrailingData, OutputLimitExceeded, or Cancelled) alongside diagnostic text; gzip/zlib similarly expose GzipErrorKind/ZlibErrorKind.
• One-shot decoding (inflate_all, inflate_exact) accepts an optional cancelled callback, polled at entry and then every ~4-8 KiB of decoded output; returning true raises InflateError(Cancelled, _), so untrusted-input loops can react to cancellation without streaming plumbing.

#Exact and bounded one-shot decoding

///|
test "README exact and limited inflate" {
  let source = b"bounded convenience API"
  let compressed = @flate.deflate_all(source)
  @test.assert_eq(@flate.inflate_exact(compressed), source)
  @test.assert_eq(
    @flate.inflate_all(compressed, max_output=source.length()),
    source,
  )
  @test.assert_eq(
    @flate.inflate_exact(compressed, max_output=source.length()),
    source,
  )
}

#ZIP container

///|
test "README zip round-trip" {
  let archive = @zip.Archive()
  archive.add("hello.txt", b"hello, zip")
  let bytes = @zip.write(archive)
  let parsed = @zip.read(bytes)
  @test.assert_eq(parsed.get("hello.txt"), Some(b"hello, zip"))
}

///|
test "README incremental ZIP writer" {
  // A real folder adapter passes a buffered file-write callback here.
  let output = @buffer.Buffer()
  let writer = @zip.Writer(chunk => output.write_bytes(chunk))
  writer.add("small.txt", b"small file")
  writer.begin_entry("chunked.txt", size=6UL)
  writer.write(b"abc")
  writer.write(b"def")
  writer.end_entry()
  writer.finish()
  let archive = @zip.read(output.to_bytes())
  @test.assert_eq(archive.get("chunked.txt"), Some(b"abcdef"))
}

#Architecture

#Optional fast stored blocks

///|
let codec = @flate.Compressor(level=6, fast_store=true)

///|
let raw = @flate.deflate_all(input, fast_store=true)

///|
let stream = @flate.Deflater(level=6, fast_store=true)

///|
let archive_bytes = @zip.write(archive, fast_store=true)

#Effort tiers

#API conventions