tgui-core 1.0.0

package/src/common/redux.ts

@@ -0,0 +1,196 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+export type Reducer<State = any, ActionType extends Action = AnyAction> = (
+  state: State | undefined,
+  action: ActionType,
+) => State;
+
+export type Store<State = any, ActionType extends Action = AnyAction> = {
+  dispatch: Dispatch<ActionType>;
+  subscribe: (listener: () => void) => void;
+  getState: () => State;
+};
+
+type MiddlewareAPI<State = any, ActionType extends Action = AnyAction> = {
+  getState: () => State;
+  dispatch: Dispatch<ActionType>;
+};
+
+export type Middleware = <State = any, ActionType extends Action = AnyAction>(
+  storeApi: MiddlewareAPI<State, ActionType>,
+) => (next: Dispatch<ActionType>) => Dispatch<ActionType>;
+
+export type Action<TType = any> = {
+  type: TType;
+};
+
+export type AnyAction = Action & {
+  [extraProps: string]: any;
+};
+
+export type Dispatch<ActionType extends Action = AnyAction> = (
+  action: ActionType,
+) => void;
+
+type StoreEnhancer = (createStoreFunction: Function) => Function;
+
+type PreparedAction = {
+  payload?: any;
+  meta?: any;
+};
+
+/**
+ * Creates a Redux store.
+ */
+export const createStore = <State, ActionType extends Action = AnyAction>(
+  reducer: Reducer<State, ActionType>,
+  enhancer?: StoreEnhancer,
+): Store<State, ActionType> => {
+  // Apply a store enhancer (applyMiddleware is one of them).
+  if (enhancer) {
+    return enhancer(createStore)(reducer);
+  }
+
+  let currentState: State;
+  let listeners: Array<() => void> = [];
+
+  const getState = (): State => currentState;
+
+  const subscribe = (listener: () => void): void => {
+    listeners.push(listener);
+  };
+
+  const dispatch = (action: ActionType): void => {
+    currentState = reducer(currentState, action);
+    for (let i = 0; i < listeners.length; i++) {
+      listeners[i]();
+    }
+  };
+
+  // This creates the initial store by causing each reducer to be called
+  // with an undefined state
+  dispatch({ type: '@@INIT' } as ActionType);
+
+  return {
+    dispatch,
+    subscribe,
+    getState,
+  };
+};
+
+/**
+ * Creates a store enhancer which applies middleware to all dispatched
+ * actions.
+ */
+export const applyMiddleware = (
+  ...middlewares: Middleware[]
+): StoreEnhancer => {
+  return (
+    createStoreFunction: (reducer: Reducer, enhancer?: StoreEnhancer) => Store,
+  ) => {
+    return (reducer, ...args): Store => {
+      const store = createStoreFunction(reducer, ...args);
+
+      let dispatch: Dispatch = (action, ...args) => {
+        throw new Error(
+          'Dispatching while constructing your middleware is not allowed.',
+        );
+      };
+
+      const storeApi: MiddlewareAPI = {
+        getState: store.getState,
+        dispatch: (action, ...args) => dispatch(action, ...args),
+      };
+
+      const chain = middlewares.map((middleware) => middleware(storeApi));
+      dispatch = chain.reduceRight(
+        (next, middleware) => middleware(next),
+        store.dispatch,
+      );
+
+      return {
+        ...store,
+        dispatch,
+      };
+    };
+  };
+};
+
+/**
+ * Combines reducers by running them in their own object namespaces as
+ * defined in reducersObj paramter.
+ *
+ * Main difference from redux/combineReducers is that it preserves keys
+ * in the state that are not present in the reducers object. This function
+ * is also more flexible than the redux counterpart.
+ */
+export const combineReducers = (
+  reducersObj: Record<string, Reducer>,
+): Reducer => {
+  const keys = Object.keys(reducersObj);
+
+  return (prevState = {}, action) => {
+    const nextState = { ...prevState };
+    let hasChanged = false;
+
+    for (const key of keys) {
+      const reducer = reducersObj[key];
+      const prevDomainState = prevState[key];
+      const nextDomainState = reducer(prevDomainState, action);
+
+      if (prevDomainState !== nextDomainState) {
+        hasChanged = true;
+        nextState[key] = nextDomainState;
+      }
+    }
+
+    return hasChanged ? nextState : prevState;
+  };
+};
+
+/**
+ * A utility function to create an action creator for the given action
+ * type string. The action creator accepts a single argument, which will
+ * be included in the action object as a field called payload. The action
+ * creator function will also have its toString() overriden so that it
+ * returns the action type, allowing it to be used in reducer logic that
+ * is looking for that action type.
+ *
+ * @param {string} type The action type to use for created actions.
+ * @param {any} prepare (optional) a method that takes any number of arguments
+ * and returns { payload } or { payload, meta }. If this is given, the
+ * resulting action creator will pass it's arguments to this method to
+ * calculate payload & meta.
+ *
+ * @public
+ */
+export const createAction = <TAction extends string>(
+  type: TAction,
+  prepare?: (...args: any[]) => PreparedAction,
+) => {
+  const actionCreator = (...args: any[]) => {
+    let action: Action<TAction> & PreparedAction = { type };
+
+    if (prepare) {
+      const prepared = prepare(...args);
+      if (!prepared) {
+        throw new Error('prepare function did not return an object');
+      }
+      action = { ...action, ...prepared };
+    } else {
+      action.payload = args[0];
+    }
+
+    return action;
+  };
+
+  actionCreator.toString = () => type;
+  actionCreator.type = type;
+  actionCreator.match = (action) => action.type === type;
+
+  return actionCreator;
+};

