0db - npm Package Compare versions

Comparing version 0.0.0 to 0.0.1

index.js

@@ -1,1 +0,39 @@
-console.log("0db");
+//==============================================================================
+// ■ 0db (0db/index.js)
+//------------------------------------------------------------------------------
+//     Main entry point.
+//==============================================================================
+const fileProvider = require("./core/file");
+const collectionProvider = require("./core/collection");
+const crudProvider = require("./core/crud/");
+const { isEmpty } = require("./utils/type");
+
+//------------------------------------------------------------------------------
+// ► Exports
+//------------------------------------------------------------------------------
+module.exports = odb;
+
+//------------------------------------------------------------------------------
+// ● Odb-Main
+//------------------------------------------------------------------------------
+async function odb(filePath = "./db.json") {
+  const file = fileProvider(filePath);
+  let dataObj = await file.load();
+  if (isEmpty(dataObj)) await file.save(dataObj);
+  const db = (collectionName) => dbApi(collectionName, dataObj, file.save);
+  db.file = file;
+  db.dataObj = dataObj;
+  db.drop = async () => {
+    dataObj = {};
+    file.save(dataObj);
+  };
+  return db;
+}
+
+//------------------------------------------------------------------------------
+// ● Db-Api
+//------------------------------------------------------------------------------
+function dbApi(collectionName, dataObj, save) {
+  const collection = collectionProvider(collectionName, dataObj, save);
+  return crudProvider(collection);
+}

package.json

 {
   "name": "0db",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Simple JSON file database.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "readme": "markdown-toc -i README.md",
+    "test": "nodemon $test/ --ignore db.json --ignore big.db.json"
   },
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "i": "^0.3.7",
+    "jsonwebtoken": "^8.5.1",
+    "lodash": "^4.17.21",
+    "uuid": "^8.3.2"
+  },
+  "devDependencies": {},
+  "author": "Ambratolm <[e-mail]>",
+  "license": "MIT",
   "repository": {
@@ -23,4 +34,2 @@ "type": "git",
   ],
