feat: async state interface & lazyAsyncState

Author: devnatan

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/state/AsyncState.java

@@ -0,0 +1,3 @@
+package me.devnatan.inventoryframework.state;
+
+public interface AsyncState<T> extends State<T> {}

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/state/State.java

@@ -16,6 +16,11 @@
  */
 public interface State<T> {
 
+    /**
+     * <p><b><i> This is an internal inventory-framework API that should not be used from outside of
+     * this library. No compatibility guarantees are provided. </i></b>
+     */
+    @ApiStatus.Internal
     AtomicLong ids = new AtomicLong();
 
     /**
@@ -51,8 +56,12 @@ public interface State<T> {
     /**
      * Generates a new state id.
      *
+     * <p><b><i> This is an internal inventory-framework API that should not be used from outside of
+     * this library. No compatibility guarantees are provided. </i></b>
+     *
      * @return A new unique state id.
      */
+    @ApiStatus.Internal
     static long next() {
         return ids.getAndIncrement();
     }

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/state/StateAccess.java

@@ -139,6 +139,40 @@ public interface StateAccess<
      */
     <T> State<T> lazyState(@NotNull Supplier<T> computation);
 
+    /**
+     * Creates an immutable lazy asynchronous state.
+     * <p>
+     * This method expects you to return a {@link CompletableFuture} in <code>computation</code>
+     * parameter so elements in the view that are watching that state can hook to it and wait
+     * until that future gets completed to proceed with whatever they are willing to do.
+     * <p>
+     * <b>This API is experimental and is not subject to the general compatibility guarantees such API
+     * may be changed or may be removed completely in any further release.</b>
+     *
+     * @param computation The value factory.
+     * @param <T>         The state value type.
+     * @return A new lazy asynchronous state instance.
+     */
+    @ApiStatus.Experimental
+    <T> State<T> lazyAsyncState(@NotNull Supplier<CompletableFuture<T>> computation);
+
+    /**
+     * Creates an immutable lazy asynchronous state.
+     * <p>
+     * This method expects you to return a {@link CompletableFuture} in <code>computation</code>
+     * parameter so elements in the view that are watching that state can hook to it and wait
+     * until that future gets completed to proceed with whatever they are willing to do.
+     * <p>
+     * <b>This API is experimental and is not subject to the general compatibility guarantees such API
+     * may be changed or may be removed completely in any further release.</b>
+     *
+     * @param computation The value factory.
+     * @param <T>         The state value type.
+     * @return A new lazy asynchronous state instance.
+     */
+    @ApiStatus.Experimental
+    <T> State<T> lazyAsyncState(@NotNull Function<Context, CompletableFuture<T>> computation);
+
     /**
      * Creates a mutable {@link #lazyState(Function) lazy state} whose value is always computed
      * from the initial data set by its {@link StateValueHost}.

inventory-framework-platform/src/main/java/me/devnatan/inventoryframework/PlatformView.java

@@ -664,6 +664,18 @@ public final <T> State<T> lazyState(@NotNull Supplier<T> computation) {
         return stateAccess.lazyState(computation);
     }
 
+    @Override
+    public <T> State<T> lazyAsyncState(@NotNull Supplier<CompletableFuture<T>> computation) {
+        requireNotInitialized();
+        return stateAccess.lazyAsyncState(computation);
+    }
+
+    @Override
+    public <T> State<T> lazyAsyncState(@NotNull Function<TContext, CompletableFuture<T>> computation) {
+        requireNotInitialized();
+        return stateAccess.lazyAsyncState(computation);
+    }
+
     @Override
     public final <T> MutableState<T> initialState() {
         requireNotInitialized();