The problem#

Let’s imagine for a moment that you need to look up a product name by its numeric ID, hundreds of times per page load. Are you going to hit the database every single time? No, of course not. So you build a cache. The classic approach is to reach for a plain JavaScript object:

1
// ES5 - the pattern that served us well for a decade
2
var oLookup = {};
3
oLookup[nProductId] = sProductName;
4
var sName = oLookup[nProductId];

This works, and the Using an Object as a Cache [7] tutorial from 2013 shows a full, production-ready version of it. I still think that article holds up for what it is. But the plain-object approach has a handful of problems that get sharper as your code matures:

• All keys are coerced to strings. Pass a numeric ID and JavaScript silently converts it. This matters when 0, "", and false all become the same key, or when two IDs that differ only in type collide.
• Prototype pollution risk. If any key matches a built-in Object property (constructor, toString, hasOwnProperty), you are in for a confusing afternoon. You can work around this with Object.create(null), but now you have to remember to do that every time.
• No .size. To count entries you iterate and count manually, or maintain a separate counter.
• No .has(). The idiom obj[key] !== undefined lies to you when you deliberately store undefined as a value.
• Zero IDE type inference. The script editor has no idea what type comes back out of oLookup[nProductId]. Every usage is any, so you get no autocomplete and no type-checking on the value you retrieved.

The ES6 Map solves all five problems. And as of Servoy 2025.09, the IDE understands the generic type parameters so you can annotate Map<Number, String> and the editor knows what .get() returns.

The approach#

ES6 gives us two typed collection types:

• Map<K, V> is an ordered key/value store where keys can be any type and the IDE knows the value type.
• Set<V> is an ordered unique-value collection where the IDE knows the element type.

Both use the Hungarian prefixes m for Map and st for Set, with a /**@type {Map<K, V>}*/ or /**@type {Set<V>}*/ annotation above every declaration. Capital-letter Servoy type names, same as everywhere else: String, Number, Boolean, Date.

The type examples given in the Servoy 2025.09 release notes are Map<String, Number> and Set<Date> [1].

In Servoy 2025.12, two more tickets deepened the support: SVY-20595 added iteration type inference (so .entries() and .keys() return properly typed iterators), and SVY-20596 added auto-typed forEach callbacks, meaning the editor infers the callback parameter types from the Map or Set’s declared generics without any extra JSDoc on the callback itself [2].

Scenario one: typed lookup table (Map replaces oCache)#

Let’s build a product-name lookup that loads once and serves many callers. This is the core use case where Map shines over the plain-object approach.

Here is the complete code:

1
// This cache lives at scope level (for example in scopes/cache.js). Persistent
2
// Servoy scope variables are declared with var, not const or let, so they keep
3
// their value for the lifetime of the scope. For a globals or shared scope that
4
// means the whole user session.
5
    /**@type {Map<Number, String>}*/
6
var mProductNames = new Map();
7

8
/**
9
 * Build a product-name lookup Map from a dataset, loading from the database
10
 * on first call. Returns from the in-memory Map on subsequent calls.
11
 *
12
 * @author Gary Dotzlaw
13
 * @since 2026-06-11
14
 * @public
15
 *
16
 * @return {Map<Number, String>} map of product ID to product name
17
 */
18
function getProductNameMap() {
19
    if (mProductNames.size > 0) {
20
        return mProductNames;
21
    }
22

23
        /**@type {QBSelect<db:/myserver/crm_product>}*/
24
    const query = datasources.db.myserver.crm_product.createSelect();
25
    query.result.add(query.columns.product_id);
26
    query.result.add(query.columns.product_name);
27
    query.where.add(query.columns.org_id.eq(globals.org_id));
28

29
        // -1 returns all rows: this is a full lookup table, so we deliberately
30
        // load every product once and serve the rest of the session from memory.
31
        /**@type {JSDataSet}*/
32
    const dsProducts = databaseManager.getDataSetByQuery(query, -1);
33
    if (!dsProducts) return mProductNames;
34

35
    for (let i = 1; i <= dsProducts.getMaxRowIndex(); i++) {
36
            /**@type {Number}*/
37
        const nId = dsProducts.getValue(i, 1);
38
            /**@type {String}*/
39
        const sName = dsProducts.getValue(i, 2);
40
        mProductNames.set(nId, sName);
41
    }
42
    return mProductNames;
43
}
44

