isaacscript-common/dist/functions/merge.d.ts

Helper functions and features for IsaacScript mods.

import type { AnyClass } from "../types/AnyClass";
/**
 * `merge` takes the values from a new table and recursively merges them into an old object (while
 * performing appropriate deserialization).
 *
 * This function is used to merge incoming data from the "save#.dat" file into a mod's variables.
 * Merging is useful instead of blowing away a table entirely because mod code often relies on the
 * local table/object references.
 *
 * This function always assumes that the new table is serialized data and will attempt to perform
 * deserialization on the objects within. In other words, unlike the `deepCopy` function, the
 * `merge` function will always operates in the mode of `SerializationType.DESERIALIZE`. For the
 * types of objects that will be deserialized, see the documentation for the `deepCopy` function.
 *
 * This function does not iterate over the old object, like you would naively expect. This is
 * because it is common for a variable to have a type of `something | null`. If this is the case,
 * the key would not appear when iterating over the old object (because a value of null transpiles
 * to nil, which means the table key does not exist). Thus, we must instead iterate over the new
 * object and copy the values backwards. The consequence of this is that `merge` can copy over old
 * variables that are no longer used in the code, or copy over old variables of a different type,
 * which can cause run-time errors. In such cases, users will have to manually delete their save
 * data.
 *
 * @param oldObject The old object to merge the values into. This can be either a Lua table, a TSTL
 *                  map, or a TSTL set.
 * @param newTable The new table to merge the values from. This must be a Lua table that represents
 *                 serialized data. In other words, it should be created with the `deepCopy`
 *                 function using `SerializationType.SERIALIZE`.
 * @param traversalDescription Used to track the current key that we are operating on for debugging
 *                             purposes. Use a name that corresponds to the name of the merging
 *                             table.
 * @param classConstructors Optional. A Lua table that maps the name of a user-defined TSTL class to
 *                          its corresponding constructor. If the `deepCopy` function finds any
 *                          user-defined TSTL classes when recursively iterating through the given
 *                          object, it will use this map to instantiate a new class. Default is an
 *                          empty Lua table.
 */
export declare function merge(oldObject: Readonly<LuaMap<AnyNotNil, unknown>> | ReadonlyMap<AnyNotNil, unknown> | ReadonlySet<AnyNotNil>, newTable: LuaMap<AnyNotNil, unknown>, traversalDescription: string, classConstructors?: LuaMap<string, AnyClass>): void;
//# sourceMappingURL=merge.d.ts.map