-  "author": "Ambratolm <[e-mail]>",
-  "license": "MIT",
   "bugs": {
@@ -27,0 +36,0 @@ "url": "https://github.com/Ambratolm/0db/issues"

README.md

@@ -1,26 +0,466 @@
-[ 🚧 Name reservation ] ⚙️ Work in progress...
-<hr />
+> ### 🚧 Work in progress...
 
-# 0db
+# ⭕ 0db
 
 [![NPM version](https://badge.fury.io/js/0db.svg)](https://npmjs.org/package/0db)
-[![Build Status](https://travis-ci.org/Ambratolm/0db.svg?branch=master)](https://travis-ci.org/Ambratolm/0db)
 
-Simple JSON file database.
+<!-- [![Build Status](https://travis-ci.org/Ambratolm/0db.svg?branch=master)](https://travis-ci.org/Ambratolm/0db) -->
 
-## Installation
+Simple JSON file based database with easy querying interface and common utilities.
 
-```sh
-$ npm i 0db
+> For whatever reason, If you don't want to use a real database, and instead simply use a file. but also want some query and utility functions of a database. this is **0db** 😁.
+
+👇 Glimpse example :
+
+```js
+db("users").create({ name: "kenza", email: "[e-mail]" });
+db("users").read({ name: "kenza" });
+db("users").update({ name: "kenza" }, { email: "[e-mail]" });
+db("users").delete({ name: "kenza" });
 ```
+**0db** is constituted of **four** (`create`, `read`, `update`, and `delete`) methods that represents the **CRUD** operations and **three** (or less) parameters (`item`, `query`, and `options`) considerably (more or less) recurring in the four methods.
 
-## Usage
+<!-- toc -->
 
+- [📥 Installation](#%F0%9F%93%A5-installation)
+- [🏁 Getting Started](#%F0%9F%8F%81-getting-started)
+- [🚩 Initialize](#%F0%9F%9A%A9-initialize)
+- [🔎 Query](#%F0%9F%94%8E-query)
+- [☑️ Options](#%E2%98%91%EF%B8%8F-options)
+- [💠 CREATE](#%F0%9F%92%A0-create)
+  * [☑️ CREATE Options](#%E2%98%91%EF%B8%8F-create-options)
+  * [🎯 CREATE Examples](#%F0%9F%8E%AF-create-examples)
+- [💠 READ](#%F0%9F%92%A0-read)
+  * [☑️ READ Options](#%E2%98%91%EF%B8%8F-read-options)
+  * [🎯 READ Examples](#%F0%9F%8E%AF-read-examples)
+- [💠 UPDATE](#%F0%9F%92%A0-update)
+  * [☑️ UPDATE Options](#%E2%98%91%EF%B8%8F-update-options)
+  * [🎯 UPDATE Examples](#%F0%9F%8E%AF-update-examples)
+- [💠 DELETE](#%F0%9F%92%A0-delete)
+  * [☑️ DELETE Options](#%E2%98%91%EF%B8%8F-delete-options)
+  * [🎯 DELETE Examples](#%F0%9F%8E%AF-delete-examples)
+- [↘️ Other](#%E2%86%98%EF%B8%8F-other)
+- [📃 License](#%F0%9F%93%83-license)
+
+<!-- tocstop -->
+
+## 📥 Installation
+
+```bash
+npm i 0db
+```
+
+## 🏁 Getting Started
+
+👇 Learn by a simple common example :
+
 ```js
-const db = require('0db');
-db();
+// Require library
+const $0db = require("0db");
+
+// Initialize database
+// 💡 By default, A "db.json" file will be created in root directory
+const db = await $0db();
+
+// Create a new item within a collection named "users"
+// 💡 If the collection doesn't exist it will be created automatically
+// 💡 With the utility option "encrypt", the "password" field
+//    will be saved as an encrypted hash string instead of the original
+const createdUser = await db("users").create(
+  {
+    name: "kenza",
+    email: "[e-mail]",
+    password: "secret123",
+  },
+  {
+    encrypt: "password",
+  }
+);
+
+// Read all items from "users" collection where "name" is "kenza"
+// 💡 The "omit" option hides the "password" and "email"
+//    fields in the returned results
+const users = await db("users").read(
+  { name: "kenza" },
+  {
+    omit: ["password", "email"],
+  }
+);
+
+// Update all "users" items where "name" is "kenza"
+// with new values for "email" and "password"
+const updatedUser = await db("users").update(
+  { name: "kenza" },
+  {
+    email: "[e-mail]",
+    password: "NEW_SECRET_123456789",
+  }
+);
+
+// Delete all "users" items where "email" is "[e-mail]"
+const deletedUser = await db("users").update({ email: "[e-mail]" });
 ```
 
-## License
+💡 A JSON file named `db.json` (by default) is created in the root directory. This is an example of its content :
 
-MIT © [Ambratolm](https://github.com/Ambratolm)
+```json
+{
+  "users": [
+    {
+      "name": "kenza",
+      "email": "[e-mail]",
+      "$id": "8c8f128e-4905-4e77-b664-e03f6de5e952",
+      "$createdAt": "2021-09-05T21:40:27Z"
+    },
+    {
+      "name": "ambratolm",
+      "email": "[e-mail]",
+      "$id": "5211133c-a183-4c99-90ab-f857adf5442a",
+      "$createdAt": "2002-11-01T22:12:55Z",
+      "$updatedAt": "2021-10-02T00:00:00Z"
+    }
+  ]
+}
+```
+
+💡 Note that the `$id` and `$createdAt` fields are created automatically when an item is created, and `$updatedAt` when it is updated.
+
+## 🚩 Initialize
+
+```js
+// Initialize with a "db.json" file in the root directory
+const db = await fsdb();
+
+// Initialize with a custom named JSON file in the root directory
+const db = await fsdb("my-database-file.json");
+
+// Initialize with a custom named JSON file in the current directory
+const db = await fsdb(__dirname + "/my-database-file");
+```
+
+## 🔎 Query
+
+Query parameter in `Read`, `Update`, and `Delete` methods is an object or function that allows targeting specific items in collection.
+
+- Query object :
+
+```
+{
+  fieldName: fieldValue,
+  fieldName: fieldValue,
+  ...etc
+}
+```
+
+Query object is an object of property values to match against collection items.<br />
+A comparison is performed between every item object property values in collection and the query object property values to determine if an item object contains equivalences.<br />
+The items containing the equivalences are returned.
+
+Example:
+```js
+const queryObj = {
+  firstName: "kenza",
+  age: 20,
+  rating: 5
+};
+
+const users = await db("users").read(queryObj);
+```
+
+- Query function :
+
+```
+(item, index?, collection?) => [Boolean]
+```
+
+Query function is a predicate called for every item when iterating over items of collection.<br />
+All items predicate returns truthy for are returned.<br />
+The predicate is invoked with three arguments :
+- `value` : **Required**. The value of the current item.
+- `index` : _Optional_. The index of the current item in collection.
+- `collection` : _Optional_. The collection array-object the current item belongs to.
+
+Example:
+
+```js
+const queryFn = (user) => {
+  return user.name.startsWith("k") && user.age >= 20 && rating >= 5;
+};
+
+const users = await db("users").read(queryFn);
+```
+
+## ☑️ Options
+
+```
+{
+  optionName: optionValue,
+  optionName: optionValue,
+  ...etc
+}
+```
+
+Options parameter in **all** methods is an object that allows to apply additional stuff to the method's subject item or to the method's returned items result.<br />
+Every method can have specific options or common options depending on the context of the method.
+
+Example :
+
+```js
+const options = {
+  unique: ["name", "email"],
+  encrypt: "password",
+  omit: ["email", "password"],
+  nocase: true
+};
+
+const user = {
+  name: "moulay-elhassan",
+  email: "[e-mail]",
+  password: "secret#hasson?1980"
+}
+
+const createdUser = await db("users").create(user, options);
+```
+
+## 💠 CREATE
+
+```js
+await db(collectionName).create(item?, options?);
+```
+
+Creates a new item in a collection.<br />
+💡 If the specified collection doesn't exist it will be created automatically.<br />
+💡 If no item object is specified (omitted, `null`, or `undefined`), an empty item is created with no fields except the system fields (with names starting with $ sign).<br />
+💡 The created item is returned.
+
+| Parameter      | Type   | Default | Description                             |
+| -------------- | ------ | ------- | --------------------------------------- |
+| collectionName | String |         | Targeted collection name                |
+| item           | Object | {}      | Item to create                          |
+| options        | Object | {}      | CREATE options                          |
+| **@returns**   | Object |         | The created item                        |
+| **@throws**    | Error  |         | If a unique field value is already used |
+| **@throws**    | Error  |         | If a value to encrypt is not a string   |
+
+### ☑️ CREATE Options
+
+| Property | Type               | Default | Description                      |
+| -------- | ------------------ | ------- | -------------------------------- |
+| unique   | String or String[] | ""      | Fields to declare as unique      |
+| encrypt  | String or String[] | ""      | Fields to encrypt                |
+| pick     | String or String[] | ""      | Fields to pick in returned items |
+| omit     | String or String[] | ""      | Fields to omit in returned items |
+| nocase   | Boolean            | false   | If true ignores case in search   |
+
+💡 When fields are declared as `unique`, a checking for duplicates is done before adding the item.
+
+💡 If `nocase` is true, letter case comparison will be ignored in search operations, like for example checking `unique` values.
+
+### 🎯 CREATE Examples
+
+```js
+// Create an item within a collection named "players" (automatically created)
+// The created item is returned
+const createdPlayer = await db("players").create({
+  name: "ambratolm",
+  level: 99,
+  inventory: ["sword", "shield", "potion"],
+});
+
+// Create an item within a collection named "players" with some options
+const createdPlayer = await db("players").create(
+  {
+    name: "ambratolm",
+    level: 99,
+    inventory: ["sword", "shield", "potion"],
+    password: "this_is_a_secret",
+  },
+  {
+    // Options
+    unique: "name", // Make "name" field unique
+    encrypt: "password", // Encrypt "password" field
+    omit: ["password", "level"], // Omit fields in the returned item object
+    nocase: true, // Ignore case when comparing strings
+  }
+);
+```
+
+## 💠 READ
+
+```js
+await db(collectionName).read(query?, options?);
+```
+
+Reads an existing item in a collection.<br />
+💡 If the specified collection doesn't exist it will be created automatically.<br />
+💡 If no query is specified (omitted, `null`, or `undefined`), the query defaults to empty query `{}` which returns all items.<br />
+💡 The read items are returned.
+
+| Parameter      | Type   | Default | Description                       |
+| -------------- | ------ | ------- | --------------------------------- |
+| collectionName | String |         | Targeted collection name          |
+| query          | Object | {}      | Query object or function          |
+| options        | Object | {}      | READ options                      |
+| **@returns**   | Array  |         | The read item                     |
+| **@throws**    | Error  |         | If an encrypted field not matched |
+
+### ☑️ READ Options
+
+| Property | Type               | Default | Description                        |
+| -------- | ------------------ | ------- | ---------------------------------- |
+| one      | Boolean            | false   | Return only one result (Object)    |
+| pick     | String or String[] | []      | Fields to pick in returned items   |
+| omit     | String or String[] | []      | Fields to omit in returned items   |
+| nocase   | Boolean            | false   | Ignore case in search              |
+| sort     | String or String[] | ""      | Fields to sort by returned items   |
+| order    | String or String[] | "asc"   | Order of sorting of returned items |
+| encrypt  | String or String[] | []      | Fields to encrypt                  |
+| limit    | Number             | MAX     | Number of returned items           |
+| page     | Number             | 0       | Index of pagination (with limit)   |
+| expand   | String             | ""      | Name of collection to expand to    |
+| embed    | String             | ""      | Name of collection to embed        |
+
+### 🎯 READ Examples
+
+```js
+// Read all items in "players" collection
+const players = await db("players").read();
+
+// Read items matching a query object
+const somePlayers = await db("players").read({ name: "ambratolm" });
+
+// Read items matching a query function
+const someOtherPlayers = await db("players").read(
+  (player) => player.level >= 90
+);
+
+// Read items matching a query with some options
+const player = await db("players").read(
+  { name: "AmBrAtOlM" },
+  {
+    // Options
+    nocase: true, // Ignore case when comparing strings
+    one: true, // return only one result (an object instead of array)
+  }
+);
+```
+
+## 💠 UPDATE
+
+```js
+await db(collectionName).update(query?, changes?, options?);
+```
+
+Updates an existing item in a collection.<br />
+💡 If the specified collection doesn't exist it will be created automatically.<br />
+💡 If no query is specified (omitted, `null`, or `undefined`), no item is updated.<br />
+💡 If an empty query `{}` is specified, all items are updated.
+💡 If no changes are specified (omitted, `null`, or `undefined`), the changes default to empty changes `{}` which only updates the `$updatedAt` field in targeted items.
+💡 The updated items are returned.
+
+| Parameter      | Type   | Default | Description                             |
+| -------------- | ------ | ------- | --------------------------------------- |
+| collectionName | String |         | Targeted collection                     |
+| query          | Object | {}      | Query object or function                |
+| changes        | Object | {}      | Changes to apply                        |
+| options        | Object | {}      | Additional options                      |
+| **@returns**   | Array  |         | The updated item                        |
+| **@throws**    | Error  |         | If Items matching query not found       |
+| **@throws**    | Error  |         | If a unique field value is already used |
+| **@throws**    | Error  |         | If a value to encrypt is not a string   |
+
+### ☑️ UPDATE Options
+
+| Property | Type               | Default | Description                       |
+| -------- | ------------------ | ------- | --------------------------------- |
+| total    | Boolean            | false   | If true overrides all item fields |
+| one      | Boolean            | false   | Return only one result (Object)   |
+| unique   | String or String[] | ""      | Fields to declare as unique       |
+| encrypt  | String or String[] | []      | Fields to encrypt                 |
+| pick     | String or String[] | []      | Fields to pick in returned items  |
+| omit     | String or String[] | []      | Fields to omit in returned items  |
+| nocase   | Boolean            | false   | Ignore case in search             |
+
+### 🎯 UPDATE Examples
+
+```js
+// Update item(s)
+// The updated item is returned
+const updatedPlayer = await db("players").update(
+  { name: "ambratolm" }, // Query can also be a function
+  { name: "new name", level: 0 } // Changes to apply
+);
+
+// Update item(s) with some options
+const updatedPlayer = await db("players").update(
+  { name: "ambratolm" }, // Query can also be a function
+  { name: "new name", level: 0 }, // Changes to apply
+  {
+    // Options
+  }
+);
+```
+
+## 💠 DELETE
+
+```js
+await db(collectionName).delete(query?, options?);
+```
+
+Deletes an existing item in a collection.<br />
+💡 If the specified collection doesn't exist it will be created automatically.<br />
+💡 If no query is specified (omitted, `null`, or `undefined`), no item is deleted.<br />
+💡 If an empty query `{}` is specified, all items are deleted.<br />
+💡 The deleted items are returned.
+
+| Parameter      | Type   | Default | Description                       |
+| -------------- | ------ | ------- | --------------------------------- |
+| collectionName | String |         | Targeted collection name          |
+| query          | Object | {}      | Query object or function          |
+| options        | Object | {}      | Additional options                |
+| **@returns**   | Object |         | The deleted item                  |
+| **@throws**    | Error  |         | If Items matching query not found |
+
+### ☑️ DELETE Options
+
+| Property | Type               | Default | Description                      |
+| -------- | ------------------ | ------- | -------------------------------- |
+| one      | Boolean            | false   | Return only one result (Object)  |
+| pick     | String or String[] | []      | Fields to pick in returned items |
+| omit     | String or String[] | []      | Fields to omit in returned items |
+| nocase   | Boolean            | false   | Ignore case in search            |
+
+### 🎯 DELETE Examples
+
+```js
+// Delete item(s)
+// The deleted item is returned
+const deletedPlayer = await db("players").delete(
+  { name: "ambratolm" } // Query can also be a function
+);
+
+// Delete item(s) with some options
+const deletedPlayer = await db("players").delete(
+  { name: "ambratolm" }, // Query can also be a function
+  {
+    // Options
+  }
+);
+```
+
+## ↘️ Other
+
+```js
+// Remove all collections
+await db.drop();
+
+// Remove a collection named "players"
+await db("players").drop();
+
+// Remove all items in a collection named "players" and keep it
+await db("players").clear();
+```
+
+## 📃 License
+
+[MIT](./LICENSE) © [Ambratolm](https://github.com/Ambratolm)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

No tests

Quality

Package does not have any tests. This is a strong signal of a poorly maintained or low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1166476

increased by54510.3%

Number of package files

25

increased by525%

Lines of code

8493

increased byInfinity%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

467

increased by1629.63%

Worsened metrics

Dependency count

5

increased byInfinity%

Number of low supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedbcryptjs@^2.4.3

• + Addedi@^0.3.7

• + Addedjsonwebtoken@^8.5.1

• + Addedlodash@^4.17.21

• + Addeduuid@^8.3.2

• + Addedbcryptjs@2.4.3(transitive)

• + Addedbuffer-equal-constant-time@1.0.1(transitive)

• + Addedecdsa-sig-formatter@1.0.11(transitive)

• + Addedi@0.3.7(transitive)

• + Addedjsonwebtoken@8.5.1(transitive)

• + Addedjwa@1.4.1(transitive)

• + Addedjws@3.2.2(transitive)

• + Addedlodash@4.17.21(transitive)

• + Addedlodash.includes@4.3.0(transitive)

• + Addedlodash.isboolean@3.0.3(transitive)

• + Addedlodash.isinteger@4.0.4(transitive)

• + Addedlodash.isnumber@3.0.3(transitive)

• + Addedlodash.isplainobject@4.0.6(transitive)

• + Addedlodash.isstring@4.0.1(transitive)

• + Addedlodash.once@4.1.1(transitive)

• + Addedms@2.1.3(transitive)

• + Addedsafe-buffer@5.2.1(transitive)

• + Addedsemver@5.7.2(transitive)

• + Addeduuid@8.3.2(transitive)