typeferry 0.6.0

package/dist/client/idle-timer.js

@@ -0,0 +1,101 @@
+import { throttle } from '../utils/lodash.js';
+import { ClientEvents, Environment } from '../utils/index.js';
+const ACTIVITY_EVENTS = [
+    'focus',
+    'mousemove',
+    'mousedown',
+    'keydown',
+    'scroll',
+    'touchstart',
+    'pageshow',
+    'pagehide',
+];
+/**
+ * Disconnects the client after a period of inactivity.
+ * Only instantiated when `idlenessTimeout` is configured.
+ *
+ * Extracted from the former IdleTimeout class to isolate idle-disconnect
+ * logic from visibility-based reconnection (now in VisibilityManager).
+ */
+export class IdleTimer {
+    client;
+    timeout;
+    timerId = null;
+    resetHandler = null;
+    constructor(client, timeout) {
+        this.client = client;
+        this.timeout = timeout;
+        this.setup();
+    }
+    /** Starts the idle countdown. Fires `client.close()` when it expires. */
+    start() {
+        if (typeof this.timeout !== 'number')
+            return;
+        if (!Environment.isBrowser && !Environment.isTest)
+            return;
+        this.timerId = setTimeout(() => {
+            this.client.close();
+            if (this.client.options?.debug) {
+                console.log('TypeFerry: Disconnected due to inactivity');
+            }
+        }, this.timeout);
+    }
+    /** Clears the current idle countdown. */
+    stop() {
+        if (this.timerId) {
+            clearTimeout(this.timerId);
+            this.timerId = null;
+        }
+    }
+    /**
+     * Resets the idle timer and reconnects if the socket is disconnected.
+     * Called on user activity (mousemove, keydown, etc.).
+     *
+     * Only reconnects if the socket is actually down — does NOT force
+     * reconnection when initialized=false, which would create loops.
+     */
+    /**
+     * Resets the idle timer and reconnects if the socket is disconnected.
+     * Defers restarting the idle countdown until after the connection is
+     * established to prevent the timer from firing mid-reconnect.
+     */
+    async reset() {
+        this.stop();
+        const socket = this.client.clientSocket.socket;
+        if (socket?.readyState === WebSocket.OPEN) {
+            this.start();
+            return;
+        }
+        this.client.clientSocket.connect();
+        await this.client.waitFor(ClientEvents.WEBSOCKET_CONNECTED, 10000);
+        this.start();
+    }
+    /** Removes all event listeners and cleans up resources. */
+    destroy() {
+        this.stop();
+        if (this.resetHandler) {
+            this.resetHandler.cancel();
+        }
+        if (typeof window !== 'undefined' && this.resetHandler) {
+            for (const event of ACTIVITY_EVENTS) {
+                window.removeEventListener(event, this.resetHandler);
+            }
+        }
+        this.resetHandler = null;
+    }
+    setup() {
+        this.client.on(ClientEvents.CLOSE, () => this.stop());
+        // Defer the first start so the constructor completes first
+        setTimeout(() => this.start(), 0);
+        if (typeof window === 'undefined')
+            return;
+        this.resetHandler = throttle(this.reset.bind(this), this.timeout / 2, {
+            leading: true,
+            trailing: true,
+        });
+        for (const event of ACTIVITY_EVENTS) {
+            window.addEventListener(event, this.resetHandler);
+        }
+    }
+}
+//# sourceMappingURL=idle-timer.js.map

package/dist/client/idle-timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-timer.js","sourceRoot":"","sources":["../../src/client/idle-timer.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+export * from './client.js';
+export * from './client-channel.js';
+export * from './client-http.js';
+export * from './client-socket.js';
+export * from './context-manager.js';
+export * from './logger.js';

package/dist/client/index.js

@@ -0,0 +1,7 @@
+export * from './client.js';
+export * from './client-channel.js';
+export * from './client-http.js';
+export * from './client-socket.js';
+export * from './context-manager.js';
+export * from './logger.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,UAAU,CAAA"}

