Merge pull request #2207 from flarum/ds/typescript-conversion

Convert several files in `common/utils` to TypeScript

js/src/common/utils/ItemList.ts

@@ -1,5 +1,9 @@
 class Item {
-  constructor(content, priority) {
+  content: any;
+  priority: number;
+  key?: number;
+
+  constructor(content: any, priority?: number) {
     this.content = content;
     this.priority = priority;
   }
@@ -10,23 +14,15 @@ class Item {
  * by priority.
  */
 export default class ItemList {
-  constructor() {
   /**
-     * The items in the list.
+   * The items in the list
-     *
-     * @type {Object}
-     * @public
    */
-    this.items = {};
+  items: { [key: string]: Item } = {};
-  }
 
   /**
    * Check whether the list is empty.
-   *
-   * @returns {boolean}
-   * @public
    */
-  isEmpty() {
+  isEmpty(): boolean {
     for (const i in this.items) {
       if (this.items.hasOwnProperty(i)) {
         return false;
@@ -38,36 +34,27 @@ export default class ItemList {
 
   /**
    * Check whether an item is present in the list.
-   *
-   * @param key
-   * @returns {boolean}
    */
-  has(key) {
+  has(key: string): boolean {
     return !!this.items[key];
   }
 
   /**
    * Get the content of an item.
-   *
-   * @param {String} key
-   * @return {*}
-   * @public
    */
-  get(key) {
+  get(key: string): any {
     return this.items[key].content;
   }
 
   /**
    * Add an item to the list.
    *
-   * @param {String} key A unique key for the item.
+   * @param key A unique key for the item.
-   * @param {*} content The item's content.
+   * @param content The item's content.
-   * @param {Integer} [priority] The priority of the item. Items with a higher
+   * @param [priority] The priority of the item. Items with a higher
    *     priority will be positioned before items with a lower priority.
-   * @return {ItemList}
-   * @public
    */
-  add(key, content, priority = 0) {
+  add(key: string, content: any, priority: number = 0): this {
     this.items[key] = new Item(content, priority);
 
     return this;
@@ -75,14 +62,8 @@ export default class ItemList {
 
   /**
    * Replace an item in the list, only if it is already present.
-   *
-   * @param {String} key
-   * @param {*} [content]
-   * @param {Integer} [priority]
-   * @return {ItemList}
-   * @public
    */
-  replace(key, content = null, priority = null) {
+  replace(key: string, content: any = null, priority: number = null): this {
     if (this.items[key]) {
       if (content !== null) {
         this.items[key].content = content;
@@ -98,12 +79,8 @@ export default class ItemList {
 
   /**
    * Remove an item from the list.
-   *
-   * @param {String} key
-   * @return {ItemList}
-   * @public
    */
-  remove(key) {
+  remove(key: string): this {
     delete this.items[key];
 
     return this;
@@ -111,12 +88,8 @@ export default class ItemList {
 
   /**
    * Merge another list's items into this one.
-   *
-   * @param {ItemList} items
-   * @return {ItemList}
-   * @public
    */
-  merge(items) {
+  merge(items: this): this {
     for (const i in items.items) {
       if (items.items.hasOwnProperty(i) && items.items[i] instanceof Item) {
         this.items[i] = items.items[i];
@@ -130,12 +103,9 @@ export default class ItemList {
    * Convert the list into an array of item content arranged by priority. Each
    * item's content will be assigned an `itemName` property equal to the item's
    * unique key.
-   *
-   * @return {Array}
-   * @public
    */
-  toArray() {
+  toArray(): any[] {
-    const items = [];
+    const items: Item[] = [];
 
     for (const i in this.items) {
       if (this.items.hasOwnProperty(i) && this.items[i] instanceof Item) {

js/src/common/utils/RequestError.ts

@@ -1,5 +1,14 @@
 export default class RequestError {
-  constructor(status, responseText, options, xhr) {
+  status: string;
+  options: object;
+  xhr: XMLHttpRequest;
+
+  responseText: string | null;
+  response: object | null;
+
+  alert: any;
+
+  constructor(status: string, responseText: string | null, options: object, xhr: XMLHttpRequest) {
     this.status = status;
     this.responseText = responseText;
     this.options = options;

js/src/common/utils/abbreviateNumber.ts

@@ -4,11 +4,8 @@
  * @example
  * abbreviateNumber(1234);
  * // "1.2K"
- *
- * @param {Integer} number
- * @return {String}
  */
-export default function abbreviateNumber(number) {
+export default function abbreviateNumber(number: number): string {
   // TODO: translation
   if (number >= 1000000) {
     return Math.floor(number / 1000000) + app.translator.trans('core.lib.number_suffix.mega_text');

js/src/common/utils/extract.js

@@ -1,15 +0,0 @@
-/**
- * The `extract` utility deletes a property from an object and returns its
- * value.
- *
- * @param {Object} object The object that owns the property
- * @param {String} property The name of the property to extract
- * @return {*} The value of the property
- */
-export default function extract(object, property) {
-  const value = object[property];
-
-  delete object[property];
-
-  return value;
-}

js/src/common/utils/extract.ts

@@ -0,0 +1,15 @@
+/**
+ * The `extract` utility deletes a property from an object and returns its
+ * value.
+ *
+ * @param object The object that owns the property
+ * @param property The name of the property to extract
+ * @return The value of the property
+ */
+export default function extract<T, K extends keyof T>(object: T, property: K): T[K] {
+  const value = object[property];
+
+  delete object[property];
+
+  return value;
+}

js/src/common/utils/formatNumber.ts

@@ -5,10 +5,7 @@
  * @example
  * formatNumber(1234);
  * // 1,234
- *
- * @param {Number} number
- * @return {String}
  */
-export default function formatNumber(number) {
+export default function formatNumber(number: number): string {
   return number.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
 }

js/src/common/utils/humanTime.ts

@@ -1,11 +1,8 @@
 /**
  * The `humanTime` utility converts a date to a localized, human-readable time-
  * ago string.
- *
- * @param {Date} time
- * @return {String}
  */
-export default function humanTime(time) {
+export default function humanTime(time: Date): string {
   let d = dayjs(time);
   const now = dayjs();
 
@@ -18,7 +15,7 @@ export default function humanTime(time) {
 
   const day = 864e5;
   const diff = d.diff(dayjs());
-  let ago = null;
+  let ago: string;
 
   // If this date was more than a month ago, we'll show the name of the month
   // in the string. If it wasn't this year, we'll show the year as well.

js/src/common/utils/liveHumanTimes.ts

@@ -1,18 +1,18 @@
-import humanTimeUtil from './humanTime';
+import humanTime from './humanTime';
 
 function updateHumanTimes() {
   $('[data-humantime]').each(function () {
     const $this = $(this);
-    const ago = humanTimeUtil($this.attr('datetime'));
+    const ago = humanTime($this.attr('datetime'));
 
     $this.html(ago);
   });
 }
 
 /**
- * The `humanTime` initializer sets up a loop every 1 second to update
+ * The `liveHumanTimes` initializer sets up a loop every 1 second to update
  * timestamps rendered with the `humanTime` helper.
  */
-export default function humanTime() {
+export default function liveHumanTimes() {
   setInterval(updateHumanTimes, 10000);
 }

js/src/common/utils/string.ts

@@ -1,12 +1,7 @@
 /**
  * Truncate a string to the given length, appending ellipses if necessary.
- *
- * @param {String} string
- * @param {Number} length
- * @param {Number} [start=0]
- * @return {String}
  */
-export function truncate(string, length, start = 0) {
+export function truncate(string: string, length: number, start: number = 0): string {
   return (start > 0 ? '...' : '') + string.substring(start, start + length) + (string.length > start + length ? '...' : '');
 }
 
@@ -17,11 +12,8 @@ export function truncate(string, length, start = 0) {
  * NOTE: This method does not use the comparably sophisticated transliteration
  * mechanism that is employed in the backend. Therefore, it should only be used
  * to *suggest* slugs that can be overridden by the user.
- *
- * @param {String} string
- * @return {String}
  */
-export function slug(string) {
+export function slug(string: string): string {
   return string
     .toLowerCase()
     .replace(/[^a-z0-9]/gi, '-')
@@ -32,11 +24,8 @@ export function slug(string) {
 /**
  * Strip HTML tags and quotes out of the given string, replacing them with
  * meaningful punctuation.
- *
- * @param {String} string
- * @return {String}
  */
-export function getPlainContent(string) {
+export function getPlainContent(string: string): string {
   const html = string.replace(/(<\/p>|<br>)/g, '$1 &nbsp;').replace(/<img\b[^>]*>/gi, ' ');
 
   const dom = $('<div/>').html(html);
@@ -55,10 +44,7 @@ getPlainContent.removeSelectors = ['blockquote', 'script'];
 
 /**
  * Make a string's first character uppercase.
- *
- * @param {String} string
- * @return {String}
  */
-export function ucfirst(string) {
+export function ucfirst(string: string): string {
   return string.substr(0, 1).toUpperCase() + string.substr(1);
 }

js/src/common/utils/stringToColor.ts

@@ -1,4 +1,6 @@
-function hsvToRgb(h, s, v) {
+type RGB = { r: number; g: number; b: number };
+
+function hsvToRgb(h: number, s: number, v: number): RGB {
   let r;
   let g;
   let b;
@@ -51,11 +53,8 @@ function hsvToRgb(h, s, v) {
 
 /**
  * Convert the given string to a unique color.
- *
- * @param {String} string
- * @return {String}
  */
-export default function stringToColor(string) {
+export default function stringToColor(string: string): string {
   let num = 0;
 
   // Convert the username into a number based on the ASCII value of each