feat: replace raw int compression level with ZstdCompressionLevel

Introduces ZstdCompressionLevel, a record wrapping the compression level as a
validated int, checked in its compact constructor against
Zstd.minCompressionLevel()/maxCompressionLevel() (IllegalArgumentException if
out of range) rather than deferring to native clamping/errors. The accepted
range is queried from libzstd once and cached, since it never changes for the
life of the process. Ships DEFAULT/FASTEST/MAX constants for the common
cases; construct directly (new ZstdCompressionLevel(n)) for any other level —
there is no separate of(int) factory, since a public record's canonical
constructor can't be hidden anyway.

Replaces every naked int level parameter with it across Zstd,
ZstdCompressContext, ZstdCompressStream, ZstdCompressDictionary,
ZstdDictionary, and ZstdOutputStream. Zstd.min/max/defaultCompressionLevel()
keep returning int, since they're the bound queries the new type validates
against.

Breaking change; the library is pre-1.0 so no compatibility shims are added.

Closes #93.

Author: dfa1

.github/smoke/src/test/java/SmokeTest.java

@@ -5,6 +5,7 @@
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressContext;
 import io.github.dfa1.zstd.ZstdCompressDictionary;
+import io.github.dfa1.zstd.ZstdCompressionLevel;
 import io.github.dfa1.zstd.ZstdCompressParameter;
 import io.github.dfa1.zstd.ZstdCompressStream;
 import io.github.dfa1.zstd.ZstdDecompressContext;
@@ -82,9 +83,11 @@ void versionAndSizing() {
         check(def >= min && def <= max, "defaultCompressionLevel() out of [min,max]");
 
         check(Zstd.compressBound(1000) >= 1000, "compressBound() below input size");
-        check(Zstd.estimateCompressContextSize(def) > 0, "estimateCompressContextSize() not positive");
+        check(Zstd.estimateCompressContextSize(ZstdCompressionLevel.DEFAULT) > 0,
+                "estimateCompressContextSize() not positive");
         check(Zstd.estimateDecompressContextSize() > 0, "estimateDecompressContextSize() not positive");
-        check(Zstd.estimateCompressDictSize(4096, def) > 0, "estimateCompressDictSize() not positive");
+        check(Zstd.estimateCompressDictSize(4096, ZstdCompressionLevel.DEFAULT) > 0,
+                "estimateCompressDictSize() not positive");
         check(Zstd.estimateDecompressDictSize(4096) > 0, "estimateDecompressDictSize() not positive");
     }
 
@@ -95,7 +98,7 @@ void coreRoundTrip() {
         byte[] compressedDefault = Zstd.compress(original);
         checkArrayEquals(original, Zstd.decompress(compressedDefault), "compress(byte[]) round-trip mismatch");
 
-        byte[] compressed = Zstd.compress(original, Zstd.maxCompressionLevel());
+        byte[] compressed = Zstd.compress(original, ZstdCompressionLevel.MAX);
         checkArrayEquals(original, Zstd.decompress(compressed), "compress(byte[], level) round-trip mismatch");
         check(compressed.length < original.length, "expected compression to shrink the input");
     }
