A list of features for the transfer API, to keep tracks of things that should be added in the future. I will amend it when I find new things.

Planned:

• Item-containing items API: #1749.

Implemented in #2375: (Not merged yet)

• Make InsertionOnlyStorage have no storage views by default.
• Add some equivalent of FluidUtil.interactTank. Ideally that should play a sound and not consume the used item in creative.
• Make FluidStorage. GENERAL_COMBINED_PROVIDER final.
• Remove "A view is always tied to a specific transaction, and should not be accessed outside of it." from StorageView since it is now outdated.
• Add copyOrCreateNbt method to TransferVariant.
• Option to color water and lava, but only if requested by at least one mod.

Implemented in #2095:

• Fluid "attributes": viscosity, temperature, light level, filling sound, emptying sound, etc... What should depend on Fluid, what should depend on FluidState or what should depend on FluidVariant is TBD.

Implemented in #2086:

• Transaction.getCurrentState() which will return whether a transaction is open, closing, final closing or not existing. This is nicer than catching the ISE in getCurrentUnsafe().
• Update the javadoc of Storage#iterator to say that the returned iterator is invalid after the transaction is closed, instead of forcing the iterator to immediately return false in hasNext. Also mention that callers are not allowed to call remove on the iterator.
• Change iterator() and iterable() to use ? extends StorageView<T> instead of StorageView<T> to make it nicer for implementing classes that just want to return a list iterator.
• Definalize SingleStackStorage#insert & related methods since implementors may wish to override them.

Implemented in #1801:

• Remove the notBlank check for ContainerItemContext.withInitial as it forced users to add a check themselves.
• Clarify that isResourceBlank() is equivalent to getResource().isBlank() for transfer variants.
• Add a few FilteringStorage static methods to wrap an existing storage, while blocking insertion or extraction entirely.
• Deprecate for removal the fluid variant rendering methods that return a single sprite, and replace them with methods that return a Sprite[]. This will provide a standard way to retrieve a flowing fluid sprite for pipes, e.g. for use in pipes.
• Add insertStacking to StorageUtil.
• Add a fallback to the sided storages that throws an exception if the world is not a server world to guard against incorrect API usage (client worlds are not allowed).

Implemented in #1762:

• The Inventory adapter should try to mutate the NBT of the stack instead of setting it to air when it detects a modification. Will be necessary to add tests, to ensure we don't introduce regressions when we touch this workaround in the future.
• Add StorageUtil#findExtractableResource with a predicate argument to allow filtering the returned resource.

Not going to implement in the foreseeable future:

• Consider adding a class similar to SingleVariant storage, but with explicit set and get methods. This would allow users of the API to store the resource and amount however they want. This is dangerous if people use multiple "facades" for a single backing storage. Given the high misuse potential, it's better to avoid it.

I think the API is stable enough now for each improvement to be tracked in its own issue. :tiny_potato: