@bereasoftware/nexa 1.7.0 → 1.8.0

package/dist/types/dev-overlay/env.d.ts

@@ -0,0 +1 @@
+export declare function isDevelopmentEnv(): boolean;

package/dist/types/dev-overlay/format.d.ts

@@ -0,0 +1,3 @@
+export declare function escapeHtml(value: string): string;
+export declare function truncateUrl(url: string, max?: number): string;
+export declare function formatJson(data: unknown): string;

package/dist/types/dev-overlay/overlay.d.ts

@@ -31,8 +31,6 @@ export declare class DevOverlayUI {
     private exportHistory;
     private copyAsFetch;
     private showNotification;
-    private truncateUrl;
-    private formatJson;
     private canUseDOM;
     private createFloatingIcon;
     private showFloatingIcon;

package/dist/types/dev-overlay/render.d.ts

@@ -0,0 +1,6 @@
+import type { TrackedRequest, DevMetrics } from './types';
+export type FilterType = 'all' | 'xhr' | 'fetch' | 'err' | 'slow';
+export declare function filterRequests(requests: TrackedRequest[], filterType: FilterType, searchQuery: string): TrackedRequest[];
+export declare function renderRequestListHtml(requests: TrackedRequest[], searchQuery: string): string;
+export declare function renderMetricsHtml(m: DevMetrics): string;
+export declare function renderDetailHtml(request: TrackedRequest): string;

package/dist/types/dev-overlay/theme.d.ts

@@ -0,0 +1,40 @@
+export declare const ICONS: {
+    gear: string;
+    close: string;
+    chevron: string;
+    back: string;
+    retry: string;
+    clear: string;
+    search: string;
+    clock: string;
+    zap: string;
+    download: string;
+    copy: string;
+};
+export declare const COLORS: {
+    bg: string;
+    bgElevated: string;
+    bgSurface: string;
+    border: string;
+    borderFocus: string;
+    text: string;
+    textMuted: string;
+    textDim: string;
+    accent: string;
+    accentHover: string;
+    accentSoft: string;
+    success: string;
+    successBg: string;
+    error: string;
+    errorBg: string;
+    warning: string;
+    warningBg: string;
+    info: string;
+    infoBg: string;
+    get: string;
+    post: string;
+    put: string;
+    patch: string;
+    delete: string;
+};
+export declare const STYLES: string;

package/dist/types/dev-overlay/tracker.d.ts

@@ -1,18 +1,24 @@
 import type { TrackedRequest, DevMetrics, DevOverlayConfig } from './types';
 export declare function loadPersistedConfig(): Partial<DevOverlayConfig>;
 export declare class RequestTracker {
-    private history;
+    /** Fixed-size ring buffer; `buffer[writeIndex]` is the next slot to overwrite. */
+    private buffer;
+    private writeIndex;
+    private count;
     private maxHistory;
     private listeners;
     private startTime;
     private config;
     constructor(config?: DevOverlayConfig);
     track(request: Omit<TrackedRequest, 'id' | 'timestamp'>): TrackedRequest;
+    /** Returns a fresh array, newest first. O(n) — safe to call on every render. */
     getHistory(): TrackedRequest[];
     getMetrics(): DevMetrics;
     clear(): void;
     onChange(listener: (request: TrackedRequest) => void): () => void;
     getConfig(): Required<DevOverlayConfig>;
     updateConfig(partial: Partial<DevOverlayConfig>): Required<DevOverlayConfig>;
+    /** Rebuilds the ring buffer at a new capacity, keeping the most recent entries. */
+    private resizeHistory;
     private generateId;
 }

package/dist/types/http-client/http-client.d.ts

@@ -58,6 +58,12 @@ export declare class HttpClient implements IHttpClient {
     post<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     put<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     patch<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    /**
+     * Safe, idempotent request carrying a JSON body (IETF-draft HTTP QUERY
+     * method). Use it for complex search/filter payloads that don't fit in a
+     * URL. Cacheable like GET when `config.cache` is enabled.
+     */
+    query<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     delete<T = unknown>(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     head(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
     options(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
@@ -120,6 +126,7 @@ export declare class HttpClient implements IHttpClient {
     poll<T = unknown>(url: string, options: PollOptions<T>, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     private buildRequest;
     private buildUrl;
+    private isCacheableMethod;
     private getCacheKey;
     private fetchWithTimeout;
     /**

package/dist/types/http-client/index.d.ts

@@ -2,6 +2,6 @@
  * HTTP Client Plugin - Main Exports
  */
 export { createHttpClient, HttpClient, HttpError, isHttpError, } from './http-client.js';
-export type { IHttpClient, HttpRequest, HttpRequestConfig, HttpResponse, HttpErrorDetails, RequestInterceptor, ResponseInterceptor, RetryStrategy, CacheStrategy, Validator, Transformer, HttpClientConfig, ResponseType, RequestHooks, ProgressEvent, PaginateOptions, PollOptions, Disposer, Result, } from '../types/index.js';
+export type { IHttpClient, HttpRequest, HttpRequestConfig, HttpResponse, HttpErrorDetails, RequestInterceptor, ResponseInterceptor, RetryStrategy, CacheStrategy, Validator, Transformer, HttpClientConfig, ResponseType, RequestHooks, ProgressEvent, PaginateOptions, PollOptions, Disposer, Result, QueryParams, QueryParamValue, } from '../types/index.js';
 export { Ok, Err } from '../types/index.js';
 export { withTimeout, retry, createSchemaValidator, createRequiredFieldsValidator, validatorIsArray, validatorIsObject, transformSnakeToCamel, transformCamelToSnake, transformFlatten, createProjectionTransformer, createWrapperTransformer, AggressiveRetry, ConservativeRetry, CircuitBreakerRetry, CacheStore, createCacheMiddleware, cacheMiddleware, RequestDeduplicator, createDedupeMiddleware, dedupeMiddleware, MiddlewarePipeline, createPipeline, type Middleware, type HttpContext, createTypedResponse, createTypedRequest, createTypedApiClient, createTypeGuard, createUrl, createApiUrl, TypedObservable, Defer, type TypedResponse, type ApiEndpoint, type ApiSchema, type Url, type ApiUrl, type FileUrl, type UnionToIntersection, type ResultOf, handleStream, streamToFile, createStreamingMiddleware, streamingMiddleware, type StreamOptions, PluginManager, LoggerPlugin, MetricsPlugin, CachePlugin, DedupePlugin, type Plugin, } from '../utils';

package/dist/types/realtime/index.d.ts

@@ -3,7 +3,7 @@
  * Provides unified API for real-time communication with automatic reconnection,
  * heartbeat, and plugin support.
  */
-export type { WebSocketOptions, SSEOptions, RealtimeMessageEvent, IRealtimeClient, IWebSocketClient, ISSEClient, } from '../types/index.js';
+export type { WebSocketOptions, SSEOptions, RealtimeMessageEvent, IRealtimeClient, IWebSocketClient, ISSEClient, RealtimeSendError, } from '../types/index.js';
 export { createWebSocketClient } from './websocket-client.js';
 export { createSSEClient } from './sse-client.js';
 export { createRealtimePlugin } from './plugin.js';

package/dist/types/types/index.d.ts

@@ -15,12 +15,24 @@ export type Result<T, E = Error> = {
 };
 export declare const Ok: <T>(value: T) => Result<T>;
 export declare const Err: <E>(error: E) => Result<never, E>;
+/**
+ * A single query-string value. Arrays are serialized as repeated keys
+ * (`?tag=a&tag=b`); nested plain objects use one level of bracket notation
+ * (`?filter[status]=active`). `null`/`undefined` values are omitted.
+ */
+export type QueryParamValue = string | number | boolean | null | undefined | Array<string | number | boolean> | Record<string, string | number | boolean | null | undefined>;
+export type QueryParams = Record<string, QueryParamValue>;
 export interface HttpRequest {
     url: string;
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /**
+     * 'QUERY' is the IETF-draft safe/idempotent/cacheable HTTP method that
+     * carries a JSON body — use it for complex search/filter payloads that
+     * don't fit cleanly in a URL. See `IHttpClient.query()`.
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'QUERY';
     headers?: Record<string, string>;
     body?: unknown;
-    query?: Record<string, string | number | boolean>;
+    query?: QueryParams;
     params?: Record<string, string | number>;
     timeout?: HttpTimeout;
     signal?: AbortSignal;
@@ -247,6 +259,12 @@ export interface IHttpClient {
     post<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     put<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     patch<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
+    /**
+     * Safe, idempotent request carrying a JSON body — for complex search/filter
+     * payloads that don't fit in a URL. Cacheable like GET when `config.cache`
+     * is enabled (the body is included in the cache key).
+     */
+    query<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, 'url' | 'method' | 'body'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     delete<T = unknown>(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<T>, HttpErrorDetails>>;
     head(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
     options(url: string, config?: Omit<HttpRequestConfig, 'url' | 'method'>): Promise<Result<HttpResponse<void>, HttpErrorDetails>>;
@@ -419,6 +437,13 @@ export interface RealtimeMessageEvent<T = unknown> {
     /** Timestamp when message was received */
     timestamp: number;
 }
+/**
+ * Error returned by a failed IRealtimeClient.send()/sendJson() call.
+ */
+export interface RealtimeSendError {
+    message: string;
+    code: 'NOT_CONNECTED' | 'UNSUPPORTED' | 'SEND_FAILED';
+}
 /**
  * Real-time client interface
  */
@@ -427,8 +452,8 @@ export interface IRealtimeClient {
     connect(): Promise<void>;
     /** Disconnect from the server */
     disconnect(): void;
-    /** Send a message */
-    send(data: string | ArrayBuffer | Blob): void;
+    /** Send a message. Returns a Result instead of throwing on failure. */
+    send(data: string | ArrayBuffer | Blob): Result<void, RealtimeSendError>;
     /** Subscribe to messages */
     onMessage<T = unknown>(callback: (event: RealtimeMessageEvent<T>) => void): () => void;
     /** Subscribe to connection open events */
@@ -453,8 +478,8 @@ export interface IRealtimeClient {
 export interface IWebSocketClient extends IRealtimeClient {
     /** WebSocket instance */
     readonly socket: WebSocket | null;
-    /** Send JSON data (automatically serialized) */
-    sendJson(data: unknown): void;
+    /** Send JSON data (automatically serialized). Returns a Result instead of throwing. */
+    sendJson(data: unknown): Result<void, RealtimeSendError>;
     /** Subscribe to specific message types */
     onMessageType<T = unknown>(type: string, callback: (data: T) => void): () => void;
 }

package/dist/types/utils/index.d.ts

@@ -189,7 +189,7 @@ export declare function createTypedResponse<T, U = unknown>(status: number, data
  * API Endpoint definition with typed request/response
  */
 export interface ApiEndpoint<TRequest = unknown, TResponse = unknown> {
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'QUERY';
     path: string;
     request?: TRequest;
     response: TResponse;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bereasoftware/nexa",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "main": "./dist/nexa.cjs.js",
   "module": "./dist/nexa.es.js",
@@ -25,7 +25,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "packageManager": "pnpm@10.21.0",
+  "packageManager": "pnpm@11.9.0",
   "keywords": [
     "http",
     "client",
@@ -90,21 +90,21 @@
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/github": "^12.0.8",
     "@semantic-release/npm": "^13.1.5",
-    "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@vitest/coverage-v8": "^4.1.2",
-    "@vitest/ui": "^4.1.2",
-    "eslint": "^9.0.0",
-    "husky": "^9.0.0",
-    "lint-staged": "^15.0.0",
-    "prettier": "^3.0.0",
-    "semantic-release": "^25.0.3",
-    "typescript": "~6.0.2",
-    "vite": "^8.0.3",
-    "vitest": "^4.1.2"
+    "@types/node": "^26.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.62.1",
+    "@typescript-eslint/parser": "^8.62.1",
+    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/ui": "^4.1.9",
+    "eslint": "^10.6.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.8",
+    "prettier": "^3.9.4",
+    "semantic-release": "^25.0.5",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.2",
+    "vitest": "^4.1.9"
   },
   "lint-staged": {
     "*.ts": [