@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/src/runes/query.svelte.ts

@@ -0,0 +1,313 @@
+import { untrack } from 'svelte';
+import type { NuiEventKey, NuiEventRequest, NuiEventResponse } from '@fivem-nui/core';
+import {
+  globalErrorHandler,
+  NuiErrorCategory,
+  isAbortError,
+  createAbortError,
+  type RetryOptions
+} from '@fivem-nui/error';
+import type { SvelteNuiClient } from '../client';
+import { useNuiClient } from '../context';
+
+export { type RetryOptions };
+
+export enum NuiQueryStatus {
+  Idle = 'idle',
+  Loading = 'loading',
+  Success = 'success',
+  Error = 'error'
+}
+
+export interface NuiQueryOptions<TRequest = unknown, TResponse = unknown> {
+  /** Optional client override (defaults to context or global client). */
+  client?: SvelteNuiClient;
+
+  /** Request timeout in ms (0 for no timeout). */
+  timeout?: number;
+
+  /**
+   * Automatic retry configuration using exponential backoff.
+   * - `true`: enables default retry (3 attempts for timeout and network errors).
+   * - `RetryOptions`: custom retry configuration (maxRetries, delays, filter).
+   */
+  retry?: boolean | RetryOptions;
+
+  /** Execute automatically on mount. */
+  immediate?: boolean;
+
+  /** Initial payload used for immediate fetch or fallback refetch. */
+  initialRequest?: TRequest;
+
+  /** Called on successful response. */
+  onSuccess?: (data: TResponse) => void;
+
+  /** Called on request failure (except when aborted). */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Controller for an asynchronous NUI query.
+ */
+export interface NuiQuery<TRequest, TResponse> {
+  readonly status: NuiQueryStatus;
+  readonly data: TResponse | null;
+  readonly loading: boolean;
+  readonly error: Error | null;
+  readonly called: boolean;
+  readonly lastUpdated: number | null;
+
+  /** Sends the request to C#. Cancels any pending request for this query. */
+  execute(request?: TRequest, overrideTimeout?: number): Promise<TResponse>;
+
+  /** Retries the last request using the same payload. */
+  refetch(overrideTimeout?: number): Promise<TResponse>;
+
+  /** Cancels the active request and stops loading. */
+  abort(): void;
+
+  /** Aborts any pending request and resets data, error, and status to idle. */
+  reset(): void;
+
+  /** Cleans up the query and aborts pending requests. */
+  destroy(): void;
+}
+
+/**
+ * Reusable controller managing reactive state and network requests for a NUI query.
+ */
+export class NuiQueryController<TRequest = unknown, TResponse = unknown> implements NuiQuery<TRequest, TResponse> {
+  data = $state<TResponse | null>(null);
+  loading = $state(false);
+  error = $state<Error | null>(null);
+  called = $state(false);
+  lastUpdated = $state<number | null>(null);
+
+  private isSuccess = $state(false);
+  private lastRequest?: TRequest;
+  private hasLastRequest = false;
+  private activeRequestId = 0;
+  private abortController: AbortController | null = null;
+  private isDisposed = false;
+
+  constructor(
+    private readonly eventName: string,
+    private readonly options: NuiQueryOptions<TRequest, TResponse> = {},
+    private readonly client: SvelteNuiClient
+  ) {
+    this.lastRequest = options.initialRequest;
+    this.hasLastRequest = 'initialRequest' in options;
+  }
+
+  get status(): NuiQueryStatus {
+    if (this.loading) return NuiQueryStatus.Loading;
+    if (this.error !== null) return NuiQueryStatus.Error;
+    if (this.isSuccess) return NuiQueryStatus.Success;
+    return NuiQueryStatus.Idle;
+  }
+
+  private async sendRequest(payload: TRequest | undefined, overrideTimeout?: number): Promise<TResponse> {
+    if (this.isDisposed) {
+      throw new Error('[useNuiQuery] Cannot execute request on a destroyed query controller.');
+    }
+
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+    const currentController = new AbortController();
+    this.abortController = currentController;
+    const currentRequestId = ++this.activeRequestId;
+
+    this.loading = true;
+    this.error = null;
+    this.called = true;
+
+    const requestFn = () =>
+      this.client.request<TRequest, TResponse>(
+        this.eventName,
+        payload,
+        overrideTimeout ?? this.options.timeout,
+        currentController.signal
+      );
+
+    try {
+      let result: TResponse;
+      if (this.options.retry) {
+        const retryConfig: RetryOptions =
+          typeof this.options.retry === 'object' ? { ...this.options.retry } : {};
+
+        const userShouldRetry = retryConfig.shouldRetry;
+        retryConfig.shouldRetry = (errorInfo) => {
+          if (
+            currentRequestId !== this.activeRequestId ||
+            currentController.signal.aborted ||
+            isAbortError(errorInfo.error)
+          ) {
+            return false;
+          }
+          if (userShouldRetry) {
+            return userShouldRetry(errorInfo);
+          }
+          return (
+            (retryConfig.retryOnTimeout !== false && errorInfo.category === NuiErrorCategory.TIMEOUT) ||
+            (retryConfig.retryOnNetworkError !== false && errorInfo.category === NuiErrorCategory.NETWORK)
+          );
+        };
+
+        result = await globalErrorHandler.retry(requestFn, retryConfig);
+      } else {
+        result = await requestFn();
+      }
+
+      if (currentRequestId !== this.activeRequestId || currentController.signal.aborted) {
+        throw createAbortError();
+      }
+
+      this.data = result;
+      this.isSuccess = true;
+      this.lastUpdated = Date.now();
+
+      try {
+        this.options.onSuccess?.(result);
+      } catch (callbackErr) {
+        void globalErrorHandler
+          .handle(
+            callbackErr instanceof Error ? callbackErr : new Error(String(callbackErr)),
+            { event: this.eventName },
+            'useNuiQuery:onSuccess'
+          )
+          .catch(() => {});
+        console.error(callbackErr);
+      }
+
+      return result;
+    } catch (err: unknown) {
+      if (currentRequestId !== this.activeRequestId || currentController.signal.aborted) {
+        throw isAbortError(err) ? err : createAbortError();
+      }
+
+      if (isAbortError(err)) {
+        throw err;
+      }
+
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.error = e;
+      this.isSuccess = false;
+
+      void globalErrorHandler
+        .handle(e, { event: this.eventName, payload }, 'useNuiQuery:request')
+        .catch(() => {});
+
+      try {
+        this.options.onError?.(e);
+      } catch (callbackErr) {
+        void globalErrorHandler
+          .handle(
+            callbackErr instanceof Error ? callbackErr : new Error(String(callbackErr)),
+            { event: this.eventName },
+            'useNuiQuery:onError'
+          )
+          .catch(() => {});
+        console.error(callbackErr);
+      }
+      throw e;
+    } finally {
+      if (currentRequestId === this.activeRequestId) {
+        this.loading = false;
+        this.abortController = null;
+      }
+    }
+  }
+
+  execute = async (...args: [request?: TRequest, overrideTimeout?: number]): Promise<TResponse> => {
+    const hasExplicitRequest = args.length > 0;
+    if (hasExplicitRequest) {
+      this.lastRequest = args[0];
+      this.hasLastRequest = true;
+    }
+    return this.sendRequest(this.lastRequest, args[1]);
+  };
+
+  refetch = (overrideTimeout?: number): Promise<TResponse> => {
+    return this.sendRequest(this.lastRequest, overrideTimeout);
+  };
+
+  abort = (): void => {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.activeRequestId++;
+    this.loading = false;
+  };
+
+  reset = (): void => {
+    this.abort();
+    this.data = null;
+    this.error = null;
+    this.isSuccess = false;
+    this.called = false;
+    this.lastUpdated = null;
+    this.lastRequest = this.options.initialRequest;
+    this.hasLastRequest = 'initialRequest' in this.options;
+  };
+
+  destroy = (): void => {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    this.abort();
+  };
+}
+
+/**
+ * Reactive query for communicating with C# (`nui.request`).
+ * Manages reactive `data`, `loading`, `error`, and `status`.
+ *
+ * Note: Access properties directly (e.g. `query.data`). Do not destructure, or you'll lose reactivity.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useNuiQuery } from '@fivem-nui/svelte';
+ *
+ *   const buy = useNuiQuery('shop:buy');
+ * </script>
+ *
+ * <button onclick={() => buy.execute({ id: 'bread', qty: 1 })} disabled={buy.loading}>
+ *   {buy.loading ? 'Buying...' : 'Buy'}
+ * </button>
+ *
+ * {#if buy.error}
+ *   <p class="error">{buy.error.message}</p>
+ * {/if}
+ * ```
+ */
+export function useNuiQuery<K extends NuiEventKey>(
+  eventName: K,
+  options?: NuiQueryOptions<NuiEventRequest<K>, NuiEventResponse<K>>
+): NuiQuery<NuiEventRequest<K>, NuiEventResponse<K>>;
+
+export function useNuiQuery<TRequest = unknown, TResponse = unknown>(
+  eventName: string,
+  options?: NuiQueryOptions<TRequest, TResponse>
+): NuiQuery<TRequest, TResponse>;
+
+export function useNuiQuery<TRequest = unknown, TResponse = unknown>(
+  eventName: string,
+  options: NuiQueryOptions<TRequest, TResponse> = {}
+): NuiQuery<TRequest, TResponse> {
+  const client = options.client ?? useNuiClient();
+  const query = new NuiQueryController(eventName, options, client);
+
+  $effect(() => () => query.destroy());
+
+  $effect(() => {
+    untrack(() => {
+      if (options.immediate) {
+        void query.execute(options.initialRequest).catch(() => {});
+      }
+    });
+  });
+
+  return query;
+}

package/src/runes/state.svelte.ts

@@ -0,0 +1,175 @@
+import { onDestroy } from 'svelte';
+import type { NuiEventKey, NuiEventPayload } from '@fivem-nui/core';
+import { globalErrorHandler } from '@fivem-nui/error';
+import type { SvelteNuiClient } from '../client';
+import { useNuiClient } from '../context';
+
+export interface NuiStateOptions<T> {
+  /** Optional client override (defaults to context or global client). */
+  client?: SvelteNuiClient;
+
+  /** Transform or validate raw incoming payload before updating state. */
+  transform?: (raw: unknown) => T;
+
+  /** Called when payload handling or transform fails. */
+  onError?: (error: Error) => void;
+
+  /**
+   * Automatic cleanup on component unmount.
+   * - `false`: disables lifecycle hook (useful for global stores / singletons).
+   * - `true`: strictly requires component context (throws if called outside).
+   * - `undefined`: automatically hooks into component lifecycle if available.
+   */
+  autoDestroy?: boolean;
+}
+
+/**
+ * Controller for reactive state synchronized with a NUI event.
+ */
+export interface NuiState<T> {
+  /** Current value. */
+  value: T;
+
+  /** Timestamp (epoch ms) of the last received event, or null. */
+  readonly updatedAt: number | null;
+
+  /** Number of received events. */
+  readonly count: number;
+
+  /** Last processing or transform error, or null. */
+  readonly error: Error | null;
+
+  /** Sets the value manually without incrementing count or updatedAt. */
+  set(value: T): void;
+
+  /** Updates the value using an updater function. */
+  update(fn: (prev: T) => T): void;
+
+  /** Resets state back to the initial value and clears errors. */
+  reset(): void;
+
+  /** Unsubscribes from the event. */
+  destroy(): void;
+}
+
+/**
+ * Binds a FiveM NUI event to reactive state.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useNuiState } from '@fivem-nui/svelte';
+ *
+ *   const player = useNuiState('player:update', { health: 100, armor: 0 });
+ * </script>
+ *
+ * <div>Health: {player.value.health}</div>
+ * ```
+ */
+/**
+ * Controller managing reactive state synchronized with a NUI event.
+ */
+export class NuiStateController<T> implements NuiState<T> {
+  value = $state<T>(undefined as unknown as T);
+  updatedAt = $state<number | null>(null);
+  count = $state(0);
+  error = $state<Error | null>(null);
+
+  private readonly initialValue: T;
+  private isDestroyed = false;
+  private readonly unsubscribe: () => void;
+
+  constructor(
+    eventName: string,
+    initialValue: T,
+    options: NuiStateOptions<T> = {},
+    client: SvelteNuiClient
+  ) {
+    this.initialValue = initialValue;
+    this.value = initialValue;
+
+    this.unsubscribe = client.on(eventName, (data: unknown) => {
+      try {
+        this.value = options.transform ? options.transform(data) : (data as T);
+        this.updatedAt = Date.now();
+        this.count += 1;
+        this.error = null;
+      } catch (err: unknown) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        this.error = e;
+        void globalErrorHandler
+          .handle(e, { event: eventName, payload: data }, 'useNuiState:transform')
+          .catch(() => {});
+        try {
+          options.onError?.(e);
+        } catch (callbackErr) {
+          void globalErrorHandler
+            .handle(
+              callbackErr instanceof Error ? callbackErr : new Error(String(callbackErr)),
+              { event: eventName },
+              'useNuiState:onError'
+            )
+            .catch(() => {});
+          console.error(callbackErr);
+        }
+      }
+    });
+  }
+
+  set = (v: T): void => {
+    this.value = v;
+  };
+
+  update = (fn: (prev: T) => T): void => {
+    this.value = fn(this.value);
+  };
+
+  reset = (): void => {
+    this.value = this.initialValue;
+    this.updatedAt = null;
+    this.count = 0;
+    this.error = null;
+  };
+
+  destroy = (): void => {
+    if (this.isDestroyed) return;
+    this.isDestroyed = true;
+    this.unsubscribe();
+  };
+}
+
+export function useNuiState<K extends NuiEventKey>(
+  eventName: K,
+  initialValue: NuiEventPayload<K>,
+  options?: NuiStateOptions<NuiEventPayload<K>>
+): NuiState<NuiEventPayload<K>>;
+export function useNuiState<T>(
+  eventName: string,
+  initialValue: T,
+  options?: NuiStateOptions<T>
+): NuiState<T>;
+export function useNuiState<T>(
+  eventName: string,
+  initialValue: T,
+  options: NuiStateOptions<T> = {}
+): NuiState<T> {
+  const client = options.client ?? useNuiClient();
+  const state = new NuiStateController(eventName, initialValue, options, client);
+
+  if (options.autoDestroy === true) {
+    try {
+      onDestroy(state.destroy);
+    } catch (err) {
+      state.destroy();
+      throw err;
+    }
+  } else if (options.autoDestroy !== false) {
+    try {
+      onDestroy(state.destroy);
+    } catch {
+      // Called outside a component lifecycle; cleanup must be managed manually via destroy().
+    }
+  }
+
+  return state;
+}