@gibs/common 1.10.1 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gibs/common",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "main": "index.js",
   "access": "public",
   "type": "module",
@@ -14,18 +14,23 @@
     "./client": "./src/client.ts"
   },
   "scripts": {
-    "build": "npx tsc"
+    "build": "npx tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "description": "",
   "devDependencies": {
-    "@types/node": "^22.12.0",
-    "typescript": "~5.7.2"
+    "@types/node": "^24",
+    "@vitest/coverage-v8": "^3.1.1",
+    "typescript": "~5.7.2",
+    "vitest": "^3.1.1"
   },
   "dependencies": {
     "lodash": "^4.17.21",
-    "viem": "^2.37.8"
+    "viem": "^2.46.3"
   }
 }

package/src/assert.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { assertDefined, ensureResult } from './assert';
+
+describe('assert', () => {
+  describe('ensureResult', () => {
+    it('should return value when truthy', () => {
+      expect(ensureResult('hello', 'test')).toBe('hello');
+      expect(ensureResult(123, 'test')).toBe(123);
+      expect(ensureResult(true, 'test')).toBe(true);
+      expect(ensureResult({ foo: 'bar' }, 'test')).toEqual({ foo: 'bar' });
+      expect(ensureResult([1, 2, 3], 'test')).toEqual([1, 2, 3]);
+    });
+
+    it('should throw Error when value is null', () => {
+      expect(() => ensureResult(null, 'TestContext')).toThrow(
+        'TestContext: Expected result but got null',
+      );
+    });
+
+    it('should throw Error when value is undefined', () => {
+      expect(() => ensureResult(undefined, 'TestContext')).toThrow(
+        'TestContext: Expected result but got undefined',
+      );
+    });
+
+    it('should throw Error when value is false', () => {
+      expect(() => ensureResult(false, 'TestContext')).toThrow(
+        'TestContext: Expected result but got false',
+      );
+    });
+
+    it('should throw Error when value is 0', () => {
+      expect(() => ensureResult(0, 'TestContext')).toThrow(
+        'TestContext: Expected result but got 0',
+      );
+    });
+
+    it('should include context in error message', () => {
+      expect(() => ensureResult(null, 'Multicall aggregate3')).toThrow(
+        'Multicall aggregate3: Expected result but got null',
+      );
+
+      expect(() => ensureResult(undefined, 'Database query')).toThrow(
+        'Database query: Expected result but got undefined',
+      );
+    });
+
+    it('should handle BigInt values', () => {
+      expect(ensureResult(123n, 'test')).toBe(123n);
+      // 0n is falsy just like 0, so it should throw
+      expect(() => ensureResult(0n, 'test')).toThrow('test: Expected result but got 0');
+    });
+
+    it('should handle empty string as falsy', () => {
+      expect(() => ensureResult('', 'TestContext')).toThrow(
+        'TestContext: Expected result but got ',
+      );
+    });
+
+    it('should handle empty array as truthy', () => {
+      expect(ensureResult([], 'test')).toEqual([]);
+    });
+
+    it('should throw Error, not the value itself', () => {
+      try {
+        ensureResult(null, 'test');
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(Error);
+        expect(err).not.toBe(null);
+      }
+    });
+  });
+
+  describe('assertDefined', () => {
+    it('should not throw when value is defined', () => {
+      expect(() => assertDefined('hello', 'test')).not.toThrow();
+      expect(() => assertDefined(123, 'test')).not.toThrow();
+      expect(() => assertDefined(true, 'test')).not.toThrow();
+      expect(() => assertDefined(false, 'test')).not.toThrow();
+      expect(() => assertDefined(0, 'test')).not.toThrow();
+      expect(() => assertDefined({}, 'test')).not.toThrow();
+      expect(() => assertDefined([], 'test')).not.toThrow();
+    });
+
+    it('should throw when value is null', () => {
+      expect(() => assertDefined(null, 'Value cannot be null')).toThrow('Value cannot be null');
+    });
+
+    it('should throw when value is undefined', () => {
+      expect(() => assertDefined(undefined, 'Value cannot be undefined')).toThrow(
+        'Value cannot be undefined',
+      );
+    });
+
+    it('should not throw for falsy but defined values', () => {
+      expect(() => assertDefined(false, 'test')).not.toThrow();
+      expect(() => assertDefined(0, 'test')).not.toThrow();
+      expect(() => assertDefined('', 'test')).not.toThrow();
+      expect(() => assertDefined(0n, 'test')).not.toThrow();
+    });
+
+    it('should include message in error', () => {
+      expect(() => assertDefined(null, 'Custom error message')).toThrow('Custom error message');
+    });
+
+    it('should throw Error object', () => {
+      try {
+        assertDefined(null, 'test');
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(Error);
+      }
+    });
+
+    it('should work with type narrowing', () => {
+      const value: string | null = 'hello';
+      assertDefined(value, 'test');
+      // TypeScript should now know value is string
+      const uppercased: string = value.toUpperCase();
+      expect(uppercased).toBe('HELLO');
+    });
+  });
+
+  describe('integration', () => {
+    it('should allow chaining ensureResult', () => {
+      const obj = { nested: { value: 42 } };
+      const result = ensureResult(ensureResult(obj, 'obj').nested, 'nested').value;
+      expect(result).toBe(42);
+    });
+
+    it('should provide clear error messages in real-world scenarios', async () => {
+      const mockApiCall = async (): Promise<any[] | null> => null;
+
+      await expect(async () => {
+        const result = await mockApiCall();
+        ensureResult(result, 'API call');
+      }).rejects.toThrow('API call: Expected result but got null');
+    });
+  });
+});

