@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/Allocation_Optimization/density_groups/Density_Group_Stock.js

@@ -0,0 +1,49 @@
+/**
+ * Finds the density group index that contains the given item id.
+ * @param {Map<number, Set<string>>} groups - Group index to item id set.
+ * @param {number} group_count - Total number of groups.
+ * @param {string} item_id - Item identifier.
+ * @returns {number|null}
+ */
+function find_group_index_for_item_id(groups, group_count, item_id)
+{
+    for (let group_index = 0; group_index < group_count; group_index++)
+    {
+        const group_ids = groups.get(group_index)
+        if (group_ids && group_ids.has(item_id))
+        {
+            return group_index
+        }
+    }
+
+    return null
+}
+
+/**
+ * Returns density group indices that still have at least one item with stock.
+ * @param {Map<number, Set<string>>} groups - Group index to item id set.
+ * @param {number} group_count - Total number of groups.
+ * @param {object[]} item_list - Master item list.
+ * @returns {number[]}
+ */
+function get_groups_with_stock(groups, group_count, item_list)
+{
+    const groups_with_stock = []
+
+    for (let group_index = 0; group_index < group_count; group_index++)
+    {
+        const group_ids = groups.get(group_index)
+        const has_stock = item_list.some(
+            item => group_ids.has(item.get_id()) && item.get_amount() > 0
+        )
+
+        if (has_stock)
+        {
+            groups_with_stock.push(group_index)
+        }
+    }
+
+    return groups_with_stock
+}
+
+module.exports = { find_group_index_for_item_id, get_groups_with_stock }

package/src/Allocation_Optimization/density_groups/Density_Groups_Strategy.js

@@ -0,0 +1,26 @@
+const DENSITY_GROUPS_STRATEGY = Object.freeze({
+    ROUND_ROBIN: 'round_robin',
+    ADAPTIVE: 'adaptive',
+})
+
+const VALID_DENSITY_GROUP_STRATEGIES = Object.freeze(Object.values(DENSITY_GROUPS_STRATEGY))
+
+/**
+ * Maps raw config input to a density group strategy constant.
+ * @param {unknown} raw - Raw strategy value from cargo profile config.
+ * @returns {typeof DENSITY_GROUPS_STRATEGY.ROUND_ROBIN | typeof DENSITY_GROUPS_STRATEGY.ADAPTIVE}
+ */
+function normalize_density_groups_strategy(raw)
+{
+    if (raw === DENSITY_GROUPS_STRATEGY.ADAPTIVE)
+    {
+        return DENSITY_GROUPS_STRATEGY.ADAPTIVE
+    }
+    return DENSITY_GROUPS_STRATEGY.ROUND_ROBIN
+}
+
+module.exports = {
+    DENSITY_GROUPS_STRATEGY,
+    VALID_DENSITY_GROUP_STRATEGIES,
+    normalize_density_groups_strategy,
+}

package/src/Allocation_Optimization/density_groups/Item_Density_Calculator.js

@@ -0,0 +1,20 @@
+/**
+ * Computes item density (weight / volume) for SKU-level grouping.
+ * @param {object} item - Item with get_weight, get_width, get_height, get_length, get_id.
+ * @returns {{ item_id: string, density: number }}
+ */
+function calculate_item_density(item)
+{
+    const weight = item.get_weight()
+    const volume = item.get_width() * item.get_height() * item.get_length()
+    const item_id = item.get_id()
+
+    if (!Number.isFinite(weight) || weight < 0 || volume <= 0)
+    {
+        return { item_id, density: Number.POSITIVE_INFINITY }
+    }
+
+    return { item_id, density: weight / volume }
+}
+
+module.exports = { calculate_item_density }

package/src/Allocation_Optimization/density_groups/Lock_Weight_Ahead_Release.js

