Awesome
Proposal Upsert
ECMAScript proposal and reference implementation for Map.prototype.getOrInsert
and Map.prototype.getOrInsertComputed
.
Authors: Daniel Minor (Mozilla) Lauritz Thoresen Angeltveit (Bergen) Jonas Haukenes (Bergen) Sune Lianes (Bergen) Vetle Larsen (Bergen) Mathias Hop Ness (Bergen)
Champion: Daniel Minor (Mozilla)
Original Author: Brad Farias (GoDaddy)
Former Champion: Erica Pramer (GoDaddy)
Stage: 2
Motivation
A common problem when using a Map
is how to handle doing an update when
you're not sure if the key already exists in the Map
. This can be handled
by first checking if the key is present, and then inserting or updating
depending upon the result, but this is both inconvenient for the developer,
and less than optimal, because it requires multiple lookups in the Map
that could otherwise be handled in a single call.
Solution: getOrInsert
We propose the addition of a method that will return the value associated
with key
if it is already present in the dictionary, and otherwise insert
the key
with the provided default value, or the result of calling a provided
callback function, and then return that value.
Earlier versions of this proposal had an getOrInsert
method that provided two callbacks,
one for insert
and the other for update
, however the current champion thinks
that the get / insert if necessary is a sufficiently common usecase that it makes
sense to focus on it, rather than trying to create an API with maximum flexibility.
It also strongly follows precedent from other languages, in particular Python.
Examples & Proposed API
Handling default values
Using getOrInsert
simplifies handling default values because it will not overwrite
an existing value.
// Currently
let prefs = new getUserPrefs();
if (!prefs.has("useDarkmode")) {
prefs.set("useDarkmode", true); // default to true
}
// Using getOrInsert
let prefs = new getUserPrefs();
prefs.getOrInsert("useDarkmode", true); // default to true
By using getOrInsert
, default values can be applied at different times, with the
assurance that later defaults will not overwrite an existing value. For example,
in a situation where there are user preferences, operating system preferences,
and application defaults, we can use getOrInsert to apply the user preferences,
and then the operating system preferences, and then the application defaults,
without worrying about overwriting the user's preferences.
Grouping data incrementally
A typical usecase is grouping data based upon key as new values become available.
This is simplified by being able to specify a default value rather than having to
check for whether the key is already present in the Map
before trying to update.
// Currently
let grouped = new Map();
for (let [key, ...values] of data) {
if (grouped.has(key)) {
grouped.get(key).push(...values);
} else {
grouped.set(key, ...values);
}
}
// Using getOrInsert
let grouped = new Map();
for (let [key, ...values] of data) {
grouped.getOrInsert(key, []).push(...values);
}
It's true that a common usecase for this pattern is already covered by
Map.groupBy
. However, that method requires that all data be available
prior to building the groups; using getOrInsert
would allow the Map to be
built and used incrementally. It also provides flexibility to work with
data other than objects, such as the array example above.
Maintaining a counter
Another common use case is maintaining a counter associated with a
particular key. Using getOrInsert
makes this more concise, and is the
kind of access and then mutate pattern that is easily optimizable
by engines.
// Currently
let counts = new Map();
if (counts.has(key)) {
counts.set(key, counts.get(key) + 1);
} else {
counts.set(key, 1);
}
// Using getOrInsert
let counts = new Map();
counts.set(key, m.getOrInsert(key, 0) + 1);
Computing a default value
For some usecases, determining the default value is potentially a costly operation that
would be best avoided if it will not be used. In this case, we can use getOrInsertComputed
.
// Using getOrInsertComputed
let grouped = new Map();
for (let [key, ...values] of data) {
grouped.getOrInsertComputed(key, () => []).push(...values);
}
Implementations in other languages
Similar functionality exists in other languages.
Java
computeIfPresent
remaps existing entrycomputeIfAbsent
insert if empty. computes the insertion value with a mapping function
C++
emplace
inserts if missingmap[] assignment opts
inserts if missing atkey
but also returns a value if it exists atkey
insert_or_assign
inserts if missing. updates existing value by replacing with a specific new one, not by applying a function to the existing value
Rust
and_modify
Provides in-place mutable access to an occupied entryor_insert_with
inserts if empty. insertion value comes from a mapping function
Python
setdefault
Performs aget
and aninsert
defaultdict
A subclass ofdict
that takes a callback function that is used to construct missing values onget
.
Elixir
Map.update/4
Updates the item with given function if key exists, otherwise inserts given initial value
Specification
Polyfill
The proposal is trivially polyfillable:
Map.prototype.getOrInsert = function (key, defaultValue) {
if (this.has(key)) {
return this.get(key);
}
this.set(key, defaultValue);
return this.get(key);
};
Map.prototype.getOrInsertComputed = function (key, callbackFunction) {
if (this.has(key)) {
return this.get(key);
}
this.set(key, callbackFunction());
return this.get(key);
};