@provex/utils 1.0.16 → 1.2.3

package/dist/src/sort.test.js

@@ -0,0 +1,216 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { orderedSort, orderedSortThenById } from './sort.js';
+describe('sort', () => {
+    describe('orderedSort', () => {
+        describe('with numbers', () => {
+            it('should sort ascending', () => {
+                assert.equal(orderedSort(1, 2, 'asc'), -1);
+                assert.equal(orderedSort(2, 1, 'asc'), 1);
+                assert.equal(orderedSort(1, 1, 'asc'), 0);
+            });
+            it('should sort descending', () => {
+                assert.ok(orderedSort(1, 2, 'desc') > 0);
+                assert.ok(orderedSort(2, 1, 'desc') < 0);
+                // Use loose equality to handle -0 === 0 case
+                assert.ok(orderedSort(1, 1, 'desc') == 0);
+            });
+            it('should handle negative numbers', () => {
+                assert.equal(orderedSort(-5, -3, 'asc'), -2);
+                assert.equal(orderedSort(-3, -5, 'asc'), 2);
+                assert.equal(orderedSort(-5, 5, 'asc'), -10);
+            });
+            it('should handle zero', () => {
+                assert.equal(orderedSort(0, 1, 'asc'), -1);
+                assert.equal(orderedSort(1, 0, 'asc'), 1);
+                assert.equal(orderedSort(0, 0, 'asc'), 0);
+            });
+            it('should handle decimals', () => {
+                assert.ok(orderedSort(1.5, 2.5, 'asc') < 0);
+                assert.ok(orderedSort(2.5, 1.5, 'asc') > 0);
+                assert.equal(orderedSort(1.5, 1.5, 'asc'), 0);
+            });
+        });
+        describe('with strings', () => {
+            it('should sort ascending', () => {
+                assert.ok(orderedSort('a', 'b', 'asc') < 0);
+                assert.ok(orderedSort('b', 'a', 'asc') > 0);
+                assert.equal(orderedSort('a', 'a', 'asc'), 0);
+            });
+            it('should sort descending', () => {
+                const result1 = orderedSort('a', 'b', 'desc');
+                const result2 = orderedSort('b', 'a', 'desc');
+                assert.ok(result1 > 0, `Expected positive, got ${result1}`);
+                assert.ok(result2 < 0, `Expected negative, got ${result2}`);
+                // Use loose equality to handle -0 === 0 case
+                assert.ok(orderedSort('a', 'a', 'desc') == 0);
+            });
+            it('should handle case-sensitive sorting', () => {
+                const result1 = orderedSort('A', 'a', 'asc');
+                const result2 = orderedSort('a', 'A', 'asc');
+                // localeCompare is case-sensitive
+                assert.notEqual(result1, 0, `'A' and 'a' should not be equal`);
+                assert.notEqual(result2, 0, `'a' and 'A' should not be equal`);
+                // They should sort opposite to each other
+                assert.ok((result1 < 0 && result2 > 0) || (result1 > 0 && result2 < 0));
+            });
+            it('should handle empty strings', () => {
+                assert.ok(orderedSort('', 'a', 'asc') < 0);
+                assert.ok(orderedSort('a', '', 'asc') > 0);
+                assert.equal(orderedSort('', '', 'asc'), 0);
+            });
+            it('should sort multi-character strings', () => {
+                assert.ok(orderedSort('apple', 'banana', 'asc') < 0);
+                assert.ok(orderedSort('banana', 'apple', 'asc') > 0);
+                assert.equal(orderedSort('apple', 'apple', 'asc'), 0);
+            });
+        });
+        describe('with bigints', () => {
+            it('should sort ascending', () => {
+                assert.equal(orderedSort(1n, 2n, 'asc'), -1);
+                assert.equal(orderedSort(2n, 1n, 'asc'), 1);
+                assert.equal(orderedSort(1n, 1n, 'asc'), 0);
+            });
+            it('should sort descending', () => {
+                assert.ok(orderedSort(1n, 2n, 'desc') > 0);
+                assert.ok(orderedSort(2n, 1n, 'desc') < 0);
+                // Use loose equality to handle -0 === 0 case
+                assert.ok(orderedSort(1n, 1n, 'desc') == 0);
+            });
+            it('should handle large bigints', () => {
+                const large1 = 999999999999999999n;
+                const large2 = 1000000000000000000n;
+                assert.equal(orderedSort(large1, large2, 'asc'), -1);
+                assert.equal(orderedSort(large2, large1, 'asc'), 1);
+            });
+            it('should handle negative bigints', () => {
+                assert.equal(orderedSort(-5n, -3n, 'asc'), -1);
+                assert.equal(orderedSort(-3n, -5n, 'asc'), 1);
+                assert.equal(orderedSort(-5n, 5n, 'asc'), -1);
+            });
+            it('should handle zero', () => {
+                assert.equal(orderedSort(0n, 1n, 'asc'), -1);
+                assert.equal(orderedSort(1n, 0n, 'asc'), 1);
+                assert.equal(orderedSort(0n, 0n, 'asc'), 0);
+            });
+        });
+        describe('with mixed types (fallback to string comparison)', () => {
+            it('should convert to strings and compare ascending', () => {
+                // number vs string - should use string comparison
+                const result = orderedSort(123, 'abc', 'asc');
+                assert.ok(typeof result === 'number');
+            });
+            it('should convert to strings and compare descending', () => {
+                const result = orderedSort(123, 'abc', 'desc');
+                assert.ok(typeof result === 'number');
+            });
+            it('should handle equal mixed types', () => {
+                // When converted to strings, '123' should equal '123'
+                const result = orderedSort('123', 123, 'asc');
+                assert.equal(result, 0);
+            });
+        });
+    });
+    describe('orderedSortThenById', () => {
+        const createMockDeposit = (depositId, timestamp) => ({
+            depositId,
+            transaction: {
+                block: {
+                    timestamp,
+                },
+            },
+        });
+        it('should sort by value first', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(2n, 1000n);
+            const result = orderedSortThenById({
+                aVal: 100,
+                bVal: 200,
+                orderDirection: 'asc',
+                a,
+                b,
+            });
+            assert.ok(result < 0); // a comes before b
+        });
+        it('should use timestamp as tiebreaker', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(2n, 2000n);
+            const result = orderedSortThenById({
+                aVal: 100,
+                bVal: 100, // Same value
+                orderDirection: 'asc',
+                a,
+                b,
+            });
+            assert.ok(result < 0); // a has earlier timestamp
+        });
+        it('should use depositId as final tiebreaker', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(2n, 1000n);
+            const result = orderedSortThenById({
+                aVal: 100,
+                bVal: 100, // Same value
+                orderDirection: 'asc',
+                a, // Same timestamp
+                b,
+            });
+            assert.ok(result < 0); // a has smaller depositId
+        });
+        it('should return 0 for identical entries', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(1n, 1000n);
+            const result = orderedSortThenById({
+                aVal: 100,
+                bVal: 100,
+                orderDirection: 'asc',
+                a,
+                b,
+            });
+            assert.equal(result, 0);
+        });
+        it('should respect order direction for primary sort', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(2n, 1000n);
+            const resultAsc = orderedSortThenById({
+                aVal: 100,
+                bVal: 200,
+                orderDirection: 'asc',
+                a,
+                b,
+            });
+            const resultDesc = orderedSortThenById({
+                aVal: 100,
+                bVal: 200,
+                orderDirection: 'desc',
+                a,
+                b,
+            });
+            assert.ok(resultAsc < 0);
+            assert.ok(resultDesc > 0);
+        });
+        it('should handle bigint values', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(2n, 1000n);
+            const result = orderedSortThenById({
+                aVal: 100n,
+                bVal: 200n,
+                orderDirection: 'asc',
+                a,
+                b,
+            });
+            assert.ok(result < 0);
+        });
+        it('should handle string values', () => {
+            const a = createMockDeposit(1n, 1000n);
+            const b = createMockDeposit(2n, 1000n);
+            const result = orderedSortThenById({
+                aVal: 'alpha',
+                bVal: 'beta',
+                orderDirection: 'asc',
+                a,
+                b,
+            });
+            assert.ok(result < 0);
+        });
+    });
+});

