@fivem-nui/core 1.0.0 → 1.1.0

package/src/MessageTransport.ts

@@ -1,88 +1,95 @@
-import { NuiErrorCodes, NuiRequestError } from './errors';
-import type { NuiLogger } from './logger';
-import type { NuiMessage } from './types';
-
-export type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
-
-/**
- * HTTP transport for FiveM NUI.
- *
- * Posts envelopes to `https://<resource>/<callback>` using `fetch`.
- * Each POST is bounded by an `AbortController` deadline so a resource
- * that stops answering (restart, shutdown) does not hang the page forever.
- *
- * Mirrors C# `FiveMNuiTransport`.
- */
-export class MessageTransport {
-  private readonly resource: string;
-  private readonly callbackName: string;
-  private readonly postTimeoutMs: number;
-  private readonly logger: NuiLogger;
-  private readonly fetchImpl: FetchImpl;
-
-  constructor(
-    resource: string,
-    callbackName: string,
-    postTimeoutMs: number,
-    logger: NuiLogger,
-    fetchImpl: FetchImpl,
-  ) {
-    this.resource = resource;
-    this.callbackName = callbackName;
-    this.postTimeoutMs = postTimeoutMs;
-    this.logger = logger;
-    this.fetchImpl = fetchImpl;
-  }
-
-  /** URL of the main resource callback. */
-  get mainCallbackUrl(): string {
-    return `https://${this.resource}/${encodeURIComponent(this.callbackName)}`;
-  }
-
-  /** Builds the URL for an arbitrary callback on the same resource. */
-  callbackUrl(callbackName: string): string {
-    return `https://${this.resource}/${encodeURIComponent(callbackName)}`;
-  }
-
-  /**
-   * Raw POST to `url` with the configured timeout deadline.
-   *
-   * @throws {NuiRequestError} with code `POST_TIMEOUT` when the resource
-   *   stops answering within `postTimeoutMs`.
-   * @throws {NuiRequestError} with code `TRANSPORT` for any other failure.
-   */
-  async post(url: string, body: unknown): Promise<void> {
-    // Without an abort, a resource that stops answering leaves this promise
-    // pending forever and the caller's await never returns.
-    const controller = new AbortController();
-    const deadline = setTimeout(() => controller.abort(), this.postTimeoutMs);
-
-    try {
-      await this.fetchImpl(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json; charset=UTF-8' },
-        body: JSON.stringify(body),
-        signal: controller.signal,
-      });
-    } catch (error) {
-      // A timeout abort surfaces as an error whose `name` is 'AbortError'.
-      // In browsers that is a DOMException, but some fetch polyfills throw a
-      // plain Error, so match on the name instead of the constructor. Checking
-      // only `controller.signal.aborted` is unsafe: a race between the deadline
-      // firing and an unrelated network error would misclassify the network
-      // error as POST_TIMEOUT.
-      const isAbortError = (error as { name?: string } | null)?.name === 'AbortError';
-
-      if (isAbortError) {
-        throw new NuiRequestError(
-          NuiErrorCodes.PostTimeout,
-          `POST ${url} timed out after ${this.postTimeoutMs}ms`,
-        );
-      }
-
-      throw new NuiRequestError(NuiErrorCodes.Transport, String(error));
-    } finally {
-      clearTimeout(deadline);
-    }
-  }
-}
+import { NuiErrorCodes, NuiRequestError } from './errors';
+import type { NuiLogger } from './logger';
+import type { NuiMessage } from './types';
+
+export type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * HTTP transport for FiveM NUI.
+ *
+ * Posts envelopes to `https://<resource>/<callback>` using `fetch`.
+ * Each POST is bounded by an `AbortController` deadline so a resource
+ * that stops answering (restart, shutdown) does not hang the page forever.
+ *
+ * Mirrors C# `FiveMNuiTransport`.
+ */
+export class MessageTransport {
+  private readonly resource: string;
+  private readonly callbackName: string;
+  private readonly postTimeoutMs: number;
+  private readonly logger: NuiLogger;
+  private readonly fetchImpl: FetchImpl;
+
+  constructor(
+    resource: string,
+    callbackName: string,
+    postTimeoutMs: number,
+    logger: NuiLogger,
+    fetchImpl: FetchImpl,
+  ) {
+    this.resource = resource;
+    this.callbackName = callbackName;
+    this.postTimeoutMs = postTimeoutMs;
+    this.logger = logger;
+    this.fetchImpl = fetchImpl;
+  }
+
+  /** URL of the main resource callback. */
+  get mainCallbackUrl(): string {
+    return `https://${this.resource}/${encodeURIComponent(this.callbackName)}`;
+  }
+
+  /** Builds the URL for an arbitrary callback on the same resource. */
+  callbackUrl(callbackName: string): string {
+    return `https://${this.resource}/${encodeURIComponent(callbackName)}`;
+  }
+
+  /**
+   * Raw POST to `url` with the configured timeout deadline.
+   *
+   * @throws {NuiRequestError} with code `POST_TIMEOUT` when the resource
+   *   stops answering within `postTimeoutMs`.
+   * @throws {NuiRequestError} with code `TRANSPORT` for any other failure.
+   */
+  async post(url: string, body: unknown): Promise<void> {
+    // Without an abort, a resource that stops answering leaves this promise
+    // pending forever and the caller's await never returns.
+    const controller = new AbortController();
+    const deadline = setTimeout(() => controller.abort(), this.postTimeoutMs);
+
+    try {
+      const response = await this.fetchImpl(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json; charset=UTF-8' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        throw new NuiRequestError(
+          NuiErrorCodes.Transport,
+          `POST ${url} failed with HTTP ${response.status}`,
+        );
+      }
+    } catch (error) {
+      // A timeout abort surfaces as an error whose `name` is 'AbortError'.
+      // In browsers that is a DOMException, but some fetch polyfills throw a
+      // plain Error, so match on the name instead of the constructor. Checking
+      // only `controller.signal.aborted` is unsafe: a race between the deadline
+      // firing and an unrelated network error would misclassify the network
+      // error as POST_TIMEOUT.
+      const isAbortError = (error as { name?: string } | null)?.name === 'AbortError';
+
+      if (isAbortError) {
+        throw new NuiRequestError(
+          NuiErrorCodes.PostTimeout,
+          `POST ${url} timed out after ${this.postTimeoutMs}ms`,
+        );
+      }
+
+      if (error instanceof NuiRequestError) throw error;
+      throw new NuiRequestError(NuiErrorCodes.Transport, String(error));
+    } finally {
+      clearTimeout(deadline);
+    }
+  }
+}

