@eulerxyz/euler-v2-sdk 0.2.3-beta → 0.2.4-beta

package/dist/src/utils/fallbackAdapter.d.ts

@@ -0,0 +1,69 @@
+import { type DataIssue, type ServiceResult } from "./entityDiagnostics.js";
+/**
+ * Why the fallback fired. Useful for telemetry: per-entity warnings
+ * (`array-missing-slots`) look different from total-failures (`primary-threw`,
+ * `result-undefined`) even though both surface as a fallback event.
+ */
+export type FallbackTrigger = "primary-threw" | "result-undefined" | "array-missing-slots" | "custom-shouldFallback" | "circuit-open";
+export interface FallbackInfo<TKey extends string = string> {
+    method: TKey;
+    args: unknown[];
+    primaryName: string;
+    secondaryName: string;
+    /** Discriminator for what actually caused the fallback. */
+    trigger: FallbackTrigger;
+    /** Error thrown by primary, if it threw. Undefined when fallback was triggered by a result code. */
+    primaryError?: unknown;
+    /** Issues from a primary `ServiceResult`, if any. Undefined when primary threw or circuit was open. */
+    primaryIssues?: DataIssue[];
+    /**
+     * For `trigger === "array-missing-slots"`: indices in the primary result array
+     * that were `undefined`. Lets callers see which inputs the primary dropped.
+     */
+    missingIndices?: number[];
+}
+export interface FallbackAdapterOptions<TKey extends string> {
+    /** Method names on the adapter that should be wrapped with fallback logic. */
+    methods: readonly TKey[];
+    /**
+     * Override the default failure-detection logic for `ServiceResult` returns.
+     * Default: fall back when `result === undefined`, or when `result` is an array
+     * containing any `undefined` slot. Per-item warnings (e.g. SOURCE_UNAVAILABLE
+     * on a nested entity) on an otherwise complete response do NOT trigger fallback.
+     */
+    shouldFallback?: (primary: ServiceResult<unknown>) => boolean;
+    /** Names attached to FALLBACK_USED diagnostics for traceability. */
+    adapterNames: {
+        primary: string;
+        secondary: string;
+    };
+    /**
+     * Open a circuit after N consecutive primary failures; skip primary for `cooldownMs`.
+     * Optional — defaults to no breaker (predictable, no surprise behavior).
+     */
+    circuitBreaker?: {
+        failures: number;
+        cooldownMs: number;
+    };
+    /**
+     * Optional callback invoked after the secondary call completes (or fails to complete).
+     * Useful for telemetry / surfacing fallback events to UI. Exceptions thrown by this
+     * callback are caught and ignored so they don't disrupt the data flow.
+     */
+    onFallback?: (info: FallbackInfo<TKey>) => void;
+}
+/**
+ * Wraps two adapters of the same interface with primary→secondary fallback.
+ *
+ * For each method in `options.methods`, runs `primary`. Fallback to `secondary`
+ * fires when the primary throws, or (for `ServiceResult` returns) when `result`
+ * is `undefined`, or when `result` is an array containing any `undefined` slot.
+ * Per-item warnings on a fully-populated response do NOT trigger fallback —
+ * the secondary can't recover information the primary already returned. Pass
+ * `shouldFallback` to override.
+ *
+ * Methods NOT in `options.methods` pass through to `primary` unchanged — this keeps
+ * setters (`setConfig`, `setPlugins`, etc.) and internal state on the primary instance.
+ */
+export declare function createFallbackAdapter<T extends object, TKey extends keyof T & string>(primary: T, secondary: T, options: FallbackAdapterOptions<TKey>): T;
+//# sourceMappingURL=fallbackAdapter.d.ts.map

package/dist/src/utils/fallbackAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallbackAdapter.d.ts","sourceRoot":"","sources":["../../../src/utils/fallbackAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EACd,KAAK,aAAa,EAGlB,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACxB,eAAe,GACf,kBAAkB,GAClB,qBAAqB,GACrB,uBAAuB,GACvB,cAAc,CAAC;AAElB,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACzD,MAAM,EAAE,IAAI,CAAC;IACb,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,OAAO,EAAE,eAAe,CAAC;IACzB,oGAAoG;IACpG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uGAAuG;IACvG,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB,CAAC,IAAI,SAAS,MAAM;IAC1D,8EAA8E;IAC9E,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;IAC9D,oEAAoE;IACpE,YAAY,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD;;;OAGG;IACH,cAAc,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;CAChD;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACpC,CAAC,SAAS,MAAM,EAChB,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,EAC5B,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAsJpE"}

package/dist/src/utils/fallbackAdapter.js