package/src/common/storage.js

@@ -0,0 +1,196 @@
+/**
+ * Browser-agnostic abstraction of key-value web storage.
+ *
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+export const IMPL_MEMORY = 0;
+export const IMPL_LOCAL_STORAGE = 1;
+export const IMPL_INDEXED_DB = 2;
+
+const INDEXED_DB_VERSION = 1;
+const INDEXED_DB_NAME = 'tgui';
+const INDEXED_DB_STORE_NAME = 'storage-v1';
+
+const READ_ONLY = 'readonly';
+const READ_WRITE = 'readwrite';
+
+const testGeneric = (testFn) => () => {
+  try {
+    return Boolean(testFn());
+  } catch {
+    return false;
+  }
+};
+
+// Localstorage can sometimes throw an error, even if DOM storage is not
+// disabled in IE11 settings.
+// See: https://superuser.com/questions/1080011
+
+const testLocalStorage = testGeneric(
+  () => window.localStorage && window.localStorage.getItem
+);
+
+const testIndexedDb = testGeneric(
+  () =>
+    (window.indexedDB || window.msIndexedDB) &&
+    (window.IDBTransaction || window.msIDBTransaction)
+);
+
+class MemoryBackend {
+  constructor() {
+    this.impl = IMPL_MEMORY;
+    this.store = {};
+  }
+
+  get(key) {
+    return this.store[key];
+  }
+
+  set(key, value) {
+    this.store[key] = value;
+  }
+
+  remove(key) {
+    this.store[key] = undefined;
+  }
+
+  clear() {
+    this.store = {};
+  }
+}
+
+class LocalStorageBackend {
+  constructor() {
+    this.impl = IMPL_LOCAL_STORAGE;
+  }
+
+  get(key) {
+    const value = localStorage.getItem(key);
+    if (typeof value === 'string') {
+      return JSON.parse(value);
+    }
+  }
+
+  set(key, value) {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
+
+  remove(key) {
+    localStorage.removeItem(key);
+  }
+
+  clear() {
+    localStorage.clear();
+  }
+}
+
+class IndexedDbBackend {
+  constructor() {
+    this.impl = IMPL_INDEXED_DB;
+    /** @type {Promise<IDBDatabase>} */
+    this.dbPromise = new Promise((resolve, reject) => {
+      const indexedDB = window.indexedDB || window.msIndexedDB;
+      const req = indexedDB.open(INDEXED_DB_NAME, INDEXED_DB_VERSION);
+      req.onupgradeneeded = () => {
+        try {
+          req.result.createObjectStore(INDEXED_DB_STORE_NAME);
+        } catch (err) {
+          reject(new Error('Failed to upgrade IDB: ' + req.error));
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => {
+        reject(new Error('Failed to open IDB: ' + req.error));
+      };
+    });
+  }
+
+  getStore(mode) {
+    return this.dbPromise.then((db) =>
+      db
+        .transaction(INDEXED_DB_STORE_NAME, mode)
+        .objectStore(INDEXED_DB_STORE_NAME)
+    );
+  }
+
+  async get(key) {
+    const store = await this.getStore(READ_ONLY);
+    return new Promise((resolve, reject) => {
+      const req = store.get(key);
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  async set(key, value) {
+    // The reason we don't _save_ null is because IE 10 does
+    // not support saving the `null` type in IndexedDB. How
+    // ironic, given the bug below!
+    // See: https://github.com/mozilla/localForage/issues/161
+    if (value === null) {
+      value = undefined;
+    }
+    // NOTE: We deliberately make this operation transactionless
+    const store = await this.getStore(READ_WRITE);
+    store.put(value, key);
+  }
+
+  async remove(key) {
+    // NOTE: We deliberately make this operation transactionless
+    const store = await this.getStore(READ_WRITE);
+    store.delete(key);
+  }
+
+  async clear() {
+    // NOTE: We deliberately make this operation transactionless
+    const store = await this.getStore(READ_WRITE);
+    store.clear();
+  }
+}
+
+/**
+ * Web Storage Proxy object, which selects the best backend available
+ * depending on the environment.
+ */
+class StorageProxy {
+  constructor() {
+    this.backendPromise = (async () => {
+      if (testIndexedDb()) {
+        try {
+          const backend = new IndexedDbBackend();
+          await backend.dbPromise;
+          return backend;
+        } catch {}
+      }
+      if (testLocalStorage()) {
+        return new LocalStorageBackend();
+      }
+      return new MemoryBackend();
+    })();
+  }
+
+  async get(key) {
+    const backend = await this.backendPromise;
+    return backend.get(key);
+  }
+
+  async set(key, value) {
+    const backend = await this.backendPromise;
+    return backend.set(key, value);
+  }
+
+  async remove(key) {
+    const backend = await this.backendPromise;
+    return backend.remove(key);
+  }
+
+  async clear() {
+    const backend = await this.backendPromise;
+    return backend.clear();
+  }
+}
+
+export const storage = new StorageProxy();

package/src/common/string.ts

@@ -0,0 +1,173 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+/**
+ * Creates a search terms matcher. Returns true if given string matches the search text.
+ *
+ * @example
+ * ```tsx
+ * type Thing = { id: string; name: string };
+ *
+ * const objects = [
+ *   { id: '123', name: 'Test' },
+ *   { id: '456', name: 'Test' },
+ * ];
+ *
+ * const search = createSearch('123', (obj: Thing) => obj.id);
+ *
+ * objects.filter(search); // returns [{ id: '123', name: 'Test' }]
+ * ```
+ */
+export function createSearch<TObj>(
+  searchText: string,
+  stringifier = (obj: TObj) => JSON.stringify(obj),
+): (obj: TObj) => boolean {
+  const preparedSearchText = searchText.toLowerCase().trim();
+
+  return (obj) => {
+    if (!preparedSearchText) {
+      return true;
+    }
+    const str = stringifier(obj);
+    if (!str) {
+      return false;
+    }
+    return str.toLowerCase().includes(preparedSearchText);
+  };
+}
+
+/**
+ * Capitalizes a word and lowercases the rest.
+ *
+ * @example
+ * ```tsx
+ * capitalize('heLLo') // Hello
+ * ```
+ */
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+}
+
+/**
+ * Similar to capitalize, this takes a string and replaces all first letters
+ * of any words.
+ *
+ * @example
+ * ```tsx
+ * capitalizeAll('heLLo woRLd') // 'HeLLo WoRLd'
+ * ```
+ */
+export function capitalizeAll(str: string): string {
+  return str.replace(/(^\w{1})|(\s+\w{1})/g, (letter) => letter.toUpperCase());
+}
+
+/**
+ * Capitalizes only the first letter of the str, leaving others untouched.
+ *
+ * @example
+ * ```tsx
+ * capitalizeFirst('heLLo woRLd') // 'HeLLo woRLd'
+ * ```
+ */
+export function capitalizeFirst(str: string): string {
+  return str.replace(/^\w/, (letter) => letter.toUpperCase());
+}
+
+const WORDS_UPPER = ['Id', 'Tv'] as const;
+
+const WORDS_LOWER = [
+  'A',
+  'An',
+  'And',
+  'As',
+  'At',
+  'But',
+  'By',
+  'For',
+  'For',
+  'From',
+  'In',
+  'Into',
+  'Near',
+  'Nor',
+  'Of',
+  'On',
+  'Onto',
+  'Or',
+  'The',
+  'To',
+  'With',
+] as const;
+
+/**
+ * Converts a string to title case.
+ *
+ * @example
+ * ```tsx
+ * toTitleCase('a tale of two cities') // 'A Tale of Two Cities'
+ * ```
+ */
+export function toTitleCase(str: string): string {
+  if (!str) return str;
+
+  let currentStr = str.replace(/([^\W_]+[^\s-]*) */g, (str) => {
+    return capitalize(str);
+  });
+
+  for (let word of WORDS_LOWER) {
+    const regex = new RegExp('\\s' + word + '\\s', 'g');
+    currentStr = currentStr.replace(regex, (str) => str.toLowerCase());
+  }
+
+  for (let word of WORDS_UPPER) {
+    const regex = new RegExp('\\b' + word + '\\b', 'g');
+    currentStr = currentStr.replace(regex, (str) => str.toLowerCase());
+  }
+
+  return currentStr;
+}
+
+const TRANSLATE_REGEX = /&(nbsp|amp|quot|lt|gt|apos);/g;
+const TRANSLATIONS = {
+  amp: '&',
+  apos: "'",
+  gt: '>',
+  lt: '<',
+  nbsp: ' ',
+  quot: '"',
+} as const;
+
+/**
+ * Decodes HTML entities and removes unnecessary HTML tags.
+ *
+ * @example
+ * ```tsx
+ * decodeHtmlEntities('&amp;') // returns '&'
+ * decodeHtmlEntities('&lt;') // returns '<'
+ * ```
+ */
+export function decodeHtmlEntities(str: string): string {
+  if (!str) return str;
+
+  return (
+    str
+      // Newline tags
+      .replace(/<br>/gi, '\n')
+      .replace(/<\/?[a-z0-9-_]+[^>]*>/gi, '')
+      // Basic entities
+      .replace(TRANSLATE_REGEX, (match, entity) => TRANSLATIONS[entity])
+      // Decimal entities
+      .replace(/&#?([0-9]+);/gi, (match, numStr) => {
+        const num = parseInt(numStr, 10);
+        return String.fromCharCode(num);
+      })
+      // Hex entities
+      .replace(/&#x?([0-9a-f]+);/gi, (match, numStr) => {
+        const num = parseInt(numStr, 16);
+        return String.fromCharCode(num);
+      })
+  );
+}

