easy-currencies 1.10.2 → 2.1.0

package/dist/converter.d.ts

@@ -1,6 +1,8 @@
+import { RetryOptions } from "./parts/requester";
 import { Provider, ProviderReference } from "./parts/providers";
-import { Config, ProxyConfiguration } from "./parts/config";
+import { Config } from "./parts/config";
 export { Chainer as Convert } from "./parts/chainer";
+import { HttpClient } from "./parts/client";
 /**
  * A simple map object for rates
  *
@@ -18,6 +20,17 @@ export interface rateObject {
  * as before.
  */
 export declare const RATES_BASE: unique symbol;
+/**
+ * The enumerable twin of `RATES_BASE`.
+ *
+ * A symbol is invisible to `JSON.stringify`, spread, `Object.assign` and
+ * `structuredClone`, so a table that has been through a cache loses the marker
+ * and a conversion against the wrong base is then accepted silently. That is
+ * the caching workflow this guard exists for, so the base also travels as an
+ * ordinary key. Underscores are not valid in a currency code, see
+ * `CURRENCY_CODE`, so this can never collide with a rate.
+ */
+export declare const RATES_BASE_KEY = "__base";
 /**
  * Regular converter class definition.
  *
@@ -32,6 +45,30 @@ export declare class Converter {
      * @memberof Converter
      */
     config: Config;
+    /**
+     * Called with each handled provider error before the next provider is tried.
+     *
+     * A library does not own the consumer's stderr, so this is the single point
+     * where that reporting happens. It defaults to the previous behaviour;
+     * assign your own to route the errors elsewhere, or assign a no-op to
+     * silence them entirely.
+     *
+     * @example
+     * const converter = new Converter();
+     * converter.onError = () => {};                 // silence
+     * converter.onError = (e) => logger.warn(e);    // or route
+     *
+     * @memberof Converter
+     */
+    onError: (error: unknown) => void;
+    /**
+     * Reports a provider failure without letting the report become the failure.
+     *
+     * `onError` is consumer code, and the default is `console.error`, which
+     * throws on a closed stdout: a CLI piped into `head` would abort the whole
+     * chain on EPIPE and never reach the healthy provider behind it.
+     */
+    private report;
     /**
      * Creates an instance of Converter.
      * @param {(...ProviderReference[] | undefined[] | string[])} config
@@ -48,15 +85,43 @@ export declare class Converter {
     get providers(): Provider[];
     get active(): Provider[];
     add: Config["add"];
-    addProvider: Config["add"];
     addMultiple: Config["addMultiple"];
-    addMultipleProviders: Config["addMultiple"];
     remove: Config["remove"];
     /**
-     * Method to set the proxy configuration.
-     * @param proxyConfiguration  The proxy configuration.
+     * Replaces the HTTP client.
+     *
+     * The default client uses the global fetch, which has no proxy option, so
+     * proxying (or a custom agent, or instrumentation) means supplying your own.
+     *
+     * @example
+     * import { ProxyAgent } from "undici";
+     * const dispatcher = new ProxyAgent("http://proxy:8080");
+     * converter.setClient({
+     *   get: (url) =>
+     *     fetch(url, { dispatcher } as any).then(async (r) => ({
+     *       status: r.status,
+     *       data: await r.json()
+     *     }))
+     * });
+     *
+     * @param {HttpClient} client - the client to use
      */
-    setProxyConfiguration: (proxyConfiguration: ProxyConfiguration) => void;
+    setClient: (client: HttpClient) => void;
+    /**
+     * Tunes retries and the time a conversion may take.
+     *
+     * `budgetMs` is wall clock for the whole call, spent across every provider
+     * rather than reset for each one, and it covers the requests themselves: a
+     * client that never settles cannot hold a conversion open past it. Fields
+     * merge, so one can be set without restating the rest.
+     *
+     * @example
+     * converter.setRetryOptions({ budgetMs: 5000 });   // an HTTP handler
+     * converter.setRetryOptions({ maxRetries: 0 });    // never retry a 429
+     *
+     * @param {RetryOptions} options - the tuning to apply
+     */
+    setRetryOptions: (options: RetryOptions) => void;
     /**
      * Conversion function (non chainable).
      *
@@ -69,23 +134,35 @@ export declare class Converter {
      * @param {string} from - base currency
      * @param {string} to - conversion currency
      * @param {any} rates - conversion rates, if they were pre-fetched
+     * @throws {Error} - if the amount is not finite, or a currency is missing
      * @returns {Promise<number>} - converted amount
      */
     convert: (amount: number, from: string, to: string, rates?: any) => Promise<number>;
     /**
      * Performs safe multiplication to get the result amount.
+     *
+     * A usable rate is finite and greater than zero; anything else multiplies
+     * into a plausible-looking wrong amount.
+     *
      * @param {number} amount - amount to be converted
      * @param {string} to - conversion currency
      * @param {any} rates - conversion rates, if they were pre-fetched
-     * @returns
+     * @throws {Error} - if the amount, the currency, the rates or the rate is invalid
+     * @returns {number} - converted amount
      */
     convertRate: (amount: number, to: string, rates?: any) => number;
     /**
-     * Rate fetch function
+     * Rate fetch function.
+     *
+     * Walks a snapshot of the chain, so concurrent calls do not shrink each
+     * other's list. A failure applies to the call, not the chain: no provider is
+     * removed, so one unknown currency cannot degrade a long-lived converter.
+     *
      * @param {string} from - base currency
      * @param {string} to - conversion currency
      * @param {boolean} multiple - determines conversion mode
-     * @returns
+     * @throws {Error} - if a currency is missing, or every provider failed
+     * @returns {Promise<rateObject>} - the fetched rates
      */
     getRates: (from: string, to: string, multiple?: boolean) => Promise<rateObject>;
 }