firestorm-db - npm Package Compare versions

Comparing version 1.9.0 to 1.10.0

index.js

@@ -28,3 +28,14 @@ try {
 
+/**
+ * @import {AxiosPromise} from 'axios'
+ */
+
+/**
+ * @ignore
+ */
 let _address = undefined
+
+/**
+ * @ignore
+ */
 let _token = undefined
@@ -46,2 +57,8 @@
 }
+const fileAddress = () => {
+  if(!_address)
+    throw new Error('Firestorm address was not configured')
+  
+  return _address + 'files.php'
+}
 
@@ -56,2 +73,19 @@ const writeToken = () => {
 /**
+ * Auto-extracts data from Axios request
+ * @ignore
+ * @param {Promise<T>} request The Axios concerned request
+ */
+const __extract_data = (request) => {
+  return new Promise((resolve, reject) => {
+    request.then(res => {
+      if ('data' in res) return resolve(res.data)
+      resolve(res)
+    })
+    .catch(err => {
+     reject(err)
+    })
+  })
+}
+
+/**
  * Class representing a collection
@@ -70,2 +104,9 @@ * @template T
 
+  /**
+   * Add user methods to the returned data
+   * @private
+   * @ignore
+   * @param {AxiosPromise} req Incoming request 
+   * @returns {Object|Object[]}
+   */
   __add_methods(req) {
@@ -90,18 +131,16 @@ return new Promise((resolve, reject) => {
    * Auto-extracts data from Axios request
-   * @param {Promise<T>} request The Axios concerned request
+   * @private
+   * @ignore
+   * @param {AxiosPromise} request The Axios concerned request
    */
   __extract_data(request) {
-    return new Promise((resolve, reject) => {
-      request.then(res => {
-        if ('data' in res) return resolve(res.data)
-        return resolve(res)
-      })
-      .catch(err => reject(err))
-    })
+    return __extract_data(request)
   }
 
   /**
-   * Send get request and extract data from ir
+   * Send get request and extract data from response
+   * @private
+   * @ignore
    * @param {Object} data Body data
-   * @returns {Promise<Any>} data out
+   * @returns {Promise<Object|Object[]>} data out
    */
@@ -316,3 +355,5 @@ __get_request(data) {
   /**
-   * 
+   * creates write requests with given value
+   * @private
+   * @ignore
    * @param {String} command The write command you want
@@ -458,2 +499,5 @@ * @param {Object?} value The value for this command
 
+/**
+ * @namespace firestorm
+ */
 const firestorm = {
@@ -493,3 +537,56 @@ /**
 
-  ID_FIELD: ID_FIELD_NAME
+  /**
+   * Value for the id field when researching content
+   */
+  ID_FIELD: ID_FIELD_NAME,
+
+  /**
+   * Test child object with child namespace
+   * @memberof firestorm
+   * @type {object}
+   */
+  files: {
+    /**
+     * gets file back
+     * @memberof firestorm.files
+     * @param {String} path File path wanted
+     */
+    get: function (path) {
+      return __extract_data(axios.get(fileAddress(), {
+        params: {
+          path: path
+        }
+      }))
+    },
+  
+    /**
+     * Uploads file
+     * @memberof firestorm.files
+     * @param {FormData} form formdata with path, filename and file
+     * @returns {Promise} http response
+     */
+    upload: function(form) {
+      form.append('token', firestorm.token())
+      return axios.post(fileAddress(), form, {
+        headers: {
+          ...form.getHeaders()
+        }
+      })
+    },
+  
+    /**
+     * Deletes a file given its path
+     * @memberof firestorm.files
+     * @param {String} path File path to delete
+     * @returns {Promise} http response
+     */
+    delete: function(path) {
+      return axios.delete(fileAddress(), {
+        data: {
+          path: path,
+          token: firestorm.token()
+        }
+      })
+    }
+  }
 }
@@ -496,0 +593,0 @@

package.json

 {
   "name": "firestorm-db",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Self hosted Firestore-like database with API endpoints based on micro bulk operations",
@@ -11,7 +11,9 @@ "main": "index.js",
     "full": "npm run php_start && npm run test ; npm run php_stop",
-    "local_tests": "sudo act -P ubuntu-latest=shivammathur/node:latest"
+    "local_tests": "sudo act -P ubuntu-latest=shivammathur/node:latest",
+    "jsdoc": "jsdoc -a all -c jsdoc.json -R README.md index.js -d docs/jsdoc",
+    "nodemon_jsdoc": "nodemon -x npm run jsdoc --watch index.js --watch jsdoc.json"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://[e-mail]/TheRolfFR/firestorm.git"
+    "url": "https://github.com/TheRolfFR/firestorm-db"
   },
@@ -23,3 +25,4 @@ "keywords": [
     "api",
-    "micro-operations"
+    "micro-operations",
+    "bulk"
   ],
@@ -40,6 +43,10 @@ "author": "TheRolf",
     "chai": "^4.3.4",
+    "form-data": "^4.0.0",
     "crypto": "^1.0.1",
+    "docdash": "^1.2.0",
     "fs": "0.0.1-security",
     "fs-extra": "^10.0.0",
     "glob": "^7.1.7",
+    "jsdoc": "^3.6.7",
+    "jsdoc-to-markdown": "^7.1.0",
     "mocha": "^9.1.3",
@@ -46,0 +53,0 @@ "path": "^0.12.7",

README.md

@@ -6,3 +6,3 @@ <div align="center">
 
-<a href="https://www.npmjs.com/package/firestorm-db" targtet="_blank" ><img alt="npm" src="https://img.shields.io/npm/v/firestorm-db?color=cb0000&logo=npm&style=flat-square"> <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/min/firestorm-db?label=NPM%20minified%20size&style=flat-square"> </a> <img alt="GitHub file size in bytes" src="https://img.shields.io/github/size/TheRolfFR/firestorm-db/index.js?color=43A047&label=Script%20size&logoColor=green&style=flat-square"><a href="https://github.com/TheRolfFR/firestorm-db/actions/workflows/testjs.yml"><img src="https://github.com/TheRolfFR/firestorm-db/actions/workflows/testjs.yml/badge.svg" alt="Tests" /></a>
+<a href="https://www.npmjs.com/package/firestorm-db" targtet="_blank" ><img alt="npm" src="https://img.shields.io/npm/v/firestorm-db?color=cb0000&logo=npm&style=flat-square"> <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/min/firestorm-db?label=NPM%20minified%20size&style=flat-square"> </a> <img alt="GitHub file size in bytes" src="https://img.shields.io/github/size/TheRolfFR/firestorm-db/index.js?color=43A047&label=Script%20size&logoColor=green&style=flat-square"><a href="https://github.com/TheRolfFR/firestorm-db/actions/workflows/testjs.yml"> <img src="https://github.com/TheRolfFR/firestorm-db/actions/workflows/testjs.yml/badge.svg" alt="Tests" /></a>
 
@@ -187,2 +187,85 @@ </div>
 
+## Files feature
+
+Files API function are detailed in the ``files.php`` PHP script. If you do not want to include this functionnality, then just delete this file.
+
+In you have to add 2 new configuration variables to your ``config.php`` file: 
+```php
+// whitelist of correct extensions
+$authorized_file_extension = array('.txt', '.png');
+
+// subfolder of uploads location, must start with dirname($_SERVER['SCRIPT_FILENAME'])
+// to force a subfolder of firestorm installation
+$STORAGE_LOCATION = dirname($_SERVER['SCRIPT_FILENAME']) . '/uploads/';
+```
+
+You can now use the wrapper functions in order to upload, get and delete a file.
+If the folder is accessible from server url, you can directly type its address.
+
+### Upload a file
+
+In order to upload a file, you have to give the function a FormData object. This class is generated from forms and is [native in modern browsers](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) but in node.js can be imported with [form-data package](https://www.npmjs.com/package/form-data).
+
+File content can be a [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) or an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).
+
+You have an overwrite option in order to avoid big mistakes or allow user with unique file names.
+
+```js
+const firestorm = require('firestorm-db')
+firestorm.address('ADRESS_VALUE')
+firestorm.token('TOKEN_VALUE')
+
+const form = new FormData()
+form.append('path', '/quote.txt')
+form.append('file', 'but your kids are gonna love it.', 'quote.txt')
+form.append('overwrite', false) // override optional argument (defaults to false)
+const uploadPromise = firestorm.files.upload(form)
+
+uploadPromise.then(() => {
+  console.log('Upload successful')
+})
+.catch(err => {
+  consoler.error(err)
+})
+```
+
+## Get a file
+
+You can get a file via its direct file URL location or its content with a request
+
+```js
+const firestorm = require('firestorm-db')
+firestorm.address('ADRESS_VALUE')
+
+const getPromise = firestorm.files.get('/quote.txt')
+
+getPromise.then(filecontent => {
+  console.log(filecontent) // 'but your kids are gonna love it.
+})
+.catch(err => {
+  console.error(err)
+})
+```
+
+## Delete a file
+
+Because I am a nice guy, I thought about deletion too. So I figured I would put a method to delete the files too.
+
+```js
+const firestorm = require('firestorm-db')
+firestorm.address('ADRESS_VALUE')
+firestorm.token('TOKEN_VALUE')
+
+const deletePromise = firestorm.files.delete('/quote.txt")
+
+deletePromise.then(() => {
+  console.log('File successfully deleted')
+})
+.catch(err => {
+  console.error(err)
+})
+
+```
+
+
 ## Memory warning
@@ -189,0 +272,0 @@

No alert changes

Improved metrics

Total package byte prevSize

31965

increased by19.06%

Lines of code

522

increased by20.83%

Number of lines in readme file

293

increased by39.52%

Worsened metrics

Dev dependency count

12

increased by50%

No dependency changes