hmpo-model 6.0.1 → 6.0.2

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contribution guidelines
+
+This is currently maintained by HMPO DCS (Digital Customer Services).
+
+## Contributing
+
+If you’ve got an idea or suggestion you can:
+
+* [Create a GitHub issue](https://github.com/HMPO/hmpo-model/issues)
+* [Open a Pull Request](https://github.com/HMPO/hmpo-model/pulls) to implement or fix a new or existing issue.
+
+## Raising bugs
+
+When reporting an issue, please include as much detail as possible to help us recreate, discuss, and resolve the problem. Here are some guidelines to follow:
+
+1. **Describe the Issue**: Provide a clear and concise description of the issue. Include any error messages, unexpected behavior, and steps to reproduce the problem.
+
+2. **Environment Details**: Specify the environment in which the issue occurred. This includes:
+
+   * Operating System (e.g., Windows 10, macOS Big Sur, Ubuntu 20.04)
+   * Browser and version (if applicable)
+   * Node.js version (if applicable)
+   * Any other relevant software versions
+
+3. **Minimal Reproducer**: To help us understand and fix the issue faster, please create a minimal reproducer repository. This should be a small, self-contained example that demonstrates the problem. Include:
+
+    * A link to the minimal reproducer repository
+    * Detailed reproduction instructions
+    * Any notes on the environment setup
+
+4. **Additional Context**: If there are any other details that might help us understand the issue better, please include them. This could be related issues, screenshots, or logs.
+
+When describing the bug it's also useful to follow the format:
+
+* what you did
+* what you expected to happen
+* what happened
+
+## Suggesting features
+
+Please raise feature requests as issues before contributing any code.
+
+This ensures they are discussed properly before any time is spent on them.
+
+## Contributing code
+
+### Indentation and whitespace
+
+Your JavaScript code should pass linting checks.
+
+We use ESLint with its rules defined by [eslint.config.js](eslint.config.js)
+Some useful docs on ESLint can be found here:
+* [ESLint - Getting Started](https://eslint.org/docs/latest/use/getting-started)
+* [ESLint - CLI Options](https://eslint.org/docs/latest/use/command-line-interface)
+* [ESLint for VS Code](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint#:~:text=If%20you%20haven't%20installed,create%20an%20.eslintrc%20configuration%20file.)
+
+We ask that you maintain 4-space, soft-tabs only indentation.
+
+### Testing
+
+Please ensure unit tests are added or updated as appropriate for your changes.
+
+### Commit hygiene
+
+To keep our commit history clean and easy to follow, we kindly ask that you squash your commits before merging your branch into the main branch. This helps to consolidate changes and makes the history more readable.

package/README.md

@@ -1,42 +1,64 @@
 # hmpo-model
+
 * localModel - Simple model for data persistance
 * remoteModel - Simple model for interacting with http/rest apis.
 
 ## Upgrading
 
 The deprecated `request` library has been replaced with `got`. The API is very similar, and some args are translated, like auth, and proxy.
-The new `got` library doesn't automativally use the proxy environment variables so you would need to use something like `global-agent` in your
+The new `got` library doesn't automatically use the proxy environment variables so you would need to use something like `global-agent` in your
 app if you need to specify proxies by environment arguments.
 
 The `request` method no longer takes a body. This should be inserted as `json`, `body`, or `form` into the `requestConfig` method.
 
 ## Local Model Usage
-### `get(name)`
-* gets a model property via a key
 
-### `set(name, value)` or `set({ name: value })`
-* sets a property on the model to a value and dispatches events
+### `constructor(attributes?, options?)`
+
+* Local Model extends the Node.JS EventEmitter. The constructor will first call the super constructor of EventEmitter, then assign the options and attributes.
+* If no `options` provided, this will default to an empty object `{}`.
+* `attributes` is first assigned an empty object without inheriting properties from `Object.prototype`. e.g. `this.attributes = Object.create(null);`.
+* If `attributes` are provided then the `attributes` object is set, with `change` event notifications suppressed.
+
+### `get(key)`
+
+* Gets a model property via a key.
+
+### `set(key, value, options?)` or `set({ key: value }, options?)`
+
+* Sets a property on the model to a value and dispatches events.
+* Suppresses `change` event notifications if `options.silent` is set. e.g. `set(key, value, {silent: true})`.
 
-### `unset(name)`
-* unsets a property
+### `unset(fields, options?)`
 
-### `reset([options])`
-* resets a model
-* suppresses `change` event notifications if `options.silent` is set
+* Unsets a field or fields. `fields` can be passed as a string or an array. If `fields` is of type `'string'` it will be wrapped in an array with this string as its single element.
+* Suppresses `change` event notifications if `options.silent` is set. E.g. `unset(fields, {silent: true})`.
 
-### `increment(name)`
-* Increments a property
+### `reset(options?)`
 
-### `toJSON()`
-* returns a JSON representation of the data in the model
+* Resets a model.
+* Suppresses `change` event notifications if `options.silent` is set. E.g. `reset({silent: true})`.
+
+### `increment(propertyName, amount?)`
+
+* Increments a property by the specified amount. Amount defaults to 1 if not provided.
+
+### `toJSON(bare?)`
+
+* Returns a JSON representation of the data in the model.
+* Optional paramter `bare` can be set to `true` or `false`. Defaults to `false`.
+* If `bare` is set to `true`, the JSON object will have a `null` prototype and will not inherit object methods from `Object.prototype`. Helpful info on this can be found on [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects).
 
 ## Remote Model Usage
 
+The Remote Model is a sub-class of the previously highlighted Local Model, and as such inherits its constructor and property accessors.
+
 Normally this would be used as an abstract class and extended with your own implementation.
 
 Implementations would normally define at least a `url():url` method to define the target of API calls.
 
 Example implimentation:
+
 ```javascript
 class MyModel extends HmpoModel {
     url() {
@@ -78,38 +100,44 @@ model.save((err, data, responseTime) => {
 
 There are three methods for API interaction corresponding to GET, POST, and DELETE http methods:
 
-### `fetch([args, ][callback])`
+### `fetch(args?, callback)`
 
 `fetch` performs a `GET` request on the url
 
+* If no args passed / function passed as only paramater, then args will be set to undefined.
+
 ```javascript
 const model = new Model();
 model.fetch((err, data, responseTime) => {
     console.log(data);
 });
 ```
+
 #### Request
-- Request args for the `got` library, can be set by overriding the `requestConfig({}):{}` method.
 
-- The `url` can be configured either by setting a default in the model options or `requestConfig()` data, or by overriding the `url(default, args):url` method.
+* Request args for the `got` library, can be set by overriding the `requestConfig({}):{}` method.
+* The `url` can be configured either by setting a default in the model options or `requestConfig()` data, or by overriding the `url(default, args):url` method.
 
-- `proxy`, `timeout`, and basic `auth` can be set in the same way, using model options, setting in `requestConfig()`, or by overriding a method.
-- Specifying a `proxy` will set up a proxy tunneling `agent` for the request.
-- Specifying a numeric `timeout` will set the same timeout for all `got` timeout values.
-- Basic `auth` can be a colon separated string, or a `{username, password}` or `{user, pass}` object.
+* `proxy`, `timeout`, and basic `auth` can be set in the same way, using model options, setting in `requestConfig()`, or by overriding a method.
+* Specifying a `proxy` will set up a proxy tunneling `agent` for the request.
+* Specifying a numeric `timeout` will set the same timeout for all `got` timeout values.
+* Basic `auth` can be a colon separated string, or a `{username, password}` or `{user, pass}` object.
 
 #### Response
-- The returned body will be expected to be in JSON format.
-- If `statusCode < 400` the JSON response will be set to the model.
+
+* The returned body will be expected to be in JSON format.
+* If `statusCode < 400` the JSON response will be set to the model.
 This behaviour can be changed by overriding the `parse(data):data` method.
-- If `statusCode >= 400` the data will be passed to the `parseError(statusCode, data):error` method, and the `fetch` callback will be called with the returned error.
-- If response statuses need to be treated differently than the above, the `parseResponse(statusCode, data, cb)` method can be overridden.
-- If the response body is not going to be JSON, the `handleResponse(response, cb)` method can be overridden.
+* If `statusCode >= 400` the data will be passed to the `parseError(statusCode, data):error` method, and the `fetch` callback will be called with the returned error.
+* If response statuses need to be treated differently than the above, the `parseResponse(statusCode, data, cb)` method can be overridden.
+* If the response body is not going to be JSON, the `handleResponse(response, cb)` method can be overridden.
 
-### `save([args, ][callback])`
+### `save(args?, callback)`
 
 `save` performs a `POST` request on the url
 
+* If no args passed / function passed as only paramater, then args will be set to undefined.
+
 ```javascript
 const model = new Model();
 model.set({
@@ -120,13 +148,15 @@ model.save((err, data, responseTime) => {
 });
 ```
 
-- By default the post body will be a JSON encoded object containing all attributes set to the model using, extracted using `model.toJSON()`. This behaviour can be changed by overriding the `prepare(callback(err, data))` method.
-- The response and body will be treated the same way as the `fetch` request above.
+* By default the post body will be a JSON encoded object containing all attributes set to the model using, extracted using `model.toJSON()`. This behaviour can be changed by overriding the `prepare(callback(err, data))` method.
+* The response and body will be treated the same way as the `fetch` request above.
 
-### `delete([args, ][callback])`
+### `delete(args?, callback)`
 
 `delete` performs a `DELETE` request on the url
 
+* If no args passed / function passed as only paramater, then args will be set to undefined.
+
 ```javascript
 const model = new Model();
 model.delete((err, data, responseTime) => {
@@ -139,16 +169,19 @@ model.delete((err, data, responseTime) => {
 API requests will emit events as part of their lifecycle.
 
 `sync` is emitted when an API request is sent
+
 ```javascript
 model.on('sync', function (settings) { });
 ```
 
 `success` is emitted when an API request successfully completes
+
 ```javascript
 model.on('success', function (data, settings, statusCode, responseTime) { });
 ```
 
 `fail` is emitted when an API request fails
+
 ```javascript
 model.on('fail', function (err, data, settings, statusCode, responseTime) { });
 ```
@@ -162,17 +195,24 @@ new Model(null, options);
 ```
 
 `sync` hook is fired when an API request is sent
+
 ```javascript
 options.hooks.sync({ settings });
 ```
 
 `success` hook is fired when an API request successfully completes
+
 ```javascript
 options.hooks.success({ data, settings, statusCode, responseTime });
 ```
 
 `fail` hook is fired when an API request fails
+
 ```javascript
 options.hooks.fail({ err, data, settings, statusCode, responseTime });
 ```
 
+## Examples in other apps
+
+[hmpo-form-wizard example : Submit Model](https://github.com/HMPO/hmpo-form-wizard/blob/master/example/models/submit.js)
+[hmpo-app example : Submission Model](https://github.com/HMPO/hmpo-app/blob/master/example/models/submission.js)

package/eslint.config.js

@@ -5,7 +5,7 @@ const globals = require('globals');
 const styleRules = {
     quotes: ['error', 'single', { avoidEscape: true }],
     'no-trailing-spaces': 'error',
-    indent: 'error',
+    indent: ['error', 4],
     'linebreak-style': ['error', 'unix'],
     semi: ['error', 'always'],
     'brace-style': ['error', '1tbs', { allowSingleLine: true }],

package/lib/local-model.js

@@ -9,7 +9,7 @@ class LocalModel extends EventEmitter {
 
         this.options = options || {};
         this.attributes = Object.create(null);
-        if (attributes) this.set(attributes, {silent: true});
+        if (attributes) this.set(attributes, { silent: true });
     }
 
     get(key) {

package/lib/remote-model.js

@@ -36,7 +36,7 @@ class RemoteModel extends LocalModel {
             callback = args;
             args = undefined;
         }
-        const config = this.requestConfig({method: 'GET'}, args);
+        const config = this.requestConfig({ method: 'GET' }, args);
         this.request(config, callback);
     }
 
@@ -47,7 +47,7 @@ class RemoteModel extends LocalModel {
         }
         this.prepare((err, json) => {
             if (err) return callback(err);
-            const config = this.requestConfig({method: 'POST', json}, args);
+            const config = this.requestConfig({ method: 'POST', json }, args);
             this.request(config, callback);
         });
     }
@@ -57,7 +57,7 @@ class RemoteModel extends LocalModel {
             callback = args;
             args = undefined;
         }
-        const config  = this.requestConfig({method: 'DELETE'}, args);
+        const config = this.requestConfig({ method: 'DELETE' }, args);
         this.request(config, callback);
     }
 
@@ -151,8 +151,8 @@ class RemoteModel extends LocalModel {
     }
 
     request(settings, callback) {
-        this.hookSync({settings});
-        this.logSync({settings});
+        this.hookSync({ settings });
+        this.logSync({ settings });
         this.emit('sync', settings);
 
         let responseTime;
@@ -164,12 +164,12 @@ class RemoteModel extends LocalModel {
 
         const _callback = (err, data, statusCode) => {
             if (err) {
-                this.hookFail({settings, statusCode, responseTime, err, data});
-                this.logError({settings, statusCode, responseTime, err, data});
+                this.hookFail({ settings, statusCode, responseTime, err, data });
+                this.logError({ settings, statusCode, responseTime, err, data });
                 this.emit('fail', err, data, settings, statusCode, responseTime);
             } else {
-                this.hookSuccess({data, settings, statusCode, responseTime});
-                this.logSuccess({settings, statusCode, responseTime});
+                this.hookSuccess({ data, settings, statusCode, responseTime });
+                this.logSuccess({ settings, statusCode, responseTime });
                 this.emit('success', data, settings, statusCode, responseTime);
             }
             if (typeof callback === 'function') {
@@ -255,7 +255,7 @@ class RemoteModel extends LocalModel {
             data.outResponseTime = tokenData.responseTime;
         }
 
-        let outError = (tokenData.err && tokenData.err.message) || (tokenData.data && ( tokenData.data.error || tokenData.data.errors ) );
+        let outError = (tokenData.err && tokenData.err.message) || (tokenData.data && (tokenData.data.error || tokenData.data.errors));
         if (outError) data.outError = outError;
 
         if (tokenData.err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmpo-model",
-  "version": "6.0.1",
+  "version": "6.0.2",
   "description": "Simple model for interacting with http/rest apis.",
   "main": "index.js",
   "scripts": {
@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/HMPO/hmpo-model#readme",
   "dependencies": {
-    "debug": "^4.3.7",
+    "debug": "4.3.7",
     "got": "<12",
     "http-proxy-agent": "^7.0.2",
     "https-proxy-agent": "^7.0.5",
@@ -35,7 +35,7 @@
   "devDependencies": {
     "chai": "^4.5.0",
     "eslint": "^9.12.0",
-    "hmpo-logger": "^8.0.0",
+    "hmpo-logger": "^8.0.2",
     "mocha": "^10.7.3",
     "nyc": "^17.1.0",
     "proxyquire": "^2.1.3",