Skip to content

Commit 0f2c465

Browse files
committed
Fix some issue in the migration guide
1 parent 17eded3 commit 0f2c465

File tree

11 files changed

+29
-30
lines changed

11 files changed

+29
-30
lines changed

README.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@ description: >-
88

99
![Credits: See bottom of page](.gitbook/assets/JOSH\_p\_light.svg)
1010

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:
1212

1313
* 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.
1515

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.
1717

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?
1919

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.
2121

2222
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.
2323

development/contributing.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Want to contribute to Josh's development? Please read this page!
44

55
# Contributing
66

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.
88

99
### What can you contribute?
1010

development/testing.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Testing Stuff
22

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.
44

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` .
66

77
You'll need to install the appropriate provider, see [Providers ](../providers/about.md)for instructions.
88

9-
Here's the script: 
9+
Here's the script:
1010

1111
```javascript
1212
const readline = require('readline');

getting-started/faq.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Not really. While JOSH does have some features Enmap doesn't (such as providers,
1212

1313
There's a few indications that maybe you'd want to move away from this system.
1414

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.
1616

1717
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.
1818

getting-started/install.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: How to install the JOSH Core Database Wrapper
44

55
# Installation
66

7-
JOSH is installed very simply through `yarn` or `npm`: 
7+
JOSH is installed very simply through `yarn` or `npm`:
88

99
```
1010
npm i @joshdb/core

getting-started/migrating-from-enmap.md

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,33 +6,33 @@ description: >-
66

77
# Migrating from Enmap
88

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.
1010

1111
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.
1212

1313
## Why Migrate?
1414

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.
1616

1717
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.
1818

1919
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.
2020

2121
## Before you migrate
2222

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.
2424

2525
[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.
2626

2727
_**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).
2828

2929
## Step 1: Installation
3030

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.
3232

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.
3434

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.
3636

3737
## Step 2: Migration
3838

@@ -65,7 +65,6 @@ const target = new Josh({
6565
// so we're going to do that with an async IIFE to simplify things.
6666
// An IIFE is just a function that runs immediately, in this case an async one.
6767
(async () => {
68-
await source.defer;
6968
console.log(`Loaded Enmap with ${source.count} rows to transfer`);
7069
console.log(`Target JOSH currently has ${await target.size} rows.`);
7170

@@ -83,19 +82,19 @@ Now that the data is completely migrated, we're ready to move on. To verify that
8382

8483
## Step 3: Changing your Code
8584

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.
8786

8887
The Initialization
8988

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.
9190

9291
> There is currently no multi() method in Josh, this is in the works, though! For now each instance must be initialized separately.
9392
9493
### The Key/Path system
9594

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.
9796

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.
9998

10099
```javascript
101100
// In Enmap, you did this:
@@ -113,7 +112,7 @@ await josh.set("somekey.a", "one");
113112

114113
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.
115114

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.
117116

118117
{% hint style="info" %}
119118
Since the key/path is a string you can use template literals for variables. For example, in a per-server settings context:
@@ -125,7 +124,7 @@ await client.settings.get(`${message.guild.id}.disabledCommands`);
125124

126125
### Find, Filter and other loops
127126

128-
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.
129128

130129
{% hint style="info" %}
131130
Josh support async functions for find(), filter() and some(). However, they will be slower due to "whatever async thing you're doing".

getting-started/usage.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Basic Usage
22

3-
\[ TBD ] - Documentation isn't yet ready fully but here's a few examples: 
3+
\[ TBD ] - Documentation isn't yet ready fully but here's a few examples:
44

55
```javascript
66
const Josh = require("@joshdb/core");

providers/indexeddb.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ There are not provider options with the IndexedDB provider, but an empty option
1212

1313
### Using with Webpack
1414

15-
To use with Webpack, install with your project: 
15+
To use with Webpack, install with your project:
1616

1717
```
1818
npm i @joshdb/indexeddb

providers/json.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ yarn add @joshdb/json
1818

1919
### Usage
2020

21-
Here's how you setup and use the JSON provider: 
21+
Here's how you setup and use the JSON provider:
2222

2323
```javascript
2424
const Josh = require('@joshdb/core');

providers/mongo.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,15 +61,15 @@ Mongo Atlas is a free mongodb hosting service made by, if that wasn't obvious, t
6161
The setup for Mongo Atlas goes something like this:
6262

6363
* Get an account at [mongodb.com](https://www.mongodb.com/cloud/atlas)
64-
* Once created, setup your cluster: 
64+
* Once created, setup your cluster:
6565
* 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!
6666
* Keep the M0 cluster tier (the only free one). You may select backups if you want, other additional options are paid.
6767
* Type in a cluster name of your choice. Something like `guidebot-cluster`.
6868
* Click **Create Cluster**.
6969
* Go make a sandwich, setup can take a while...
7070
* Click the Collection button in the middle of the page.
7171
* 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.
7373
* Click **Command Line Tools** at the top of the cluster window, then click **Connect Instructions**.
7474
* 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**.
7575
* Enter a database access _username_ and _password_, then click **Create MongoDB User**.

providers/sqlite.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: >-
66

77
# SQLite
88

9-
SQLite communication is provided by better-sqlite3. 
9+
SQLite communication is provided by better-sqlite3.
1010

1111
This provider requires building better-sqlite3 from source, so you'll need to make sure your system is ready for that.
1212

0 commit comments

Comments
 (0)