package/dist/src/stateKey.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview State key constants for the indexer's contractStateLink table.
+ *
+ * The contractStateLink table tracks the current value of various contract
+ * configuration parameters. State keys identify which parameter is being tracked.
+ *
+ * @see {@link indexer} for how these are used in event handlers
+ */
+/**
+ * State keys for contract configuration tracking.
+ * Each key corresponds to a different contract parameter that can change over time.
+ *
+ * @example
+ * ```ts
+ * // Used in indexer to track current dust threshold
+ * await updateContractState({
+ *   stateKey: stateKey.dustThreshold,
+ *   value: event.args.newThreshold,
+ *   ...
+ * })
+ * ```
+ */
+export declare const stateKey: {
+    readonly dustRecipient: "dustRecipient";
+    readonly dustThreshold: "dustThreshold";
+    readonly protocolFee: "protocolFee";
+    readonly protocolFeeRecipient: "protocolFeeRecipient";
+};
+export type StateKey = (typeof stateKey)[keyof typeof stateKey];
+/**
+ * Type guard to check if a string is a valid state key.
+ * @param key - The string to check
+ * @returns True if the key is a valid StateKey
+ */
+export declare const isStateKey: (key: string) => key is StateKey;

package/dist/src/stateKey.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview State key constants for the indexer's contractStateLink table.
+ *
+ * The contractStateLink table tracks the current value of various contract
+ * configuration parameters. State keys identify which parameter is being tracked.
+ *
+ * @see {@link indexer} for how these are used in event handlers
+ */
+/**
+ * State keys for contract configuration tracking.
+ * Each key corresponds to a different contract parameter that can change over time.
+ *
+ * @example
+ * ```ts
+ * // Used in indexer to track current dust threshold
+ * await updateContractState({
+ *   stateKey: stateKey.dustThreshold,
+ *   value: event.args.newThreshold,
+ *   ...
+ * })
+ * ```
+ */
+export const stateKey = {
+    dustRecipient: 'dustRecipient',
+    dustThreshold: 'dustThreshold',
+    protocolFee: 'protocolFee',
+    protocolFeeRecipient: 'protocolFeeRecipient',
+};
+/**
+ * Type guard to check if a string is a valid state key.
+ * @param key - The string to check
+ * @returns True if the key is a valid StateKey
+ */
+export const isStateKey = (key) => {
+    return key in stateKey;
+};