45
/**
46
 * Look up a product name by its numeric ID.
47
 *
48
 * @author Gary Dotzlaw
49
 * @since 2026-06-11
50
 * @public
51
 *
52
 * @param {Number} nProductId the numeric product ID
53
 * @return {String|null} the product name, or null if not found
54
 */
55
function getProductName(nProductId) {
56
        /**@type {Map<Number, String>}*/
57
    const mNames = getProductNameMap();
58
    if (mNames.has(nProductId)) {
59
        return mNames.get(nProductId);
60
    }
61
    return null;
62
}
63

64
/**
65
 * Clear the product-name lookup cache so the next call reloads from the database.
66
 *
67
 * @author Gary Dotzlaw
68
 * @since 2026-06-11
69
 * @public
70
 *
71
 * @return {void}
72
 */
73
function clearProductNameCache() {
74
    mProductNames.clear();
75
}

The code is doing several things that are worth calling out:

• var mProductNames = new Map() at scope level: The cache is declared with var, not const, and it lives at the top of a scope file (for example scopes/cache.js). That is deliberate. In Servoy, a persistent scope variable, the kind that keeps its value across calls for the lifetime of the scope, is declared with var. A const or let at the top of a scope file is a module-local binding and is not guaranteed to give you scope-variable persistence. Since this Map is the whole point of a session cache, var is the correct choice here. This is the one place the conventions doc’s “var only when scope-level persistence is required” rule applies.
• databaseManager.getDataSetByQuery(query, -1): The -1 means return all rows. This is a full lookup table, so loading every product once on the first call is the intended behaviour, not an unbounded-load mistake. Every subsequent call returns straight from the in-memory Map thanks to the size guard at the top of the function.
• /**@type {Map<Number, String>}*/: This annotation tells the Servoy IDE that keys are Number and values are String. When you call mProductNames.get(nId), the editor knows the return type is String, not any. That is the whole point of the tutorial.
• mProductNames.set(nId, sName): The .set() call is chainable and returns the Map, but we don’t need the return here. The key remains a Number; no string coercion happens.
• mNames.has(nProductId) before .get(): Always check .has() before .get() when a missing key is a valid business condition. .get() returns undefined for missing keys, and if your IDE type says the value is String, that undefined can be a surprise.
• mProductNames.clear(): One call drops every entry. No iteration required.

Here is how callers use it:

1
/**
2
 * Build a display string for a line item.
3
 *
4
 * @author Gary Dotzlaw
5
 * @since 2026-06-11
6
 * @private
7
 *
8
 * @param {Number} nProductId the product ID
9
 * @param {Number} nQty the ordered quantity
10
 * @return {String} display string
11
 */
12
function buildLineItemLabel(nProductId, nQty) {
13
        /**@type {String|null}*/
14
    const sName = getProductName(nProductId);
15
    if (!sName) return `Product ${nProductId} (unknown)`;
16
    return `${sName} x ${nQty}`;
17
}

The editor knows sName is String|null because the return type of getProductName is annotated. You get autocomplete on string methods and a type error if you pass sName somewhere that expects a non-null String. That is the lookup table that doesn’t lie.

Scenario two: typed Set for deduplication#

Now let’s look at Set. The canonical use case is collecting unique values without worrying about duplicates.

Imagine you need to know which unique category codes appear in a product foundset. With a plain array you would check indexOf on every add. With a Set you just call .add() and let the Set handle uniqueness.

1
/**
2
 * Collect the unique category codes from a product foundset.
3
 *
4
 * @author Gary Dotzlaw
5
 * @since 2026-06-11
6
 * @public
7
 *
8
 * @param {JSFoundSet<db:/myserver/crm_product>} fsProducts the product foundset to scan
9
 * @return {Set<String>} the unique category codes found
10
 */
11
function getUniqueCategoryCodes(fsProducts) {
12
        /**@type {Set<String>}*/
13
    const stCodes = new Set();
14
    for (let i = 1; i <= fsProducts.getSize(); i++) {
15
            /**@type {JSRecord<db:/myserver/crm_product>}*/
16
        const rProd = fsProducts.getRecord(i);
17
            /**@type {String}*/
18
        const sCategoryCode = rProd.category_code;
19
        stCodes.add(sCategoryCode);
20
    }
21
    return stCodes;
22
}