package/src/common/timer.ts

@@ -0,0 +1,68 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+/**
+ * Returns a function, that, as long as it continues to be invoked, will
+ * not be triggered. The function will be called after it stops being
+ * called for N milliseconds. If `immediate` is passed, trigger the
+ * function on the leading edge, instead of the trailing.
+ */
+export const debounce = <F extends (...args: any[]) => any>(
+  fn: F,
+  time: number,
+  immediate = false,
+): ((...args: Parameters<F>) => void) => {
+  let timeout: ReturnType<typeof setTimeout> | null;
+  return (...args: Parameters<F>) => {
+    const later = () => {
+      timeout = null;
+      if (!immediate) {
+        fn(...args);
+      }
+    };
+    const callNow = immediate && !timeout;
+    clearTimeout(timeout!);
+    timeout = setTimeout(later, time);
+    if (callNow) {
+      fn(...args);
+    }
+  };
+};
+
+/**
+ * Returns a function, that, when invoked, will only be triggered at most once
+ * during a given window of time.
+ */
+export const throttle = <F extends (...args: any[]) => any>(
+  fn: F,
+  time: number,
+): ((...args: Parameters<F>) => void) => {
+  let previouslyRun: number | null,
+    queuedToRun: ReturnType<typeof setTimeout> | null;
+  return function invokeFn(...args: Parameters<F>) {
+    const now = Date.now();
+    if (queuedToRun) {
+      clearTimeout(queuedToRun);
+    }
+    if (!previouslyRun || now - previouslyRun >= time) {
+      fn.apply(null, args);
+      previouslyRun = now;
+    } else {
+      queuedToRun = setTimeout(
+        () => invokeFn(...args),
+        time - (now - (previouslyRun ?? 0)),
+      );
+    }
+  };
+};
+
+/**
+ * Suspends an asynchronous function for N milliseconds.
+ *
+ * @param {number} time
+ */
+export const sleep = (time: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, time));

