Code cleanup, expand README, fix some minor bugs

.gitignore

@@ -1,11 +1,9 @@
-php/tokens.php
-php/config.php
 files/*
 node_modules
 *.log
 .vscode/
 
-# NPM RC WITH SENSIBLE INFOS
+# NPM RC WITH SENSITIVE INFO
 \.npmrc
 
 ### Node ###
@@ -129,5 +127,5 @@ dist
 .pnp.*
 
 #jsdoc
-docs/
-.DS_Store
+docs/
+.DS_Store

CHANGELOG.md

@@ -5,7 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.12.0]
+## Unreleased
+
+### Added
+
+- Exposed `Collection.collectionName` as a readonly property for TypeScript usage.
+- TypeScript overview to the README.
+- Optional replacement argument for `array-splice` edit fields.
+- `array-contains-none` option for array fields.
+- Optional constructor for the `JSONDatabase` PHP class to reduce repetitive code.
+- "Advanced" section to the README for previously undocumented features.
+- `original` option for `readRaw` to not insert ID fields, for easier non-relational collection usage.
+
+### Changed
+
+- Rejected incorrect parameters are now `TypeError`s instead of regular `Error`s.
+- Deprecated `firestorm.table(name)` method, since `firestorm.collection(name)` does exactly the same thing.
+- Reformatted the repository and improved README.md to make it easier to set up Firestorm.
+- Clean up and standardize JSDoc comments.
+- `editField` and `editFieldBulk` now return confirmations like all other write methods.
+- `editField` and `editFieldBulk` now reject with a descriptive error message on failure rather than silently failing.
+
+### Fixed
+
+- PHP-level errors not being rejected properly in GET requests.
+- Certain write commands mutating data internally and affecting parameters outside Firestorm.
+- `Collection.searchKeys` and `Collection.values` not returning proper `Error` objects sometimes.
+- `files.upload` not allowing the `form-data` package's typing of `FormData` in TypeScript.
+- Inconsistent use of indentation and formatting in PHP files.
+- Various typos in PHP files.
+- `Collection` class being exported in TypeScript despite the actual class being private.
+- `array-splice` edit fields being incorrectly typed as `array-slice`.
+- Platform-specific PHP error when searching nested keys.
+- `Collection.remove` rejecting numeric keys, despite `Collection.removeBulk` not doing so.
+- `editField` and `editFieldBulk` validation issues.
+
+## [1.12.0] - 2024-02-22
 
 ### Added
 
@@ -14,7 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Refactored JavaScript part to be less verbose and reuse existing code better.
-- Use JSDoc `{@link }` properties.
+- Added JSDoc `{@link }` properties.
 - Cleaned up and clarified README.md.
 - Renamed `AllCriteria` to `AnyCriteria` to be more accurate.
 - Replaced broken `NoMethods<T>` type with a more generalized `RemoveMethods<T>` type.
@@ -76,4 +111,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
-- crypto module as it is now deprecated and a built-in node package
+- `crypto` module as it is now deprecated and a built-in node package

jsdoc.json

@@ -26,7 +26,7 @@
         "keyword": "firebase,firestore,db,api,php,micro-operations,bulk"
     },
     "menu": {
-      "Github repo": {
+      "Repository": {
         "href": "https://github.com/TheRolfFR/firestorm",
         "target": "_blank",
         "class": "menu-item",

package.json

@@ -11,7 +11,7 @@
     "full": "npm run php_stop ; npm run php_start && npm run test ; npm run php_stop",
     "local_tests": "sudo act -P ubuntu-latest=shivammathur/node:latest -j js-wrapper-test",
     "jsdoc": "jsdoc src/index.js -c jsdoc.json -R README.md -t ./node_modules/docdash -d out",
-    "nodemon_jsdoc": "nodemon -x npm run jsdoc --watch src/index.js --watch jsdoc.json",
+    "nodemon_jsdoc": "nodemon -x npm run jsdoc --watch src/index.js --watch jsdoc.json --watch README.md",
     "types": "npx tsc",
     "prettier": "prettier \"{,!(node_modules)/**/}*.{js,ts}\" --config .prettierrc --write",
     "cov": "npm run php_stop ; npm run php_start && nyc --reporter=text mocha tests/**/*.spec.js; npm run php_stop"
@@ -39,19 +39,19 @@
     "typings/index.d.ts"
   ],
   "dependencies": {
-    "axios": "^1.6.7"
+    "axios": "^1.6.8",
+    "form-data": "^4.0.0"
   },
   "devDependencies": {
     "chai": "^4.4.1",
     "docdash": "^2.0.2",
-    "form-data": "^4.0.0",
-    "glob": "^10.3.10",
+    "glob": "^10.3.12",
     "jsdoc": "^4.0.2",
     "jsdoc-to-markdown": "^8.0.1",
-    "mocha": "^10.3.0",
+    "mocha": "^10.4.0",
     "nyc": "^15.1.0",
     "prettier": "^3.2.5",
     "recursive-copy": "^2.0.14",
-    "typescript": "^5.3.3"
+    "typescript": "^5.4.5"
   }
 }

php/classes/FileAccess.php

@@ -0,0 +1,61 @@
+<?php
+
+class FileAccess {
+    public static function read($filepath, $waitLock = false, $default = null) {
+        $fileObj = array('filepath' => $filepath, 'content' => '');
+        // open file as binary
+        $file = fopen($filepath, 'rb');
+
+        // exit if couldn't find file
+        if ($file === false) {
+            if ($default == null)
+                throw new Exception("Could not open file: $filepath");
+
+            // set default value
+            $fileObj['content'] = $default;
+        }
+
+        // if no file, puts default value inside
+        if ($file === false) {
+            file_put_contents($fileObj['filepath'], $fileObj['content'], LOCK_EX);
+            $file = fopen($filepath, 'rb');
+        }
+
+        $fileObj['fd'] = $file;
+
+        // if want the lock, we wait for the shared lock
+        if ($waitLock) {
+            $lock = flock($file, LOCK_SH);
+            if (!$lock) {
+                fclose($file);
+                throw new Exception('Failed to lock file');
+            }
+        }
+
+        // read file content
+        $string = '';
+        while (!feof($file)) {
+            $string .= fread($file, 8192);
+        }
+
+        $fileObj['content'] = $string;
+
+        // if no wait you can close the file
+        if (!$waitLock)
+            fclose($file);
+
+        return $fileObj;
+    }
+    public static function write($fileObj) {
+        // lock and close
+        flock($fileObj['fd'], LOCK_UN);
+        fclose($fileObj['fd']);
+
+        if (!is_writable($fileObj['filepath'])) {
+            throw new HTTPException("PHP script can't write to file. Check permission, group and owner.", 400);
+        }
+
+        $ret = file_put_contents($fileObj['filepath'], $fileObj['content'], LOCK_EX);
+        return $ret;
+    }
+}

php/classes/HTTPException.php

@@ -0,0 +1,23 @@
+<?php
+
+class HTTPException extends Exception {
+    // custom message
+    public function __construct($message, $code = 400, Throwable $previous = null) {
+        $type_message = gettype($message);
+
+        if ($type_message != 'string')
+            throw new Exception("Incorrect message type for HTTPException constructor, expected string, got $type_message");
+
+        $type_code = gettype($code);
+        if ($type_code != 'integer')
+            throw new Exception("Incorrect code type for HTTPException constructor, expected string, got $type_code");
+
+        // assign everything
+        parent::__construct($message, $code, $previous);
+    }
+
+    // prettier representation
+    public function __toString(): string {
+        return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
+    }
+}