storion 0.2.3 → 0.3.0

package/dist/async/async.d.ts

@@ -0,0 +1,87 @@
+import { Focus } from '../types';
+import { AsyncState, AsyncMode, AsyncHandler, AsyncOptions, AsyncActions, CancellablePromise, InferAsyncData, MapAsyncData, MapSettledResult, RaceResult } from './types';
+
+/**
+ * Get the pending promise for an async state (for Suspense).
+ * Returns undefined if no pending promise.
+ */
+export declare function getPendingPromise<T>(state: AsyncState<T, any>): Promise<T> | undefined;
+/**
+ * Wraps a synchronous or async function to always return a Promise.
+ * Ensures async execution even for synchronous functions.
+ */
+declare function promiseTry<T>(fn: () => T | PromiseLike<T>): Promise<Awaited<T>>;
+export declare function async<T, M extends AsyncMode, TArgs extends any[]>(focus: Focus<AsyncState<T, M>>, handler: AsyncHandler<T, TArgs>, options?: AsyncOptions): AsyncActions<T, M, TArgs>;
+export declare namespace async {
+    /**
+     * Create a fresh mode async state (data undefined during loading/error).
+     */
+    function fresh<T = unknown>(): AsyncState<T, "fresh">;
+    /**
+     * Create a stale mode async state with initial data.
+     * Data is preserved during loading and error states.
+     */
+    function stale<T>(initialData: T): AsyncState<T, "stale">;
+    function delay<T = void>(ms: number, resolved?: T): CancellablePromise<T>;
+    /**
+     * Wraps a synchronous or async function to always return a Promise.
+     * Ensures async execution even for synchronous functions.
+     *
+     * This is the same utility used internally for dispatching handlers.
+     *
+     * @example
+     * const promise = async.invoke(() => {
+     *   // Sync or async code
+     *   return someValue;
+     * });
+     */
+    const invoke: typeof promiseTry;
+    /**
+     * Extract data from AsyncState, throws if not ready.
+     * - Success: returns data
+     * - Stale mode (idle/pending/error with data): returns stale data
+     * - Pending with promise: throws promise (for Suspense)
+     * - Otherwise: throws error or AsyncNotReadyError
+     */
+    function wait<T, M extends AsyncMode>(state: AsyncState<T, M>): M extends "stale" ? T : T;
+    /**
+     * Returns the first successful result from a record of async states.
+     * Also considers stale data as "ready" in stale mode.
+     */
+    function race<T extends Record<string, AsyncState<any, any>>>(states: T): RaceResult<T>;
+    /**
+     * Returns all data if all states are ready.
+     * In stale mode, stale data counts as ready.
+     */
+    function all<T extends readonly AsyncState<any, any>[]>(...states: T): MapAsyncData<T>;
+    /**
+     * Returns the first ready data from multiple states.
+     */
+    function any<T extends readonly AsyncState<any, any>[]>(...states: T): InferAsyncData<T[number]>;
+    /**
+     * Returns settled results for all states (never throws).
+     * Includes mode-aware data in results.
+     */
+    function settled<T extends readonly AsyncState<any, any>[]>(...states: T): MapSettledResult<T>;
+    /**
+     * Check if state has data available (success or stale).
+     */
+    function hasData<T, M extends AsyncMode>(state: AsyncState<T, M>): state is AsyncState<T, M> & {
+        data: T;
+    };
+    /**
+     * Check if state is loading (pending status).
+     */
+    function isLoading<T, M extends AsyncMode>(state: AsyncState<T, M>): state is AsyncState<T, M> & {
+        status: "pending";
+    };
+    /**
+     * Check if state has an error.
+     */
+    function isError<T, M extends AsyncMode>(state: AsyncState<T, M>): state is AsyncState<T, M> & {
+        status: "error";
+        error: Error;
+    };
+}
+export {};
+//# sourceMappingURL=async.d.ts.map

