Making AutoMapper 9 About 10x Faster

In short, AutoMapper TypeScript v9 is faster, a lot faster. In the numbers I measured, upgrading from the last 8.x release (8.8.1) to 9.0 makes the common mapping path roughly 10x faster.

For the simple flat fixture:

Not only that, memory consumption gets better too. The flat class batch went from about 12.8MB allocated per 1,000 mapped objects to about 0.87MB, roughly 15x less transient garbage.

Numbers sound really nice but the point of this blog post is to show how AI can help some old OSS codebases get better and dive into those improvements.

The improvements wouldn’t be made possible without the help of AI. I’m not going to deny that. However, the work done in nartc/mapper is an honest collaborative work between myself and AI, along with the help of @kylecannon

Everything basically started with the following prompt when Fable 5 first dropped

1
/goal adversarial review the codebase and find top 10 things that can increase the performances of mapper, improve maintainabilities, while keeping the public APIs as minimally breaking as possible. Look into modern typescript ecosystem. Spawn subagents aggressively as needed.

The shape of the work

The 9.0 performance work came in two phases. Phase one was nine perf(core) commits, which is the part I can decompose commit by commit. Phase two was a single follow-up PR that shipped squashed, so it lands as one extra step at the very end.

Here is phase one. Measured cumulatively against the same benchmark harness, the flat class map() path looked like this:

Writing to the destination: what set() actually did

Every property that gets mapped has to be written into the destination somewhere. AutoMapper does this through an internal set() helper that takes a path like ['address', 'street'] and writes the value at the leaf.

Here is what the old set() did for one property write:

1
// set(destination, ['address', 'street'], 'Main St')
2

3
// level 1: 'address'
4
const { decomposedPath, base } = decomposePath(path); // allocates a { decomposedPath, base } object
5
assignEmpty(destination, base); // destination.address = {} if missing
6
value = set(
7
  destination[base],
8
  decomposedPath.slice(1), // allocates a fresh ['street'] array
9
  value,
10
);
11
return Object.assign(destination, { [base]: value }); // allocates a { address: ... } temp object
12

13
// level 2: 'street'
14
const { decomposedPath, base } = decomposePath(path); // allocates again
15
return Object.assign(obj, { [base]: value }); // allocates a { street: ... } temp object

Count the garbage: two decomposePath result objects, one sliced array, two single-key temp objects — five throwaway allocations to write one value. The temp objects exist purely so Object.assign can merge one key into an object we already hold a reference to.

The thing is… flat case pays too. Writing ['name'] still allocated the decomposePath object and the { name: value } temp object. So an 8-field flat mapping created 16 throwaway objects per mapped object, just for the writes.

The new set() walks the path by index and writes the leaf directly:

1
// set(destination, ['address', 'street'], 'Main St', index = 0)
2

3
const base = path[index]; // direct index access, no slice
4

5
// leaf? write it
6
if (index >= path.length - 1) {
7
  obj[base] = value;
8
  return object;
9
}
10

11
if (!Object.prototype.hasOwnProperty.call(obj, base)) {
12
  obj[base] = {}; // the only object we create is one the destination actually needs
13
}
14
set(obj[base], path, value, index + 1); // same path array, next index

Same destination, same result. The difference is what the allocator sees along the way. The flat case is now literally obj.name = value with no temp allocations, and the nested case only creates the intermediate {} objects that end up in the destination.

This one change took the flat map() from 1.79µs to 934ns.

The check that outlived its own job

The next commit deleted 11 lines from map(). And there’s a story to tell about this one as I went down the rabbit hole to try to prove the LLMs wrong for deleting it.

Previously, here is what was running on every MapInitialize member of every map() call:

1
// check if metadata as destinationMemberPath is null
2
const destinationMetadata = metadataMap.get(destinationIdentifier);
3
const hasNullMetadata =
4
  destinationMetadata &&
5
  destinationMetadata.find((metadata) =>
6
    isPrimitiveArrayEqual(
7
      metadata[MetadataClassId.propertyKeys],
8
      destinationMemberPath,
9
    ),
10
  ) === null;

Looks harmless right? Well, Array.prototype.find() returns the found element or undefined, not a null value. So hasNullMetadata has always been false. This is an O(members²) metadata scan (per member and per metadata again), per map() call.

Season 1, 2021. “Null metadata” check was real. Some members have no concrete type — an any-typed property, an arbitrary object. Their metadata says null, which means: do not try to nested-map this, just assign the value as-is. Back then this was computed once at config time and stored as a boolean in the mapping:

1
// 2021: decided at createMap, stored in the tuple, just read at map time
2
[mapInitialize(sourcePath), isMetadataNullAtKey(destinationPath)];

