Consider tightening nullable compress return types once native failures throw CompressError

[AlexV525]

Motivation

Follow-up to #252. Once native compress failures propagate to Dart as CompressError instead of a silent null return (Step 1 — see the tracking work following that issue), the currently-nullable APIs have no legitimate "returns null on success" cases left. Every remaining null path is a failure signal that would be more accurately expressed as an exception.

Proposal

Tighten these signatures from Future<T?> to Future<T>:

• FlutterImageCompress.compressWithFile — Future<Uint8List?> → Future<Uint8List>
• FlutterImageCompress.compressAndGetFile — Future<XFile?> → Future<XFile>
• FlutterImageCompress.compressAssetImage — Future<Uint8List?> → Future<Uint8List> (empty asset bundle bytes → throw CompressError(...))

compressWithList is already non-nullable and stays that way.

Null-source inventory

For reference — every existing null-return path is either dead code, a failure signal, or a latent bug:

API	Null source (pre-Step-1)	After Step 1
compressWithFile	if (!support) return null; — dead code (checkSupportPlatform throws); native reply(null)/result(nil) on failure	Both paths gone: dead code removed, native failure translates to CompressError
compressAndGetFile	Same as above	Same
compressAssetImage	Same, plus uint8List.isEmpty → return null on empty asset bundle	Empty-bundle case becomes throw CompressError('Empty asset bundle bytes for \$assetName')
compressWithList (common)	Was already non-nullable but silently propagated null → runtime TypeError	Fixed in Step 1

Why this is breaking

Any caller doing if (result == null) or result?.path breaks compilation. Migration is straightforward — replace null-checks with try/catch (CompressError) — but needs a major-version bump and a migrate.md section.

Not blocked on anything but coordination

Technically ready to land once Step 1 is in. Waiting on:

1. A convenient major-version window.
2. Deciding whether to bundle other breaking changes (e.g. web-platform compressAndGetFile shape from [Feature request] Return XFile or Path instead of Uint8List for compressions #281 discussion) into the same release.

Filing this as a tracking issue so we don't lose the reasoning.

[CaiJingLong]

Conclusion: keep this issue open.

#397 completed and shipped the prerequisite: native failures now surface as CompressError. However, #397 explicitly left the public signatures unchanged and identified #396 as the follow-up breaking change for v-next. On current main (e4bbcca), compressWithFile, compressAndGetFile, and compressAssetImage remain nullable in both the public API and platform interface. Residual null paths also remain—empty asset bytes and defensive null passthroughs in common, macOS, and OpenHarmony—while the README examples, integration tests, and migrate.md still describe nullable results.

There is no open PR implementing the type tightening. #281 has since been closed as already available/not planned, so that coordination item can be removed, but the major-version coordination remains.

Close #396 only after the non-null signatures, residual null-to-CompressError conversions, migration documentation, and tests land. Alternatively, close it as not planned only if maintainers explicitly decide not to pursue the change.

This comment was generated by AI agent omp (model: l-openai/gpt-5.6-sol).