You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -8,16 +8,16 @@ description: >-
8
8
9
9

10
10
11
-
JOSH is the JavaScript Object Storage Helper - a simple, effective, and efficient database wrapper. The idea of JOSH came out of my existing wrapper, Enmap, which suffers from two very unique but important flaws: 
11
+
JOSH is the JavaScript Object Storage Helper - a simple, effective, and efficient database wrapper. The idea of JOSH came out of my existing wrapper, Enmap, which suffers from two very unique but important flaws:
12
12
13
13
* It cannot scale very well, being locked to better-sqlite3 which doesn't support live data updates
14
-
* It requires the use of a cache, since most of its features, as used by most people, require the cache to be available. 
14
+
* It requires the use of a cache, since most of its features, as used by most people, require the cache to be available.
15
15
16
-
JOSH intends to solve both those problems that can't actually be resolved in Enmap itself, by moving away from the synchronous nature of better-sqlite3 and using [Promises](https://js.evie.dev/promises). In this way, JOSH can keep most of Enmap's features but add on a whole lot more. 
16
+
JOSH intends to solve both those problems that can't actually be resolved in Enmap itself, by moving away from the synchronous nature of better-sqlite3 and using [Promises](https://js.evie.dev/promises). In this way, JOSH can keep most of Enmap's features but add on a whole lot more.
17
17
18
-
Now that this history lesson is done, what exactly _is_ JOSH except being a contrast to something I've already done? 
18
+
Now that this history lesson is done, what exactly _is_ JOSH except being a contrast to something I've already done?
19
19
20
-
JOSH is a promise-based database wrapper that assists in quick prototyping and rapid development of Node.js applications that require data storage. It aims at removing some of the complexity of database management and communication by providing a _simple_ interface that anyone can pick up and use. 
20
+
JOSH is a promise-based database wrapper that assists in quick prototyping and rapid development of Node.js applications that require data storage. It aims at removing some of the complexity of database management and communication by providing a _simple_ interface that anyone can pick up and use.
21
21
22
22
JOSH can communicate with many different database systems through the use of _Providers_, which are a translation layer between the JOSH API and the Database system.
Copy file name to clipboardExpand all lines: development/contributing.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ description: Want to contribute to Josh's development? Please read this page!
4
4
5
5
# Contributing
6
6
7
-
I love coding, but sometimes, managing multiple projects can be a tough job. I welcome the contributions of the community to make the experience of using JOSH better. 
7
+
I love coding, but sometimes, managing multiple projects can be a tough job. I welcome the contributions of the community to make the experience of using JOSH better.
Copy file name to clipboardExpand all lines: development/testing.md
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
# Testing Stuff
2
2
3
-
If you feel the need to "test" JOSH's functionality from a command line, you're not alone, because I do to! That's why I created a very simple script that lets me directly import and interact with JOSH from the command line. That way I can set, get, delete, and do all the things without having to restart a script every time. 
3
+
If you feel the need to "test" JOSH's functionality from a command line, you're not alone, because I do to! That's why I created a very simple script that lets me directly import and interact with JOSH from the command line. That way I can set, get, delete, and do all the things without having to restart a script every time.
4
4
5
-
The script uses a simple `readline` module that's core to node, so really the only thing it needs to run is `josh` itself, and a provider such as `@josh-providers/sqlite` . 
5
+
The script uses a simple `readline` module that's core to node, so really the only thing it needs to run is `josh` itself, and a provider such as `@josh-providers/sqlite` .
6
6
7
7
You'll need to install the appropriate provider, see [Providers ](../providers/about.md)for instructions.
Copy file name to clipboardExpand all lines: getting-started/faq.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ Not really. While JOSH does have some features Enmap doesn't (such as providers,
12
12
13
13
There's a few indications that maybe you'd want to move away from this system.
14
14
15
-
One of them is if you need more control over the data and how it's stored. JOSH just throws anything you give it into a database, it makes no effort to check, type, or validate that data. 
15
+
One of them is if you need more control over the data and how it's stored. JOSH just throws anything you give it into a database, it makes no effort to check, type, or validate that data.
16
16
17
17
Another is if you require modelling ("models") or types for your data, as in, very specific limitations on what data can be stored. I've no intention of adding these features.
Copy file name to clipboardExpand all lines: getting-started/migrating-from-enmap.md
+12-13Lines changed: 12 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -6,33 +6,33 @@ description: >-
6
6
7
7
# Migrating from Enmap
8
8
9
-
While Josh and Enmap are based on the same basic concepts and ideas, there are some changes that will need to happen in your code if you want to move from Enmap to Josh. 
9
+
While Josh and Enmap are based on the same basic concepts and ideas, there are some changes that will need to happen in your code if you want to move from Enmap to Josh.
10
10
11
11
A few decisions I made here and there mean that unfortunately, almost all lines related to your database interactions will need to be changed one way or another, so before we start, I apologize from the bottom of my heart that this isn't as straightforward as "change a few lines and import the data". The significant work you'll have to do to convert is entirely my fault, so make sure that you _need_ to move to Josh before you start, otherwise, you're just adding pain onto yourself and I can't take all the blame for that.
12
12
13
13
## Why Migrate?
14
14
15
-
First off: you shouldn't just migrate from Enmap to Josh "just because Josh is newer". Josh isn't an _upgrade_ to Enmap, it's a different module altogether which offers only a few very clear benefit and two downsides that might not be worth it for you. 
15
+
First off: you shouldn't just migrate from Enmap to Josh "just because Josh is newer". Josh isn't an _upgrade_ to Enmap, it's a different module altogether which offers only a few very clear benefit and two downsides that might not be worth it for you.
16
16
17
17
The first reason why you _should_ migrate, is if you need to access your data from more than one process. For example, if you need to shard a discord.js bot, or if you want a dashboard separated from the bot itself. Or, if you simply have more than one app accessing the same database. Since Enmap doesn't do that (well, it "does" with polling but it's pretty crappy at it), going to Josh is a valid solution.
18
18
19
19
The second reason you'd want to migrate is if you want to move away from SQLite and want a database server that's more powerful or hosted remotely. Josh offers various providers that give you this capability.
20
20
21
21
## Before you migrate
22
22
23
-
So before you get into this, I would very strongly recommend you get very comfortable with the use of promises. Thing is, where Enmap doesn't use promises at all except for the defer option (which you usually don't need except for specific circumstances), Josh is quite the contrary: _Everything Is Promises_. So, if you don't understand async/await or how to resolve promises you're going to have a bad time. 
23
+
So before you get into this, I would very strongly recommend you get very comfortable with the use of promises. Thing is, where Enmap doesn't use promises at all except for the defer option (which you usually don't need except for specific circumstances), Josh is quite the contrary: _Everything Is Promises_. So, if you don't understand async/await or how to resolve promises you're going to have a bad time.
24
24
25
25
[The Promise page on my JS guide](https://js.evie.dev/promises) should cover most of the concepts required for you to use Josh so go through that page and then come back. I suggest using async/await whenever possible, and that's how I build all my examples and documentation.
26
26
27
27
_**MAKE A BACKUP OF YOUR PROJECT NOW**_. If you're using GIT that's simple, just make sure all your changes are commited. If not, just create a zip file or a copy of your project folder (it'll take time unless you delete node\_modules first).
28
28
29
29
## Step 1: Installation
30
30
31
-
The TL;DR of the Installation page is that you just need to run `npm i josh@latest` or `yarn add josh@latest` in your project to get Josh itself. You can simply do this in your project folder, because we can do all this within that folder without losing any data. 
31
+
The TL;DR of the Installation page is that you just need to run `npm i @joshdb/core` or `yarn add @joshdb/core` in your project to get Josh itself. You can simply do this in your project folder, because we can do all this within that folder without losing any data.
32
32
33
-
Then, you choose a provider and you install that, too, with its pre-requisites. In this example we're going for the SQLite provider, but the instructions should be identical for all of them except for the provider name. So in our case, with the windows-build-tools already installed (because you're using Enmap, you have those already!) we can just `npm i @josh-providers/sqlite` or `yarn add @josh-providers@sqlite` to add it. 
33
+
Then, you choose a provider and you install that, too, with its pre-requisites. In this example we're going for the SQLite provider, but the instructions should be identical for all of them except for the provider name. So in our case, with the windows-build-tools already installed (because you're using Enmap, you have those already!) we can just `npm i @joshdb/sqlite` or `yarn add @joshdb/sqlite` to add it.
34
34
35
-
With those 2 modules added we can continue on to the migration itself. DO NOT DELETE OR UNINSTALL ENMAP OR ITS DATA YET, obviously.
35
+
With those 2 modules added we can continue on to the migration itself. DO NOT DELETE OR UNINSTALL ENMAP OR ITS DATA YET.
36
36
37
37
## Step 2: Migration
38
38
@@ -65,7 +65,6 @@ const target = new Josh({
65
65
// so we're going to do that with an async IIFE to simplify things.
66
66
// An IIFE is just a function that runs immediately, in this case an async one.
67
67
(async () => {
68
-
awaitsource.defer;
69
68
console.log(`Loaded Enmap with ${source.count} rows to transfer`);
70
69
console.log(`Target JOSH currently has ${awaittarget.size} rows.`);
71
70
@@ -83,19 +82,19 @@ Now that the data is completely migrated, we're ready to move on. To verify that
83
82
84
83
## Step 3: Changing your Code
85
84
86
-
Now comes the hard part. You'll need to change your entire code for Josh. This includes every single line where you're getting, setting, or modifying the database. But, there are some general guidelines that will clarify exactly what changes need to be made. 
85
+
Now comes the hard part. You'll need to change your entire code for Josh. This includes every single line where you're getting, setting, or modifying the database. But, there are some general guidelines that will clarify exactly what changes need to be made.
87
86
88
87
The Initialization
89
88
90
-
This is an easy one: the initialization for Josh is exactly what you used above in the migration script. You import Josh, the Provider, then you initialize it with the new Josh() line. 
89
+
This is an easy one: the initialization for Josh is exactly what you used above in the migration script. You import Josh, the Provider, then you initialize it with the new Josh() line.
91
90
92
91
> There is currently no multi() method in Josh, this is in the works, though! For now each instance must be initialized separately.
93
92
94
93
### The Key/Path system
95
94
96
-
In Josh, there is no separate "key" and "path" when it comes to arguments. Basically I realized that with the various arguments between functions, it sometimes was vague or confusing what went where. To simplify this, it's now a single argument that starts each method where a key and/or path is necessary. 
95
+
In Josh, there is no separate "key" and "path" when it comes to arguments. Basically I realized that with the various arguments between functions, it sometimes was vague or confusing what went where. To simplify this, it's now a single argument that starts each method where a key and/or path is necessary.
97
96
98
-
So, the new system works as a single string, where each part is separated by a dot to indicate a level in the object. Let's see an example with set() first, to, errr, "set the table" as it were. 
97
+
So, the new system works as a single string, where each part is separated by a dot to indicate a level in the object. Let's see an example with set() first, to, errr, "set the table" as it were.
If you need to access a property that's nested in another level, you can just chain the path exactly as you would have in Enmap, so `await josh.set("somekey.a.foo.bar", "newvalue")` would set at the 3rd level of the object.
115
114
116
-
Every other method will have the same tweak, from push() and remove() in arrays to get() and has() and all these wonderful things. 
115
+
Every other method will have the same tweak, from push() and remove() in arrays to get() and has() and all these wonderful things.
117
116
118
117
{% hint style="info" %}
119
118
Since the key/path is a string you can use template literals for variables. For example, in a per-server settings context:
Because Josh is not cached in memory, there are a few little changes to the way array methods work. First and foremost it's important to know that for most providers, using the looping methods will cause a significant increase in temporary memory usage (because data still needs to be loaded in memory to be processed in most cases), and using a _path_ rather than a function is going to always be much faster and efficient. In fact, for providers supporting JSON data types (rethink, mongo, postgresql), using path equality means no data is loaded in memory, it's all database-processed and is faster by an order of magnitude. 
127
+
Because Josh is not cached in memory, there are a few little changes to the way array methods work. First and foremost it's important to know that for most providers, using the looping methods will cause a significant increase in temporary memory usage (because data still needs to be loaded in memory to be processed in most cases), and using a _path_ rather than a function is going to always be much faster and efficient. In fact, for providers supporting JSON data types (rethink, mongo, postgresql), using path equality means no data is loaded in memory, it's all database-processed and is faster by an order of magnitude.
129
128
130
129
{% hint style="info" %}
131
130
Josh support async functions for find(), filter() and some(). However, they will be slower due to "whatever async thing you're doing".
Copy file name to clipboardExpand all lines: providers/mongo.md
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -61,15 +61,15 @@ Mongo Atlas is a free mongodb hosting service made by, if that wasn't obvious, t
61
61
The setup for Mongo Atlas goes something like this:
62
62
63
63
* Get an account at [mongodb.com](https://www.mongodb.com/cloud/atlas)
64
-
* Once created, setup your cluster: 
64
+
* Once created, setup your cluster:
65
65
* Provider & Region: Up to you, I chose AWS in my test (but you might have a closer free region!). Make sure to select a "FREE TIER AVAILABLE" region!
66
66
* Keep the M0 cluster tier (the only free one). You may select backups if you want, other additional options are paid.
67
67
* Type in a cluster name of your choice. Something like `guidebot-cluster`.
68
68
* Click **Create Cluster**.
69
69
* Go make a sandwich, setup can take a while...
70
70
* Click the Collection button in the middle of the page.
71
71
* Click Create Database. Enter a name such as `guidebot-session` then a collection name such as `sessions`.
72
-
* Now that the cluster is created, we now need to get a connection string. But we need to create a user, which there's a wizard for. 
72
+
* Now that the cluster is created, we now need to get a connection string. But we need to create a user, which there's a wizard for.
73
73
* Click **Command Line Tools** at the top of the cluster window, then click **Connect Instructions**.
74
74
* Click **Add your Current IP** if you're on the machine that will host your bot. Otherwise, click **Add a Different IP Address** and enter it on the left. Click **Add IP Address**.
75
75
* Enter a database access _username_ and _password_, then click **Create MongoDB User**.
0 commit comments