@skillswaveca/nova-shared-libraries 1.12.2

package/packages/nova-model/index.js

@@ -0,0 +1,6 @@
+export * from './src/repo/nova-model-repo.js';
+export * from './src/repo/api-token.js';
+export * from './src/model/nova-schema.js';
+export * from './src/model/nova-model.js';
+export * from './src/model/api-token.js';
+export * from './src/model/models/nova-user.js';

package/packages/nova-model/package.json

@@ -0,0 +1,19 @@
+{
+  "type": "module",
+  "name": "@skillswaveca/nova-model",
+  "description": "Nova model stuff",
+  "repository": "https://github.com/SkillsWave/nova-shared-libraries",
+  "version": "1.2.1",
+  "main": "index.js",
+  "scripts": {
+    "create-index": "node ../../scripts/create-index.js",
+    "generate-docs": "documentation build src/** -f html -o docs",
+    "test": "mocha --parallel 'test/**/*.test.js'"
+  },
+  "author": "SkillsWave",
+  "license": "UNLICENSED",
+  "devDependencies": {
+  },
+  "dependencies": {
+  }
+}

package/packages/nova-model/src/model/api-token.js

@@ -0,0 +1,27 @@
+import { NovaSchema, SchemaAttribute } from './nova-schema.js';
+import { NovaModel } from './nova-model.js';
+
+class ApiTokenModelSchema extends NovaSchema {
+
+  constructor() {
+    const config = {
+      apiIdentifier: new SchemaAttribute(),
+      token: new SchemaAttribute(),
+      ttl: new SchemaAttribute(),
+    };
+    super('apiToken', config);
+  }
+}
+
+const ApiTokenSchema = new ApiTokenModelSchema();
+
+export class ApiToken extends NovaModel {
+
+  constructor(base = {}) {
+    super('apiToken', base);
+  }
+
+  getSchema() {
+    return ApiTokenSchema;
+  }
+}

package/packages/nova-model/src/model/models/nova-user.js

@@ -0,0 +1,55 @@
+import { NovaSchema, SchemaAttribute } from '../nova-schema.js';
+import { NovaModel } from '../nova-model.js';
+
+class NovaUserModelSchema extends NovaSchema {
+
+  constructor() {
+    const config = {
+      tenantId: new SchemaAttribute().isRequired(),
+      guid: new SchemaAttribute(),
+      employeeId: new SchemaAttribute(),
+      thirdPartyUserId: new SchemaAttribute(),
+      supervisorDisplayName: new SchemaAttribute(),
+      supervisorThirdPartyUserId: new SchemaAttribute(),
+
+      preferredLanguage: new SchemaAttribute(),
+      firstName: new SchemaAttribute().isRequired(),
+      lastName: new SchemaAttribute().isRequired(),
+      displayName: new SchemaAttribute(),
+      preferredName: new SchemaAttribute(),
+      jobTitle: new SchemaAttribute(),
+      department: new SchemaAttribute(),
+      division: new SchemaAttribute(),
+      workPhone: new SchemaAttribute(),
+      mobilePhone: new SchemaAttribute(),
+      email: new SchemaAttribute().isRequired(),
+      location: new SchemaAttribute(),
+      photoUrl: new SchemaAttribute(),
+      active: new SchemaAttribute(true),
+      employeeStartDate: new SchemaAttribute(),
+    };
+    super('user', config);
+  }
+}
+
+export const NovaUserSchema = new NovaUserModelSchema();
+
+export class NovaUser extends NovaModel {
+
+  constructor(base = {}) {
+    super('user', base);
+  }
+
+  getSchema() {
+    return NovaUserSchema;
+  }
+
+  getDisplayName() {
+    return getDisplayName(this);
+  }
+}
+
+export const getDisplayName = user => {
+  const firstLast = `${user.firstName} ${user.lastName}`;
+  return user.displayName || firstLast || user.email || user.thirdPartyUserId || user.guid || 'Unknown';
+};

package/packages/nova-model/src/model/nova-model.js

