/**
 * Mutex decorator for exclusive method execution
 *
 * Without arguments: Per-instance locking (each object has its own lock per method)
 *   @mutex
 *   async my_method() { ... }
 *
 * With ID argument: Global locking by ID (all instances share the lock)
 *   @mutex('operation_name')
 *   async my_method() { ... }
 *
 * @decorator
 * @param {string} [global_id] - Optional global mutex ID for cross-instance locking
 */
function mutex(global_id) {
    // Storage (using IIFEs to keep WeakMap/Map in closure scope)
    const instance_mutexes = (function() {
        if (!mutex._instance_storage) {
            mutex._instance_storage = new WeakMap();
        }
        return mutex._instance_storage;
    })();

    const global_mutexes = (function() {
        if (!mutex._global_storage) {
            mutex._global_storage = new Map();
        }
        return mutex._global_storage;
    })();

    /**
     * Get or create a mutex for a specific instance and method
     */
    function get_instance_mutex(instance, method_name) {
        let instance_locks = instance_mutexes.get(instance);
        if (!instance_locks) {
            instance_locks = new Map();
            instance_mutexes.set(instance, instance_locks);
        }

        let lock_state = instance_locks.get(method_name);
        if (!lock_state) {
            lock_state = { active: false, queue: [] };
            instance_locks.set(method_name, lock_state);
        }

        return lock_state;
    }

    /**
     * Get or create a global mutex by ID
     */
    function get_global_mutex(id) {
        let lock_state = global_mutexes.get(id);
        if (!lock_state) {
            lock_state = { active: false, queue: [] };
            global_mutexes.set(id, lock_state);
        }
        return lock_state;
    }

    /**
     * Execute the next queued operation for a mutex
     */
    function schedule_next(lock_state) {
        if (lock_state.active || lock_state.queue.length === 0) {
            return;
        }

        const { fn, resolve, reject } = lock_state.queue.shift();
        lock_state.active = true;

        Promise.resolve()
            .then(fn)
            .then(resolve, reject)
            .finally(() => {
                lock_state.active = false;
                schedule_next(lock_state);
            });
    }

    /**
     * Acquire a mutex lock and execute callback
     */
    function acquire_lock(lock_state, fn) {
        return new Promise((resolve, reject) => {
            lock_state.queue.push({ fn, resolve, reject });
            schedule_next(lock_state);
        });
    }

    // If called with an ID argument: @mutex('id')
    if (typeof global_id === 'string') {
        return function(target, key, descriptor) {
            const original_method = descriptor.value;

            if (typeof original_method !== 'function') {
                throw new Error(`@mutex can only be applied to methods (tried to apply to ${key})`);
            }

            descriptor.value = function(...args) {
                const lock_state = get_global_mutex(global_id);
                return acquire_lock(lock_state, () => original_method.apply(this, args));
            };

            return descriptor;
        };
    }

    // If called without arguments: @mutex (target is the first argument)
    const target = global_id;  // In this case, first arg is target
    const key = arguments[1];
    const descriptor = arguments[2];

    const original_method = descriptor.value;

    if (typeof original_method !== 'function') {
        throw new Error(`@mutex can only be applied to methods (tried to apply to ${key})`);
    }

    descriptor.value = function(...args) {
        const lock_state = get_instance_mutex(this, key);
        return acquire_lock(lock_state, () => original_method.apply(this, args));
    };

    return descriptor;
}