madden-franchise 3.3.0 → 3.4.0

package/FranchiseEnum.js

@@ -1,12 +1,17 @@
 const FranchiseEnumValue = require('./FranchiseEnumValue');
 
 class FranchiseEnum {
+  /** @param {string | FranchiseEnum} name @param {number} assetId @param {boolean} isRecordPersistent */
   constructor(name, assetId, isRecordPersistent) {
     if (typeof name === 'object') {
       const theEnum = name;
+      /** @private */
       this._name = theEnum._name;
+      /** @private */
       this._assetId = theEnum._assetId;
+      /** @private */
       this._isRecordPersistent = theEnum._isRecordPersistent;
+      /** @private */
       this._members = [];
 
       for (let i = 0; i < theEnum._members.length; i++) {
@@ -24,26 +29,32 @@ class FranchiseEnum {
     }
   };
 
+  /** @returns {string} */
   get name () {
     return this._name;
   };
 
+  /** @returns {number} */
   get assetId () {
     return this._assetId;
   };
 
+  /** @returns {boolean} */
   get isRecordPersistent () {
     return this._isRecordPersistent;
   };
 
+  /** @returns {Array<FranchiseEnumValue>} */
   get members () {
     return this._members;
   }
 
+  /** @param {string} name @param {number} index @param {string} value @param {string?} [unformattedValue] */
   addMember(name, index, value, unformattedValue) {
     this._members.push(new FranchiseEnumValue(name, index, value, unformattedValue));
   };
 
+  /** @param {string} value @returns {FranchiseEnumValue?} */
   getMemberByValue(value) {
     const matches = this._members.filter((member) => { return member.name !== 'First_' && member.name !== 'Last_' && member.value === value; });
     if (matches.length === 0) { throw new Error(`Argument is not a valid enum value for this field. You passed in ${value}. Field name: ${this.name}`); }
@@ -52,6 +63,7 @@ class FranchiseEnum {
     return matchesNoUnderscore ? matchesNoUnderscore : matches[0];
   };
 
+  /** @param {string} value @returns {FranchiseEnumValue?} */
   getMemberByUnformattedValue(value) {
     if (value.length > this._maxLength) {
       const valueToCutOff = value.substring(0, value.length - this._maxLength);
@@ -72,6 +84,7 @@ class FranchiseEnum {
     return matchesNoUnderscore ? matchesNoUnderscore : matches[0];
   };
   
+  /** @param {string} name @returns {FranchiseEnumValue?} */
   getMemberByName(name) {
     return this._members.find((member) => { return member.name.toLowerCase() === name.toLowerCase(); });
   };

package/FranchiseEnumValue.js

@@ -1,10 +1,15 @@
 const utilService = require('./services/utilService');
 
 class FranchiseEnumValue {
+  /** @param {string} name @param {number} index @param {string} value @param {string?} [unformattedValue] */
   constructor(name, index, value, unformattedValue) {
+    /** @private */
     this._name = name;
+    /** @private */
     this._index = typeof(index) === 'number' ? index : parseInt(index);
+    /** @private */
     this._value = typeof(value) === 'number' ? value : parseInt(value);
+    /** @private */
     this._unformattedValue = unformattedValue ? unformattedValue : parseFormattedValue(parseInt(value));
   };
 
@@ -20,10 +25,12 @@ class FranchiseEnumValue {
     return this._value;
   };
 
+  /** @returns {string?} */
   get unformattedValue () {
     return this._unformattedValue;
   };
 
+  /** @param {number} length */
   setMemberLength(length) {
     if (this.value < 0) {
       this._unformattedValue = '1' + this._unformattedValue.padStart(length - 1, '0');

package/FranchiseFile.js

@@ -1,7 +1,6 @@
 const fs = require("fs");
 const zlib = require("zlib");
 const Constants = require("./Constants");
-// const debug = require('debug')('madden-franchise');
 const EventEmitter = require("events").EventEmitter;
 const FranchiseSchema = require("./FranchiseSchema");
 const utilService = require("./services/utilService");
@@ -11,8 +10,24 @@ const FranchiseFileSettings = require("./FranchiseFileSettings");
 const schemaPickerService = require("./services/schemaPicker");
 
 const COMPRESSED_DATA_OFFSET = 0x52;
+/** 
+ * @typedef {Object} AssetTable 
+ * @param {number} assetId 
+ * @param {number} reference 
+ */
+/**
+   * @typedef {Object} RecordReference
+   * @param {number} tableId
+   * @param {number} rowNumber
+   */
 
 class FranchiseFile extends EventEmitter {
+  /**
+   * 
+   * @param {string} filePath 
+   * @param {FranchiseFileSettings?} [settings] 
+   * @returns {Promise<FranchiseFile>}
+   */
   static create(filePath, settings) {
     return new Promise((resolve, reject) => {
       const file = new FranchiseFile(filePath, settings);
@@ -26,27 +41,43 @@ class FranchiseFile extends EventEmitter {
     });
   }
 
+  /**
+   * 
+   * @param {string} filePath 
+   * @param {FranchiseFileSettings} settings 
+   */
   constructor(filePath, settings) {
     super();
+    /** @private @type {FranchiseFileSettings} */
     this._settings = new FranchiseFileSettings(settings);
     this.isLoaded = false;
 
     if (Array.isArray(filePath)) {
+      /** @private @type {string} */
       this._filePath = filePath[0];
     } else {
       this._filePath = filePath;
     }
 
+    /** @private @type {Buffer} */
     this._rawContents = fs.readFileSync(filePath);
+
+    /** @private @type {FileType} */
     this._type = getFileType(this._rawContents);
+
+    /** @private @type {string} */
     this._gameYear = this._type.year;
+
+    /** @private @type {SchemaMetadata} */
     this._expectedSchemaVersion = getSchemaMetadata(
       this.rawContents,
       this._type
     );
 
     if (this._type.compressed) {
+      /** @type {Buffer} */
       this.packedFileContents = this._rawContents;
+      /** @type {Buffer} */
       this.unpackedFileContents = unpackFile(this._rawContents, this._type);
 
       if (this._type.format === Constants.FORMAT.FRANCHISE_COMMON) {
@@ -67,6 +98,9 @@ class FranchiseFile extends EventEmitter {
     }
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   parse() {
     const that = this;
     this.strategy = StrategyPicker.pick(this.type);
@@ -136,6 +170,7 @@ class FranchiseFile extends EventEmitter {
         }
       }
 
+      /** @type {Array<FranchiseFileTable>} */
       this.tables = [];
 
       for (let i = 0; i < tableIndicies.length; i++) {
@@ -175,6 +210,7 @@ class FranchiseFile extends EventEmitter {
     });
 
     let assetTablePromise = new Promise((resolve, reject) => {
+      /** @type {Array<AssetTable>} */
       this.assetTable = [];
 
       const assetTableOffset = this.unpackedFileContents.readUInt32BE(4);
@@ -218,10 +254,22 @@ class FranchiseFile extends EventEmitter {
       });
   }
 
+  /**
+   * 
+   * @param {string} outputFilePath 
+   * @param {object} options 
+   * @returns {Promise<string>}
+   */
   save(outputFilePath, options) {
     return this.packFile(outputFilePath, options);
   }
 
+  /**
+   * 
+   * @param {string} outputFilePath 
+   * @param {object} options 
+   * @returns {Promise<string>}
+   */
   packFile(outputFilePath, options) {
     const that = this;
     this.emit("saving");
@@ -262,6 +310,9 @@ class FranchiseFile extends EventEmitter {
     });
   }
 
+  /**
+   * @returns {Buffer}
+   */
   get rawContents() {
     return this._rawContents;
   }
@@ -270,26 +321,44 @@ class FranchiseFile extends EventEmitter {
     return this._openedFranchiseFile;
   }
 
+  /**
+   * @returns {string}
+   */
   get filePath() {
     return this._filePath;
   }
 
+  /**
+   * @returns {FranchiseSchema}
+   */
   get schema() {
     return this.schemaList;
   }
 
+  /**
+   * @returns {SchemaMetadata}
+   */
   get expectedSchemaVersion() {
     return this._expectedSchemaVersion;
   }
 
+  /**
+   * @returns {FranchiseFileSettings}
+   */
   get settings() {
     return this._settings;
   }
 
+  /**
+   * @returns {string}
+   */
   get gameYear() {
     return this._gameYear;
   }
 
+  /**
+   * @returns {FileType}
+   */
   get type() {
     return this._type;
   }
@@ -302,39 +371,74 @@ class FranchiseFile extends EventEmitter {
     this._settings = new FranchiseFileSettings(settings);
   }
 
+  /**
+   * 
+   * @param {string} name 
+   * @returns {FranchiseFileTable?}
+   */
   getTableByName(name) {
     return this.tables.find((table) => {
       return table.name === name;
     });
   }
 
+  /**
+   * 
+   * @param {string} name 
+   * @returns {Array<FranchiseFileTable>}
+   */
   getAllTablesByName(name) {
     return this.tables.filter((table) => {
       return table.name === name;
     });
   }
 
+  /**
+   * 
+   * @param {number} id 
+   * @returns {FranchiseFileTable?}
+   */
   getTableById(id) {
     return this.tables.find((table) => {
       return table.header && table.header.tableId === id;
     });
   }
 
+  /**
+   * 
+   * @param {number} index 
+   * @returns {FranchiseFileTable?}
+   */
   getTableByIndex(index) {
     return this.tables[index];
   }
 
+  /**
+   * 
+   * @param {number} id 
+   * @returns {FranchiseFileTable?}
+   */
   getTableByUniqueId(id) {
     return this.tables.find((table) => {
       return table.header && table.header.uniqueId === id;
     });
   }
 
+  /**
+   * 
+   * @param {string} referenceValue 
+   * @returns {RecordReference}
+   */
   getReferencedRecord(referenceValue) {
     const reference = utilService.getReferenceData(referenceValue);
     return this.getTableById(reference.tableId)?.records[reference.rowNumber];
   }
 
+  /**
+   * 
+   * @param {number} assetId 
+   * @returns {RecordReference?}
+   */
   getReferenceFromAssetId(assetId) {
     const assetEntry = this.assetTable.find((assetEntry) => {
       return assetEntry.assetId === assetId;
@@ -350,6 +454,18 @@ class FranchiseFile extends EventEmitter {
     }
   }
 
+  /**
+   * @typedef {Object} TableRecordReference
+   * @param {number} tableId
+   * @param {string} name
+   * @param {FranchiseFileTable} table
+   */
+  /**
+   * 
+   * @param {number} tableId 
+   * @param {number} recordIndex 
+   * @returns {Array<TableRecordReference>}
+   */
   getReferencesToRecord(tableId, recordIndex) {
     const referencedTable = this.getTableById(tableId);
 
@@ -455,6 +571,18 @@ function _saveSync(destination, packedContents) {
   fs.writeFileSync(destination, packedContents);
 }
 
+/**
+ * @typedef {Object} FileType
+ * @property {string} format
+ * @property {number} year
+ * @property {boolean} compressed
+ */
+
+/**
+ * 
+ * @param {Buffer} data 
+ * @returns {FileType}
+ */
 function getFileType(data) {
   const isDataCompressed = isCompressed(data);
   const format = getFormat(data, isDataCompressed);
@@ -467,6 +595,11 @@ function getFileType(data) {
   };
 }
 
+/**
+ * 
+ * @param {Buffer} data 
+ * @returns {Boolean}
+ */
 function isCompressed(data) {
   const DECOMPRESSED_HEADER = Buffer.from([0x46, 0x72, 0x54, 0x6b]); // FrTk
 
@@ -477,6 +610,12 @@ function isCompressed(data) {
   return true;
 }
 
+/**
+ * 
+ * @param {Buffer} data 
+ * @param {Boolean} isCompressed 
+ * @returns {string}
+ */
 function getFormat(data, isCompressed) {
   if (isCompressed) {
     const ZLIB_HEADER = Buffer.from([0x78, 0x9c]);
@@ -497,6 +636,13 @@ function getFormat(data, isCompressed) {
   }
 }
 
+/**
+ * 
+ * @param {Buffer} data 
+ * @param {Boolean} isCompressed 
+ * @param {string} format 
+ * @returns {number}
+ */
 function getGameYear(data, isCompressed, format) {
   const schemaMax = [
     {
@@ -560,6 +706,20 @@ function getGameYear(data, isCompressed, format) {
   }
 }
 
+/**
+ * @typedef {Object} SchemaMetadata
+ * @property {string?} gameYear
+ * @property {number?} major
+ * @property {number?} minor
+ * @property {string?} path
+ */
+
+/**
+ * 
+ * @param {Buffer} data 
+ * @param {FileType} type 
+ * @returns {SchemaMetadata}
+ */
 function getSchemaMetadata(data, type) {
   let schemaMeta = {
     gameYear: type.year,
@@ -590,6 +750,17 @@ function getSchemaMetadata(data, type) {
   return schemaMeta;
 }
 
+/**
+ * @typedef PartialSchemaMetadata
+ * @property {number} major
+ * @property {number} minor
+ */
+
+/**
+ * 
+ * @param {Buffer} data 
+ * @returns {PartialSchemaMetadata}
+ */
 function getCompressedSchema(data) {
   return {
     major: data.readUInt32LE(0x3e),

package/FranchiseFileField.js

@@ -5,33 +5,45 @@ const FranchiseFileTable2Field = require('./FranchiseFileTable2Field');
 const FranchiseFileTable3Field = require('./FranchiseFileTable3Field');
 
 class FranchiseFileField {
+  /** @param {string} key @param {Buffer} value @param {OffsetTableEntry} offset @param {FranchiseFileRecord} parent */
   constructor(key, value, offset, parent) {
+    /** @private */
     this._key = key;
+    /** @private */
     this._recordBuffer = value;
+    /** @private */
     this._unformattedValue = null;
+    /** @private */
     this._offset = offset;
+    /** @private */
     this._parent = parent;
+    /** @private */
     this._isChanged = false;
 
     if (offset.valueInSecondTable) {
+      /** @type {FranchiseFileTable2Field?} */
       this.secondTableField = new FranchiseFileTable2Field(this._recordBuffer.readUInt32BE(offset.offset / 8), offset.maxLength);
       this.secondTableField.fieldReference = this;
     }
 
     if (offset.valueInThirdTable) {
+      /** @type {FranchiseFileTable3Field?} */
       this.thirdTableField = new FranchiseFileTable3Field(this._recordBuffer.readUInt32BE(offset.offset / 8), offset.maxLength);
       this.thirdTableField.fieldReference = this;
     }
   };
 
+  /** @returns {string} */
   get key() {
     return this._key;
   };
 
+  /** @returns {OffsetTableEntry} */
   get offset() {
     return this._offset;
   };
 
+  /** @returns {*} */
   get value() {
     if (this._unformattedValue === null) {
       this._setUnformattedValueIfEmpty();
@@ -44,10 +56,12 @@ class FranchiseFileField {
     return this._value;
   };
 
+  /** @returns {boolean} */
   get isReference() {
     return this._offset.isReference;
   };
 
+  /** @returns {RecordReference?} */
   get referenceData() {
     if (this._unformattedValue === null) {
       this._setUnformattedValueIfEmpty();
@@ -151,6 +165,7 @@ class FranchiseFileField {
     }
   };
 
+  /** @returns {BitView} */
   get unformattedValue() {
     if (this._unformattedValue === null) {
       this._setUnformattedValueIfEmpty();
@@ -159,20 +174,24 @@ class FranchiseFileField {
     return this._unformattedValue;
   };
 
+  /** @param {BitView} unformattedValue */
   set unformattedValue(unformattedValue) {
     this.setUnformattedValueWithoutChangeEvent(unformattedValue);
     this._value = null;
     this._parent.onEvent('change', this);
   };
 
+  /** @returns {boolean} */
   get isChanged() {
     return this._isChanged;
   };
 
+  /** @param {boolean} changed */
   set isChanged(changed) {
     this._isChanged = changed;
   };
 
+  /** @param {OffsetTableEntry} offset */
   getValueAs(offset) {
     if (this._unformattedValue === null) {
       this._setUnformattedValueIfEmpty();
@@ -196,6 +215,7 @@ class FranchiseFileField {
     this._unformattedValue.bigEndian = true;
   };
 
+  /** @param {BitView} unformattedValue @param {boolean} suppressErrors */
   setUnformattedValueWithoutChangeEvent(unformattedValue, suppressErrors) {
     if (!(unformattedValue instanceof BitView)) {
       throw new Error(`Argument must be of type BitView. You passed in a(n) ${typeof unformattedValue}.`);
@@ -205,6 +225,7 @@ class FranchiseFileField {
     }
   }
 
+  /** @returns {FranchiseEnumValue?} */
   _getEnumFromValue(value) {
     const enumName = this.offset.enum.getMemberByName(value);
 
@@ -227,6 +248,7 @@ class FranchiseFileField {
     }
   };
 
+  /** @param {BitView} unformatted, @param {OffsetTableEntry} offset */
   _parseFieldValue(unformatted, offset) {
     if (offset.valueInSecondTable) {
       return this.secondTableField.value;

package/FranchiseFileRecord.js

@@ -2,15 +2,23 @@ const utilService = require('./services/utilService');
 const FranchiseFileField = require('./FranchiseFileField');
 
 class FranchiseFileRecord {
+  /** @param {Buffer} data @param {number} index @param {OffsetTableEntry} offsetTable, @param {FranchiseFileTable} parent */
   constructor(data, index, offsetTable, parent) {
+    /** @type {Buffer}  */
     this._data = data;
+    /** @type {OffsetTableEntry} */
     this._offsetTable = offsetTable;
+    /** @type {number} */
     this.index = index;
+    /** @private @type {Array<FranchiseFileField>} */
     this._fieldsArray = [];
+    /** @private @type {Record<string, FranchiseFileField>} */
     this._fields = this.parseRecordFields();
     this._isChanged = false;
+    /** @type {number} */
     this.arraySize = null;
     this.isEmpty = false;
+    /** @type {FranchiseFileTable} */
     this._parent = parent;
 
     return new Proxy(this, {
@@ -30,22 +38,27 @@ class FranchiseFileRecord {
     })
   };
 
+  /** @returns {Buffer} */
   get hexData () {
     return this._data;
   };
 
+  /** @returns {Record<string, FranchiseFileField>} */
   get fields () {
     return this._fields;
   };
 
+  /** @returns {Array<FranchiseFileField>} */
   get fieldsArray () {
     return this._fieldsArray;
   };
 
+  /** @returns {Buffer} */
   get data() {
     return this._data;
   };
 
+  /** @param {Buffer} data */
   set data (data) {
     this._data = data;
 
@@ -59,6 +72,7 @@ class FranchiseFileRecord {
     return this._isChanged;
   };
 
+  /** @param {boolean} changed */
   set isChanged(changed) {
     this._isChanged = changed;
 
@@ -69,20 +83,24 @@ class FranchiseFileRecord {
     }
   }
 
+  /** @param {string} key @returns {FranchiseFileField?} */
   getFieldByKey(key) {
     return this._fields[key];
   };
 
+  /** @param {string} key @returns {*?} */
   getValueByKey(key) {
     let field = this.getFieldByKey(key);
     return field ? field.value : null;
   };
 
+  /** @param {string} key @returns {RecordReference?} */
   getReferenceDataByKey(key) {
     let field = this.getFieldByKey(key);
     return field ? field.referenceData : null;
   };
 
+  /** @returns {Record<string, FranchiseFileField>} */
   parseRecordFields() {
     let fields = {};
     this._fieldsArray = [];
@@ -105,6 +123,7 @@ class FranchiseFileRecord {
     this.isEmpty = true;
   };
 
+  /** @param {string} name @param {FranchiseFileField} field */
   onEvent(name, field) {
     if (name === 'change') {
       // this._data = utilService.replaceAt(this._data, field.offset.offset, field.unformattedValue);

package/FranchiseFileSettings.js

@@ -1,9 +1,24 @@
+/** 
+ * @typedef {Object} SettingsParam 
+ * @param {boolean?} [saveOnChange]
+ * @param {SchemaMetadata?} [schemaOverride]
+ * @param {string?} [schemaDirectory]
+ * @param {boolean?} [autoParse]
+ * @param {boolean?} [autoUnempty]
+*/
+
 class FranchiseFileSettings {
+  /** @param {SettingsParam} settings */
   constructor(settings) {
+    /** @type {boolean} */
     this.saveOnChange = settings && settings.saveOnChange ? settings.saveOnChange : false;
+    /** @type {SchemaMetadata | false} */
     this.schemaOverride = settings && settings.schemaOverride ? settings.schemaOverride: false;
+    /** @type {string | false} */
     this.schemaDirectory = settings && settings.schemaDirectory ? settings.schemaDirectory : false;
+    /** @type {boolean} */
     this.autoParse = settings && (settings.autoParse !== null && settings.autoParse !== undefined) ? settings.autoParse : true;
+    /** @type {boolean} */
     this.autoUnempty = settings && (settings.autoUnempty !== null && settings.autoUnempty !== undefined) ? settings.autoUnempty : false;
   }
 };