@@ -0,0 +1,184 @@
+export const isEmpty = obj => {
+  if (obj === 0 || obj === false) return false; // If it's 0, or the value false it's not empty
+  if (obj instanceof Object && Object.keys(obj).length <= 0) return true; // if it's an object and there are no keys - it's empty
+  if (Array.isArray(obj) && obj.length <= 0) return true; // if it's an empty array
+  return !obj;
+};
+
+const SPECIAL_ATTRIBUTES = ['h', 'r', 'g1h', 'g1r', 'g2h', 'g2r', 'g3h', 'g3r', 'g4h', 'g4r', '__type', 'ignoreUpdates'];
+
+/**
+ * The base class for all Model instances.
+ */
+export class NovaModel {
+
+  /**
+   * Constructs a new NovaModel instance. It will make the base object conform to the schema of the model.
+   * @param modelType
+   * @param base
+   * @returns {NovaModel|any|boolean}
+   */
+  constructor(modelType, base) {
+    this.__type = modelType;
+    const attributeNames = Object.keys({ ...this.modelType.attributes, ...this.modelType.modelAttributes });
+    // Set the base attributes
+    for (const attrName of attributeNames) {
+      if (base[attrName] !== undefined) this[attrName] = base[attrName];
+    }
+    // Apply the default values. Doing it after all the base attributes are set in case the default value is set through
+    // a function(data will be prepopulated).
+    for (const attrName of attributeNames) {
+      const schemaAttribute = this.modelType.attributes[attrName] || this.modelType.modelAttributes[attrName];
+      const attributeValue = this[attrName] ?? schemaAttribute.getDefaultValue(this);
+      if (schemaAttribute.Type && Array.isArray(attributeValue) && schemaAttribute.isArrayType) {
+        // if the attribute value is an array and is an array type, instantiate each element in the array to that type
+        this[attrName] = attributeValue.map(v => new schemaAttribute.Type(v));
+      } else if (schemaAttribute.Type && !schemaAttribute.isArrayType) {
+        // if the attribute has a type and it's not an array type, instantiate the value to that type
+        this[attrName] = new schemaAttribute.Type(attributeValue);
+      } else if (attributeValue !== undefined) {
+        this[attrName] = attributeValue;
+      }
+    }
+    // If the schema allows extra attributes, create a proxy to handle them
+    if (this.getSchema().allowExtraAttributes) {
+      // Whatever attributes don't exist in the schema, add them to the extraAttributes object
+      for (const key of Object.keys(base)) {
+        if (this.isExcludedAttribute(key)) {
+          this.setExtraAttributes(key, base[key]);
+        }
+      }
+      return new Proxy(this, {
+        get(target, property) {
+          return target.getter(property);
+        },
+        set(target, property, value) {
+          target.setter(target, property, value);
+          return true;
+        },
+      });
+    }
+  }
+
+  /**
+   * Sets extra attributes on the model. This is only used if the schema allows extra attributes.
+   * @param key
+   * @param value
+   */
+  setExtraAttributes(key, value) {
+    if (!this.extraAttributes) this.extraAttributes = {};
+    this.extraAttributes[key] = value;
+  }
+
+  /**
+   * Retrieves a property value from the model, including extra attributes not defined in the schema if they exist.
+   * This method first checks for a getter function defined on the property, then checks the model's properties, and finally
+   * falls back to extra attributes.
+   *
+   * @param {string} property - The property name to retrieve the value for.
+   * @returns {*} The value of the property, if found.
+   */
+  getter(property) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(this), property);
+    if (descriptor && typeof descriptor.get === 'function') {
+      return descriptor.get.call(this);
+    }
+    if (this[property] !== undefined) {
+      return this[property];
+    }
+    return this.extraAttributes?.[property];
+  }
+
+  /**
+   * Sets a property value on the model. If the property is identified as an excluded attribute (not part of the schema and not special),
+   * it's treated as an extra attribute. Otherwise, it's set directly on the model.
+   *
+   * @param {NovaModel} target - The target model instance where the property will be set.
+   * @param {string} property - The property name to set the value for.
+   * @param {*} value - The value to set for the property.
+   */
+  setter(target, property, value) {
+    if (this.isExcludedAttribute(property) && typeof value !== 'function') {
+      this.setExtraAttributes(property, value);
+    } else {
+      target[property] = value;
+    }
+  }
+
+  /**
+   * Checks if an attribute is excluded from the model's schema and not part of the special attributes.
+   * Excluded attributes are neither defined in the model's schema nor listed as special, and can be stored as extra attributes.
+   *
+   * @param {string} attribute - The attribute name to check.
+   * @returns {boolean} Returns true if the attribute is excluded, false otherwise.
+   */
+  isExcludedAttribute(attribute) {
+    const allAttrs = [...this.getSchema().attributeNames, ...Object.keys(this.getSchema().modelAttributes)];
+    if (!SPECIAL_ATTRIBUTES.includes(attribute) && !allAttrs.includes(attribute)) return true;
+  }
+
+  get modelName() {
+    return this.__type;
+  }
+
+  get modelType() {
+    return this.getSchema();
+  }
+
+  getFormattedValue(attribute, extraFormatters = []) {
+    const schemaAttribute = this.modelType.getAttribute(attribute);
+    const formatters = [...schemaAttribute.formatters].concat(extraFormatters);
+    let ret = this[attribute];
+    try {
+      for (const format of formatters) {
+        ret = format(this, ret);
+      }
+    } catch (err) {
+      // Ignore the response - return the last result of the chain that doesnt error.
+    }
+    return ret;
+  }
+
+  getPossibleValues(attribute) {
+    return this.modelType.getPossibleValues(attribute);
+  }
+
+  getSchema() {
+    throw new Error('Schema undefined'); // This should never happen. If a model doesn't define it's schema, it's impossible to construct
+  }
+
+  getTranslatedValue(attribute, lang) {
+    return this.modelType.getTranslatedValue(attribute, this[attribute], lang);
+  }
+
+  /**
+   * Serializes the model instance to a JSON object. By default, it includes both model and schema attributes, and it
+   * can also include nested models if they define a toJSON method. This method is typically used to prepare the model for
+   * persistence or transmission.
+   *
+   * @param {boolean} includeModelAttributes - Whether to include model-specific attributes in the output.
+   * @param {boolean} baseModel - Whether this instance is the base model or part of a nested structure.
+   * @returns {Object} The JSON representation of the model.
+   */
+  toJSON(includeModelAttributes = true, baseModel = true) {
+    const attributeNames = includeModelAttributes
+      ? Object.keys({ ...this.modelType.attributes, ...this.modelType.modelAttributes })
+      : Object.keys(this.modelType.attributes);
+
+    // If the object has toJSON, call it. Otherwise, just return the object
+    const _toJSONIfExists = obj => {
+      if (obj && obj.toJSON) return obj.toJSON(includeModelAttributes, false);
+      return obj;
+    };
+    const ret = {};
+    for (const attributeName of attributeNames) {
+      const attribute = this.modelType.attributes[attributeName] || this.modelType.modelAttributes[attributeName];
+      const newVal = Array.isArray(this[attributeName]) ? this[attributeName].map(item => _toJSONIfExists(item)) : _toJSONIfExists(this[attributeName]);
+      if (!isEmpty(newVal) || newVal !== attribute.getDefaultValue(this)) ret[attributeName] = newVal;
+    }
+    ret.__type = this.__type;
+    if (!baseModel) delete ret.__type;
+    return ret;
+  }
+
+}

package/packages/nova-model/src/model/nova-schema.js

@@ -0,0 +1,154 @@
+/**
+ * A class representing the configuration information for a model
+ */
+export class SchemaAttribute {
+
+  constructor(defaultValue) {
+    this.defaultValue = defaultValue;
+    this.formatters = [];
+    this.allowEmptyTranslation = true;
+    this.required = false;
+  }
+
+  addFormatter(func) {
+    this.formatters.push(func);
+    return this;
+  }
+
+  getDefaultValue(model) {
+    return typeof this.defaultValue === 'function' ? this.defaultValue(model) : this.defaultValue;
+  }
+
+  /**
+   * Sets the attribute as required.
+   * @returns {SchemaAttribute}
+   */
+  isRequired() {
+    this.required = true;
+    return this;
+  }
+
+  setAllowEmptyTranslation(allow) {
+    this.allowEmptyTranslation = allow;
+    return this;
+  }
+
+  /**
+   * Sets the possible values for the attribute. This is used for validation and translation.
+   *
+   * @param possibleValues
+   * @returns {SchemaAttribute}
+   */
+  setPossibleValues(possibleValues) {
+    this.possibleValues = possibleValues;
+    return this;
+  }
+
+  /**
+   * @param {class} type - class to use for instantiating value
+   * @param {boolean} isArrayType - whether the type applies to an array attribute
+   */
+  setType(type, isArrayType = false) {
+    this.Type = type;
+    this.isArrayType = isArrayType;
+    return this;
+  }
+
+}
+
+/**
+ * The generic model schema class. Implements functions all schemas support
+ *
+ * TODO: Add the ability to create an AJV schema for validation purposes.
+ */
+export class NovaSchema {
+
+  constructor(type, attributes = [], modelAttributes = {}) {
+    this.lang = 'en';
+    this.type = type;
+    this.attributes = attributes;
+    this._modelAttributes = modelAttributes;
+  }
+
+  get attributes() {
+    return this._attributes;
+  }
+
+  get attributeNames() {
+    return Object.keys(this.attributes);
+  }
+
+  set attributes(attributes) {
+    this._attributes = attributes;
+  }
+
+  // TODO: should we add modelAttributes to getAttribute and other functions?
+  // These are set to be removed before being stored in the db in repo.js (toRecord() will call toJSON(false) -> which wipes the modelAttibutes)
+  get modelAttributes() {
+    return this._modelAttributes;
+  }
+
+  set modelAttributes(mAttributes) {
+    this._modelAttributes = mAttributes;
+  }
+
+  /**
+   * Gets the attribute with the given name. Returns undefined if the attribute doesn't exist.
+   * @param attribute
+   * @returns {*}
+   */
+  getAttribute(attribute) {
+    return this.attributes[attribute];
+  }
+
+  setAllowExtraAttributes() {
+    if (this.allowExtraAttributes) return;
+    this.allowExtraAttributes = true;
+    this.attributes.extraAttributes = new SchemaAttribute();
+  }
+
+  /**
+   * Returns a list of possible values in the following format. Returns undefined if there are no possible values or the attribute doesn't exist.
+   *
+   * @example
+   * {
+   *   displayName: 'Some translated value', // Uses the same translation format as getTranslatedValue
+   *   value: 'The value'.
+   * }
+   * @param attribute
+   * @param language
+   * @returns {undefined|*}
+   */
+  getPossibleValues(attribute, language) {
+    if (!this.attributes[attribute]) return undefined;
+    const possibleValues = this.attributes[attribute].possibleValues;
+    if (!possibleValues) return undefined;
+    return possibleValues.map(value => {
+      return {
+        displayName: this.getTranslatedValue(attribute, value, language),
+        value,
+      };
+    });
+  }
+
+  /**
+   * Returns true if all of the attributes passed in are valid.
+   *
+   * Ignores attributes that are not part of the schema
+   *
+   * @returns {undefined|*}
+   * @param data
+   */
+  isValid(data) {
+    const attributeNames = Object.keys(data);
+    for (const attribute of attributeNames) {
+      if (!this.attributes[attribute]) continue;
+      const possibleValues = this.attributes[attribute].possibleValues;
+      if (!possibleValues) continue;
+      if (!possibleValues.some(val => val === data[attribute])) return false;
+    }
+    return true;
+  }
+
+}
+

package/packages/nova-model/src/repo/api-token.js

@@ -0,0 +1,12 @@
+
+import { NovaModelRepo } from './nova-model-repo.js';
+import { ApiToken } from '../model/api-token.js';
+
+class ApiTokenRepo extends NovaModelRepo {
+
+  toKey(record) {
+    return { h: 'apiToken', r: record.apiIdentifier };
+  }
+}
+
+export const apiTokenRepo = new ApiTokenRepo(ApiToken);

package/packages/nova-model/src/repo/nova-model-repo.js

@@ -0,0 +1,203 @@
+import { DynamoDbDriver } from '../../../drivers/src/aws/dynamodb.js';
+import { log } from '../../../nova-utils/src/logger.js';
+
+const dynamodb = new DynamoDbDriver();
+
+const batchSize = 100;
+
+/**
+ * This class is the generic data repository class. It can be extended to implement specific repositories.
+ */
+export class NovaModelRepo {
+
+  /**
+   * The constructor takes a model class that this repository will use to create models.
+   * @param Model
+   */
+  constructor(Model) {
+    this.Model = Model;
+    this.__model = new Model();
+    this._dynamodb = dynamodb;
+  }
+
+  get dynamodb() {
+    return dynamodb;
+  }
+
+  /**
+   * Helper method to delete a list of records to ddb
+   * @param {Array} records
+   */
+  async deleteRecords(records) {
+    return Promise.all(records.map(async record => {
+      const params = {
+        TableName: this._tableName(),
+        Key: this.toKey(record),
+      };
+      return dynamodb.delete(params);
+    }));
+  }
+
+  /**
+   * Helper method to delete a list of records to ddb
+   * @param {Array} records
+   */
+  async _deleteRecords(records) {
+    return Promise.all(records.map(async record => {
+      const params = {
+        TableName: this._tableName(),
+        Key: this.toKey(record),
+      };
+      return dynamodb.delete(params);
+    }));
+  }
+  /**
+   * Returns the pino logger
+   * @returns {Logger}
+   */
+  get log() {
+    return log;
+  }
+
+  /**
+   * Returns the table name for this class.
+   * @returns {string}
+   * @private
+   */
+  _tableName() {
+    return process.env.TABLE_NAME;
+  }
+
+  /**
+   * Helper method to create a string that can be used to log
+   */
+  _logString(action) {
+    return `${this.__model.modelName}.repository.${action}`;
+  }
+
+  /**
+   * This function is for returning the 'h' and 'r' for the record of this type.
+   * When decalring you toKey function please have them listed inline ie. return { h: h_key, r: r_key }
+   */
+  // eslint-disable-next-line no-unused-vars
+  toKey(model) {
+    throw new Error('Must define a toKey method');
+  }
+
+  /**
+   * This function is for returning the 'h' and 'r' values - as well as all of the gsi's that are used by this data model.
+   * @param model
+   */
+  toKeys(model) {
+    return this.toKey(model);
+  }
+
+  /**
+   * Takes a record and returns a model.
+   */
+  fromRecord(record) {
+    const { r: id, ...item } = record;
+    return new this.Model({ id, ...item });
+  }
+
+  /**
+   * Takes a model and returns a record.
+   */
+  toRecord(model) {
+    const record = new this.Model(model); // This can go away once we are converted to using the models everywhere
+    return {
+      ...this.toKeys(record),
+      ...record.toJSON(false),
+    };
+  }
+
+  async batchGet(ids) {
+    if (!ids || ids.length === 0) return [];
+    const batches = [];
+    if (ids.length >= batchSize) {
+      // split into batches of batchSize or less
+      const batchCount = Math.ceil(ids.length / batchSize);
+      for (let i = 0; i < batchCount; i++) {
+        batches.push(ids.splice(0, batchSize));
+      }
+    } else {
+      batches.push(ids);
+    }
+
+    const mappedBatches = batches.map(batch => batch.map(this.toKey));
+
+    const batchResponses = await Promise.all(mappedBatches.map(async batch => {
+      const params = {
+        RequestItems: {
+          [this._tableName()]: { Keys: batch },
+        },
+      };
+      return await dynamodb.batchGet(params);
+    }));
+
+    const response = batchResponses.map(batch => batch?.Responses[this._tableName()]).flat();
+
+    log.trace({ response }, this._logString('batchGet'));
+    if (response) {
+      return response.map(this.fromRecord);
+    }
+    return [];
+  }
+
+  /**
+   * Get's the model from the database using the 'h' and 'r' values.
+   * @param model The model to get. Doesn't need the whole model(that wouldn't be very useful :D) - just enough to extract the h and r values.
+   */
+  async get(model) {
+    const response = await dynamodb.get({
+      TableName: this._tableName(),
+      Key: this.toKey(model),
+    });
+
+    log.trace({ response }, this._logString('get'));
+
+    if (response.Item) {
+      return this.fromRecord(response.Item);
+    }
+    return undefined;
+  }
+
+  /**
+   * Saves the model to the DB
+   * @param model The model to save.
+   * @param extraAttributes Extra attributes to persist to the DB record that don't exist in the model.
+   */
+  async save(model, extraAttributes = {}) {
+    const params = {
+      TableName: this._tableName(),
+      Item: {
+        ...this.toRecord(model),
+        ...extraAttributes,
+      },
+    };
+
+    log.trace({ params }, this._logString('save'));
+    const response = await dynamodb.put(params);
+    log.trace({ response }, this._logString('save'));
+    return model;
+  }
+
+  /**
+   * Delete the model from the DB. Uses the 'h' and 'r' values to delete the record.
+   * @param model The model to delete. Doesn't need the whole model - just enough to  extract the h and r values.
+   */
+  async delete(model) {
+    const Key = this.toKey(model);
+
+    const response = await dynamodb.delete({
+      TableName: this._tableName(),
+      Key,
+    });
+
+    log.trace({ response }, this._logString('delete'));
+
+    if (response) {
+      return model;
+    }
+  }
+}

package/packages/nova-model/test/.eslintrc.yaml

@@ -0,0 +1,27 @@
+extends:
+  - brightspace/testing-config
+
+rules:
+  indent:
+    - error
+    - 2
+    - SwitchCase: 1
+  no-console:
+    - off
+  sort-imports:
+    - error
+    - ignoreCase: true
+      ignoreDeclarationSort: false
+      ignoreMemberSort: false
+      memberSyntaxSortOrder:
+        - none
+        - all
+        - multiple
+        - single
+      allowSeparatedGroups: true
+  import/no-extraneous-dependencies:
+    - error
+    - devDependencies:
+        - "**/test/**/*.js"
+        - "**/*.spec.js"
+        - "**/*.test.js"