@ar.io/wayfinder-react 1.0.2-alpha.2 → 1.0.2

package/dist/cache/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export * from './local-storage.js';

package/dist/cache/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export * from './local-storage.js';

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

@@ -0,0 +1,32 @@
+/**
+ * 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';
+export declare class LocalStorageGatewaysProvider implements GatewaysProvider {
+    private readonly storageKey;
+    private readonly defaultTtlSeconds;
+    private readonly gatewaysProvider;
+    private readonly ttlSeconds;
+    constructor({ ttlSeconds, gatewaysProvider, }: {
+        ttlSeconds?: number;
+        gatewaysProvider: GatewaysProvider;
+    });
+    getGateways(): Promise<URL[]>;
+    private getCachedGateways;
+    private isCacheValid;
+    private cacheGateways;
+    clearCache(): void;
+}

package/dist/cache/local-storage.js

@@ -0,0 +1,70 @@
+export class LocalStorageGatewaysProvider {
+    storageKey = 'wayfinder-gateways-cache';
+    defaultTtlSeconds = 3600; // 1 hour default
+    gatewaysProvider;
+    ttlSeconds;
+    constructor({ ttlSeconds = 300, gatewaysProvider, }) {
+        this.gatewaysProvider = gatewaysProvider;
+        this.ttlSeconds = ttlSeconds;
+        this.gatewaysProvider = gatewaysProvider;
+    }
+    async getGateways() {
+        const cached = this.getCachedGateways();
+        if (cached && this.isCacheValid(cached)) {
+            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) {
+            console.warn('Failed to retrieve cached gateways:', error);
+            return undefined;
+        }
+    }
+    isCacheValid(cached) {
+        const now = Date.now();
+        const cacheAge = now - cached.timestamp;
+        const ttlMs = (cached.ttlSeconds || this.defaultTtlSeconds) * 1000;
+        const gatewaysCount = cached.gateways.length;
+        return cacheAge < ttlMs && gatewaysCount > 0;
+    }
+    cacheGateways(gateways) {
+        try {
+            if (typeof window === 'undefined' || !window.localStorage) {
+                return;
+            }
+            const cached = {
+                gateways: gateways.map((gateway) => gateway.toString()),
+                timestamp: Date.now(),
+                ttlSeconds: this.ttlSeconds,
+            };
+            window.localStorage.setItem(this.storageKey, JSON.stringify(cached));
+        }
+        catch (error) {
+            console.warn('Failed to cache gateways:', error);
+        }
+    }
+    clearCache() {
+        try {
+            if (typeof window === 'undefined' || !window.localStorage) {
+                return;
+            }
+            window.localStorage.removeItem(this.storageKey);
+        }
+        catch (error) {
+            console.warn('Failed to clear gateway cache:', error);
+        }
+    }
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,372 @@
+/**
+ * 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 assert from 'node:assert';
+import { beforeEach, describe, it } from 'node:test';
+import { LocalStorageGatewaysProvider } from './local-storage.js';
+class MockGatewaysProvider {
+    gateways;
+    constructor(gateways = ['https://gateway1.com', 'https://gateway2.com']) {
+        this.gateways = gateways.map((url) => new URL(url));
+    }
+    async getGateways() {
+        return this.gateways;
+    }
+    setGateways(gateways) {
+        this.gateways = gateways.map((url) => new URL(url));
+    }
+}
+function setupBrowserEnvironment() {
+    const mockLocalStorage = {
+        store: {},
+        get length() {
+            return Object.keys(this.store).length;
+        },
+        getItem: function (key) {
+            return this.store[key] || null;
+        },
+        setItem: function (key, value) {
+            this.store[key] = value;
+        },
+        removeItem: function (key) {
+            delete this.store[key];
+        },
+        clear: function () {
+            this.store = {};
+        },
+        key: function (index) {
+            const keys = Object.keys(this.store);
+            return keys[index] || null;
+        },
+    };
+    // @ts-expect-error - Mock global window object
+    global.window = {
+        localStorage: mockLocalStorage,
+    };
+    return mockLocalStorage;
+}
+function teardownBrowserEnvironment() {
+    // @ts-expect-error - Remove mock global window object
+    delete global.window;
+}
+describe('LocalStorageGatewaysProvider', () => {
+    let mockLocalStorage;
+    let mockGatewaysProvider;
+    beforeEach(() => {
+        mockLocalStorage = setupBrowserEnvironment();
+        mockGatewaysProvider = new MockGatewaysProvider();
+    });
+    describe('constructor', () => {
+        it('should initialize with default TTL when not provided', () => {
+            const provider = new LocalStorageGatewaysProvider({
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            assert.ok(provider instanceof LocalStorageGatewaysProvider);
+        });
+        it('should initialize with custom TTL when provided', () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 600,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            assert.ok(provider instanceof LocalStorageGatewaysProvider);
+        });
+    });
+    describe('getGateways', () => {
+        describe('cache hit scenarios', () => {
+            it('should return cached gateways when cache is valid', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const cachedGateways = {
+                    gateways: ['https://cached1.com', 'https://cached2.com'],
+                    timestamp: Date.now(),
+                    ttlSeconds: 300,
+                };
+                mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(cachedGateways));
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://cached1.com/');
+                assert.strictEqual(result[1].toString(), 'https://cached2.com/');
+            });
+            it('should return URLs as URL objects from cache', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const cachedGateways = {
+                    gateways: ['https://example.com'],
+                    timestamp: Date.now(),
+                    ttlSeconds: 300,
+                };
+                mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(cachedGateways));
+                const result = await provider.getGateways();
+                assert.ok(result[0] instanceof URL);
+                assert.strictEqual(result[0].toString(), 'https://example.com/');
+            });
+        });
+        describe('cache miss scenarios', () => {
+            it('should fetch from provider when no cache exists', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+                assert.strictEqual(result[1].toString(), 'https://gateway2.com/');
+                const cached = mockLocalStorage.getItem('wayfinder-gateways-cache');
+                assert.ok(cached);
+                const parsedCache = JSON.parse(cached);
+                assert.strictEqual(parsedCache.gateways.length, 2);
+                assert.strictEqual(parsedCache.ttlSeconds, 300);
+            });
+            it('should fetch from provider when cache is expired', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const expiredCache = {
+                    gateways: ['https://expired.com'],
+                    timestamp: Date.now() - 400000, // 400 seconds ago (expired)
+                    ttlSeconds: 300,
+                };
+                mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(expiredCache));
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+                assert.strictEqual(result[1].toString(), 'https://gateway2.com/');
+            });
+            it('should use default TTL from cache when cache TTL is missing', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const cacheWithoutTTL = {
+                    gateways: ['https://cached.com'],
+                    timestamp: Date.now() - 3700000, // Older than default TTL (3600s)
+                };
+                mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(cacheWithoutTTL));
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+            });
+        });
+        describe('error handling', () => {
+            it('should handle JSON parse errors gracefully', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                mockLocalStorage.setItem('wayfinder-gateways-cache', 'invalid-json');
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+            });
+            it('should handle localStorage getItem errors', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                mockLocalStorage.getItem = () => {
+                    throw new Error('Storage error');
+                };
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+            });
+            it('should handle localStorage setItem errors gracefully', async () => {
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                mockLocalStorage.setItem = () => {
+                    throw new Error('Storage quota exceeded');
+                };
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+            });
+        });
+        describe('non-browser environment', () => {
+            it('should work when window is undefined', async () => {
+                teardownBrowserEnvironment();
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+                setupBrowserEnvironment();
+            });
+            it('should work when localStorage is undefined', async () => {
+                // @ts-expect-error - Mock window without localStorage
+                global.window = {};
+                const provider = new LocalStorageGatewaysProvider({
+                    ttlSeconds: 300,
+                    gatewaysProvider: mockGatewaysProvider,
+                });
+                const result = await provider.getGateways();
+                assert.strictEqual(result.length, 2);
+                assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+            });
+        });
+    });
+    describe('clearCache', () => {
+        it('should remove cache from localStorage', () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            const cachedGateways = {
+                gateways: ['https://cached.com'],
+                timestamp: Date.now(),
+                ttlSeconds: 300,
+            };
+            mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(cachedGateways));
+            assert.ok(mockLocalStorage.getItem('wayfinder-gateways-cache'));
+            provider.clearCache();
+            assert.strictEqual(mockLocalStorage.getItem('wayfinder-gateways-cache'), null);
+        });
+        it('should handle localStorage removeItem errors gracefully', () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            mockLocalStorage.removeItem = () => {
+                throw new Error('Storage error');
+            };
+            assert.doesNotThrow(() => {
+                provider.clearCache();
+            });
+        });
+        it('should handle non-browser environment gracefully', () => {
+            teardownBrowserEnvironment();
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            assert.doesNotThrow(() => {
+                provider.clearCache();
+            });
+            setupBrowserEnvironment();
+        });
+        it('should handle missing localStorage gracefully', () => {
+            // @ts-expect-error - Mock window without localStorage
+            global.window = {};
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            assert.doesNotThrow(() => {
+                provider.clearCache();
+            });
+        });
+    });
+    describe('cache validation', () => {
+        it('should consider cache valid when within TTL', async () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            const recentCache = {
+                gateways: ['https://recent.com'],
+                timestamp: Date.now() - 100000, // 100 seconds ago
+                ttlSeconds: 300,
+            };
+            mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(recentCache));
+            const result = await provider.getGateways();
+            assert.strictEqual(result[0].toString(), 'https://recent.com/');
+        });
+        it('should consider cache invalid when beyond TTL', async () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            const oldCache = {
+                gateways: ['https://old.com'],
+                timestamp: Date.now() - 400000, // 400 seconds ago
+                ttlSeconds: 300,
+            };
+            mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(oldCache));
+            const result = await provider.getGateways();
+            assert.strictEqual(result[0].toString(), 'https://gateway1.com/');
+        });
+        it('should handle edge case when cache timestamp equals current time', async () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            const currentTime = Date.now();
+            const exactCache = {
+                gateways: ['https://exact.com'],
+                timestamp: currentTime,
+                ttlSeconds: 300,
+            };
+            mockLocalStorage.setItem('wayfinder-gateways-cache', JSON.stringify(exactCache));
+            const result = await provider.getGateways();
+            assert.strictEqual(result[0].toString(), 'https://exact.com/');
+        });
+    });
+    describe('integration scenarios', () => {
+        it('should cache results after fetching from provider', async () => {
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 600,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            await provider.getGateways();
+            const cached = mockLocalStorage.getItem('wayfinder-gateways-cache');
+            assert.ok(cached);
+            const parsedCache = JSON.parse(cached);
+            assert.strictEqual(parsedCache.gateways.length, 2);
+            assert.strictEqual(parsedCache.gateways[0], 'https://gateway1.com/');
+            assert.strictEqual(parsedCache.gateways[1], 'https://gateway2.com/');
+            assert.strictEqual(parsedCache.ttlSeconds, 600);
+            assert.ok(typeof parsedCache.timestamp === 'number');
+        });
+        it('should work with different gateway providers', async () => {
+            const customProvider = new MockGatewaysProvider([
+                'https://custom1.com',
+                'https://custom2.com',
+                'https://custom3.com',
+            ]);
+            const provider = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: customProvider,
+            });
+            const result = await provider.getGateways();
+            assert.strictEqual(result.length, 3);
+            assert.strictEqual(result[0].toString(), 'https://custom1.com/');
+            assert.strictEqual(result[1].toString(), 'https://custom2.com/');
+            assert.strictEqual(result[2].toString(), 'https://custom3.com/');
+        });
+        it('should maintain separate cache instances', async () => {
+            const provider1 = new LocalStorageGatewaysProvider({
+                ttlSeconds: 300,
+                gatewaysProvider: mockGatewaysProvider,
+            });
+            const provider2 = new LocalStorageGatewaysProvider({
+                ttlSeconds: 600,
+                gatewaysProvider: new MockGatewaysProvider(['https://different.com']),
+            });
+            await provider1.getGateways();
+            provider1.clearCache();
+            const result2 = await provider2.getGateways();
+            assert.strictEqual(result2[0].toString(), 'https://different.com/');
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-react",
-  "version": "1.0.2-alpha.2",
+  "version": "1.0.2",
   "description": "React components for WayFinder",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -30,7 +30,7 @@
     "format:check": "biome format"
   },
   "dependencies": {
-    "@ar.io/wayfinder-core": "1.0.1-alpha.2",
+    "@ar.io/wayfinder-core": "1.0.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },