@oxyhq/core 1.0.0

package/dist/cjs/shared/utils/networkUtils.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Network Utility Functions
+ *
+ * Consolidated network utilities including circuit breaker pattern
+ * and exponential backoff for resilient API calls.
+ *
+ * @module shared/utils/networkUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = void 0;
+/**
+ * Default circuit breaker configuration.
+ */
+exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = {
+    baseInterval: 10000,
+    maxInterval: 60000,
+    maxFailures: 5,
+    recoveryTimeout: 30000,
+};
+/**
+ * Creates initial circuit breaker state.
+ *
+ * @param config - Optional custom configuration
+ * @returns Initial circuit breaker state
+ *
+ * @example
+ * ```ts
+ * const state = createCircuitBreakerState({ maxFailures: 3 });
+ * ```
+ */
+const createCircuitBreakerState = (config = {}) => {
+    const { baseInterval, maxInterval, maxFailures } = {
+        ...exports.DEFAULT_CIRCUIT_BREAKER_CONFIG,
+        ...config,
+    };
+    return {
+        consecutiveFailures: 0,
+        currentInterval: baseInterval,
+        baseInterval,
+        maxInterval,
+        maxFailures,
+        isOpen: false,
+    };
+};
+exports.createCircuitBreakerState = createCircuitBreakerState;
+/**
+ * Calculates next interval using exponential backoff.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Next interval in milliseconds
+ *
+ * @example
+ * ```ts
+ * const nextInterval = calculateBackoffInterval(state);
+ * await delay(nextInterval);
+ * ```
+ */
+const calculateBackoffInterval = (state) => {
+    const { consecutiveFailures, baseInterval, maxInterval } = state;
+    if (consecutiveFailures === 0)
+        return baseInterval;
+    const backoffMultiplier = Math.min(Math.pow(2, consecutiveFailures - 1), maxInterval / baseInterval);
+    return Math.min(baseInterval * backoffMultiplier, maxInterval);
+};
+exports.calculateBackoffInterval = calculateBackoffInterval;
+/**
+ * Records a failure and updates circuit breaker state.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Updated state after recording failure
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await apiCall();
+ *   state = recordSuccess(state);
+ * } catch (error) {
+ *   state = recordFailure(state);
+ * }
+ * ```
+ */
+const recordFailure = (state) => {
+    const newFailures = state.consecutiveFailures + 1;
+    const newInterval = (0, exports.calculateBackoffInterval)({
+        ...state,
+        consecutiveFailures: newFailures,
+    });
+    const shouldOpenCircuit = newFailures >= state.maxFailures;
+    const finalInterval = shouldOpenCircuit ? state.maxInterval : newInterval;
+    return {
+        ...state,
+        consecutiveFailures: newFailures,
+        currentInterval: finalInterval,
+        isOpen: shouldOpenCircuit,
+        openedAt: shouldOpenCircuit ? Date.now() : state.openedAt,
+    };
+};
+exports.recordFailure = recordFailure;
+/**
+ * Records a success and resets circuit breaker state.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Reset state after successful request
+ */
+const recordSuccess = (state) => {
+    return {
+        ...state,
+        consecutiveFailures: 0,
+        currentInterval: state.baseInterval,
+        isOpen: false,
+        openedAt: undefined,
+    };
+};
+exports.recordSuccess = recordSuccess;
+/**
+ * Checks if the circuit breaker should allow a request.
+ *
+ * When the circuit is open, it will only allow requests after
+ * the recovery timeout has passed (half-open state).
+ *
+ * @param state - Current circuit breaker state
+ * @param recoveryTimeout - Time to wait before allowing recovery attempts
+ * @returns true if request should be allowed
+ */
+const shouldAllowRequest = (state, recoveryTimeout = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG.recoveryTimeout) => {
+    if (!state.isOpen)
+        return true;
+    if (!state.openedAt)
+        return true;
+    const timeSinceOpen = Date.now() - state.openedAt;
+    return timeSinceOpen >= recoveryTimeout;
+};
+exports.shouldAllowRequest = shouldAllowRequest;
+/**
+ * Delays execution for a specified duration.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * ```ts
+ * await delay(1000); // Wait 1 second
+ * ```
+ */
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+exports.delay = delay;
+/**
+ * Executes a function with exponential backoff retry.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ * @throws Last error if all retries fail
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+const withRetry = async (fn, options = {}) => {
+    const { maxRetries = 3, baseDelay = 1000, maxDelay = 30000, shouldRetry = () => true, onRetry, } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxRetries || !shouldRetry(error)) {
+                throw error;
+            }
+            const delayMs = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+            onRetry?.(error, attempt + 1);
+            await (0, exports.delay)(delayMs);
+        }
+    }
+    throw lastError;
+};
+exports.withRetry = withRetry;

package/dist/cjs/shared/utils/themeUtils.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Theme Utility Functions
+ *
+ * Consolidated theme utilities for normalizing and handling color schemes
+ * across the OxyServices ecosystem.
+ *
+ * @module shared/utils/themeUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = void 0;
+/**
+ * Normalizes a theme value to ensure it's always 'light' or 'dark'.
+ *
+ * @param theme - Theme value (may be 'light' | 'dark' | string | undefined)
+ * @returns Normalized 'light' | 'dark' theme (defaults to 'light')
+ *
+ * @example
+ * ```ts
+ * normalizeTheme('dark');     // 'dark'
+ * normalizeTheme('light');    // 'light'
+ * normalizeTheme('unknown');  // 'light'
+ * normalizeTheme(undefined);  // 'light'
+ * normalizeTheme(null);       // 'light'
+ * ```
+ */
+const normalizeTheme = (theme) => theme === 'light' || theme === 'dark' ? theme : 'light';
+exports.normalizeTheme = normalizeTheme;
+/**
+ * Normalizes a color scheme value with optional fallback chain.
+ *
+ * Handles null/undefined cases from React Native's useColorScheme() hook
+ * with a proper fallback chain.
+ *
+ * @param colorScheme - The color scheme from useColorScheme() hook (may be null/undefined)
+ * @param theme - Optional theme prop as fallback
+ * @returns Normalized 'light' | 'dark' color scheme
+ *
+ * @example
+ * ```ts
+ * // In a React Native component:
+ * const systemScheme = useColorScheme(); // might be null
+ * const colorScheme = normalizeColorScheme(systemScheme, props.theme);
+ *
+ * normalizeColorScheme('dark', 'light');      // 'dark'
+ * normalizeColorScheme(null, 'dark');         // 'dark'
+ * normalizeColorScheme(undefined, undefined); // 'light'
+ * ```
+ */
+const normalizeColorScheme = (colorScheme, theme) => {
+    if (colorScheme === 'light' || colorScheme === 'dark') {
+        return colorScheme;
+    }
+    if (theme === 'light' || theme === 'dark') {
+        return theme;
+    }
+    return 'light';
+};
+exports.normalizeColorScheme = normalizeColorScheme;
+/**
+ * Gets the opposite theme value.
+ *
+ * @param theme - Current theme value
+ * @returns The opposite theme ('light' → 'dark', 'dark' → 'light')
+ *
+ * @example
+ * ```ts
+ * getOppositeTheme('light'); // 'dark'
+ * getOppositeTheme('dark');  // 'light'
+ * ```
+ */
+const getOppositeTheme = (theme) => theme === 'light' ? 'dark' : 'light';
+exports.getOppositeTheme = getOppositeTheme;
+/**
+ * Checks if the system prefers dark mode.
+ *
+ * This function only works in browser environments.
+ * Returns false in non-browser environments (Node.js, React Native).
+ *
+ * @returns true if system prefers dark mode, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (systemPrefersDarkMode()) {
+ *   setTheme('dark');
+ * }
+ * ```
+ */
+const systemPrefersDarkMode = () => {
+    if (typeof window === 'undefined')
+        return false;
+    return window.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false;
+};
+exports.systemPrefersDarkMode = systemPrefersDarkMode;
+/**
+ * Gets the system's preferred color scheme.
+ *
+ * @returns 'dark' if system prefers dark mode, 'light' otherwise
+ *
+ * @example
+ * ```ts
+ * const theme = getSystemColorScheme();
+ * ```
+ */
+const getSystemColorScheme = () => (0, exports.systemPrefersDarkMode)() ? 'dark' : 'light';
+exports.getSystemColorScheme = getSystemColorScheme;