package/dist/client/logger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Centralized logging for TypeFerry client.
+ * Provides structured logging with categories and levels for easier debugging.
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+export declare enum LogCategory {
+    CONNECTION = "connection",
+    AUTH = "auth",
+    METHOD = "method",
+    SUBSCRIPTION = "subscription",
+    CHANNEL = "channel"
+}
+export interface LogEntry {
+    level: LogLevel;
+    category: LogCategory;
+    message: string;
+    context?: Record<string, unknown>;
+    error?: Error;
+    timestamp: number;
+}
+export type LogListener = (entry: LogEntry) => void;
+/**
+ * Logger for TypeFerry client with structured logging support.
+ *
+ * @example
+ * ```ts
+ * const logger = new TypeFerryLogger()
+ * logger.setLevel(LogLevel.DEBUG)
+ *
+ * // Subscribe to all logs
+ * const unsubscribe = logger.onLog(entry => {
+ *   // Send to external service
+ * })
+ *
+ * // Log with context
+ * logger.method(LogLevel.ERROR, 'Method call failed', {
+ *   method: 'boards.get',
+ *   timeout: 30000,
+ * })
+ * ```
+ */
+export declare class TypeFerryLogger {
+    private level;
+    private listeners;
+    /**
+     * Set the minimum log level. Messages below this level are ignored.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current log level.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Subscribe to log entries.
+     * Returns an unsubscribe function.
+     */
+    onLog(listener: LogListener): () => void;
+    /**
+     * Core logging method.
+     */
+    log(entry: Omit<LogEntry, 'timestamp'>): void;
+    private output;
+    connection(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error): void;
+    auth(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error): void;
+    method(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error): void;
+    subscription(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error): void;
+    channel(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error): void;
+}
+/** Shared logger instance for the TypeFerry client. */
+export declare const logger: TypeFerryLogger;

package/dist/client/logger.js

@@ -0,0 +1,129 @@
+/**
+ * Centralized logging for TypeFerry client.
+ * Provides structured logging with categories and levels for easier debugging.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+export var LogCategory;
+(function (LogCategory) {
+    LogCategory["CONNECTION"] = "connection";
+    LogCategory["AUTH"] = "auth";
+    LogCategory["METHOD"] = "method";
+    LogCategory["SUBSCRIPTION"] = "subscription";
+    LogCategory["CHANNEL"] = "channel";
+})(LogCategory || (LogCategory = {}));
+/**
+ * Logger for TypeFerry client with structured logging support.
+ *
+ * @example
+ * ```ts
+ * const logger = new TypeFerryLogger()
+ * logger.setLevel(LogLevel.DEBUG)
+ *
+ * // Subscribe to all logs
+ * const unsubscribe = logger.onLog(entry => {
+ *   // Send to external service
+ * })
+ *
+ * // Log with context
+ * logger.method(LogLevel.ERROR, 'Method call failed', {
+ *   method: 'boards.get',
+ *   timeout: 30000,
+ * })
+ * ```
+ */
+export class TypeFerryLogger {
+    level = LogLevel.WARN;
+    listeners = new Set();
+    /**
+     * Set the minimum log level. Messages below this level are ignored.
+     */
+    setLevel(level) {
+        this.level = level;
+    }
+    /**
+     * Get the current log level.
+     */
+    getLevel() {
+        return this.level;
+    }
+    /**
+     * Subscribe to log entries.
+     * Returns an unsubscribe function.
+     */
+    onLog(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Core logging method.
+     */
+    log(entry) {
+        if (entry.level < this.level)
+            return;
+        const fullEntry = { ...entry, timestamp: Date.now() };
+        this.output(fullEntry);
+        this.listeners.forEach(listener => listener(fullEntry));
+    }
+    output(entry) {
+        const prefix = `[TypeFerry:${entry.category}]`;
+        const args = [prefix, entry.message];
+        if (entry.context)
+            args.push(entry.context);
+        if (entry.error)
+            args.push(entry.error);
+        switch (entry.level) {
+            case LogLevel.DEBUG:
+                console.debug(...args);
+                break;
+            case LogLevel.INFO:
+                console.log(...args);
+                break;
+            case LogLevel.WARN:
+                console.warn(...args);
+                break;
+            case LogLevel.ERROR:
+                console.error(...args);
+                break;
+        }
+    }
+    // Category-specific convenience methods
+    connection(level, message, context, error) {
+        this.log({
+            level,
+            category: LogCategory.CONNECTION,
+            message,
+            context,
+            error,
+        });
+    }
+    auth(level, message, context, error) {
+        this.log({ level, category: LogCategory.AUTH, message, context, error });
+    }
+    method(level, message, context, error) {
+        this.log({ level, category: LogCategory.METHOD, message, context, error });
+    }
+    subscription(level, message, context, error) {
+        this.log({
+            level,
+            category: LogCategory.SUBSCRIPTION,
+            message,
+            context,
+            error,
+        });
+    }
+    channel(level, message, context, error) {
+        this.log({ level, category: LogCategory.CHANNEL, message, context, error });
+    }
+}
+/** Shared logger instance for the TypeFerry client. */
+export const logger = new TypeFerryLogger();
+//# sourceMappingURL=logger.js.map

package/dist/client/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/client/logger.ts"],"names":[],"mappings":"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"}

package/dist/client/visibility-manager.d.ts

@@ -0,0 +1,62 @@
+import type { Client } from './client.js';
+import type { IdleTimer } from './idle-timer.js';
+/**
+ * Handles tab visibility changes and reconnects after browser/OS sleep.
+ * Always instantiated — visibility recovery is always active regardless
+ * of whether idle timeout is configured.
+ *
+ * Uses both `visibilitychange` events and a setInterval heartbeat to
+ * detect sleep. macOS may not fire `visibilitychange` before idle-triggered
+ * sleep, so the heartbeat catches gaps the event misses.
+ */
+export declare class VisibilityManager {
+    private client;
+    private idleTimer;
+    /**
+     * Optional async hook called before reconnecting after tab visibility restore.
+     * Used by the auth system to proactively refresh expired access tokens so the
+     * socket reconnects with a valid token instead of failing auth first.
+     */
+    onBeforeReconnect: (() => Promise<void>) | null;
+    private visibilityHandler;
+    private hiddenAt;
+    private heartbeatTimer;
+    private lastHeartbeat;
+    /**
+     * Guards against duplicate reconnects when both the heartbeat and
+     * visibilitychange fire in quick succession after wake.
+     */
+    private reconnecting;
+    constructor(client: Client, idleTimer: IdleTimer | null);
+    /**
+     * Tears down the existing socket and creates a fresh connection.
+     * After tab sleep, the socket may be in a stale state — so we always
+     * do a full cleanup before reconnecting.
+     */
+    reconnect(): void;
+    /** Removes all listeners and timers to prevent memory leaks. */
+    destroy(): void;
+    private setup;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private handlePageHide;
+    /**
+     * Unified entry point for sleep detection from both the heartbeat
+     * timer and `visibilitychange`. Uses `reconnecting` to prevent
+     * duplicate reconnects when both fire after wake.
+     */
+    private handleSleepDetected;
+    /**
+     * Runs the pre-reconnect hook with bounded retries (WiFi may take
+     * seconds to reconnect after wake), then reconnects. Falls back to
+     * reconnecting even if all retry attempts fail.
+     */
+    private runHookAndReconnect;
+    /**
+     * Determines whether reconnection is needed and triggers it. Routes
+     * through `handleSleepDetected` for deduplication with the heartbeat.
+     */
+    private handlePageVisible;
+    /** Promisified delay for hook retry backoff. */
+    private delay;
+}

package/dist/client/visibility-manager.js

@@ -0,0 +1,177 @@
+import { ClientEvents } from '../utils/index.js';
+/**
+ * Time threshold below which we trust the socket connection is healthy.
+ * If hidden for less than this, we only reconnect if the socket is actually
+ * disconnected.
+ */
+const FORCE_RECONNECT_THRESHOLD = 60 * 60 * 1000; // 1 hour
+/** Heartbeat fires every 30s to detect OS sleep gaps. */
+const HEARTBEAT_INTERVAL_MS = 30_000;
+/** If the gap between heartbeats exceeds 2x the interval, we were sleeping. */
+const HEARTBEAT_THRESHOLD_MS = 60_000;
+/** Max retry attempts for the pre-reconnect hook (network may not be ready on wake). */
+const HOOK_RETRY_ATTEMPTS = 3;
+/** Delay between hook retry attempts in ms. */
+const HOOK_RETRY_DELAY_MS = 2_000;
+/**
+ * Handles tab visibility changes and reconnects after browser/OS sleep.
+ * Always instantiated — visibility recovery is always active regardless
+ * of whether idle timeout is configured.
+ *
+ * Uses both `visibilitychange` events and a setInterval heartbeat to
+ * detect sleep. macOS may not fire `visibilitychange` before idle-triggered
+ * sleep, so the heartbeat catches gaps the event misses.
+ */
+export class VisibilityManager {
+    client;
+    idleTimer;
+    /**
+     * Optional async hook called before reconnecting after tab visibility restore.
+     * Used by the auth system to proactively refresh expired access tokens so the
+     * socket reconnects with a valid token instead of failing auth first.
+     */
+    onBeforeReconnect = null;
+    visibilityHandler = null;
+    hiddenAt = null;
+    heartbeatTimer = null;
+    lastHeartbeat = Date.now();
+    /**
+     * Guards against duplicate reconnects when both the heartbeat and
+     * visibilitychange fire in quick succession after wake.
+     */
+    reconnecting = false;
+    constructor(client, idleTimer) {
+        this.client = client;
+        this.idleTimer = idleTimer;
+        this.setup();
+    }
+    /**
+     * Tears down the existing socket and creates a fresh connection.
+     * After tab sleep, the socket may be in a stale state — so we always
+     * do a full cleanup before reconnecting.
+     */
+    reconnect() {
+        const wasInitialized = this.client.initialized;
+        this.client.initialized = false;
+        this.client.initializing = false;
+        const existingSocket = this.client.clientSocket.socket;
+        if (existingSocket) {
+            existingSocket.close();
+            this.client.clientSocket.socket = undefined;
+        }
+        this.client.clientSocket.connect();
+        this.lastHeartbeat = Date.now();
+        this.reconnecting = false;
+        if (wasInitialized) {
+            this.client.emit(ClientEvents.WEBSOCKET_RECONNECTING);
+        }
+    }
+    /** Removes all listeners and timers to prevent memory leaks. */
+    destroy() {
+        if (typeof document !== 'undefined' && this.visibilityHandler) {
+            document.removeEventListener('visibilitychange', this.visibilityHandler);
+        }
+        this.visibilityHandler = null;
+        this.stopHeartbeat();
+    }
+    setup() {
+        if (typeof window === 'undefined')
+            return;
+        this.visibilityHandler = () => {
+            if (document.visibilityState === 'hidden') {
+                this.hiddenAt = Date.now();
+                this.handlePageHide();
+            }
+            else if (document.visibilityState === 'visible') {
+                this.handlePageVisible();
+            }
+        };
+        document.addEventListener('visibilitychange', this.visibilityHandler);
+        this.startHeartbeat();
+    }
+    startHeartbeat() {
+        this.lastHeartbeat = Date.now();
+        this.heartbeatTimer = setInterval(() => {
+            const now = Date.now();
+            const gap = now - this.lastHeartbeat;
+            this.lastHeartbeat = now;
+            if (gap > HEARTBEAT_THRESHOLD_MS) {
+                this.handleSleepDetected('heartbeat', gap);
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    handlePageHide() {
+        if (this.client.options?.ws?.disconnectOnPageHide) {
+            this.client.close();
+            if (this.client.options?.debug) {
+                console.log('TypeFerry: Disconnected on page hide');
+            }
+        }
+    }
+    /**
+     * Unified entry point for sleep detection from both the heartbeat
+     * timer and `visibilitychange`. Uses `reconnecting` to prevent
+     * duplicate reconnects when both fire after wake.
+     */
+    handleSleepDetected(source, durationMs) {
+        if (this.reconnecting)
+            return;
+        this.reconnecting = true;
+        if (this.client.options?.debug) {
+            console.log(`TypeFerry: Sleep detected via ${source} (${Math.round(durationMs / 1000)}s gap), reconnecting`);
+        }
+        this.runHookAndReconnect();
+    }
+    /**
+     * Runs the pre-reconnect hook with bounded retries (WiFi may take
+     * seconds to reconnect after wake), then reconnects. Falls back to
+     * reconnecting even if all retry attempts fail.
+     */
+    async runHookAndReconnect() {
+        if (this.onBeforeReconnect) {
+            for (let attempt = 0; attempt < HOOK_RETRY_ATTEMPTS; attempt++) {
+                try {
+                    await this.onBeforeReconnect();
+                    break;
+                }
+                catch {
+                    const isLastAttempt = attempt === HOOK_RETRY_ATTEMPTS - 1;
+                    if (!isLastAttempt) {
+                        await this.delay(HOOK_RETRY_DELAY_MS);
+                    }
+                }
+            }
+        }
+        this.reconnect();
+    }
+    /**
+     * Determines whether reconnection is needed and triggers it. Routes
+     * through `handleSleepDetected` for deduplication with the heartbeat.
+     */
+    handlePageVisible() {
+        const hiddenDuration = this.hiddenAt ? Date.now() - this.hiddenAt : 0;
+        this.hiddenAt = null;
+        const socket = this.client.clientSocket.socket;
+        const isConnected = socket?.readyState === WebSocket.OPEN && this.client.initialized;
+        const needsReconnect = !isConnected || hiddenDuration > FORCE_RECONNECT_THRESHOLD;
+        if (needsReconnect) {
+            this.handleSleepDetected('visibility', hiddenDuration);
+            return;
+        }
+        if (this.idleTimer) {
+            this.idleTimer.stop();
+            this.idleTimer.start();
+        }
+    }
+    /** Promisified delay for hook retry backoff. */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=visibility-manager.js.map

package/dist/client/visibility-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-manager.js","sourceRoot":"","sources":["../../src/client/visibility-manager.ts"],"names":[],"mappings":"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"}

package/dist/ejson/adjust-types-from-json-value.d.ts

@@ -0,0 +1 @@
+export declare const adjustTypesFromJSONValue: (obj: any) => any;

package/dist/ejson/adjust-types-from-json-value.js

@@ -0,0 +1,35 @@
+/**
+ * for both arrays and objects. Tries its best to just
+ * use the object you hand it, but may return something
+ * different if the object you hand it itself needs changing.
+ */
+import { fromJSONValueHelper } from './helpers/from-json-value-helper.js';
+import { isObject, keysOf } from './utils.js';
+export const adjustTypesFromJSONValue = obj => {
+    if (obj === null) {
+        return null;
+    }
+    const maybeChanged = fromJSONValueHelper(obj);
+    if (maybeChanged !== obj) {
+        return maybeChanged;
+    }
+    // Other atoms are unchanged.
+    if (!isObject(obj)) {
+        return obj;
+    }
+    keysOf(obj).forEach(key => {
+        const value = obj[key];
+        if (isObject(value)) {
+            const changed = fromJSONValueHelper(value);
+            if (value !== changed) {
+                obj[key] = changed;
+                return;
+            }
+            // if we get here, value is an object but not adjustable
+            // at this level.  recurse.
+            adjustTypesFromJSONValue(value);
+        }
+    });
+    return obj;
+};
+//# sourceMappingURL=adjust-types-from-json-value.js.map

package/dist/ejson/adjust-types-from-json-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adjust-types-from-json-value.js","sourceRoot":"","sources":["../../src/ejson/adjust-types-from-json-value.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAE1C,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC,EAAE;IAC5C,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,YAAY,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IAC7C,IAAI,YAAY,KAAK,GAAG,EAAE,CAAC;QACzB,OAAO,YAAY,CAAA;IACrB,CAAC;IAED,6BAA6B;IAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;QACxB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAA;QACtB,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAA;YAC1C,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;gBACtB,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAA;gBAClB,OAAM;YACR,CAAC;YACD,wDAAwD;YACxD,2BAA2B;YAC3B,wBAAwB,CAAC,KAAK,CAAC,CAAA;QACjC,CAAC;IACH,CAAC,CAAC,CAAA;IACF,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA"}

package/dist/ejson/base64.d.ts

@@ -0,0 +1,11 @@
+import { newBinary } from './utils.js';
+/**
+ * Encodes binary payloads for EJSON without relying on a CJS-only dependency
+ * that breaks browser ESM loading in source-first consumers.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Decodes EJSON base64 payloads while preserving the legacy polyfill
+ * behavior for runtimes without `Uint8Array`.
+ */
+export declare function decodeBase64(value: string): Uint8Array | ReturnType<typeof newBinary>;