danholibraryjs 1.10.0 → 2.0.0

package/src/Extensions/index.ts

@@ -1,24 +1,6 @@
-
 export * from './Array';
 export * from './Document';
 export * from './Map';
 export * from './Object';
-export * from './String';
-
-declare global {
-    interface BooleanConstructor {
-        /**
-         * Parses string to boolean. Will only return true if value === "true" otherwise false
-         */
-        parseBoolean(value: string): boolean
-    }
-}
-
-function parseBoolean(value: string) {
-    return value === "true";
-};
-Boolean.parseBoolean = parseBoolean;
-
-export const BooleanExtensions = {
-    parseBoolean
-};
+export * from './Number';
+export * from './String';

package/src/Interfaces/ElementOptions.ts

@@ -1,9 +1,9 @@
-import { Arrayable, IElement } from "../Types"
+import { Arrayable, IElement } from "../Types";
 
 type Events = Record<
-    `on${Capitalize<keyof HTMLElementEventMap>}`,
-    (event: Event) => void
->
+  `on${Capitalize<keyof HTMLElementEventMap>}`,
+  (event: Event) => void
+>;
 
 /**
  * Construction options when creating an HTML element using:
@@ -12,10 +12,10 @@ type Events = Record<
  * @borrows Arrayable
  */
 export type ElementOptions = Partial<
-    Events & Record<string, any> & {
+  Events & Record<string, any> & {
     id: string,
     className: Arrayable<string>;
     children: Arrayable<IElement>;
-    dataset: Record<string, string>
-}>
+    dataset: Record<string, string>;
+  }>;
 export default ElementOptions;

package/src/Interfaces/IReplacement.ts

@@ -7,7 +7,7 @@ import { StringRegex } from "../Types";
  * @borrows StringRegex
 */
 export interface IReplacement {
-    replacer?: StringRegex,
-    replacement?: string
+  replacer?: StringRegex,
+  replacement?: string;
 }
 export default IReplacement;

package/src/Types/Able.ts

@@ -0,0 +1,22 @@
+/**
+ * Item is function or T
+ */
+export type Functionable<T, Args extends any[] = []> = T | ((...args: Args) => T);
+
+/**
+ * Item is Promise<T> or T
+ */
+export type Promisable<T> = T | Promise<T>;
+
+/**
+ * Item is T or null
+ */
+export type Nullable<T> = T | null;
+
+/**
+ * Item cannot be null or undefined
+ */
+export type NonNullable<T> =
+  T extends null ? never :
+  T extends undefined ? never :
+  T;

package/src/Types/Array.ts

@@ -0,0 +1,7 @@
+/**
+ * Item is single or multiple
+ */
+export type Arrayable<T> = T | Array<T>;
+
+export type SingleArrayable<T> = T | [T];
+export type TFromArray<T> = T extends Array<infer U> ? U : never;

package/src/Types/C#.ts

@@ -0,0 +1,9 @@
+/**
+ * C# Guid representation
+ */
+export type Guid = string;
+
+/**
+ * C# TimeSpan representation from JSON
+ */
+export type TimeSpanType = string;

package/src/Types/Date.ts

@@ -1,4 +1,4 @@
-export type LongMonth = 'Janurary' | 'February' | 'March' | 'April' | 'May' | 'June' | 'July' | 'August' | 'September' | 'October' | 'November' | 'December';
+export type LongMonth = 'January' | 'February' | 'March' | 'April' | 'May' | 'June' | 'July' | 'August' | 'September' | 'October' | 'November' | 'December';
 export type ShortMonth = 'Jan' | 'Feb' | 'Mar' | 'Apr' | 'May' | 'Jun' | 'Jul' | 'Aug' | 'Sep' | 'Oct' | 'Nov' | 'Dec';
 export type Month = LongMonth | ShortMonth;
 

package/src/Types/Events.ts

@@ -1,15 +1,15 @@
 /**
- * Default eventhandler mapper. Object with properties that are arrays
+ * Default event-handler mapper. Object with properties that are arrays
  */
- export type BaseEvent<Keys extends string, Types extends Array<any>> = Record<Keys, Types>;
+export type BaseEvent<Keys extends string, Types extends Array<any>> = Record<Keys, Types>;
 
