@stenajs-webui/core 23.21.16 → 23.22.0

package/dist/hooks/UseDebouncedWrite.d.ts

@@ -0,0 +1,72 @@
+export interface UseDebouncedWriteOptions<T> {
+    /**
+     * How long scheduling has to pause before the latest value is written, in
+     * milliseconds.
+     */
+    delay: number;
+    /**
+     * Called when a write fails, with the value it was writing.
+     *
+     * A failed write does not stop the queue. A value scheduled while it was in
+     * flight is newer than the one that failed, so it is still written.
+     */
+    onError?: (error: unknown, value: T) => void;
+    /**
+     * Called once everything scheduled has been written, whether each write
+     * succeeded or not. Useful for re-reading what was actually stored.
+     *
+     * Not called when there turned out to be nothing to write.
+     */
+    onSettled?: () => void;
+}
+export interface UseDebouncedWriteResult<T> {
+    /**
+     * Schedules a value to be written. It replaces any value that has not
+     * started writing yet.
+     */
+    schedule: (value: T) => void;
+    /**
+     * Writes the scheduled value now, without waiting for the delay. Resolves
+     * once nothing is left to write, including anything scheduled while it
+     * waits. Never rejects; failures go to onError.
+     */
+    flush: () => Promise<void>;
+    /**
+     * Drops the scheduled value if it has not started writing yet. A write that
+     * is already in flight cannot be stopped, and finishes as normal.
+     */
+    cancel: () => void;
+}
+/**
+ * Writes the latest scheduled value once scheduling has paused, and never has
+ * more than one write in flight.
+ *
+ * Meant for input the user can repeat quickly, where each change is sent
+ * somewhere: steppers, counters, sliders, autosave. The delay turns a burst of
+ * changes into a single write. The serialisation is the part that is easy to
+ * get wrong: two writes in flight at once race each other, and a slow network
+ * can release them together or deliver them out of order.
+ *
+ * A value scheduled while a write is in flight waits for it, and is written as
+ * soon as it finishes. Only the latest waiting value is written. The ones it
+ * replaced are no longer what the user is asking for.
+ *
+ * Serialisation is per hook instance. Two components using this hook against
+ * the same resource each have their own queue, and can still overlap.
+ *
+ * On unmount, a value that has not started writing is dropped, the same as
+ * cancel. Call flush first if it must be written, for example before
+ * navigating away. A write already in flight finishes, and onSettled still
+ * runs.
+ *
+ * The callbacks are always read from the latest render, so a queued value is
+ * written with the write function as it is now, not as it was when the value
+ * was scheduled. The returned functions never change identity.
+ *
+ * @example
+ * const { schedule } = useDebouncedWrite(
+ *   (count: number) => savePassengerCount({ bookingId, count }),
+ *   { delay: 400, onSettled: refetchBooking },
+ * );
+ */
+export declare const useDebouncedWrite: <T>(write: (value: T) => Promise<unknown>, { delay, onError, onSettled }: UseDebouncedWriteOptions<T>) => UseDebouncedWriteResult<T>;

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export * from "./types/PickByValue";
 export * from "./hooks/UseArraySet";
 export * from "./hooks/UseBoolean";
 export * from "./hooks/UseDebounce";
+export * from "./hooks/UseDebouncedWrite";
 export * from "./hooks/UseDelayedFalse";
 export * from "./hooks/UseDomId";
 export * from "./hooks/UseElementDimensions";