@@ -0,0 +1,75 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const { DENSITY_GROUPS_STRATEGY } = require('./Density_Groups_Strategy')
+const { get_weight_ahead_threshold } = require('./Adaptive_Density_Group_Threshold_Resolver')
+const { get_weight_utilization, get_space_utilization } = require('./Container_Utilization')
+
+/**
+ * Returns whether the continuation lock should release so adaptive density groups can expose lighter SKUs.
+ * @param {object} container - Current container.
+ * @param {object} density_scheduler - Density group scheduler.
+ * @param {object[]} item_list - Master item list.
+ * @param {object} locked_item - Locked item instance.
+ * @returns {boolean}
+ */
+function should_release_lock_for_weight_ahead(container, density_scheduler, item_list, locked_item)
+{
+    const gap = get_weight_utilization(container) - get_space_utilization(container)
+    if (gap <= get_weight_ahead_threshold())
+    {
+        return false
+    }
+
+    const groups_with_stock = density_scheduler.get_groups_with_stock(item_list)
+    if (groups_with_stock.length === 0)
+    {
+        return false
+    }
+
+    const lowest_density_group = Math.min(...groups_with_stock)
+    const locked_group = density_scheduler.find_group_index_for_item_id(locked_item.get_id())
+    if (locked_group === null)
+    {
+        return false
+    }
+
+    return locked_group > lowest_density_group
+}
+
+/**
+ * Releases the lock when weight is ahead and the locked SKU is not in the lightest density band.
+ * @param {object} container - Current container.
+ * @param {object|null} density_scheduler - Density group scheduler, if enabled.
+ * @param {object} item_lock - Item continuation lock instance.
+ * @param {object[]} item_list - Master item list.
+ * @param {object|null} locked_item - Currently locked item, if any.
+ * @returns {object|null} Locked item after optional release.
+ */
+function apply_weight_ahead_lock_release(container, density_scheduler, item_lock, item_list, locked_item)
+{
+    if (!locked_item || !density_scheduler)
+    {
+        return locked_item
+    }
+
+    if (Cargo_Profile.density_groups_strategy() !== DENSITY_GROUPS_STRATEGY.ADAPTIVE)
+    {
+        return locked_item
+    }
+
+    const should_release = should_release_lock_for_weight_ahead(
+        container,
+        density_scheduler,
+        item_list,
+        locked_item
+    )
+
+    if (!should_release)
+    {
+        return locked_item
+    }
+
+    item_lock.release_for_density_balance()
+    return null
+}
+
+module.exports = { apply_weight_ahead_lock_release }

package/src/Allocation_Optimization/exceptions/Invalid_Item_Amount_Exception.js

