npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@darcas/keyplex

v1.0.2

Published

A versatile and modular library for managing namespaced key-value storage, with built-in support for localStorage and sessionStorage, and the ability to easily extend for custom storage solutions.

Readme

KeyPlex

NPM Last Update NPM Version NPM Downloads NPM License

KeyPlex is a versatile and modular library for managing namespaced key-value storage. It provides an abstract class that can be extended to create custom storage solutions, as well as concrete implementations for localStorage and sessionStorage.

Features

  • Namespace Support: Automatically scopes keys using a customizable namespace (default is derived from the current domain).
  • Extensibility: Easily create custom storage backends by extending the KeyPlex abstract class.
  • Convenient API: Simplified methods for getting, setting, deleting, and checking keys.

Installation

npm install @darcas/keyplex

Or, if you're using yarn:

yarn add @darcas/keyplex

Usage

Using LocalPlex and SessionPlex

KeyPlex includes two built-in implementations:

  • LocalPlex: Uses localStorage as the backend.
  • SessionPlex: Uses sessionStorage as the backend.

Example:

import { LocalPlex, SessionPlex } from '@darcas/keyplex';

// Initialize a LocalPlex instance
const localStore = new LocalPlex('myNamespace');

// Set a value
localStore.set('key', { name: 'KeyPlex' });

// Get a value
const value = localStore.get('key');
console.log(value); // Output: { name: 'KeyPlex' }

// Check if a key exists
if (localStore.has('key')) {
  console.log('Key exists!');
}

// Delete a key
localStore.del('key');

// Initialize a SessionPlex instance
const sessionStore = new SessionPlex('sessionNamespace');
sessionStore.set('sessionKey', 'Session Data');

Deleting with Wildcard (%)

In KeyPlex, when you want to delete multiple keys at once, you can use the % wildcard at the end of the key name. This allows you to match all keys that start with the same prefix, making it easier to clean up related entries.

How It Works:

  • If the key you're deleting ends with a %, the library will match all keys that start with the same prefix (before the % symbol).
  • The % wildcard acts like a "glob" or "pattern matching" character, allowing for batch deletion of keys that follow a similar naming convention.

Example:

// Initialize a LocalPlex or SessionPlex instance
const localStore = new LocalPlex('myNamespace');

// Set some keys
localStore.set('user/123/profile', { name: 'John Doe' });
localStore.set('user/123/settings', { theme: 'dark' });
localStore.set('user/124/profile', { name: 'Jane Doe' });

// Delete all keys related to user 123
localStore.del('user/123%');

// After deletion, only user/124 keys will remain in the storage

In this case, the localStore.del('user/123%') call will remove the following keys:

  • user/123/profile
  • user/123/settings

This is useful when you have a group of related keys (e.g., user data) and want to delete them in bulk without needing to manually list all keys.

Important Notes:

  • The wildcard % only works at the end of the key name.
  • It does not support complex patterns or regular expressions, so only keys that start with the specified prefix will be matched.
  • Wildcard deletion is recursive, meaning that it will apply to all keys with matching prefixes, so use it carefully to avoid unintended deletions.

Extending KeyPlex

To create a custom storage backend, extend the KeyPlex class and implement the required methods:

  1. keys: Return all keys in the storage.
  2. getItem: Retrieve a value by its key.
  3. setItem: Store a value by its key.
  4. removeItem: Remove a value by its key.

Example:

import { KeyPlex } from '@darcas/keyplex';

class CustomStorage extends KeyPlex {
  private store: Record<string, string> = {};

  keys(): string[] {
    return Object.keys(this.store);
  }

  protected getItem(key: string): string | null {
    return this.store[key] || null;
  }

  protected setItem(key: string, value: string): void {
    this.store[key] = value;
  }

  protected removeItem(key: string): void {
    delete this.store[key];
  }
}

// Usage
const customStore = new CustomStorage('customNamespace');
customStore.set('customKey', 'Custom Value');
console.log(customStore.get('customKey')); // Output: 'Custom Value'

API Reference

KeyPlex Methods

  • get<T = unknown>(key: string, def: T | null = null): T Retrieves the value associated with the key, or returns the default value if the key does not exist.

  • set<T = unknown>(key: string, value: T): void Stores the value under the specified key.

  • del(key: string): void Deletes the value associated with the key. Supports pattern deletion using a % wildcard.

  • has(key: string): boolean Checks whether a key exists in the storage.

  • keys(): string[] (Abstract)
    Returns all keys in the storage.

Contributing

If you'd like to contribute to the project, feel free to fork it and create a pull request. Please ensure that your changes are well-tested and properly documented.

License

This project is licensed under the MIT License. See the LICENSE file for details.


Made with ❤️ by Dario Casertano (DarCas).