@ar.io/wayfinder-core 1.0.1-alpha.1 → 1.0.1

package/dist/gateways/local-storage-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { GatewaysProvider } from '@ar.io/wayfinder-core';
+import type { Logger } from '../types.js';
+export declare class LocalStorageGatewaysProvider implements GatewaysProvider {
+    private readonly storageKey;
+    private readonly defaultTtlSeconds;
+    private readonly gatewaysProvider;
+    private readonly ttlSeconds;
+    private readonly logger;
+    constructor({ ttlSeconds, gatewaysProvider, logger, }: {
+        ttlSeconds?: number;
+        gatewaysProvider: GatewaysProvider;
+        logger?: Logger;
+    });
+    getGateways(): Promise<URL[]>;
+    private getCachedGateways;
+    private isCacheValid;
+    private cacheGateways;
+    clearCache(): void;
+}
+//# sourceMappingURL=local-storage-cache.d.ts.map

package/dist/gateways/local-storage-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage-cache.d.ts","sourceRoot":"","sources":["../../src/gateways/local-storage-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA+B1C,qBAAa,4BAA6B,YAAW,gBAAgB;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EACV,UAAmC,EACnC,gBAAgB,EAChB,MAAsB,GACvB,EAAE;QACD,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAaK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAmBnC,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,aAAa;IAmBrB,UAAU,IAAI,IAAI;CAWnB"}

package/dist/gateways/local-storage-cache.js

@@ -0,0 +1,83 @@
+import { defaultLogger } from '../logger.js';
+import { isBrowser } from '../utils/browser.js';
+export class LocalStorageGatewaysProvider {
+    storageKey = 'wayfinder-gateways-cache';
+    defaultTtlSeconds = 3600; // 1 hour default
+    gatewaysProvider;
+    ttlSeconds;
+    logger;
+    constructor({ ttlSeconds = this.defaultTtlSeconds, gatewaysProvider, logger = defaultLogger, }) {
+        if (!isBrowser()) {
+            throw new Error('LocalStorageGatewaysProvider is only available in browser environments. Consider using SimpleCacheGatewaysProvider for node.js environments.');
+        }
+        this.gatewaysProvider = gatewaysProvider;
+        this.ttlSeconds = ttlSeconds;
+        this.gatewaysProvider = gatewaysProvider;
+        this.logger = logger;
+    }
+    async getGateways() {
+        const cached = this.getCachedGateways();
+        if (cached && this.isCacheValid(cached)) {
+            this.logger?.debug('Using cached gateways', {
+                ttlSeconds: this.ttlSeconds,
+                timestamp: cached.timestamp,
+                expiresAt: cached.expiresAt,
+                gateways: cached.gateways.length,
+            });
+            return cached.gateways.map((gateway) => new URL(gateway));
+        }
+        const gateways = await this.gatewaysProvider.getGateways();
+        this.cacheGateways(gateways);
+        return gateways;
+    }
+    getCachedGateways() {
+        try {
+            if (typeof window === 'undefined' || !window.localStorage) {
+                return undefined;
+            }
+            const cached = window.localStorage.getItem(this.storageKey);
+            if (!cached) {
+                return undefined;
+            }
+            return JSON.parse(cached);
+        }
+        catch (error) {
+            this.logger?.warn('Failed to retrieve cached gateways:', error);
+            return undefined;
+        }
+    }
+    isCacheValid(cached) {
+        const now = Date.now();
+        const expiresAt = cached.timestamp + cached.ttlSeconds * 1000;
+        const gatewaysCount = cached.gateways.length;
+        return now < expiresAt && gatewaysCount > 0;
+    }
+    cacheGateways(gateways) {
+        try {
+            if (typeof window === 'undefined' || !window.localStorage) {
+                return;
+            }
+            const cached = {
+                gateways: gateways.map((gateway) => gateway.toString()),
+                timestamp: Date.now(),
+                expiresAt: Date.now() + this.ttlSeconds * 1000,
+                ttlSeconds: this.ttlSeconds,
+            };
+            window.localStorage.setItem(this.storageKey, JSON.stringify(cached));
+        }
+        catch (error) {
+            this.logger?.warn('Failed to cache gateways:', error);
+        }
+    }
+    clearCache() {
+        try {
+            if (typeof window === 'undefined' || !window.localStorage) {
+                return;
+            }
+            window.localStorage.removeItem(this.storageKey);
+        }
+        catch (error) {
+            this.logger?.warn('Failed to clear gateway cache:', error);
+        }
+    }
+}

package/dist/gateways/simple-cache.d.ts

@@ -1,28 +1,35 @@
+import type { GatewaysProvider, Logger } from '../types.js';
 /**
- * WayFinder
- * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ * Simple in-memory cache provider for gateways that fetches gateways from a
+ * GatewaysProvider and caches them for a given number of seconds. Ideal for
+ * node.js environments where you want to cache gateways for a given number of
+ * seconds and avoid rate limiting. If you are in a browser environment,
+ * consider using LocalStorageGatewaysProvider instead.
+ *
+ * ```ts
+ * import { NetworkGatewaysProvider, SimpleCacheGatewaysProvider } from '@ar.io/wayfinder-core';
  *
- * 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
+ * // Create your network provider (fetches gateways from the network)
+ * const networkProvider = new NetworkGatewaysProvider({ ... });
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * // Wrap with SimpleCacheGatewaysProvider for caching
+ * const cachedProvider = new SimpleCacheGatewaysProvider({
+ *   gatewaysProvider: networkProvider,
+ *   ttlSeconds: 3600, // cache for 1 hour
+ * });
  *
- * 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.
+ * // Use cachedProvider to get gateways
+ * const gateways = await cachedProvider.getGateways();
+ * ```
  */
-import type { GatewaysProvider, Logger } from '../types.js';
 export declare class SimpleCacheGatewaysProvider implements GatewaysProvider {
     private gatewaysProvider;
+    private defaultTtlSeconds;
     private ttlSeconds;
-    private lastUpdated;
+    private expiresAt;
     private gatewaysCache;
     private logger;
-    constructor({ gatewaysProvider, ttlSeconds, // 1 hour
-    logger, }: {
+    constructor({ gatewaysProvider, ttlSeconds, logger, }: {
         gatewaysProvider: GatewaysProvider;
         ttlSeconds?: number;
         logger?: Logger;
@@ -31,5 +38,6 @@ export declare class SimpleCacheGatewaysProvider implements GatewaysProvider {
         path?: string;
         subdomain?: string;
     }): Promise<URL[]>;
+    private isCacheValid;
 }
 //# sourceMappingURL=simple-cache.d.ts.map

package/dist/gateways/simple-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simple-cache.d.ts","sourceRoot":"","sources":["../../src/gateways/simple-cache.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5D,qBAAa,2BAA4B,YAAW,gBAAgB;IAClE,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,gBAAgB,EAChB,UAAoB,EAAE,SAAS;IAC/B,MAAsB,GACvB,EAAE;QACD,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAQK,WAAW,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CACxE,GAAG,EAAE,CACN;CAmCF"}
+{"version":3,"file":"simple-cache.d.ts","sourceRoot":"","sources":["../../src/gateways/simple-cache.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;IAClE,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,gBAAgB,EAChB,UAAmC,EACnC,MAAsB,GACvB,EAAE;QACD,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAQK,WAAW,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CACxE,GAAG,EAAE,CACN;IAgCD,OAAO,CAAC,YAAY;CAGrB"}

package/dist/gateways/simple-cache.js

@@ -15,33 +15,54 @@
  * limitations under the License.
  */
 import { defaultLogger } from '../logger.js';
+/**
+ * Simple in-memory cache provider for gateways that fetches gateways from a
+ * GatewaysProvider and caches them for a given number of seconds. Ideal for
+ * node.js environments where you want to cache gateways for a given number of
+ * seconds and avoid rate limiting. If you are in a browser environment,
+ * consider using LocalStorageGatewaysProvider instead.
+ *
+ * ```ts
+ * import { NetworkGatewaysProvider, SimpleCacheGatewaysProvider } from '@ar.io/wayfinder-core';
+ *
+ * // Create your network provider (fetches gateways from the network)
+ * const networkProvider = new NetworkGatewaysProvider({ ... });
+ *
+ * // Wrap with SimpleCacheGatewaysProvider for caching
+ * const cachedProvider = new SimpleCacheGatewaysProvider({
+ *   gatewaysProvider: networkProvider,
+ *   ttlSeconds: 3600, // cache for 1 hour
+ * });
+ *
+ * // Use cachedProvider to get gateways
+ * const gateways = await cachedProvider.getGateways();
+ * ```
+ */
 export class SimpleCacheGatewaysProvider {
     gatewaysProvider;
+    defaultTtlSeconds = 3600; // 1 hour default
     ttlSeconds;
-    lastUpdated;
+    expiresAt;
     gatewaysCache;
     logger;
-    constructor({ gatewaysProvider, ttlSeconds = 60 * 60, // 1 hour
-    logger = defaultLogger, }) {
+    constructor({ gatewaysProvider, ttlSeconds = this.defaultTtlSeconds, logger = defaultLogger, }) {
         this.gatewaysCache = [];
         this.gatewaysProvider = gatewaysProvider;
         this.ttlSeconds = ttlSeconds;
-        this.lastUpdated = 0;
+        this.expiresAt = 0;
         this.logger = logger;
     }
     async getGateways(params) {
-        const now = Date.now();
-        if (this.gatewaysCache.length === 0 ||
-            now - this.lastUpdated > this.ttlSeconds * 1000) {
+        if (this.isCacheValid()) {
             try {
                 this.logger.debug('Cache expired, fetching new gateways', {
-                    cacheAge: now - this.lastUpdated,
+                    expiresAt: this.expiresAt,
                     ttlSeconds: this.ttlSeconds,
                 });
                 // preserve the cache if the fetch fails
                 const allGateways = await this.gatewaysProvider.getGateways(params);
                 this.gatewaysCache = allGateways;
-                this.lastUpdated = now;
+                this.expiresAt = Date.now() + this.ttlSeconds * 1000;
                 this.logger.debug('Updated gateways cache', {
                     gatewayCount: allGateways.length,
                 });
@@ -55,11 +76,14 @@ export class SimpleCacheGatewaysProvider {
         }
         else {
             this.logger.debug('Using cached gateways', {
-                cacheAge: now - this.lastUpdated,
+                expiresAt: this.expiresAt,
                 ttlSeconds: this.ttlSeconds,
                 gatewayCount: this.gatewaysCache.length,
             });
         }
         return this.gatewaysCache;
     }
+    isCacheValid() {
+        return Date.now() < this.expiresAt && this.gatewaysCache.length > 0;
+    }
 }

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export * from './routing/simple-cache.js';
 export * from './gateways/network.js';
 export * from './gateways/simple-cache.js';
 export * from './gateways/static.js';
+export * from './gateways/local-storage-cache.js';
 export * from './verification/data-root-verifier.js';
 export * from './verification/hash-verifier.js';
 export * from './verification/signature-verifier.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;AAG1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AAGrC,cAAc,sCAAsC,CAAC;AACrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,cAAc,CAAC;AAG7B,cAAc,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;AAG1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAGlD,cAAc,sCAAsC,CAAC;AACrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -27,6 +27,7 @@ export * from './routing/simple-cache.js';
 export * from './gateways/network.js';
 export * from './gateways/simple-cache.js';
 export * from './gateways/static.js';
+export * from './gateways/local-storage-cache.js';
 // verification strategies
 export * from './verification/data-root-verifier.js';
 export * from './verification/hash-verifier.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.0.1-alpha.1";
+export declare const WAYFINDER_CORE_VERSION = "v1.0.1-alpha.2";
 //# 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.0.1-alpha.1';
+export const WAYFINDER_CORE_VERSION = 'v1.0.1-alpha.2';

package/package.json

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