@v-tilt/browser 1.4.2 → 1.4.4

package/lib/storage.d.ts

@@ -1,23 +1,41 @@
 /**
- * Unified Storage Manager - Following PostHog's PostHogPersistence pattern
+ * Unified Storage Manager
  *
- * Single class handles all storage operations for both sessions and users.
- * Reduces code duplication and ensures consistent cookie handling.
+ * Handles all storage operations for sessions and users with consistent
+ * cookie handling across different persistence methods.
  *
  * Storage methods:
- * - cookie: Browser cookies (cross-subdomain support)
- * - localStorage: Persistent local storage
- * - sessionStorage: Tab-specific storage (cleared on tab close)
- * - localStorage+cookie: Both for redundancy
- * - memory: In-memory only (no persistence)
+ * - `cookie`: Browser cookies with cross-subdomain support
+ * - `localStorage`: Persistent local storage
+ * - `sessionStorage`: Tab-specific storage (cleared on tab close)
+ * - `localStorage+cookie`: Hybrid mode (default) - full data in localStorage,
+ *   critical identity properties also in cookies for SSR support
+ * - `memory`: In-memory only (no persistence)
+ *
+ * The `localStorage+cookie` mode is designed for traditional server-side
+ * rendered websites where each page navigation reloads JavaScript:
+ * - Critical properties (anonymous_id, device_id, etc.) are stored in cookies
+ * - Cookies ensure identity persists across full page reloads
+ * - localStorage provides fast access for SPA-style navigation
+ * - Falls back to cookie-only if localStorage is unavailable
  */
 import { PersistenceMethod } from "./types";
+/**
+ * Critical properties persisted to cookies in `localStorage+cookie` mode.
+ * These ensure identity survives full page reloads in traditional SSR websites.
+ */
+export declare const COOKIE_PERSISTED_PROPERTIES: readonly ["__vt_anonymous_id", "__vt_device_id", "__vt_distinct_id", "__vt_user_state"];
+/** Session cookie TTL: 30 minutes */
 export declare const SESSION_COOKIE_MAX_AGE = 1800;
+/** User cookie TTL: 1 year */
 export declare const USER_COOKIE_MAX_AGE = 31536000;
 export interface StorageOptions {
     method: PersistenceMethod;
+    /** Enable cross-subdomain cookies (auto-detected if not specified) */
     cross_subdomain?: boolean;
+    /** Use secure cookies (auto-detected from protocol if not specified) */
     secure?: boolean;
+    /** Cookie SameSite attribute */
     sameSite?: "Strict" | "Lax" | "None";
 }
 export interface StorageItem<T = string> {
@@ -25,13 +43,15 @@ export interface StorageItem<T = string> {
     expiry?: number;
 }
 /**
- * Auto-detect if cross-subdomain cookies should be enabled
- * Returns false for platforms like herokuapp.com, vercel.app, netlify.app
+ * Check if cross-subdomain cookies should be enabled.
+ * Returns false for shared hosting platforms to prevent cookie conflicts.
  */
 export declare function shouldUseCrossSubdomainCookie(): boolean;
 /**
  * Unified Storage Manager
+ *
  * Provides consistent storage operations across all persistence methods
+ * with automatic fallbacks and SSR support.
  */
 export declare class StorageManager {
     private method;
@@ -39,62 +59,59 @@ export declare class StorageManager {
     private secure;
     private sameSite;
     private memoryStorage;
+    private _localStorageSupported;
     constructor(options: StorageOptions);
+    /** Check if localStorage is available (result is cached) */
+    private isLocalStorageSupported;
+    /** Check if a key should be persisted to cookies */
+    private isCriticalProperty;
     /**
-     * Get a value from storage
+     * Get a value from storage.
+     *
+     * For `localStorage+cookie` mode:
+     * - Critical properties: read cookie first (for SSR), fall back to localStorage
+     * - Non-critical properties: read from localStorage only
      */
     get(key: string): string | null;
     /**
-     * Set a value in storage
-     * @param maxAge - Cookie max age in seconds (ignored for localStorage/sessionStorage)
+     * Set a value in storage.
+     * @param maxAge Cookie max age in seconds (only for cookie-based storage)
+     *
+     * For `localStorage+cookie` mode:
+     * - All values stored in localStorage (if available)
+     * - Critical properties ALWAYS stored in cookies for SSR support
      */
     set(key: string, value: string, maxAge?: number): void;
-    /**
-     * Remove a value from storage
-     */
+    /** Remove a value from storage */
     remove(key: string): void;
-    /**
-     * Get JSON value with expiry check
-     * Returns null if expired or not found
-     */
+    private getLocalStoragePlusCookie;
+    private setLocalStoragePlusCookie;
+    private removeLocalStoragePlusCookie;
+    private getLocalStorage;
+    private setLocalStorage;
+    private removeLocalStorage;
+    private readFromSessionStorage;
+    private writeToSessionStorage;
+    private removeFromSessionStorage;
+    private getCookie;
+    private setCookie;
+    private removeCookie;
+    /** Get JSON value with expiry check */
     getWithExpiry<T>(key: string): T | null;
-    /**
-     * Set JSON value with optional expiry
-     * @param ttlMs - Time to live in milliseconds
-     */
+    /** Set JSON value with optional TTL */
     setWithExpiry<T>(key: string, value: T, ttlMs?: number): void;
-    /**
-     * Get JSON value (no expiry check)
-     */
+    /** Get parsed JSON value */
     getJSON<T>(key: string): T | null;
-    /**
-     * Set JSON value
-     */
+    /** Set JSON value */
     setJSON<T>(key: string, value: T, maxAge?: number): void;
-    private getCookie;
-    private setCookie;
-    private removeCookie;
-    private usesLocalStorage;
-    private usesSessionStorage;
-    /**
-     * Check if sessionStorage is available
-     */
+    /** Check if sessionStorage is available */
     canUseSessionStorage(): boolean;
-    /**
-     * Get direct access to sessionStorage (for window_id which always uses sessionStorage)
-     */
+    /** Get sessionStorage instance (for window_id which always uses sessionStorage) */
     getSessionStorage(): Storage | null;
-    /**
-     * Update storage method at runtime
-     */
+    /** Update storage method at runtime */
     setMethod(method: PersistenceMethod): void;
-    /**
-     * Get current storage method
-     */
+    /** Get current storage method */
     getMethod(): PersistenceMethod;
 }
-/**
- * Create a shared storage instance
- * Use this for creating storage managers with consistent settings
- */
+/** Factory function to create a StorageManager with default settings */
 export declare function createStorageManager(method: PersistenceMethod, cross_subdomain?: boolean): StorageManager;