Types

Shared TypeScript types exported by @almighty-shogun/webkit-native-bridge.

Some signatures reuse utility types from @almighty-shogun/utils: Nullable, NullableOrUndefinable, and Undefinable.

BridgeSuccess

Successful native bridge response. It carries the typed response data and keeps message nullable because native code may omit a human-readable message for successful responses.

type BridgeSuccess<T> = {
    ok: true;
    message: Nullable<string>;
    data: T;
};

BridgeError

Error payload returned by native code or produced by the JavaScript transport layer. The type field distinguishes native application errors from transport failures such as timeouts or unavailable handlers.

type BridgeError<TCode extends string = string, TDetails = unknown> = {
    type: 'native' | 'transport';
    code: TCode;
    message: Nullable<string>;
    details: Nullable<TDetails>;
};

BridgeFailure

Failed native bridge response. It keeps the top-level nullable message from the raw response and includes the structured BridgeError for code, type, and details handling.

type BridgeFailure<TCode extends string = string, TDetails = unknown> = {
    ok: false;
    message: Nullable<string>;
    error: BridgeError<TCode, TDetails>;
};

BridgeResponse

Discriminated union returned by NativeBridge.request(). Branch on response.ok to safely access either typed data or typed error details.

type BridgeResponse<
    TData,
    TCode extends string = string,
    TDetails = unknown
> = BridgeSuccess<TData> | BridgeFailure<TCode, TDetails>;

ResolvedBridgeError

Normalized error shape returned by mapBridgeError() and used by failed NormalizedBridgeResponse values. Unlike BridgeError, the message is always a string.

type ResolvedBridgeError = {
    type: 'native' | 'transport';
    code: string;
    message: string;
    details: unknown;
};

NormalizedBridgeResponse

Response union returned by normalizeBridgeResponse(). Success responses keep the original success shape, while failures expose a ResolvedBridgeError with a non-null message.

type NormalizedBridgeResponse<TData> = BridgeSuccess<TData> | {
    ok: false;
    error: ResolvedBridgeError;
};

NativeTransportErrorCode

Transport error code union produced by the JavaScript bridge runtime for failures that happen before or outside native application handling.

type NativeTransportErrorCode =
    | 'TIMEOUT'
    | 'UNAVAILABLE'
    | 'DISPOSED'
    | 'UNKNOWN';

NativeTransportErrorDetails

Details attached to transport errors. The cause field can preserve the original thrown error or runtime value that triggered the transport failure.

type NativeTransportErrorDetails = {
    cause?: unknown;
};

NativeBridgeRequestMap

Contract map used to type native request method names, request bodies, response bodies, and optional native error metadata.

type NativeBridgeRequestMap = Record<string, {
    body: unknown;
    response: unknown;
    errorCode?: Undefinable<string>;
    errorDetails?: unknown;
}>;

NativeRequestResult

The full response type for one request method, assembled from the contract's response body and the two error unions above. NativeBridge.request() resolves to this, so it is what you branch on with response.ok.

type NativeRequestResult<
    TRequests extends NativeBridgeRequestMap,
    TMethod extends keyof TRequests
> = BridgeResponse<
    NativeResponseBody<TRequests, TMethod>,
    BridgeErrorCode<TRequests, TMethod>,
    BridgeErrorDetails<TRequests, TMethod>
>;

NativeResponseEventDetail

DOM event detail shape expected by NativeBridge.handleResponse() and the automatic response listener. Native code dispatches this detail back to JavaScript to resolve a pending request.

type NativeResponseEventDetail = {
    requestId: string;
    ok: boolean;
    payload: unknown;
    error: unknown;
};

NativeBridgeWindow

Window-like object used by the bridge runtime. Pass this through NativeBridgeOptions.window for tests, alternate runtimes, or explicit WebKit window injection.

type NativeBridgeWindow = Window & {
    webkit?: Undefinable<{
        messageHandlers?: Undefinable<Record<
            string,
            Undefinable<NativeBridgeMessageHandler>
        >>;
    }>
};

NativeRequestOptions

Per-request options accepted by NativeBridge.request(). Use timeout to override the bridge default for one request, or null to disable that request timeout.

type NativeRequestOptions = {
    timeout?: NullableOrUndefinable<number>;
};

NativeBridgeOptions

Configuration accepted by createNativeBridge(). It controls the response event name, WebKit handler name, default request timeout, and window-like runtime object.

type NativeBridgeOptions = {
    eventName?: Undefinable<string>;
    handlerName?: Undefinable<string>;
    requestTimeout?: NullableOrUndefinable<number>;
    window?: Undefinable<NativeBridgeWindow>;
};

NativeBridge

Runtime bridge object returned by createNativeBridge(). It exposes low-level posting, typed request/response calls, fire-and-forget commands, availability checks, manual response handling, and disposal.

type NativeBridge<
    TRequests extends NativeBridgeRequestMap,
    TCommands extends string = never
> = {
    call(method: TCommands): void;
    dispose(): void;
    handleResponse(detail: NativeResponseEventDetail): void;
    isAvailable(): boolean;
    postMessage(message: string): void;
    request: {
        <TMethod extends NativeMethodsWithoutBody<TRequests>>(
            method: TMethod,
            body?: undefined,
            options?: Undefinable<NativeRequestOptions>
        ): Promise<NativeRequestResult<TRequests, TMethod>>;
        <TMethod extends NativeMethodsWithBody<TRequests>>(
            method: TMethod,
            body: NativeRequestBody<TRequests, TMethod>,
            options?: Undefinable<NativeRequestOptions>
        ): Promise<NativeRequestResult<TRequests, TMethod>>;
    };
};