Season 2, 2022. I rewrote the internals, dropped the boolean from the tuple, and re-implemented the check as the per-call scan you see above — with the === null bug.

The bug was never noticed, not because it never came up, but because there’s another check that had quietly grown to cover it. When a member’s metadata is null on both sides, the mapping stores the pair [null, null], and the neighboring hasSameIdentifier check does this:

1
// null === null, and there is no registered mapping for (null, null)
2
// → "same identifier, nothing to map it with" → assign the value as-is
3
const hasSameIdentifier =
4
  sameIdentifierCandidate && !getMapping(mapper, null, null, true);

Which is exactly the treat-as-is behavior the 2021 boolean implemented.

Season 3, 2026. Delete the scan. Before removing it I went down the “what if find() finds an element whose value is null?” rabbit hole, and the answer is: no code path ever stores a null entry in the metadata array (nullness lives in what the entry’s metaFn() returns, one level deeper than the scan was looking), and even if one existed, the predicate would throw on null[propertyKeys] before find() could return it. I’m lucky that this never crashed.

Deleting it took another 23% off the clock and ~4 MB off the batch allocation.

The Proxy was cute

AutoMapper used to return a Proxy from createMapper().

1
return new Proxy({} as Mapper, {
2
  get(target, p, receiver) {
3
    if (p === STRATEGY) {
4
      /* lazy-init strategy, return it */
5
    }
6
    if (p === MAPPINGS) {
7
      /* lazy-init mappings Map, return it */
8
    }
9
    // ... 15 more branches ...
10
    if (p === "map") {
11
      // a brand new closure, allocated on every single access
12
      return (
13
        sourceObject,
14
        sourceIdentifier,
15
        destinationIdentifier,
16
        options,
17
      ) => {
18
        const mapping = getMapping(receiver /* ... */);
19
        // ... actual mapping work ...
20
      };
21
    }
22
    // ...
23
  },
24
});

Proxy can be a clean way to expose a nice API while keeping state hidden. But I don’t know what the hell I was on to use a Proxy for the Mapper, especially the mapper.map() call is on a very hot path of the entire library.

1. mapper.map fires the get trap
2. the trap walks an 18-branch if-else chain until it hits 'map'
3. that branch allocates a closure every time and returns it
4. you call that closure — and inside it, reading internal state like the strategy goes through the same trap all over again

The fix is, well, a good ol’ plain object. Methods defined once, internal state hung on symbol-keyed fields:

1
const mapper = {
2
  map(sourceObject, sourceIdentifier, destinationIdentifier, options) {
3
    const mapping = getMapping(mapper /* ... */);
4
    // ... same mapping work as before ...
5
  },
6
  mapArray(/* ... */) {
7
    // ...
8
  },
9
  // ... the rest, defined once ...
10
};
11

12
Object.defineProperties(mapper, {
13
  [MAPPINGS]: { value: mappings }, // eager, direct
14
  [STRATEGY]: {
15
    get() {
16
      // the one thing that stays lazy
17
      if (!strategy) strategy = strategyInitializer(mapper);
18
      return strategy;
19
    },
20
  },
21
});

Now mapper.map === mapper.map is true, the property load is monomorphic, and as a small bonus, stack traces stop showing Proxy stuff.

Replacing the Proxy with a plain object only showed an 8% improvement on top of previous commits. Which is like whatever but I took the Proxy fix and put it on the main branch and the improvement was almost 3.2x win on its own. So, still a big win in my book.

The real shift: stop interpreting the map

Saving the best for last as they say as I think this is the most significant change to AutoMapper TypeScript.

AutoMapper configuration is known at createMap() time. The source model, destination model, configured members, transformation types, nested mapping decisions, and a lot of member-level metadata are not mysteries by the time map() runs. In fact, they CANNOT be mysteries by the time map() runs.

But the old hot path behaved more like an interpreter. On every object, it would walk the mapping configuration, destructure tuples, rebuild lists, check transformation types, and decide what to do for each member again and again. Imagine a mapArray() over 1,000 items, Mapper would have to do this interpretation of each member over 1,000 times.

AI raises an excellent question when it first scans nartc/mapper: why are we asking the same question per object?

Well yeah, I didn’t really have an answer as to why and only responded: If something is known at createMap() time, map() should not rediscover it.

To see how much rediscovering was going on, you have to see how a mapping is stored internally: a deeply nested tuple. A single property’s configuration looks like this:

