localstorage-slim

If the browser does not support localStorage, localstorage-slim automatically falls back to MemoryStorage.

Implications:

• Single Page Applications (SPAs): The fallback works perfectly as data persists for the duration of the session.
• Multi-Page Applications (MPAs): Data will not be persisted between page loads/refreshes because MemoryStorage is volatile.

The default encryption is a simple obfuscation. For real security, you can override ls.config.encrypter and ls.config.decrypter with your own logic (e.g., using CryptoJS for AES). You can also provide a specific secret for individual items during set or get calls.

// Example: Integrating a custom encryption algorithm
ls.config.encrypt = true;
ls.config.secret = 'my-secure-password';

ls.config.encrypter = (data, secret) => {
  // Your encryption logic here
  return 'encrypted string';
};

ls.config.decrypter = (encryptedString, secret) => {
  // Your decryption logic here
  return 'original data';
};

// Using a specific secret for a single item
ls.set('key', 'value', { secret: 'xyz' });
ls.get('key', { secret: 'xyz' });

You can install localstorage-slim via npm or Yarn. After installation, you can import it as an ES6 module, a CommonJS module, or include it via a <script> tag in the browser. When included via a script tag, the library is available globally as window.ls.

# npm
$ npm install --save localstorage-slim

# yarn
$ yarn add localstorage-slim

// ES6 modules
import ls from 'localstorage-slim';

// CommonJS modules
var ls = require('localstorage-slim');

<!-- CDN via jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/localstorage-slim"></script>

<!-- CDN via unpkg -->
<script src="https://unpkg.com/localstorage-slim@2.7.0/dist/localstorage-slim.js"></script>

By default, the library uses localStorage. You can switch to sessionStorage or any custom object that implements the Web Storage API by assigning it to ls.config.storage.

/* Use sessionStorage */
ls.config.storage = sessionStorage;

/* Use a custom store */
ls.config.storage = (() => {
  const store = {
    // implementation of getItem, setItem, removeItem, clear, length
  };
  return store;
})();

The ls.config object allows you to set global defaults for the library. All parameters are optional. Setting these will apply to all subsequent ls.set() and ls.get() calls unless overridden at the method level.

ls.config.ttl = 3600; // Global TTL of 1 hour
ls.config.encrypt = true; // Enable global encryption
ls.config.secret = 'my-secret-key'; // Global secret for encryption
ls.config.storage = sessionStorage; // Use sessionStorage instead of localStorage

Use ls.set(key, value) to store data and ls.get(key) to retrieve it. The library supports various data types including objects, arrays, strings, and numbers. You can also provide an optional configuration object to set and get to specify ttl (Time To Live) in seconds or enable encrypt/decrypt for specific items.

const value = { a: 1, b: 'test' };

// Basic set and get
ls.set('key1', value);
ls.get('key1');

// Using TTL (expiry in seconds)
ls.set('key2', value, { ttl: 5 });
ls.get('key2'); // returns value within 5 seconds
// after 5 seconds, ls.get('key2') returns null

// Using encryption for a specific item
ls.set('key3', value, { encrypt: true });
ls.get('key3', { decrypt: true });

The following parameters are available in the ls.config object to customize library behavior globally.

| Parameter | Description | Default |
| --------- | ----------- | ------- |
| `ttl?: number|null` | Global TTL in seconds for every item stored. | `null` |
| `encrypt?: boolean` | Enable global encryption of stored data. | `false` |
| `decrypt?: boolean` | Used only by `ls.get()` to decrypt data. | `undefined` |
| `encrypter?: (data: unknown, secret: string): string` | Custom encryption function. Default is obfuscation. | Obfuscation |
| `decrypter?: (encryptedString: string, secret: string): unknown` | Custom decryption function. Default is deobfuscation. | deobfuscation |
| `secret?: unknown` | Secret key passed to encrypter/decrypter. | (none) |
| `storage?: Storage` | The Storage implementation to use (e.g., `localStorage`, `sessionStorage`). | `localStorage` |

If you enable encryption in StorageConfig, you can provide custom logic via the encrypter and decrypter types to control how data is transformed.

• Encrypter: A function signature (...args: unknown[]) => string. It is responsible for taking the data (and optionally a secret) and returning an encrypted string.
• Decrypter: A function signature (...args: unknown[]) => unknown. It is responsible for taking the encrypted string (and optionally a secret) and returning the original value.

type Encrypter = (...args: unknown[]) => string;
type Decrypter = (...args: unknown[]) => unknown;

The ls.flush(force = false) method manages the removal of items based on their TTL.

• ls.flush(): Removes only the items that have already expired.
• ls.flush(true): Force-flushes all items that have a TTL set, even if they are not yet expired.

Note: flush(true) only affects items that had a TTL set. To remove data without a TTL, use remove() or clear().

// removes all expired data (i.e. ttl has expired)
ls.flush();

// removes all data that has a ttl (i.e. even if the ttl has not yet expired)
ls.flush(true);