package/src/NuiClient.ts

@@ -35,15 +35,15 @@ const WINDOW_ACTIONS: ReadonlySet<string> = new Set<NuiWindowAction>([
 type WindowHandler = (action: NuiWindowAction, window: string | undefined) => void;
 
 /**
- * `NuiClient` is **thin façade** it composes four collaborators and
+ * `NuiClient` is **thin façade** it composes four collaborators and
  * orchestrates their interaction:
  *
  * | Collaborator           | Responsibility                         |
  * |------------------------|----------------------------------------|
  * | `MessageTransport`     | Raw HTTP POST to `https://<res>/<cb>`  |
- * | `RequestCoordinator`   | Correlation ID ↔ Promise resolution    |
+ * | `RequestCoordinator`   | Correlation ID ↔ Promise resolution    |
  * | `CallbackRegistry`     | C#-request handler lookup              |
- * | `EventBus`             | C#→UI event subscription / dispatch    |
+ * | `EventBus`             | C#→UI event subscription / dispatch    |
  *
  * Window lifecycle listeners (`onWindow`) and the browser `message`
  * listener (`listen`) stay here because they are browser-integration glue.
@@ -94,7 +94,7 @@ export class NuiClient {
 
     this.logger.debug('NuiClient initialized', { resource, callbackName, postTimeoutMs });
   }
-  
+
   /**
    * Sends a one way message to C#.
    *
@@ -277,7 +277,7 @@ export class NuiClient {
       throw error;
     }
   }
-  
+
   // Callback server (C# → UI requests)
   /**
    * Registers a callback handler for C# requests.
@@ -339,7 +339,7 @@ export class NuiClient {
   unregisterCallback(eventName: string): boolean {
     return this.callbackRegistry.unregister(eventName);
   }
-  
+
   /**
    * Subscribes to C# events.
    *
@@ -349,7 +349,7 @@ export class NuiClient {
   on<T>(eventName: keyof NuiEventMap extends never ? string : never, handler: (data: T) => void): () => void;
   on(eventName: string, handler: (data: unknown) => void): () => void {
     if (this.disposed) {
-      return () => {};
+      return () => { };
     }
 
     return this.eventBus.on(eventName, handler);
@@ -362,7 +362,7 @@ export class NuiClient {
   once<T>(eventName: keyof NuiEventMap extends never ? string : never, handler: (data: T) => void): () => void;
   once(eventName: string, handler: (data: unknown) => void): () => void {
     if (this.disposed) {
-      return () => {};
+      return () => { };
     }
 
     return this.eventBus.once(eventName, handler);
@@ -374,7 +374,7 @@ export class NuiClient {
   off(eventName: string, handler?: EventHandler): void {
     this.eventBus.off(eventName, handler);
   }
-  
+
   /**
    * Subscribes to window lifecycle envelopes from C#.
    *
@@ -383,7 +383,7 @@ export class NuiClient {
    */
   onWindow(handler: WindowHandler): () => void {
     if (this.disposed) {
-      return () => {};
+      return () => { };
     }
 
     this.windowListeners.add(handler);
@@ -392,7 +392,7 @@ export class NuiClient {
       this.windowListeners.delete(handler);
     };
   }
-  
+
   /**
    * Routes an incoming message from C#. Pass `MessageEvent.data` here;
    * `listen()` does that for you.
@@ -430,7 +430,7 @@ export class NuiClient {
    */
   listen(target: Window = window): () => void {
     if (this.listening) {
-      return () => {};
+      return () => { };
     }
 
     this.listening = true;
@@ -451,15 +451,19 @@ export class NuiClient {
 
     target.addEventListener('message', listener as EventListener);
 
-    this.stopListening = () => {
+    let stopped = false;
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
       target.removeEventListener('message', listener as EventListener);
-      this.listening = false;
-      this.stopListening = null;
+      if (this.stopListening === stop) {
+        this.listening = false;
+        this.stopListening = null;
+      }
     };
+    this.stopListening = stop;
 
-    return () => {
-      this.stopListening?.();
-    };
+    return stop;
   }
 
   /** Handles incoming requests from C#. */
@@ -556,7 +560,7 @@ export class NuiClient {
       }
     }
   }
-  
+
   /**
    * POSTs an envelope to the main callback, incrementing the `sent` counter.
    * Reused by `send`, `sendAndWait` and `request`.
@@ -575,7 +579,7 @@ export class NuiClient {
       this.logger.warn('Could not deliver response', error);
     }
   }
-  
+
   /** Current counters. Cheap enough to call from a diagnostics panel. */
   getDiagnostics(): NuiDiagnostics {
     return {

package/src/NuiClientOptions.ts

@@ -1,57 +1,57 @@
-import type { NuiLogger } from './logger';
-
-/**
- * Options for the NUI bridge.
- */
-export interface NuiClientOptions {
-  /**
-   * Resource name the NUI page is served from. Defaults to `GetParentResourceName()`.
-   */
-  resource?: string;
-  /**
-   * Name of the resource callback C# registered via `RegisterRawNuiCallback`.
-   * Every outbound message is POSTed to `https://<resource>/<callback>`.
-   */
-  callback?: string;
-  /**
-   * Window name that `open`/`close` envelopes refer to. Passed straight
-   * through to `onWindow`, so the UI can ignore other windows.
-   */
-  window?: string;
-  /**
-   * How long a single POST may take before it is aborted, in milliseconds.
-   * The resource can stop answering at any time (restart, shutdown) and a raw
-   * fetch without a deadline would leave the caller awaiting forever.
-   */
-  postTimeoutMs?: number;
-  /**
-   * Default deadline for {@link NuiClient.request}, in milliseconds.
-   * Matches the C# `NuiOptions.DefaultTimeout` default of 30s.
-   */
-  requestTimeoutMs?: number;
-  /**
-   * Where diagnostics go. Defaults to the console; pass `nullNuiLogger` to
-   * silence it entirely.
-   */
-  logger?: NuiLogger;
-  /**
-   * Injection seam for tests. Defaults to the global `fetch`.
-   */
-  fetch?: typeof fetch;
-}
-
-/**
- * Resolves the owning FiveM resource name from the ambient FiveM runtime.
- *
- * Falls back to `'unknown_resource'` when running outside a game context
- * (SSR, unit tests, build pipeline) so importing the package never throws.
- */
-export function readResourceName(): string {
-  const runtime = globalThis as { GetParentResourceName?: () => string };
-
-  if (typeof runtime.GetParentResourceName === 'function') {
-    return runtime.GetParentResourceName();
-  }
-
-  return 'unknown_resource';
-}
+import type { NuiLogger } from './logger';
+
+/**
+ * Options for the NUI bridge.
+ */
+export interface NuiClientOptions {
+  /**
+   * Resource name the NUI page is served from. Defaults to `GetParentResourceName()`.
+   */
+  resource?: string;
+  /**
+   * Name of the resource callback C# registered via `RegisterRawNuiCallback`.
+   * Every outbound message is POSTed to `https://<resource>/<callback>`.
+   */
+  callback?: string;
+  /**
+   * Window name that `open`/`close` envelopes refer to. Passed straight
+   * through to `onWindow`, so the UI can ignore other windows.
+   */
+  window?: string;
+  /**
+   * How long a single POST may take before it is aborted, in milliseconds.
+   * The resource can stop answering at any time (restart, shutdown) and a raw
+   * fetch without a deadline would leave the caller awaiting forever.
+   */
+  postTimeoutMs?: number;
+  /**
+   * Default deadline for {@link NuiClient.request}, in milliseconds.
+   * Matches the C# `NuiOptions.DefaultTimeout` default of 30s.
+   */
+  requestTimeoutMs?: number;
+  /**
+   * Where diagnostics go. Defaults to the console; pass `nullNuiLogger` to
+   * silence it entirely.
+   */
+  logger?: NuiLogger;
+  /**
+   * Injection seam for tests. Defaults to the global `fetch`.
+   */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Resolves the owning FiveM resource name from the ambient FiveM runtime.
+ *
+ * Falls back to `'unknown_resource'` when running outside a game context
+ * (SSR, unit tests, build pipeline) so importing the package never throws.
+ */
+export function readResourceName(): string {
+  const runtime = globalThis as { GetParentResourceName?: () => string };
+
+  if (typeof runtime.GetParentResourceName === 'function') {
+    return runtime.GetParentResourceName();
+  }
+
+  return 'unknown_resource';
+}

package/src/RequestCoordinator.ts

@@ -1,105 +1,105 @@
-/**
- * A pending request awaiting a correlated response.
- */
-interface PendingRequest {
-  resolve: (value: unknown) => void;
-  reject: (error: Error) => void;
-  timeout: ReturnType<typeof setTimeout>,
-  /** Released whenever the request settles or is removed (e.g. abort listener). */
-  cleanup?: () => void;
-}
-
-/**
- * Tracks in-flight requests by correlation ID, matching responses
- * to their Promise resolvers.
- *
- * Mirrors C# `ConcurrentRequestManager` same idea, same responsibilities:
- * register, resolve, reject, unregister, and reject all on dispose.
- */
-export class RequestCoordinator {
-  private pending = new Map<string, PendingRequest>();
-
-  /** Store a pending request so a later response can resolve or reject it. */
-  register(
-    id: string,
-    resolve: PendingRequest['resolve'],
-    reject: PendingRequest['reject'],
-    timeout: ReturnType<typeof setTimeout>,
-    cleanup?: () => void,
-  ): void {
-    this.pending.set(id, { resolve, reject, timeout, cleanup });
-  }
-
-  /**
-   * Resolve the request whose correlation ID matches.
-   * @returns `true` if a matching request was found.
-   */
-  resolve(id: string, payload: unknown): boolean {
-    const entry = this.pending.get(id);
-    if (!entry) {
-      return false;
-    }
-
-    clearTimeout(entry.timeout);
-    entry.cleanup?.();
-    this.pending.delete(id);
-    entry.resolve(payload);
-    return true;
-  }
-
-  /**
-   * Reject the request whose correlation ID matches.
-   * @returns `true` if a matching request was found.
-   */
-  reject(id: string, error: Error): boolean {
-    const entry = this.pending.get(id);
-    if (!entry) {
-      return false;
-    }
-
-    clearTimeout(entry.timeout);
-    entry.cleanup?.();
-    this.pending.delete(id);
-    entry.reject(error);
-    return true;
-  }
-
-  /** Removes a request without resolving or rejecting it (error-path cleanup). */
-  unregister(id: string): void {
-    const entry = this.pending.get(id);
-    if (entry) {
-      clearTimeout(entry.timeout);
-      entry.cleanup?.();
-      this.pending.delete(id);
-    }
-  }
-
-  /** Number of requests still awaiting a response. */
-  get pendingCount(): number {
-    return this.pending.size;
-  }
-
-  /**
-   * Rejects every outstanding request with the supplied error.
-   * Called during `dispose()` so callers don't hang forever.
-   * @returns the number of requests that were rejected.
-   */
-  rejectAll(error: Error): number {
-    const entries = Array.from(this.pending.values());
-
-    this.pending.clear();
-
-    for (const entry of entries) {
-      clearTimeout(entry.timeout);
-      entry.cleanup?.();
-      entry.reject(error);
-    }
-
-    return entries.length;
-  }
-
-  /** Generates a unique correlation ID for a new request. */
-  static generateCorrelationId(): string {
-    return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
-  }
-}
+/**
+ * A pending request awaiting a correlated response.
+ */
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>,
+  /** Released whenever the request settles or is removed (e.g. abort listener). */
+  cleanup?: () => void;
+}
+
+/**
+ * Tracks in-flight requests by correlation ID, matching responses
+ * to their Promise resolvers.
+ *
+ * Mirrors C# `ConcurrentRequestManager` same idea, same responsibilities:
+ * register, resolve, reject, unregister, and reject all on dispose.
+ */
+export class RequestCoordinator {
+  private pending = new Map<string, PendingRequest>();
+
+  /** Store a pending request so a later response can resolve or reject it. */
+  register(
+    id: string,
+    resolve: PendingRequest['resolve'],
+    reject: PendingRequest['reject'],
+    timeout: ReturnType<typeof setTimeout>,
+    cleanup?: () => void,
+  ): void {
+    this.pending.set(id, { resolve, reject, timeout, cleanup });
+  }
+
+  /**
+   * Resolve the request whose correlation ID matches.
+   * @returns `true` if a matching request was found.
+   */
+  resolve(id: string, payload: unknown): boolean {
+    const entry = this.pending.get(id);
+    if (!entry) {
+      return false;
+    }
+
+    clearTimeout(entry.timeout);
+    entry.cleanup?.();
+    this.pending.delete(id);
+    entry.resolve(payload);
+    return true;
+  }
+
+  /**
+   * Reject the request whose correlation ID matches.
+   * @returns `true` if a matching request was found.
+   */
+  reject(id: string, error: Error): boolean {
+    const entry = this.pending.get(id);
+    if (!entry) {
+      return false;
+    }
+
+    clearTimeout(entry.timeout);
+    entry.cleanup?.();
+    this.pending.delete(id);
+    entry.reject(error);
+    return true;
+  }
+
+  /** Removes a request without resolving or rejecting it (error-path cleanup). */
+  unregister(id: string): void {
+    const entry = this.pending.get(id);
+    if (entry) {
+      clearTimeout(entry.timeout);
+      entry.cleanup?.();
+      this.pending.delete(id);
+    }
+  }
+
+  /** Number of requests still awaiting a response. */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  /**
+   * Rejects every outstanding request with the supplied error.
+   * Called during `dispose()` so callers don't hang forever.
+   * @returns the number of requests that were rejected.
+   */
+  rejectAll(error: Error): number {
+    const entries = Array.from(this.pending.values());
+
+    this.pending.clear();
+
+    for (const entry of entries) {
+      clearTimeout(entry.timeout);
+      entry.cleanup?.();
+      entry.reject(error);
+    }
+
+    return entries.length;
+  }
+
+  /** Generates a unique correlation ID for a new request. */
+  static generateCorrelationId(): string {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+}