Storage Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'getItem')

  cause The `InitializeStorageUtils` function was not called or was called with an invalid `engine` object, especially common in React Native where `AsyncStorage` needs to be provided.
  fix Ensure `InitializeStorageUtils` is called at application startup with a valid storage engine. For React Native, this means `InitializeStorageUtils({ engine: AsyncStorage, engineName: 'AsyncStorage' });` after importing `AsyncStorage`.

• Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'then') OR GetItem returns Promise {<pending>}

  cause Attempting to use `GetItem` or `GetItemAsync` (post v3.0.0) in an asynchronous context (like React Native's AsyncStorage) without `await`.
  fix Always `await` the result of `GetItemAsync('key')`. If using `GetItem` and encountering this, switch to `GetItemAsync` or ensure `await` is applied if `GetItem` is configured with an async engine.

• ReferenceError: AsyncStorage is not defined

  cause You are attempting to use `AsyncStorage` in React Native but have not imported it or installed the necessary package (`@react-native-async-storage/async-storage`).
  fix Install `@react-native-async-storage/async-storage` (`npm install @react-native-async-storage/async-storage`) and `import AsyncStorage from '@react-native-async-storage/async-storage';` in your React Native files.

Warnings

• breaking With v3.0.0, getter functions became promise-based, primarily manifesting through the introduction of `GetItemAsync`. The `GetItem` function itself might now return a Promise if configured with an asynchronous engine like AsyncStorage, which is a breaking change from its previous synchronous behavior.
  Fix: Always use `await GetItemAsync('key')` for retrieving values, especially when using AsyncStorage or in contexts where values might be fetched asynchronously. If using `GetItem`, be aware it might return a Promise and should be awaited.
• gotcha The `InitializeStorageUtils` function is critical for setting up the environment in React Native with `AsyncStorage`. Failing to call it with the correct `engine` and `engineName` will lead to runtime errors when attempting to use storage functions.
  Fix: Call `InitializeStorageUtils({ engine: AsyncStorage, engineName: 'AsyncStorage' })` once at the root of your React Native application or component. For web, it can be skipped unless you need to override the default `localStorage` engine or `storeName`.
• breaking Version 2.0.0 introduced time-based storage policy via the `span` option in `SetItem`. While a feature, it changed the `SetItem` API signature by adding an options object, meaning older direct calls without the options object might behave differently or need adjustment if `span` functionality is desired.
  Fix: Review `SetItem` calls and update to `SetItem(key, payload, { span: <minutes>, isNonVolatile: false })` if time-based expiration or non-volatile categorization is intended.
• gotcha Data stored using `SetItem` without `isNonVolatile: true` is considered 'volatile' and can be mass-deleted by specific utility functions not detailed in the provided API. If data must persist across specific actions (like user logout), ensure it's marked as non-volatile.
  Fix: For data that should not be automatically purged by volatile cleanup mechanisms, explicitly set `isNonVolatile: true` in the options object: `SetItem(key, payload, { isNonVolatile: true })`.

Install

• npm install storage-utility npm
• yarn add storage-utility yarn
• pnpm add storage-utility pnpm

Imports

• InitializeStorageUtils
  wrong:

  const InitializeStorageUtils = require('storage-utility').InitializeStorageUtils;

  correct:

  import { InitializeStorageUtils } from 'storage-utility';

  Primarily for React Native setup. Optional for web unless overriding defaults.
• SetItem
  wrong:

  import SetItem from 'storage-utility';

  correct:

  import { SetItem } from 'storage-utility';

  This is a named export. Ensure to destructure correctly.
• GetItemAsync
  wrong:

  const GetItemAsync = require('storage-utility').GetItemAsync;

  correct:

  import { GetItemAsync } from 'storage-utility';

  Introduced in v3.0.0 as the primary promise-based getter, especially for AsyncStorage.
• GetItem
  wrong:

  await GetItem('key'); // If used for AsyncStorage without await in v3+

  correct:

  import { GetItem } from 'storage-utility';

  While `GetItem` still exists, `GetItemAsync` should be preferred for consistency and when interacting with asynchronous engines like AsyncStorage since v3.0.0. `GetItem` might return a Promise if configured with an async engine.

Quickstart

Demonstrates initializing `storage-utility` for React Native (or browser), setting a time-sensitive item, and asynchronously retrieving it.

import React, { useEffect, useState } from 'react';
import { GetItemAsync, SetItem, InitializeStorageUtils } from 'storage-utility';
import AsyncStorage from '@react-native-async-storage/async-storage'; // Ensure this is installed for RN

// This setup would typically be in your app's entry point or root component constructor
// For a browser environment, InitializeStorageUtils can often be skipped.
InitializeStorageUtils({
    storeName: 'MyTestStore',
    engine: AsyncStorage, // Use localStorage for web: window.localStorage
    engineName: 'AsyncStorage' // Use 'localStorage' for web
});

const StorageExample = () => {
    const [value, setValue] = useState(null);
    const key = 'myPersistentData';

    useEffect(() => {
        const storeAndRetrieve = async () => {
            console.log('Attempting to set item...');
            // Store data that expires in 1 minute and is volatile
            SetItem(key, { message: 'Hello from storage!', timestamp: Date.now() }, { span: 1, isNonVolatile: false });
            console.log('Item set. Waiting for retrieval...');

            // Retrieve the data using the async getter
            const stored = await GetItemAsync(key);
            setValue(stored);
            console.log('Retrieved:', stored);
        };

        storeAndRetrieve();
    }, []);

    return (
        <div>
            <h1>Storage Utility Example</h1>
            <p>Stored Value: {value ? JSON.stringify(value) : 'No value found or expired'}</p>
            <p>Check console for logs.</p>
        </div>
    );
};

export default StorageExample;