The /**@type {Set<String>}*/ annotation tells the editor that every value stored in stCodes is a String. Calling .has() on it is type-checked. After running this function, you have an ordered collection of unique category codes, deduplicated automatically, with no manual indexOf check.

Here is a usage example that demonstrates .has(), .size, and .delete():

1
/**
2
 * Check whether a product foundset contains any items in the "clearance" category
3
 * and, if so, remove clearance from the code set for the purposes of reporting.
4
 *
5
 * @author Gary Dotzlaw
6
 * @since 2026-06-11
7
 * @public
8
 *
9
 * @param {JSFoundSet<db:/myserver/crm_product>} fsProducts the foundset to inspect
10
 * @return {Set<String>} the non-clearance category codes
11
 */
12
function getNonClearanceCodes(fsProducts) {
13
        /**@type {Set<String>}*/
14
    const stCodes = getUniqueCategoryCodes(fsProducts);
15

16
        /**@type {String}*/
17
    const sClearanceCode = 'CLRNC';
18

19
    if (stCodes.has(sClearanceCode)) {
20
        stCodes.delete(sClearanceCode);
21
        application.output('Removed clearance category from report set.', LOGGINGLEVEL.DEBUG);
22
    }
23
    application.output('Category codes in report: ' + stCodes.size, LOGGINGLEVEL.DEBUG);
24
    return stCodes;
25
}

The Set API is clean and intentional: .add() to insert, .has() to test membership, .delete() to remove a specific value, and .size to count entries [5].

Iterating with forEach: the value-first gotcha#

Both Map and Set support forEach, and both will surprise you if you assume the callback signature mirrors what you’d expect from an array.

For Map.forEach, the callback receives (value, key, map), value FIRST, then key [4]. This is the opposite of the natural reading order and is a common source of bugs. I’ll say it again to make sure it sticks: value first, key second.

Here is the correct pattern:

1
/**
2
 * Log all product name entries in the lookup Map for debugging.
3
 *
4
 * @author Gary Dotzlaw
5
 * @since 2026-06-11
6
 * @private
7
 *
8
 * @param {Map<Number, String>} mNames the product name Map to log
9
 * @return {void}
10
 */
11
function logProductNames(mNames) {
12
    mNames.forEach((sName, nId) => {
13
        // NOTE: value (sName) comes FIRST, key (nId) comes SECOND.
14
        // This is Map.forEach behavior per the ES6 spec [4].
15
        // DEBUG-only private helper; per-item output inside the loop is acceptable here.
16
        application.output(`Product ${nId}: ${sName}`, LOGGINGLEVEL.DEBUG);
17
    });
18
}

In Servoy 2025.12 with SVY-20596, the callback parameters sName and nId are automatically inferred from the Map’s declared generic type [2]. On 2025.09, before that auto-inference landed, you can assign the callback parameters to typed locals inside the callback body (for example /**@type {String}*/ const sNameTyped = sName;) if you want the editor to track their types, since an inline arrow parameter list has no line above each parameter to annotate.

For Set.forEach, the signature is function(value, value, set) where the first and second parameters are both the value [5]. The duplicate is there for API consistency with Map.forEach. In practice you only use the first parameter:

1
/**
2
 * Log all category codes in a Set for debugging.
3
 *
4
 * @author Gary Dotzlaw
5
 * @since 2026-06-11
6
 * @private
7
 *
8
 * @param {Set<String>} stCodes the Set of category codes
9
 * @return {void}
10
 */
11
function logCategoryCodes(stCodes) {
12
    stCodes.forEach((sCode) => {
13
        // DEBUG-only private helper; per-item output inside the loop is acceptable here.
14
        application.output('Category code: ' + sCode, LOGGINGLEVEL.DEBUG);
15
    });
16
}

forEach is the recommended iteration style in this codebase. The ES6 for...of loop also works on Map and Set (both implement Symbol.iterator in Rhino 1.8.0), but note that Rhino’s ES6 support does not include iterator closing on break, so a for...of loop that exits early via break may not trigger iterator cleanup. Using forEach sidesteps this entirely, and it is what house conventions recommend for collections.

Scope-level Maps as session caches#

A Map or Set declared at scope level in Servoy (for example, in globals.js) persists for the lifetime of that scope, which for the globals scope means the entire user session. This makes scope-level Maps a natural fit for session-duration caches: load once on first call, serve from memory for the rest of the session, clear on logout or on a business event that invalidates the data.

