@performant-software/shared-components 0.5.1

package/src/utils/Object.js

@@ -0,0 +1,114 @@
+// @flow
+
+import _ from 'underscore';
+
+type OptionsProps = {
+  emptyValues: Array<any>,
+  ignoreHtml: boolean
+};
+
+const EMPTY_VALUES = [
+  '',
+  null,
+  undefined,
+  [],
+  {}
+];
+
+const DEFAULT_OPTIONS = {
+  emptyValues: EMPTY_VALUES,
+  ignoreHtml: true,
+  ignoreWhitespace: true
+};
+
+const HTML_REGEX = /(<([^>]+)>)/gi;
+const WHITESPACE_REGEX = /\s\s+/g;
+
+/**
+ * Returns true if the passed value is considered "empty".
+ *
+ * @param value
+ *
+ * @returns {boolean|*}
+ */
+export const isEmpty = (value: any) => {
+  // If the value is an object or array, use underscore's isEmpty check.
+  if (_.isObject(value) || _.isArray(value)) {
+    return _.isEmpty(value);
+  }
+
+  return !value;
+};
+
+/**
+ * Returns true if the passed two arguments as deep equal. This function will perform a recursive check against all of
+ * the keys in the objects.
+ *
+ * @param a
+ * @param b
+ *
+ * @returns {boolean}
+ */
+export const isEqual = (a: any, b: any, userOptions: OptionsProps = {}) => {
+  const options = _.defaults(userOptions, DEFAULT_OPTIONS);
+
+  // Check equality, consider empty strings and "null" values as equal
+  if (a === b || (_.contains(options.emptyValues, a) && _.contains(options.emptyValues, b))) {
+    return true;
+  }
+
+  // Deep string comparison
+  if (_.isString(a) && _.isString(b)) {
+    let aString = a;
+    let bString = b;
+
+    // Remove superfluous whitespace
+    if (options.ignoreWhitespace) {
+      aString = a.replace(WHITESPACE_REGEX, ' ');
+      bString = b.replace(WHITESPACE_REGEX, ' ');
+    }
+
+    // If we're ignoring HTML, compare the string values with HTML tags removed
+    if (options.ignoreHtml) {
+      aString = aString.replace(HTML_REGEX, '');
+      bString = bString.replace(HTML_REGEX, '');
+    }
+
+    if (aString === bString) {
+      return true;
+    }
+  }
+
+  if (a !== null && typeof a === 'object' && b !== null && typeof b === 'object') {
+    const aKeys = _.keys(a);
+    const bKeys = _.keys(b);
+
+    // If the objects contain different number of keys, return false
+    if (aKeys.length !== bKeys.length) {
+      return false;
+    }
+
+    // Recursively check each key for equality
+    let equal = true;
+
+    _.each(_.keys(a), (key) => {
+      if (!(_.has(b, key) && isEqual(a[key], b[key]))) {
+        equal = false;
+      }
+    });
+
+    // If any of the recursive keys are not equal, return false
+    if (!equal) {
+      return false;
+    }
+
+    // If we've made it this far, we've checked the equality of all the keys in both objects, return true
+    return true;
+  }
+
+  return false;
+};
+
+export default {
+
+};

package/src/utils/String.js

@@ -0,0 +1,20 @@
+// @flow
+
+import _ from 'underscore';
+
+const includes = (a: any, b: any) => (
+  a && b && a.toString().toLowerCase().includes(b.toString().toLowerCase())
+);
+
+const toString = (value: any) => {
+  if (_.isNumber(value) || _.isBoolean(value)) {
+    return value;
+  }
+
+  return value || '';
+};
+
+export default {
+  includes,
+  toString
+};

package/src/utils/Timer.js

@@ -0,0 +1,32 @@
+// @flow
+
+const DEFAULT_TIMEOUT = 500;
+
+/**
+ * The timer class encapsulates the logic for setting and clearing a timeout. This is particularly useful for
+ * keydown/keyup events when we only want to perform an action after the user has finished typing.
+ */
+class Timer {
+  timeout: TimeoutID | null;
+
+  constructor() {
+    this.timeout = null;
+  }
+
+  /**
+   * Clears the search timer.
+   */
+  clearSearchTimer() {
+    clearTimeout(this.timeout);
+  }
+
+  /**
+   * Sets the search timer.
+   */
+  setSearchTimer(onTimeout: () => void) {
+    clearTimeout(this.timeout);
+    this.timeout = setTimeout(onTimeout, DEFAULT_TIMEOUT);
+  }
+}
+
+export default new Timer();

package/src/utils/Utility.js

