Mostly, this documentation will be concentrating on the "persistent" version of enmap - the one where data is saved automatically.

If you don't want persistence, the only difference is how you initialize the enmap:

const Enmap = require("enmap");
const myEnmap = new Enmap();

// you can now use your enmap directly

Persistent Enmaps

By default, Enmap saves only in memory and does not save anything to disk. To have persistent storage, you need to add some options. Enmaps with a "name" option will save, and there are additional options you can use to fine-tune the saving and loading features.

Enmap Options

The following is a list of all options that are available in Enmap, when initializing it:

• name: A name for the enmap. Defines the table name in SQLite (the name is "cleansed" before use).

  • If an enmap has a name, it is considered persistent and will require better-sqlite-pool to run.

Now that we have a functional Enmap structure (which we'll always refer to as myEnmap), we're ready to start writing data to it, and getting data from it.

The code samples on this page assume that you have correctly initialized myEnmap

Writing Data

In terms of Enmap, "writing", "adding" and "editing" data is essentially the same thing. When using the basic set() method, if the key does not exist it's created, and if it does, it's modified.

Enmap supports pretty much all native JavaScript data types. However, it cannot support Class Instances directly. That means if you have, say, a "User" object or a "House" class, they cannot be stored here.

There is however a workaround, which is to use .

Objects and Arrays are a little more complex to deal with, so they have their own page. See for more information.

The usage for the set() method is simple:

• key must be a string or integer. A key should be unique, otherwise it will be overwritten by new values using the same key.

• value must be a supported native data type as mentioned above.

Here are a few examples of writing simple data values:

Retrieving Data

Getting data back from an Enmap is just as simple as writing to it. All you need is the key of what you want to retrieve, and you get its value back!

That's pretty much it for only retrieving a single data value. There are more complex operations that are available, take a look at for the more advanced things you can do on Enmap's data!

Deleting Data

Removing data from Enmap is as simple as saving or retrieving. You can easily use the delete() method as such:

Upgrading to enmap v4 requires a little bit of migration, as Enmap 4 changed the internal method by which data is stored, slightly. To use this migration:

• Make a copy of your current app in a new folder.

• Create a new folder "on the same level" as your bot. Name it something like "migrate"

• You should now have 3 folders. Something like mybots/coolbot , mybots/coolbot-copy , mybots/migrate/

• In the migrate folder, run npm i enmap@3.1.4 enmap-sqlite@latest , as well as whatever source provider you need if it's not sqlite (in my example, npm i enmap-mongo@latest

You should now have something like the following image.

In the migrate folder, create an index.js and use the following script for migration. Note that it's an example, change the provider option to fit what you're actually using.

Very important: the "target" must be enmap-sqlite. Enmap v4 only supports an sqlite-backend.

From the migrate folder, run node index.js, which should correctly migrate your data.

Simpler migration from enmap-sqlite

If you're using enmap-sqlite already, you don't really need to do the entire thing above. Adding a single file called migrate.js to your project folder, then running it with node migrate.js will convert the format and then all you need is to modify the code for Enmap 4. Still, I recommend backing up your bot first. Just in case.

Code Changes

There is very little you need to change when moving to Enmap 4. The only changes that are required after migrating is the initialization of your Enmap which is now simpler.

If using Enmap.multi(), the change is just as simple:

The rest of your code (all interactions with Enmap) can remain the same - there should be no need to edit any of it.

Installing V4

Once your data is migrating and the code is changed, you can go ahead and install enmap version 4 through npm i enmap@latest in your "new" bot folder (the target of the migration). This will take a few minutes (it needs to rebuild sqlite) and output that 4.0.x is now installed. Start the bot, and it should be working! If it doesn't, join the support server and we'll help you out ^_^.

Enmap is a wrapper around better-sqlite3, which requires to be built directly on your system. As such, you need to install pre-requisites first. Please follow these instructions to the letter. If it's not written here, you probably shouldn't do it unless you know why you're doing it.

Pre-Requisites

How to install the pre-requisites depends on your operating system, so see below for instructions:

Installing Enmap

Once those pre-requisites are installed (if they're not, scroll up, and follow the instructions), and you've closed all open command prompts, open a new, normal (not-admin) command prompt or terminal in your project, then install Enmap using the following command:

This will take a few minutes, as it needs to build better-sqlite3 from source code, and then install enmap itself. Note that "a few minutes" can be 1 or 30 minutes, it really depends on your hardware and configuration.

If you get any errors, please see the . If the guide doesn't help, join the Discord (link at the top of this page).

In a whole lot of methods for Enmap, one of the properties is the "path". Paths are used in Object data saved in Enmap, that is to say, setting or ensuring a value that is an object at the top level.

To understand what a path really means, we can start by having an object as a value. Here I'm not even using Enmap, as the idea is related to basic JavaScript, not my module.

So here we have an object that actually has multiple levels, that is to say, the c and sub properties have, as a value, another object with its own keys. sub takes this further with 4 different levels, just to fully demonstrate my point.

So how would we reach the values in this object? Well, in core JavaScript, let's say we wanted to get the word "cool", we'd use myObject.sub.values.are.cool. This is one way to access object properties, the other one being myObject["sub"]["values"]["are"]["cool"] (where those strings can be variables, btw, for dynamic property access).

Alright so what about the array, there? Well, arrays are accessed through their index, meaning their position in the array, starting at 0. That means to access the c.and values, you'd do something like myObject.c.and[0] . That looks like a strange syntax I'll admit, but considering you can use the same for objects, myObject["c"]["and"][1] perhaps looks a bit more coherent.

Doing it in Enmap

Now that you've seen how to access those properties in regular JavaScript, what about doing it in Enmap? Well, it's actually quite simple: the path parameter in the methods simply take exactly what you've seen above, with 2 exceptions:

• The path doesn't include the object name (which is your key)

• You don't need to use variables for dynamic paths since it's a string

What does that mean in reality? Well let's rewrite the example above as Enmap code:

To access the "cool" string, the code then becomes myEnmap.get("myObject", "sub.values.are") . Accessing the array values looks the same: myEnmap.get("myObject", "c.and[0]") . In this case indexes can be used either way, so you can also do myEnmap.get("myObject", "c.and.0") and that'll work equally well.

Enmap stands for "Enhanced Map", and is a data structure based on the native JavaScript Map() structure with additional helper methods from the native Array() structure. Enmap also offers persistence, which means it will automatically save everything to save to it in a database, in the background, without any additional code or delays.

Why Enmap?

While there are other better-known systems that offer some features of Enmap, especially caching in memory, Enmap is targeted specifically to newer users of JavaScript that might not want to deal with complicated systems or database queries.

Advantage/Disadvantage

Here are some advantages of using Enmap:

• Simple to Install: Enmap itself only requires a simple npm install command to install and use, and a single line to initialize. .

• Simple to Use: Basic Enmap usage can be completely done with 1-2 lines of initialization, and 3 commands, set(), get() and delete().

Some disadvantages, compared to using a database connection directly:

• More memory use: Since Enmap resides in memory and (by default) all its data is loaded when it starts, your entire data resides in RAM. When using a large amount of data on a low-end computer or VPS, this might be an issue for some users.

• Limited power: You can have multiple Enmap "tables" loaded in your app, but they do not and cannot have relationships between them. Basically, one Enmap value can't refer to another value in another Enmap. This is something databases can be very good at, but due to the simplistic nature of Enmap, it's not possible here.

As described in the home page, one disadvantage of Enmap is that it loads all your data in memory, so you're sacrificing RAM in order to gain speed. In larger projects, this might become a concern fairly quickly - or when using larger data sets that take more memory.

For this purpose, there are features in Enmap that enable less caching, by sacrificing some speed and ease of use. That is to say, with data not being fully loaded, there are some things that can't be done easily - see below for details.

The options are as follow:

• fetchAll: Defaults to true, which means fetching all keys on load. Setting it to false means that no keys are fetched, so it loads faster and uses less memory.

  autoFetch: Defaults to true. When enabled, will automatically fetch any key that's requested using get, getProp, etc. This is a "synchronous" operation, which means it doesn't need any of this promise or callback use.

What does it mean if the data isn't loaded?

If fetchAll is set to false, no data (by default) will be loaded from the database - the Enmap will be completely empty. This means that doing a .size check returns 0, looping and filtering doesn't return anything, and get() requests all return null.

Ok but... how's that useful? It's useful because if you don't need the data, it's not loaded. To load data, there are 2 different methods available.

Fetching Data

• enmap.fetchEverything() will, of course, fetch all the data from the database - this is the method that's called on init() if fetchAll is true. This means you can stagger your loading time, or that you can decide, later, under certain conditions, you do want to load everything.

• enmap.fetch(key) can fetch a single key from the database, saves it to enmap, and returns a promise with the fetched value.

That's it!

Yup. Those are the only things you really need to know for the current version of Enmap's fetchAll feature.

Enmap is a great way to store structured data, and offers a few helper features that directly affect both objects and arrays.

Let's assume for a moment that we want to store the following data structure in Enmap:

This structure has 5 "properties": first, second, changeme, isCool, sub. The sub property has 2 properties of its own, yay and thing.

To store this structure in Enmap, you can use a variable, or just straight-up write the object:

Note: All further methods require the value to be an object. If you attempt to get, set, modify or remove using the below methods and your value isn't an object, Enmap will throw an error.

Getting properties

Retrieving a specific property from an object is done through the get() method, by specifying both the key and the "path" to the property you want.

The exact method is <Enmap>.get(key, path).

Checking if a property exists

You can also check if a specific property exists or not. This is done through the has method, with a key, and path to the property:

Modifying Properties

There are a few various ways to modify properties of both Objects and Arrays. The very basic way to set a property on an object or array is through .set(key, value, path) like the following examples:

As you can see, setProp() and getProp() work on the same concept that the path can be as complex as you want.

Arrays have additional helper methods, .

This points bot is simple, but functional. Make sure you've followed the Installation Instructions before doing the following.

First, you need to create a new persistent Enmap. Here's how it goes:

That will create a new Enmap under the name of points, and attaches it to the client object so it can be used where ever you have access to the client object.

Accumulating Points

The obvious goal of a points system is to accumulate fake internet points and gloat about it. So, of course, that's going to be our first focus. In this example implementation, we will make the points guild-specific, and unusable in DMs. Points will still accumulate even if the user does a command, which simplifies our code a bit.

Our starting point is a very basic message handler with pre-existing commands - such as what we see in the page on An Idiot's Guide. The code is as such:

We do have a small caveat - we really don't want to react on Direct Messages, so our whole code will be in a block that checks for that:

Our very first step is going to be to initialize a new entry in the enmap for any new user - one we haven't received a message from before. This is done using the enmap.ensure(key, defaultvalue) method, which can check if a specific key exists in the Enmap, write it if it doesn't (and return the defaultvalue in this case). Note that our keys take the format of guildid-userid so they're unique to the guild and the user. Also, our data in this case is a complete object, which we'll take advantage of fully.

There's obviously a few ways we could have done this, including some fancy ternary condition or whatever. I will, however, keep this code as simple to read as possible.

The following bit is super simple - Enmap has a method to directly increment a value in Enmap even if it's in an object. Pretty clever if I do say so myself!

Ding!

Time to level up! If a user has enough points, they will go up a level. Now we have to do some math here, but don't run off in fear, this one's pretty easy. This is how we calculate the levels:

This line will calculate the square root of currentPoints then multiplies that result by 0.1 then floors that result for a round number.

Now we should work out if you've amassed enough points to actually level up, by grabbing the current user's level and comparing them. If the new calculated level is higher, it means the user leveled up and we can deal with that, first by sending them a very annoying mee6-inspired message!

Lastly, we want to update the score.level value with the new level so throw this under the message.reply.

So here's the whole thing from top to bottom, with bonus comments!

Points & Level Commands

Alright, that's the bulk of the code, you could throw this into your bot and it would work like a charm, however your users wouldn't know how many points, or even their levels, so let's fix that, make a new command called points, which will also show them their level.

So let's re-iterate our current starting position.

The points command would look like this:

We are the champions, my friend!

Let's finish this off with a very simple leaderboard command that will show the top 10 users in the current guild. For this we'll need to filter the Enmap to only get the users for the current guild, then we'll convert the results to an array, sort that, and keep the first 10 results only.

So here's our leaderboard command:

ADDENDUM: Extra Commands!

A common issue

When Enmap is used with its default options, it loads everything in its cache and generally provides your data from this cache, not directly from the database. In the case where you want to use the data from one Enmap from multiple locations, you might encounter the following issue:

Hi! When I update data in Enmap from one file, it doesn't update in the other file, I have to restart the bot to update. Is this a bug?

To answer my own obvious question: it's not a bug, it's a feature that I cannot implement. The way Enmap's cache works is that the data is loaded in memory _in that _of Enmap, and only for that instance. This is what enables you to have many different Enmaps in your project - one Enmap doesn't share data with another.

However, this also means that when you do new Enmap({ name: "something" }) from more than one file, that's also a different instance, that doesn't share the same memory space. So not only will it not update the data in memory for the other file, it also uses double the memory. And of course, that's bad. So how do we fix this?

The Shared Variable Method

Admittedly, the vast majority of you Enmap users are doing Discord.js Bots, and even though Enmap works fine with any nodejs project that need simple data storage, bots are my main clients. Considering this fact, we have an extremely simple way to share an Enmap between multiple files: We attach it to the bot client. Usually your client is defined in your main file (index.js, app.js, bot.js, whatever you named it), and every part of your bot has access to this client. We can attach Enmap directly to it, like so:

This will work even if you're using a command handler, framework, or whatever - as long as you have access to a client variable, you have access to your enmaps.

In other frameworks and libraries, you might have something similar. For example with Express or Koa for http servers, you can sometimes attach the enmap to your request from the very top, in a middleware. If that's not possible, or if you find that to be complicated, you can use the next method.

The Module Method

All things considered, are probably the recommended way to use your Enmap in multiple files within your project. Not only does it give you a single file to import, lets you define multiple Enmaps you can individually import, it also gives you the ability to add specific functions to do common actions you use throughout your project.

As covered in , modules are fairly straightforward. This is how I have done an Enmap shared module before:

This means you can simply require that file elsewhere. Let's say we called that file db.js , here's how you'd use it:

And as I mentioned, as a bonus you now have the ability to create functions which you can export and use, to simplify your code and remove duplication. So, let's say I need to get all the tags for a specific guild, and my tags are built using an object as shown above. To get all those tags for a guild, you'd need filters, right? Like so:

now let's say you use this code a lot in your app, and you'd like to not have to type this whole thing every time. You could add a simple function in your module that only takes an ID and returns the tags:

And there you have it! There are other ways to build the exports, you can also split it differently, take a look at for more information.

It's Taking Suuuuuuuuuuuuuuuuuper Long to Install! Whats up with that?

Your computer has to install some programs and then build everything from source. This is going to take a while depending on your computer speed. Patience is key. We can't speed it up for you. It may look like its frozen but it is not.

My Question Isn't Answered Here!

Please make sure you read the first. If you can't find what your looking for you can join the discord .

MSB3428: Could not load the Visual C++ component "VCBuild.exe"

The following is the complete list of methods available in Enmap. As it is auto-generated from the source code and its comments, it's a little more "raw" than the Usage docs. However, it has the benefit of being more complete and usually more up to date than the manually written docs.

new Enmap(iterable, [options])

Initializes a new Enmap, with options.

Example

enmap.count ⇒ integer

Retrieves the number of rows in the database for this enmap, even if they aren't fetched.

Kind: instance property of Returns: integer - The number of rows in the database.

enmap.indexes ⇒ array.<string>

Retrieves all the indexes (keys) in the database for this enmap, even if they aren't fetched.

Kind: instance property of Returns: array.<string> - Array of all indexes (keys) in the enmap, cached or not.

enmap.autonum ⇒ number

Generates an automatic numerical key for inserting a new value. This is a "weak" method, it ensures the value isn't duplicated, but does not guarantee it's sequential (if a value is deleted, another can take its place). Useful for logging, actions, items, etc - anything that doesn't already have a unique ID.

Kind: instance property of Returns: number - The generated key number. Example

enmap.set(key, val, path) ⇒

Sets a value in Enmap.

Kind: instance method of Returns: - The enmap.

Example

enmap.update(key, valueOrFunction) ⇒ *

Update an existing object value in Enmap by merging new keys. This only works on objects, any other value will throw an error. Heavily inspired by setState from React's class components. This is very useful if you have many different values to update and don't want to have more than one .set(key, value, prop) lines.

Kind: instance method of Returns: * - The updated, merged value.

Example

enmap.get(key, path) ⇒ *

Retrieves a key from the enmap. If fetchAll is false, returns a promise.

Kind: instance method of Returns: * - The value for this key.

Example

enmap.observe(key, path) ⇒ *

Returns an observable object. Modifying this object or any of its properties/indexes/children will automatically save those changes into enmap. This only works on objects and arrays, not "basic" values like strings or integers.

Kind: instance method of Returns: * - The value for this key.

enmap.fetchEverything() ⇒

Fetches every key from the persistent enmap and loads them into the current enmap value.

Kind: instance method of Returns: - The enmap containing all values.

enmap.fetch(keyOrKeys) ⇒ | *

Force fetch one or more key values from the enmap. If the database has changed, that new value is used.

Kind: instance method of Returns: | * - The Enmap, including the new fetched values, or the value in case the function argument is a single key.

enmap.evict(keyOrArrayOfKeys) ⇒

Removes a key or keys from the cache - useful when disabling autoFetch.

Kind: instance method of Returns: - The enmap minus the evicted keys.

enmap.changed(cb)

Function called whenever data changes within Enmap after the initial load. Can be used to detect if another part of your code changed a value in enmap and react on it.

Kind: instance method of

Example

enmap.close() ⇒ Promise.<*>

Shuts down the database. WARNING: USING THIS MAKES THE ENMAP UNUSEABLE. You should only use this method if you are closing your entire application. This is useful if you need to copy the database somewhere else, or if you're somehow losing data on shutdown.

Kind: instance method of Returns: Promise.<*> - The promise of the database closing operation.

enmap.push(key, val, path, allowDupes) ⇒

Push to an array value in Enmap.

Kind: instance method of Returns: - The enmap.

Example

enmap.math(key, operation, operand, path) ⇒

Executes a mathematical operation on a value and saves it in the enmap.

Kind: instance method of Returns: - The enmap.

Example

enmap.inc(key, path) ⇒

Increments a key's value or property by 1. Value must be a number, or a path to a number.

Kind: instance method of Returns: - The enmap.

Example

enmap.dec(key, path) ⇒

Decrements a key's value or property by 1. Value must be a number, or a path to a number.

Kind: instance method of Returns: - The enmap.

Example

enmap.ensure(key, defaultValue, path) ⇒ *

Returns the key's value, or the default given, ensuring that the data is there. This is a shortcut to "if enmap doesn't have key, set it, then get it" which is a very common pattern.

Kind: instance method of Returns: * - The value from the database for the key, or the default value provided for a new key.

Example

enmap.has(key, path) ⇒ boolean

Returns whether or not the key exists in the Enmap.

Kind: instance method of

Example

enmap.includes(key, val, path) ⇒ boolean

Performs Array.includes() on a certain enmap value. Works similar to .

Kind: instance method of Returns: boolean - Whether the array contains the value.

enmap.delete(key, path) ⇒

Deletes a key in the Enmap.

Kind: instance method of Returns: - The enmap.

enmap.clear()

Deletes everything from the enmap. If persistent, clears the database of all its data for this table.

Kind: instance method of

enmap.destroy() ⇒ null

Completely destroys the entire enmap. This deletes the database tables entirely. It will not affect other enmap data in the same database, however. THIS ACTION WILL DESTROY YOUR DATA AND CANNOT BE UNDONE.

Kind: instance method of

enmap.remove(key, val, path) ⇒

Remove a value in an Array or Object element in Enmap. Note that this only works for values, not keys. Note that only one value is removed, no more. Arrays of objects must use a function to remove, as full object matching is not supported.

Kind: instance method of Returns: - The enmap.

Example

enmap.export() ⇒ string

Exports the enmap data to a JSON file. WARNING: Does not work on memory enmaps containing complex data!

Kind: instance method of Returns: string - The enmap data in a stringified JSON format.

enmap.import(data, overwrite, clear) ⇒

Import an existing json export from enmap from a string. This data must have been exported from enmap, and must be from a version that's equivalent or lower than where you're importing it.

Kind: instance method of Returns: - The enmap with the new data.

enmap.array() ⇒ Array

Creates an ordered array of the values of this Enmap. The array will only be reconstructed if an item is added to or removed from the Enmap, or if you change the length of the array itself. If you don't want this caching behaviour, use Array.from(enmap.values()) instead.

Kind: instance method of

enmap.keyArray() ⇒ Array.<(string|number)>

Creates an ordered array of the keys of this Enmap The array will only be reconstructed if an item is added to or removed from the Enmap, or if you change the length of the array itself. If you don't want this caching behaviour, use Array.from(enmap.keys()) instead.

Kind: instance method of

enmap.random([count]) ⇒ * | Array.<*>

Obtains random value(s) from this Enmap. This relies on .

Kind: instance method of Returns: * | Array.<*> - The single value if count is undefined, or an array of values of count length

enmap.randomKey([count]) ⇒ * | Array.<*>

Obtains random key(s) from this Enmap. This relies on

Kind: instance method of Returns: * | Array.<*> - The single key if count is undefined, or an array of keys of count length

enmap.findAll(prop, value) ⇒ Array

Searches for all items where their specified property's value is identical to the given value (item[prop] === value).

Kind: instance method of

Example

enmap.find(propOrFn, [value]) ⇒ *

Searches for a single item where its specified property's value is identical to the given value (item[prop] === value), or the given function returns a truthy value. In the latter case, this is identical to .

All Enmap used in Discord.js are mapped using their `id` property, and if you want to find by id you should use the `get` method. See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.

Kind: instance method of

Example

Example

enmap.findKey(propOrFn, [value]) ⇒ string | number

Searches for the key of a single item where its specified property's value is identical to the given value (item[prop] === value), or the given function returns a truthy value. In the latter case, this is identical to .

Kind: instance method of

Example

Example

enmap.sweep(fn, [thisArg]) ⇒ number

Removes entries that satisfy the provided filter function.

Kind: instance method of Returns: number - The number of removed entries

enmap.filter(fn, [thisArg]) ⇒

Identical to , but returns a Enmap instead of an Array.

Kind: instance method of

enmap.filterArray(fn, [thisArg]) ⇒ Array

Identical to .

Kind: instance method of

enmap.map(fn, [thisArg]) ⇒ Array

Identical to .

Kind: instance method of

enmap.some(fn, [thisArg]) ⇒ boolean

Identical to .

Kind: instance method of

enmap.every(fn, [thisArg]) ⇒ boolean

Identical to .

Kind: instance method of

enmap.reduce(fn, [initialValue]) ⇒ *

Identical to .

Kind: instance method of

enmap.clone() ⇒

Creates an identical shallow copy of this Enmap.

Kind: instance method of Example

enmap.concat(...enmaps) ⇒

Combines this Enmap with others into a new Enmap. None of the source Enmaps are modified.

Kind: instance method of

Example

Enmap.multi(names, options) ⇒ Array.<Map>

Initialize multiple Enmaps easily.

Kind: static method of Returns: Array.<Map> - An array of initialized Enmaps.

Example

While Enmap is a Map enhanced with Array methods, Enmap also offers some enhanced array methods for the data stored inside of it. Talk about Arrayception!

So what do I mean by methods for your stored data? I mean that you can store arrays inside Enmap, and directly push, pull, add and remove from those arrays. There are methods to work both on direct arrays, as well as arrays stored inside of an object.

Let's take a look at three example entries in Enmap that we can use. The first is a direct array, the second is an array inside an object, the last is an array of objects.

myEnmap.set("simpleArray", [1,2,3,4,5]);

myEnmap.set("arrInObj", {
  name: "Bob",
  aliases: ["Bobby", "Robert"]
});


myEnmap.set('objectarray', [{ a: 1, b: 2, c: 3 }, { d: 4, e: 5, f: 6 }]);

Adding to the array

There are two methods to push to an array, one for simple arrays and one for arrays inside objects. Pushing in an Enmap array is the same as a regular array push: it adds the element to the end of the array.

The third parameter in push is the "path" to the array in an object. It works the same as the properties path used in .

Removing from the array

Similarly, you can remove from an array. With the normal path system, you can either remove via the index in the array, or remove simple strings. To remove a complex object, you'll need to use a function in the remove method.

Some quick docs:

enmap.math(key, operation, operator, [objectPath])

Possible Operators (accepts all variations listed below, as strings):

• +, add, addition: Increments the value in the enmap by the provided value.

• -, sub, subtract: Decrements the value in the enmap by the provided value.

enmap.inc(key, [objectPath])

enmap.dec(key. [objectPath])

Introduced in Enmap 5.6, Serializers and Deserializers are functions that you use to manipulate the data before storing it in the database, or before using it after retrieving it.

This feature is born from a limitation in Enmap: it cannot store very complex objects, such as the instance of a class, objects with circular references, functions, etc. So, typically when you have such data, you need to manually convert it to some simple representation before storing, and then do the inverse after getting it from enmap. This is a more automated way of doing it.

What are they?

The Serializer function runs every single time data is stored in the enmap, if one is provided. This function receives the data provided to set() as an input, and must return a value to be stored in the database. This function MUST be synchronous, that is to say, cannot be an async function or return a promise.

The Deserializer function is the reverse, and runs on each value pulled from the database, before it is returned through the get() method. This function receives the data stored in the database and returns the value that you want to use directly. This function MUST be synchronous, that is to say, cannot be an async function or return a promise.

Examples

Guild Settings: A more sensible example

Taking a hit from my own example of Per-Server Settings, this is a better example that doesn't require storing just the name of a channel, but straight-up the channel itself.

This example uses a very, very simple bot made in discord.js to demonstrate how easily Enmap can be used to create a per-server configuration system.

Remember to follow the Installation Instructions before running any of this!

Initializing

Our first task is of course to initialize the enmap correctly. In this case, we're attaching the settings to our client object so we can use it in different commands.

Events Setup

Message Event

The main event for our bot, where messages are received. Any error here will probably crash the bot on every message received, so be careful!

Command to set configurations

Command to show the configuration

In this example we'll be using Enmap to store user data in order to authenticate users on a simple Koa application. In order to make this secure, we'll be using bcrypt to encrypt the passwords, so of course they will not be plain text in the database.

Requirements

We'll be using koa as a web server module, along with koa-session in order to store the session information. Additionally, for ease of use, koa-router is used to simplify the route code.

This tutorial uses koa-session which, by default, is insecure since it stores the entire session data in a browser cookie. This means the password, though encrypted, would be availble in the cookie, and easy to spoof. There are many session stores available for different storage system, but using them is beyond the scope of this example.

To install those requirements, run the following in a new, empty folder for your project:

Once all of those are installed, we're ready to start! We're going to create an index page, login page, and one "protected" page that requires login. Let's start with the top of the file, which is all the required modules:

So now we have all the basics necessary.

Account Creation Function

Let's create a few functions specifically for the login features, related to enmap. First, a function to create a new user:

This function takes in the following arguments:

• username which obviously is self-explanatory: it's the username entered during login.

• name is the "full name" or "display name", for a friendly display on the page or an email.

• plainpw

The function first checks if the username exists and returns an error if it does. It then generates a salted, hashed version of the password which it stores in the database. Don't let the name fool you, the password is not "encrypted", which implies that it can be decrypted. Instead, it's a "cryptographic hash functions", a unidirectional function that cannot be undone. The only way to verify that a password is correct is to re-hash it again and compared the hashes.

Once the hashed password is obtained, the user itself is stored in the database with all 4 incoming arguments except the password which is the hashed version.

Login Function

The login function takes in the username and the incoming plain password and verifies that the hashed version corresponds with the one stored in the database.

An important point here is that this function returns a promise in all cases. If the username doesn't exist or the password is blank, a false response is returned in a promise. Otherwise, the response of bcrypt's compare function is returned. This function returns true if the passwords match, false if they do not.

Defining some app settings

There's a few configuration items we need to take care of. First off, the session settings:

Then we need to setup how Koa will handle rendering EJS pages. This is one pretty awesome thing about Koa, that this can be setup automatically and globally, but don't let me gush all over this!

Basic Routes

So let's establish our "routes", which is the pages that can be accessed by the browser. With the help of the Router, this can be really straightforward.

Then we have the login route, which does a lot of the bulk of our work. It checks for login, and adds everything it needs to the session in Koa if the authentication is successful:

Let's also create a logout function, that simply destroys the current session and returns the user to the index:

This one is pretty straightforward, so I don't think I need to get into the details, right? ;)

Lastly, we have the route for our "private" page. the one that only works if you're logged in. Now, there are "better" ways to establish protected routes, but let's go with the simplest one for now. We're just going to check for the logged property of the session to determine if the user is logged in.

The End of the File

At the very end of our file we still have a bit of stuff to add. Mainly starting the server, but also telling the parser and routers to initialize. This would be how it's done:

Creating Templates

While templating is slightly beyond the scope of an authentication tutorial, I would be remiss to ignore the fact that logging in without a page would be... let's say a little hard.

Koa's EJS templating configuration, that we did above, means that templates need to appear in the views folder. There will be a few template files:

• template.html will be the "main" template. It will have the header, footer, and whatever else we want to appear on every page.

• index.html will be the main page everyone can access.

• login.html

Let's start with the template.html file.

The <%- body %> tag is where the contents of the other pages appear.

The index.html is just some welcome thingy that we aren't concerned about:

Then we have the login.html page which has our form. The form simply posts back to itself, so it'll trigger the .post endpoint:

And, finally, the secret.html page we've all been waiting for. Nothing that you haven't heard before, though:

With all said and done, . Want a more "advanced" version of this project? Check out .

An interesting problem in javascript is that having an array of objects can be quite the ordeal. A lot of things you want to do require functions and loops, bleh. So, where Enmap is meant to be easier to use, this is an area where it's still a bit hard to handle things.

But there's a solution. If Enmap isn't enough, how about **TWO ** Enmap???? So yeah, we're going to be using one enmap to store user data, and another to store "warnings", that is to say, moderation actions stored as objects.

When we add a new element to the actions enmap, we'll be adding a reference to that new entry in the user enmap, via the autonum feature.

If you've read about databases a bit, you might have heard about "autonum" and "automatic indexes" before, and this is exactly it. Alright let's get down to brass tax!

Why providers in the first place?

So one of the major changes from Enmap 3 to 4 is the removal of Providers. Providers were something I've had since Enmap 1.0 (when I converted from djs-collections-persistent), and had 2 advantages (2 reasons to have them in the first place).

As I've noted in my, when Enmap moved to SQLite only, there were a few feathers and features lost in transition. Most notably, the loss of Providers was a big one, even though in my opinion it was a good trade-off to get the new features I wanted to include in Enmap 4 and onward.

But since that moment where Providers were removed, I had a plan in mind to give those that needed them an escape route. And not only that, Enmap itself does have some pretty solid limitations when it comes to growth, because of its lack of ability to support multiple processes and sharded applications.

Introducing Josh

From the first moment where I started using the Discord.js library, one thing in it fascinated me: "Collections". Discord.js Collections are a Map structure from JavaScript on top of which a bunch of useful methods are added, most notably those from JavaScript's Array structure.

Things like map, filter, reduce, find, sort... they made Maps so useful, so much more powerful, that I admired their design. It struck me at one point, that if such a structure were to be separated from Discord.js and perhaps made to be saved in a database, it would make interacting with data so easy that even a child could do it.

So when I started getting seriously into bot that required their own data to be saved, I turned to Amish Shah (Hydrabolt) and I said to him, I said "Listen, buddy, can I extract Collections and publish them as a separate module? That'd be awesome!" and Amish replied, like the great guy he is, "uhhhh sure, why not?"

And so, in May 2017, the djs-collection module was born. It was a simple thing, just straight-up lifted from Discord.js' code (not illegally, mind you, I retained all proper licenses and credits to Hydrabolt!). The following month, I added persistence (saving to a database) to it and published

Enmap Partners

An Idiot's Guide