ls-jsondb
TypeScript icon, indicating that this package has built-in type declarations

1.10.2 • Public • Published

JSON Database

What's new?

If you want to read documentation, move down to Documentation header.

Version: 1.10

typescript and javascript support

Now this database supports both typescript and javascript code.
Also now ts-node is installed, so you can test your database without tsc compilation to js:
ts-node ./yourFile

backup system

Now you can backup an entire folder of tables or a single table.

constructor fixes

fixed some bugs with param: boolean | undefined, where if undefined, now uses force false.

Contact with me

You can add me in Discord: Squeens#6280
Or join my test Discord server: https://discord.gg/mKYuStucmp

Documentation

Variables

Main module declaration:

// ts
import { Database } from "ls-jsondb";
// js
const { Database } = require("ls-jsondb");

Declare a single database:

const anyVarName = new Database("path", Alerts?);

Alerts?: alert things to database?

Alerts: Boolean;

path is a String option to declare path to a folder with .json files aka tables.
you can use multiple amount of databases by creating new paths:

// for example:
const first = new Database("./first");
const second = new Database("./second");

Database class

constructor:

tablepath(String) is a path where are your .json tables stored.
alerts?(Boolean) is a parameter if you want to log all things happening.

tip: there are tooltips for every parameter and argument if you hover on any function or constructor.

Tables

Database#createTable(tablename, {strict}): void

tablename(String) is a .json file inside path you declared.
strict(Object) is an object of strict rules for this table. (more about this down below)

Database#removeTable(tablename): void

tablename(String) is a .json file inside path you declared.

Main

Database#write(tablename, key, value): void

tablename(String) is a .json file inside path you declared.
key(String) is a header of an Object.
value(Any) is a value.

{
  key: value;
}

Database#read(tablename, key): any | undefined

tablename(String) is a .json file inside path you declared.
key(String) is a header of an Object.

Returns Any

{
  key: value;
}

Database#edit(tablename, key, value, subvalue?): void

tablename(String) is a .json file inside path you declared.
key(String) is a header of an Object.
value(Any) is a value that you are editing inside of an Object.
subvalue?(Any) a value of parent value.
UPDATED: if subvalue === null or !subvalue it changes whole value.

{
  key: value;
}

Database#remove(tablename, key): void

tablename(String) is a .json file inside path you declared.
key(String) is a header of an Object.

{
  key: value = undefined;
}

Database#check(tablename, key): boolean

tablename(String) is a .json file inside path you declared.
key(String) is a header of an Object.

Returns Boolean

{
  key: value;
}

Database#checkIncrement(): void

checks if increment value is correct. If not creates a new one from backup file.

Database#readIncrement(): any | undefined

returns stringified Object of all increment values in console.

Database#editIncrement(tableName, value): vod

tableName(String) is a .json file inside path you declared (and also stored as a key for increment).
value(Number) is a numberic value-ofset of increment.

Backup

tip: there are tooltips for every parameter and argument if you hover on any function or constructor.

WARNING: this feature is currently in beta. May contain bugs.

Backup#createBackup(filename | dirname): void

filename(String) is a .json file you want to save for backup.

WARNING: this now requires to put ".json" at the end.

WARNING: if you want to save file from different folders with the same name, they will overwrite.

WARNING: Backup#createBackup() reads files in your working dir. Not in /backup/. If you want to save a single file from folder, type "dir/file.json" and it will save it to /backup/unsorted/.

dirname(String) is a directory, where all .json files you want to backup.

create a new backup of table or folder.

Backup#removeBackup(filename | dirname): void

filename(String) is a .json file you want to save for backup.

WARNING: this now requires to put .json at the end.

WARNING: Backup#removeBackup() reads files in /backup/ folder. Removing file, that you saved from previous derictory, is in /backup/unsorted/. Use single "file.json" syntax.

dirname(String) is a directory, where all .json files you want to backup.

remove backup files of table or folder.

Backup#restoreBackup(filename | dirname, directory): void

