@ar.io/wayfinder-core 1.8.1 → 1.9.0

package/README.md

@@ -36,11 +36,10 @@ import {
   createWayfinderClient,
   FastestPingRoutingStrategy,
   NetworkGatewaysProvider,
-  WayfinderFetchOptions,
 } from '@ar.io/wayfinder-core';
 import { ARIO } from '@ar.io/sdk';
 
-const options: WayfinderFetchOptions = {
+const wayfinder = createWayfinderClient({
   routingStrategy: new FastestPingRoutingStrategy({
     gatewaysProvider: new NetworkGatewaysProvider({
       ario: ARIO.mainnet(),
@@ -49,9 +48,7 @@ const options: WayfinderFetchOptions = {
       limit: 10,
     }),
   }),
-};
-
-const wayfinder = createWayfinderClient(options);
+});
 ```
 
 ### Enable Verification
@@ -60,17 +57,14 @@ const wayfinder = createWayfinderClient(options);
 import {
   createWayfinderClient,
   HashVerificationStrategy,
-  WayfinderFetchOptions,
 } from '@ar.io/wayfinder-core';
 
-const options: WayfinderFetchOptions = {
+const wayfinder = createWayfinderClient({
   verificationStrategy: new HashVerificationStrategy({
     trustedGateways: [new URL('https://permagate.io')],
   }),
   strict: true, // Fail requests on verification errors
-};
-
-const wayfinder = createWayfinderClient(options);
+});
 ```
 
 Wayfinder Core provides helper functions to construct routing and verification strategies:
@@ -178,6 +172,7 @@ Gateway providers supply the list of gateways for routing. **By default, `create
 | `StaticGatewaysProvider`       | Returns a static list of gateways | Testing or specific gateways |
 | `SimpleCacheGatewaysProvider`  | In-memory caching wrapper | Reduce API calls (used by default) |
 | `LocalStorageGatewaysProvider` | Browser localStorage caching | Persistent caching (used by default in browsers) |
+| `CompositeGatewaysProvider`    | Chains multiple providers with fallback | Maximum resilience with multiple sources |
 
 #### NetworkGatewaysProvider
 
@@ -208,6 +203,47 @@ const gatewayProvider = new TrustedPeersGatewaysProvider({
 });
 ```
 
+#### CompositeGatewaysProvider
+
+Chains multiple gateway providers together, trying each in sequence until one succeeds. This is useful for building resilient gateway discovery with fallbacks.
+
+**How it works:**
+
+1. Tries each provider in the order they're provided
+2. If a provider returns a non-empty list of gateways, those gateways are used
+3. If a provider throws an error or returns an empty list, moves to the next provider
+4. If all providers fail, throws an error
+
+```javascript
+import {
+  CompositeGatewaysProvider,
+  NetworkGatewaysProvider,
+  StaticGatewaysProvider,
+  TrustedPeersGatewaysProvider,
+} from '@ar.io/wayfinder-core';
+import { ARIO } from '@ar.io/sdk';
+
+// Example: Network-first with static fallback
+const gatewayProvider = new CompositeGatewaysProvider({
+  providers: [
+    // Try fetching from AR.IO network first
+    new NetworkGatewaysProvider({
+      ario: ARIO.mainnet(),
+      sortBy: 'operatorStake',
+      limit: 10,
+    }),
+    // Fallback to trusted peers if network fetch fails
+    new TrustedPeersGatewaysProvider({
+      trustedGateway: 'https://arweave.net',
+    }),
+    // Final fallback to static list
+    new StaticGatewaysProvider({
+      gateways: ['https://arweave.net', 'https://permagate.io'],
+    }),
+  ],
+});
+```
+
 ## Routing Strategies
 
 Wayfinder supports multiple routing strategies to select target gateways for your requests.

package/dist/gateways/composite.d.ts

@@ -0,0 +1,13 @@
+import type { GatewaysProvider, Logger } from '../types.js';
+export declare class CompositeGatewaysProvider implements GatewaysProvider {
+    private providers;
+    private logger;
+    constructor({ providers, logger, }?: {
+        providers?: GatewaysProvider[];
+        logger?: Logger;
+    });
+    getGateways(): Promise<URL[]>;
+    addProvider(provider: GatewaysProvider): void;
+    getProviders(): GatewaysProvider[];
+}
+//# sourceMappingURL=composite.d.ts.map

package/dist/gateways/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/gateways/composite.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5D,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,SAAc,EACd,MAAsB,GACvB,GAAE;QACD,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAQA,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IA+BnC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAI7C,YAAY,IAAI,gBAAgB,EAAE;CAGnC"}

package/dist/gateways/composite.js

@@ -0,0 +1,59 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { defaultLogger } from '../logger.js';
+export class CompositeGatewaysProvider {
+    providers;
+    logger;
+    constructor({ providers = [], logger = defaultLogger, } = {}) {
+        if (providers.length === 0) {
+            throw new Error('At least one gateways provider must be provided');
+        }
+        this.providers = providers;
+        this.logger = logger;
+    }
+    async getGateways() {
+        this.logger.debug('CompositeGatewaysProvider: starting gateway fetch', {
+            providersCount: this.providers.length,
+        });
+        for (const provider of this.providers) {
+            try {
+                this.logger.debug('CompositeGatewaysProvider: trying provider');
+                const gateways = await provider.getGateways();
+                if (gateways.length > 0) {
+                    this.logger.debug('CompositeGatewaysProvider: provider succeeded', {
+                        gatewaysCount: gateways.length,
+                    });
+                    return gateways;
+                }
+                this.logger.debug('CompositeGatewaysProvider: provider returned empty list');
+            }
+            catch (error) {
+                this.logger.debug('CompositeGatewaysProvider: provider failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        this.logger.error('CompositeGatewaysProvider: all providers failed to return gateways');
+        throw new Error('All gateways providers failed to return gateways');
+    }
+    addProvider(provider) {
+        this.providers.push(provider);
+    }
+    getProviders() {
+        return [...this.providers];
+    }
+}

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from './routing/round-robin.js';
 export * from './routing/preferred-with-fallback.js';
 export * from './routing/simple-cache.js';
 export * from './routing/composite.js';
+export * from './gateways/composite.js';
 export * from './gateways/network.js';
 export * from './gateways/simple-cache.js';
 export * from './gateways/static.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC;AACrD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AAGrC,cAAc,cAAc,CAAC;AAG7B,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC;AACrD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AAGrC,cAAc,cAAc,CAAC;AAG7B,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -25,6 +25,7 @@ export * from './routing/preferred-with-fallback.js';
 export * from './routing/simple-cache.js';
 export * from './routing/composite.js';
 // gateways providers
+export * from './gateways/composite.js';
 export * from './gateways/network.js';
 export * from './gateways/simple-cache.js';
 export * from './gateways/static.js';

package/dist/version.d.ts

@@ -14,5 +14,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const WAYFINDER_CORE_VERSION = "v1.8.1";
+export declare const WAYFINDER_CORE_VERSION = "v1.9.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -14,4 +14,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export const WAYFINDER_CORE_VERSION = 'v1.8.1';
+export const WAYFINDER_CORE_VERSION = 'v1.9.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",