webpack/lib/util/StackedMap.js

Packs ECMAScript/CommonJs/AMD modules for the browser. Allows you to split your codebase into multiple bundles, which can be loaded on demand. Supports loaders to preprocess files, i.e. json, jsx, es7, css, less, ... and your custom stuff.

/*
	MIT License http://www.opensource.org/licenses/mit-license.php
	Author Tobias Koppers @sokra
*/

"use strict";

const TOMBSTONE = Symbol("tombstone");
const UNDEFINED_MARKER = Symbol("undefined");

/**
 * Public cell value exposed by `StackedMap`, where `undefined` is preserved as
 * a valid stored result.
 * @template T
 * @typedef {T | undefined} Cell<T>
 */

/**
 * Internal cell value used to distinguish deleted entries and explicit
 * `undefined` assignments while traversing stacked scopes.
 * @template T
 * @typedef {T | typeof TOMBSTONE | typeof UNDEFINED_MARKER} InternalCell<T>
 */

/**
 * Converts an internal key/value pair into the external representation returned
 * by iteration helpers.
 * @template K
 * @template V
 * @param {[K, InternalCell<V>]} pair the internal cell
 * @returns {[K, Cell<V>]} its “safe” representation
 */
const extractPair = (pair) => {
	const key = pair[0];
	const val = pair[1];
	if (val === UNDEFINED_MARKER || val === TOMBSTONE) {
		return [key, undefined];
	}
	return /** @type {[K, Cell<V>]} */ (pair);
};

/**
 * Layered map that supports child scopes while memoizing lookups from parent
 * scopes into the current layer.
 * @template K
 * @template V
 */
class StackedMap {
	/**
	 * Creates a new map layer on top of an optional parent stack.
	 * @param {Map<K, InternalCell<V>>[]=} parentStack an optional parent
	 */
	constructor(parentStack) {
		/** @type {Map<K, InternalCell<V>>} */
		this.map = new Map();
		/** @type {Map<K, InternalCell<V>>[]} */
		this.stack = parentStack === undefined ? [] : [...parentStack];
		this.stack.push(this.map);
	}

	/**
	 * Stores a value in the current layer, preserving explicit `undefined`
	 * values with an internal marker.
	 * @param {K} item the key of the element to add
	 * @param {V} value the value of the element to add
	 * @returns {void}
	 */
	set(item, value) {
		this.map.set(item, value === undefined ? UNDEFINED_MARKER : value);
	}

	/**
	 * Deletes a key from the current view, either by removing it outright in the
	 * root layer or by recording a tombstone in child layers.
	 * @param {K} item the item to delete
	 * @returns {void}
	 */
	delete(item) {
		if (this.stack.length > 1) {
			this.map.set(item, TOMBSTONE);
		} else {
			this.map.delete(item);
		}
	}

	/**
	 * Checks whether a key exists in the current scope chain, caching any parent
	 * lookup result in the current layer.
	 * @param {K} item the item to test
	 * @returns {boolean} true if the item exists in this set
	 */
	has(item) {
		const topValue = this.map.get(item);
		if (topValue !== undefined) {
			return topValue !== TOMBSTONE;
		}
		if (this.stack.length > 1) {
			for (let i = this.stack.length - 2; i >= 0; i--) {
				const value = this.stack[i].get(item);
				if (value !== undefined) {
					this.map.set(item, value);
					return value !== TOMBSTONE;
				}
			}
			this.map.set(item, TOMBSTONE);
		}
		return false;
	}

	/**
	 * Returns the visible value for a key, caching parent hits and misses in the
	 * current layer.
	 * @param {K} item the key of the element to return
	 * @returns {Cell<V>} the value of the element
	 */
	get(item) {
		const topValue = this.map.get(item);
		if (topValue !== undefined) {
			return topValue === TOMBSTONE || topValue === UNDEFINED_MARKER
				? undefined
				: topValue;
		}
		if (this.stack.length > 1) {
			for (let i = this.stack.length - 2; i >= 0; i--) {
				const value = this.stack[i].get(item);
				if (value !== undefined) {
					this.map.set(item, value);
					return value === TOMBSTONE || value === UNDEFINED_MARKER
						? undefined
						: value;
				}
			}
			this.map.set(item, TOMBSTONE);
		}
	}

	/**
	 * Collapses the stacked layers into a single concrete map.
	 */
	_compress() {
		if (this.stack.length === 1) return;
		this.map = new Map();
		for (const data of this.stack) {
			for (const pair of data) {
				if (pair[1] === TOMBSTONE) {
					this.map.delete(pair[0]);
				} else {
					this.map.set(pair[0], pair[1]);
				}
			}
		}
		this.stack = [this.map];
	}

	/**
	 * Returns the visible keys as an array after collapsing the stack.
	 * @returns {K[]} array of keys
	 */
	asArray() {
		this._compress();
		return [...this.map.keys()];
	}

	/**
	 * Returns the visible keys as a `Set` after collapsing the stack.
	 * @returns {Set<K>} set of keys
	 */
	asSet() {
		this._compress();
		return new Set(this.map.keys());
	}

	/**
	 * Returns visible key/value pairs using the external representation.
	 * @returns {[K, Cell<V>][]} array of key/value pairs
	 */
	asPairArray() {
		this._compress();
		return Array.from(this.map.entries(), extractPair);
	}

	/**
	 * Returns the visible contents as a plain `Map`.
	 * @returns {Map<K, Cell<V>>} materialized map
	 */
	asMap() {
		return new Map(this.asPairArray());
	}

	/**
	 * Returns the number of visible keys after collapsing the stack.
	 * @returns {number} number of keys
	 */
	get size() {
		this._compress();
		return this.map.size;
	}

	/**
	 * Creates a child `StackedMap` that sees the current layers as its parent
	 * scope.
	 * @returns {StackedMap<K, V>} child map
	 */
	createChild() {
		return new StackedMap(this.stack);
	}
}

module.exports = StackedMap;