package/src/assert.ts

@@ -0,0 +1,28 @@
+/**
+ * Asserts that a value is defined (not null, undefined, or falsy)
+ * Throws a descriptive error if the value is falsy
+ *
+ * @param value - The value to check
+ * @param context - Context description for the error message
+ * @returns The value if defined
+ * @throws Error if value is falsy
+ */
+export function ensureResult<T>(value: T | null | undefined | false | 0, context: string): T {
+  if (!value) {
+    throw new Error(`${context}: Expected result but got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Type guard that asserts a value is defined
+ * Similar to ensureResult but uses TypeScript's asserts syntax
+ *
+ * @param value - The value to check
+ * @param message - Error message if assertion fails
+ */
+export function assertDefined<T>(value: T | null | undefined, message: string): asserts value is T {
+  if (value === null || value === undefined) {
+    throw new Error(message);
+  }
+}

package/src/cache.test.ts

@@ -0,0 +1,176 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { maxMemoize, ttlMemoizeSingle } from './cache';
+
+describe('cache', () => {
+  describe('maxMemoize', () => {
+    it('should cache function results', () => {
+      const fn = vi.fn((a: number, b: number) => a + b);
+      const memoized = maxMemoize(fn);
+
+      const result1 = memoized(1, 2);
+      const result2 = memoized(1, 2);
+
+      expect(result1).toBe(3);
+      expect(result2).toBe(3);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should cache different argument combinations separately', () => {
+      const fn = vi.fn((a: number, b: number) => a + b);
+      const memoized = maxMemoize(fn);
+
+      expect(memoized(1, 2)).toBe(3);
+      expect(memoized(2, 3)).toBe(5);
+      expect(memoized(1, 2)).toBe(3);
+
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should handle bigint arguments correctly', () => {
+      const fn = vi.fn((a: bigint) => a * 2n);
+      const memoized = maxMemoize(fn);
+
+      const result1 = memoized(100n);
+      const result2 = memoized(100n);
+
+      expect(result1).toBe(200n);
+      expect(result2).toBe(200n);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should respect max cache size', () => {
+      const fn = vi.fn((n: number) => n * 2);
+      const memoized = maxMemoize(fn, 3);
+
+      // Fill cache with 3 entries
+      memoized(1);
+      memoized(2);
+      memoized(3);
+
+      // Add 4th entry - should evict oldest
+      memoized(4);
+
+      // Call first entry again - should recompute
+      memoized(1);
+
+      // Total calls: 5 (1, 2, 3, 4, 1 again)
+      expect(fn).toHaveBeenCalledTimes(5);
+    });
+
+    it('should handle complex object arguments', () => {
+      const fn = vi.fn((obj: { a: number; b: string }) => `${obj.a}-${obj.b}`);
+      const memoized = maxMemoize(fn);
+
+      const result1 = memoized({ a: 1, b: 'test' });
+      const result2 = memoized({ a: 1, b: 'test' });
+
+      expect(result1).toBe('1-test');
+      expect(result2).toBe('1-test');
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return undefined for cached undefined results', () => {
+      const fn = vi.fn(() => undefined);
+      const memoized = maxMemoize(fn);
+
+      const result1 = memoized();
+      const result2 = memoized();
+
+      expect(result1).toBe(undefined);
+      expect(result2).toBe(undefined);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('ttlMemoizeSingle', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should cache result within TTL', () => {
+      const fn = vi.fn(() => Math.random());
+      const memoized = ttlMemoizeSingle(fn, 1000);
+
+      const result1 = memoized();
+      vi.advanceTimersByTime(500);
+      const result2 = memoized();
+
+      expect(result1).toBe(result2);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should recompute after TTL expires', () => {
+      const fn = vi.fn(() => Math.random());
+      const memoized = ttlMemoizeSingle(fn, 1000);
+
+      const result1 = memoized();
+      vi.advanceTimersByTime(1001);
+      const result2 = memoized();
+
+      expect(result1).not.toBe(result2);
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should use default TTL of 1 hour', () => {
+      const fn = vi.fn(() => 'test');
+      const memoized = ttlMemoizeSingle(fn);
+
+      memoized();
+      vi.advanceTimersByTime(1000 * 60 * 59); // 59 minutes
+      memoized();
+
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      vi.advanceTimersByTime(1000 * 60 * 2); // 2 more minutes (total 61)
+      memoized();
+
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should ignore arguments and always return same cached result', () => {
+      const fn = vi.fn((n: number) => n * 2);
+      const memoized = ttlMemoizeSingle(fn, 1000);
+
+      const result1 = memoized(5);
+      const result2 = memoized(10);
+
+      // Second call should return cached result from first call
+      expect(result1).toBe(10);
+      expect(result2).toBe(10);
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenCalledWith(5);
+    });
+
+    it('should handle bigint results', () => {
+      const fn = vi.fn(() => 999999999999999999n);
+      const memoized = ttlMemoizeSingle(fn, 1000);
+
+      const result1 = memoized();
+      const result2 = memoized();
+
+      expect(result1).toBe(999999999999999999n);
+      expect(result2).toBe(999999999999999999n);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should cache null and undefined results', () => {
+      const fnNull = vi.fn(() => null);
+      const memoizedNull = ttlMemoizeSingle(fnNull, 1000);
+
+      expect(memoizedNull()).toBe(null);
+      expect(memoizedNull()).toBe(null);
+      expect(fnNull).toHaveBeenCalledTimes(1);
+
+      const fnUndefined = vi.fn(() => undefined);
+      const memoizedUndefined = ttlMemoizeSingle(fnUndefined, 1000);
+
+      expect(memoizedUndefined()).toBe(undefined);
+      expect(memoizedUndefined()).toBe(undefined);
+      expect(fnUndefined).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/cache.ts

@@ -1,4 +1,4 @@
-import { jsonAnyStringify } from "./serialize.js"
+import { jsonAnyStringify } from './serialize.js';
 
 /**
  * Memoize a function result and return a single value
@@ -7,24 +7,24 @@ import { jsonAnyStringify } from "./serialize.js"
  * @returns the memoized function
  */
 export const maxMemoize = <A extends unknown[], B>(fn: (...a: A) => B, max = 1024) => {
-  const cache = new Map<string, B>()
+  const cache = new Map<string, B>();
   return (...a: A) => {
-    const key = JSON.stringify(a, jsonAnyStringify)
-    const existing = cache.get(key)
+    const key = JSON.stringify(a, jsonAnyStringify);
+    const existing = cache.get(key);
     if (cache.has(key)) {
-      return existing
+      return existing;
     }
     for (const k of cache.keys()) {
-      if (cache.size < max) break
-      cache.delete(k)
+      if (cache.size < max) break;
+      cache.delete(k);
     }
-    const result = fn(...a)
-    cache.set(key, result)
-    return result
-  }
-}
+    const result = fn(...a);
+    cache.set(key, result);
+    return result;
+  };
+};
 
-const hour1 = 1000 * 60 * 60
+const hour1 = 1000 * 60 * 60;
 /**
  * Memoize a function result and return a single value
  * @param fn the function to memoize
@@ -33,16 +33,16 @@ const hour1 = 1000 * 60 * 60
  */
 export const ttlMemoizeSingle = <A extends unknown[], B>(fn: (...a: A) => B, ttl = hour1) => {
   let cache: {
-    timestamp: number
-    result: B
-  } | null = null
+    timestamp: number;
+    result: B;
+  } | null = null;
   return (...a: A) => {
-    const now = Date.now()
+    const now = Date.now();
     if (cache && cache.timestamp + ttl > now) {
-      return cache.result
+      return cache.result;
     }
-    const result = fn(...a)
-    cache = { timestamp: now, result }
-    return result
-  }
-}
+    const result = fn(...a);
+    cache = { timestamp: now, result };
+    return result;
+  };
+};

package/src/client.test.ts

@@ -0,0 +1,205 @@
+import type { Chain } from 'viem';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { chainKey, clientFromChain, defaultBatchConfig } from './client';
+
+// Mock viem functions
+vi.mock('viem', async () => {
+  const actual = await vi.importActual<typeof import('viem')>('viem');
+  return {
+    ...actual,
+    createPublicClient: vi.fn((config: any) => ({
+      ...config,
+      mockClient: true,
+    })),
+    http: vi.fn((url?: string, config?: any) => ({
+      type: 'http',
+      url,
+      config,
+    })),
+    webSocket: vi.fn((url: string, config?: any) => ({
+      type: 'webSocket',
+      url,
+      config,
+    })),
+    fallback: vi.fn((transports: any[], config?: any) => ({
+      type: 'fallback',
+      transports,
+      config,
+    })),
+  };
+});
+
+describe('client', () => {
+  describe('defaultBatchConfig', () => {
+    it('should have correct batch wait time', () => {
+      expect(defaultBatchConfig.batch.wait).toBe(10);
+    });
+
+    it('should have correct batch size', () => {
+      expect(defaultBatchConfig.batch.batchSize).toBe(32);
+    });
+
+    it('should have batch property', () => {
+      expect(defaultBatchConfig).toHaveProperty('batch');
+      expect(defaultBatchConfig.batch).toHaveProperty('wait');
+      expect(defaultBatchConfig.batch).toHaveProperty('batchSize');
+    });
+  });
+
+  describe('chainKey', () => {
+    it('should create key from chainId and single URL', () => {
+      const result = chainKey(1, ['https://eth.llamarpc.com']);
+      expect(result).toBe('1,https://eth.llamarpc.com');
+    });
+
+    it('should create key from chainId and multiple URLs', () => {
+      const result = chainKey(369, [
+        'https://rpc.pulsechain.com',
+        'https://rpc-pulsechain.g4mm4.io',
+      ]);
+      expect(result).toBe('369,https://rpc.pulsechain.com,https://rpc-pulsechain.g4mm4.io');
+    });
+
+    it('should lowercase the result', () => {
+      const result = chainKey(1, ['HTTPS://ETH.LLAMARPC.COM']);
+      expect(result).toBe('1,https://eth.llamarpc.com');
+    });
+
+    it('should handle empty URL array', () => {
+      const result = chainKey(1, []);
+      expect(result).toBe('1,');
+    });
+
+    it('should handle WebSocket URLs', () => {
+      const result = chainKey(1, ['wss://eth.llamarpc.com']);
+      expect(result).toBe('1,wss://eth.llamarpc.com');
+    });
+
+    it('should create unique keys for different chainIds', () => {
+      const key1 = chainKey(1, ['https://rpc.example.com']);
+      const key2 = chainKey(369, ['https://rpc.example.com']);
+      expect(key1).not.toBe(key2);
+    });
+
+    it('should create unique keys for different URL arrays', () => {
+      const key1 = chainKey(1, ['https://rpc1.example.com']);
+      const key2 = chainKey(1, ['https://rpc2.example.com']);
+      expect(key1).not.toBe(key2);
+    });
+
+    it('should create same key for same inputs', () => {
+      const key1 = chainKey(1, ['https://rpc.example.com', 'https://backup.example.com']);
+      const key2 = chainKey(1, ['https://rpc.example.com', 'https://backup.example.com']);
+      expect(key1).toBe(key2);
+    });
+
+    it('should handle URLs with query parameters', () => {
+      const result = chainKey(1, ['https://rpc.example.com?apiKey=123']);
+      expect(result).toBe('1,https://rpc.example.com?apikey=123');
+    });
+
+    it('should handle URLs with ports', () => {
+      const result = chainKey(1, ['https://localhost:8545']);
+      expect(result).toBe('1,https://localhost:8545');
+    });
+
+    it('should handle testnet chain IDs', () => {
+      const sepolia = chainKey(11155111, ['https://sepolia.infura.io']);
+      expect(sepolia).toBe('11155111,https://sepolia.infura.io');
+    });
+
+    it('should create different keys when URL order differs', () => {
+      const key1 = chainKey(1, ['https://rpc1.example.com', 'https://rpc2.example.com']);
+      const key2 = chainKey(1, ['https://rpc2.example.com', 'https://rpc1.example.com']);
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe('clientFromChain', () => {
+    let mockChain: Chain;
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+      mockChain = {
+        id: 1,
+        name: 'Ethereum',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrls: {
+          default: { http: ['https://eth.llamarpc.com'] },
+        },
+      } as Chain;
+    });
+
+    it('should create client with http transport when urls provided', () => {
+      const urls = ['https://eth.llamarpc.com'];
+      const client = clientFromChain({ chain: mockChain, urls });
+
+      expect(client).toBeDefined();
+      expect((client as any).mockClient).toBe(true);
+    });
+
+    it('should create client with multiple http urls using fallback', () => {
+      const urls = ['https://eth.llamarpc.com', 'https://rpc.ankr.com/eth'];
+      const client = clientFromChain({ chain: mockChain, urls });
+
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with websocket transport', () => {
+      const urls = ['wss://eth.llamarpc.com'];
+      const client = clientFromChain({ chain: mockChain, urls });
+
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with mixed http and websocket transports', () => {
+      const urls = ['https://eth.llamarpc.com', 'wss://eth.llamarpc.com'];
+      const client = clientFromChain({ chain: mockChain, urls });
+
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with empty urls array', () => {
+      const urls: string[] = [];
+      const client = clientFromChain({ chain: mockChain, urls });
+
+      expect(client).toBeDefined();
+    });
+
+    it('should use cache for same chain and urls', () => {
+      const urls = ['https://eth.llamarpc.com'];
+
+      const client1 = clientFromChain({ chain: mockChain, urls });
+      const client2 = clientFromChain({ chain: mockChain, urls });
+
+      // Should return cached client
+      expect(client1).toBe(client2);
+    });
+
+    it('should create new client for different urls', () => {
+      const urls1 = ['https://eth.llamarpc.com'];
+      const urls2 = ['https://rpc.ankr.com/eth'];
+
+      const client1 = clientFromChain({ chain: mockChain, urls: urls1 });
+      const client2 = clientFromChain({ chain: mockChain, urls: urls2 });
+
+      // Should be different clients
+      expect(client1).not.toBe(client2);
+    });
+
+    it('should create new client for different chain', () => {
+      const urls = ['https://eth.llamarpc.com'];
+      const chain2: Chain = {
+        ...mockChain,
+        id: 369,
+        name: 'PulseChain',
+      };
+
+      const client1 = clientFromChain({ chain: mockChain, urls });
+      const client2 = clientFromChain({ chain: chain2, urls });
+
+      // Should be different clients
+      expect(client1).not.toBe(client2);
+    });
+  });
+});