- /**
-  * Eventhandler type for:
-  * @see EventCollection
-  * @borrows BaseEvent
-  */
- export type EventHandler<
-     Events extends BaseEvent<string, Array<any>> = BaseEvent<string, Array<any>>,
-     Event extends keyof Events = keyof Events,
-     ReturnType = any
- > = (...args: Events[Event]) => ReturnType;
+/**
+ * Event-handler type for:
+ * @see EventCollection
+ * @borrows BaseEvent
+ */
+export type EventHandler<
+  Events extends BaseEvent<string, Array<any>> = BaseEvent<string, Array<any>>,
+  Event extends keyof Events = keyof Events,
+  ReturnType = any
+> = (...args: Events[Event]) => ReturnType;

package/src/Types/Function.ts

@@ -0,0 +1,10 @@
+export type NewReturnType<
+  Function extends (...args: any[]) => any,
+  NewReturnType extends any
+> = (...args: Parameters<Function>) => NewReturnType;
+
+export type PromisedReturn<
+  Function extends (...args: any[]) => any,
+> = NewReturnType<Function, Promise<ReturnType<Function>>>;
+
+export type NoFunctions<T> = { [K in keyof T]: T[K] extends Function ? never : T[K]; };

package/src/Types/Object.ts

@@ -0,0 +1,4 @@
+/**
+ * Return types of T
+ */
+export type ValueOf<T> = T[keyof T];

package/src/Types/PropertiesWith.ts

@@ -2,13 +2,44 @@
  * Filters all properties from From that has the return type of Type
  */
 export type PropertiesWith<Type, From> = {
-    [Key in keyof From as From[Key] extends Type ? Key : never]: From[Key]
-}
+  [Key in keyof From as From[Key] extends Type ? Key : never]: From[Key]
+};
 export default PropertiesWith;
 
 /**
  * Fitlers all properties from From that don't have the return type of Type
  */
 export type PropertiesWithout<Type, From> = {
-    [Key in keyof From as From[Key] extends Type ? never : Key]: From[Key]
-}
+  [Key in keyof From as From[Key] extends Type ? never : Key]: From[Key]
+};
+
+/**
+ * GetRepeatedKeys<[
+ *  { username: string, password: string },
+ *  { username: number, email: string },
+ * ]> // { username: string | number }
+ */
+export type GetRepeatedKeys<Types extends Array<any>> = (
+  Types extends [infer First, infer Second, ...infer Rest]
+    ? First extends object
+      ? Second extends object
+        ? {
+          [Key in Extract<keyof First, keyof Second>]: First[Key] | Second[Key]
+        } & GetRepeatedKeys<Rest>
+        : {}
+      : {}
+    : {}
+);
+
+/**
+ * Situation: Model = Character | Artifact | Domain
+ * Type must include generic type T, which is the Model type
+ * Type must also include generic type TProps, which is the properties of the Model type. Selected properties of TProps must extract the types of Model whose properties has been selected.
+ * 
+ * Example:
+ * type Model = Character | Artifact | Domain
+ * Properties<Model, 'name' | 'rarity'>
+ * 
+ * Result: Character | Artifact, because only Character and Artifact have 'name' and 'rarity' properties
+ */
+export type ModelWithProps<T, TProps extends (keyof T | string)> = T extends Record<TProps, any> ? T : never;

package/src/Types/String.ts

@@ -0,0 +1 @@
+export type Autocomplete<T> = T | (string & {});

package/src/Types/TransformTypes.ts

@@ -2,17 +2,35 @@
  * Converts Start types to Switch types in From type
  */
 export type TransformType<From, Start, Switch> = {
-    [Key in keyof From]: From[Key] extends Start ? Switch : From[Key]
-}
+  [Key in keyof From]: From[Key] extends Start ? Switch : From[Key]
+};
 
 /**
  * Returns object with properties matching BaseType with types of NewType
  */
-export type TransformTypes<From, BaseType, NewType> = Record<keyof { 
-    [Key in keyof From as From[Key] extends BaseType ? Key : never]: Key 
-}, NewType>
+export type TransformTypes<From, BaseType, NewType> = Record<keyof {
+  [Key in keyof From as From[Key] extends BaseType ? Key : never]: Key
+}, NewType>;
 
 //Returns From with properties switched from BaseType to NewType
 // export type TransformTypes<From, BaseType, NewType> = TransformType<From, BaseType[keyof BaseType], NewType>;
 