@@ -199,7 +202,7 @@ void skippableFrames() {
     void compressContextAdvancedParameters() {
         byte[] original = sampleText();
         try (ZstdCompressContext cctx = new ZstdCompressContext()) {
-            cctx.level(5)
+            cctx.level(new ZstdCompressionLevel(5))
                     .checksum(true)
                     .longDistanceMatching(true)
                     .windowLog(20)
@@ -211,7 +214,7 @@ void compressContextAdvancedParameters() {
             check(cctx.sizeOf() > 0, "cctx.sizeOf() not positive");
 
             cctx.reset(ZstdResetDirective.SESSION_AND_PARAMETERS);
-            byte[] afterReset = cctx.level(3).compress(original);
+            byte[] afterReset = cctx.level(new ZstdCompressionLevel(3)).compress(original);
             checkArrayEquals(original, Zstd.decompress(afterReset, original.length),
                     "compress after SESSION_AND_PARAMETERS reset mismatch");
         }
@@ -361,7 +364,8 @@ void streamingIo() throws IOException {
         }
 
         ByteArrayOutputStream sinkPledged = new ByteArrayOutputStream();
-        try (ZstdOutputStream zout = ZstdOutputStream.withPledgedSize(sinkPledged, 5, original.length)) {
+        try (ZstdOutputStream zout =
+                     ZstdOutputStream.withPledgedSize(sinkPledged, new ZstdCompressionLevel(5), original.length)) {
             zout.write(original);
         }
         byte[] pledgedFrame = sinkPledged.toByteArray();

CHANGELOG.md

@@ -6,6 +6,19 @@ git tags, which trigger publication to Maven Central.
 
 ## [Unreleased]
 
+### Changed
+- **Breaking:** every public API that took a raw `int` compression level now
+  takes a `ZstdCompressionLevel` value type, which validates the level against
+  the linked libzstd's accepted range at construction (throwing
+  `IllegalArgumentException`) rather than deferring to native clamping/errors.
+  Affects `Zstd.compress(byte[], …)`, `Zstd.estimateCompressContextSize`,
+  `Zstd.estimateCompressDictSize`, `ZstdCompressContext.level`,
+  `ZstdCompressStream`, `ZstdOutputStream`, `ZstdCompressDictionary`,
+  `ZstdDictionary.compressDict`/`trainCover`/`trainFastCover`/`finalizeFrom`.
+  Use `new ZstdCompressionLevel(19)` or the `DEFAULT`/`FASTEST`/`MAX` constants.
+  The `Zstd.min/max/defaultCompressionLevel()` bound queries still return `int`.
+  ([#93](https://github.com/dfa1/zstd-java/issues/93))
+
 ## [0.10] - 2026-07-18
 
 ### Added

README.md

@@ -29,7 +29,7 @@ One-shot round-trip with `byte[]` — the convenient path:
 import io.github.dfa1.zstd.Zstd;
 
 byte[] data = ...;
-byte[] frame = Zstd.compress(data);        // or Zstd.compress(data, level)
+byte[] frame = Zstd.compress(data);        // or Zstd.compress(data, new ZstdCompressionLevel(19))
 byte[] back  = Zstd.decompress(frame);     // size read from the frame header
 ```
 

benchmark/src/main/java/io/github/dfa1/zstd/bench/CompressBenchmark.java

@@ -5,6 +5,7 @@
 import io.airlift.compress.v3.zstd.ZstdJavaCompressor;
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressContext;
+import io.github.dfa1.zstd.ZstdCompressionLevel;
 import java.lang.foreign.Arena;
 import java.lang.foreign.MemorySegment;
 import java.util.concurrent.TimeUnit;
@@ -58,7 +59,7 @@ public void setup() {
         src = BenchData.generate(size);
         int bound = (int) Zstd.compressBound(size);
 
-        ffmCtx = new ZstdCompressContext().level(level);
+        ffmCtx = new ZstdCompressContext().level(new ZstdCompressionLevel(level));
         ffmDst = new byte[bound];
 
         arena = Arena.ofConfined();

benchmark/src/main/java/io/github/dfa1/zstd/bench/GoldenCorpusBenchmark.java

@@ -4,6 +4,7 @@
 
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressContext;
+import io.github.dfa1.zstd.ZstdCompressionLevel;
 import io.github.dfa1.zstd.ZstdDecompressContext;
 import java.io.UncheckedIOException;
 import java.io.IOException;
@@ -88,7 +89,7 @@ public void setup() {
         srcSize = src.length;
         frame = Zstd.compress(src);
 
-        cctx = new ZstdCompressContext().level(level);
+        cctx = new ZstdCompressContext().level(new ZstdCompressionLevel(level));
         dctx = new ZstdDecompressContext();
         bound = (int) Zstd.compressBound(srcSize);
         compressDst = new byte[bound];

benchmark/src/main/java/io/github/dfa1/zstd/bench/MultiThreadCompressBenchmark.java

@@ -4,6 +4,7 @@
 
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressContext;
+import io.github.dfa1.zstd.ZstdCompressionLevel;
 import io.github.dfa1.zstd.ZstdCompressParameter;
 import java.lang.foreign.Arena;
 import java.lang.foreign.MemorySegment;
@@ -59,7 +60,7 @@ public void setup() {
         byte[] src = BenchData.generate(size);
         int bound = (int) Zstd.compressBound(size);
 
-        ctx = new ZstdCompressContext().level(level);
+        ctx = new ZstdCompressContext().level(new ZstdCompressionLevel(level));
         if (nbWorkers > 0) {
             ctx.parameter(ZstdCompressParameter.NB_WORKERS, nbWorkers);
         }

docs/how-to.md

@@ -8,7 +8,7 @@ Task-focused recipes. Each assumes you have the library on the classpath (see th
 Reuse a context to amortize native allocation across many calls:
 
 ```java
-try (ZstdCompressContext cctx = new ZstdCompressContext().level(19);
+try (ZstdCompressContext cctx = new ZstdCompressContext().level(new ZstdCompressionLevel(19));
      ZstdDecompressContext dctx = new ZstdDecompressContext()) {
     byte[] packed   = cctx.compress(message);
     byte[] restored = dctx.decompress(packed, message.length);
@@ -26,7 +26,7 @@ or to abort a half-written frame and start clean — without freeing and recreat
 it. Pick what to clear with `ZstdResetDirective`:
 
 ```java
-try (ZstdCompressContext cctx = new ZstdCompressContext().level(19)) {
+try (ZstdCompressContext cctx = new ZstdCompressContext().level(new ZstdCompressionLevel(19))) {
     byte[] a = cctx.compress(first);
 
     // Cheap: drop any unflushed frame state, keep the level and parameters.
@@ -51,7 +51,7 @@ matching) set on the context. To combine the two, make the dictionary *sticky*
 with `loadDictionary` — then the normal `compress` path honors both:
 
 ```java
-try (ZstdCompressContext cctx = new ZstdCompressContext().level(19).checksum(true)) {
+try (ZstdCompressContext cctx = new ZstdCompressContext().level(new ZstdCompressionLevel(19)).checksum(true)) {
     cctx.loadDictionary(dict);          // ZstdDictionary, or a native MemorySegment
     byte[] frame = cctx.compress(record); // dictionary + checksum, together
 }
@@ -62,7 +62,7 @@ by reference — no per-call digesting, no copy. It pairs with `reset` for a
 pooled, recycled context:
 
 ```java
-try (ZstdCompressDictionary cdict = dict.compressDict(19)) {
+try (ZstdCompressDictionary cdict = dict.compressDict(new ZstdCompressionLevel(19))) {
     // one cctx per pooled worker, all sharing the one digested dictionary
     try (ZstdCompressContext cctx = new ZstdCompressContext()) {
         cctx.refDictionary(cdict);          // borrowed; cdict must outlive cctx
@@ -105,7 +105,7 @@ ZstdDictionary reloaded = ZstdDictionary.of(persisted);
 On a hot path, digest the dictionary once to skip per-call setup:
 
 ```java
-try (ZstdCompressDictionary cdict = dict.compressDict(19);
+try (ZstdCompressDictionary cdict = dict.compressDict(new ZstdCompressionLevel(19));
      ZstdDecompressDictionary ddict = dict.decompressDict();
      ZstdCompressContext cctx = new ZstdCompressContext();
      ZstdDecompressContext dctx = new ZstdDecompressContext()) {
@@ -231,7 +231,7 @@ can't size the arena (see [the explanation](zero-copy.md)). Tell the encoder the
 total up front and it stamps the content size into the header:
 
 ```java
-try (var zout = ZstdOutputStream.withPledgedSize(sink, 6, data.length)) {
+try (var zout = ZstdOutputStream.withPledgedSize(sink, new ZstdCompressionLevel(6), data.length)) {
     zout.write(data);                                 // pledge must equal bytes written
 }
 MemorySegment src = MemorySegment.ofBuffer(mmap);     // downstream, in a mapped reader

docs/tutorial.md

@@ -116,7 +116,7 @@ incrementally, so memory stays flat no matter how big the payload.
 
 ```java
 // compress a file as you write it
-try (var out = new ZstdOutputStream(Files.newOutputStream(packed), 9)) {
+try (var out = new ZstdOutputStream(Files.newOutputStream(packed), new ZstdCompressionLevel(9))) {
     Files.copy(source, out);
 }
 

integration-tests/src/test/java/io/github/dfa1/zstd/it/GoldenCorpusTest.java

@@ -3,6 +3,7 @@
 import io.github.dfa1.zstd.ZstdDictionaryId;
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressContext;
+import io.github.dfa1.zstd.ZstdCompressionLevel;
 import io.github.dfa1.zstd.ZstdDecompressContext;
 import io.github.dfa1.zstd.ZstdDictionary;
 import io.github.dfa1.zstd.ZstdException;
@@ -136,7 +137,7 @@ void javaCompressJniDecompress(String name, Path file) {
             byte[] data = read(file);
 
             // When
-            byte[] frame = Zstd.compress(data, Zstd.defaultCompressionLevel());
+            byte[] frame = Zstd.compress(data, ZstdCompressionLevel.DEFAULT);
 
             // Then
             assertThat(com.github.luben.zstd.Zstd.decompress(frame, data.length)).isEqualTo(data);

integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdInteropExtrasTest.java

@@ -3,6 +3,7 @@
 import com.github.luben.zstd.ZstdCompressCtx;
 import io.github.dfa1.zstd.ZstdDictionaryId;
 import io.github.dfa1.zstd.Zstd;
+import io.github.dfa1.zstd.ZstdCompressionLevel;
 import io.github.dfa1.zstd.ZstdDictionary;
 import io.github.dfa1.zstd.ZstdException;
 import io.github.dfa1.zstd.ZstdFrame;
@@ -127,7 +128,7 @@ void jniStreamSkipsJavaSkippableFrame() {
             byte[] payload = "after the skippable frame ".repeat(1000).getBytes(StandardCharsets.UTF_8);
             byte[] meta = "sidecar-metadata".getBytes(StandardCharsets.UTF_8);
             byte[] skippable = ZstdFrame.writeSkippableFrame(meta, 0);
-            byte[] real = Zstd.compress(payload, Zstd.defaultCompressionLevel());
+            byte[] real = Zstd.compress(payload, ZstdCompressionLevel.DEFAULT);
 
             // When
             byte[] restored = jniStreamDecode(concat(skippable, real));
@@ -164,8 +165,8 @@ class MultiFrame {
         void javaFramesConcatReadByJniStream() {
             // Given
             byte[] joined = concat(
-                    Zstd.compress(a, Zstd.defaultCompressionLevel()),
-                    Zstd.compress(b, Zstd.defaultCompressionLevel()));
+                    Zstd.compress(a, ZstdCompressionLevel.DEFAULT),
+                    Zstd.compress(b, ZstdCompressionLevel.DEFAULT));
 
             // When
             byte[] restored = jniStreamDecode(joined);
@@ -266,7 +267,7 @@ void javaChunkedWriteJniRead(String name, byte[] data) throws IOException {
             ByteArrayOutputStream sink = new ByteArrayOutputStream();
 
             // When
-            try (ZstdOutputStream zout = new ZstdOutputStream(sink, 7)) {
+            try (ZstdOutputStream zout = new ZstdOutputStream(sink, new ZstdCompressionLevel(7))) {
                 writeInChunks(zout, data);
             }