@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/src/client.ts

@@ -0,0 +1,323 @@
+import { NuiClient as CoreNuiClient } from '@fivem-nui/core';
+import type {
+  NuiClientOptions,
+  NuiEventKey,
+  NuiEventPayload,
+  NuiEventRequest,
+  NuiEventResponse,
+  NuiWindowAction,
+  SendPayload
+} from '@fivem-nui/core';
+import { installGlobalErrorHandlers, type GlobalErrorListenerOptions } from '@fivem-nui/error';
+
+type UntypedNuiClient = Omit<
+  InstanceType<typeof CoreNuiClient>,
+  'on' | 'once' | 'off' | 'send' | 'sendAndWait' | 'request' | 'callback' | 'onWindow'
+> & {
+  on(eventName: string, handler: (data: unknown) => void): () => void;
+  once(eventName: string, handler: (data: unknown) => void): () => void;
+  off(eventName: string, handler?: (data: unknown) => void): void;
+  send(eventName: string, payload?: unknown): void;
+  sendAndWait(eventName: string, payload?: unknown): Promise<void>;
+  request<TResponse = unknown>(
+    eventName: string,
+    request?: unknown,
+    timeout?: number,
+    signal?: AbortSignal
+  ): Promise<TResponse>;
+  callback(
+    eventName: string,
+    handler: (
+      request: unknown
+    ) => Promise<{ success: boolean; value?: unknown; error?: { code: string; message: string } }>
+  ): void;
+  onWindow(handler: (action: string, window: string | undefined) => void): () => void;
+};
+
+/**
+ * Configuration options for creating a {@link SvelteNuiClient}.
+ */
+export interface SvelteNuiClientOptions extends Partial<NuiClientOptions> {
+  /**
+   * Optional pre-configured `@fivem-nui/core` client instance to wrap.
+   */
+  client?: InstanceType<typeof CoreNuiClient>;
+
+  /**
+   * Whether to automatically start listening for window `message` events upon instantiation.
+   * @defaultValue true
+   */
+  autoInitialize?: boolean;
+
+  /**
+   * Whether to install global window error & unhandled rejection listeners.
+   * If `true`, uses default configuration. You can also pass custom {@link GlobalErrorListenerOptions}.
+   * @defaultValue false
+   */
+  captureGlobalErrors?: boolean | GlobalErrorListenerOptions;
+}
+
+/**
+ * Svelte NUI Client adapter.
+ *
+ * Wraps `@fivem-nui/core`'s transport layer with type-safe overloads for contract maps,
+ * event listeners, RPC requests, and lifecycle tracking.
+ */
+export class SvelteNuiClient {
+  private readonly _typedClient: InstanceType<typeof CoreNuiClient>;
+  private readonly _client: UntypedNuiClient;
+  private readonly _listeners = new Set<() => void>();
+  private _listening = false;
+
+  /**
+   * Creates a new SvelteNuiClient instance.
+   *
+   * @param options - Configuration options for the client adapter and underlying transport.
+   */
+  constructor(options: SvelteNuiClientOptions = {}) {
+    this._typedClient = options.client ?? new CoreNuiClient(options);
+    this._client = this._typedClient as unknown as UntypedNuiClient;
+
+    if (options.autoInitialize !== false) {
+      this.listen();
+    }
+
+    if (options.captureGlobalErrors) {
+      const errorOpts = typeof options.captureGlobalErrors === 'object' ? options.captureGlobalErrors : {};
+      const unsubErrors = installGlobalErrorHandlers(errorOpts);
+      this._listeners.add(unsubErrors);
+    }
+  }
+
+  private _ensureListening(): void {
+    if (!this._listening) {
+      const unsub = this._client.listen();
+      this._listeners.add(unsub);
+      this._listening = true;
+    }
+  }
+
+  // --- Subscriptions ---
+
+  /**
+   * Subscribes to an event emitted from C# / game backend.
+   *
+   * @param eventName - Name of the event emitted by C# / game backend.
+   * @param handler - Callback function invoked when the event payload arrives.
+   * @returns Unsubscribe function to remove the event listener.
+   */
+  on<K extends NuiEventKey>(eventName: K, handler: (data: NuiEventPayload<K>) => void): () => void;
+  on<T = unknown>(eventName: string, handler: (data: T) => void): () => void;
+  on(eventName: string, handler: (data: any) => void): () => void {
+    this._ensureListening();
+    const unsub = this._client.on(eventName, handler);
+    this._listeners.add(unsub);
+    return () => {
+      this._listeners.delete(unsub);
+      unsub();
+    };
+  }
+
+  /**
+   * Subscribes to an event once and automatically unsubscribes upon first receipt.
+   *
+   * @param eventName - Name of the event to listen for once.
+   * @param handler - Callback function invoked upon first receipt of the event.
+   * @returns Unsubscribe function to remove the one-time listener prior to firing.
+   */
+  once<K extends NuiEventKey>(eventName: K, handler: (data: NuiEventPayload<K>) => void): () => void;
+  once<T = unknown>(eventName: string, handler: (data: T) => void): () => void;
+  once(eventName: string, handler: (data: any) => void): () => void {
+    this._ensureListening();
+    let unsub: () => void;
+    const wrappedHandler = (data: any) => {
+      this._listeners.delete(unsub);
+      handler(data);
+    };
+    unsub = this._client.once(eventName, wrappedHandler);
+    this._listeners.add(unsub);
+    return () => {
+      this._listeners.delete(unsub);
+      unsub();
+    };
+  }
+
+  /**
+   * Removes an event listener.
+   *
+   * @param eventName - Name of the event to stop listening for.
+   * @param handler - Specific handler callback to remove. If omitted, removes all handlers for this event.
+   */
+  off(eventName: string, handler?: (data: unknown) => void): void {
+    this._client.off(eventName, handler);
+  }
+
+  // --- Sending ---
+
+  /**
+   * Sends a fire-and-forget message to C# via the NUI transport layer.
+   *
+   * @param eventName - Target event name on the game backend.
+   * @param payload - Optional data payload to transmit.
+   */
+  send<K extends NuiEventKey>(eventName: K, payload?: SendPayload<K>): void;
+  send(eventName: string, payload?: unknown): void;
+  send(eventName: string, payload?: unknown): void {
+    this._ensureListening();
+    this._client.send(eventName, payload);
+  }
+
+  /**
+   * Sends a message to C# and awaits delivery to the transport layer.
+   *
+   * @param eventName - Target event name on the game backend.
+   * @param payload - Optional data payload to transmit.
+   * @returns Promise that resolves once the transport layer confirms transmission.
+   */
+  async sendAndWait<K extends NuiEventKey>(eventName: K, payload?: SendPayload<K>): Promise<void>;
+  async sendAndWait(eventName: string, payload?: unknown): Promise<void>;
+  async sendAndWait(eventName: string, payload?: unknown): Promise<void> {
+    this._ensureListening();
+    await this._client.sendAndWait(eventName, payload);
+  }
+
+  // --- Requests (UI -> C#) ---
+
+  /**
+   * Sends an RPC request to C# and waits for the correlated response envelope.
+   *
+   * @param eventName - RPC event name on the game backend.
+   * @param request - Request payload data.
+   * @param timeout - Request timeout in milliseconds.
+   * @param signal - AbortSignal to cancel the pending request.
+   * @returns Promise resolving to the correlated response payload from C#.
+   */
+  request<K extends NuiEventKey>(
+    eventName: K,
+    request?: NuiEventRequest<K>,
+    timeout?: number,
+    signal?: AbortSignal
+  ): Promise<NuiEventResponse<K>>;
+  request<TRequest = unknown, TResponse = unknown>(
+    eventName: string,
+    request?: TRequest,
+    timeout?: number,
+    signal?: AbortSignal
+  ): Promise<TResponse>;
+  async request(
+    eventName: string,
+    request?: unknown,
+    timeout?: number,
+    signal?: AbortSignal
+  ): Promise<unknown> {
+    this._ensureListening();
+    return this._client.request(eventName, request, timeout, signal);
+  }
+
+  // --- Lifecycle Callbacks ---
+
+  /**
+   * Sends a notification to a specific native callback endpoint (e.g. `'ready'`, `'close'`).
+   *
+   * @param callbackName - Name of the native callback endpoint.
+   * @param payload - Optional data to send with the notification.
+   */
+  notify(callbackName: string, payload?: unknown): void {
+    this._client.notify(callbackName, payload);
+  }
+
+  /**
+   * Sends a notification and awaits HTTP transmission confirmation.
+   *
+   * @param callbackName - Name of the native callback endpoint.
+   * @param payload - Optional data to send with the notification.
+   * @returns Promise that resolves once the HTTP notification is acknowledged.
+   */
+  async notifyAndWait(callbackName: string, payload?: unknown): Promise<void> {
+    await this._client.notifyAndWait(callbackName, payload);
+  }
+
+  /**
+   * Registers a handler for requests initiated from C# to the UI.
+   *
+   * @param eventName - Name of the incoming RPC endpoint from C#.
+   * @param handler - Handler function returning a promise with response envelope.
+   */
+  callback(
+    eventName: string,
+    handler: (request: unknown) => Promise<{ success: boolean; value?: unknown; error?: { code: string; message: string } }>
+  ): void {
+    this._ensureListening();
+    this._client.callback(eventName, handler);
+  }
+
+  /**
+   * Unregisters an incoming RPC callback handler previously registered with {@link callback}.
+   *
+   * @param eventName - Name of the RPC endpoint to unregister.
+   * @returns True if a handler was registered and removed, false otherwise.
+   */
+  unregisterCallback(eventName: string): boolean {
+    return this._client.unregisterCallback(eventName);
+  }
+
+  // --- Window Lifecycle ---
+
+  /**
+   * Listens for window lifecycle actions from C# (`'open'`, `'close'`, `'focus'`, `'blur'`).
+   *
+   * @param handler - Callback invoked with the lifecycle action and target window identifier.
+   * @returns Unsubscribe function to remove the window action listener.
+   */
+  onWindow(handler: (action: NuiWindowAction, window: string | undefined) => void): () => void {
+    this._ensureListening();
+    const unsub = this._client.onWindow((action, win) => handler(action as NuiWindowAction, win));
+    this._listeners.add(unsub);
+    return () => {
+      this._listeners.delete(unsub);
+      unsub();
+    };
+  }
+
+  /**
+   * Starts listening for NUI message events dispatched to the window.
+   *
+   * @returns Unsubscribe function to stop listening to window messages.
+   */
+  listen(): () => void {
+    const unsub = this._client.listen();
+    this._listeners.add(unsub);
+    this._listening = true;
+    return unsub;
+  }
+
+  /**
+   * Returns an untyped view of the underlying transport client.
+   *
+   * @returns Untyped transport client reference.
+   */
+  getClient(): UntypedNuiClient {
+    return this._client;
+  }
+
+  /**
+   * Returns the underlying strongly typed `@fivem-nui/core` client instance.
+   *
+   * @returns The underlying `NuiClient` instance.
+   */
+  getTypedClient(): InstanceType<typeof CoreNuiClient> {
+    return this._typedClient;
+  }
+
+  /**
+   * Cleans up all active listeners, stops listening, and disposes the underlying transport client.
+   */
+  destroy(): void {
+    for (const unsub of this._listeners) {
+      unsub();
+    }
+    this._listeners.clear();
+    this._listening = false;
+    this._typedClient.dispose();
+  }
+}