+export type Json<T> = {
+  [Key in keyof T]: T[Key] extends object
+    ? Json<T[Key]>
+    : T[Key] extends Array<infer U>
+      ? Array<Json<U>>
+      : T[Key] extends number | string | boolean | null
+        ? T[Key]
+        : string
+};
+
+
+/**
+ * Type's properties are ReturnType
+ */
+export type AllPropsAre<ReturnType> = {
+  [key: string]: ReturnType;
+};
+
 export default TransformTypes;

package/src/Types/index.ts

@@ -1,18 +1,14 @@
+export * from './Able';
+export * from './Array';
 export * from './BetterTypes';
+export * from './C#';
 export * from './Date';
 export * from './Events';
+export * from './Function';
 export * from './TransformTypes';
+export * from './Object';
 export * from './PropertiesWith';
-
-/**
- * Item is single or multiple
- */
-export type Arrayable<T> = T | Array<T>;
-
-/**
- * Item is function or T
- */
-export type Functionable<T> = T | (() => T);
+export * from './String';
 
 /**
  * Used for HTMLElement.append in ElementOptions, Document.createProperElement.
@@ -23,39 +19,9 @@ export type Functionable<T> = T | (() => T);
  */
 export type IElement = HTMLElement | string;
 
-/**
- * Return types of T
- */
-export type ValueOf<T> = T[keyof T];
-
-/**
- * Type's properties are ReturnType
- */
-export type AllPropsAre<ReturnType> = {
-    [key: string]: ReturnType
-}
-
 /**
  * string or RegExp.. pretty self-explanatory
  */
 export type StringRegex = string | RegExp;
 
-export type If<Boolean extends boolean, True, False> = Boolean extends true ? True : False;
-
-/**
- * GetRepeatedKeys<[
- *  { username: string, password: string },
- *  { username: number, email: string },
- * ]> // { username: string | number }
- */
-export type GetRepeatedKeys<Types extends Array<any>> = (
-    Types extends [infer First, infer Second, ...infer Rest]
-        ? First extends object
-            ? Second extends object
-                ? {
-                    [Key in Extract<keyof First, keyof Second>]: First[Key] | Second[Key]
-                } & GetRepeatedKeys<Rest>
-            : {}
-        : {}
-    : {}
-);
+export type If<Boolean extends boolean, True, False> = Boolean extends true ? True : False;

package/src/Utils/ApiUtils/ApiTypes.ts

@@ -0,0 +1,43 @@
+// An ApiEndpoint parameter can be either a string or undefined
+export type TParam = string | undefined;
+
+// All possible HTTP methods
+export type HttpMethods =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE';
+
+// Options for the Request function
+export type RequestOptions<TBody = any> = Omit<RequestInit, 'method' | 'body'> & {
+  method?: HttpMethods;
+  body?: TBody;
+  noHeaders?: boolean;
+  controller?: AbortController;
+  query?: Record<string, string | undefined>;
+  baseEndpoint?: string;
+};
+
+export type ApiUtilOptions = {
+  baseEndpointDev: string;
+  baseEndpoint?: string;
+  log?: boolean;
+}
+
+// All possible endpoints for the API. This will generate autocomplete when using the Request function
+// The commented code below is an example from my previous "CitizenTaxi" project to illustrate how this works
+
+// export type ApiEndpoints<Param extends TParam = undefined> =
+//   | `bookings` // [GET, POST]
+//   | `bookings?citizenId=${Param}` // [GET] Guid
+//   | `bookings/${Param}` // [GET, PUT, DELETE] Guid bookingId
+
+//   | `notes` // [GET, POST]
+//   | `notes?citizenId=${Param}` // [GET] Guid
+//   | `notes/${Param}` // [GET, PUT, DELETE] Guid noteId
+
+//   | `users` // [GET, POST]
+//   | `users?role=${Param}` // [GET] enum Role
+//   | `users/${Param}` // [GET, PUT, DELETE] Guid userId
+//   | `users/authenticate`; // [POST, DELETE]

package/src/Utils/ApiUtils/RequestUtil.ts

