cachexs v1.0.0

CacheXS

Discover CacheXS, a remarkably efficient library for JavaScript and Node.js, ideal for developers prioritizing performance and simplicity. Written in TypeScript, and it uses the ioredis library under the hood, it offers seamless integration for both TypeScript and JavaScript projects. Its compact size belies its powerful functionality, making it perfect for lightweight, modern applications. With ESM compatibility, CacheXS aligns with contemporary development practices, ensuring its utility in a range of projects from small-scale to complex.

Quick Navigation

1. Installation
2. Usage
3. Documentation
4. Support and Questions
5. Contribution
6. Guidelines for Contributions
7. License

Installation

Getting up and running with CacheXS is a breeze. Choose your preferred package manager from the options below and follow the simple installation steps:

NPM

npm i cachexs

Bun

bun i cachexs

Yarn

yarn add cachexs

Pnpm

pnpm install cachexs

Usage

Once you have installed CacheXS, integrating it into your project is straightforward. Below are the basic steps to get you started:

First, import CacheXS into your JavaScript or TypeScript file:

import CacheXS from 'cachexs'

Then create a new instance for CacheXS and pass the configuration to it:

const cacheXS = new CacheXS({
	redisConfig: {
		host: 'localhost',
		port: 6379,
		password: '',
	},
})

And then you can use it like this:

const cachedData = cacheXS.get('foo') // -> Bar

Documentation

The CacheXS package comes with a comprehensive set of features designed to make cache in your application straightforward and efficient. This section provides an overview of its capabilities and guides on how to use them effectively.

• Features Overview

  • Simple Cache Management: Easily cache the data in Redis with simple functions.

• Usage & Configuration

  • Installation

    Refer to the Installation section for instructions on how to install CacheXS using various package managers.

  • Initializing the Library:

    You can create a new instance of CacheXS and pass the configuration for it directly like this example below:

    const cacheXS = new CacheXS({
    	redisConnection: ioredis,
    	namespace: 'myCache',
    	enableDebug: true,
    })

    Alternatively, you can split the creation of the new instance and the configuration, useful when split up into different modules for bootstrapping.

    const cacheXS = new CacheXS()
    
    cacheXS.configure({
    	redisConnection: ioredis,
    	namespace: 'myCache',
    	enableDebug: true,
    })

• Methods/Properties

  • get Retrieves the value associated with the specified key from the cache.

    const stringValue = await cacheXS.get<string>('myKey') // -> myValue
    const stringValue = await cacheXS.get<number>('myKey') // -> 123
    const objectValue = await cacheXS.get<MyObject>('myKey') // -> { name: 'John', age: 30 }

  • set: Sets a value in the cache.

    await cacheXS.set('myKey', 'myValue')
    await cacheXS.set('myKey', 123)
    await cacheXS.set('myKey', { name: 'John', age: 30 }, { expiresIn: 360 })

  • setForever Sets a value in the cache forever

    await cacheXS.setForever('user', { name: 'John Doe', age: 30 })

  • getOrSet Retrieves the value associated with the specified key from the cache. If the value does not exist, it sets the value to the provided fallback value and returns it.

    const username = await cacheXS.getOrSet('myKey', 'myValue')

  • getOrSetForever Retrieves the value associated with the specified key from the cache. If the value does not exist, it sets the specified fallback value in the cache and returns it.

    value = await cacheXS.getOrSetForever('myKey', 'defaultValue')

  • delete Deletes a cache entry by its key.

    await cacheXS.delete('myKey')

  • deleteMany Deletes multiple cache entries specified by the given keys.

    await cacheXS.deleteMany(['myKey', 'myKey2', 'myKey3'])

  • clear Clears all cache entries in the CacheXS instance.

    await cacheXS.clear()

  • has Checks if a key exists in the cache.

    await cacheXS.has('myKey') // -> True || False

  • missing Checks if a key is missing in the cache.

    await cacheXS.missing('myKey') // -> True || False

  • concatenateKey Concatenates the given key with the namespace and returns the resulting string.

    await cacheXS.concatenateKey('myKey') // -> 'CacheXS:myKey'

  • redisConnection Gets the Redis connection.

    cacheXS.redisConnection // -> ioredis instance

  • redisUrl Gets the Redis URL.

    cacheXS.redisUrl // -> 'redis://user:pass@localhost:6379'

  • redisConfig Gets the Redis configuration.

    cacheXS.redisConfig // -> { host: 'localhost', port: 6379, password: '' }

  • expiresIn Gets the expiration time in seconds.

    cacheXS.expiresIn // -> 60

  • namespace Gets the namespace of the cache.

    cacheXS.namespace // -> 'CacheXS

  • isDebugEnabled Gets a value indicating whether debug mode is enabled.

    cacheXS.isDebugEnabled // -> True || False

Support and Questions

If you have any questions or need support while using CacheXS, feel free to open an issue on our GitHub repository or reach out to the community for help.

For the complete and detailed guide, please refer to our official documentation.

Contribution

First off, thank you for considering contributing to CacheXS! It's people like you who make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

There are many ways you can contribute to CacheXS, even if you're not a technical person:

• Submit Bug Reports: If you find a bug, please open an issue. Remember to include a clear description and as much relevant information as possible.
• Feature Suggestions: Have an idea for a new feature or an improvement? Open an issue and tag it as a feature request.
• Code Contributions: Interested in adding a feature or fixing a bug? Awesome! Please open a pull request with your changes.
• Documentation: Good documentation is key to any project. If you see something unclear or missing, feel free to submit a pull request.
• Spread the Word: Share CacheXS with your network and let others know about it.

Guidelines for Contributions

Ensure you use a consistent coding style with the rest of the project. Write clear, readable, and concise code. Add unit tests for new features to ensure reliability and maintainability. Update the README or documentation with details of changes, this includes new environment variables, exposed ports, useful file locations, and container parameters. Increase the version numbers in any example files and the README to the new version that this Pull Request would represent.

License

CacheXS is licensed under the MIT License. This license permits use, modification, and distribution, free of charge, for both private and commercial purposes. It also offers a good balance between protecting the author's rights and allowing for flexibility and freedom in the use of the software.