chainson

🪐 Chainson is a database-backed Map with zero dependencies for Node.js

Please read the following before using: This library is still in alpha. A lot of things might change internally and to the outside of the library. I aim to keep the API the same but I'm confident some things are gonna change. It's recommended to install it and lock it on one version to avoid having it automatically grab a newer version (that could theoretically break your application).

Now we got that out of the way, let's start!

Example

Let me show you how easy to use it is! More examples will be in the examples folders in the (near) future!

const Chainson = require('chainson')

const chain = new Chainson()
chain.add('hello', 'world')

const world = chain.get('hello')
console.log(`Hello, ${world}!`) // Helo, world!

Installing

It's pretty easy cause we're on NPM! Simply run the following command to install the library as a dependency. We do not recommend installing it globally to ensure you use the right version in your projects.

NPM - Node Package Manager

npm i chainson

Yarn - Package Manager

yarn add chainson

Why create a library like this?

We all have worked on an application that, for example, needed a simple settings menu or has to store something based on what an user enters and just want to simply store it. Usually, this requires you to setup some sort of database (such as SQLite or even heavier databases). This can take some effort and introduces security issues if not properly implemented (such as SQL-Injection).

That's why I'm working on a library to simply store and retrieve data without having to set up anything or having to think about security.

Isn't this basically storing a map to JSON and vice verca?

Kinda, yes! But it'll be able to do much more than just storing and retrieving data. Besides that, it's a lot of fun for me learning new things while working on a project that I'm actually planning on using myself in the future.

Why use it?

• It's easy to use. Everything you need is already included by default with Node.js.
• It's completely dependency free.
• It's small!
• You can rapidly store and retrieve data without having to worry about SQL.
• It's literally as easy as using a Map, it uses a Map for storing in memory and it's gonna be fully compliant with the Map methods on the future.
• It got typings, duh, it's built with Typescript!

Logic

When the database is "started", it loads the chainfile into memory. Every change to the chainfile will be saved to a json file.

What does Chainson mean?

It's simple! The data is stored in a Map which is kinda like a Chain and when the data is made persistent on the drive of the system it's running on it stores it as JSON so that's where the "son" part comes from.

What is supported?

• Strings
• Numbers
• Booleans
• Arrays
• Objects
• Floats
• null
• undefined, theoretically supported. It just removes it from the chain.
• Maps, which is funny because it uses maps to properly function. I might add a function later to put a Map inside of a chain

Roadmap

Moved! I'm gonna keep updating this README until all of the tasks here are done. But if you want to see new tasks or an overview of what is being worked on head over to our Github Projects board with the Tasks over here

Here follows a list of things that still need to be implemented:

• Check if chainfile already exists
• Create chainfile if none is available
• Queue for adding, removing, etc. to avoid getting the file corrupt
• Add to chain
• Getting from chain
• Check if chainfile is writable
• Check if chainfile is readable
• Loading chainfile into memory
• A store function to save memory to a file
• Check if exists in chain
• Remove from chain
• Update in chain
• Convert the data from the saved chain file back to original data structure
• Automatic repairing of a chainfile
• Automatic restoring of an older chainfile
• Automatic merging of older and newer chainfile (if new one not fully functional)
• Write a complex parser to add/change/remove specific key/value pairs example of what I mean
• In between editing and saving lock the chain (chainfile.json.lock) with an ID that has to match the process trying to edit it in order to unlock it
• Optional Chainhistory folder with older versions of the chain, can be "every 5 minutes" or "every change" etc.
• Robust logging system
• Robust error handling
• Undo function for recent changes (bottom of chainfile holds last x amount of change)
• Have the entire thing be fully asynchronous (except methods appended with Sync for flexibility)

If something is [x], it doesn't mean that it's working properly. It's just means that it has been implemented. In the future I'm gonna add unit tests and make everything a lot more secure. I first want to build a base to work from.

Documentation

There are a few places to find documentation for the application:

1. In the codebase itself there should be comments on almost every method.
2. An online version based on these comments can be found on chainson.js.org.

How to release a new version or contribute.

This part of the documention is mainly for myself at the moment (or people who might have release permissions in the future).

To ensure everything is formatted and linted, simply run npm run prepare-for-release and all the things that need to be ran will be run. If there are any errors or warnings: ⚠️ DO NOT RELEASE ⚠️ and fix the issues or wait for a fix to be implemented.

This ensures everything is consistent across all releases.

If you are contributing to the project ensure you run this command before you open a pull request. There have to be no errors before we're gonna merge your pull request so everything stays consistent.

During development you probably don't want to constantly generate documentation. That's why I've added npm run fix to make your life easier during development.

When you are ready to make a pull request make a pull request to the latest x.x.x-y branch (ensure your branch is based on the latest version of dev to avoid any merge conflicts). Once that gets accepted it will be merged into the x.x.x-y branch. Once a new set of features is implemented and the version is ready for release we'll merge it with master.

In the meanwhile, I personally work on the dev branch with my own features. There is a chance that your code get changed on the dev branch after it has been merged for optimizations. So don't be scared if you see me changing your code :)

Done reading? Check out this joke!

Refresh for a new one!

License

The library is released under an Apache 2.0 License.