@@ -0,0 +1,87 @@
+import { RequestOptions } from "./ApiTypes";
+
+/**
+ * Makes a request to the API
+ * @param path Api endpoint to request
+ * @param options Additional options for the request
+ * @returns The response from the API
+ */
+export async function Request<TData, ApiEndpoints extends string>(
+  path: ApiEndpoints,
+  // Destructor the options object, if it's undefined then set it to an empty object
+  {
+    method = 'GET',
+    body,
+    noHeaders = false,
+    controller = new AbortController(),
+    query,
+    baseEndpoint
+  }: RequestOptions | undefined = {}, 
+  log = false
+) {
+  // console.log(`Requesting ${path} with method ${method}`);
+
+  // Construct the endpoint for the request
+  const endpoint = (() => {
+    const result = baseEndpoint + ensureSlash(path);
+    if (path.includes('?') || !query) return result;
+
+    // If the query object is defined, then construct a query string from it
+    const queryString = Object.entries(query)
+      .map(([key, value]) => value ? `${key}=${value}` : '')
+      .join('&');
+
+    return path.includes('?') ? `${result}&${queryString}` : `${result}?${queryString}`;
+  })();
+
+  // Construct the request init object to pass to the fetch function
+  const init: RequestInit = {
+    method,
+    body: body ? !noHeaders ? JSON.stringify(body) : body : undefined,
+    headers: !noHeaders ? { 'Content-Type': 'application/json' } : undefined,
+    signal: controller.signal,
+    credentials: 'include',
+    mode: 'cors'
+  };
+
+  // Make the request, log any errors, and throw them again
+  const res = await fetch(endpoint, init).catch(err => {
+    console.error(`Failed to [${method}] ${path}`, err);
+    throw err;
+  });
+
+  if (log) console.log(`[${method}] ${path} responded with ${res.status}`, res);
+
+  // Clone the response so that it can be converted to JSON and text
+  const clone = res.clone();
+
+  // All successful responses are in the 200s, so check if the status code starts with 2
+  const isSuccessful = res.status.toString().startsWith('2');
+
+  // This try-catch block is used to catch any errors when converting the response to JSON
+  // If the response is not jsonable, then the catch will return null for the data
+  try {
+    return {
+      success: isSuccessful,
+      status: res.status,
+      data: await res.json() as TData,
+      text: await clone.text(),
+    };
+  } catch {
+    return {
+      success: isSuccessful,
+      status: res.status,
+      data: null as unknown as TData,
+      text: await clone.text(),
+    };
+  }
+}
+
+/**
+ * Ensures that the path starts with a /
+ * @param path Path string
+ * @returns Path that starts with a /
+ */
+export function ensureSlash(path: string) {
+  return path.startsWith('/') ? path : '/' + path;
+}

package/src/Utils/ApiUtils/index.ts

@@ -0,0 +1,39 @@
+import { ApiUtilOptions, RequestOptions } from "./ApiTypes";
+import { Request } from "./RequestUtil";
+
+export class ApiUtils<ApiEndpoints extends string> {
+  protected __baseEndpointDev: string;
+  protected __baseEndpoint?: string;
+  protected __log: boolean;
+  
+  constructor({ baseEndpointDev, baseEndpoint, log }: ApiUtilOptions) {
+    this.__baseEndpointDev = baseEndpointDev;
+    this.__baseEndpoint = baseEndpoint;
+    this.__log = log ?? false;
+  }
+
+  /**
+   * Make a request to the API
+   * @param path The path to the endpoint
+   * @param options The options for the request
+   * @returns The response from the API
+   */
+  public async request<TData>(
+    path: ApiEndpoints,
+    options?: RequestOptions
+  ) {
+    return Request<TData, ApiEndpoints>(path, {
+      ...options,
+      baseEndpoint: this.baseEndpoint
+    }, this.__log);
+  }
+
+  public get baseEndpoint() {
+    const processExists = 'process' in globalThis;
+
+    // @ts-ignore -- process is not defined in the browser
+    const isDev = processExists && process.env.NODE_ENV === 'development';
+
+    return isDev ? this.__baseEndpointDev : this.__baseEndpoint ?? this.__baseEndpointDev;
+  }
+}

package/src/Utils/ColorUtils.ts

