@tetherto/mdk-react-devkit 0.0.0 → 0.12.1

package/dist/primitives/utils/string.js

@@ -0,0 +1,106 @@
+/**
+ * String utilities
+ *
+ * Pure functions for string parsing, transformation, and extraction.
+ */
+// ============================================================================
+// Auth Token Parsing
+// ============================================================================
+/**
+ * Parse an auth token string to extract role names
+ *
+ * @example
+ * ```ts
+ * getRolesFromAuthToken('...roles:admin:viewer:...')
+ * // ['admin', 'viewer']
+ * ```
+ */
+export const getRolesFromAuthToken = (authToken) => {
+    if (!authToken)
+        return [];
+    const rolesMatch = authToken.match(/roles:([a-z_*:]*)/);
+    if (!rolesMatch?.[1])
+        return [];
+    return rolesMatch[1].split(':').filter(Boolean);
+};
+// ============================================================================
+// Location String Parsing
+// ============================================================================
+/**
+ * Format a dot-separated location string into a readable label
+ *
+ * @example
+ * ```ts
+ * getLocationLabel('site_a.lab_1')  // "Site A Lab 1"
+ * getLocationLabel(null)            // "Unknown"
+ * getLocationLabel('unknown')       // "Unknown"
+ * ```
+ */
+export const getLocationLabel = (location) => {
+    if (location == null || location === 'unknown') {
+        return 'Unknown';
+    }
+    return location
+        .split('.')
+        .join(' ')
+        .replace(/[_-]+/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(' ');
+};
+/**
+ * Get the major (site) part of a "site.location" string
+ *
+ * @example
+ * ```ts
+ * getMajorLocation('site-a.lab_1')  // "site-a"
+ * getMajorLocation('invalid')        // "unknown"
+ * ```
+ */
+export const getMajorLocation = (location) => {
+    const parts = location.split('.');
+    if (parts.length !== 2) {
+        return 'unknown';
+    }
+    return parts[0];
+};
+/**
+ * Get the minor (sub-location) part of a "site.location" string
+ *
+ * @example
+ * ```ts
+ * getMinorLocation('site-a.lab_1')  // "lab_1"
+ * getMinorLocation('invalid')        // "unknown"
+ * ```
+ */
+export const getMinorLocation = (location) => {
+    const parts = location.split('.');
+    if (parts.length !== 2) {
+        return 'unknown';
+    }
+    return parts[1];
+};
+// ============================================================================
+// Color String Utilities
+// ============================================================================
+/**
+ * Normalize a hex color by removing the leading `#`
+ *
+ * @example
+ * ```ts
+ * normalizeHexColor('#ff0000')  // "ff0000"
+ * normalizeHexColor('ff0000')   // "ff0000"
+ * ```
+ */
+export const normalizeHexColor = (color) => color.startsWith('#') ? color.slice(1) : color;
+/**
+ * Safely converts unknown value to string for display
+ * Returns empty string if value is null or undefined
+ */
+export const safeString = (value) => {
+    if (value == null) {
+        return '';
+    }
+    return String(value);
+};

package/dist/primitives/utils/time.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Time range and interval utilities
+ *
+ * Pure functions for working with time ranges, intervals, and periods.
+ */
+import { add } from 'date-fns/add';
+import type { TimeInterval } from './types';
+export declare const TimeRangeTypes: {
+    readonly DAY: 'day';
+    readonly MINUTE: 'minute';
+};
+export type TimeRangeType = (typeof TimeRangeTypes)[keyof typeof TimeRangeTypes];
+/**
+ * Determine whether a time span is best represented in day or minute resolution
+ *
+ * @returns `'minute'` if range is within 24 hours, otherwise `'day'`
+ */
+export declare const getTimeRange: (latestTimeStampMs: number | undefined, oldTimeStampMs: number | undefined) => TimeRangeType;
+/**
+ * Break a time range into equal intervals
+ *
+ * @param start - Start timestamp in milliseconds
+ * @param end - End timestamp in milliseconds
+ * @param intervalMs - Interval size in milliseconds
+ * @returns Array of intervals with start and end timestamps
+ *
+ * @example
+ * ```ts
+ * const oneHourMs = 3_600_000
+ * breakTimeIntoIntervals(0, 7_200_000, oneHourMs)
+ * // [{ start: 0, end: 3600000 }, { start: 3600000, end: 7200000 }]
+ * ```
+ */
+export declare const breakTimeIntoIntervals: (start: number, end: number, intervalMs: number) => TimeInterval[];
+/**
+ * Find the smallest start and largest end from an array of time ranges
+ *
+ * @returns Object with `start` (smallest) and `end` (largest), or nulls if empty
+ */
+export declare const getSmallestAndLargestTs: (array: TimeInterval[]) => {
+    start: number | null;
+    end: number | null;
+};
+/**
+ * Get a time range covering the last N days, ending at end of yesterday
+ *
+ * Useful for reports that exclude the current (incomplete) day.
+ *
+ * @param days - Number of days to include in the range (default: 7)
+ * @param referenceDate - Reference date to calculate from (default: current date)
+ *
+ * @example
+ * ```ts
+ * getLastNDaysEndingYesterday(7)  // Last 7 days ending at 23:59:59.999 yesterday
+ * ```
+ */
+export declare const getLastNDaysEndingYesterday: (days?: number, referenceDate?: Date) => TimeInterval;
+/**
+ * Generator that iterates over timestamps from startTs to endTs
+ * separated by a given duration
+ *
+ * @param startTs - Start timestamp in milliseconds
+ * @param endTs - End timestamp in milliseconds
+ * @param duration - date-fns Duration object
+ *
+ * @example
+ * ```ts
+ * for (const ts of timeRangeWalker(start, end, { hours: 1 })) {
+ *   console.log(new Date(ts))
+ * }
+ * ```
+ */
+export declare const timeRangeWalker: (startTs: number, endTs: number, duration: Parameters<typeof add>[1]) => Generator<number>;
+/**
+ * Convert seconds to milliseconds
+ *
+ * @param seconds - Number of seconds
+ * @returns Equivalent number of milliseconds
+ *
+ * @example
+ * ```ts
+ * secondsToMs(60)  // 60000
+ * ```
+ */
+export declare const secondsToMs: (seconds: number) => number;

package/dist/primitives/utils/time.js

@@ -0,0 +1,135 @@
+/**
+ * Time range and interval utilities
+ *
+ * Pure functions for working with time ranges, intervals, and periods.
+ */
+import { add } from 'date-fns/add';
+import { endOfDay } from 'date-fns/endOfDay';
+import { startOfDay } from 'date-fns/startOfDay';
+import { subDays } from 'date-fns/subDays';
+// ============================================================================
+// Time Range Types
+// ============================================================================
+export const TimeRangeTypes = {
+    DAY: 'day',
+    MINUTE: 'minute',
+};
+// ============================================================================
+// Time Range Helpers
+// ============================================================================
+/**
+ * Determine whether a time span is best represented in day or minute resolution
+ *
+ * @returns `'minute'` if range is within 24 hours, otherwise `'day'`
+ */
+export const getTimeRange = (latestTimeStampMs, oldTimeStampMs) => {
+    if (!latestTimeStampMs || !oldTimeStampMs) {
+        return TimeRangeTypes.DAY;
+    }
+    const range = latestTimeStampMs - oldTimeStampMs;
+    // If range is 0 (single data point), default to DAY
+    if (range === 0) {
+        return TimeRangeTypes.DAY;
+    }
+    return range <= 24 * 60 * 60 * 1000 ? TimeRangeTypes.MINUTE : TimeRangeTypes.DAY;
+};
+/**
+ * Break a time range into equal intervals
+ *
+ * @param start - Start timestamp in milliseconds
+ * @param end - End timestamp in milliseconds
+ * @param intervalMs - Interval size in milliseconds
+ * @returns Array of intervals with start and end timestamps
+ *
+ * @example
+ * ```ts
+ * const oneHourMs = 3_600_000
+ * breakTimeIntoIntervals(0, 7_200_000, oneHourMs)
+ * // [{ start: 0, end: 3600000 }, { start: 3600000, end: 7200000 }]
+ * ```
+ */
+export const breakTimeIntoIntervals = (start, end, intervalMs) => {
+    const totalIntervals = Math.ceil((end - start) / intervalMs);
+    return Array.from({ length: totalIntervals }, (_, i) => {
+        const intervalStart = start + i * intervalMs;
+        const intervalEnd = Math.min(intervalStart + intervalMs, end);
+        return { start: intervalStart, end: intervalEnd };
+    });
+};
+/**
+ * Find the smallest start and largest end from an array of time ranges
+ *
+ * @returns Object with `start` (smallest) and `end` (largest), or nulls if empty
+ */
+export const getSmallestAndLargestTs = (array) => {
+    if (array.length === 0) {
+        return { start: null, end: null };
+    }
+    let minStart = array[0].start;
+    let maxEnd = array[0].end;
+    for (const item of array) {
+        if (item.start < minStart)
+            minStart = item.start;
+        if (item.end > maxEnd)
+            maxEnd = item.end;
+    }
+    return { start: minStart, end: maxEnd };
+};
+/**
+ * Get a time range covering the last N days, ending at end of yesterday
+ *
+ * Useful for reports that exclude the current (incomplete) day.
+ *
+ * @param days - Number of days to include in the range (default: 7)
+ * @param referenceDate - Reference date to calculate from (default: current date)
+ *
+ * @example
+ * ```ts
+ * getLastNDaysEndingYesterday(7)  // Last 7 days ending at 23:59:59.999 yesterday
+ * ```
+ */
+export const getLastNDaysEndingYesterday = (days = 7, referenceDate = new Date()) => {
+    const yesterday = subDays(referenceDate, 1);
+    const start = startOfDay(subDays(yesterday, days - 1)).getTime();
+    const end = endOfDay(yesterday).getTime();
+    return { start, end };
+};
+/**
+ * Generator that iterates over timestamps from startTs to endTs
+ * separated by a given duration
+ *
+ * @param startTs - Start timestamp in milliseconds
+ * @param endTs - End timestamp in milliseconds
+ * @param duration - date-fns Duration object
+ *
+ * @example
+ * ```ts
+ * for (const ts of timeRangeWalker(start, end, { hours: 1 })) {
+ *   console.log(new Date(ts))
+ * }
+ * ```
+ */
+export const timeRangeWalker = function* (startTs, endTs, duration) {
+    if (!startTs || !endTs) {
+        throw new Error('startTs and endTs must be provided');
+    }
+    let currentTs = startTs;
+    yield currentTs;
+    while (currentTs <= endTs) {
+        const currentDate = new Date(currentTs);
+        currentTs = add(currentDate, duration).valueOf();
+        yield currentTs;
+    }
+};
+/**
+ * Convert seconds to milliseconds
+ *
+ * @param seconds - Number of seconds
+ * @returns Equivalent number of milliseconds
+ *
+ * @example
+ * ```ts
+ * secondsToMs(60)  // 60000
+ * ```
+ */
+export const secondsToMs = (seconds) => seconds * 1000;

package/dist/primitives/utils/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared type definitions for utility functions
+ */
+export type ValueUnit = {
+    value: number | string | null;
+    unit: string;
+    realValue: number;
+};
+export type HashrateUnit = ValueUnit & {
+    unit: string;
+};
+export type CurrencyUnit = ValueUnit & {
+    unit: string;
+};
+export type UnitLabel = 'decimal' | 'k' | 'M' | 'G' | 'T' | 'P';
+export type ErrorWithTimestamp = {
+    msg?: string;
+    message?: string;
+    timestamp?: number | string;
+};
+export type TimeRangeFormatted = {
+    start: string;
+    end: string;
+    formatted: string;
+};
+export type TimeInterval = {
+    start: number;
+    end: number;
+};
+export type WeightedAverageResult = {
+    avg: number;
+    totalWeight: number;
+    weightedValue: number;
+};
+export type WeightedDataPoint = {
+    value: number;
+    weight: number;
+};
+export type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea';
+export type CurtailmentResult = {
+    curtailmentMWh: number;
+    curtailmentRate: number;
+};
+export type TransactionEntry = {
+    changed_balance?: number;
+    satoshis_net_earned?: number;
+    fees_colected_satoshis?: number;
+    mining_extra?: {
+        tx_fee?: number;
+    };
+};
+export type TransactionSum = {
+    revenueBTC: number;
+    feesBTC: number;
+};

package/dist/primitives/utils/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared type definitions for utility functions
+ */
+export {};

package/dist/primitives/utils/validation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Validation utilities
+ */
+/**
+ * Check if value is empty
+ */
+export declare const isEmpty: (value: unknown) => boolean;
+/**
+ * Validate email
+ */
+export declare const isValidEmail: (email: string) => boolean;
+/**
+ * Validate URL
+ */
+export declare const isValidUrl: (url: string) => boolean;
+/**
+ * Check if a value is null or undefined
+ */
+export declare const isNil: (value: unknown) => value is null | undefined;
+/**
+ * Check if value is a plain object (not array, not null, not Date, not RegExp)
+ */
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;

package/dist/primitives/utils/validation.js

@@ -0,0 +1,56 @@
+/**
+ * Validation utilities
+ */
+/**
+ * Check if value is empty
+ */
+export const isEmpty = (value) => {
+    if (value == null)
+        return true;
+    if (typeof value === 'string')
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length === 0;
+    return false;
+};
+/**
+ * Validate email
+ */
+export const isValidEmail = (email) => {
+    const emailRegex = /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/;
+    return emailRegex.test(email);
+};
+/**
+ * Validate URL
+ */
+export const isValidUrl = (url) => {
+    try {
+        // oxlint-disable-next-line no-new
+        new URL(url);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Check if a value is null or undefined
+ */
+export const isNil = (value) => {
+    return value === null || value === undefined;
+};
+/**
+ * Check if value is a plain object (not array, not null, not Date, not RegExp)
+ */
+export const isPlainObject = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    // Exclude Date and RegExp objects
+    if (value instanceof Date || value instanceof RegExp) {
+        return false;
+    }
+    return true;
+};