package/dist/async/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/async/async.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EAET,YAAY,EACZ,YAAY,EACZ,YAAY,EAEZ,kBAAkB,EAElB,cAAc,EAEd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EAIX,MAAM,SAAS,CAAC;AAOjB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAKxB;AAID;;;GAGG;AACH,iBAAS,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAIxE;AAuDD,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAAE,KAAK,SAAS,GAAG,EAAE,EAC/D,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAC9B,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,GACrB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAkU3B;AAID,yBAAiB,KAAK,CAAC;IAGrB;;OAEG;IACH,SAAgB,KAAK,CAAC,CAAC,GAAG,OAAO,KAAK,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,CAS3D;IAED;;;OAGG;IACH,SAAgB,KAAK,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,CAS/D;IAGD,SAAgB,KAAK,CAAC,CAAC,GAAG,IAAI,EAC5B,EAAE,EAAE,MAAM,EACV,QAAQ,CAAC,EAAE,CAAC,GACX,kBAAkB,CAAC,CAAC,CAAC,CAUvB;IAED;;;;;;;;;;;OAWG;IACI,MAAM,MAAM,mBAAa,CAAC;IAEjC;;;;;;OAMG;IACH,SAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EACzC,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,CAAC,CA0B3B;IAED;;;OAGG;IACH,SAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EACjE,MAAM,EAAE,CAAC,GACR,UAAU,CAAC,CAAC,CAAC,CAoCf;IAED;;;OAGG;IACH,SAAgB,GAAG,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC3D,GAAG,MAAM,EAAE,CAAC,GACX,YAAY,CAAC,CAAC,CAAC,CA4BjB;IAED;;OAEG;IACH,SAAgB,GAAG,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC3D,GAAG,MAAM,EAAE,CAAC,GACX,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CA8B3B;IAED;;;OAGG;IACH,SAAgB,OAAO,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC/D,GAAG,MAAM,EAAE,CAAC,GACX,gBAAgB,CAAC,CAAC,CAAC,CA+BrB;IAED;;OAEG;IACH,SAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAC5C,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,KAAK,IAAI,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAIzC;IAED;;OAEG;IACH,SAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAC9C,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,KAAK,IAAI,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,SAAS,CAAA;KAAE,CAEnD;IAED;;OAEG;IACH,SAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAC5C,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,KAAK,IAAI,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAE/D;CACF"}

