isaacscript-common 10.0.1 → 10.0.2

package/src/functions/rng.ts

@@ -1,3 +1,4 @@
+import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
@@ -6,6 +7,7 @@ import { isTable } from "./types";
 
 export type SerializedRNG = LuaMap<string, unknown> & {
   readonly __serializedRNGBrand: symbol;
+  readonly __kind: CopyableIsaacAPIClassType.RNG;
 };
 
 /**

package/src/functions/serialization.ts

@@ -1,7 +1,13 @@
-import { CopyableIsaacAPIClassType } from "../enums/private/CopyableIsaacAPIClassType";
+import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
 import { ISAAC_API_CLASS_TYPE_TO_BRAND } from "../objects/isaacAPIClassTypeToBrand";
-import { ISAAC_API_CLASS_TYPE_TO_FUNCTIONS } from "../objects/isaacAPIClassTypeToFunctions";
-import { SerializedIsaacAPIClass } from "../types/SerializedIsaacAPIClass";
+import {
+  CopyableIsaacAPIClass,
+  IsaacAPIClassTypeFunctions,
+  IsaacAPIClassTypeToSerializedType,
+  IsaacAPIClassTypeToType,
+  ISAAC_API_CLASS_TYPE_TO_FUNCTIONS,
+  SerializedIsaacAPIClass,
+} from "../objects/isaacAPIClassTypeToFunctions";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
 import { isTable, isUserdata } from "./types";
 
@@ -11,7 +17,9 @@ import { isTable, isUserdata } from "./types";
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export function copyIsaacAPIClass(isaacAPIClass: unknown): unknown {
+export function copyIsaacAPIClass<T extends CopyableIsaacAPIClass>(
+  isaacAPIClass: T,
+): T {
   if (!isUserdata(isaacAPIClass)) {
     error(
       `Failed to copy an Isaac API class since the provided object was of type: ${typeof isaacAPIClass}`,
@@ -27,9 +35,19 @@ export function copyIsaacAPIClass(isaacAPIClass: unknown): unknown {
 
   const copyableIsaacAPIClassType =
     isaacAPIClassType as CopyableIsaacAPIClassType;
-  const functions =
-    ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[copyableIsaacAPIClassType];
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+
+  type ThisIsaacAPIClassType = T;
+  type ThisSerializedIsaacAPIClassType =
+    IsaacAPIClassTypeToSerializedType[T["__kind"]];
+
+  const functions = ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[
+    copyableIsaacAPIClassType
+  ] as unknown as
+    | IsaacAPIClassTypeFunctions<
+        ThisIsaacAPIClassType,
+        ThisSerializedIsaacAPIClassType
+      >
+    | undefined;
   if (functions === undefined) {
     error(
       `Failed to copy an Isaac API class since the associated functions were not found for Isaac API class type: ${copyableIsaacAPIClassType}`,
@@ -46,9 +64,11 @@ export function copyIsaacAPIClass(isaacAPIClass: unknown): unknown {
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export function deserializeIsaacAPIClass(
-  serializedIsaacAPIClass: unknown,
-): unknown {
+export function deserializeIsaacAPIClass<
+  SerializedT extends SerializedIsaacAPIClass,
+>(
+  serializedIsaacAPIClass: SerializedT,
+): IsaacAPIClassTypeToType[SerializedT["__kind"]] {
   if (!isTable(serializedIsaacAPIClass)) {
     error(
       `Failed to deserialize an Isaac API class since the provided object was of type: ${typeof serializedIsaacAPIClass}`,
@@ -64,9 +84,17 @@ export function deserializeIsaacAPIClass(
     );
   }
 
-  const functions =
-    ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[copyableIsaacAPIClassType];
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  type ThisIsaacAPIClassType = IsaacAPIClassTypeToType[SerializedT["__kind"]];
+  type ThisSerializedIsaacAPIClassType = SerializedT;
+
+  const functions = ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[
+    copyableIsaacAPIClassType
+  ] as unknown as
+    | IsaacAPIClassTypeFunctions<
+        ThisIsaacAPIClassType,
+        ThisSerializedIsaacAPIClassType
+      >
+    | undefined;
   if (functions === undefined) {
     error(
       `Failed to deserialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
@@ -81,7 +109,7 @@ export function deserializeIsaacAPIClass(
  * serialized table for brands.
  */
 function getSerializedTableType(
-  serializedIsaacAPIClass: LuaMap<AnyNotNil, unknown>,
+  serializedIsaacAPIClass: SerializedIsaacAPIClass,
 ): CopyableIsaacAPIClassType | undefined {
   for (const [copyableIsaacAPIClassType, serializationBrand] of Object.entries(
     ISAAC_API_CLASS_TYPE_TO_BRAND,
@@ -94,6 +122,20 @@ function getSerializedTableType(
   return undefined;
 }
 
+/**
+ * Helper function to generically check if a given object is a copyable Isaac API class. (This is
+ * used by the save data manager when determining what is safe to copy.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+export function isCopyableIsaacAPIClass(
+  object: unknown,
+): object is CopyableIsaacAPIClass {
+  const allFunctions = Object.values(ISAAC_API_CLASS_TYPE_TO_FUNCTIONS);
+  const isFunctions = allFunctions.map((functions) => functions.is);
+  return isFunctions.some((identityFunction) => identityFunction(object));
+}
+
 /**
  * Helper function to generically check if a given Lua table is a serialized Isaac API class. (This
  * is used by the save data manager when reading data from the "save#.dat" file.)
@@ -118,7 +160,9 @@ export function isSerializedIsaacAPIClass(
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export function serializeIsaacAPIClass(isaacAPIClass: unknown): unknown {
+export function serializeIsaacAPIClass<T extends CopyableIsaacAPIClass>(
+  isaacAPIClass: T,
+): IsaacAPIClassTypeToSerializedType[T["__kind"]] {
   if (!isUserdata(isaacAPIClass)) {
     error(
       `Failed to serialize an Isaac API class since the provided object was of type: ${typeof isaacAPIClass}`,
@@ -134,9 +178,19 @@ export function serializeIsaacAPIClass(isaacAPIClass: unknown): unknown {
 
   const copyableIsaacAPIClassType =
     isaacAPIClassType as CopyableIsaacAPIClassType;
-  const functions =
-    ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[copyableIsaacAPIClassType];
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+
+  type ThisIsaacAPIClassType = T;
+  type ThisSerializedIsaacAPIClassType =
+    IsaacAPIClassTypeToSerializedType[T["__kind"]];
+
+  const functions = ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[
+    copyableIsaacAPIClassType
+  ] as unknown as
+    | IsaacAPIClassTypeFunctions<
+        ThisIsaacAPIClassType,
+        ThisSerializedIsaacAPIClassType
+      >
+    | undefined;
   if (functions === undefined) {
     error(
       `Failed to serialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,

package/src/functions/vector.ts

@@ -1,4 +1,7 @@
-import { Direction } from "isaac-typescript-definitions";
+import {
+  CopyableIsaacAPIClassType,
+  Direction,
+} from "isaac-typescript-definitions";
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { angleToDirection } from "./direction";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
@@ -13,6 +16,7 @@ import { isTable } from "./types";
 
 export type SerializedVector = LuaMap<string, unknown> & {
   readonly __serializedVectorBrand: symbol;
+  readonly __kind: CopyableIsaacAPIClassType.VECTOR;
 };
 
 const OBJECT_NAME = "Vector";

package/src/functions/weighted.ts

@@ -0,0 +1,36 @@
+import { WeightedArray } from "../types/WeightedArray";
+import { arrayToString, sumArray } from "./array";
+import { getRandomFloat } from "./random";
+import { getRandomSeed } from "./rng";
+
+/** Get a random value from a `WeightedArray`. (The second element in the array is the weight.) */
+export function getRandomFromWeightedArray<T>(
+  weightedArray: WeightedArray<T>,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): T {
+  if (weightedArray.length === 0) {
+    error(
+      "Failed to get a random element from a weighted array since the provided array was empty.",
+    );
+  }
+
+  const weights = weightedArray.map((tuple) => tuple[1]);
+  const totalWeight = sumArray(weights);
+  const randomWeight = getRandomFloat(0, totalWeight, seedOrRNG);
+
+  let weightAccumulator = 0;
+  for (const tuple of weightedArray) {
+    const [element, weight] = tuple;
+
+    weightAccumulator += weight;
+    if (weightAccumulator >= randomWeight) {
+      return element;
+    }
+  }
+
+  error(
+    `Failed to get a random element from a weighted array: ${arrayToString(
+      weightedArray,
+    )}`,
+  );
+}

package/src/index.ts

@@ -149,6 +149,7 @@ export * from "./functions/types";
 export * from "./functions/ui";
 export * from "./functions/utils";
 export * from "./functions/vector";
+export * from "./functions/weighted";
 export * from "./interfaces/ChargeBarSprites";
 export * from "./interfaces/Corner";
 export * from "./interfaces/CustomStageTSConfig";
@@ -174,5 +175,5 @@ export * from "./types/PickingUpItem";
 export * from "./types/PickupIndex";
 export * from "./types/PlayerIndex";
 export * from "./types/PossibleStatType";
-export * from "./types/SerializedIsaacAPIClass";
 export * from "./types/TSTLClass";
+export * from "./types/WeightedArray";

package/src/interfaces/SaveData.ts

@@ -1,5 +1,7 @@
 /* eslint-disable max-classes-per-file */
 
+import { CopyableIsaacAPIClass } from "../objects/isaacAPIClassTypeToFunctions";
+
 /**
  * This is the format of the object that you give to the save data manager. It will contains all of
  * the variables for the particular mod feature.
@@ -45,7 +47,7 @@ type Serializable<T> =
   T extends SerializablePrimitive
     ? T
     : // Allow a specific subset of Isaac API classes that are copyable / serializable.
-    T extends SerializableIsaacAPIClass
+    T extends CopyableIsaacAPIClass
     ? T
     : // Disallow all other Isaac API classes.
     T extends IsaacAPIClass
@@ -77,7 +79,7 @@ type SerializableInsideArrayOrMap<T> =
   T extends SerializablePrimitive
     ? T
     : // Allow a specific subset of Isaac API classes that are copyable / serializable.
-    T extends SerializableIsaacAPIClass
+    T extends CopyableIsaacAPIClass
     ? T
     : // Disallow all other Isaac API classes.
     T extends IsaacAPIClass
@@ -125,7 +127,6 @@ type SerializableReadonlyMap<K, V> = ReadonlyMap<
 type SerializableSet<T> = Set<SerializableInsideArrayOrMap<T>>;
 type SerializableReadonlySet<T> = ReadonlySet<SerializableInsideArrayOrMap<T>>;
 type SerializableObject<T> = { [K in keyof T]: Serializable<T[K]> };
-type SerializableIsaacAPIClass = BitSet128 | Color | KColor | RNG | Vector;
 
 // eslint-disable-next-line @typescript-eslint/ban-types
 type HasMethods<T> = {} extends {

package/src/objects/isaacAPIClassTypeToBrand.ts

@@ -1,4 +1,4 @@
-import { CopyableIsaacAPIClassType } from "../enums/private/CopyableIsaacAPIClassType";
+import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 
 export const ISAAC_API_CLASS_TYPE_TO_BRAND: {

package/src/objects/isaacAPIClassTypeToFunctions.ts

@@ -1,72 +1,121 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-import { CopyableIsaacAPIClassType } from "../enums/private/CopyableIsaacAPIClassType";
+import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
 import {
   copyBitSet128,
   deserializeBitSet128,
+  isBitSet128,
   isSerializedBitSet128,
   serializeBitSet128,
+  SerializedBitSet128,
 } from "../functions/bitSet128";
 import {
   copyColor,
   deserializeColor,
+  isColor,
   isSerializedColor,
   serializeColor,
+  SerializedColor,
 } from "../functions/color";
 import {
   copyKColor,
   deserializeKColor,
+  isKColor,
   isSerializedKColor,
+  SerializedKColor,
   serializeKColor,
 } from "../functions/kColor";
 import {
   copyRNG,
   deserializeRNG,
+  isRNG,
   isSerializedRNG,
+  SerializedRNG,
   serializeRNG,
 } from "../functions/rng";
 import {
   copyVector,
   deserializeVector,
   isSerializedVector,
+  isVector,
+  SerializedVector,
   serializeVector,
 } from "../functions/vector";
 
-interface IsaacAPIClassTypeFunctions {
-  isSerialized: (object: unknown) => object is unknown;
-  copy: (object: any) => any;
-  serialize: (object: any) => any;
-  deserialize: (object: any) => any;
+/** A type representing an Isaac API class that can be safely copied or serialized. */
+export type CopyableIsaacAPIClass = BitSet128 | Color | KColor | RNG | Vector;
+
+/**
+ * A type representing an Isaac API class like `Color` or `RNG` that has been written to the
+ * "save#.dat" file. It is used by the save data manager when reading and writing to that file.
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+export type SerializedIsaacAPIClass =
+  | SerializedBitSet128
+  | SerializedColor
+  | SerializedKColor
+  | SerializedRNG
+  | SerializedVector;
+
+export interface IsaacAPIClassTypeToType {
+  [CopyableIsaacAPIClassType.BIT_SET_128]: BitSet128;
+  [CopyableIsaacAPIClassType.COLOR]: Color;
+  [CopyableIsaacAPIClassType.K_COLOR]: KColor;
+  [CopyableIsaacAPIClassType.RNG]: RNG;
+  [CopyableIsaacAPIClassType.VECTOR]: Vector;
+}
+
+export interface IsaacAPIClassTypeToSerializedType {
+  [CopyableIsaacAPIClassType.BIT_SET_128]: SerializedBitSet128;
+  [CopyableIsaacAPIClassType.COLOR]: SerializedColor;
+  [CopyableIsaacAPIClassType.K_COLOR]: SerializedKColor;
+  [CopyableIsaacAPIClassType.RNG]: SerializedRNG;
+  [CopyableIsaacAPIClassType.VECTOR]: SerializedVector;
+}
+
+export interface IsaacAPIClassTypeFunctions<T, SerializedT> {
+  is: (object: unknown) => object is T;
+  isSerialized: (object: unknown) => object is SerializedT;
+  copy: (object: T) => T;
+  serialize: (object: T) => SerializedT;
+  deserialize: (object: SerializedT) => T;
 }
 
 export const ISAAC_API_CLASS_TYPE_TO_FUNCTIONS: {
-  readonly [key in CopyableIsaacAPIClassType]: IsaacAPIClassTypeFunctions;
+  readonly [key in CopyableIsaacAPIClassType]: IsaacAPIClassTypeFunctions<
+    IsaacAPIClassTypeToType[key],
+    IsaacAPIClassTypeToSerializedType[key]
+  >;
 } = {
   [CopyableIsaacAPIClassType.BIT_SET_128]: {
+    is: isBitSet128,
     isSerialized: isSerializedBitSet128,
     copy: copyBitSet128,
     serialize: serializeBitSet128,
     deserialize: deserializeBitSet128,
   },
   [CopyableIsaacAPIClassType.COLOR]: {
+    is: isColor,
     isSerialized: isSerializedColor,
     copy: copyColor,
     serialize: serializeColor,
     deserialize: deserializeColor,
   },
   [CopyableIsaacAPIClassType.K_COLOR]: {
+    is: isKColor,
     isSerialized: isSerializedKColor,
     copy: copyKColor,
     serialize: serializeKColor,
     deserialize: deserializeKColor,
   },
   [CopyableIsaacAPIClassType.RNG]: {
+    is: isRNG,
     isSerialized: isSerializedRNG,
     copy: copyRNG,
     serialize: serializeRNG,
     deserialize: deserializeRNG,
   },
   [CopyableIsaacAPIClassType.VECTOR]: {
+    is: isVector,
     isSerialized: isSerializedVector,
     copy: copyVector,
     serialize: serializeVector,

package/src/types/WeightedArray.ts

@@ -0,0 +1,2 @@
+/** An array where each element is paired with a number indicating that elements 'weight'. */
+export type WeightedArray<T> = Array<[T, float]>;

package/dist/src/enums/private/CopyableIsaacAPIClassType.d.ts

@@ -1,12 +0,0 @@
-/**
- * - This must match the JSDoc comments for `deepCopy` and `merge`.
- * - This must match the `SerializableIsaacAPIClass` type union.
- */
-export declare enum CopyableIsaacAPIClassType {
-    BIT_SET_128 = "BitSet128",
-    COLOR = "Color",
-    K_COLOR = "KColor",
-    RNG = "RNG",
-    VECTOR = "Vector"
-}
-//# sourceMappingURL=CopyableIsaacAPIClassType.d.ts.map

package/dist/src/enums/private/CopyableIsaacAPIClassType.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CopyableIsaacAPIClassType.d.ts","sourceRoot":"","sources":["../../../../src/enums/private/CopyableIsaacAPIClassType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,yBAAyB;IACnC,WAAW,cAAc;IACzB,KAAK,UAAU;IACf,OAAO,WAAW;IAClB,GAAG,QAAQ;IACX,MAAM,WAAW;CAClB"}

package/dist/src/enums/private/CopyableIsaacAPIClassType.lua

@@ -1,10 +0,0 @@
-local ____exports = {}
---- - This must match the JSDoc comments for `deepCopy` and `merge`.
--- - This must match the `SerializableIsaacAPIClass` type union.
-____exports.CopyableIsaacAPIClassType = {}
-____exports.CopyableIsaacAPIClassType.BIT_SET_128 = "BitSet128"
-____exports.CopyableIsaacAPIClassType.COLOR = "Color"
-____exports.CopyableIsaacAPIClassType.K_COLOR = "KColor"
-____exports.CopyableIsaacAPIClassType.RNG = "RNG"
-____exports.CopyableIsaacAPIClassType.VECTOR = "Vector"
-return ____exports

package/dist/src/types/SerializedIsaacAPIClass.d.ts

@@ -1,11 +0,0 @@
-/// <reference types="@typescript-to-lua/language-extensions" />
-/**
- * This is a type representing an Isaac API class like `Color` or `RNG` that has been written to the
- * "save#.dat" file. It is used by the save data manager when reading and writing to that file.
- *
- * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
- */
-export declare type SerializedIsaacAPIClass = LuaMap<string, unknown> & {
-    readonly __serializedIsaacAPIClassBrand: symbol;
-};
-//# sourceMappingURL=SerializedIsaacAPIClass.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"SerializedIsaacAPIClass.d.ts","sourceRoot":"","sources":["../../../src/types/SerializedIsaacAPIClass.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;AACH,oBAAY,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC9D,QAAQ,CAAC,8BAA8B,EAAE,MAAM,CAAC;CACjD,CAAC"}

package/src/enums/private/CopyableIsaacAPIClassType.ts

@@ -1,11 +0,0 @@
-/**
- * - This must match the JSDoc comments for `deepCopy` and `merge`.
- * - This must match the `SerializableIsaacAPIClass` type union.
- */
-export enum CopyableIsaacAPIClassType {
-  BIT_SET_128 = "BitSet128",
-  COLOR = "Color",
-  K_COLOR = "KColor",
-  RNG = "RNG",
-  VECTOR = "Vector",
-}

package/src/types/SerializedIsaacAPIClass.ts

@@ -1,9 +0,0 @@
-/**
- * This is a type representing an Isaac API class like `Color` or `RNG` that has been written to the
- * "save#.dat" file. It is used by the save data manager when reading and writing to that file.
- *
- * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
- */
-export type SerializedIsaacAPIClass = LuaMap<string, unknown> & {
-  readonly __serializedIsaacAPIClassBrand: symbol;
-};