Keep in mind that a scope-level Map is in-memory storage only. It is not persisted when the Servoy application restarts, and JSON.stringify(new Map()) returns "{}", so you cannot round-trip a Map through a dataprovider or a database column directly. To persist a Map’s contents, convert to a plain object or array first.

A note on JSRecord-valued Maps#

A natural question is whether you can annotate a Map with a JSRecord value type, like Map<String, JSRecord<db:/myserver/crm_customer>>, to build a typed record cache. The JSRecord<db:/...> compound type is supported in scalar @type annotations for foundsets, so the mechanism is plausible. However, the 2025.09 release notes confirm the generic syntax with scalar type examples (Map<String, Number>, Set<Date>), and the specific form Map<String, JSRecord<db:/myserver/crm_customer>> has not been confirmed verbatim in vendor documentation as of the date of this tutorial. You can try it in your own 2025.09+ installation. If the IDE honours it, you get typed record retrieval; if not, annotate the value as JSRecord<db:/myserver/crm_customer> on the call site instead.

For this tutorial I use scalar value types (Map<Number, String>, Set<String>) as the primary showcase because the core teaching rests on the confirmed 2025.09 syntax.

Also worth knowing: the “tab-panels-map” article uses an Array#

If you have read the tutorial titled “Add Forms to Tab Panels using a Map,” note that the word “map” in that title is colloquial: the technique uses a plain JavaScript Array to maintain an ordered list of tab names, not an ES6 Map. It is a naming coincidence. The ES6 Map type this tutorial covers is a different thing entirely.

Putting the API in one place#

For quick reference, here are the methods you will reach for most often.

Map methods (source: MDN [4], Servoy 2025.09+ [1]):

Set methods (source: MDN [5], Servoy 2025.09+ [1]):

Key equality for both uses the SameValueZero algorithm: NaN equals NaN, and objects are compared by reference (two distinct objects with identical properties are not equal) [4].

Practical advantages#

Using typed Maps and Sets instead of plain objects has several advantages:

• IDE type safety. The @type annotation means the editor knows what .get() returns. You get autocomplete on the value and a type error if you misuse it.
• Clean, explicit API. .has(), .get(), .set(), .delete(), .size, and .clear() are purpose-built methods. No workarounds for counting, checking existence, or avoiding prototype collisions.
• Any-type keys. Numeric IDs stay numeric. Boolean flags stay boolean. Object references work as keys. No silent string coercion.
• Insertion-order iteration. Both Map and Set maintain insertion order, which is now guaranteed by the ES6 spec.
• Deduplication is automatic with Set. No manual indexOf checks.
• Less boilerplate. The old oCache pattern needed 30 to 50 lines to achieve what new Map() gives you in one.

Conclusion#

That concludes this Servoy tutorial on typed Maps and Sets. I hope you enjoyed it, and I look forward to bringing you more Servoy tutorials in the future.

References#

[1] Servoy, “Servoy 2025.09 Release Notes (SVY-18614: Typed Map and Set Support),” Servoy Documentation, 2025. https://docs.servoy.com/release-notes/release-notes/2025.09

[2] Servoy, “Servoy 2025.12 Release Notes (SVY-20595, SVY-20596: Strong Typing for Collections),” Servoy Documentation, 2025. https://docs.servoy.com/release-notes/release-notes/2025.12

[3] Mozilla Rhino, “Release Rhino 1.8.0,” GitHub, 2025. https://github.com/mozilla/rhino/releases/tag/Rhino1_8_0_Release

[4] MDN Web Docs, “Map,” Mozilla, 2024. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map

[5] MDN Web Docs, “Set,” Mozilla, 2024. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set

[6] G. Dotzlaw, “Modern JavaScript in Servoy: ES6+ Features with Rhino 1.8,” dotzlaw.com, 2026. /insights/servoy-tutorial-17-modern-javascript/

[7] G. Dotzlaw, “Using an Object as a Cache,” dotzlaw.com, 2013. /insights/servoy-tutorial-object-cache/

[8] G. Dotzlaw, “Typed Query Builder in Servoy,” dotzlaw.com, 2026. /insights/servoy-tutorial-19-typed-query-builder/

[9] G. Dotzlaw, “Typed Solution Model in Servoy,” dotzlaw.com, 2026. /insights/servoy-tutorial-20-typed-solution-model/