package/src/common/type-utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Helps visualize highly complex ui data on the fly.
+ * @example
+ * ```tsx
+ * const { data } = useBackend<CargoData>();
+ * logger.log(getShallowTypes(data));
+ * ```
+ */
+export function getShallowTypes(
+  data: Record<string, any>,
+): Record<string, any> {
+  const output = {};
+
+  for (const key in data) {
+    if (Array.isArray(data[key])) {
+      const arr: any[] = data[key];
+
+      // Return the first array item if it exists
+      if (data[key].length > 0) {
+        output[key] = arr[0];
+        continue;
+      }
+
+      output[key] = 'emptyarray';
+    } else if (typeof data[key] === 'object' && data[key] !== null) {
+      // Please inspect it further and make a new type for it
+      output[key] = 'object (inspect) || Record<string, any>';
+    } else if (typeof data[key] === 'number') {
+      const num = Number(data[key]);
+
+      // 0 and 1 could be booleans from byond
+      if (num === 1 || num === 0) {
+        output[key] = `${num}, BooleanLike?`;
+        continue;
+      }
+      output[key] = data[key];
+    }
+  }
+
+  return output;
+}

package/src/common/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the arguments of a function F as an array.
+ */
+
+export type ArgumentsOf<F extends Function> = F extends (
+  ...args: infer A
+) => unknown
+  ? A
+  : never;

package/src/common/uuid.ts

@@ -0,0 +1,24 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+/**
+ * Creates a UUID v4 string
+ *
+ * @example
+ * ```tsx
+ * createUuid(); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+ * ```
+ */
+export function createUuid(): string {
+  let d = new Date().getTime();
+
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (d + Math.random() * 16) % 16 | 0;
+    d = Math.floor(d / 16);
+
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}