@@ -0,0 +1,14 @@
+// @flow
+
+/**
+ * Returns true if passed value is a promise (i.e, has a .then method)
+ *
+ * @param *
+ *
+ * @returns {boolean}
+ */
+const isPromise = (value: any) => !!value && typeof value === 'object' && typeof value.then === 'function';
+
+export default {
+  isPromise
+};

package/test/api/Attachments.spec.js

@@ -0,0 +1,32 @@
+import Attachments from '../../src/api/Attachments';
+
+describe('toPayload', () => {
+  test('toPayload adds the attachment, if provided', () => {
+    const formData = {
+      append: jest.fn()
+    };
+
+    const record = {
+      attachment: jest.fn(),
+      attachment_remove: true
+    };
+
+    Attachments.toPayload(formData, 'test', record, 'attachment');
+
+    expect(formData.append).toHaveBeenCalledWith('test[attachment]', record.attachment);
+  });
+
+  test('toPayload removes the attachment if the *_remove attribute is provided with no attachment', () => {
+    const formData = {
+      append: jest.fn()
+    };
+
+    const record = {
+      attachment_remove: true
+    };
+
+    Attachments.toPayload(formData, 'test', record, 'attachment');
+
+    expect(formData.append).toHaveBeenCalledWith('test[attachment_remove]', true);
+  });
+});

package/types/api/Attachments.js.flow

@@ -0,0 +1,28 @@
+// @flow
+
+/**
+ * Helper class for handling binary data. This class should be used in conjunction with the FormDataTransform.
+ */
+class Attachments {
+  /**
+   * Appends the attachment for the passed record to the passed form data. If the attachment is not present, the
+   * "*_remove" attribute will be appended if the attachment has been removed.
+   *
+   * @param formData
+   * @param prefix
+   * @param record
+   * @param name
+   */
+  toPayload(formData: FormData, prefix: string, record: any, name: string) {
+    const attachment = record[name];
+    const removeAttribute = `${name}_remove`;
+
+    if (attachment) {
+      formData.append(`${prefix}[${name}]`, attachment);
+    } else if (record[removeAttribute]) {
+      formData.append(`${prefix}[${removeAttribute}]`, record[removeAttribute]);
+    }
+  }
+}
+
+export default new Attachments();

package/types/api/BaseService.js.flow

@@ -0,0 +1,127 @@
+// @flow
+
+import axios, { type AxiosResponse } from 'axios';
+
+/**
+ * Base class for making API calls. This class uses Axios under the hood and a customizable transform class for
+ * PUT/POST requests.
+ */
+class BaseService {
+  /**
+   * Constructs a new BaseService object. This constructor should never be used directly.
+   */
+  constructor() {
+    if (this.constructor === BaseService) {
+      throw new TypeError('Abstract class "BaseService" cannot be instantiated directly.');
+    }
+  }
+
+  /**
+   * Calls the POST /api/<resource>/ endpoint with the passed item.
+   *
+   * @param item
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  create(item: any): Promise<AxiosResponse> {
+    const transform = this.getTransform();
+
+    // $FlowFixMe - Flow doesn't currently support abstract classes
+    return axios.post(this.getBaseUrl(), transform.toPayload(item), this.getConfig());
+  }
+
+  /**
+   * Calls the DELETE /api/<resource>/:id endpoint for the passed item.
+   *
+   * @param item
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  delete(item: any) {
+    return axios.delete(`${this.getBaseUrl()}/${item.id}`);
+  }
+
+  /**
+   * Calls the GET /api/<resource>/ endpoint.
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  fetchAll(params: any) {
+    return axios.get(this.getBaseUrl(), { params });
+  }
+
+  /**
+   * Calls the GET /api/<resource>/:id endpoint.
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  fetchOne(id: number) {
+    return axios.get(`${this.getBaseUrl()}/${id}`);
+  }
+
+  /**
+   * Calls the create/update API endpoint for the passed item.
+   *
+   * @param item
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  save(item: any) {
+    return item.id ? this.update(item) : this.create(item);
+  }
+
+  /**
+   * Calls the POST /api/<resource>/search endpoint.
+   *
+   * @param params
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  search(params: any) {
+    return axios.post(`${this.getBaseUrl()}/search`, params);
+  }
+
+  /**
+   * Calls the PUT /api/<resource>/:id endpoint with the passed item.
+   *
+   * @param item
+   *
+   * @returns {Promise<AxiosResponse<T>>}
+   */
+  update(item: any) {
+    const transform = this.getTransform();
+
+    // $FlowFixMe - Flow doesn't currently support abstract classes
+    return axios.put(`${this.getBaseUrl()}/${item.id}`, transform.toPayload(item), this.getConfig());
+  }
+
+  // protected
+
+  /**
+   * Returns the API base URL string.
+   */
+  getBaseUrl(): string {
+    // Implemented in concrete classes.
+    return '';
+  }
+
+  /**
+   * Returns the config properties for POST/PUT requests.
+   *
+   * @returns {null}
+   */
+  getConfig() {
+    // Implemented in concrete classes
+    return null;
+  }
+
+  /**
+   * Returns the transform object. This class will be used to generate the object sent on POST/PUT requests.
+   */
+  getTransform() {
+    // Implemented in concrete classes.
+    return {};
+  }
+}
+
+export default BaseService;