package/dist/src/stats.d.ts

@@ -1,7 +1,61 @@
+/**
+ * @fileoverview Statistical event type definitions for the indexer.
+ *
+ * These event types categorize different liquidity movements for
+ * aggregated statistics (hourly, daily, monthly summaries).
+ *
+ * @see {@link ids} for stat ID generation
+ */
+/**
+ * Types of statistical events tracked by the indexer.
+ * Each event type represents a different category of liquidity movement.
+ *
+ * - `deposit`: Funds added to a deposit
+ * - `withdrawal`: Funds removed from a deposit
+ * - `exchange`: Intent fulfilled, funds exchanged
+ * - `fee`: Protocol fees collected
+ * - `dust`: Dust amounts collected
+ */
+export declare const statEvent: {
+    readonly deposit: "deposit";
+    readonly withdrawal: "withdrawal";
+    readonly exchange: "exchange";
+    readonly fee: "fee";
+    readonly dust: "dust";
+    readonly intentSignaled: "intent-signaled";
+    readonly intentFulfilled: "intent-fulfilled";
+    readonly intentCancelled: "intent-cancelled";
+    readonly intentExpired: "intent-expired";
+    readonly fillTime: "fill-time";
+};
+/**
+ * Union type of all valid stat event types.
+ */
+export type StatEvent = (typeof statEvent)[keyof typeof statEvent];
+/**
+ * Type guard to check if a string is a valid stat event type.
+ */
+export declare const isStatEvent: (event: string) => event is StatEvent;
+/**
+ * Stat actions represent different types of liquidity movements.
+ * Alias for statEvent to maintain consistency with usage patterns.
+ */
 export declare const statAction: {
     readonly deposit: "deposit";
     readonly withdrawal: "withdrawal";
     readonly exchange: "exchange";
+    readonly fee: "fee";
+    readonly dust: "dust";
+    readonly intentSignaled: "intent-signaled";
+    readonly intentFulfilled: "intent-fulfilled";
+    readonly intentCancelled: "intent-cancelled";
+    readonly intentExpired: "intent-expired";
+    readonly fillTime: "fill-time";
 };