package/dist/cjs/utils/apiUtils.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Utility functions for common API patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSearchParams = buildSearchParams;
+exports.buildUrl = buildUrl;
+exports.buildPaginationParams = buildPaginationParams;
+exports.safeJsonParse = safeJsonParse;
+/**
+ * Build URL search parameters from an object
+ * @param params Object with parameter key-value pairs
+ * @returns URLSearchParams instance
+ */
+function buildSearchParams(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+            searchParams.append(key, value.toString());
+        }
+    }
+    return searchParams;
+}
+/**
+ * Build URL with search parameters
+ * @param baseUrl Base URL
+ * @param params Object with parameter key-value pairs
+ * @returns Complete URL with search parameters
+ */
+function buildUrl(baseUrl, params) {
+    if (!params)
+        return baseUrl;
+    const searchParams = buildSearchParams(params);
+    const queryString = searchParams.toString();
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}
+/**
+ * Build pagination search parameters
+ * @param params Pagination parameters
+ * @returns URLSearchParams with pagination
+ */
+function buildPaginationParams(params) {
+    return buildSearchParams(params);
+}
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+function safeJsonParse(data, fallback) {
+    if (typeof data === 'string') {
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return data;
+}

package/dist/cjs/utils/asyncUtils.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delay = void 0;
+exports.withErrorHandling = withErrorHandling;
+exports.parallelWithErrorHandling = parallelWithErrorHandling;
+exports.retryAsync = retryAsync;
+exports.debounceAsync = debounceAsync;
+exports.throttleAsync = throttleAsync;
+exports.sequentialWithProgress = sequentialWithProgress;
+exports.batchAsync = batchAsync;
+exports.createCancellableAsync = createCancellableAsync;
+exports.withTimeout = withTimeout;
+exports.withLoadingState = withLoadingState;
+exports.retryOnError = retryOnError;
+const loggerUtils_1 = require("./loggerUtils");
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+async function withErrorHandling(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (errorHandler) {
+            errorHandler(error);
+        }
+        else {
+            loggerUtils_1.logger.error(`Error in ${context || 'operation'}`, error instanceof Error ? error : new Error(String(error)), {
+                component: 'asyncUtils',
+                method: 'withErrorHandling',
+            });
+        }
+        return null;
+    }
+}
+/**
+ * Execute multiple async operations in parallel with error handling
+ */
+async function parallelWithErrorHandling(operations, errorHandler) {
+    const results = await Promise.allSettled(operations.map((op, index) => withErrorHandling(op, error => errorHandler?.(error, index))));
+    return results.map(result => result.status === 'fulfilled' ? result.value : null);
+}
+/**
+ * Retry an async operation with exponential backoff
+ *
+ * By default, does not retry on 4xx errors (client errors).
+ * Use shouldRetry callback to customize retry behavior.
+ */
+async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, shouldRetry) {
+    let lastError;
+    // Default shouldRetry: don't retry on 4xx errors
+    const defaultShouldRetry = (error) => {
+        // Don't retry on 4xx errors (client errors)
+        if (error?.response?.status >= 400 && error?.response?.status < 500) {
+            return false;
+        }
+        return true;
+    };
+    const retryCheck = shouldRetry || defaultShouldRetry;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxRetries) {
+                break;
+            }
+            if (!retryCheck(error)) {
+                break;
+            }
+            // Calculate delay with exponential backoff and jitter
+            const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Debounce async function calls
+ */
+function debounceAsync(func, delay) {
+    let timeoutId;
+    const lastPromise = null;
+    return (...args) => {
+        return new Promise((resolve, reject) => {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(async () => {
+                try {
+                    const result = await func(...args);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }, delay);
+        });
+    };
+}
+/**
+ * Throttle async function calls
+ */
+function throttleAsync(func, limit, interval) {
+    let inThrottle = false;
+    let lastPromise = null;
+    return (...args) => {
+        if (inThrottle) {
+            return lastPromise;
+        }
+        inThrottle = true;
+        lastPromise = func(...args);
+        setTimeout(() => {
+            inThrottle = false;
+        }, interval);
+        return lastPromise;
+    };
+}
+/**
+ * Execute async operations sequentially with progress tracking
+ */
+async function sequentialWithProgress(operations, onProgress) {
+    const results = [];
+    for (let i = 0; i < operations.length; i++) {
+        const result = await operations[i]();
+        results.push(result);
+        onProgress?.(i + 1, operations.length);
+    }
+    return results;
+}
+/**
+ * Batch async operations
+ */
+async function batchAsync(items, batchSize, processor) {
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        await processor(batch);
+    }
+}
+/**
+ * Create a cancellable async operation
+ */
+function createCancellableAsync(operation) {
+    let abortController = null;
+    return {
+        execute: async () => {
+            abortController = new AbortController();
+            return await operation(abortController.signal);
+        },
+        cancel: () => {
+            abortController?.abort();
+        }
+    };
+}
+/**
+ * Timeout wrapper for async operations
+ */
+async function withTimeout(operation, timeoutMs, timeoutMessage) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error(timeoutMessage || `Operation timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    return Promise.race([operation, timeoutPromise]);
+}
+/**
+ * Execute async operation with loading state
+ */
+async function withLoadingState(operation, setLoading) {
+    setLoading(true);
+    try {
+        return await operation();
+    }
+    finally {
+        setLoading(false);
+    }
+}
+/**
+ * Create a promise that resolves after a delay
+ */
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+exports.delay = delay;
+/**
+ * Execute async operation with retry on specific errors
+ */
+async function retryOnError(operation, retryableErrors, maxRetries = 3) {
+    return retryAsync(operation, maxRetries, 1000, (error) => {
+        const errorCode = error?.code || error?.status || error?.message;
+        return retryableErrors.includes(errorCode);
+    });
+}