1
// one entry in the mapping's properties array
2
[
3
  ["address", "street"], // destination path
4
  [
5
    ,
6
    // (a hole)
7
    [
8
      transformationMapFn, // [type, fn, ...] — another tuple
9
      [preCondPredicate, preCondDefault],
10
    ],
11
  ],
12
  [destinationIdentifier, sourceIdentifier],
13
];

To my defense, at the time of writing AutoMapper TypeScript, the V8 engine wasn’t that good in terms of performance so tricks like using tuples with const enum as internal data structure was a good trick to ensure monomorphic reads.

However though, the problem was what the old map() did with it — per call, per member:

1
for (let i = 0; i < propsToMap.length; i++) {
2
 // re-destructure the nested tuple, with default fallbacks, every time
3
 const [
4
  destinationMemberPath,
5
  [, [transformationMapFn, [preCond, preCondDefault = undefined] = []]],
6
  [destinationMemberIdentifier, sourceMemberIdentifier] = [],
7
 ] = propsToMap[i];
8

9
 // recompute whether the identifiers are the same (invariant per mapping)
10
 let hasSameIdentifier = /* isMappableIdentifier(...) && ... */;
11

12
 // allocate a fresh setMember closure for this member
13
 const setMember = (valFn) => {
14
  /* try/catch around the write */
15
 };
16

17
 // rebuild the configured-keys list (identical every call)
18
 configuredKeys.push(destinationMemberPath[0]);
19

20
 // and finally: figure out what KIND of member this is... again, yeah again
21
 if (transformationMapFn[MapFnClassId.type] === TransformationType.MapInitialize) {
22
  // ... 60 lines of type checks, array checks, nested checks ...
23
  setMember(() => mapInitializedValue); // another thunk allocation
24
 } else {
25
  setMember(() => mapMember(transformationMapFn /* ... */)); // thunk + ANOTHER type switch inside
26
 }
27
}

None of these have different outputs between calls. The destructuring result is invariant. The configured keys are invariant. The transformation type is invariant. The identifier comparison is invariant.

Three commits turned this interpreter into more of a compiler.

• P7 destructures each tuple once into a flat descriptor and caches it. That took the flat path from 513ns to 393ns and cut batch allocation roughly in half again.
• P8 moves that build to createMap() and hangs it on the Mapping.
• P9 compiles each member into a specialized step closure, once, at createMap():

1
// at createMap — once per mapping
2
function compileStep(prop) {
3
 // hoist everything invariant into the closure, NOW:
4
 const mapInitializeFn = /* extracted from the tuple */;
5
 const sameIdentifierCandidate = /* the identifier comparison, decided once */;
6
 const destinationIsPrimitive = isPrimitiveConstructor(prop.destinationMemberIdentifier);
7
 // the TransformationType switch happens HERE, once —
8
 // each branch returns a different specialized closure
9

10
 return (ctx) => {
11
  // only per-object work survives to run time
12
  const value = mapInitializeFn(ctx.sourceObject);
13
  // ... assign it ...
14
 };
15
}
16

17
const steps = props.map(compileStep);

And map() collapses into a straight line:

1
// at map() — every call
2
const context = { sourceObject, destination, mapper /* ... */ }; // ONE object
3

4
for (let i = 0; i < steps.length; i++) {
5
  steps[i](context);
6
}

That’s it. The loop now just calls each step() closure with a context object that the steps would need. After P9, the flat class map() path landed at 335ns in the per-commit harness. That is where phase one ends: about 5.3x over the baseline.

Then @kylecannon steps in.

Phase two: the follow-up that doubled it again

To be honest, I had already called the hot path done at this point. 5.3x, compiled plan, happy. Kyle then opened a PR that took the same flat class map() from 335ns down to about 171ns — another rough doubling, on top of the one I had just spent nine commits earning. Truly humbling.

The PR shipped squashed into one commit, so I can’t slice it into a tidy waterfall the way I can for the nine. Allocation got cut again too: phase one had already taken the per-batch figure from 12.8MB down to 2.1MB, and this PR took it the rest of the way, down to about 0.87MB.

So where did the second doubling come from? Eighteen distinct optimizations by my count, but the hot-path story is three ideas.

First, mapFrom gets its own compiled step. After P9, every forMember(..., mapFrom(fn)) member still went through the generic dispatch — a thunk allocation into mapMember(), which switches on the transformation type again:

1
// before: the generic arm, even for the most common transform
2
return (ctx) => {
3
  setMemberValue(
4
    () => mapMember(transformationMapFn, ctx.sourceObject /* ... */), // thunk + type switch inside
5
    destinationMemberPath,
6
    ctx,
7
  );
8
};

mapFrom is by far the most common custom transform, and everything about it is known at createMap() time. So it gets its own specialized step — the selector called inline, nothing allocated:

1
// after: compileStep recognizes MapFrom and bakes the selector in
2
if (transformationType === TransformationType.MapFrom) {
3
  const mapFromFn = transformationMapFn[MapFnClassId.fn];
4
  return (ctx) => {
5
    assignResolved(mapFromFn(ctx.sourceObject), destinationMemberPath, ctx);
6
  };
7
}

The same idea P9 applied to the loop, just one level deeper.

Second, the curried writer gets un-curried. The member writer was a closure factory — setMemberFn(path, destination) returned a function that you then call with the value. One extra function allocation per member write, existing purely for the calling convention:

1
// before: allocate a writer, then call it
2
const setValue = ctx.setMemberFn(destinationMemberPath, ctx.destination);
3
setValue(value);
4

5
// after: just... pass the value
6
ctx.setMemberFn(destinationMemberPath, ctx.destination, value);

The closure survives only on the async arm, where a pending Promise genuinely needs to capture where its value goes. The sync path — the one you’re on 99% of the time — allocates nothing.

Third, the post-map check moves to config time. assertUnmappedProperties — the “did we miss anything?” check — was building a new Set(configuredKeys) and diffing it against the destination’s writable keys on every call. But which keys could possibly be unmapped is fixed the moment createMap() returns. So the residual list is precomputed once, and the per-call check becomes a walk over a usually-tiny, often-empty array. A mapArray() of 100,000 objects used to create 100,000 identical Sets to arrive at the same answer every single time.

Same rule, third appearance: if it’s knowable at createMap() time, it’s not allowed on the hot path.

The PR also went after createMap() itself. Some of that weight was phase one’s fault — an eagerly-built plan has to be built somewhere — and some of it was ancient: metadata storage re-spread the whole accumulated array per property ([...existing, item], O(P²) for a P-property class, now a push), the @AutoMap decorator had the same quadratic spread, and wide classes (over 30 properties) got a keyed metadata index instead of .find() scans. Plus a scalar fast-path so primitive values skip the Date/File tag checks entirely, and a shared options object in the mapArray() loop instead of a fresh one per element.

Does this only help toy objects?

That was the first thing I wanted to check, because the headline fixture is too simple: 8 flat fields. If a mapper only gets faster on a toy object, that is for show, but not very useful.

So I measured a few different shapes:

The engine-bound mappings get roughly 7-11x faster. Wide mappings benefit the most because the old per-property overhead scaled with field count, so removing it pays off once per field. Deep mappings and arrays still improve, but not magically more than flat ones, because their extra work is actual nested mapping work.

And if your mapping is dominated by an expensive mapFrom() function, the engine improvement basically disappears. If you spend 98% of your time inside your own transformation function, making the mapper engine faster can only help the remaining 2%. I would rather admit that than pretend every user will see 10x everywhere.

A correctness note about async

One 9.0 change is not a performance win at all.

The old mapAsync() path did not actually await async member resolvers. If a mapFrom() returned a Promise, the destination could receive the unresolved Promise instead of the resolved value. That made the old version look very fast in one specific way because it returned before the async work finished.

In 9.0, mapAsync() waits for async member work and assigns the settled value. For mapArrayAsync(), the mapper collects the pending work and awaits it concurrently with Promise.all(), so 50 objects with a 20ms async resolver do not become 50 x 20ms sequential work.

There is a migration caveat here. If some code accidentally relied on the old behavior, it will observe different timing and different output. But the old output was a leaked Promise, so I am comfortable calling this a correctness fix instead of a perf regression.

How I measured it

The numbers came from built artifacts, not TypeScript source running directly in a benchmark setup. The 8.8.1 baseline was the published package. The 9.0 numbers used the built ESM output a user would actually install.

For the per-commit waterfall, I held the 9.0 build toolchain constant and replayed each core source snapshot cumulatively. That way, the toolchain does not get to take credit for an algorithm change.

The machine was an Apple M5 Max on Node 22.14, using mitata, reporting medians from three runs. Micro-benchmarks are still micro-benchmarks. Real applications have I/O, cold starts, surrounding allocations, and plenty of other noise. So, the absolute numbers will vary.

The rule of thumb

The practical takeaway for me is pretty simple:

If the mapper knows something at createMap() time, map() should not rediscover it per object.

Thanks for reading, and have fun!

Benchmark notes: phase one measured 2026-06-21; headline and scenario numbers re-baselined 2026-06-23 against the current 9.0 tip. Apple M5 Max, Node 22.14. Phase-one per-commit references: fc11170, c313fa8, 21a0f28, 72edd19, 2bfef38, 49bfbf0, cb772ac, 038d14d, dabf047. Phase two: PR #632.