-export type StatAction = (typeof statAction)[keyof typeof statAction];
+export type StatAction = StatEvent;
+/**
+ * Type guard to check if a string is a valid stat action.
+ * @param action - The string to check
+ * @returns True if the action is a valid StatAction
+ */
 export declare const isStatAction: (action: string) => action is StatAction;

package/dist/src/stats.js

@@ -1,8 +1,53 @@
-export const statAction = {
+/**
+ * @fileoverview Statistical event type definitions for the indexer.
+ *
+ * These event types categorize different liquidity movements for
+ * aggregated statistics (hourly, daily, monthly summaries).
+ *
+ * @see {@link ids} for stat ID generation
+ */
+/**
+ * Types of statistical events tracked by the indexer.
+ * Each event type represents a different category of liquidity movement.
+ *
+ * - `deposit`: Funds added to a deposit
+ * - `withdrawal`: Funds removed from a deposit
+ * - `exchange`: Intent fulfilled, funds exchanged
+ * - `fee`: Protocol fees collected
+ * - `dust`: Dust amounts collected
+ */
+export const statEvent = {
     deposit: 'deposit',
     withdrawal: 'withdrawal',
     exchange: 'exchange',
+    fee: 'fee',
+    dust: 'dust',
+    // Intent lifecycle stats — one row per intent, bucketed by day/hour/month.
+    // Eliminates the need to paginate raw intentSignaled/intentFulfilled tables for KPIs.
+    intentSignaled: 'intent-signaled',
+    intentFulfilled: 'intent-fulfilled',
+    intentCancelled: 'intent-cancelled',
+    intentExpired: 'intent-expired',
+    // Fill time: amount = fillTimeSeconds. Individual data points (not accumulated)
+    // so median/percentile can be computed per time bucket.
+    fillTime: 'fill-time',
 };
+/**
+ * Type guard to check if a string is a valid stat event type.
+ */
+export const isStatEvent = (event) => {
+    return event in statEvent;
+};
+/**
+ * Stat actions represent different types of liquidity movements.
+ * Alias for statEvent to maintain consistency with usage patterns.
+ */
+export const statAction = statEvent;
+/**
+ * Type guard to check if a string is a valid stat action.
+ * @param action - The string to check
+ * @returns True if the action is a valid StatAction
+ */
 export const isStatAction = (action) => {
     return action in statAction;
 };

package/dist/src/stats.test.d.ts

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

package/dist/src/stats.test.js

@@ -0,0 +1,104 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { statEvent, isStatEvent, statAction, isStatAction, } from './stats.js';
+describe('stats', () => {
+    describe('statEvent', () => {
+        it('should define deposit event', () => {
+            assert.equal(statEvent.deposit, 'deposit');
+        });
+        it('should define withdrawal event', () => {
+            assert.equal(statEvent.withdrawal, 'withdrawal');
+        });
+        it('should define exchange event', () => {
+            assert.equal(statEvent.exchange, 'exchange');
+        });
+        it('should define fee event', () => {
+            assert.equal(statEvent.fee, 'fee');
+        });
+        it('should define dust event', () => {
+            assert.equal(statEvent.dust, 'dust');
+        });
+        it('should have exactly 5 event types', () => {
+            const eventCount = Object.keys(statEvent).length;
+            assert.equal(eventCount, 5);
+        });
+    });
+    describe('isStatEvent', () => {
+        it('should return true for valid stat events', () => {
+            assert.equal(isStatEvent('deposit'), true);
+            assert.equal(isStatEvent('withdrawal'), true);
+            assert.equal(isStatEvent('exchange'), true);
+            assert.equal(isStatEvent('fee'), true);
+            assert.equal(isStatEvent('dust'), true);
+        });
+        it('should return false for invalid stat events', () => {
+            assert.equal(isStatEvent('invalid'), false);
+            assert.equal(isStatEvent(''), false);
+            assert.equal(isStatEvent('DEPOSIT'), false); // case-sensitive
+            assert.equal(isStatEvent('transfer'), false);
+        });
+        it('should work as a type guard', () => {
+            const event = 'deposit';
+            if (isStatEvent(event)) {
+                // TypeScript should narrow the type here
+                const typedEvent = event;
+                assert.equal(typedEvent, 'deposit');
+            }
+            else {
+                assert.fail('Expected deposit to be a valid stat event');
+            }
+        });
+    });
+    describe('statAction', () => {
+        it('should be an alias for statEvent', () => {
+            assert.deepEqual(statAction, statEvent);
+        });
+        it('should have the same keys as statEvent', () => {
+            const eventKeys = Object.keys(statEvent).sort();
+            const actionKeys = Object.keys(statAction).sort();
+            assert.deepEqual(eventKeys, actionKeys);
+        });
+    });
+    describe('isStatAction', () => {
+        it('should return true for valid stat actions', () => {
+            assert.equal(isStatAction('deposit'), true);
+            assert.equal(isStatAction('withdrawal'), true);
+            assert.equal(isStatAction('exchange'), true);
+            assert.equal(isStatAction('fee'), true);
+            assert.equal(isStatAction('dust'), true);
+        });
+        it('should return false for invalid stat actions', () => {
+            assert.equal(isStatAction('invalid'), false);
+            assert.equal(isStatAction(''), false);
+            assert.equal(isStatAction('WITHDRAWAL'), false); // case-sensitive
+        });
+        it('should work as a type guard', () => {
+            const action = 'exchange';
+            if (isStatAction(action)) {
+                // TypeScript should narrow the type here
+                const typedAction = action;
+                assert.equal(typedAction, 'exchange');
+            }
+            else {
+                assert.fail('Expected exchange to be a valid stat action');
+            }
+        });
+    });
+    describe('type consistency', () => {
+        it('StatEvent and StatAction should be assignable to each other', () => {
+            const event = 'deposit';
+            const action = event; // Should compile
+            assert.equal(event, action);
+        });
+        it('all statEvent values should be valid StatEvent types', () => {
+            for (const [key, value] of Object.entries(statEvent)) {
+                assert.ok(isStatEvent(value), `${key} should be a valid StatEvent`);
+            }
+        });
+        it('all statAction values should be valid StatAction types', () => {
+            for (const [key, value] of Object.entries(statAction)) {
+                assert.ok(isStatAction(value), `${key} should be a valid StatAction`);
+            }
+        });
+    });
+});

package/dist/src/time.d.ts

@@ -1,4 +1,18 @@
-/** Interval in milliseconds */
+/**
+ * @fileoverview Time and date utilities for formatting and calculations.
+ *
+ * Provides:
+ * - Interval constants in milliseconds for time calculations
+ * - Human-readable relative time formatting ("5m ago", "2d 3h ago")
+ * - Duration formatting for time ranges
+ * - Absolute timestamp formatting
+ *
+ * @see {@link units} for blockchain timestamp conversion
+ */
+/**
+ * Time unit relationships for manual calculations.
+ * Use these when building complex time expressions.
+ */
 export declare const intervalIn: {
     readonly yearInDays: 365;
     readonly quarterInMonths: 3;
@@ -9,7 +23,19 @@ export declare const intervalIn: {
     readonly secondInMinutes: 60;
     readonly millisecondInSecond: 1000;
 };
-/** Intervals in milliseconds */
+/**
+ * Common time intervals in milliseconds.
+ * Use for timeout calculations, polling intervals, and date math.
+ *
+ * @example
+ * ```ts
+ * // Set a 5 minute timeout
+ * setTimeout(callback, 5 * interval.minute)
+ *
+ * // Calculate time 1 day ago
+ * const yesterday = Date.now() - interval.day
+ * ```
+ */
 export declare const interval: {
     readonly second: 1000;
     readonly minute: number;
@@ -18,20 +44,33 @@ export declare const interval: {
     readonly month: number;
     readonly year: number;
 };
-/** Default display intervals */
+/**
+ * Default number of time units to display in statistics/charts.
+ * Used for "show last N hours/days/months" UI controls.
+ */
 export declare const defaultDisplayInterval: {
     readonly hour: number;
     readonly day: number;
     readonly month: 60;
 };
 /**
- * Format a timestamp
- * @param timestamp - The timestamp to format
- * @param param1.anchor - The anchor date
- * @param param1.showSeconds - Whether to show seconds
- * @returns The formatted timestamp
+ * Format a timestamp as a human-readable relative time string.
+ * Produces compact strings like "5m ago", "2h 30m ago", "3d ago".
+ *
+ * @param timestamp - The timestamp to format (Date, number in ms, or date string)
+ * @param options - Optional configuration
+ * @param options.anchor - Reference date for "ago" calculation (default: now)
+ * @param options.showSeconds - Whether to show seconds for very recent times
+ * @returns Human-readable relative time string
+ *
+ * @example
+ * ```ts
+ * formatTimestamp(Date.now() - 5 * 60 * 1000)  // "5m ago"
+ * formatTimestamp(Date.now() - 2.5 * 60 * 60 * 1000)  // "2h 30m ago"
+ * formatTimestamp(Date.now() - 3 * 24 * 60 * 60 * 1000)  // "3d 0h ago"
+ * ```
  */
-export declare const formatTimestamp: (timestamp: number | Date | string, { anchor, showSeconds, }?: {
+export declare const formatTimestamp: (timestamp: number | Date | string, options?: {
     anchor?: Date;
     showSeconds?: boolean;
 }) => string;
@@ -45,10 +84,21 @@ export declare const formatDuration: ({ start, until, }?: {
     start?: Date;
     until?: Date;
 }) => string;
+/**
+ * Format an absolute timestamp to a human-readable string
+ * @param timestamp - Unix timestamp in seconds or milliseconds (auto-detected)
+ * @param options - Intl.DateTimeFormatOptions for formatting
+ * @returns Formatted absolute timestamp string
+ */
+export declare const formatAbsoluteTimestamp: (timestamp: number | bigint, options?: Intl.DateTimeFormatOptions) => string;
 /**
  * Sleep for a given number of milliseconds
  * @param ms - The number of milliseconds to sleep
  * @returns A promise that resolves after the given number of milliseconds
  */
 export declare const sleep: (ms: number) => Promise<unknown>;
+/**
+ * Time resolution keys for aggregated statistics.
+ * Used by the indexer to bucket events by time period.
+ */
 export type TimeResolutionKey = "hour" | "day" | "month";