NEW: add MultiLangString model (#115)

closes #47

Author: dwhieb

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,7 +15,7 @@
 
 - [ ] Write code to pass the tests. (`npm test`)
 
-- [ ] Add inline code commenting (using [JSDoc][JSDoc] style).
+- [ ] Add inline code commenting (using [JSDoc][JSDoc] style). Add links to cross-referenced modules, and the DLx data format.
 
 - [ ] Generate the developer documentation (`npm run docs`) and check your changes by opening `docs/index.html` in a browser.
 

archive/models/MultiLangString/MultiLangString.js

@@ -1,9 +1,6 @@
-/**
- * @module
- */
-
 /**
  * A base Model class
+ * @memberof core
  */
 class Model {
 

archive/models/MultiLangString/MultiLangString.test.js

@@ -1,12 +1,7 @@
 /**
- * @module core
+ * @namespace core
  */
 
-/**
- * @member Model
- * @instance
- * @see module:core/Model
- */
 import Model from './Model.js';
 
 export default { Model };

src/core/Model.js

@@ -1,11 +1,8 @@
-/**
- * @module
- */
-
 import Model from '../core/Model.js';
 
 /**
  * A class representing a language
+ * @memberof models
  * @extends Model
  */
 class Language extends Model {

src/core/index.js

@@ -1,14 +1,7 @@
-const {
-  core:   { Model },
-  models: { Language },
-} = require(`../../test`);
+const { models: { Language } } = require(`../../test`);
 
 describe(`Language`, () => {
 
-  it(`is a Model`, () => {
-    expect(new Language).toBeInstanceOf(Model);
-  });
-
   it(`is a Language class`, () => {
     expect(Language.name).toBe(`Language`);
   });

src/models/Language.js

@@ -0,0 +1,108 @@
+/**
+ * @module models.MultiLangString
+ */
+
+import isLanguageTag from '../utilities/validate/isLanguageTag.js';
+
+/**
+ * Proxy traps for the MultiLangString class
+ * @type {Object}
+ */
+const classTraps = {
+  construct(Target, args) {
+
+    const map = Reflect.construct(Target, args);
+
+    Object.defineProperty(map, `set`, {
+      configurable: true,
+      enumerable:   false,
+      get() {
+        return function(key, val) { // eslint-disable-line func-names
+          validateLanguageTag(key);
+          validateString(val);
+          return map.set.apply(this, [key, val]); // eslint-disable-line no-invalid-this
+        };
+      },
+    });
+
+    return map;
+
+  },
+};
+
+/**
+ * Validates a language tag. Throws a type error if the input is not a valid IETF language tag.
+ * @param {Any} input The input to validate
+ */
+function validateLanguageTag(input) {
+  if (!isLanguageTag(input)) {
+    const e = new TypeError(`Each language key must be a valid IETF language tag.`);
+    e.name = `LanguageTagError`;
+    throw e;
+  }
+}
+
+/**
+ * Validates a String for MultiLangStrings. Throws a type error if the input is not a String.
+ * @param {Any} input The input to validate
+ */
+function validateString(input) {
+  if (typeof input !== `string`) {
+    const e = new TypeError(`Each piece of data in a MultiLangString must be a String of text in a particular language.`);
+    e.name = `MultiLangStringError`;
+    throw e;
+  }
+}
+
+/**
+ * A class representing a Multi-Language Text / String
+ * @memberof models
+ * @extends Map
+ *
+ * @example
+ * const translation = new MultiLangString({
+ *   spa: 'Hola, me llamo Daniel.',
+ *   eng: 'Hello, my name is Daniel.',
+ * });
+ *
+ * console.log(translation.get(`spa`)); // Hola, me llamo Daniel.
+ */
+class MultiLangString extends Map {
+
+  /**
+   * Create a new MultiLangString
+   * @param {Map|Object|String} [data={}] The data to use for this MultiLangString, as either a Map, an Object, or a String. If a String is provided, it is assumed to be English.
+   */
+  constructor(data = {}) {
+
+    // VALIDATE ARGUMENTS
+
+    if (!(
+      typeof data === `string`
+      || typeof data === `object`
+    )) {
+      const e = new TypeError(`The data passed to the MultiLangString constructor must be an Object or String.`);
+      e.name = `MultiLangStringDataError`;
+      throw e;
+    }
+
+    // STANDARDIZE DATA
+
+    /* eslint-disable no-param-reassign */
+    if (data && typeof data === `string`) data = { eng: data };
+    if (data instanceof Map) data = Object.fromEntries(data);
+    /* eslint-enable no-param-reassign */
+
+    // VALIDATE DATA
+
+    Object.keys(data).forEach(validateLanguageTag);
+    Object.values(data).forEach(validateString);
+
+    // INSTANTIATE MODEL
+
+    super(Object.entries(data));
+
+  }
+}
+
+export default new Proxy(MultiLangString, classTraps);