Storage Methods

These methods handle individual storage operations like setting, getting, and removing items.

Note

All methods are asynchronous and return Promises. Always use await or .then() when calling them.

set()

Stores a JSON-serializable value associated with a key.

Syntax

await storage.set(key, value)

Parameters

• key (String) — The key to store the value under
• value (Any JSON-serializable value) — The value to store (object, array, string, number, boolean, null)

Returns

Promise<void>

Errors

Throws an error if the value is not JSON-serializable.

Example

// Store primitive values
await storage.set('username', 'Alice');
await storage.set('count', 42);
await storage.set('isActive', true);

// Store objects
await storage.set('user', {
  name: 'Alice',
  email: 'alice@example.com',
  roles: ['admin', 'user']
});

// Store arrays
await storage.set('items', [1, 2, 3, 4, 5]);

Tip

If the key has a default expiration configured in the constructor, it will automatically expire after the specified duration.

---

get()

Retrieves the value associated with a key.

Syntax

await storage.get(key)

Parameters

• key (String) — The key to retrieve

Returns

Promise<any> — The stored value (parsed from JSON), or null if:

• The key doesn’t exist
• The item has expired (and is automatically removed)

Example

const user = await storage.get('user');
console.log(user); // Output: { name: 'Alice', email: '...' }

const missing = await storage.get('nonexistent');
console.log(missing); // Output: null

---

expires()

Sets or updates the expiration time for an existing key.

Syntax

await storage.expires(key, expiresIn)

Parameters

• key (String) — The key to set expiration for
• expiresIn (Number) — The time in seconds from now until the item expires

Returns

Promise<void>

Example

// Store a value
await storage.set('tempData', { info: 'test' });

// Set it to expire in 10 minutes (600 seconds)
await storage.expires('tempData', 600);

// Update expiration to 5 minutes
await storage.expires('tempData', 300);

Note

If the key doesn’t exist when you call expires(), the expiration will be set but won’t have any effect until you store a value with that key.

---

remove()

Removes an item from storage and clears any associated expiration timer.

Syntax

await storage.remove(key)

Parameters

• key (String) — The key to remove

Returns

Promise<void>

Example

await storage.set('tempToken', 'abc123');
// Later...
await storage.remove('tempToken');

const token = await storage.get('tempToken');
console.log(token); // Output: null

---

has()

Checks if a key exists in storage and has not expired.

Syntax

await storage.has(key)

Parameters

• key (String) — The key to check

Returns

Promise<boolean> — true if the key exists and is not expired, false otherwise

Example

await storage.set('user', { name: 'Alice' });

const hasUser = await storage.has('user');
console.log(hasUser); // Output: true

const hasOther = await storage.has('nonexistent');
console.log(hasOther); // Output: false

Tip

Use has() when you only need to check existence without retrieving the value. It’s more efficient than calling get() and checking for null.

---

keys()

Returns an array of all keys within the instance’s namespace.

Syntax

await storage.keys()

Returns

Promise<string[]> — An array of key names (without the namespace prefix)

Example

await storage.set('user', { name: 'Alice' });
await storage.set('preferences', { theme: 'dark' });
await storage.set('settings', { lang: 'en' });

const allKeys = await storage.keys();
console.log(allKeys); // Output: ['user', 'preferences', 'settings']

Note

The keys() method returns all keys in the namespace, including expired ones. Use has() to check if a specific key is still valid.

---

getAll()

Retrieves all non-expired key-value pairs within the instance’s namespace.

Syntax

await storage.getAll()

Returns

Promise<Object> — An object mapping keys to their values. Expired items are excluded.

Example

await storage.set('user', { name: 'Alice' });
await storage.set('preferences', { theme: 'dark' });
await storage.set('expired', 'test');
await storage.expires('expired', 1); // Expires in 1 second

// Wait for expiration
await new Promise(resolve => setTimeout(resolve, 1100));

const allData = await storage.getAll();
console.log(allData);
// Output: { user: { name: 'Alice' }, preferences: { theme: 'dark' } }
// Note: 'expired' is not included

---

clear()

Removes all items associated with the instance’s namespace from storage.

Syntax

await storage.clear()

Returns

Promise<void>

Example

await storage.set('key1', 'value1');
await storage.set('key2', 'value2');
await storage.set('key3', 'value3');

// Remove everything in this namespace
await storage.clear();

const allKeys = await storage.keys();
console.log(allKeys); // Output: []

Caution

The clear() method is destructive and cannot be undone. Use it carefully, especially in production code.

---

cleanup()

Manually triggers a cleanup of expired items within the namespace. This is automatically called during instantiation, but you can call it manually if needed.

Syntax

await storage.cleanup()

Returns

Promise<void>

Example

// Manually clean up expired items
await storage.cleanup();

Note

The cleanup() method is usually not needed because expired items are automatically removed when you try to retrieve them with get(), and cleanup runs on initialization.

Next Steps

Learn about Batch Operations for efficiently handling multiple items at once.