@opra/client 1.26.3 → 1.27.0

package/README.md

@@ -1,3 +1,26 @@
 # @opra/client
 
-OPRA Client
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+
+## Support
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+
+## Node Compatibility
+- node >= 20.x
+
+
+## License
+Available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/@opra/client
+[npm-url]: https://npmjs.org/package/@opra/client
+[downloads-image]: https://img.shields.io/npm/dm/@opra/client.svg
+[downloads-url]: https://npmjs.org/package/@opra/client
+[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=main
+[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/core/backend.d.ts

@@ -1,18 +1,41 @@
 import { ApiDocument } from '@opra/common';
 import { Observable } from 'rxjs';
 import type { HttpEvent } from '../http/interfaces/http-event.js';
+/**
+ * Abstract base class for all backends.
+ *
+ * @class Backend
+ */
 export declare abstract class Backend implements Backend {
+    /** The API document associated with this backend */
     document?: ApiDocument;
+    /**
+     * Creates a new instance of Backend.
+     *
+     * @param options Configuration options.
+     * @protected
+     */
     protected constructor(options?: Backend.Options);
+    /**
+     * Handles the request and returns an observable of {@link HttpEvent}.
+     *
+     * @param init The request initialization parameters.
+     * @returns An observable of HttpEvent.
+     */
     abstract handle(init: Backend.RequestInit): Observable<HttpEvent>;
 }
 /**
+ * Namespace for {@link Backend} related types and interfaces.
+ *
  * @namespace Backend
  */
 export declare namespace Backend {
+    /** Configuration options for Backend */
     interface Options {
+        /** The API document associated with this backend */
         document?: ApiDocument;
     }
+    /** Request initialization parameters for Backend */
     interface RequestInit {
     }
 }

package/core/backend.js

@@ -1,5 +1,17 @@
+/**
+ * Abstract base class for all backends.
+ *
+ * @class Backend
+ */
 export class Backend {
+    /** The API document associated with this backend */
     document;
+    /**
+     * Creates a new instance of Backend.
+     *
+     * @param options Configuration options.
+     * @protected
+     */
     constructor(options) {
         this.document = options?.document;
     }

package/core/client-error.d.ts

@@ -1,8 +1,21 @@
 import type { ErrorIssue } from '@opra/common';
+/**
+ * Error class for OPRA client operations.
+ *
+ * @class ClientError
+ */
 export declare class ClientError extends Error {
     cause?: Error | undefined;
+    /** Detailed error issues */
     issues: ErrorIssue[];
+    /** HTTP status code */
     status?: number;
+    /**
+     * Creates a new instance of ClientError.
+     *
+     * @param init Initialization parameters.
+     * @param cause The underlying error cause.
+     */
     constructor(init: {
         message: string;
         issues?: ErrorIssue[];

package/core/client-error.js

@@ -1,7 +1,20 @@
+/**
+ * Error class for OPRA client operations.
+ *
+ * @class ClientError
+ */
 export class ClientError extends Error {
     cause;
+    /** Detailed error issues */
     issues;
+    /** HTTP status code */
     status;
+    /**
+     * Creates a new instance of ClientError.
+     *
+     * @param init Initialization parameters.
+     * @param cause The underlying error cause.
+     */
     constructor(init, cause) {
         super(init.message);
         this.cause = cause;

package/http/http-backend.d.ts

@@ -2,25 +2,42 @@ import { Backend } from '../core/backend.js';
 import type { HttpHandler } from './interfaces/http-handler.js';
 import type { HttpInterceptor } from './interfaces/http-interceptor.js';
 /**
+ * Base class for HTTP backends.
  *
  * @class HttpBackend
  */
 export declare abstract class HttpBackend extends Backend implements HttpHandler {
+    /** The base URL of the service */
     readonly serviceUrl: string;
+    /** List of HTTP interceptors */
     interceptors?: HttpInterceptor<any>[];
+    /**
+     * Creates a new instance of HttpBackend.
+     *
+     * @param serviceUrl The base URL of the service.
+     * @param options Configuration options.
+     * @protected
+     */
     protected constructor(serviceUrl: string, options?: HttpBackend.Options);
 }
 /**
+ * Namespace for {@link HttpBackend} related types and interfaces.
  *
  * @namespace HttpBackend
  */
 export declare namespace HttpBackend {
+    /** Configuration options for HttpBackend */
     interface Options extends Backend.Options {
     }
+    /** Request initialization parameters for HttpBackend */
     interface RequestInit extends Backend.RequestInit {
+        /** HTTP method (GET, POST, etc.) */
         method: string;
+        /** The target URL */
         url: string | URL;
+        /** HTTP headers */
         headers?: Headers;
+        /** Request body */
         body?: any;
     }
 }

package/http/http-backend.js

@@ -1,11 +1,21 @@
 import { Backend } from '../core/backend.js';
 /**
+ * Base class for HTTP backends.
  *
  * @class HttpBackend
  */
 export class HttpBackend extends Backend {
+    /** The base URL of the service */
     serviceUrl;
+    /** List of HTTP interceptors */
     interceptors;
+    /**
+     * Creates a new instance of HttpBackend.
+     *
+     * @param serviceUrl The base URL of the service.
+     * @param options Configuration options.
+     * @protected
+     */
     constructor(serviceUrl, options) {
         super(options);
         const u = new URL(serviceUrl);

package/http/http-client-base.d.ts

@@ -4,33 +4,100 @@ import { kBackend } from '../constants.js';
 import { HttpBackend } from './http-backend.js';
 import { HttpRequestObservable } from './http-request-observable.js';
 /**
+ * Namespace for {@link OpraClientBase} related types and interfaces.
  *
  * @namespace OpraClientBase
  */
 export declare namespace OpraClientBase {
+    /** Configuration options for OpraClientBase */
     interface Options {
+        /** The API document associated with this client */
         document?: ApiDocument;
     }
+    /** Generic request options for OPRA client */
     type RequestOptions = Partial<StrictOmit<HttpBackend.RequestInit, 'url'>> & {
+        /** URL parameters */
         params?: URLSearchParamsInit;
     };
 }
 /**
+ * Base class for OPRA HTTP clients.
  *
  * @class OpraClientBase
  * @abstract
  */
 export declare abstract class HttpClientBase<TRequestOptions = {}, TResponseExt = {}> {
     protected [kBackend]: HttpBackend;
+    /**
+     * Creates a new instance of HttpClientBase.
+     *
+     * @param backend The backend instance to use for requests.
+     * @protected
+     */
     protected constructor(backend: HttpBackend);
+    /**
+     * Gets the base service URL.
+     */
     get serviceUrl(): string;
+    /**
+     * Fetches the API document from the service.
+     *
+     * @param options Fetch options.
+     * @returns A promise that resolves to an ApiDocument.
+     * @throws {@link Error} if there is an issue fetching or parsing the document.
+     */
     fetchDocument(options?: {
         documentId?: string;
     }): Promise<ApiDocument>;
+    /**
+     * Creates a new {@link HttpRequestObservable} for a specific path.
+     *
+     * @param path The path of the request.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     request<TBody = any>(path: string, options?: OpraClientBase.RequestOptions): HttpRequestObservable<TBody, TBody, TRequestOptions, TResponseExt>;
+    /**
+     * Sends a DELETE request.
+     *
+     * @param path The path of the request.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     delete<TBody = any>(path: string, options?: StrictOmit<OpraClientBase.RequestOptions, 'method' | 'body'>): HttpRequestObservable<TBody, TBody, TRequestOptions, TResponseExt>;
+    /**
+     * Sends a GET request.
+     *
+     * @param path The path of the request.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     get<TBody = any>(path: string, options?: StrictOmit<OpraClientBase.RequestOptions, 'method' | 'body'>): HttpRequestObservable<TBody, TBody, TRequestOptions, TResponseExt>;
+    /**
+     * Sends a PATCH request.
+     *
+     * @param path The path of the request.
+     * @param requestBody The request body.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     patch<TBody = any>(path: string, requestBody: any, options?: StrictOmit<OpraClientBase.RequestOptions, 'method' | 'body'>): HttpRequestObservable<TBody, TBody, TRequestOptions, TResponseExt>;
+    /**
+     * Sends a POST request.
+     *
+     * @param path The path of the request.
+     * @param requestBody The request body.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     post<TBody = any>(path: string, requestBody: any, options?: StrictOmit<OpraClientBase.RequestOptions, 'method' | 'body'>): HttpRequestObservable<TBody, TBody, TRequestOptions, TResponseExt>;
+    /**
+     * Sends a PUT request.
+     *
+     * @param path The path of the request.
+     * @param requestBody The request body.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     put<TBody = any>(path: string, requestBody: any, options?: StrictOmit<OpraClientBase.RequestOptions, 'method' | 'body'>): HttpRequestObservable<TBody, TBody, TRequestOptions, TResponseExt>;
 }

package/http/http-client-base.js

@@ -4,20 +4,37 @@ import { kBackend } from '../constants.js';
 import { HttpRequestObservable } from './http-request-observable.js';
 const SPLIT_BACKSLASH_PATTERN = /^(\/*)(.+)/;
 /**
+ * Base class for OPRA HTTP clients.
  *
  * @class OpraClientBase
  * @abstract
  */
 export class HttpClientBase {
+    /**
+     * Creates a new instance of HttpClientBase.
+     *
+     * @param backend The backend instance to use for requests.
+     * @protected
+     */
     constructor(backend) {
         Object.defineProperty(this, kBackend, {
             enumerable: false,
             value: backend,
         });
     }
+    /**
+     * Gets the base service URL.
+     */
     get serviceUrl() {
         return this[kBackend].serviceUrl;
     }
+    /**
+     * Fetches the API document from the service.
+     *
+     * @param options Fetch options.
+     * @returns A promise that resolves to an ApiDocument.
+     * @throws {@link Error} if there is an issue fetching or parsing the document.
+     */
     async fetchDocument(options) {
         const documentMap = {};
         const getDocument = async (documentId) => {
@@ -52,8 +69,15 @@ export class HttpClientBase {
             throw e;
         });
     }
+    /**
+     * Creates a new {@link HttpRequestObservable} for a specific path.
+     *
+     * @param path The path of the request.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     request(path, options) {
-        /** Remove leading backslashes */
+        /* Remove leading backslashes */
         path = SPLIT_BACKSLASH_PATTERN.exec(path)?.[2] || '';
         const observable = new HttpRequestObservable(this[kBackend], {
             ...options,
@@ -64,18 +88,40 @@ export class HttpClientBase {
             observable.param(options.params);
         return observable;
     }
+    /**
+     * Sends a DELETE request.
+     *
+     * @param path The path of the request.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     delete(path, options) {
         return this.request(path, {
             ...options,
             method: 'DELETE',
         });
     }
+    /**
+     * Sends a GET request.
+     *
+     * @param path The path of the request.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     get(path, options) {
         return this.request(path, {
             ...options,
             method: 'GET',
         });
     }
+    /**
+     * Sends a PATCH request.
+     *
+     * @param path The path of the request.
+     * @param requestBody The request body.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     patch(path, requestBody, options) {
         return this.request(path, {
             ...options,
@@ -83,6 +129,14 @@ export class HttpClientBase {
             body: requestBody,
         });
     }
+    /**
+     * Sends a POST request.
+     *
+     * @param path The path of the request.
+     * @param requestBody The request body.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     post(path, requestBody, options) {
         return this.request(path, {
             ...options,
@@ -90,6 +144,14 @@ export class HttpClientBase {
             body: requestBody,
         });
     }
+    /**
+     * Sends a PUT request.
+     *
+     * @param path The path of the request.
+     * @param requestBody The request body.
+     * @param options Request options.
+     * @returns A new HttpRequestObservable instance.
+     */
     put(path, requestBody, options) {
         return this.request(path, {
             ...options,

package/http/http-client.d.ts

@@ -2,11 +2,21 @@ import { kBackend } from '../constants.js';
 import { FetchBackend } from './fetch-backend.js';
 import { HttpClientBase } from './http-client-base.js';
 /**
+ * Default implementation of {@link HttpClientBase} using {@link FetchBackend}.
  *
  * @class OpraHttpClient
  */
 export declare class OpraHttpClient extends HttpClientBase<FetchBackend.RequestOptions> {
     [kBackend]: FetchBackend;
+    /**
+     * Creates a new instance of OpraHttpClient.
+     *
+     * @param serviceUrl The base URL of the service.
+     * @param options Configuration options.
+     */
     constructor(serviceUrl: string, options?: FetchBackend.Options);
+    /**
+     * Gets the default request options from the backend.
+     */
     get defaults(): FetchBackend.RequestDefaults;
 }

package/http/http-client.js

@@ -2,13 +2,23 @@ import { kBackend } from '../constants.js';
 import { FetchBackend } from './fetch-backend.js';
 import { HttpClientBase } from './http-client-base.js';
 /**
+ * Default implementation of {@link HttpClientBase} using {@link FetchBackend}.
  *
  * @class OpraHttpClient
  */
 export class OpraHttpClient extends HttpClientBase {
+    /**
+     * Creates a new instance of OpraHttpClient.
+     *
+     * @param serviceUrl The base URL of the service.
+     * @param options Configuration options.
+     */
     constructor(serviceUrl, options) {
         super(new FetchBackend(serviceUrl, options));
     }
+    /**
+     * Gets the default request options from the backend.
+     */
     get defaults() {
         return this[kBackend].defaults;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/client",
-  "version": "1.26.3",
+  "version": "1.27.0",
   "description": "Opra Client package",
   "author": "Panates",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.3",
+    "@opra/common": "^1.27.0",
     "rxjs": "^7.0.0 || ^8.0.0"
   },
   "type": "module",