isaacscript-common 21.4.1 → 21.5.1

package/dist/{index.d.ts → index.rollup.d.ts}

@@ -1543,7 +1543,7 @@ export declare function countSetBits(n: int): int;
  */
 declare abstract class CustomCallback<T extends ModCallbackCustom> extends Feature {
     private subscriptions;
-    addSubscriber(callbackFunc: AddCallbackParametersCustom[T][0], ...optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>): void;
+    addSubscriber(priority: CallbackPriority | int, callbackFunc: AddCallbackParametersCustom[T][0], ...optionalArgs: AllButFirst<AddCallbackParametersCustom[T]>): void;
     /**
      * If the submitted function does not match any of the existing subscriptions, this method will do
      * nothing.
@@ -11652,7 +11652,7 @@ export declare class ModFeature {
      * argument of the constructor.
      */
     initialized: boolean;
-    constructor(mod: ModUpgradedBase, init?: boolean);
+    constructor(mod: ModUpgraded, init?: boolean);
     /**
      * Runs the `Mod.AddCallback` and `ModUpgraded.AddCallbackCustom` methods for all of the decorated
      * callbacks.
@@ -11676,22 +11676,11 @@ export declare class ModFeature {
  *
  * To upgrade your mod, use the `upgradeMod` helper function.
  *
- * 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.
- */
-declare type ModUpgraded<T extends readonly ISCFeature[] = []> = ModUpgradedBase & ISCFeaturesToKeys<T>;
-
-/**
- * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
- * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
- * extends the base class and adds a new method of `AddCallbackCustom`.
- *
- * To upgrade your mod, use the `upgradeMod` helper function.
- *
- * `ModUpgradedBase` provides the core functionality of the `ModUpgraded` class. (It does not
- * include the methods for the individual ISC features.)
+ * By specifying one or more optional features when upgrading your mod, you will get a version of
+ * `ModUpgraded` that has extra methods corresponding to the features that were specified. (This
+ * corresponds to the internal-type `ModUpgradedWithFeatures` type, which extends `ModUpgraded`.)
  */
-export declare class ModUpgradedBase implements Mod {
+export declare class ModUpgraded implements Mod {
     Name: string;
     /** We store a copy of the original mod object so that we can re-implement its functions. */
     private mod;
@@ -11700,42 +11689,34 @@ export declare class ModUpgradedBase implements Mod {
     private callbacks;
     private features;
     constructor(mod: Mod, debug: boolean, timeThreshold?: float);
-    /**
-     * Registers a function to be executed when an in-game event happens. For example, the
-     * `ModCallback.POST_UPDATE` event corresponds to being executed once at the end of every game
-     * logic frame.
-     */
     AddCallback<T extends ModCallback | string>(modCallback: T, ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]): void;
     AddPriorityCallback<T extends ModCallback | string>(modCallback: T, priority: CallbackPriority | int, ...args: T extends ModCallback ? AddCallbackParameters[T] : unknown[]): void;
-    /** Returns whether or not a corresponding "save#.dat" file exists for the current mod. */
     HasData(): boolean;
-    /**
-     * Returns a string containing all of the data inside of the corresponding "save#.dat" file for
-     * this mod.
-     */
     LoadData(): string;
-    /**
-     * Unregisters a function that was previously registered with the `AddCallback` method.
-     *
-     * This method does not care about the tertiary argument. In other words, regardless of the
-     * conditions of how you registered the callback, it will be removed.
-     */
     RemoveCallback<T extends ModCallback>(modCallback: T, callback: AddCallbackParameters[T][0]): void;
-    /** Deletes the corresponding "save#.dat" file for this mod, if it exists. */
     RemoveData(): void;
-    /**
-     * Creates or updates the corresponding "save#.dat" file for this mod with the provided string.
-     */
     SaveData(data: string): void;
     /**
-     * Registers a function to be executed when an in-game event happens. This method is specifically
-     * for events that are provided by the IsaacScript standard library. For example, the
-     * `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb explodes.
+     * Registers a function to be executed when an in-game event happens.
+     *
+     * This method is specifically for events that are provided by the IsaacScript standard library.
+     * For example, the `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb
+     * explodes.
      */
     AddCallbackCustom<T extends ModCallbackCustom>(modCallbackCustom: T, ...args: AddCallbackParametersCustom[T]): void;
+    /**
+     * The same as the `ModUpgraded.AddCallbackCustom` method, but allows setting a custom priority.
+     * By default, callbacks are added with a priority of 0, so this allows you to add early or late
+     * callbacks as necessary. See the `CallbackPriority` enum.
+     */
+    AddPriorityCallbackCustom<T extends ModCallbackCustom>(modCallbackCustom: T, priority: CallbackPriority | int, ...args: AddCallbackParametersCustom[T]): void;
     /**
      * Unregisters a function that was previously registered with the `AddCallbackCustom` method.
      *
+     * This method is specifically for events that are provided by the IsaacScript standard library.
+     * For example, the `ModCallbackCustom.POST_BOMB_EXPLODE` event corresponds to when a bomb
+     * explodes.
+     *
      * This method does not care about the tertiary argument. In other words, regardless of the
      * conditions of how you registered the callback, it will be removed.
      */
@@ -11763,13 +11744,24 @@ export declare class ModUpgradedBase implements Mod {
      * don't have access to it.
      */
     private initOptionalFeature;
-    /**
-     * This is mostly the same as the `AddCustomCallback` method, but we initialize the custom
-     * callback without actually registering a subscription.
-     */
-    private initCustomCallbackEarly;
 }
 
+/**
+ * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
+ * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
+ * extends the base class and adds a new method of `AddCallbackCustom`.
+ *
+ * To upgrade your mod, use the `upgradeMod` helper function.
+ *
+ * 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).
+ */
+declare type ModUpgradedWithFeatures<T extends readonly ISCFeature[] = []> = ModUpgraded & ISCFeaturesToKeys<T>;
+
 export declare const MOVEMENT_ACTIONS_SET: ReadonlySet<ButtonAction>;
 
 /**
@@ -14527,6 +14519,45 @@ export declare function smeltTrinkets(player: EntityPlayer, ...trinketTypes: Tri
  */
 export declare function some<T>(array: T[], func: (value: T, index: number, array: T[]) => boolean): boolean;
 
+/**
+ * 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 declare function sortObjectArrayByKey(key: string): (a: unknown, b: unknown) => -1 | 0 | 1;
+
+/**
+ * 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 declare function sortTwoDimensionalArray<T>(a: T[], b: T[]): -1 | 0 | 1;
+
 export declare type SoulHeartType = HeartSubType.SOUL | HeartSubType.BLACK | HeartSubType.BONE;
 
 /**
@@ -15353,21 +15384,6 @@ infer F,
 /** Helper type to convert a tuple to a union. */
 export declare type TupleToUnion<T extends unknown[]> = T[number];
 
-/**
- * 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 declare function twoDimensionalSort<T>(array1: T[], array2: T[]): -1 | 0 | 1;
-
 /**
  * This is the number of draw coordinates that each heart spans on the UI in the upper left hand
  * corner.
@@ -15397,22 +15413,15 @@ export declare type UnionToIntersection<U> = (U extends U ? (u: U) => 0 : never)
  * @param modVanilla The mod object returned by the `RegisterMod` function.
  * @param features Optional. An array containing the optional standard library features that you
  *                 want to enable, if any. Default is an empty array.
- * @param customCallbacksUsed Optional. An array containing the custom callbacks that you will be
- *                            subscribing to after you upgrade your mod. Specifying this will
- *                            immediately initialize the callbacks (as opposed to lazy-initializing
- *                            them when you first subscribe to the callback). This is only necessary
- *                            if you the order of callback firing is important for your mod. (For
- *                            example, you may want the `POST_NEW_ROOM` part of the
- *                            `POST_GRID_ENTITY_INIT` callback to fire before your own
- *                            `POST_NEW_ROOM` callbacks.)
  * @param debug Optional. Whether to log additional output when a callback is fired. Default is
  *              false.
  * @param timeThreshold Optional. If provided, will only log callbacks that take longer than the
  *                      specified number of seconds (if the "--luadebug" launch flag is turned on)
  *                      or milliseconds (if the "--luadebug" launch flag is turned off).
  * @returns The upgraded mod object.
+ * @beta A dummy field used to hide this function from `api-extractor`.
  */
-export declare function upgradeMod<T extends readonly ISCFeature[] = never[]>(modVanilla: Mod, features?: ISCFeatureTuple<T>, customCallbacksUsed?: ModCallbackCustom[] | readonly ModCallbackCustom[], debug?: boolean, timeThreshold?: float): ModUpgraded<T>;
+export declare function upgradeMod<T extends readonly ISCFeature[] = never[]>(modVanilla: Mod, features?: ISCFeatureTuple<T>, debug?: boolean, timeThreshold?: float): ModUpgradedWithFeatures<T>;
 
 /** Helper type to match all of the uppercase keys of an object. */
 export declare type UppercaseKeys<T> = StartsWithUppercase<keyof T>;