geoserver-node-client 0.0.6 → 1.1.0

package/README.md

@@ -5,21 +5,62 @@
 
 Node.js / JavaScript Client for the [GeoServer REST API](https://docs.geoserver.org/stable/en/user/rest/).
 
-**CAUTION: This is highly bleeding edge, heavily under development and therefore breaking changes can be made at every time!**
-
 ### API-Docs ###
 
-Detailed API-Docs can be found [here](https://meggsimum.github.io/geoserver-node-client/index.html).
+Detailed [API-Docs](https://meggsimum.github.io/geoserver-node-client/) are automatically created with JSDoc.
 
 ### Meta information
 
 Compatible with [GeoServer](https://geoserver.org)
 
+  - v2.21.x
   - v2.20.x
-  - v2.19.x
+  - v2.19.x (no more maintained and officially deprecated)
   - v2.18.x (no more maintained and officially deprecated)
   - v2.17.x (no more maintained and officially deprecated)
 
+
+### Usage
+
+```shell
+npm i geoserver-node-client
+```
+
+usage with require (ES5):
+```js
+const grcImport = require('geoserver-node-client');
+const GeoServerRestClient = grcImport.GeoServerRestClient;
+
+const url = 'http://localhost:8080/geoserver/rest/';
+const user = 'admin';
+const pw = 'geoserver';
+const grc = new GeoServerRestClient(url, user, pw);
+
+async function main () {
+    const result =  await grc.about.exists();
+    console.log(result);
+};
+
+main();
+```
+
+usage as ES module (ES6)
+```js
+import {GeoServerRestClient} from 'geoserver-node-client';
+
+const url = 'http://localhost:8080/geoserver/rest/';
+const user = 'admin';
+const pw = 'geoserver';
+const grc = new GeoServerRestClient(url, user, pw);
+
+async function main () {
+    const result =  await grc.about.exists();
+    console.log(result);
+};
+
+main();
+```
+
 ### Setup
 
 Run as local checkout (mainly for development purposes)
@@ -34,6 +75,28 @@ npm install
 npm run demo
 ```
 
+### Error Handling
+
+A request either succeeds or throws the custom `GeoServerResponseError`. It has the standard `message` property with a "human-readable" text. Additionally the error has the property `geoServerOutput` which contains the direct response from GeoServer. This output is not guaranteed to exist and can either be a simple text or a complete HTML document. The latter is difficult to read, but might still be helpful for debugging. This example shows how these error properties can be used. It also shows how to filter by error type:
+
+```javascript
+  try {
+      // call any function from this library
+      await grc.styles.publish(workspace, styleName, sldBody)
+    } catch (error) {
+      // the standard error message
+      console.error(error.message);
+
+      // the whole error including stack trace and (if available) the property 'geoServerOutput'
+      console.error(error);
+
+      if (error instanceof GeoServerResponseError) {
+        // a GeoServer specific error happened
+      } else {
+        // another error happened
+      }
+    }
+```
 
 ### Unit Tests
 
@@ -43,19 +106,23 @@ First start a GeoServer, e.g. by using this Docker container:
 docker run \
   -p 8080:8080 \
   -v /path/to/geoserver_mnt:/opt/geoserver_data \
-  meggsimum/geoserver:2.20.1
+  meggsimum/geoserver:2.20.4
 ```
 
 Then, in an other terminal, run:
 
 ```shell
 # specify the GeoServer version and run the test suite
-GEOSERVER_VERSION=2.20.1 npm run test
+GEOSERVER_VERSION=2.20.4 npm run test
 ```
 
 ### Release
 
-The release to GitHub and npm is done via [release-it](https://github.com/release-it/release-it). This is the workflow for releasing:
+Setting a git tag and increasing the version in the `package.json` as well as releasing to npm is done via [release-it](https://github.com/release-it/release-it).
+
+The GitHub release has to be performed manually based on the tag created by `release-it`.
+
+This is the workflow for releasing:
 
 1. Make sure a `GITHUB_TOKEN` is available as environment variable. See [here](https://github.com/release-it/release-it/blob/master/docs/github-releases.md) for more information.
 
@@ -77,6 +144,9 @@ npm run release
 ```
 
 4. Follow the questions in the commandline.
+  - automatically upgrades the version in `package.json`
+  - makes a release commit and pushes it to GitHub
+  - publishes the new version to npm
 
 ### Who do I talk to? ###
 
@@ -84,8 +154,9 @@ npm run release
 
 ### Credits
 
-This project was initiated by [meggsimum](https://meggsimum.de) within the [mFund](https://www.bmvi.de/EN/Topics/Digital-Matters/mFund/mFund.html) research project [SAUBER](https://sauber-projekt.de/).
+This project was initiated by [meggsimum](https://meggsimum.de) within the [mFund](https://www.bmvi.de/EN/Topics/Digital-Matters/mFund/mFund.html) research project [SAUBER](https://sauber-projekt.de/) and is further developed in the mFund research project [KLIPS](http://www.klips-projekt.de/):
 <p><img src="https://sauber-projekt.de/wp-content/uploads/2018/12/SAG_SAUBER_Logo_Dez3_transparent-1-e1543843688935.png" alt="SAUBER Logo" width="200"/></p>.
+<p><img src="http://www.klips-projekt.de/wp-content/uploads/2021/02/SAG_KLIPS-Logo_Jan21.png" alt="KLIPS Logo" width="200"/></p>.
 
 <img src="https://sauber-projekt.de/wp-content/uploads/2018/12/mfund-logo-download-e1547545420815-300x77.jpg" alt="mFund Logo" width="300"/>
 <img src="https://sauber-projekt.de/wp-content/uploads/2019/06/BMVI_Fz_2017_Office_Farbe_de_Bundestag-400x402.png" alt="BMVI Logo" height="200"/>

package/dist/geoserver-rest-client.js

@@ -0,0 +1,87 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "GeoServerResponseError", {
+  enumerable: true,
+  get: function get() {
+    return _geoserver.GeoServerResponseError;
+  }
+});
+exports.GeoServerRestClient = void 0;
+
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+
+var _layer = _interopRequireDefault(require("./src/layer.js"));
+
+var _style = _interopRequireDefault(require("./src/style.js"));
+
+var _workspace = _interopRequireDefault(require("./src/workspace.js"));
+
+var _datastore = _interopRequireDefault(require("./src/datastore.js"));
+
+var _imagemosaic = _interopRequireDefault(require("./src/imagemosaic.js"));
+
+var _security = _interopRequireDefault(require("./src/security.js"));
+
+var _settings = _interopRequireDefault(require("./src/settings.js"));
+
+var _namespace = _interopRequireDefault(require("./src/namespace.js"));
+
+var _about = _interopRequireDefault(require("./src/about.js"));
+
+var _geoserver = require("./src/util/geoserver.js");
+
+/**
+ * Client for GeoServer REST API.
+ * Has minimal basic functionality and offers REST client instances for
+ * sub-entities, like workspaces or datastores as member variables.
+ *
+ * @module GeoServerRestClient
+ */
+var GeoServerRestClient = /*#__PURE__*/(0, _createClass2["default"])(
+/**
+ * Creates a GeoServerRestClient instance.
+ *
+ * @param {String} url The URL of the GeoServer REST API endpoint
+ * @param {String} user The user for the GeoServer REST API
+ * @param {String} password The password for the GeoServer REST API
+ */
+function GeoServerRestClient(url, user, password) {
+  (0, _classCallCheck2["default"])(this, GeoServerRestClient);
+  this.url = url.endsWith('/') ? url : url + '/';
+  this.auth = 'Basic ' + Buffer.from(user + ':' + password).toString('base64');
+  /** @member {LayerClient} layers GeoServer REST client instance for layers */
+
+  this.layers = new _layer["default"](this.url, this.auth);
+  /** @member {StyleClient} styles GeoServer REST client instance for styles */
+
+  this.styles = new _style["default"](this.url, this.auth);
+  /** @member {WorkspaceClient} workspaces GeoServer REST client instance for workspaces */
+
+  this.workspaces = new _workspace["default"](this.url, this.auth);
+  /** @member {NamespaceClient} namespaces GeoServer REST client instance for namespaces */
+
+  this.namespaces = new _namespace["default"](this.url, this.auth);
+  /** @member {DatastoreClient} datastores GeoServer REST client instance for data stores */
+
+  this.datastores = new _datastore["default"](this.url, this.auth);
+  /** @member {ImageMosaicClient} imagemosaics GeoServer REST client instance for image mosaics */
+
+  this.imagemosaics = new _imagemosaic["default"](this.url, this.auth);
+  /** @member {SecurityClient} security GeoServer REST client instance for security related modifications */
+
+  this.security = new _security["default"](this.url, this.auth);
+  /** @member {SettingsClient} settings GeoServer REST client instance for settings */
+
+  this.settings = new _settings["default"](this.url, this.auth);
+  /** @member {AboutClient} about GeoServer REST client instance for about endpoint */
+
+  this.about = new _about["default"](this.url, this.auth);
+});
+exports.GeoServerRestClient = GeoServerRestClient;

package/dist/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "geoserver-node-client",
+  "version": "1.1.0",
+  "description": "Node.js client for GeoServer REST API",
+  "type": "commonjs",
+  "main": "geoserver-rest-client.js",
+  "scripts": {
+    "demo": "node demo/index.js",
+    "docs": "./node_modules/.bin/jsdoc geoserver-rest-client.js src/*.js DOCS_HOME.md",
+    "lint": "eslint src/**/*.js test/**/*.js scripts/**/*.js geoserver-rest-client.js",
+    "lint-fix": "eslint --fix  src/**/*.js test/**/*.js scripts/**/*.js geoserver-rest-client.js",
+    "pretest": "npm run lint",
+    "test": "mocha --timeout 10000",
+    "release": "release-it",
+    "build": "npm run build:clean && npm run build:babel && npm run build:fixup",
+    "build:clean": "rm -rf dist",
+    "build:babel": "babel geoserver-rest-client.js -d dist && babel src -d dist/src",
+    "build:fixup": "node scripts/create-custom-package-json.js"
+  },
+  "exports": {
+    "import": "./geoserver-rest-client.js",
+    "require": "./dist/geoserver-rest-client.js"
+  },
+  "files": [
+    "geoserver-rest-client.js",
+    "src",
+    "dist"
+  ],
+  "keywords": [
+    "GeoServer",
+    "REST",
+    "Client"
+  ],
+  "author": "C. Mayer, meggsimum (info_at*meggsimum?dot?de)",
+  "license": "BSD-2-Clause",
+  "dependencies": {
+    "@babel/runtime": "^7.18.3",
+    "node-fetch": "^2.6.5"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.17.10",
+    "@babel/core": "^7.17.12",
+    "@babel/plugin-transform-runtime": "^7.18.0",
+    "@babel/preset-env": "^7.17.12",
+    "chai": "^4.3.4",
+    "eslint": "^7.32.0",
+    "eslint-config-standard": "^14.1.1",
+    "eslint-plugin-import": "^2.25.2",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^4.3.1",
+    "eslint-plugin-standard": "^4.1.0",
+    "jsdoc": "^3.6.10",
+    "mocha": "^9.1.3",
+    "release-it": "^14.14.3"
+  }
+}

package/dist/src/about.js

@@ -0,0 +1,145 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+
+var _nodeFetch = _interopRequireDefault(require("node-fetch"));
+
+var _geoserver = require("./util/geoserver.js");
+
+/**
+ * Client for GeoServer "about" endpoint
+ *
+ * @module AboutClient
+ */
+var AboutClient = /*#__PURE__*/function () {
+  /**
+   * Creates a GeoServer REST AboutClient instance.
+   *
+   * @param {String} url The URL of the GeoServer REST API endpoint
+   * @param {String} auth The Basic Authentication string
+   */
+  function AboutClient(url, auth) {
+    (0, _classCallCheck2["default"])(this, AboutClient);
+    this.url = url;
+    this.auth = auth;
+  }
+  /**
+   * Get the GeoServer version.
+   *
+   * @throws Error if request fails
+   *
+   * @returns {Object} The version of GeoServer
+   */
+
+
+  (0, _createClass2["default"])(AboutClient, [{
+    key: "getVersion",
+    value: function () {
+      var _getVersion = (0, _asyncToGenerator2["default"])( /*#__PURE__*/_regenerator["default"].mark(function _callee() {
+        var url, response, geoServerResponse;
+        return _regenerator["default"].wrap(function _callee$(_context) {
+          while (1) {
+            switch (_context.prev = _context.next) {
+              case 0:
+                url = this.url + 'about/version.json';
+                _context.next = 3;
+                return (0, _nodeFetch["default"])(url, {
+                  credentials: 'include',
+                  method: 'GET',
+                  headers: {
+                    Authorization: this.auth
+                  }
+                });
+
+              case 3:
+                response = _context.sent;
+
+                if (response.ok) {
+                  _context.next = 9;
+                  break;
+                }
+
+                _context.next = 7;
+                return (0, _geoserver.getGeoServerResponseText)(response);
+
+              case 7:
+                geoServerResponse = _context.sent;
+                throw new _geoserver.GeoServerResponseError(null, geoServerResponse);
+
+              case 9:
+                return _context.abrupt("return", response.json());
+
+              case 10:
+              case "end":
+                return _context.stop();
+            }
+          }
+        }, _callee, this);
+      }));
+
+      function getVersion() {
+        return _getVersion.apply(this, arguments);
+      }
+
+      return getVersion;
+    }()
+    /**
+     * Checks if the configured GeoServer REST connection exists.
+     *
+     * @returns {Boolean} If the connection exists
+     */
+
+  }, {
+    key: "exists",
+    value: function () {
+      var _exists = (0, _asyncToGenerator2["default"])( /*#__PURE__*/_regenerator["default"].mark(function _callee2() {
+        var versionInfo;
+        return _regenerator["default"].wrap(function _callee2$(_context2) {
+          while (1) {
+            switch (_context2.prev = _context2.next) {
+              case 0:
+                _context2.prev = 0;
+                _context2.next = 3;
+                return this.getVersion();
+
+              case 3:
+                versionInfo = _context2.sent;
+                return _context2.abrupt("return", !!versionInfo);
+
+              case 7:
+                _context2.prev = 7;
+                _context2.t0 = _context2["catch"](0);
+                return _context2.abrupt("return", false);
+
+              case 10:
+              case "end":
+                return _context2.stop();
+            }
+          }
+        }, _callee2, this, [[0, 7]]);
+      }));
+
+      function exists() {
+        return _exists.apply(this, arguments);
+      }
+
+      return exists;
+    }()
+  }]);
+  return AboutClient;
+}();
+
+exports["default"] = AboutClient;