@@ -0,0 +1,139 @@
+import { dataIssueLocation, serviceDiagnosticOwner, } from "./entityDiagnostics.js";
+function isServiceResult(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        "result" in value &&
+        "errors" in value &&
+        Array.isArray(value.errors));
+}
+/**
+ * Wraps two adapters of the same interface with primary→secondary fallback.
+ *
+ * For each method in `options.methods`, runs `primary`. Fallback to `secondary`
+ * fires when the primary throws, or (for `ServiceResult` returns) when `result`
+ * is `undefined`, or when `result` is an array containing any `undefined` slot.
+ * Per-item warnings on a fully-populated response do NOT trigger fallback —
+ * the secondary can't recover information the primary already returned. Pass
+ * `shouldFallback` to override.
+ *
+ * Methods NOT in `options.methods` pass through to `primary` unchanged — this keeps
+ * setters (`setConfig`, `setPlugins`, etc.) and internal state on the primary instance.
+ */
+export function createFallbackAdapter(primary, secondary, options) {
+    const wrappedMethods = new Set(options.methods);
+    const names = options.adapterNames;
+    const breaker = options.circuitBreaker;
+    let consecutiveFailures = 0;
+    let circuitOpenUntil = 0;
+    const evaluateResultTrigger = (primaryResult) => {
+        if (options.shouldFallback) {
+            return options.shouldFallback(primaryResult)
+                ? { trigger: "custom-shouldFallback" }
+                : undefined;
+        }
+        if (primaryResult.result === undefined)
+            return { trigger: "result-undefined" };
+        if (Array.isArray(primaryResult.result)) {
+            const missingIndices = [];
+            for (let i = 0; i < primaryResult.result.length; i += 1) {
+                if (primaryResult.result[i] === undefined)
+                    missingIndices.push(i);
+            }
+            if (missingIndices.length > 0) {
+                return { trigger: "array-missing-slots", missingIndices };
+            }
+        }
+        return undefined;
+    };
+    const makeFallbackIssue = (methodName, primaryError, primaryErrorsFromResult) => ({
+        code: "FALLBACK_USED",
+        severity: "info",
+        message: `Fell back from ${names.primary} to ${names.secondary} for ${methodName}.`,
+        locations: [
+            dataIssueLocation(serviceDiagnosticOwner(names.primary, undefined, methodName)),
+        ],
+        source: names.primary,
+        originalValue: primaryError !== undefined
+            ? primaryError instanceof Error
+                ? primaryError.message
+                : String(primaryError)
+            : primaryErrorsFromResult,
+    });
+    return new Proxy(primary, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function" ||
+                typeof prop !== "string" ||
+                !wrappedMethods.has(prop)) {
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+            return async (...args) => {
+                const now = Date.now();
+                const circuitOpen = breaker !== undefined && now < circuitOpenUntil;
+                let primaryResult;
+                let primaryThrow;
+                if (!circuitOpen) {
+                    try {
+                        const out = await value.apply(target, args);
+                        if (!isServiceResult(out)) {
+                            consecutiveFailures = 0;
+                            return out;
+                        }
+                        primaryResult = out;
+                    }
+                    catch (err) {
+                        primaryThrow = err;
+                    }
+                }
+                let resultTrigger;
+                if (primaryResult !== undefined) {
+                    resultTrigger = evaluateResultTrigger(primaryResult);
+                }
+                const needsFallback = circuitOpen || primaryThrow !== undefined || resultTrigger !== undefined;
+                if (!needsFallback) {
+                    consecutiveFailures = 0;
+                    return primaryResult;
+                }
+                if (breaker !== undefined && !circuitOpen) {
+                    consecutiveFailures += 1;
+                    if (consecutiveFailures >= breaker.failures) {
+                        circuitOpenUntil = now + breaker.cooldownMs;
+                        consecutiveFailures = 0;
+                    }
+                }
+                const secondaryFn = Reflect.get(secondary, prop);
+                const secondaryOut = await secondaryFn.apply(secondary, args);
+                if (options.onFallback) {
+                    const trigger = circuitOpen
+                        ? "circuit-open"
+                        : primaryThrow !== undefined
+                            ? "primary-threw"
+                            : (resultTrigger?.trigger ?? "result-undefined");
+                    try {
+                        options.onFallback({
+                            method: prop,
+                            args,
+                            primaryName: names.primary,
+                            secondaryName: names.secondary,
+                            trigger,
+                            primaryError: primaryThrow,
+                            primaryIssues: primaryResult?.errors,
+                            missingIndices: resultTrigger?.missingIndices,
+                        });
+                    }
+                    catch {
+                        // swallow — telemetry must never break the data flow.
+                    }
+                }
+                if (!isServiceResult(secondaryOut))
+                    return secondaryOut;
+                const fallbackIssue = makeFallbackIssue(prop, primaryThrow, primaryResult?.errors);
+                return {
+                    result: secondaryOut.result,
+                    errors: [fallbackIssue, ...secondaryOut.errors],
+                };
+            };
+        },
+    });
+}
+//# sourceMappingURL=fallbackAdapter.js.map

package/dist/src/utils/fallbackAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallbackAdapter.js","sourceRoot":"","sources":["../../../src/utils/fallbackAdapter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eulerxyz/euler-v2-sdk",
-  "version": "0.2.3-beta",
+  "version": "0.2.4-beta",
   "description": "SDK for interacting with Euler V2 Lending Platform",
   "repository": {
     "type": "git",