isaacscript-common 10.0.0 → 10.1.0

package/src/functions/table.ts

@@ -1,4 +1,4 @@
-import { isBoolean, isNumber, isString, isTable } from "./types";
+import { isBoolean, isNumber, isString, isUserdata } from "./types";
 
 /**
  * In a `Map`, you can use the `clear` method to delete every element. However, in a `LuaMap`, the
@@ -10,13 +10,13 @@ export function clearTable(luaMap: LuaMap<AnyNotNil, unknown>): void {
   }
 }
 
-/** Helper function to copy specific values from a object to a table. */
-export function copyValuesToTable(
+/** Helper function to copy specific values from a userdata object (e.g. `Vector`) to a table. */
+export function copyUserdataValuesToTable(
   object: unknown,
   keys: string[],
   luaMap: LuaMap<string, unknown>,
 ): void {
-  if (!isTable(object)) {
+  if (!isUserdata(object)) {
     error(
       `Failed to copy an object values to a table, since the object was of type: ${type(
         object,
@@ -24,8 +24,11 @@ export function copyValuesToTable(
     );
   }
 
+  // We can access values on userdata objects similar to a normal table.
+  const userdata = object as unknown as LuaMap<AnyNotNil, unknown>;
+
   for (const key of keys) {
-    const value = object.get(key);
+    const value = userdata.get(key);
     luaMap.set(key, value);
   }
 }

package/src/functions/vector.ts

@@ -1,14 +1,22 @@
-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";
 import { getRandomFloat } from "./random";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
-import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
+import {
+  copyUserdataValuesToTable,
+  getNumbersFromTable,
+  tableHasKeys,
+} from "./table";
 import { isTable } from "./types";
 
 export type SerializedVector = LuaMap<string, unknown> & {
   readonly __serializedVectorBrand: symbol;
+  readonly __kind: CopyableIsaacAPIClassType.VECTOR;
 };
 
 const OBJECT_NAME = "Vector";
@@ -104,7 +112,7 @@ export function serializeVector(vector: Vector): SerializedVector {
   }
 
   const vectorTable = new LuaMap<string, unknown>();
-  copyValuesToTable(vector, KEYS, vectorTable);
+  copyUserdataValuesToTable(vector, KEYS, vectorTable);
   vectorTable.set(SerializationBrand.VECTOR, "");
   return vectorTable as SerializedVector;
 }

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;
-};