@@ -0,0 +1,17 @@
+const { build_message_entry } = require('../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+class Invalid_Item_Amount_Exception extends Error
+{
+    /**
+     * @param {string|number} item
+     */
+    constructor(item)
+    {
+        const message_key = ALLOCATOR_MESSAGE.INVALID_ITEM_AMOUNT
+        super(message_key)
+        this.message_entry = build_message_entry(message_key, [String(item)])
+    }
+}
+
+module.exports = Invalid_Item_Amount_Exception

package/src/Allocation_Optimization/exceptions/No_Valid_Allocation_Exception.js

@@ -0,0 +1,14 @@
+const { build_message_entry } = require('../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+class No_Valid_Allocation_Exception extends Error
+{
+    constructor()
+    {
+        const message_key = ALLOCATOR_MESSAGE.NO_VALID_ALLOCATION
+        super(message_key)
+        this.message_entry = build_message_entry(message_key)
+    }
+}
+
+module.exports = No_Valid_Allocation_Exception

package/src/Allocation_Optimization/exceptions/Optimization_Infeasible_Exception.js

@@ -0,0 +1,14 @@
+const { build_message_entry } = require('../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+class Optimization_Infeasible_Exception extends Error
+{
+    constructor()
+    {
+        const message_key = ALLOCATOR_MESSAGE.OPTIMIZATION_INFEASIBLE
+        super(message_key)
+        this.message_entry = build_message_entry(message_key)
+    }
+}
+
+module.exports = Optimization_Infeasible_Exception

package/src/Allocation_Optimization/functions/Measure_Reader.js

@@ -0,0 +1,20 @@
+const Cargo_Profile       = require('../../models/Cargo_Profile')
+const measure_to_optimize = require('./measure_to_optimize')
+
+function read_measure_to_be_optimized()
+{
+    const config = Cargo_Profile.measure_to_optimize()
+    switch (config.toLowerCase())
+    {
+        case measure_to_optimize.LENGTH:
+            return measure_to_optimize.LENGTH
+        case measure_to_optimize.WIDTH:
+            return measure_to_optimize.WIDTH
+        default:
+            return measure_to_optimize.WIDTH
+    }
+}
+
+module.exports = {
+    read_measure_to_be_optimized
+}

package/src/Allocation_Optimization/functions/Weight_Getter/Measure_Cobination_Mode.js

@@ -0,0 +1,25 @@
+
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const { mode_checks } = require('./Measure_Combination_Mode_Checkers')
+
+/*
+ * Determines the computation mode based on the block variable weight configuration.
+ * @returns {string} The computation mode.
+ */
+function get_mode()
+{
+    const config = Cargo_Profile.block_variable_weight_config()
+
+    const default_value = 'volume'
+
+    if (!config || config.length <= 1)
+    {
+        return default_value
+    }
+
+    const found = mode_checks.find(item => item.check(config))
+
+    return found ? found.mode : default_value
+}
+
+module.exports = get_mode

package/src/Allocation_Optimization/functions/Weight_Getter/Measure_Cobination_Strategies.js

@@ -0,0 +1,8 @@
+const strategies = {
+    volume: block => block.get_volume(),
+    height_length: block => block.get_length() * block.get_height(),
+    length_width: block => block.get_length() * block.get_width(),
+    height_width: block => block.get_height() * block.get_width(),
+}
+
+module.exports = strategies

package/src/Allocation_Optimization/functions/Weight_Getter/Measure_Combination_Mode_Checkers.js

@@ -0,0 +1,70 @@
+const { DIMENSIONS } = require('./constants')
+const { includes_key_or_translation } = require('./Translation')
+
+/**
+ * Checks if a configuration array contains all the given keys, considering translations.
+ * @param {string[]} config - The configuration array from Cargo Profile.
+ * @param  {...string} keys - The dimension keys to check for.
+ * @returns {boolean}
+ */
+const has = (config, ...keys) => keys.every( key => includes_key_or_translation(config, key) )
+
+const { HEIGHT, LENGTH, WIDTH } = DIMENSIONS
+
+/**
+ * @constant {object} volume_check
+ * @property {function(string[]): boolean} check - Function to check if the config includes HEIGHT, LENGTH, and WIDTH.
+ * @property {string} mode - The mode name for volume.
+ * @augments ModeCheck
+ */
+const volume_check = {
+    check: config => has(config, HEIGHT, LENGTH, WIDTH),
+    mode: 'volume',
+}
+
+/**
+ * @constant {object} height_length_check
+ * @property {function(string[]): boolean} check - Function to check if the config includes HEIGHT and LENGTH, but not WIDTH.
+ * @property {string} mode - The mode name for height and length.
+ * @augments ModeCheck
+ */
+const height_length_check = {
+    check: config => has(config, HEIGHT, LENGTH) && !has(config, WIDTH),
+    mode: 'height_length',
+}
+
+/**
+ * @constant {object} length_width_check
+ * @property {function(string[]): boolean} check - Function to check if the config includes LENGTH and WIDTH, but not HEIGHT.
+ * @property {string} mode - The mode name for length and width.
+ * @augments ModeCheck
+ */
+const length_width_check = {
+    check: config => has(config, LENGTH, WIDTH) && !has(config, HEIGHT),
+    mode: 'length_width',
+}
+
+/**
+ * @constant {object} height_width_check
+ * @property {function(string[]): boolean} check - Function to check if the config includes HEIGHT and WIDTH, but not LENGTH.
+ * @property {string} mode - The mode name for height and width.
+ * @augments ModeCheck
+ */
+const height_width_check = {
+    check: config => has(config, HEIGHT, WIDTH) && !has(config, LENGTH),
+    mode: 'height_width',
+}
+
+/**
+ * @typedef {object} ModeCheck
+ * @property {function(string[]): boolean} check - A function that takes a configuration array and returns true if the configuration matches this mode.
+ * @property {string} mode - The string identifier for the mode.
+ */
+const mode_checks = [
+    volume_check,
+    height_length_check,
+    length_width_check,
+    height_width_check
+]
+
+module.exports = { mode_checks }

package/src/Allocation_Optimization/functions/Weight_Getter/Translation.js

@@ -0,0 +1,22 @@
+const {TRANSLATIONS} = require('./constants')
+
+/**
+ * Translates a given key using predefined translations.
+ * If no translation is found, the original key is returned.
+ * @param {string} key - The key to translate.
+ * @returns {string} The translated key or the original key if no translation exists.
+ */
+const translate = key => (TRANSLATIONS[key] || key)
+
+/**
+ * Checks if a configuration array includes a specific key or its translation.
+ * @param {string[]} config - The configuration array.
+ * @param {string} key - The key to check for.
+ * @returns {boolean} True if the key or its translation is found, false otherwise.
+ */
+const includes_key_or_translation = (config, key) =>
+{
+    return config.includes(key) || config.includes(translate(key))
+}
+
+module.exports = {includes_key_or_translation}

package/src/Allocation_Optimization/functions/Weight_Getter/Variable_Weight_Getter.js

@@ -0,0 +1,85 @@
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const round = require('../../../tools/Rounder')
+const get_mode = require('./Measure_Cobination_Mode')
+
+const should_prefer_same_measure_items_block = () => Cargo_Profile.prefer_same_measure_slot_blocks()
+
+const compute_weight = {
+    volume: block => block.get_volume(),
+    height_length: block => block.get_height() * block.get_length(),
+    length_width: block => block.get_length() * block.get_width(),
+    height_width: block => block.get_height() * block.get_width(),
+}
+
+const get_item_amount_untie = block => block.get_slot_list().length * Cargo_Profile.untie_by_quantity_multiplier()
+
+/**
+ * Calculates a bonus weight based on the measure combination mode.
+ * The specific calculation depends on the mode returned by `get_mode()`.
+ * @param {Block} block - The block object for which to calculate the bonus.
+ * @returns {number} The measure combination bonus weight.
+ */
+const get_measure_combination_bonus = (block) =>
+{
+    const mode = get_mode()
+    const computer = compute_weight[mode]
+    if (computer)
+    {
+        return computer(block) / 10
+    }
+    return 0
+}
+
+/**
+ * Calculates a bonus weight based on the block's stackability index.
+ * @param {Block} block - The block object for which to calculate the bonus.
+ * @returns {number} The stackability bonus weight.
+ */
+const get_stackability_bonus = block => block.get_stackability_index()
+
+/**
+ * Calculates a bonus weight if the block is marked as a "preference" block.
+ * Returns preferential_blocks_bonus(default 5) if preferred, otherwise 0.
+ * @param {Block} block - The block object for which to calculate the bonus.
+ * @returns {number} The preference bonus weight.
+ */
+const get_preference_bonus = block => (block.is_preference() ? Cargo_Profile.preferential_blocks_bonus() : 0)
+
+/**
+ * Calculates a bonus weight if the block's slots have the same measures and
+ * either same-measure preference flag is true.
+ * @param {Block} block - The block object for which to calculate the bonus.
+ * @returns {number} The same item measures bonus weight.
+ */
+function get_same_item_measures_bonus (block)
+{
+    const has_same_measures = block.is_slots_of_same_measure()
+    const same_item_measures_bonus = Cargo_Profile.same_item_measures_bonus()
+    return should_prefer_same_measure_items_block() && has_same_measures ? same_item_measures_bonus : 0
+}
+
+
+// --- Main Exported Function ---
+
+/**
+ * Calculates a custom weight for a block based on various factors.
+ * @param {object} block - The block to be evaluated.
+ * @returns {number} The calculated custom weight.
+ */
+function get_custom_weight(block)
+{
+
+    const weight_components = [
+        get_measure_combination_bonus(block),
+        get_stackability_bonus(block),
+        get_same_item_measures_bonus(block),
+        get_preference_bonus(block),
+        get_item_amount_untie(block)
+    ]
+
+    const total_weight = weight_components.reduce((sum, value) => sum + value, 0)
+
+    return round(total_weight)
+}
+
+module.exports = get_custom_weight

package/src/Allocation_Optimization/functions/Weight_Getter/constants.js

@@ -0,0 +1,16 @@
+const DIMENSIONS = {
+    HEIGHT: 'height',
+    LENGTH: 'length',
+    WIDTH: 'width',
+}
+
+const TRANSLATIONS = {
+    [DIMENSIONS.HEIGHT]: 'altura',
+    [DIMENSIONS.LENGTH]: 'comprimento',
+    [DIMENSIONS.WIDTH]: 'largura',
+}
+
+module.exports = {
+    DIMENSIONS,
+    TRANSLATIONS,
+}

package/src/Allocation_Optimization/functions/measure_to_optimize.js

@@ -0,0 +1,6 @@
+const measure_to_optimize = {
+    LENGTH :'length',
+    WIDTH : 'width'
+}
+
+module.exports = measure_to_optimize

package/src/Allocation_Optimization/item_consumption_heuristic/Capacity_Bias_Item_Order.js

@@ -0,0 +1,76 @@
+const { get_weight_utilization, get_space_utilization } = require('../density_groups/Container_Utilization')
+const { calculate_item_density } = require('../density_groups/Item_Density_Calculator')
+
+/**
+ * Compares two items by density for stable sorting.
+ * @param {object} left_item
+ * @param {object} right_item
+ * @returns {number}
+ */
+function compare_by_density_ascending(left_item, right_item)
+{
+    const left_density = calculate_item_density(left_item).density
+    const right_density = calculate_item_density(right_item).density
+    if (left_density !== right_density)
+    {
+        return left_density - right_density
+    }
+    return String(left_item.get_id()).localeCompare(String(right_item.get_id()))
+}
+
+/**
+ * Whether the container exposes the accessors needed for utilization metrics.
+ * @param {object} container
+ * @returns {boolean}
+ */
+function container_supports_utilization(container)
+{
+    const required_methods = [
+        'get_allocated_items',
+        'get_width',
+        'get_height',
+        'get_length'
+    ]
+    return required_methods.every((method_name) =>
+        typeof container[method_name] === 'function'
+    )
+}
+
+/**
+ * Reorders compatible items using container weight vs space utilization.
+ * @param {object[]} item_list - Candidate items.
+ * @param {object|null|undefined} container - Container with allocated items.
+ * @returns {object[]} Same items, possibly reordered.
+ */
+function order_items_by_capacity_bias(item_list, container)
+{
+    if (!container || item_list.length <= 1)
+    {
+        return item_list
+    }
+
+    if (!container_supports_utilization(container))
+    {
+        return item_list
+    }
+
+    const gap = get_weight_utilization(container) - get_space_utilization(container)
+    if (gap === 0)
+    {
+        return item_list
+    }
+
+    const sorted_items = item_list.slice()
+    if (gap > 0)
+    {
+        sorted_items.sort(compare_by_density_ascending)
+        return sorted_items
+    }
+
+    sorted_items.sort((left_item, right_item) =>
+        compare_by_density_ascending(right_item, left_item)
+    )
+    return sorted_items
+}
+
+module.exports = { order_items_by_capacity_bias }

package/src/Allocation_Optimization/item_consumption_heuristic/Choose_Item_Heuristic_Context.js

@@ -0,0 +1,63 @@
+/**
+ * Builds a container stub for tests and legacy callers that only pass height_limit.
+ * @param {number} height_limit - Stack height cap.
+ * @returns {object} Minimal container with get_height and permissive is_a_valid_stacking.
+ */
+function create_height_limit_container_stub(height_limit)
+{
+    return {
+        get_height: () => height_limit,
+        is_a_valid_stacking: () => true
+    }
+}
+
+/**
+ * Resolves slot, container, and item_position for choose_item heuristic path.
+ * @param {object} data - Same bag as choose_item.
+ * @returns {{ slot: object, container: object, item_position: { x: number, y: number, z: number } }}
+ */
+function resolve_choose_item_heuristic_context(data)
+{
+    const slot = data.slot ?? data.block_slot
+    if (!slot)
+    {
+        throw new Error('choose_item heuristic requires data.slot or data.block_slot')
+    }
+    let container = data.container
+    if (!container && data.height_limit != null)
+    {
+        container = create_height_limit_container_stub(data.height_limit)
+    }
+    if (!container)
+    {
+        throw new Error('choose_item heuristic requires data.container or data.height_limit')
+    }
+    const item_position = data.item_position
+    return { slot, container, item_position }
+}
+
+/**
+ * Human-readable slot label for exception messages.
+ * @param {object} slot - Slot with optional to_string or get_x/get_y/get_z.
+ * @returns {string}
+ */
+function format_slot_label_for_exception(slot)
+{
+    if (typeof slot.to_string === 'function')
+    {
+        return slot.to_string()
+    }
+    const x = slot.get_x?.()
+    const y = slot.get_y?.()
+    const z = slot.get_z?.()
+    if (x !== undefined && y !== undefined && z !== undefined)
+    {
+        return `${x};${y};${z}`
+    }
+    return 'slot'
+}
+
+module.exports = {
+    resolve_choose_item_heuristic_context,
+    format_slot_label_for_exception
+}