tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
871 lines • 35 kB
text/typescript
export default TinyInventory;
/**
* Represents a registered item definition in the global registry.
*/
export type ItemDef = {
/**
* - Unique identifier for the item.
*/
id: string;
/**
* - Weight of a single unit of the item.
*/
weight: number;
/**
* - Default metadata for the item type.
*/
metadata: InventoryMetadata;
/**
* - Maximum quantity per stack.
*/
maxStack: number;
/**
* - Callback triggered when the item is used.
*/
onUse: OnUseEvent | null;
/**
* - Optional category/type identifier.
*/
type: string | null;
};
/**
* Represents an individual stored item instance in the inventory.
*/
export type InventoryItem = {
/**
* - Unique identifier for the item.
*/
id: string;
/**
* - Metadata specific to this item instance.
*/
metadata: InventoryMetadata;
/**
* - Number of units in this stack.
*/
quantity: number;
};
/**
* A collection of item stacks stored in the inventory.
*/
export type InvSlots = (InventoryItem | null)[];
/**
* Metadata object used to store arbitrary key-value pairs for an item.
*/
export type InventoryMetadata = Record<string | number | symbol, any>;
/**
* Represents a special slot (e.g., equipment) in the inventory.
*/
export type SpecialSlot = {
/**
* - Optional slot category/type.
*/
type: string | null;
/**
* - Item currently equipped in this slot.
*/
item: InventoryItem | null;
};
/**
* Generic event callback triggered by inventory actions.
*/
export type OnEvent = (payload: EventPayload) => void;
/**
* Event fired when an item is added to the inventory.
*/
export type AddItemEvent = OnEvent;
/**
* Event fired when an item is setted to the inventory.
*/
export type SetItemEvent = OnEvent;
/**
* Event fired when an item is removed from the inventory.
*/
export type RemoveItemEvent = OnEvent;
/**
* Event fired when an item is used.
*/
export type UseItemEvent = OnEvent;
/**
* A function executed when an inventory item is used.
* Can be assigned to handle custom "on use" behavior.
*/
export type OnUseEvent = OnEvent;
/**
* Represents the supported event types for inventory actions.
*/
export type EventsType = "add" | "remove" | "use" | "set";
/**
* Callback used to filter items by matching metadata.
*/
export type GetItemsByMetadataCallback = (metadata: InventoryMetadata, item: InventoryItem) => boolean;
/**
* Callback used when searching for an item in an inventory collection.
* Works similarly to `Array.prototype.find()` conditions.
*/
export type FindItemCallback = (value: InventoryItem, index: number, items: InventoryItem[]) => boolean;
/**
* Represents the fully serialized structure of a TinyInventory instance.
* Intended for pure JSON storage and transmission.
*/
export type SerializedInventory = {
/**
* - Schema identifier for validation.
*/
__schema: "TinyInventory";
/**
* - Serialized format version.
*/
version: number;
/**
* - Maximum allowed weight, or null if unlimited.
*/
maxWeight: number | null;
/**
* - Maximum allowed slots, or null if unlimited.
*/
maxSlots: number | null;
/**
* - Maximum allowed size for items, or null if unlimited.
*/
maxSize: number | null;
/**
* - Maximum stack size allowed per item.
*/
maxStack: number;
/**
* - Flat inventory items.
*/
items: (InventoryItem | null)[];
/**
* - Special equipment or reserved slots keyed by ID.
*/
specialSlots: Record<string, SpecialSlot>;
};
/**
* Represents an entry from the inventory as a pair containing the item and its index in the collection.
*/
export type ItemListData = [InventoryItem, number];
/**
* Payload data dispatched when an inventory event occurs (e.g., add, remove, equip, unequip).
*/
export type EventPayload = {
/**
* - Index of the item in its collection (null if not applicable).
*/
index: number | null;
/**
* - The item affected by the event.
*/
item: InventoryItem | null;
/**
* - Whether the item came from a collection (true) or not.
*/
isCollection: boolean;
/**
* - ID of the special slot involved in the event, if any.
*/
specialSlot: string | null;
/**
* - Function to remove the item from its slot, optionally forcing space rules.
*/
remove: (forceSpace: boolean) => void;
};
/**
* Result of adding items to an inventory.
*/
export type AddItemResult = {
/**
* - Quantity of the item that could NOT be added due to space/stack limits.
*/
remaining: number;
/**
* - Array of slot indexes in the inventory where the item was successfully added.
*/
placesAdded: {
index: number;
quantity: number;
}[];
};
/**
* Represents a registered item definition in the global registry.
*
* @typedef {Object} ItemDef
* @property {string} id - Unique identifier for the item.
* @property {number} weight - Weight of a single unit of the item.
* @property {InventoryMetadata} metadata - Default metadata for the item type.
* @property {number} maxStack - Maximum quantity per stack.
* @property {OnUseEvent|null} onUse - Callback triggered when the item is used.
* @property {string|null} type - Optional category/type identifier.
*/
/**
* Represents an individual stored item instance in the inventory.
*
* @typedef {Object} InventoryItem
* @property {string} id - Unique identifier for the item.
* @property {InventoryMetadata} metadata - Metadata specific to this item instance.
* @property {number} quantity - Number of units in this stack.
*/
/**
* A collection of item stacks stored in the inventory.
*
* @typedef {(InventoryItem|null)[]} InvSlots
*/
/**
* Metadata object used to store arbitrary key-value pairs for an item.
*
* @typedef {Record<string|number|symbol, any>} InventoryMetadata
*/
/**
* Represents a special slot (e.g., equipment) in the inventory.
*
* @typedef {Object} SpecialSlot
* @property {string|null} type - Optional slot category/type.
* @property {InventoryItem|null} item - Item currently equipped in this slot.
*/
/**
* Generic event callback triggered by inventory actions.
* @typedef {(payload: EventPayload) => void} OnEvent
*/
/**
* Event fired when an item is added to the inventory.
*
* @typedef {OnEvent} AddItemEvent
*/
/**
* Event fired when an item is setted to the inventory.
*
* @typedef {OnEvent} SetItemEvent
*/
/**
* Event fired when an item is removed from the inventory.
*
* @typedef {OnEvent} RemoveItemEvent
*/
/**
* Event fired when an item is used.
*
* @typedef {OnEvent} UseItemEvent
*/
/**
* A function executed when an inventory item is used.
* Can be assigned to handle custom "on use" behavior.
*
* @typedef {OnEvent} OnUseEvent
* @returns {void} - Does not return a value.
*/
/**
* Represents the supported event types for inventory actions.
* @typedef {'add'|'remove'|'use'|'set'} EventsType
*/
/**
* Callback used to filter items by matching metadata.
*
* @callback GetItemsByMetadataCallback
* @param {InventoryMetadata} metadata - The metadata object to match against.
* @param {InventoryItem} item - The current item being evaluated.
* @returns {boolean} - `true` if the item matches the metadata, otherwise `false`.
*/
/**
* Callback used when searching for an item in an inventory collection.
* Works similarly to `Array.prototype.find()` conditions.
*
* @callback FindItemCallback
* @param {InventoryItem} value - The current inventory item being evaluated.
* @param {number} index - The index of the current item in the array.
* @param {InventoryItem[]} items - The array of all inventory items.
* @returns {boolean} - `true` if the item matches the search criteria, otherwise `false`.
*/
/**
* Represents the fully serialized structure of a TinyInventory instance.
* Intended for pure JSON storage and transmission.
*
* @typedef {Object} SerializedInventory
* @property {'TinyInventory'} __schema - Schema identifier for validation.
* @property {number} version - Serialized format version.
* @property {number|null} maxWeight - Maximum allowed weight, or null if unlimited.
* @property {number|null} maxSlots - Maximum allowed slots, or null if unlimited.
* @property {number|null} maxSize - Maximum allowed size for items, or null if unlimited.
* @property {number} maxStack - Maximum stack size allowed per item.
* @property {(InventoryItem|null)[]} items - Flat inventory items.
* @property {Record<string, SpecialSlot>} specialSlots - Special equipment or reserved slots keyed by ID.
*/
/**
* Represents an entry from the inventory as a pair containing the item and its index in the collection.
* @typedef {[InventoryItem, number]} ItemListData
*/
/**
* Payload data dispatched when an inventory event occurs (e.g., add, remove, equip, unequip).
* @typedef {Object} EventPayload
* @property {number|null} index - Index of the item in its collection (null if not applicable).
* @property {InventoryItem|null} item - The item affected by the event.
* @property {boolean} isCollection - Whether the item came from a collection (true) or not.
* @property {string|null} specialSlot - ID of the special slot involved in the event, if any.
* @property {(forceSpace: boolean) => void} remove - Function to remove the item from its slot, optionally forcing space rules.
*/
/**
* Result of adding items to an inventory.
* @typedef {Object} AddItemResult
* @property {number} remaining - Quantity of the item that could NOT be added due to space/stack limits.
* @property {{ index: number; quantity: number }[]} placesAdded - Array of slot indexes in the inventory where the item was successfully added.
*/
/**
* TinyInventory — A flexible inventory management system.
*
* This class provides:
* - Standard inventory slots with configurable limits on weight, size, and stack.
* - Special slots for equipment, tools, or unique item types.
* - Full CRUD operations for items (add, remove, move, use, equip, unequip).
* - Metadata-aware operations to differentiate items with durability, enchantments, etc.
* - Serialization and deserialization to/from JSON for saving/loading inventory state.
* - Event triggers for 'add', 'remove', 'use', and 'set' actions.
*
* @beta
*/
declare class TinyInventory {
/**
* Registry of all item definitions available in TinyInventory.
* Keys are item IDs, values are configuration objects created with {@link TinyInventory.defineItem}.
* @type {Map<string, ItemDef>}
*/
static "__#private@#ItemRegistry": Map<string, ItemDef>;
/**
* Returns a deep-cloned snapshot of all registered items.
* Ensures the caller cannot mutate the internal registry.
*
* @returns {Record<string, ItemDef>} A map of item IDs to their definitions.
*/
static get itemRegistry(): Record<string, ItemDef>;
/**
* Defines or updates an item type in the global item registry.
* Stores key properties such as weight, stackability rules, and optional behavior callbacks.
*
* @param {Object} config - Item configuration object.
* @param {string} config.id - Unique identifier for the item.
* @param {number} [config.weight=0] - Weight of a single unit of the item.
* @param {InventoryMetadata} [config.metadata={}] - Default metadata for the item type.
* @param {number} [config.maxStack=1] - Maximum quantity allowed in a single stack.
* @param {OnUseEvent|null} [config.onUse=null] - Optional callback executed when the item is used.
* @param {string|null} [config.type=null] - Optional type/category identifier for the item.
* @throws {Error} If `id` is missing or not a string.
*/
static defineItem(config: {
id: string;
weight?: number | undefined;
metadata?: InventoryMetadata | undefined;
maxStack?: number | undefined;
onUse?: OnEvent | null | undefined;
type?: string | null | undefined;
}): void;
/**
* Removes an item definition from the global registry.
*
* @param {string} itemId - Unique identifier of the item to remove.
* @returns {boolean} True if the item was removed, false if it did not exist.
*/
static removeItem(itemId: string): boolean;
/**
* Checks whether an item is registered.
*
* @param {string} itemId - The item ID to check.
* @returns {boolean} True if the item exists in the registry, false otherwise.
*/
static hasItem(itemId: string): boolean;
/**
* Retrieves an item definition from the registry.
*
* @param {string} itemId - The ID of the item to retrieve.
* @returns {ItemDef} The definition of the requested item.
* @throws {Error} If the item is not registered.
*/
static getItem(itemId: string): ItemDef;
/**
* Rebuilds a TinyInventory from a plain object created by {@link TinyInventory.toObject}.
* Item definitions (ItemRegistry) must be already defined externally; this method only restores state.
*
* @param {SerializedInventory} obj - Parsed JSON object.
* @returns {TinyInventory} A new TinyInventory instance populated with the saved state.
* @throws {Error} If validation fails and `validate` is true.
*/
static fromObject(obj: SerializedInventory): TinyInventory;
/**
* Rebuilds a TinyInventory from a JSON string produced by {@link TinyInventory.toJSON}.
* @param {string} json - JSON string.
* @returns {TinyInventory} A new TinyInventory instance.
*/
static fromJSON(json: string): TinyInventory;
/**
* Creates a new TinyInventory instance.
*
* @param {Object} [options={}] - Configuration options for the inventory.
* @param {number|null} [options.maxWeight=null] - Maximum allowed total weight (null for no limit).
* @param {number|null} [options.maxSlots=null] - Maximum number of item slots (null for no limit).
* @param {number|null} [options.maxSize=null] - Maximum number of total item amount (null for no limit).
* @param {number} [options.maxStack=Infinity] - Global maximum stack size (per slot).
* @param {Record<string, { type: string | null; }>} [options.specialSlots] - IDs for special slots (e.g., "helmet", "weapon").
*/
constructor(options?: {
maxWeight?: number | null | undefined;
maxSlots?: number | null | undefined;
maxSize?: number | null | undefined;
maxStack?: number | undefined;
specialSlots?: Record<string, {
type: string | null;
}> | undefined;
});
/**
* Sets the maximum stack size per item.
* @param {number} value - Must be a positive integer.
* @throws {Error} If the value is not a valid positive integer.
*/
set maxStack(value: number);
/**
* Gets the maximum stack size allowed per item.
* @returns {number}
*/
get maxStack(): number;
/**
* Sets the maximum item size.
* @param {number|null} value - Must be a positive integer or null.
* @throws {Error} If the value is not null or a positive integer.
*/
set maxSize(value: number | null);
/**
* Gets the maximum item size allowed.
* @returns {number|null}
*/
get maxSize(): number | null;
/**
* Sets the maximum number of slots.
* @param {number|null} value - Must be a positive integer or null.
* @throws {Error} If the value is not null or a positive integer.
*/
set maxSlots(value: number | null);
/**
* Gets the maximum number of slots allowed.
* @returns {number|null}
*/
get maxSlots(): number | null;
/**
* Sets the maximum inventory weight.
* @param {number|null} value - Must be a positive number or null.
* @throws {Error} If the value is not null or a positive number.
*/
set maxWeight(value: number | null);
/**
* Gets the maximum inventory weight allowed.
* @returns {number|null}
*/
get maxWeight(): number | null;
/**
* Gets the registered inventory event listeners.
* Always returns a clone to prevent external mutation.
* @returns {{ add: AddItemEvent[], remove: RemoveItemEvent[], use: UseItemEvent[], set: SetItemEvent[] }}
*/
get events(): {
add: AddItemEvent[];
remove: RemoveItemEvent[];
use: UseItemEvent[];
set: SetItemEvent[];
};
/**
* Gets the current inventory item slots.
* Always returns a clone to prevent external mutation.
* @returns {InvSlots}
*/
get items(): InvSlots;
/**
* Gets the current special slots.
* Always returns a clone to prevent external mutation.
* @returns {Map<string, SpecialSlot>}
*/
get specialSlots(): Map<string, SpecialSlot>;
/**
* Gets the total quantity of items in the inventory.
* Unlike slot count, this sums up the `quantity` of each item.
*
* @returns {number} - The total number of item units stored in the inventory.
*/
get size(): number;
/**
* Gets the total quantity of used slots in the inventory.
*
* @returns {number} - The total number of used slots stored in the inventory.
*/
get slotsSize(): number;
/**
* Gets the total weight of all items in the inventory.
* @returns {number} The total weight.
*/
get weight(): number;
/**
* Cleans up unnecessary trailing nulls in a collection.
* @private
*/
private _cleanNulls;
/**
* Checks if there is available space based on slot and weight limits.
* @param {Object} [settings={}] - Optional configuration for the space check.
* @param {number} [settings.weight=0] - Extra weight to include in the calculation (e.g., previewing an item addition).
* @param {number} [settings.sizeLength=0] - Extra item count to include in the calculation (e.g., previewing a amount usage).
* @param {number} [settings.slotsLength=0] - Extra item count to include in the calculation (e.g., previewing a slot usage).
* @returns {boolean} True if there is space; false otherwise.
*/
hasSpace({ weight, sizeLength, slotsLength }?: {
weight?: number | undefined;
sizeLength?: number | undefined;
slotsLength?: number | undefined;
}): boolean;
/**
* Checks if the inventory weight exceeds the maximum allowed limit,
* optionally considering an additional weight.
*
* @param {number} [extraWeight=0] - Additional weight to consider in the calculation.
* @returns {boolean} - Returns `true` if the total weight (current + extra) exceeds `maxWeight`, otherwise `false`.
*/
isHeavy(extraWeight?: number): boolean;
/**
* Checks if the inventory amount has reached its maximum capacity.
*
* @param {number} [extraLength=0] - Additional length to consider in the calculation.
* @returns {boolean} - Returns `true` if the total number of items is greater than or equal to `maxSlots`, otherwise `false`.
*/
areFull(extraLength?: number): boolean;
/**
* Checks if the inventory has reached its maximum amount capacity.
*
* @param {number} [extraLength=0] - Additional length to consider in the calculation.
* @returns {boolean} - Returns `true` if the total number of items is greater than or equal to `maxSlots`, otherwise `false`.
*/
isFull(extraLength?: number): boolean;
/**
* Checks if the inventory slots has reached its maximum slot capacity.
*
* @param {number} [extraLength=0] - Additional length to consider in the calculation.
* @returns {boolean} - Returns `true` if the total number of items is greater than or equal to `maxSlots`, otherwise `false`.
*/
areFullSlots(extraLength?: number): boolean;
/**
* Checks if the inventory has reached its maximum slot capacity.
*
* @param {number} [extraLength=0] - Additional length to consider in the calculation.
* @returns {boolean} - Returns `true` if the total number of items is greater than or equal to `maxSlots`, otherwise `false`.
*/
isFullSlots(extraLength?: number): boolean;
/**
* Unregisters a specific callback for the given event type.
* @param {EventsType} eventType - The event type to remove from.
* @param {OnEvent} callback - The callback function to remove.
*/
off(eventType: EventsType, callback: OnEvent): void;
/**
* Unregisters all callbacks for the given event type.
* @param {EventsType} eventType - The event type to clear.
*/
offAll(eventType: EventsType): void;
/**
* Returns a shallow copy of the callbacks for a given event type.
* @param {EventsType} eventType - The event type to clone.
* @returns {OnEvent[]} A cloned array of callback functions.
*/
cloneEventCallbacks(eventType: EventsType): OnEvent[];
/**
* Registers a callback to be executed when an item is added.
* @param {AddItemEvent} callback - Function receiving the event payload.
*/
onAddItem(callback: AddItemEvent): void;
/**
* Registers a callback to be executed when an item is removed.
* @param {SetItemEvent} callback - Function receiving the event payload.
*/
onSetItem(callback: SetItemEvent): void;
/**
* Registers a callback to be executed when an item is removed.
* @param {RemoveItemEvent} callback - Function receiving the event payload.
*/
onRemoveItem(callback: RemoveItemEvent): void;
/**
* Registers a callback to be executed when an item is used.
* @param {UseItemEvent} callback - Function receiving the event payload.
*/
onUseItem(callback: UseItemEvent): void;
/**
* Removes all unnecessary `null` values from the inventory, compacting the slots.
* Preserves the relative order of items and does not modify metadata.
*/
compactInventory(): void;
/**
* Adds an item to the inventory, respecting stackability rules, stack limits, and metadata matching.
* If the item cannot be fully added (e.g., due to stack limits), the remaining quantity is returned.
*
* @param {Object} options - Item addition configuration.
* @param {string} options.itemId - ID of the item to add.
* @param {boolean} [options.forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @param {number} [options.quantity=1] - Quantity to add.
* @param {InventoryMetadata} [options.metadata={}] - Instance-specific metadata (must match for stacking).
* @returns {AddItemResult} Quantity that could not be added (0 if all were added).
* @throws {Error} If the item is not registered.
*/
addItem({ itemId, quantity, metadata, forceSpace }: {
itemId: string;
forceSpace?: boolean | undefined;
quantity?: number | undefined;
metadata?: InventoryMetadata | undefined;
}): AddItemResult;
/**
* Gets the item stored at a specific slot.
* @param {number} slotIndex - The slot index.
* @returns {InventoryItem|null} The item object or null if empty.
* @throws {Error} If the slot index is out of bounds.
*/
getItemFrom(slotIndex: number): InventoryItem | null;
/**
* Sets an item at a specific slot index, replacing whatever was there.
* Can also be used to place `null` in the slot to clear it.
*
* @param {Object} options - Item addition configuration.
* @param {number} options.slotIndex - Index of the slot to set.
* @param {InventoryItem|null} options.item - Item to place in the slot, or null to clear.
* @param {boolean} [options.forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @throws {Error} If the index is out of range, or item type is invalid.
*/
setItem({ slotIndex, item, forceSpace }: {
slotIndex: number;
item: InventoryItem | null;
forceSpace?: boolean | undefined;
}): void;
/**
* Deletes an item from a specific slot by setting it to null.
*
* @param {number} slotIndex - Index of the slot to delete from.
* @param {boolean} [forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
*/
deleteItem(slotIndex: number, forceSpace?: boolean): void;
/**
* Moves an item from one slot to another.
*
* @param {number} fromIndex - Source slot index.
* @param {number} toIndex - Target slot index.
* @param {boolean} [forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @throws {Error} If the source slot is empty or the move is invalid.
*/
moveItem(fromIndex: number, toIndex: number, forceSpace?: boolean): void;
/**
* Removes a given quantity of an item from the inventory, including special slots.
* @param {Object} settings - Removal configuration.
* @param {string} settings.itemId - ID of the item to remove.
* @param {InventoryMetadata|null} [settings.metadata={}] - Metadata to match when removing (e.g., durability, enchantments).
* @param {number} [settings.quantity=1] - Quantity to remove.
* @returns {boolean} True if fully removed; false if insufficient quantity.
*/
removeItem({ itemId, metadata, quantity }: {
itemId: string;
metadata?: InventoryMetadata | null | undefined;
quantity?: number | undefined;
}): boolean;
/**
* Uses an item from a specific slot, or special slot,
* triggering its `onUse` callback if defined.
* Automatically removes the item if `remove()` is called inside the callback.
*
* @param {Object} location - Item location data.
* @param {number} [location.slotIndex] - Index in inventory.
* @param {string} [location.specialSlot] - Name of the special slot (if applicable).
* @param {boolean} [location.forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @param {...any} args - Additional arguments passed to the `onUse` handler.
* @returns {any} - The return value of the `onUse` callback, or `null` if no callback exists.
* @throws {Error} - If the item is not found in the specified location.
*/
useItem({ slotIndex, specialSlot, forceSpace }: {
slotIndex?: number | undefined;
specialSlot?: string | undefined;
forceSpace?: boolean | undefined;
}, ...args: any[]): any;
/**
* Checks if a special slot with the given ID exists in the inventory.
* @param {string} slotId - ID of the special slot.
* @returns {boolean} True if the slot exists, otherwise false.
*/
hasSpecialSlot(slotId: string): boolean;
/**
* Gets the item stored in a special slot.
* @param {string} slotId - The special slot ID.
* @returns {InventoryItem|null} The item object or null if empty.
* @throws {Error} If the special slot does not exist.
*/
getSpecialItem(slotId: string): InventoryItem | null;
/**
* Gets the type of a special slot.
* @param {string} slotId - The special slot ID.
* @returns {string|null} The slot type, or null if no type restriction.
* @throws {Error} If the special slot does not exist.
*/
getSpecialSlotType(slotId: string): string | null;
/**
* Sets or clears an item in a special slot.
*
* @param {Object} options - Item addition configuration.
* @param {string} options.slotId - Name of the special slot.
* @param {InventoryItem|null} options.item - Item to place, or null to clear.
* @param {boolean} [options.forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @throws {Error} If the slot does not exist, or item is invalid.
*/
setSpecialSlot({ slotId, item, forceSpace }: {
slotId: string;
item: InventoryItem | null;
forceSpace?: boolean | undefined;
}): void;
/**
* Deletes an item from a specific special slot by setting it to null.
*
* @param {string} slotId - Special slot to delete from.
* @param {boolean} [forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
*/
deleteSpecialItem(slotId: string, forceSpace?: boolean): void;
/**
* Equips an item from the inventory into a special slot.
*
* Behavior:
* 1. If the same item is already equipped and stackable, it will merge quantities up to `maxStack`.
* Any leftover remains in the original inventory slot.
* 2. If another item is equipped (different ID or non-stackable), the current one is moved back to inventory
* and the new item is equipped (up to its stack limit). Any leftover stays in the inventory.
*
* @param {Object} configs - Configuration object for equipping the item.
* @param {string} configs.slotId - ID of the special slot where the item will be equipped.
* @param {number} configs.slotIndex - Index of the inventory slot containing the item to equip.
* @param {number} [configs.quantity=1] - Quantity of the item to equip.
* @param {boolean} [configs.forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @returns {number} Amount of the item that could NOT be equipped (leftover remains in inventory).
* @throws {Error} If the special slot does not exist, if the item type mismatches the slot,
* or if the inventory lacks the required quantity.
*/
equipItem({ slotId, slotIndex, quantity, forceSpace }: {
slotId: string;
slotIndex: number;
quantity?: number | undefined;
forceSpace?: boolean | undefined;
}): number;
/**
* Unequips a specific quantity of an item from a special slot
* and returns it to the inventory.
*
* If no quantity is specified, removes the entire stack.
*
* @param {Object} config - Item location data.
* @param {string} config.slotId - ID of the special slot.
* @param {number|null} [config.quantity=null] - Quantity to unequip (default: all).
* @param {boolean} [config.forceSpace=false] - Forces the item to be added even if space or stack limits would normally prevent it.
* @returns {boolean} True if any item was unequipped; false if slot empty.
* @throws {Error} If the slot does not exist or invalid quantity.
*/
unequipItem({ slotId, quantity, forceSpace }: {
slotId: string;
quantity?: number | null | undefined;
forceSpace?: boolean | undefined;
}): boolean;
/**
* Returns all items from the inventory with their respective indexes.
* @returns {ItemListData[]} An array where each entry is `[InventoryItem, index]`.
*/
getItemList(): ItemListData[];
/**
* Returns all items currently stored in the inventory,
* excluding null or undefined entries.
* @returns {InventoryItem[]} Array of item objects.
*/
getAllItems(): InventoryItem[];
/**
* Finds all items matching a given metadata filter function.
* @param {GetItemsByMetadataCallback} filterFn - Function receiving (itemTypeMetadata, itemInstance).
* @returns {InventoryItem[]} Array of matching items.
*/
getItemsByMetadata(filterFn: GetItemsByMetadataCallback): InventoryItem[];
/**
* Finds the first item matching the given predicate.
* @param {FindItemCallback} predicate - Function receiving the item instance.
* @returns {InventoryItem|undefined} The first matching item, or undefined if none match.
*/
findItem(predicate: FindItemCallback): InventoryItem | undefined;
/**
* Finds all items matching the given predicate.
* @param {FindItemCallback} predicate - Function receiving the item instance.
* @returns {InventoryItem[]} Array of matching items.
*/
findItems(predicate: FindItemCallback): InventoryItem[];
/**
* Counts the total quantity of a given item in the inventory.
* @param {string} itemId - Item ID to count.
* @returns {number} Total quantity of that item.
*/
getItemCount(itemId: string): number;
/**
* Checks whether the inventory contains at least the given quantity of an item.
* @param {string} itemId - Item ID to check.
* @param {number} [quantity=1] - Quantity to check.
* @returns {boolean} True if the inventory has the quantity or more.
*/
hasItem(itemId: string, quantity?: number): boolean;
/**
* Checks if there is an item stored at the given slot index.
*
* @param {number} slotIndex - The inventory slot to check.
* @returns {boolean} True if the slot contains an item, otherwise false.
*/
existsItemAt(slotIndex: number): boolean;
/**
* Clears all items and event listeners from the inventory.
* Resets the inventory state but preserves max limits and slot definitions.
*
* @returns {void}
*/
clear(): void;
/**
* Removes all registered event listeners from the inventory.
*
* @returns {void}
*/
clearAllEvents(): void;
/**
* Clears all items in normal and special slots and triggers remove events.
*
* @returns {void}
*/
clearAllItems(): void;
/**
* Clears all items in the normal inventory slots and triggers remove events.
*
* @returns {void}
*/
clearItems(): void;
/**
* Clears all items in special slots and triggers remove events.
*
* @returns {void}
*/
clearSpecialItems(): void;
/**
* Creates a deep copy of this inventory.
*
* The cloned inventory will contain the same items, slots, and metadata,
* but will be a fully independent instance. Any changes to the clone will
* not affect the original inventory and vice versa.
*
* @returns {TinyInventory} A new TinyInventory instance identical to this one.
*/
clone(): TinyInventory;
/**
* Creates a plain JSON-safe object representing the current inventory state.
* Functions (e.g., onUse) are NOT serialized; only instance state is saved.
* @returns {SerializedInventory} A plain object safe to JSON.stringify.
*/
toObject(): SerializedInventory;
/**
* Serializes the inventory to a JSON string.
* @param {number} [space=0] - Pretty-print indentation (e.g., 2).
* @returns {string} JSON string.
*/
toJSON(space?: number): string;
#private;
}
//# sourceMappingURL=TinyInventory.d.mts.map