@gearbox-protocol/sdk 14.12.0-next.82 → 14.12.0-next.83

package/dist/cjs/new-sdk/utils/filterResponse.js

@@ -1,14 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/new-sdk/utils/filterResponse.ts
-/**
-* Narrows an already-read list, rows and metadata alike. `undefined` passes
-* through, so a read still in flight stays that way.
-*
-* @typeParam T - Row type.
-* @typeParam F - Filter type.
-* @param matches - Whether one row satisfies the filter, e.g.
-*   `matchesOpportunityFilter`.
-**/
 function filterResponse(response, filter, matches) {
 	if (!response) return;
 	const chainIds = filter?.chainIds;

package/dist/cjs/new-sdk/utils/mergeChains.js

@@ -6,11 +6,6 @@ require("../errors/index.js");
 * How many seconds the backend may lag the chain and still be used.
 **/
 const DEFAULT_MAX_OFFCHAIN_LAG = 120;
-/**
-* Merges two lists chain by chain: a chain is served by the backend when it is
-* within `maxLagSeconds` of the chain, by the chain otherwise, and reported as
-* an error when neither source succeeded.
-**/
 function mergeChainList(onchain, offchain, maxLagSeconds = 120) {
 	if (!onchain && !offchain) return;
 	const fromOnchain = /* @__PURE__ */ new Map();

package/dist/esm/new-sdk/utils/filterResponse.js

@@ -1,13 +1,4 @@
 //#region src/new-sdk/utils/filterResponse.ts
-/**
-* Narrows an already-read list, rows and metadata alike. `undefined` passes
-* through, so a read still in flight stays that way.
-*
-* @typeParam T - Row type.
-* @typeParam F - Filter type.
-* @param matches - Whether one row satisfies the filter, e.g.
-*   `matchesOpportunityFilter`.
-**/
 function filterResponse(response, filter, matches) {
 	if (!response) return;
 	const chainIds = filter?.chainIds;

package/dist/esm/new-sdk/utils/mergeChains.js

@@ -5,11 +5,6 @@ import "../errors/index.js";
 * How many seconds the backend may lag the chain and still be used.
 **/
 const DEFAULT_MAX_OFFCHAIN_LAG = 120;
-/**
-* Merges two lists chain by chain: a chain is served by the backend when it is
-* within `maxLagSeconds` of the chain, by the chain otherwise, and reported as
-* an error when neither source succeeded.
-**/
 function mergeChainList(onchain, offchain, maxLagSeconds = 120) {
 	if (!onchain && !offchain) return;
 	const fromOnchain = /* @__PURE__ */ new Map();

package/dist/types/new-sdk/AbstractNamespace.d.ts

@@ -2,7 +2,7 @@ import { ILogger } from "../sdk/types/logger.js";
 import { DataResponse } from "../model/response.js";
 import "../model/index.js";
 import { NamespaceOptions } from "./types.js";
-import { SourceMerger } from "./utils/types.js";
+import { EntityMerger, ListMerger } from "./utils/types.js";
 import "./utils/index.js";
 //#region src/new-sdk/AbstractNamespace.d.ts
 /**
@@ -16,7 +16,7 @@ import "./utils/index.js";
 interface MergedQuery<Onchain, Offchain, T> {
   fromChain: (source: Onchain) => Promise<DataResponse<T>>;
   fromBackend: (source: Offchain) => Promise<DataResponse<T>>;
-  merge: SourceMerger<T>;
+  merge: ListMerger<T> | EntityMerger<T>;
 }
 /**
  * Base class of every {@link GearboxSDK} namespace: holds the two source

package/dist/types/new-sdk/index.d.ts

@@ -1,8 +1,8 @@
 import { GearboxSDKOptions, Mode, NamespaceOptions, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, PlainMultichainSDKOptions } from "./types.js";
+import { EntityMerger, FilterResult, ListMerger, MergeListResult } from "./utils/types.js";
 import { filterResponse } from "./utils/filterResponse.js";
 import { HistoryReader } from "./utils/history.js";
 import { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne } from "./utils/mergeChains.js";
-import { SourceMerger } from "./utils/types.js";
 import "./utils/index.js";
 import { AbstractNamespace, MergedQuery } from "./AbstractNamespace.js";
 import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers } from "./opportunities/types.js";
@@ -20,4 +20,4 @@ import { SourceUnavailableError } from "./errors/SourceUnavailableError.js";
 import { assertSameChains } from "./errors/assertSameChains.js";
 import { everyChainFailed } from "./errors/everyChainFailed.js";
 import "./errors/index.js";
-export { AbstractNamespace, AllSourcesFailedError, ChainRef, DEFAULT_MAX_OFFCHAIN_LAG, GearboxSDK, GearboxSDKOptions, HistoryReader, MergedQuery, MissingSourceError, Mode, NamespaceOptions, NoSourceServedError, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesNamespace, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers, PlainMultichainSDKOptions, PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsNamespace, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly, SourceChainMismatchError, type SourceMerger, SourceUnavailableError, assertSameChains, everyChainFailed, filterResponse, mergeChainList, mergeChainOne };
+export { AbstractNamespace, AllSourcesFailedError, ChainRef, DEFAULT_MAX_OFFCHAIN_LAG, type EntityMerger, type FilterResult, GearboxSDK, GearboxSDKOptions, HistoryReader, type ListMerger, type MergeListResult, MergedQuery, MissingSourceError, Mode, NamespaceOptions, NoSourceServedError, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesNamespace, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers, PlainMultichainSDKOptions, PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsNamespace, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly, SourceChainMismatchError, SourceUnavailableError, assertSameChains, everyChainFailed, filterResponse, mergeChainList, mergeChainOne };

package/dist/types/new-sdk/opportunities/OpportunitiesNamespace.d.ts

@@ -7,6 +7,7 @@ import "../../sdk/index.js";
 import { GearboxAPI } from "../../offchain/GearboxAPI.js";
 import "../../offchain/index.js";
 import { NamespaceOptions } from "../types.js";
+import { FilterResult } from "../utils/types.js";
 import { HistoryReader } from "../utils/history.js";
 import "../utils/index.js";
 import { AbstractNamespace } from "../AbstractNamespace.js";
@@ -37,7 +38,7 @@ declare class OpportunitiesNamespace extends AbstractNamespace<MultichainSDK["op
   /**
    * {@inheritDoc OpportunitiesBase.filter}
    **/
-  filter(response: DataResponse<Opportunity[]> | undefined, filter?: OpportunityFilter): DataResponse<Opportunity[]> | undefined;
+  filter<R extends DataResponse<Opportunity[]> | undefined>(response: R, filter?: OpportunityFilter): FilterResult<R, Opportunity>;
   /**
    * {@inheritDoc OpportunitiesOffchainOnly.history}
    **/

package/dist/types/new-sdk/opportunities/types.d.ts

@@ -7,8 +7,8 @@ import "../../sdk/index.js";
 import { OffchainOpportunities } from "../../offchain/opportunities/OffchainOpportunities.js";
 import "../../offchain/index.js";
 import { Mode } from "../types.js";
+import { EntityMerger, FilterResult, ListMerger } from "../utils/types.js";
 import { HistoryReader } from "../utils/history.js";
-import { SourceMerger } from "../utils/types.js";
 import "../utils/index.js";
 //#region src/new-sdk/opportunities/types.d.ts
 /**
@@ -31,9 +31,10 @@ interface OpportunitiesBase {
   getStrategy(key: StrategyOpportunityKey): Promise<DataResponse<StrategyOpportunityDetail>>;
   /**
    * Narrows an already-read list, rows and metadata alike. `undefined` passes
-   * through, so a read still in flight stays that way.
+   * through, so a read still in flight stays that way, and a list already read
+   * narrows to a list.
    **/
-  filter(response: DataResponse<Opportunity[]> | undefined, filter?: OpportunityFilter): DataResponse<Opportunity[]> | undefined;
+  filter<R extends DataResponse<Opportunity[]> | undefined>(response: R, filter?: OpportunityFilter): FilterResult<R, Opportunity>;
   /**
    * The chain on its own, for a consumer that shows each source as it arrives.
    * Throws in `offchain` mode.
@@ -66,15 +67,6 @@ interface OpportunitiesOffchainOnly {
  * Reads only the chain can answer. Empty for now.
  **/
 interface OpportunitiesOnchainOnly {}
-/**
- * How each read combines what the two sources returned: a chain is served by
- * the backend when it is fresh enough, and by the chain otherwise.
- **/
-interface OpportunityMergers {
-  list: SourceMerger<Opportunity[]>;
-  pool: SourceMerger<PoolOpportunityDetail>;
-  strategy: SourceMerger<StrategyOpportunityDetail>;
-}
 /**
  * Which reads the `opportunities` namespace has in each mode. A widened mode
  * offers what every mode has, i.e. {@link OpportunitiesBase} alone.
@@ -94,9 +86,9 @@ interface OpportunitiesOffchainBranch {
  * by the backend when it is fresh enough, and by the chain otherwise.
  **/
 interface OpportunityMergers {
-  list: SourceMerger<Opportunity[]>;
-  pool: SourceMerger<PoolOpportunityDetail>;
-  strategy: SourceMerger<StrategyOpportunityDetail>;
+  list: ListMerger<Opportunity[]>;
+  pool: EntityMerger<PoolOpportunityDetail>;
+  strategy: EntityMerger<StrategyOpportunityDetail>;
 }
 /**
  * Merging, which only exists where there are two sources to merge.

package/dist/types/new-sdk/positions/PositionsNamespace.d.ts

@@ -7,6 +7,7 @@ import "../../sdk/index.js";
 import { GearboxAPI } from "../../offchain/GearboxAPI.js";
 import "../../offchain/index.js";
 import { NamespaceOptions } from "../types.js";
+import { FilterResult } from "../utils/types.js";
 import { HistoryReader } from "../utils/history.js";
 import "../utils/index.js";
 import { AbstractNamespace } from "../AbstractNamespace.js";
@@ -30,7 +31,7 @@ declare class PositionsNamespace extends AbstractNamespace<MultichainSDK["positi
   /**
    * {@inheritDoc PositionsBase.filter}
    **/
-  filter(response: DataResponse<Position[]> | undefined, filter?: PositionFilter): DataResponse<Position[]> | undefined;
+  filter<R extends DataResponse<Position[]> | undefined>(response: R, filter?: PositionFilter): FilterResult<R, Position>;
   /**
    * {@inheritDoc PositionsOffchainOnly.history}
    **/

package/dist/types/new-sdk/positions/types.d.ts

@@ -7,8 +7,8 @@ import "../../sdk/index.js";
 import { OffchainPositions } from "../../offchain/positions/OffchainPositions.js";
 import "../../offchain/index.js";
 import { Mode } from "../types.js";
+import { FilterResult, ListMerger } from "../utils/types.js";
 import { HistoryReader } from "../utils/history.js";
-import { SourceMerger } from "../utils/types.js";
 import "../utils/index.js";
 import { Address } from "viem";
 //#region src/new-sdk/positions/types.d.ts
@@ -25,9 +25,10 @@ interface PositionsBase {
   list(wallet: Address, filter?: PositionFilter): Promise<DataResponse<Position[]>>;
   /**
    * Narrows an already-read list, rows and metadata alike. `undefined` passes
-   * through, so a read still in flight stays that way.
+   * through, so a read still in flight stays that way, and a list already read
+   * narrows to a list.
    **/
-  filter(response: DataResponse<Position[]> | undefined, filter?: PositionFilter): DataResponse<Position[]> | undefined;
+  filter<R extends DataResponse<Position[]> | undefined>(response: R, filter?: PositionFilter): FilterResult<R, Position>;
   /**
    * The chain on its own, for a consumer that shows each source as it arrives.
    * Throws in `offchain` mode.
@@ -62,13 +63,6 @@ interface PositionsOffchainOnly {
  * Reads only the chain can answer. Empty for now.
  **/
 interface PositionsOnchainOnly {}
-/**
- * How each read combines what the two sources returned: a chain is served by
- * the backend when it is fresh enough, and by the chain otherwise.
- **/
-interface PositionMergers {
-  list: SourceMerger<Position[]>;
-}
 /**
  * Which reads the `positions` namespace has in each mode. A widened mode offers
  * what every mode has, i.e. {@link PositionsBase} alone.
@@ -88,7 +82,7 @@ interface PositionsOffchainBranch {
  * by the backend when it is fresh enough, and by the chain otherwise.
  **/
 interface PositionMergers {
-  list: SourceMerger<Position[]>;
+  list: ListMerger<Position[]>;
 }
 /**
  * Merging, which only exists where there are two sources to merge.

package/dist/types/new-sdk/utils/filterResponse.d.ts

@@ -1,16 +1,19 @@
 import { ChainScopedFilter } from "../../model/filters.js";
 import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
+import { FilterResult } from "./types.js";
 //#region src/new-sdk/utils/filterResponse.d.ts
 /**
  * Narrows an already-read list, rows and metadata alike. `undefined` passes
- * through, so a read still in flight stays that way.
+ * through, so a read still in flight stays that way, and an envelope narrows to
+ * an envelope, see {@link FilterResult}.
  *
  * @typeParam T - Row type.
  * @typeParam F - Filter type.
+ * @typeParam R - What the response was given as.
  * @param matches - Whether one row satisfies the filter, e.g.
  *   `matchesOpportunityFilter`.
  **/
-declare function filterResponse<T, F extends ChainScopedFilter>(response: DataResponse<T[]> | undefined, filter: F | undefined, matches: (row: T, filter?: F) => boolean): DataResponse<T[]> | undefined;
+declare function filterResponse<T, F extends ChainScopedFilter, R extends DataResponse<T[]> | undefined>(response: R, filter: F | undefined, matches: (row: T, filter?: F) => boolean): FilterResult<R, T>;
 //#endregion
 export { filterResponse };

package/dist/types/new-sdk/utils/index.d.ts

@@ -1,5 +1,5 @@
+import { EntityMerger, FilterResult, ListMerger, MergeListResult } from "./types.js";
 import { filterResponse } from "./filterResponse.js";
 import { HistoryReader } from "./history.js";
 import { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne } from "./mergeChains.js";
-import { SourceMerger } from "./types.js";
-export { DEFAULT_MAX_OFFCHAIN_LAG, HistoryReader, type SourceMerger, filterResponse, mergeChainList, mergeChainOne };
+export { DEFAULT_MAX_OFFCHAIN_LAG, type EntityMerger, type FilterResult, HistoryReader, type ListMerger, type MergeListResult, filterResponse, mergeChainList, mergeChainOne };

package/dist/types/new-sdk/utils/mergeChains.d.ts

@@ -1,5 +1,6 @@
 import { ChainScoped, DataResponse } from "../../model/response.js";
 import "../../model/index.js";
+import { MergeListResult } from "./types.js";
 //#region src/new-sdk/utils/mergeChains.d.ts
 /**
  * How many seconds the backend may lag the chain and still be used.
@@ -8,9 +9,10 @@ declare const DEFAULT_MAX_OFFCHAIN_LAG = 120;
 /**
  * Merges two lists chain by chain: a chain is served by the backend when it is
  * within `maxLagSeconds` of the chain, by the chain otherwise, and reported as
- * an error when neither source succeeded.
+ * an error when neither source succeeded. Answers with an envelope as soon as
+ * either side has arrived, see {@link MergeListResult}.
  **/
-declare function mergeChainList<T extends ChainScoped>(onchain: DataResponse<T[]> | undefined, offchain: DataResponse<T[]> | undefined, maxLagSeconds?: number): DataResponse<T[]> | undefined;
+declare function mergeChainList<T extends ChainScoped, Onchain extends DataResponse<T[]> | undefined, Offchain extends DataResponse<T[]> | undefined>(onchain: Onchain, offchain: Offchain, maxLagSeconds?: number): MergeListResult<Onchain, Offchain, T[]>;
 /**
  * Merges two versions of one entity under the same freshness rule as
  * {@link mergeChainList}, returning the winning response whole.

package/dist/types/new-sdk/utils/types.d.ts

@@ -2,10 +2,42 @@ import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
 //#region src/new-sdk/utils/types.d.ts
 /**
- * How one read combines what the two sources returned.
+ * Whether a merge could have been given nothing at all, i.e. both sides are
+ * typed as possibly absent. One definite side already answers this `false`.
+ **/
+type BothMayBeMissing<Onchain, Offchain> = undefined extends Onchain & Offchain ? true : false;
+/**
+ * What merging two lists answers with: an envelope unless both sides could
+ * still be missing, since a list merge serves whichever side did arrive.
+ *
+ * @typeParam Onchain - What the on-chain side was given as.
+ * @typeParam Offchain - What the backend side was given as.
+ * @typeParam T - Payload type of the read.
+ **/
+type MergeListResult<Onchain, Offchain, T> = BothMayBeMissing<Onchain, Offchain> extends true ? DataResponse<T> | undefined : DataResponse<T>;
+/**
+ * What narrowing an already-read list answers with: `undefined` only where the
+ * read itself was still in flight.
+ *
+ * @typeParam R - What the response was given as.
+ * @typeParam T - Row type.
+ **/
+type FilterResult<R, T> = R extends undefined ? undefined : DataResponse<T[]>;
+/**
+ * How a list read combines what the two sources returned. A side still in
+ * flight is `undefined`; the merge answers with an envelope as soon as either
+ * one has arrived, see {@link MergeListResult}.
+ *
+ * @typeParam T - Payload type of the read.
+ **/
+type ListMerger<T> = <Onchain extends DataResponse<T> | undefined, Offchain extends DataResponse<T> | undefined>(onchain: Onchain, offchain: Offchain) => MergeListResult<Onchain, Offchain, T>;
+/**
+ * How a single-entity read combines what the two sources returned. Unlike
+ * {@link ListMerger} this stays optional whatever it was given: neither source
+ * may have served the entity, and there is nothing to answer with then.
  *
  * @typeParam T - Payload type of the read.
  **/
-type SourceMerger<T> = (onchain: DataResponse<T> | undefined, offchain: DataResponse<T> | undefined) => DataResponse<T> | undefined;
+type EntityMerger<T> = (onchain: DataResponse<T> | undefined, offchain: DataResponse<T> | undefined) => DataResponse<T> | undefined;
 //#endregion
-export { SourceMerger };
+export { EntityMerger, FilterResult, ListMerger, MergeListResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "14.12.0-next.82",
+  "version": "14.12.0-next.83",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {