@buoy-gg/storage 1.7.2

package/lib/module/storage/utils/lineDiff.js

@@ -0,0 +1,359 @@
+"use strict";
+
+/**
+ * Line-by-line diff computation for React Native
+ * Adapted from react-diff-viewer for object comparison
+ */
+
+export let DiffType = /*#__PURE__*/function (DiffType) {
+  DiffType["DEFAULT"] = "unchanged";
+  DiffType["ADDED"] = "added";
+  DiffType["REMOVED"] = "removed";
+  DiffType["MODIFIED"] = "modified";
+  return DiffType;
+}({});
+/**
+ * Compute diff based on method - for word-level diff within lines
+ */
+function computeDiffByMethod(oldStr, newStr, method) {
+  let oldParts;
+  let newParts;
+  switch (method) {
+    case "chars":
+      // Split into individual characters
+      oldParts = oldStr.split("");
+      newParts = newStr.split("");
+      break;
+    case "words":
+      // Split by word boundaries, keeping whitespace
+      oldParts = oldStr.match(/\S+|\s+/g) || [];
+      newParts = newStr.match(/\S+|\s+/g) || [];
+      break;
+    case "trimmedLines":
+      {
+        // For trimmedLines, compare without leading/trailing whitespace
+        const oldTrimmed = oldStr.trim();
+        const newTrimmed = newStr.trim();
+        // But still do word-level diff on the trimmed content
+        oldParts = oldTrimmed.match(/\S+|\s+/g) || [];
+        newParts = newTrimmed.match(/\S+|\s+/g) || [];
+        break;
+      }
+    case "lines":
+    default:
+      // For lines mode, don't do word diff - just show the whole line
+      return {
+        left: [{
+          value: oldStr,
+          type: DiffType.REMOVED
+        }],
+        right: [{
+          value: newStr,
+          type: DiffType.ADDED
+        }]
+      };
+  }
+
+  // Simple LCS-like algorithm for better diff
+  const left = [];
+  const right = [];
+  let i = 0,
+    j = 0;
+
+  // Find matching parts
+  while (i < oldParts.length && j < newParts.length) {
+    if (oldParts[i] === newParts[j]) {
+      // Parts match
+      left.push({
+        value: oldParts[i],
+        type: DiffType.DEFAULT
+      });
+      right.push({
+        value: newParts[j],
+        type: DiffType.DEFAULT
+      });
+      i++;
+      j++;
+    } else {
+      // Look ahead for matches
+      let foundMatch = false;
+
+      // Check if we can find newParts[j] in upcoming oldParts
+      for (let k = i + 1; k < Math.min(i + 5, oldParts.length); k++) {
+        if (oldParts[k] === newParts[j]) {
+          // Mark everything from i to k-1 as removed
+          for (let m = i; m < k; m++) {
+            left.push({
+              value: oldParts[m],
+              type: DiffType.REMOVED
+            });
+          }
+          i = k;
+          foundMatch = true;
+          break;
+        }
+      }
+      if (!foundMatch) {
+        // Check if we can find oldParts[i] in upcoming newParts
+        for (let k = j + 1; k < Math.min(j + 5, newParts.length); k++) {
+          if (newParts[k] === oldParts[i]) {
+            // Mark everything from j to k-1 as added
+            for (let m = j; m < k; m++) {
+              right.push({
+                value: newParts[m],
+                type: DiffType.ADDED
+              });
+            }
+            j = k;
+            foundMatch = true;
+            break;
+          }
+        }
+      }
+      if (!foundMatch) {
+        // No match found nearby, mark as changed
+        left.push({
+          value: oldParts[i],
+          type: DiffType.REMOVED
+        });
+        right.push({
+          value: newParts[j],
+          type: DiffType.ADDED
+        });
+        i++;
+        j++;
+      }
+    }
+  }
+
+  // Handle remaining parts
+  while (i < oldParts.length) {
+    left.push({
+      value: oldParts[i],
+      type: DiffType.REMOVED
+    });
+    i++;
+  }
+  while (j < newParts.length) {
+    right.push({
+      value: newParts[j],
+      type: DiffType.ADDED
+    });
+    j++;
+  }
+  return {
+    left,
+    right
+  };
+}
+
+/**
+ * Convert object to formatted JSON lines
+ */
+function objectToLines(obj) {
+  if (obj === null || obj === undefined) {
+    return [String(obj)];
+  }
+  try {
+    // Pretty print JSON with 2 space indentation
+    const jsonStr = JSON.stringify(obj, null, 2);
+    // Split into lines and filter out empty lines that appear between array elements
+    const lines = jsonStr.split("\n");
+
+    // Remove empty lines but keep structure
+    const filteredLines = [];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      // Keep the line if it's not empty or if it's meaningful whitespace
+      if (trimmed !== "") {
+        filteredLines.push(line);
+      } else if (i === 0 || i === lines.length - 1) {
+        // Keep first and last empty lines if they exist (though they shouldn't)
+        filteredLines.push(line);
+      }
+      // Skip other empty lines
+    }
+    return filteredLines;
+  } catch {
+    return [String(obj)];
+  }
+}
+/**
+ * Apply showDiffOnly filter with context lines
+ */
+function filterDiffWithContext(diffs, contextLines) {
+  if (contextLines < 0) return diffs;
+  const result = [];
+  const changedIndices = [];
+
+  // Find all changed lines
+  diffs.forEach((diff, idx) => {
+    if (diff.type !== DiffType.DEFAULT) {
+      changedIndices.push(idx);
+    }
+  });
+
+  // If no changes, return empty
+  if (changedIndices.length === 0) {
+    return [];
+  }
+
+  // Build ranges to include
+  const ranges = [];
+  let currentStart = Math.max(0, changedIndices[0] - contextLines);
+  let currentEnd = Math.min(diffs.length - 1, changedIndices[0] + contextLines);
+  for (let i = 1; i < changedIndices.length; i++) {
+    const idx = changedIndices[i];
+    const rangeStart = Math.max(0, idx - contextLines);
+    const rangeEnd = Math.min(diffs.length - 1, idx + contextLines);
+
+    // If ranges overlap or are adjacent, merge them
+    if (rangeStart <= currentEnd + 1) {
+      currentEnd = Math.max(currentEnd, rangeEnd);
+    } else {
+      // Save current range and start a new one
+      ranges.push([currentStart, currentEnd]);
+      currentStart = rangeStart;
+      currentEnd = rangeEnd;
+    }
+  }
+
+  // Don't forget the last range
+  ranges.push([currentStart, currentEnd]);
+
+  // Build result from ranges
+  ranges.forEach(([start, end]) => {
+    for (let i = start; i <= end; i++) {
+      result.push(diffs[i]);
+    }
+  });
+  return result;
+}
+
+/**
+ * Compare lines based on method
+ */
+function compareLinesWithMethod(line1, line2, method) {
+  switch (method) {
+    case "trimmedLines":
+      return line1.trim() === line2.trim();
+    case "chars":
+    case "words":
+    case "lines":
+    default:
+      return line1 === line2;
+  }
+}
+
+/**
+ * Compute line-by-line diff between two objects
+ */
+export function computeLineDiff(oldValue, newValue, options = {}) {
+  const {
+    compareMethod = "words",
+    disableWordDiff = false,
+    showDiffOnly = false,
+    contextLines = 3
+  } = options;
+  const oldLines = objectToLines(oldValue);
+  const newLines = objectToLines(newValue);
+  const result = [];
+  let leftLineNum = 1;
+  let rightLineNum = 1;
+
+  // Simple line diff algorithm (can be improved with LCS)
+  let i = 0,
+    j = 0;
+  while (i < oldLines.length || j < newLines.length) {
+    if (i >= oldLines.length) {
+      // Rest are additions
+      result.push({
+        rightLineNumber: rightLineNum++,
+        type: DiffType.ADDED,
+        rightContent: newLines[j],
+        rightRaw: newLines[j]
+      });
+      j++;
+    } else if (j >= newLines.length) {
+      // Rest are removals
+      result.push({
+        leftLineNumber: leftLineNum++,
+        type: DiffType.REMOVED,
+        leftContent: oldLines[i],
+        leftRaw: oldLines[i]
+      });
+      i++;
+    } else if (compareLinesWithMethod(oldLines[i], newLines[j], compareMethod === "trimmedLines" ? "trimmedLines" : "lines")) {
+      // Lines match (possibly after trimming if trimmedLines)
+      result.push({
+        leftLineNumber: leftLineNum++,
+        rightLineNumber: rightLineNum++,
+        type: DiffType.DEFAULT,
+        leftContent: oldLines[i],
+        rightContent: newLines[j],
+        leftRaw: oldLines[i],
+        rightRaw: newLines[j]
+      });
+      i++;
+      j++;
+    } else {
+      // Lines differ - check if it's a modification or separate add/remove
+      const oldTrimmed = oldLines[i].trim();
+      const newTrimmed = newLines[j].trim();
+
+      // Simple heuristic: if lines start similarly, treat as modification
+      if (oldTrimmed && newTrimmed && (oldTrimmed.startsWith(newTrimmed.substring(0, 3)) || newTrimmed.startsWith(oldTrimmed.substring(0, 3)))) {
+        // Treat as modification - compute word diff if enabled
+        if (!disableWordDiff && compareMethod !== "lines") {
+          const wordDiff = computeDiffByMethod(oldLines[i], newLines[j], compareMethod);
+          result.push({
+            leftLineNumber: leftLineNum++,
+            rightLineNumber: rightLineNum++,
+            type: DiffType.MODIFIED,
+            leftContent: wordDiff.left,
+            rightContent: wordDiff.right,
+            leftRaw: oldLines[i],
+            rightRaw: newLines[j]
+          });
+        } else {
+          // No word diff - just mark lines as different
+          result.push({
+            leftLineNumber: leftLineNum++,
+            rightLineNumber: rightLineNum++,
+            type: DiffType.MODIFIED,
+            leftContent: oldLines[i],
+            rightContent: newLines[j],
+            leftRaw: oldLines[i],
+            rightRaw: newLines[j]
+          });
+        }
+        i++;
+        j++;
+      } else {
+        // Treat as separate remove and add
+        result.push({
+          leftLineNumber: leftLineNum++,
+          type: DiffType.REMOVED,
+          leftContent: oldLines[i],
+          leftRaw: oldLines[i]
+        });
+        result.push({
+          rightLineNumber: rightLineNum++,
+          type: DiffType.ADDED,
+          rightContent: newLines[j],
+          rightRaw: newLines[j]
+        });
+        i++;
+        j++;
+      }
+    }
+  }
+
+  // Apply showDiffOnly filter if enabled
+  if (showDiffOnly) {
+    return filterDiffWithContext(result, contextLines);
+  }
+  return result;
+}

package/lib/module/storage/utils/mmkvAvailability.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * MMKV Availability Detection
+ *
+ * Safely detects if react-native-mmkv is available in the current environment.
+ * This allows the app to work in Expo Go where native modules aren't available.
+ */
+
+let _isMMKVAvailable = null;
+let _MMKVClass = null;
+
+/**
+ * Check if MMKV is available in the current environment
+ *
+ * @returns True if react-native-mmkv is installed and available
+ */
+export function isMMKVAvailable() {
+  // Cache the result after first check
+  if (_isMMKVAvailable !== null) {
+    return _isMMKVAvailable;
+  }
+  try {
+    // Attempt to require MMKV
+    const MMKVModule = require('react-native-mmkv');
+
+    // v4 uses createMMKV factory function, v3 used MMKV class
+    // Try v4 API first (recommended), fall back to v3
+    _MMKVClass = MMKVModule.createMMKV || MMKVModule.MMKV;
+    _isMMKVAvailable = _MMKVClass !== undefined;
+    return _isMMKVAvailable;
+  } catch (error) {
+    // MMKV is not available (e.g., Expo Go, not installed)
+    _isMMKVAvailable = false;
+    return false;
+  }
+}
+
+/**
+ * Get the MMKV class if available
+ *
+ * @returns MMKV class or null if not available
+ */
+export function getMMKVClass() {
+  if (!isMMKVAvailable()) {
+    return null;
+  }
+  return _MMKVClass;
+}
+
+/**
+ * Get a user-friendly error message when MMKV is not available
+ */
+export function getMMKVUnavailableMessage() {
+  return 'MMKV is not available in this environment. MMKV requires native modules and cannot run in Expo Go. Please use a development build or EAS Build.';
+}

package/lib/module/storage/utils/mmkvTypeDetection.js

@@ -0,0 +1,133 @@
+"use strict";
+
+/**
+ * MMKV Type Detection Utilities
+ *
+ * MMKV stores values with native types (string, number, boolean, ArrayBuffer).
+ * This module provides utilities to detect the type of a stored value by trying
+ * each getter sequentially.
+ */
+
+// Use 'any' type for MMKV to avoid hard dependency on react-native-mmkv
+
+/**
+ * Detect the type of a value stored in MMKV by trying each getter.
+ *
+ * Since MMKV doesn't provide a getType() method, we must try each getter
+ * (getString, getNumber, getBoolean, getBuffer) until one returns a value.
+ *
+ * Order matters: We try in order of most common types first.
+ *
+ * @param instance - MMKV instance to read from
+ * @param key - Storage key
+ * @returns Value and its detected type
+ *
+ * @example
+ * ```typescript
+ * const instance = createMMKV();
+ * instance.set('name', 'John');
+ * instance.set('age', 30);
+ * instance.set('active', true);
+ *
+ * detectMMKVType(instance, 'name');   // { value: 'John', type: 'string' }
+ * detectMMKVType(instance, 'age');    // { value: 30, type: 'number' }
+ * detectMMKVType(instance, 'active'); // { value: true, type: 'boolean' }
+ * detectMMKVType(instance, 'missing');// { value: undefined, type: 'unknown' }
+ * ```
+ */
+export function detectMMKVType(instance, key) {
+  // Try string (most common)
+  const stringValue = instance.getString(key);
+  if (stringValue !== undefined) {
+    return {
+      value: stringValue,
+      type: 'string'
+    };
+  }
+
+  // Try number
+  const numberValue = instance.getNumber(key);
+  if (numberValue !== undefined) {
+    return {
+      value: numberValue,
+      type: 'number'
+    };
+  }
+
+  // Try boolean
+  const booleanValue = instance.getBoolean(key);
+  if (booleanValue !== undefined) {
+    return {
+      value: booleanValue,
+      type: 'boolean'
+    };
+  }
+
+  // Try buffer (least common)
+  const bufferValue = instance.getBuffer(key);
+  if (bufferValue !== undefined) {
+    // Format buffer for display (don't return raw ArrayBuffer)
+    return {
+      value: `<ArrayBuffer ${bufferValue.byteLength} bytes>`,
+      type: 'buffer'
+    };
+  }
+
+  // Key doesn't exist or unknown type
+  return {
+    value: undefined,
+    type: 'unknown'
+  };
+}
+
+/**
+ * Format an MMKV value for display in the UI.
+ *
+ * @param value - The value to format
+ * @param type - The detected type
+ * @returns Formatted string representation
+ *
+ * @example
+ * ```typescript
+ * formatMMKVValue('hello', 'string');  // '"hello"'
+ * formatMMKVValue(42, 'number');       // '42'
+ * formatMMKVValue(true, 'boolean');    // 'true'
+ * formatMMKVValue('<ArrayBuffer 1024 bytes>', 'buffer'); // '<ArrayBuffer 1024 bytes>'
+ * ```
+ */
+export function formatMMKVValue(value, type) {
+  if (value === undefined) return 'undefined';
+  if (value === null) return 'null';
+  switch (type) {
+    case 'string':
+      return `"${value}"`;
+    case 'number':
+      return String(value);
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'buffer':
+      // Value is already formatted as "<ArrayBuffer X bytes>"
+      return value;
+    case 'unknown':
+      return 'unknown';
+    default:
+      return String(value);
+  }
+}
+
+/**
+ * Check if a value type matches an expected type for validation.
+ *
+ * @param actualType - Detected type
+ * @param expectedType - Expected type from configuration
+ * @returns True if types match
+ *
+ * @example
+ * ```typescript
+ * isTypeMatch('string', 'string');  // true
+ * isTypeMatch('number', 'string');  // false
+ * ```
+ */
+export function isTypeMatch(actualType, expectedType) {
+  return actualType === expectedType;
+}

package/lib/module/storage/utils/objectDiff.js

@@ -0,0 +1,153 @@
+"use strict";
+
+/**
+ * Type guard to check if a value is a plain object (not array or null)
+ * 
+ * @param obj - Value to check
+ * @returns True if the value is a plain object
+ */
+function isObject(obj) {
+  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
+}
+
+/**
+ * Type guard to check if a value is an array
+ * 
+ * @param obj - Value to check
+ * @returns True if the value is an array
+ */
+function isArray(obj) {
+  return Array.isArray(obj);
+}
+
+/**
+ * Recursively compare two values and collect differences
+ * 
+ * This function handles deep comparison of objects, arrays, and primitive values,
+ * building a comprehensive diff that tracks the exact path of each change.
+ * 
+ * @param oldVal - The original value to compare from
+ * @param newVal - The new value to compare to
+ * @param path - Current path in the object structure (for nested properties)
+ * @param diffs - Array to collect difference items
+ * 
+ * @performance Uses recursive traversal with path tracking for memory efficiency
+ * @performance Handles large nested structures without stack overflow concerns for typical use cases
+ */
+function compareValues(oldVal, newVal, path, diffs) {
+  // Both are objects
+  if (isObject(oldVal) && isObject(newVal)) {
+    const allKeys = new Set([...Object.keys(oldVal), ...Object.keys(newVal)]);
+    for (const key of allKeys) {
+      const newPath = [...path, key];
+      if (!(key in oldVal)) {
+        // Key was added
+        diffs.push({
+          type: "CREATE",
+          path: newPath,
+          value: newVal[key]
+        });
+      } else if (!(key in newVal)) {
+        // Key was removed
+        diffs.push({
+          type: "REMOVE",
+          path: newPath,
+          oldValue: oldVal[key]
+        });
+      } else {
+        // Key exists in both, compare values
+        compareValues(oldVal[key], newVal[key], newPath, diffs);
+      }
+    }
+  }
+  // Both are arrays
+  else if (isArray(oldVal) && isArray(newVal)) {
+    const maxLength = Math.max(oldVal.length, newVal.length);
+    for (let i = 0; i < maxLength; i++) {
+      const newPath = [...path, i];
+      if (i >= oldVal.length) {
+        // Item was added
+        diffs.push({
+          type: "CREATE",
+          path: newPath,
+          value: newVal[i]
+        });
+      } else if (i >= newVal.length) {
+        // Item was removed
+        diffs.push({
+          type: "REMOVE",
+          path: newPath,
+          oldValue: oldVal[i]
+        });
+      } else {
+        // Item exists in both, compare values
+        compareValues(oldVal[i], newVal[i], newPath, diffs);
+      }
+    }
+  }
+  // Values are different types or primitives
+  else if (oldVal !== newVal) {
+    diffs.push({
+      type: "CHANGE",
+      path,
+      oldValue: oldVal,
+      value: newVal
+    });
+  }
+}
+
+/**
+ * Generate a comprehensive diff between two objects or values
+ * 
+ * This function performs a deep comparison between two values and returns
+ * a detailed list of all differences, including additions, removals, and changes.
+ * Each difference includes the exact path where the change occurred.
+ * 
+ * @param oldObj - The original object/value to compare from
+ * @param newObj - The new object/value to compare to
+ * @returns Array of DiffItem objects describing all differences
+ * 
+ * @example
+ * ```typescript
+ * const oldData = { user: { name: "John", age: 30 }, items: [1, 2] };
+ * const newData = { user: { name: "Jane", age: 30 }, items: [1, 2, 3] };
+ * 
+ * const diffs = objectDiff(oldData, newData);
+ * // Returns:
+ * // [
+ * //   { type: "CHANGE", path: ["user", "name"], oldValue: "John", value: "Jane" },
+ * //   { type: "CREATE", path: ["items", 2], value: 3 }
+ * // ]
+ * ```
+ * 
+ * @performance Handles circular references and deep nesting efficiently
+ * @performance Uses Set for key deduplication to optimize comparison speed
+ */
+export function objectDiff(oldObj, newObj) {
+  const diffs = [];
+
+  // Handle null/undefined cases
+  if (oldObj === newObj) {
+    return diffs;
+  }
+  if (oldObj === null || oldObj === undefined) {
+    if (newObj !== null && newObj !== undefined) {
+      diffs.push({
+        type: "CREATE",
+        path: [],
+        value: newObj
+      });
+    }
+    return diffs;
+  }
+  if (newObj === null || newObj === undefined) {
+    diffs.push({
+      type: "REMOVE",
+      path: [],
+      oldValue: oldObj
+    });
+    return diffs;
+  }
+  compareValues(oldObj, newObj, [], diffs);
+  return diffs;
+}