@@ -0,0 +1,102 @@
+export type RGB = [number, number, number];
+export type Hex = `#${string}`;
+export type ColorType = 'hex' | 'rgb' | 'hsl';
+
+
+export function convert(value: RGB, to: Exclude<ColorType, 'rgb'>): string;
+export function convert(value: string, from: Exclude<ColorType, 'rgb'>, to: 'rgb'): RGB;
+export function convert(value: string | RGB, fromOrTo: ColorType, to?: ColorType): string | RGB {
+  const from = typeof value === 'string' ? fromOrTo : 'rgb';
+  const target = typeof value === 'string' ? to : fromOrTo;
+
+  if (from === target) return value as string;
+
+  switch (from) {
+    case 'hsl': {
+      switch (target) {
+        case 'hex': return hslToHex(value as string);
+        case 'rgb': return hexToRgb(hslToHex(value as string)) as RGB;
+      }
+    }
+    case 'rgb': {
+      switch (target) {
+        case 'hex': return hslToHex(rgbToHsl(value as RGB))
+        case 'hsl': return rgbToHsl(value as RGB);
+      }
+    }
+    case 'hex': {
+      switch (target) {
+        case 'rgb': return hexToRgb(value as Hex) as RGB;
+        case 'hsl': return rgbToHsl(hexToRgb(value as Hex));
+      }
+    }
+    default: return value;
+  }
+}
+
+export function generateRandomColor(): Hex {
+  return `#${Math.floor(Math.random() * 16777215).toString(16).padStart(6, '0')}`;
+}
+
+export const ColorUtils = {
+  convert,
+  generateRandomColor
+};
+
+export default ColorUtils;
+
+function hslToHex(value?: string): Hex {
+  if (!value) return "#000000";
+
+  const match = value.match(/hsl\((\d+), (\d+)%, (\d+)%\)/);
+  if (!match) return value as Hex;
+
+  let [_, h, s, l] = match.map(Number);
+  l /= 100;
+  const a = s * Math.min(l, 1 - l) / 100;
+  const format = (value: number) => {
+    const k = (value + h / 30) % 12;
+    const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+    return Math.round(255 * color).toString(16).padStart(2, '0');
+  };
+  return `#${format(0)}${format(8)}${format(4)}`;
+}
+
+function hexToRgb(hex: Hex): RGB {
+  if (!hex) return [0, 0, 0];
+
+  const match = hex.match(/[a-f0-9]{6}|[a-f0-9]{3}/i);
+  if (!match) return [0, 0, 0];
+
+  let colorString = match[0];
+
+  if (match[0].length === 3) colorString = colorString.split('').map(char => char + char).join('');
+
+  const integer = parseInt(colorString, 16);
+  const r = (integer >> 16) & 0xFF;
+  const g = (integer >> 8) & 0xFF;
+  const b = integer & 0xFF;
+
+  return [r, g, b];
+}
+
+function rgbToHsl(rgb: RGB): string {
+  let [r, g, b] = rgb.map(x => x / 255);
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  let h = 0, s = 0, l = (max + min) / 2;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+    switch (max) {
+      case r: h = (g - b) / d + (g < b ? 6 : 0); break;
+      case g: h = (b - r) / d + 2; break;
+      case b: h = (r - g) / d + 4; break;
+    }
+
+    h /= 6;
+  }
+
+  return `hsl(${Math.round(h * 360)}, ${Math.round(s * 100)}%, ${Math.round(l * 100)}%)`;
+}

package/src/Utils/FormUtils.ts

@@ -0,0 +1,33 @@
+/**
+ * Serialize a form into an object
+ * @param form The form to serialize
+ * @returns An object of type T from the form
+ */
+export function serializeForm<T extends object>(form: HTMLFormElement, log = false) {
+  const children = Array.from(form.children);
+  const formData = children.reduce((acc, child) => {
+    // Find inputs and selects
+    const elements = Array.from(child.querySelectorAll('input, select') as NodeListOf<HTMLInputElement | HTMLSelectElement>);
+    if (['INPUT', 'SELECT'].includes(child.tagName)) elements.push(child as HTMLInputElement | HTMLSelectElement);
+
+    for (const element of Array.from(elements)) {
+      if (element.type === 'submit') continue; // Ignore submit buttons
+
+      const name = element.getAttribute('name');
+      if (!name) {
+        console.error('[DanhoLibraryJS] [FormUtil]: name attribute is required', { element });
+        throw new Error('name attribute is required');
+      }
+
+      const value = element.value;
+      if (value === null) console.warn(`${name}.value returned null`, { element });
+
+      if (log) console.log(`[DanhoLibraryJS] [FormUtil]`, { name, value });
+      acc[name] = /^\d$/.test(value) ? parseInt(value) : value;
+    }
+
+    return acc;
+  }, {} as Record<string, any>) as T;
+
+  return formData;
+}

package/src/Utils/NumberUtils.ts

@@ -0,0 +1,3 @@
+export function between(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}