package/src/context/index.ts

@@ -0,0 +1,127 @@
+import { getContext, setContext, hasContext } from 'svelte';
+import type { SvelteNuiClient } from '../client';
+
+/**
+ * Global Symbol key used for Svelte Context API registration.
+ * Scoped with package prefix to prevent realm collisions with other libraries.
+ */
+export const NUI_CONTEXT_KEY = Symbol.for('@fivem-nui/svelte:client');
+
+/**
+ * Global Symbol key used to store the default client singleton on `globalThis`.
+ * Ensures duplicate package copies (e.g. nested node_modules or micro-frontends)
+ * share the same default client instance.
+ */
+const GLOBAL_DEFAULT_KEY = Symbol.for('@fivem-nui/svelte:default-client');
+
+function getDefaultClient(): SvelteNuiClient | null {
+  const g = globalThis as unknown as { [GLOBAL_DEFAULT_KEY]?: SvelteNuiClient | null };
+  return g[GLOBAL_DEFAULT_KEY] ?? null;
+}
+
+function setDefaultClient(client: SvelteNuiClient | null): void {
+  const g = globalThis as unknown as { [GLOBAL_DEFAULT_KEY]?: SvelteNuiClient | null };
+  g[GLOBAL_DEFAULT_KEY] = client;
+}
+
+/**
+ * Registers the global default `SvelteNuiClient` instance used when no scoped context is found.
+ *
+ * @remarks
+ * **SSR & CEF Environment**:
+ * The default client is a singleton stored on `globalThis` intended for client-side FiveM CEF
+ * and SPA environments. In server-side rendering (SSR) environments, avoid relying on global
+ * singletons and prefer component-scoped context via `setNuiClient()`.
+ *
+ * @param client - The client instance to register as the default.
+ * @returns The registered client instance for convenient chaining.
+ */
+export function setDefaultNuiClient(client: SvelteNuiClient): SvelteNuiClient {
+  const current = getDefaultClient();
+  const isHmr = typeof import.meta !== 'undefined' && Boolean((import.meta as any)?.hot);
+
+  if (!isHmr && current !== null && current !== client) {
+    console.warn(
+      '[fivem-nui-svelte] setDefaultNuiClient called with a new client instance while a default client was already registered. Overwriting default client.'
+    );
+  }
+  setDefaultClient(client);
+  return client;
+}
+
+/**
+ * Directly retrieves the global default `SvelteNuiClient` instance without checking Svelte context.
+ * Useful in standalone stores, utility files, or outside component initialization.
+ *
+ * @returns The registered global default client, or `null` if none has been registered.
+ */
+export function getDefaultNuiClient(): SvelteNuiClient | null {
+  return getDefaultClient();
+}
+
+/**
+ * Resets the default global client instance to null.
+ * Intended for test isolation and teardown.
+ */
+export function resetDefaultNuiClient(): void {
+  setDefaultClient(null);
+}
+
+/**
+ * Provides a `SvelteNuiClient` instance to the component hierarchy via Svelte's Context API.
+ *
+ * @param client - The client instance to provide to child components.
+ * @returns The provided client instance for convenient inline assignment.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { setNuiClient, SvelteNuiClient } from '@fivem-nui/svelte';
+ *   const client = setNuiClient(new SvelteNuiClient());
+ * </script>
+ * ```
+ */
+export function setNuiClient(client: SvelteNuiClient): SvelteNuiClient {
+  setContext(NUI_CONTEXT_KEY, client);
+  return client;
+}
+
+/**
+ * Retrieves the currently active `SvelteNuiClient`.
+ *
+ * Resolution priority order:
+ * 1. **Component Context**: Scoped client provided via `setNuiClient()` in an ancestor component
+ *    (checked safely; outside component lifecycle, this step is skipped).
+ * 2. **Explicit Override**: `fallbackClient` argument passed directly to `useNuiClient(fallbackClient)`.
+ * 3. **Global Default**: Singleton client registered via `setDefaultNuiClient()` or the default `nui` instance
+ *    registered upon importing the root package entrypoint (`src/index.ts`).
+ *
+ * @remarks
+ * **Lifecycle Safety**:
+ * Svelte's `hasContext()` / `getContext()` throw a `lifecycle_outside_component` runtime error
+ * when invoked outside component initialization (e.g. in async handlers, stores, or outside component trees).
+ * This function safely catches that error to allow graceful fallback to the explicit or global client.
+ *
+ * @param fallbackClient - Optional client to use if no scoped context is found.
+ * @returns The resolved `SvelteNuiClient`.
+ * @throws Error if no client is found in context, fallback, or default singleton.
+ */
+export function useNuiClient(fallbackClient?: SvelteNuiClient): SvelteNuiClient {
+  try {
+    if (hasContext(NUI_CONTEXT_KEY)) {
+      return getContext<SvelteNuiClient>(NUI_CONTEXT_KEY);
+    }
+  } catch {
+    // Outside component initialization lifecycle (e.g. async handler, store, or external helper).
+    // Safely proceed to explicit fallback or global default client.
+  }
+
+  const client = fallbackClient ?? getDefaultClient();
+  if (!client) {
+    throw new Error(
+      '[fivem-nui-svelte] No NuiClient available. Call setNuiClient(client) in a parent component, provide an explicit client argument to useNuiClient(fallback), or register a default client via setDefaultNuiClient(client) at startup.'
+    );
+  }
+
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// Main entrypoint for @fivem-nui/svelte
+// High-performance Svelte SDK for FiveM NUI
+
+import { SvelteNuiClient, type SvelteNuiClientOptions } from './client';
+import { setDefaultNuiClient } from './context';
+
+// ===== GLOBAL CLIENT SINGLETON & FACTORY =====
+
+/**
+ * Default global `SvelteNuiClient` singleton instance.
+ * Automatically registered with {@link setDefaultNuiClient}.
+ */
+export const nui = new SvelteNuiClient();
+setDefaultNuiClient(nui);
+
+/**
+ * Creates a new custom `SvelteNuiClient` instance.
+ *
+ * @param options - Configuration options for the client.
+ * @returns A new `SvelteNuiClient` instance.
+ */
+export function createNui(options?: SvelteNuiClientOptions): SvelteNuiClient {
+  return new SvelteNuiClient(options);
+}
+
+// ===== CLIENT CLASS & TYPES =====
+
+export { SvelteNuiClient, type SvelteNuiClientOptions };
+
+// ===== DOMAINS RE-EXPORTS =====
+
+export * from './context';
+export * from './runes/index.svelte';
+export * from './actions';
+export * from './utils';
+export * from './mock';
+export * from '@fivem-nui/error';
+
+// ===== CORE CONTRACTS RE-EXPORTS =====
+
+export type {
+  NuiEventMap,
+  NuiEventKey,
+  NuiEventRequest,
+  NuiEventResponse,
+  NuiEventPayload,
+  SendPayload,
+  RequestPayload,
+  RequestResponse,
+  NuiWindowAction,
+  NuiMessage,
+  NuiError
+} from '@fivem-nui/core';

package/src/mock/index.ts

@@ -0,0 +1,176 @@
+import type { NuiWindowAction } from '@fivem-nui/core';
+import { isNui, getResourceName } from '../utils/env';
+import {
+  type NuiMockOptions,
+  type NuiMockController,
+  NuiMessageType,
+  NOOP_CONTROLLER
+} from './types';
+import { createFetchInterceptor } from './interceptor';
+
+export { NuiMessageType };
+export type { NuiMockOptions, NuiMockController };
+export { isNuiUrl, parseNuiUrl } from './url';
+export { createFetchInterceptor, extractRequestBody } from './interceptor';
+
+/**
+ * Sets up a browser mock environment for FiveM NUI.
+ *
+ * Intercepts POST requests sent to `https://<resource>/<callback>` and
+ * responds with mock data when running outside FiveM CEF.
+ *
+ * @param options - Configuration options for the mock environment.
+ * @returns Controller for emitting simulated events and registering dynamic mocks.
+ *
+ * @example
+ * ```ts
+ * import { setupNuiMock } from '@fivem-nui/svelte';
+ *
+ * const mock = setupNuiMock({
+ *   requests: {
+ *     getPlayerData: () => ({ id: 1, name: 'John Doe' })
+ *   }
+ * });
+ * ```
+ */
+export function setupNuiMock(options: NuiMockOptions = {}): NuiMockController {
+  const {
+    requests = {},
+    callbacks = {},
+    onSend: sendHandlers = {},
+    latencyMs = 50,
+    log = true,
+    resourceName: customResource
+  } = options;
+
+  // 1. SSR check first to avoid referencing window when unavailable
+  if (typeof window === 'undefined') {
+    return NOOP_CONTROLLER;
+  }
+
+  // 2. In CEF FiveM, the mock interceptor must remain disabled
+  if (isNui()) {
+    if (log) {
+      console.info('[fivem-nui-svelte] Running inside FiveM CEF - mock interceptor disabled.');
+    }
+    return NOOP_CONTROLLER;
+  }
+
+  // 3. Clean up any previously active mock instance (e.g. on Vite HMR reload)
+  if ((window as any).__nuiMock && typeof (window as any).__nuiMock.destroy === 'function') {
+    (window as any).__nuiMock.destroy();
+  }
+
+  const targetResource = customResource || getResourceName('') || 'nui';
+  const activeRequests: Record<string, (payload: any) => Promise<any> | any> = { ...requests };
+  const activeCallbacks: Record<string, (payload: any) => void> = { ...callbacks };
+  const activeSendHandlers: Record<string, (payload: any) => void> = { ...sendHandlers };
+
+  const originalFetch = window.fetch;
+
+  function emitEvent(eventName: string, payload?: unknown, delayMs?: number): void {
+    const dispatch = () => {
+      if (log) {
+        console.debug(`[NUI Mock] <- EVENT '${eventName}'`, payload);
+      }
+      window.postMessage(
+        {
+          type: NuiMessageType.Event,
+          event: eventName,
+          payload,
+          // 'data' preserved alongside 'payload' for backward compatibility with legacy scripts
+          data: payload
+        },
+        '*'
+      );
+    };
+
+    if (delayMs && delayMs > 0) {
+      setTimeout(dispatch, delayMs);
+    } else {
+      dispatch();
+    }
+  }
+
+  function emitWindow(action: NuiWindowAction, windowName?: string, delayMs?: number): void {
+    const dispatch = () => {
+      if (log) {
+        console.debug(`[NUI Mock] <- WINDOW action='${action}' window='${windowName ?? '*'}'`);
+      }
+      window.postMessage(
+        {
+          type: action,
+          event: windowName,
+          action,
+          window: windowName
+        },
+        '*'
+      );
+    };
+
+    if (delayMs && delayMs > 0) {
+      setTimeout(dispatch, delayMs);
+    } else {
+      dispatch();
+    }
+  }
+
+  const interceptedFetch = createFetchInterceptor({
+    targetResource,
+    latencyMs,
+    log,
+    activeRequests,
+    activeCallbacks,
+    activeSendHandlers,
+    originalFetch
+  });
+
+  window.fetch = interceptedFetch;
+
+  const controller: NuiMockController = {
+    emitEvent,
+    emitWindow,
+    mockRequest<TRequest = unknown, TResponse = unknown>(
+      eventName: string,
+      handler: (payload: TRequest) => Promise<TResponse> | TResponse
+    ) {
+      activeRequests[eventName] = handler;
+      return () => {
+        if (activeRequests[eventName] === handler) {
+          delete activeRequests[eventName];
+        }
+      };
+    },
+    removeRequest(eventName: string) {
+      delete activeRequests[eventName];
+    },
+    onSend<T = unknown>(eventName: string, handler: (payload: T) => void) {
+      activeSendHandlers[eventName] = handler;
+      return () => {
+        if (activeSendHandlers[eventName] === handler) {
+          delete activeSendHandlers[eventName];
+        }
+      };
+    },
+    destroy() {
+      if (typeof window !== 'undefined') {
+        if (window.fetch === interceptedFetch) {
+          window.fetch = originalFetch;
+        }
+        if ((window as any).__nuiMock === controller) {
+          delete (window as any).__nuiMock;
+        }
+      }
+    }
+  };
+
+  (window as any).__nuiMock = controller;
+
+  if (log) {
+    console.info(
+      `[fivem-nui-svelte] Mock interceptor active for resource '${targetResource}'. window.__nuiMock ready.`
+    );
+  }
+
+  return controller;
+}