package/dist/async/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Async module for Storion
+ *
+ * Provides utilities for handling async operations (queries/mutations)
+ * with built-in cancellation, retry, and state management.
+ *
+ * Two modes:
+ * - fresh: data is undefined during loading/error (only show fresh data)
+ * - stale: data is preserved during loading/error (stale-while-revalidate)
+ */
+export { async, getPendingPromise } from './async';
+export { AsyncNotReadyError, AsyncAggregateError, type AsyncMode, type AsyncState, type AsyncIdleState, type AsyncIdleStateFresh, type AsyncIdleStateStale, type AsyncPendingState, type AsyncPendingStateFresh, type AsyncPendingStateStale, type AsyncSuccessState, type AsyncErrorState, type AsyncErrorStateFresh, type AsyncErrorStateStale, type AsyncStatus, type AsyncContext, type AsyncHandler, type AsyncOptions, type AsyncRetryOptions, type AsyncActions, type AsyncLastInvocation, type CancellablePromise, type InferAsyncData, type InferAsyncMode, type SettledResult, type MapAsyncData, type MapSettledResult, type RaceResult, type AsyncKey, type SerializedAsyncState, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,oBAAoB,GAC1B,MAAM,SAAS,CAAC"}

package/dist/async/index.js

@@ -0,0 +1,451 @@
+class AsyncNotReadyError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "AsyncNotReadyError";
+  }
+}
+class AsyncAggregateError extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+    this.name = "AsyncAggregateError";
+  }
+}
+const pendingPromises = /* @__PURE__ */ new WeakMap();
+function getPendingPromise(state) {
+  if (state.status === "pending" && "__key" in state && state.__key) {
+    return pendingPromises.get(state.__key);
+  }
+  return void 0;
+}
+function promiseTry(fn) {
+  return new Promise((resolve) => {
+    resolve(fn());
+  });
+}
+function createCancellablePromise(promise, cancel) {
+  const cancellable = promise;
+  cancellable.cancel = cancel;
+  return cancellable;
+}
+function stateToJSON() {
+  if (this.mode === "stale") {
+    return { status: "success", mode: "stale", data: this.data };
+  }
+  if (this.status === "success") {
+    return { status: "success", mode: "fresh", data: this.data };
+  }
+  return null;
+}
+function getRetryCount(retry) {
+  if (typeof retry === "number") return retry;
+  if (retry && typeof retry === "object") return retry.count;
+  return 0;
+}
+function getRetryDelay(retry, attempt, error) {
+  if (typeof retry === "number") return 1e3;
+  if (retry && typeof retry === "object") {
+    if (typeof retry.delay === "function") return retry.delay(attempt, error);
+    return retry.delay ?? 1e3;
+  }
+  return 1e3;
+}
+function async(focus, handler, options) {
+  const [getState, setState] = focus;
+  const asyncKey = {};
+  let lastCancel = null;
+  let lastArgs = null;
+  let invocationCount = 0;
+  function dispatch(...args) {
+    if (lastCancel && (options == null ? void 0 : options.autoCancel) !== false) {
+      lastCancel();
+    }
+    const abortController = new AbortController();
+    let isCancelled = false;
+    const requestId = {};
+    let rejectOnCancel = null;
+    const cancelPromise = new Promise((_, reject) => {
+      rejectOnCancel = reject;
+    });
+    const cancel2 = () => {
+      if (!isCancelled) {
+        isCancelled = true;
+        abortController.abort();
+        pendingPromises.delete(asyncKey);
+        rejectOnCancel == null ? void 0 : rejectOnCancel(new DOMException("Aborted", "AbortError"));
+      }
+    };
+    lastCancel = cancel2;
+    lastArgs = args;
+    invocationCount++;
+    const prevState = getState();
+    const mode = prevState.mode;
+    const staleData = mode === "stale" ? prevState.data : prevState.status === "success" ? prevState.data : void 0;
+    const autoCancel = (options == null ? void 0 : options.autoCancel) !== false;
+    const isStateExternallyModified = () => {
+      if (!autoCancel) {
+        const currentState2 = getState();
+        return currentState2.__requestId === void 0;
+      }
+      const currentState = getState();
+      return currentState.__requestId !== requestId;
+    };
+    const retryCount = getRetryCount(options == null ? void 0 : options.retry);
+    const executeWithRetry = async () => {
+      let lastError = null;
+      for (let attempt = 0; attempt <= retryCount; attempt++) {
+        try {
+          const isCancelledOrAborted = () => isCancelled || abortController.signal.aborted;
+          const asyncContext = {
+            signal: abortController.signal,
+            safe(promiseOrCallback) {
+              if (promiseOrCallback instanceof Promise) {
+                return new Promise((resolve, reject) => {
+                  promiseOrCallback.then(
+                    (value) => {
+                      if (!isCancelledOrAborted()) {
+                        resolve(value);
+                      }
+                    },
+                    (error) => {
+                      if (!isCancelledOrAborted()) {
+                        reject(error);
+                      }
+                    }
+                  );
+                });
+              }
+              return (...args2) => {
+                if (!isCancelledOrAborted()) {
+                  return promiseOrCallback(
+                    ...args2
+                  );
+                }
+                return void 0;
+              };
+            },
+            cancel: cancel2
+          };
+          const result = await promiseTry(() => handler(asyncContext, ...args));
+          if (isCancelled) {
+            throw new DOMException("Aborted", "AbortError");
+          }
+          if (isStateExternallyModified()) {
+            return result;
+          }
+          setState({
+            status: "success",
+            mode,
+            data: result,
+            error: void 0,
+            timestamp: Date.now(),
+            __requestId: requestId,
+            toJSON: stateToJSON
+          });
+          if (lastCancel === cancel2) {
+            lastCancel = null;
+          }
+          return result;
+        } catch (error) {
+          if (isCancelled || abortController.signal.aborted) {
+            throw error instanceof Error ? error : new DOMException("Aborted", "AbortError");
+          }
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (attempt < retryCount) {
+            const delay = getRetryDelay(options == null ? void 0 : options.retry, attempt + 1, lastError);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+      }
+      if (!abortController.signal.aborted) {
+        abortController.abort();
+      }
+      if (isStateExternallyModified()) {
+        throw lastError;
+      }
+      setState({
+        status: "error",
+        mode,
+        data: mode === "stale" ? staleData : void 0,
+        error: lastError,
+        timestamp: void 0,
+        __requestId: requestId,
+        toJSON: stateToJSON
+      });
+      if (lastCancel === cancel2) {
+        lastCancel = null;
+      }
+      if ((options == null ? void 0 : options.onError) && lastError) {
+        options.onError(lastError);
+      }
+      throw lastError;
+    };
+    const executionPromise = executeWithRetry();
+    const promise = Promise.race([executionPromise, cancelPromise]);
+    pendingPromises.set(asyncKey, executionPromise);
+    setState({
+      status: "pending",
+      mode,
+      data: mode === "stale" ? staleData : void 0,
+      error: void 0,
+      timestamp: void 0,
+      __key: asyncKey,
+      __requestId: requestId,
+      toJSON: stateToJSON
+    });
+    promise.then(
+      () => pendingPromises.delete(asyncKey),
+      () => pendingPromises.delete(asyncKey)
+    );
+    return createCancellablePromise(promise, cancel2);
+  }
+  function refresh() {
+    if (lastArgs === null) {
+      return void 0;
+    }
+    return dispatch(...lastArgs);
+  }
+  function cancel() {
+    if (lastCancel) {
+      lastCancel();
+      lastCancel = null;
+    }
+  }
+  function reset() {
+    cancel();
+    lastArgs = null;
+    const currentState = getState();
+    const mode = currentState.mode;
+    const resetRequestId = {};
+    if (mode === "stale") {
+      setState({
+        status: "idle",
+        mode: "stale",
+        data: currentState.data,
+        error: void 0,
+        timestamp: void 0,
+        __requestId: resetRequestId,
+        toJSON: stateToJSON
+      });
+    } else {
+      setState({
+        status: "idle",
+        mode: "fresh",
+        data: void 0,
+        error: void 0,
+        timestamp: void 0,
+        __requestId: resetRequestId,
+        toJSON: stateToJSON
+      });
+    }
+  }
+  function last() {
+    const hasDispatched = !!lastArgs;
+    if (!hasDispatched) {
+      return void 0;
+    }
+    return {
+      args: lastArgs,
+      nth: invocationCount,
+      // Read state to trigger reactivity (via focus getter) - this is the only tracked read
+      state: getState()
+    };
+  }
+  return {
+    dispatch,
+    refresh,
+    cancel,
+    reset,
+    last
+  };
+}
+((async2) => {
+  function fresh() {
+    return {
+      status: "idle",
+      mode: "fresh",
+      data: void 0,
+      error: void 0,
+      timestamp: void 0,
+      toJSON: stateToJSON
+    };
+  }
+  async2.fresh = fresh;
+  function stale(initialData) {
+    return {
+      status: "idle",
+      mode: "stale",
+      data: initialData,
+      error: void 0,
+      timestamp: void 0,
+      toJSON: stateToJSON
+    };
+  }
+  async2.stale = stale;
+  function delay(ms, resolved) {
+    let timeout;
+    return createCancellablePromise(
+      new Promise((resolve) => {
+        timeout = setTimeout(resolve, ms, resolved);
+      }),
+      () => {
+        clearTimeout(timeout);
+      }
+    );
+  }
+  async2.delay = delay;
+  async2.invoke = promiseTry;
+  function wait(state) {
+    if (state.status === "success") {
+      return state.data;
+    }
+    if (state.mode === "stale" && state.data !== void 0) {
+      return state.data;
+    }
+    if (state.status === "error") {
+      throw state.error;
+    }
+    if (state.status === "pending") {
+      const promise = getPendingPromise(state);
+      if (promise) {
+        throw promise;
+      }
+    }
+    throw new AsyncNotReadyError(
+      `Cannot wait: state is ${state.status}`,
+      state.status
+    );
+  }
+  async2.wait = wait;
+  function race(states) {
+    for (const key in states) {
+      if (Object.prototype.hasOwnProperty.call(states, key)) {
+        const state = states[key];
+        if (state.status === "success") {
+          return [key, state.data];
+        }
+      }
+    }
+    for (const key in states) {
+      if (Object.prototype.hasOwnProperty.call(states, key)) {
+        const state = states[key];
+        if (state.mode === "stale" && state.data !== void 0) {
+          return [key, state.data];
+        }
+      }
+    }
+    for (const key in states) {
+      if (Object.prototype.hasOwnProperty.call(states, key)) {
+        const state = states[key];
+        if (state.status === "error") {
+          throw state.error;
+        }
+      }
+    }
+    throw new AsyncNotReadyError(
+      "No async state has resolved successfully",
+      "pending"
+    );
+  }
+  async2.race = race;
+  function all(...states) {
+    const results = [];
+    for (let i = 0; i < states.length; i++) {
+      const state = states[i];
+      if (state.status === "success") {
+        results.push(state.data);
+        continue;
+      }
+      if (state.mode === "stale" && state.data !== void 0) {
+        results.push(state.data);
+        continue;
+      }
+      if (state.status === "error") {
+        throw state.error;
+      }
+      throw new AsyncNotReadyError(
+        `State at index ${i} is ${state.status}`,
+        state.status
+      );
+    }
+    return results;
+  }
+  async2.all = all;
+  function any(...states) {
+    const errors = [];
+    for (const state of states) {
+      if (state.status === "success") {
+        return state.data;
+      }
+    }
+    for (const state of states) {
+      if (state.mode === "stale" && state.data !== void 0) {
+        return state.data;
+      }
+      if (state.status === "error") {
+        errors.push(state.error);
+      }
+    }
+    if (errors.length === states.length) {
+      throw new AsyncAggregateError("All async states have errors", errors);
+    }
+    throw new AsyncNotReadyError(
+      "No async state has resolved successfully",
+      "pending"
+    );
+  }
+  async2.any = any;
+  function settled(...states) {
+    const results = [];
+    for (const state of states) {
+      switch (state.status) {
+        case "success":
+          results.push({ status: "success", data: state.data });
+          break;
+        case "error":
+          results.push({
+            status: "error",
+            error: state.error,
+            data: state.mode === "stale" ? state.data : void 0
+          });
+          break;
+        case "pending":
+          results.push({
+            status: "pending",
+            data: state.mode === "stale" ? state.data : void 0
+          });
+          break;
+        case "idle":
+          results.push({
+            status: "idle",
+            data: state.mode === "stale" ? state.data : void 0
+          });
+          break;
+      }
+    }
+    return results;
+  }
+  async2.settled = settled;
+  function hasData(state) {
+    if (state.status === "success") return true;
+    if (state.mode === "stale" && state.data !== void 0) return true;
+    return false;
+  }
+  async2.hasData = hasData;
+  function isLoading(state) {
+    return state.status === "pending";
+  }
+  async2.isLoading = isLoading;
+  function isError(state) {
+    return state.status === "error";
+  }
+  async2.isError = isError;
+})(async || (async = {}));
+export {
+  AsyncAggregateError,
+  AsyncNotReadyError,
+  async,
+  getPendingPromise
+};