isaacscript-common 21.4.0 → 21.5.0

package/src/functions/sort.ts

@@ -0,0 +1,128 @@
+import { isNumber, isString, isTable } from "./types";
+
+function sortNormal(a: unknown, b: unknown): -1 | 0 | 1 {
+  if (!isNumber(a) && !isString(a)) {
+    error(`Failed to sort since the first value was not a number or string.`);
+  }
+
+  if (!isNumber(b) && !isString(b)) {
+    error(`Failed to sort since the second value was not a number or string.`);
+  }
+
+  if (a < b) {
+    return -1;
+  }
+
+  if (a > b) {
+    return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Helper function to sort an array of objects by one of the object keys.
+ *
+ * For example:
+ *
+ * ```ts
+ * const myArray = [
+ *   {
+ *     name: "alice",
+ *     age: 30,
+ *   },
+ *   {
+ *     name: "bob",
+ *     age: 20,
+ *   },
+ * ];
+ * myArray.sort(sortObjectArrayByKey("age"));
+ * ```
+ */
+export function sortObjectArrayByKey(key: string) {
+  return (a: unknown, b: unknown): -1 | 0 | 1 => {
+    if (!isTable(a)) {
+      error(
+        `Failed to sort an object by the key of "${key}" since the first element was not a table.`,
+      );
+    }
+
+    if (!isTable(b)) {
+      error(
+        `Failed to sort an object by the key of "${key}" since the second element was not a table.`,
+      );
+    }
+
+    const aValue = a.get(key);
+    const bValue = b.get(key);
+
+    return sortNormal(aValue, bValue);
+  };
+}
+
+/**
+ * Helper function to sort a two-dimensional array by the first element.
+ *
+ * For example:
+ *
+ * ```ts
+ * const myArray = [[1, 2], [2, 3], [3, 4]];
+ * myArray.sort(twoDimensionalSort);
+ * ```
+ *
+ * This function also properly handles when the array elements are strings or numbers (instead of
+ * another array).
+ *
+ * From:
+ * https://stackoverflow.com/questions/16096872/how-to-sort-2-dimensional-array-by-column-value
+ */
+export function sortTwoDimensionalArray<T>(a: T[], b: T[]): -1 | 0 | 1 {
+  const aType = type(a);
+  const bType = type(b);
+  if (aType !== bType) {
+    error(
+      `Failed to two-dimensional sort since the two elements were disparate types: ${a} & ${b} (${aType} & ${bType})`,
+    );
+  }
+
+  if (aType === "string" || aType === "number") {
+    return sortNormal(a, b);
+  }
+
+  if (aType !== "table") {
+    error(
+      "Failed to two-dimensional sort since the first element was not a string, number, or table.",
+    );
+  }
+
+  if (bType !== "table") {
+    error(
+      "Failed to two-dimensional sort since the second element was not a string, number, or table.",
+    );
+  }
+
+  const firstElement1 = a[0];
+  const firstElement2 = b[0];
+
+  if (firstElement1 === undefined || firstElement1 === null) {
+    error(
+      "Failed to two-dimensional sort since the first element of the first array was undefined.",
+    );
+  }
+
+  if (firstElement2 === undefined || firstElement2 === null) {
+    error(
+      "Failed to two-dimensional sort since the first element of the second array was undefined.",
+    );
+  }
+
+  const elementType1 = type(firstElement1);
+  const elementType2 = type(firstElement2);
+  if (elementType1 !== elementType2) {
+    error(
+      `Failed to two-dimensional sort since the first element of each array were disparate types: ${firstElement1} & ${firstElement2} (${elementType1} & ${elementType2})`,
+    );
+  }
+
+  return sortNormal(firstElement1, firstElement2);
+}

package/src/functions/utils.ts

@@ -1,7 +1,5 @@
 import { RenderMode } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
-import { CONSOLE_COMMANDS_SET } from "../sets/consoleCommandsSet";
-import { log } from "./log";
 
 /**
  * Helper function to return an array of integers with the specified range, inclusive on the lower
@@ -95,29 +93,6 @@ export function isReflectionRender(): boolean {
   return renderMode === RenderMode.WATER_REFLECT;
 }
 
-/**
- * Helper function to see if a particular command is a vanilla console command. This is useful
- * because the `EXECUTE_CMD` callback will not fire for any vanilla commands.
- */
-export function isVanillaConsoleCommand(commandName: string): boolean {
-  return CONSOLE_COMMANDS_SET.has(commandName);
-}
-
-/**
- * Helper function to log a message to the "log.txt" file and to print it to the screen at the same
- * time.
- */
-export function logAndPrint(msg: string): void {
-  log(msg);
-  print(msg);
-}
-
-/** Helper function to print whether something was enabled or disabled to the in-game console. */
-export function printEnabled(enabled: boolean, description: string): void {
-  const enabledText = enabled ? "Enabled" : "Disabled";
-  print(`${enabledText} ${description}.`);
-}
-
 /**
  * Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.
  *
@@ -159,102 +134,3 @@ export function repeat(n: int, func: (i: int) => void): void {
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export function todo(...args: unknown[]): void {}
-
-/**
- * Helper function to sort a two-dimensional array by the first element.
- *
- * For example:
- *
- * ```ts
- * const myArray = [[1, 2], [2, 3], [3, 4]];
- * myArray.sort(twoDimensionalSort);
- * ```
- *
- * From:
- * https://stackoverflow.com/questions/16096872/how-to-sort-2-dimensional-array-by-column-value
- */
-export function twoDimensionalSort<T>(array1: T[], array2: T[]): -1 | 0 | 1 {
-  const type1 = type(array1);
-  const type2 = type(array2);
-  if (type1 !== type2) {
-    error(
-      `Failed to two-dimensional sort since the two elements were disparate types: ${array1} & ${array2} (${type1} & ${type2})`,
-    );
-  }
-
-  if (type1 === "string" || type1 === "number") {
-    if (array1 === array2) {
-      return 0;
-    }
-
-    return array1 < array2 ? -1 : 1;
-  }
-
-  if (type1 !== "table") {
-    error(
-      "Failed to two-dimensional sort since the elements were not a string, number, or table.",
-    );
-  }
-
-  const firstElement1 = array1[0];
-  const firstElement2 = array2[0];
-
-  if (firstElement1 === undefined || firstElement1 === null) {
-    error(
-      "Failed to two-dimensional sort since the first element of the first array was undefined.",
-    );
-  }
-
-  if (firstElement2 === undefined || firstElement2 === null) {
-    error(
-      "Failed to two-dimensional sort since the first element of the second array was undefined.",
-    );
-  }
-
-  const elementType1 = type(firstElement1);
-  const elementType2 = type(firstElement2);
-  if (elementType1 !== elementType2) {
-    error(
-      `Failed to two-dimensional sort since the first element of each array were disparate types: ${firstElement1} & ${firstElement2} (${elementType1} & ${elementType2})`,
-    );
-  }
-
-  if (firstElement1 === firstElement2) {
-    return 0;
-  }
-
-  return firstElement1 < firstElement2 ? -1 : 1;
-}
-
-/**
- * Helper function to validate that an interface contains all of the keys of an enum. You must
- * specify both generic parameters in order for this to work properly (i.e. the interface and then
- * the enum).
- *
- * For example:
- *
- * ```ts
- * enum MyEnum {
- *   Value1,
- *   Value2,
- *   Value3,
- * }
- *
- * interface MyEnumToType {
- *   [MyEnum.Value1]: boolean;
- *   [MyEnum.Value2]: number;
- *   [MyEnum.Value3]: string;
- * }
- *
- * validateInterfaceMatchesEnum<MyEnumToType, MyEnum>();
- * ```
- *
- * This function is only meant to be used with interfaces (i.e. types that will not exist at
- * run-time). If you are generating an object that will contain all of the keys of an enum, use the
- * `satisfies` operator with the `Record` type instead.
- */
-export function validateInterfaceMatchesEnum<
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  T extends Record<Enum, unknown>,
-  Enum extends string | number,
->(): void {}

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from "./classes/DefaultMap";
 export * from "./classes/ModFeature";
-export * from "./classes/ModUpgradedBase";
+export * from "./classes/ModUpgraded";
 export * from "./core/cachedClasses";
 export * from "./core/constants";
 export * from "./core/constantsFirstLast";
@@ -35,6 +35,7 @@ export * from "./functions/chargeBar";
 export * from "./functions/collectibles";
 export * from "./functions/collectibleTag";
 export * from "./functions/color";
+export * from "./functions/console";
 export * from "./functions/curses";
 export * from "./functions/debugFunctions";
 export * from "./functions/decorators";
@@ -106,6 +107,7 @@ export * from "./functions/seeds";
 export * from "./functions/serialization";
 export * from "./functions/set";
 export * from "./functions/slots";
+export * from "./functions/sort";
 export * from "./functions/sound";
 export * from "./functions/spawnCollectible";
 export * from "./functions/sprites";
@@ -156,7 +158,6 @@ export * from "./types/GridEntityID";
 export * from "./types/HasFunction";
 export * from "./types/Immutable";
 export * from "./types/LowercaseKeys";
-export * from "./types/ModUpgraded";
 export * from "./types/PickingUpItem";
 export * from "./types/PickupIndex";
 export * from "./types/PlayerIndex";

package/src/interfaces/private/AddCallbackParametersCustom.ts

@@ -33,7 +33,7 @@ import { HealthType } from "../../enums/HealthType";
 import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
 import { SlotDestructionType } from "../../enums/SlotDestructionType";
 import { StatType } from "../../enums/StatType";
-import { validateInterfaceMatchesEnum } from "../../functions/utils";
+import { validateInterfaceMatchesEnum } from "../../functions/enums";
 import {
   PickingUpItem,
   PickingUpItemCollectible,

package/src/interfaces/private/ModUpgradedInterface.ts

@@ -1,9 +1,11 @@
 import { Feature } from "../../classes/private/Feature";
 
 /**
- * An interface that represents the `ModUpgradedBase` class.
+ * An interface that represents the `ModUpgraded` class.
  *
- * These methods are private on the real `ModUpgradedBase` class, so the instantiated class must be
+ * This is used to prevent circular dependencies.
+ *
+ * These methods are private on the real `ModUpgraded` class, so the instantiated class must be
  * unsafely type-asserted.
  */
 export interface ModUpgradedInterface extends Mod {

package/src/types/{ModUpgraded.ts → private/ModUpgradedWithFeatures.ts}

@@ -1,10 +1,10 @@
-import { ModUpgradedBase } from "../classes/ModUpgradedBase";
-import { Feature } from "../classes/private/Feature";
-import { ISCFeature } from "../enums/ISCFeature";
-import { ISCFeatureToClass } from "../features";
-import { PublicInterface } from "./PublicInterface";
-import { TupleToIntersection } from "./TupleToIntersection";
-import { Writeable } from "./Writable";
+import { ModUpgraded } from "../../classes/ModUpgraded";
+import { Feature } from "../../classes/private/Feature";
+import { ISCFeature } from "../../enums/ISCFeature";
+import { ISCFeatureToClass } from "../../features";
+import { PublicInterface } from "../PublicInterface";
+import { TupleToIntersection } from "../TupleToIntersection";
+import { Writeable } from "../Writable";
 
 /**
  * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
@@ -15,9 +15,13 @@ import { Writeable } from "./Writable";
  *
  * By specifying one or more optional features, end-users will get a version of `ModUpgraded` that
  * has extra methods corresponding to the features that were specified.
+ *
+ * This type is in the private directory because if it was exported, it would cause all of the
+ * internal feature classes to populate the auto-complete of end-user mods (which should never be
+ * directly imported by end-users).
  */
-export type ModUpgraded<T extends readonly ISCFeature[] = []> =
-  ModUpgradedBase & ISCFeaturesToKeys<T>;
+export type ModUpgradedWithFeatures<T extends readonly ISCFeature[] = []> =
+  ModUpgraded & ISCFeaturesToKeys<T>;
 
 /**
  * We want to only extract the class public methods, so we omit the keys of the `Feature` base

package/dist/src/classes/ModUpgradedBase.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ModUpgradedBase.d.ts","sourceRoot":"","sources":["../../../src/classes/ModUpgradedBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8DAA8D,CAAC;AAIhG,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAQ/D,OAAO,EAAE,2BAA2B,EAAE,MAAM,mDAAmD,CAAC;AAMhG;;;;;;;;;GASG;AACH,qBAAa,eAAgB,YAAW,GAAG;IAKlC,IAAI,EAAE,MAAM,CAAC;IAMpB,4FAA4F;IAC5F,OAAO,CAAC,GAAG,CAAM;IAEjB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,aAAa,CAAoB;IAEzC,OAAO,CAAC,SAAS,CAAC;IAGlB,OAAO,CAAC,QAAQ,CAAC;gBAML,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,KAAK;IAgB3D;;;;OAIG;IACI,WAAW,CAAC,CAAC,SAAS,WAAW,GAAG,MAAM,EAC/C,WAAW,EAAE,CAAC,EACd,GAAG,IAAI,EAAE,CAAC,SAAS,WAAW,GAAG,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GACpE,IAAI;IAIA,mBAAmB,CAAC,CAAC,SAAS,WAAW,GAAG,MAAM,EACvD,WAAW,EAAE,CAAC,EACd,QAAQ,EAAE,gBAAgB,GAAG,GAAG,EAChC,GAAG,IAAI,EAAE,CAAC,SAAS,WAAW,GAAG,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GACpE,IAAI;IAwDP,0FAA0F;IACnF,OAAO,IAAI,OAAO;IAIzB;;;OAGG;IACI,QAAQ,IAAI,MAAM;IAIzB;;;;;OAKG;IACI,cAAc,CAAC,CAAC,SAAS,WAAW,EACzC,WAAW,EAAE,CAAC,EACd,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpC,IAAI;IAIP,6EAA6E;IACtE,UAAU,IAAI,IAAI;IAIzB;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQnC;;;;OAIG;IACI,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,EAClD,iBAAiB,EAAE,CAAC,EACpB,GAAG,IAAI,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,IAAI;IAOP;;;;;OAKG;IACI,oBAAoB,CAAC,CAAC,SAAS,iBAAiB,EACrD,iBAAiB,EAAE,CAAC,EACpB,QAAQ,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1C,IAAI;IAOP;;;OAGG;IACI,eAAe,IAAI,IAAI;IA0C9B;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA+DnB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAsDrB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;CAIhC"}

package/dist/src/types/ModUpgraded.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ModUpgraded.d.ts","sourceRoot":"","sources":["../../../src/types/ModUpgraded.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,GAAG,EAAE,IAC1D,eAAe,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAEzC;;;GAGG;AACH,KAAK,iBAAiB,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,IAAI,IAAI,CAC5D,mBAAmB,CAAC,2BAA2B,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAC9D,MAAM,OAAO,CACd,CAAC;AAEF;;;GAGG;AACH,KAAK,2BAA2B,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI;KACxD,GAAG,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7D,CAAC"}