filename(String) is a .json file you want to save for backup.
directory(String|null) is a directory name where you want to backup your files. If null -> put in project dir.

WARNING: this now requires to put .json at the end.
> dirname(String) is a directory, where stored all of .json files you want to backup.

restore backup of the table or folder.

Backup#viewBackup(logs, returns): object | void

logs logs all of the saved files with time, when they were created.
returns returns object of all files:

{
  "unsorted": [
    "unsortedTable" // /backup/unsorted/unsortedTable.json
  ],
  "exampleDirectory": [
    "exmapleTable" // /backup/exampleDirectory/exampleTable.json
  ]
}

increment is also in /backup/system/ folder. You can't delete /system/ folder:

{
  "system": [
    "increment" // /backup/system/increment.json
  ],
}

Tools class

Tools#generateToken(length, {parameters?}): string

length(Number) is a length of the token.
alphabet? is a String value of all possible characters. If not stated, uses "ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789" by default.
nonallowed? is a String[] ['upperCaseString', 'lowerCaseString', 'numbers, 'others?'] of letters, that won't be used by the generator.


UPDATED: "others" works only if parameter alphabet stated.

Returns String

Tools#generateTable(table, length): string

table is an object, where value is an array.
length is how wide each column is. Can be replaced with "longest" and length will be the same as longest word in any column.


WARNING: table values accept only string, number and boolean types.

Returns String

other parameters

"AUTO_INCREMENT"

Put this inside value parameter or inside mother {Object}
For example:

database.write("test", "USER", { id: "AUTO_INCREMENT" });

and it will write it like that:

{
  "USER": {
    "id": 1
  }
}

increment value is written inside ./increment.json and writes like that:

{
  TABLENAME: VALUE; // Number
}

WARNING: can be used only once per table!
WARNING: do not use AUTO_INCREMENT value in edit() function.
WARNING: write() function creates a new version of the key so it always reroll AUTO_INCREMENT value.

STRICT MODE

This is a very complicated thing. Let's talk about it a little bit more.
When using createTable() function, you can add {parameters} after tableName property.
It automaticaly makes this table in strict mode: creates tableName-rules.json file.
Example of usage:

db.createTable("example", { id: "AUTO_INCREMENT", roles: "ARRAY" });

It creates empty file example.json and example-rules.json with:

{
  "id": "AUTO_INCREMENT",
  "roles": "ARRAY"
}

When you write or edit something in this table, it uses strict parameters:

db.write("example", "user", {
  id: "AUTO_INCREMENT",
  roles: ["ADMIN", "MODER"],
});

If, for example, you make "roles" as a STRING, it will throw an error:

db.write("example", "user", {
  id: "AUTO_INCREMENT",
  roles: "ADMIN",
  //     ^^^^^^^ typeof ≠ array.
});

console:

Error: in rule-file "roles" is instance of ARRAY

that's it.

Examples

createTable()

Default mode:

db.createTable("example");

Strict mode:

db.createTable("example", {
  id: "AUTO_INCREMENT",
  username: "STRING",
});

removeTable()

db.removeTable("example");

editIncrement()

db.editIncrement("example", 1);

readIncrement()

db.readIncrement();

write()

Default mode:

db.write("users", db.generateToken(12), {
  id: "AUTO_INCREMENT",
  username: "user",
});

Strict mode:

// rules:
{
  id: "AUTO_INCREMENT",
  username: "STRING",
}

db.write("users", db.generateToken(12), {
  id: "AUTO_INCREMENT", // rule -> returned true
  username: "user" // rule -> returned true
});

edit()

Default mode:

db.edit("users", db.generateToken(12), {
  // do not edit AUTO_INCREMENT
  username: "lissa",
});

// if you need to add a new line, just paste it:
db.edit("users", db.generateToken(12), {
  description: "example description.",
});

Strict mode:

// rules:
{
  id: "AUTO_INCREMENT",
  username: "STRING",
}

db.edit("users", db.generateToken(12), {
  // do not edit AUTO_INCREMENT values or create new ones.
  username: "lissa" // rule -> returned true
});

// you can't add new lines in strict mode.

remove()

db.remove("users", "aBc123dEf456");

check()

if (db.check("users", "aBc123dEf456") == true) doSomething();

read()

const user = db.read("users", "aBc123dEf456");

// for example returns:
aBc123dEf456: {
  "id": 1,
  "username": "Lissa",
  "description": "Example description."
}

console.log(user.id) // returns 1
console.log(user.username) // returns "Lissa"
console.log(user.description) // returns "Example description."

createBackup()

for all Backup methods use:

import { Backup } from "ls-jsondb";
// or
const { Backup } = require("ls-jsondb");

const anyVarName = new Backup();
backup.createBackup('database/exampleFile.json')
// will create a backup for unsorted group for exampleFile.json

backup.createBackup('database')
// will create a backup for entire folder and set it as parent sorting group.
// for example /database/ has test.json and users.json.
// it will write it as object to return in Backup#viewBackup() and it will be done in /backup/ folder like that:
{
  unsorted: [
    "exampleFile" // /backup/unsorted/exampleFile.json
  ],
  database: [
    "test", // /backup/database/test.json
    "users" // /backup/database/users.json
  ]
}

WARNING:

// if you want to save backup file from any dir: "dir/file.json", use this syntax. It counts as single file and saves to /unsorted/.
backup.createBackup("database/exampleFile.json"); // warning: dir connection syntax is kinda is kinda buggy. Tried our best to fix it, but still could have problems

removeBackup()

backup.removeBackup("exampleFile.json");
// will remove backup of exampleFile.json

backup.removeBackup("database");
// will remove backup of this folder with all files in it.

WARNING:

// if you want to remove backup file, you saved from "dir/file.json", type just "file.json", because it reads /unsorted/
backup.removeBackup("exampleFile.json");

restoreBackup()

backup.restoreBackup("exampleFile.json", "newDatabase");
// will restore backup of exampleFile.json

backup.restoreBackup("database", null);
// will restore backup of this folder with all files in it.

// or you can restore single file from sorted folder:
backup.restoreBackup("database/exampleFile.json", "newDatabase");

viewBackup()

backup.viewBackup(logs: true, returns: true)
// returns object of all backup files.
{
  system: [
    "increment" // /backup/system/increment.json
  ],
  unsorted: [
    "exampleFile" // /backup/unsorted/exampleFile.json
  ],
  database: [
    "test", // /backup/database/test.json
    "users" // /backup/database/users.json
  ]
}
// and logs all of them:

  system        |  unsorted        |  database    |
 -------------- | ---------------- | ------------ |
 increment.json | exampleFile.json | test.json    |
                |                  | users.json   |
                |                  |              |
 -------------- | ---------------- | ------------ |

generateToken()

const token = db.generateToken(
  12, // length -> required
  "abcdefABCDEF123456.", // alphabet -> nonrequired. if !alphabet -> uses default alphabet
  ["upperCaseString"] // nonallowed -> nonrequired. if !nonallowed -> uses all characters.
);
// generates token using "abcdefABCDEF123456." characters but without "ABCDEF".

// if you want to generate token with just nonallowed:
const token = db.generateToken(
  12,
  undefined, // use this.
  ["upperCaseString"]
);

generateTable()

const token = db.generateToken(
  {
    roles: ["admin", "moderator", "helper", "user"],
    people: ["keisi", "lissa"],
  },
  "longest" // or any number greater than longest.
);

returns:

| --------- | --------- |
| roles     | people    |
| --------- | --------- |
| admin     | keisi     |
| moderator | lissa     |
| helper    |           |
| user      |           |
| --------- | --------- |

Package Sidebar

Install

npm i ls-jsondb

Weekly Downloads

45

Version

1.10.2

License

ISC

Unpacked Size

60.5 kB

Total Files

12

Last publish

Collaborators

  • lissasqueens