package/types/api/BaseTransform.js.flow

@@ -0,0 +1,55 @@
+// @flow
+
+import _ from 'underscore';
+
+/**
+ * Class for handling transforming objects for PUT/POST requests. This class transforms records into
+ * plain Javascript objects.
+ */
+class BaseTransform {
+  /**
+   * Constructs a new BaseTransform object. This constructor should never be used directly.
+   */
+  constructor() {
+    if (this.constructor === BaseTransform) {
+      throw new TypeError('Abstract class "BaseTransform" cannot be instantiated directly.');
+    }
+  }
+
+  // protected
+
+  /**
+   * Returns the parameter name.
+   *
+   * @returns {string}
+   */
+  getParameterName(): string {
+    // Implemented in sub-class
+    return '';
+  }
+
+  /**
+   * Returns the array of payload keys.
+   *
+   * @returns {*[]}
+   */
+  getPayloadKeys(): Array<string> {
+    // Implemented in sub-class
+    return [];
+  }
+
+  /**
+   * Returns the object for POST/PUT requests as a plain Javascript object.
+   *
+   * @param item
+   *
+   * @returns any
+   */
+  toPayload(item: any): any {
+    return {
+      [this.getParameterName()]: _.pick(item, this.getPayloadKeys())
+    };
+  }
+}
+
+export default BaseTransform;

package/types/api/FormDataTransform.js.flow

@@ -0,0 +1,30 @@
+// @flow
+
+import _ from 'underscore';
+import BaseTransform from './BaseTransform';
+import StringUtils from '../utils/String';
+
+/**
+ * Class for handling transforming records for PUT/POST requests. This class transforms objects in FormData. This
+ * class is useful if your model contains binary data to be uploaded.
+ */
+class FormDataTransform extends BaseTransform {
+  /**
+   * Converts the passed records to a formData object to be sent on PUT/POST requests.
+   *
+   * @param record
+   *
+   * @returns {FormData}
+   */
+  toPayload(record: any) {
+    const formData = new FormData();
+
+    _.each(this.getPayloadKeys(), (key) => {
+      formData.append(`${this.getParameterName()}[${key}]`, StringUtils.toString(record[key]));
+    });
+
+    return formData;
+  }
+}
+
+export default FormDataTransform;

package/types/api/NestedAttributesTransform.js.flow

@@ -0,0 +1,63 @@
+// @flow
+
+import _ from 'underscore';
+import StringUtils from '../utils/String';
+
+/**
+ * Class for handling transforming nested attributes of a parent object. This class will handle transforming the
+ * object into a payload to be sent to a POST/PUT request on an API. This class currently supports transforming into
+ * a plain Javascript object or a FormData object.
+ */
+class NestedAttributesTransform {
+  /**
+   * Constructs a new BaseTransform object. This constructor should never be used directly.
+   */
+  constructor() {
+    if (this.constructor === NestedAttributesTransform) {
+      throw new TypeError('Abstract class "NestedAttributesTransform" cannot be instantiated directly.');
+    }
+  }
+
+  /**
+   * Returns the array of payload keys.
+   *
+   * @returns {*[]}
+   */
+  getPayloadKeys() {
+    // Implemented in sub-class.
+    return [];
+  }
+
+  /**
+   * Appends the passed record's collection to the form data.
+   *
+   * @param formData
+   * @param prefix
+   * @param record
+   * @param collection
+   */
+  toFormData(formData: FormData, prefix: string, record: any, collection: string) {
+    _.each(record[collection], (item, index) => {
+      _.each(this.getPayloadKeys(), (key) => {
+        formData.append(`${prefix}[${collection}][${index}][${key}]`, StringUtils.toString(item[key]));
+      });
+    });
+  }
+
+  /**
+   * Transforms the passed record's collection to a payload object.
+   *
+   * @param record
+   * @param collection
+   *
+   * @returns {{[p: string]: *}}
+   */
+  toPayload(record: any, collection: string) {
+    return {
+      [collection]: _.map(record[collection],
+        (item, index) => ({ ..._.pick(item, this.getPayloadKeys()), order: index }))
+    };
+  }
+}
+
+export default NestedAttributesTransform;