@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/models/Block.js

@@ -0,0 +1,198 @@
+const {Cube}      = require('@jetta/empty-spaces-manager')
+const Slot        = require('./Slot')
+const create_hash = require('../tools/Hash')
+const clone       = require('../tools/Clone')
+const Invalid_Parameter_Exception = require('../exceptions/Invalid_Parameter_Exception')
+const slots_have_same_measure = require('./slots_have_same_measure')
+
+const default_sorting = (a, b) => Number(a.y) - Number(b.y)
+
+/**
+ * @class Block
+ * @augments Cube
+ * @description Represents a block of items, which can be a single item or a combination of multiple items (slots).
+ * Inherits from `Cube` for spatial dimensions and provides additional properties and methods
+ * related to item allocation, stacking, and preferences.
+ */
+class Block extends Cube
+{
+    #data
+    #slot_list = []
+    #is_block = false
+    #stackability_index = -1
+    #id
+    #volume
+    #is_slots_of_same_measure = false
+    #allocation_preference = false
+
+    /**
+     * @constructor
+     * @param {object} measures - An object containing the block's initial data, including dimensions (width, height, length).
+     * @param {Array<Slot>} slot_list - An array of `Slot` objects that compose this block.
+     */
+    constructor(measures, slot_list)
+    {
+        super(measures.width, measures.height, measures.length)
+        if (!slot_list || slot_list.length === 0)
+        {
+            throw new Invalid_Parameter_Exception('slot_list cannot be null or empty')
+        }
+        this.#data                      = measures
+        this.#slot_list                 = slot_list
+        this.#is_block                  = slot_list.length > 1
+        this.#id                        = this.#create_id()
+        this.#volume                    = this.#slot_list.reduce((acc, cur) => acc + cur.get_volume(), 0)
+        this.#is_slots_of_same_measure  = slots_have_same_measure(slot_list)
+        this.#data.is_slots_of_same_measure = this.#is_slots_of_same_measure
+        this.#sort_slots()
+    }
+
+    /**
+     * Returns the unique identifier of the block.
+     * @returns {string} The block's ID.
+     */
+    get_id = () => this.#id
+
+    /**
+     * Returns the calculated stackability index of the block.
+     * @returns {number} The stackability index.
+     */
+    get_stackability_index = () => this.#stackability_index
+
+    /**
+     * Returns the maximum height occupied by any item within the block.
+     * @returns {number} The maximum height.
+     */
+    get_height = () => Math.max(...this.#items_end_y())
+
+    /**
+     * Returns a clone of the block's total volume.
+     * @returns {number} The total volume.
+     */
+    get_volume = () => clone(this.#volume)
+
+    /**
+     * Returns tie-ratio orientation when this block was generated by tie_ratio_blocks.
+     * @returns {'3_2'|'2_3'|undefined}
+     */
+    get_tie_ratio_orientation = () => this.#data.tie_ratio_orientation
+
+    /**
+     * @returns {boolean} True when block carries tie-ratio orientation metadata.
+     */
+    is_tie_ratio_block = () => this.#data.tie_ratio_orientation !== undefined
+
+    /**
+     * Returns a shallow copy of the block's raw data.
+     * @returns {object} The block's data.
+     */
+    get_json = () => Object.assign({}, this.#data)
+
+    /**
+     * Returns the list of slots (items) that compose this block.
+     * @returns {Array<Slot>} The list of slots.
+     */
+    get_slot_list = () => this.#slot_list
+
+    /**
+     * Sets the allocation preference flag for this block to true.
+     */
+    set_preference = () => this.#allocation_preference = true
+
+    /**
+     * Calculates and sets the stackability index of the block based on its slots.
+     * The stackability index is the minimum stackability index among all its slots.
+     */
+    calculate_stackability_index = () =>
+    {
+        const slots_index        = this.#get_block_slots_index_list()
+        this.#stackability_index = Math.min(...slots_index)
+    }
+
+    /**
+     * Checks if the block has an allocation preference.
+     * @returns {boolean} True if preferred, false otherwise.
+     */
+    is_preference = () => this.#allocation_preference
+
+    /**
+     * Checks if the block contains more than one slot, indicating it's a combined block.
+     * @returns {boolean} True if it's a multi-slot block, false otherwise.
+     */
+    is_block = () => (this.#slot_list.length > 1)
+
+    /**
+     * Checks if all slots within the block have the same measure.
+     * @returns {boolean} True if slots have same measure, false otherwise.
+     */
+    is_slots_of_same_measure = () => this.#is_slots_of_same_measure
+
+    /**
+     * Checks if the block contains more than one slot, indicating it's a combined block.
+     * (Duplicate of `is_block` above, consider consolidating).
+     * @returns {boolean} True if it's a multi-slot block, false otherwise.
+     */
+    is_block = () => this.#is_block
+
+    /**
+     * @private
+     * Retrieves the stackability index for each slot in the block.
+     * @returns {Array<number>} An array of stackability indices for each slot.
+     */
+    #get_block_slots_index_list = () => this.#slot_list.map(slot => slot.get_stackability_index())
+
+    /**
+     * @private
+     * Retrieves the end Y-coordinate for each slot in the block.
+     * @returns {Array<number>} An array of end Y-coordinates for each slot.
+     */
+    #items_end_y = () => this.#slot_list.map(slot => slot.get_end_point().y)
+
+    /**
+     * @private
+     * Prepares a string by concatenating the hashes of all slots, used for creating the block's ID.
+     * @returns {string} A concatenated string of slot hashes.
+     */
+    #prepare_id = () =>this.#slot_list.reduce((acc, cur) => `${acc};${cur.get_hash()}`, '')
+
+    /**
+     * @private
+     * Creates a unique hash ID for the block based on the combined hashes of its slots.
+     * @returns {string} The unique hash ID.
+     */
+    #create_id = () =>  create_hash(this.#prepare_id())
+
+    /**
+     * @private
+     * Sorts the internal list of slots based on a provided sorting function.
+     * Defaults to sorting by the Y-coordinate.
+     * @param {function(Slot, Slot): number} [sort_function=default_sorting] - The function to use for sorting slots.
+     */
+    #sort_slots = (sort_function = default_sorting) => this.#slot_list.sort((a, b) => sort_function(a, b))
+
+    fits_rotated_item(item)
+    {
+        for (const slot of this.#slot_list)
+        {
+            if (slot.rotated_item_fits_perfectly(item))
+            {
+                return true
+            }
+        }
+        return false
+    }
+}
+
+/**
+ * Creates a `Block` instance from a single item's data.
+ * This effectively treats a single item as a block composed of one slot.
+ * @param {object} data - The item's data, including dimensions (width, height, length).
+ * @returns {Block} A new `Block` instance representing the single item.
+ */
+function create_block_from_item(data)
+{
+    const positioned_item = new Slot(0, 0, 0, data.width, data.height, data.length)
+    return new Block(data , [positioned_item])
+}
+
+module.exports = {create_block_from_item, Block}

package/src/models/Cargo_Profile.js

@@ -0,0 +1,418 @@
+const {
+    DENSITY_GROUPS_STRATEGY,
+    normalize_density_groups_strategy,
+} = require('../Allocation_Optimization/density_groups/Density_Groups_Strategy')
+const {
+    DEFAULT_WEIGHT_AHEAD_THRESHOLD_PP,
+    DEFAULT_SPACE_AHEAD_THRESHOLD_PP,
+    percentage_points_to_fraction,
+} = require('../Allocation_Optimization/density_groups/Adaptive_Density_Group_Thresholds')
+const str_to_bool = require('../tools/String_To_Boolean')
+const assert = require('assert')
+const create_block_module_lost = require('./auxiliaryFunctions/Available_Block_Module_List_Creator')
+const clone = require('../tools/Clone')
+const {
+    finite_float_from_string_or_number,
+    finite_int_from_string_or_number,
+    optional_finite_float_from_string_or_number,
+} = require('../tools/cargo_profile/Cargo_Profile_Field_Value_Resolver')
+
+class Cargo_Profile
+{
+    static #instance = null
+    static #stacking_constraints_module_list = []
+
+    constructor(cargo_profile_json)
+    {
+        assert(Cargo_Profile.#instance === null, 'Cargo_Profile instance already exists')
+        Object.assign(this, cargo_profile_json)
+        Cargo_Profile.#instance = this
+    }
+
+    static set_stacking_constraints_list(stacking_constraints_module_list)
+    {
+        this.#stacking_constraints_module_list = stacking_constraints_module_list
+    }
+
+    static get_stacking_constraint_module_list()
+    {
+        return Cargo_Profile.#stacking_constraints_module_list
+    }
+
+    static measure_to_optimize()
+    {
+        return this.#instance['allocation.blocks.measure_to_optimize'] ?? ''
+    }
+
+    static enable_to_find_empty_space_block()
+    {
+        const key = 'allocation.empty_space.finder.enable_to_find_empty_space_block'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static enable_to_find_empty_space_from_spiral_block_of_same_measure()
+    {
+        const key = 'allocation.empty_space.finder.enable_to_find_empty_space_from_spiral_block_of_same_measure'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static empty_space_score_strategy_criterias()
+    {
+        const key = 'allocation.empty_space.chooser.score_strategy_criterias'
+        return this.#instance[key] ?? [{ criteria: 'MaximumFill', weight: 1 }]
+    }
+
+    static prefer_block_with_same_item()
+    {
+        return str_to_bool(this.#instance['allocation.blocks.prefer_block_with_same_item'], true)
+    }
+
+    /**
+     * Whether single-slot Item_Continuation_Lock is active.
+     * Defaults to true when omitted or when no cargo profile is loaded (legacy behavior).
+     * @returns {boolean}
+     */
+    static enable_item_continuation_lock()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return true
+        }
+        return str_to_bool(this.#instance['allocation.blocks.enable_item_continuation_lock'], true)
+    }
+
+    static enable_key_item_mapping()
+    {
+        return str_to_bool(this.#instance['allocation.blocks.preferential.enable'], true)
+    }
+
+    static preferential_blocks_bonus()
+    {
+        const key = 'allocation.blocks.preferential_blocks_bonus'
+        return finite_float_from_string_or_number(this.#instance[key], 5)
+    }
+
+    static enable_block_equalization()
+    {
+        return str_to_bool(this.#instance['allocation.blocks.enable_block_equalization'], false)
+    }
+
+    static enable_block_formatter()
+    {
+        const key = 'allocation.blocks.enable_block_formatter'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static enforce_single_item_type()
+    {
+        return str_to_bool(this.#instance['allocation.blocks.enforce_single_item_type'], false)
+    }
+
+    static enforce_uniform_block_measure()
+    {
+        const key = 'allocation.blocks.enforce_uniform_block_measure'
+        return str_to_bool(this.#instance[key], true)
+    }
+
+    static enforce_relational_group_co_location()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const explicit_flag = this.#instance['allocation.blocks.enforce_relational_group_co_location']
+        if (explicit_flag !== undefined)
+        {
+            return str_to_bool(explicit_flag, false)
+        }
+        return str_to_bool(this.#instance['relational_allocation_enabled'], false)
+    }
+
+    static relational_lp_require_exact_pass_amount()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const key = 'allocation.blocks.relational_lp_require_exact_pass_amount'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static block_equalization_tolerance()
+    {
+        const key = 'allocation.blocks.block_equalization_tolerance'
+        return finite_float_from_string_or_number(this.#instance[key], 0.04)
+    }
+
+    static block_equalization_penalty_coefficient()
+    {
+        const key = 'allocation.blocks.block_equalization_penalty_coefficient'
+        return finite_int_from_string_or_number(this.#instance[key], -5)
+    }
+
+    static untie_by_quantity_multiplier()
+    {
+        const key = 'allocation.blocks.untie_by_quantity_multiplier'
+        return finite_float_from_string_or_number(this.#instance[key], 2)
+    }
+
+    static same_item_measures_bonus()
+    {
+        const key = 'allocation.blocks.same_item_measures_bonus'
+        return finite_float_from_string_or_number(this.#instance[key], 10)
+    }
+
+    static enable_blocks_extra_score()
+    {
+        return str_to_bool(this.#instance['allocation.optimization.enable_blocks_extra_score'], false)
+    }
+
+    static enable_max_tower_cut()
+    {
+        return str_to_bool(this.#instance['allocation.blocks.enable_max_tower_cut'], false)
+    }
+
+    static obligate_block_allocation_first()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        return str_to_bool(this.#instance['allocation.blocks.obligate_block_allocation_first'], false)
+    }
+
+    /**
+     * Leftover-SKU unitary fill after compound-first probe fails.
+     * Requires obligate_block_allocation_first. Default false (prod compound-first only).
+     * @returns {boolean}
+     */
+    static leftover_sku_unitary_fill()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        return str_to_bool(this.#instance['allocation.blocks.leftover_sku_unitary_fill'], false)
+    }
+
+    /**
+     * Snaps elevated wall items onto unique floor (x, z) footprints.
+     * Default false (prod: no snap, stacking does not require a floor twin).
+     * @returns {boolean}
+     */
+    static snap_stacked_items_to_floor_footprints()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        return str_to_bool(
+            this.#instance['allocation.blocks.snap_stacked_items_to_floor_footprints'],
+            false
+        )
+    }
+
+    /**
+     * Rejects blocks whose slots overlap on create. Default false (prod: filter off).
+     * @returns {boolean}
+     */
+    static reject_blocks_with_overlapped_slots()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        return str_to_bool(this.#instance['allocation.blocks.reject_blocks_with_overlapped_slots'], false)
+    }
+
+    static enable_density_groups()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const key = 'allocation.items.density_groups.enable'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static density_groups_count()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return 3
+        }
+        const key = 'allocation.items.density_groups.count'
+        const raw = finite_int_from_string_or_number(this.#instance[key], 3)
+        return Math.max(2, raw)
+    }
+
+    /**
+     * @returns {typeof DENSITY_GROUPS_STRATEGY.ROUND_ROBIN | typeof DENSITY_GROUPS_STRATEGY.ADAPTIVE}
+     */
+    static density_groups_strategy()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return DENSITY_GROUPS_STRATEGY.ROUND_ROBIN
+        }
+        const key = 'allocation.items.density_groups.strategy'
+        return normalize_density_groups_strategy(this.#instance[key])
+    }
+
+    /**
+     * @returns {number} Weight-ahead gap threshold as a utilization fraction (default 0.10).
+     */
+    static density_groups_weight_ahead_threshold()
+    {
+        return Cargo_Profile.#resolve_density_group_threshold_pp(
+            'allocation.items.density_groups.weight_ahead_threshold_pp',
+            DEFAULT_WEIGHT_AHEAD_THRESHOLD_PP
+        )
+    }
+
+    /**
+     * @returns {number} Space-ahead gap threshold as a utilization fraction (default 0.15).
+     */
+    static density_groups_space_ahead_threshold()
+    {
+        return Cargo_Profile.#resolve_density_group_threshold_pp(
+            'allocation.items.density_groups.space_ahead_threshold_pp',
+            DEFAULT_SPACE_AHEAD_THRESHOLD_PP
+        )
+    }
+
+    static #resolve_density_group_threshold_pp(key, default_pp)
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return percentage_points_to_fraction(default_pp)
+        }
+        const raw = finite_float_from_string_or_number(this.#instance[key], default_pp)
+        return percentage_points_to_fraction(raw)
+    }
+
+    static enable_stacking_constraints_service()
+    {
+        return str_to_bool(this.#instance['allocation.stacking.enable_stacking_constraints_service'], true)
+    }
+
+    static prefer_spiral_blocks_with_slots_of_same_measures()
+    {
+        const key = 'allocation.blocks.prefer_spiral_blocks_with_slots_of_same_measures'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    /**
+     * Generic gate for the same-measure slot LP bonus. Default false.
+     * @returns {boolean}
+     */
+    static prefer_blocks_with_slots_of_same_measures()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const key = 'allocation.blocks.prefer_blocks_with_slots_of_same_measures'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    /**
+     * True when the generic or spiral-named same-measure preference flag is on.
+     * @returns {boolean}
+     */
+    static prefer_same_measure_slot_blocks()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        return this.prefer_spiral_blocks_with_slots_of_same_measures()
+            || this.prefer_blocks_with_slots_of_same_measures()
+    }
+
+    static block_variable_weight_config()
+    {
+        return this.#instance['allocation.blocks.block_variable_weight_config'] ?? []
+    }
+
+    static max_tower_height_superior_gap()
+    {
+        const key = 'allocation.optimization.max_tower_height_calculation.superior_gap'
+        return optional_finite_float_from_string_or_number(this.#instance[key])
+    }
+
+    static max_tower_height_inferior_gap()
+    {
+        const key = 'allocation.optimization.max_tower_height_calculation.inferior_gap'
+        return optional_finite_float_from_string_or_number(this.#instance[key])
+    }
+
+    static block_module_list()
+    {
+        return create_block_module_lost(clone(this.#instance))
+    }
+
+    static allocate_intercalated()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const key = 'allocation.blocks.allocate_intercalated'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static tie_ratio_allocate_remainder_as_partial_blocks()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const key = 'allocation.blocks.tie_ratio.allocate_remainder_as_partial_blocks'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static stack_loose_on_tie_ratio_blocks()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        const key = 'allocation.blocks.stack_loose_on_tie_ratio_blocks'
+        return str_to_bool(this.#instance[key], false)
+    }
+
+    static reset()
+    {
+        Cargo_Profile.#instance = null
+    }
+
+    static read_cargo_profile(cargo_profile)
+    {
+        if (!Cargo_Profile.#instance)
+        {
+            Cargo_Profile.#instance = new Cargo_Profile(cargo_profile)
+        }
+        return Cargo_Profile.#instance
+    }
+
+    static set_cargo_profile(cargo_profile)
+    {
+        Cargo_Profile.#instance = null
+        Cargo_Profile.#instance = new Cargo_Profile(cargo_profile)
+    }
+
+    static get_cargo_profile()
+    {
+        assert(Cargo_Profile.#instance !== null, 'No cargo profile has been read.')
+        return Cargo_Profile.#instance
+    }
+
+    static get_cargo_profile_as_js_object()
+    {
+        assert(Cargo_Profile.#instance !== null, 'cargo profile has not been set yet.')
+        return { ...Cargo_Profile.#instance }
+    }
+}
+
+module.exports = Cargo_Profile