DEV Community: Syd Amir

The Nature of Data: Why Lesan's Relationships Win in the Real World

Syd Amir — Wed, 19 Aug 2026 11:27:16 +0000

In the last article we showed the mechanism — Lesan turns a ~2,550,250-document read into a ~25,250-document read by embedding relationships and keeping them in sync. This article answers the obvious objection: "But what about the writes?" The answer comes from the nature of data itself.

By the Lesan team · GitHub · Docs · Read part 1

1. The objection

Any engineer who reads Why Lesan — where embedded relationships turn a ~2.5-million-document request into a ~25-thousand-document one — asks the same question within seconds:

"OK, but you're duplicating data. Every time something changes, you have to update all those embedded copies. Isn't that a nightmare on writes?"

It's a fair question. Manual embedding is a nightmare on writes — we showed the updateMany + arrayFilters horror in part 1. The difference is that Lesan automates the sync. But the deeper objection remains: even automated, doesn't maintaining N embedded copies make every write N times more expensive?

The honest answer is: sometimes yes — and it doesn't matter. Because of the nature of data models, the writes that cost you the most are exactly the ones that happen least often.

Let's look at real projects to see why.

2. The law of data

Step back from frameworks for a moment and look at what data actually does in the wild:

A blog article is read thousands of times a day, but written once.
A social post is viewed millions of times, but created once.
A user updates their profile once or twice a year, but their content is read hundreds of thousands of times a day.
A product's description changes a few times a year, but it's browsed thousands of times a day.

There's a pattern here, and it's not a coincidence:

Expensive updates and deletions are rare. Cheap operations are frequent.

This is the nature of data models. Reading is what users do all day; writing is what happens occasionally. And critically — the operations that are expensive to maintain in an embedded world (updating a user who is embedded in a thousand articles) are precisely the operations that happen least often (a user updates their profile twice a year).

Every framework optimizes reads. Few stop to notice that the write side — the side they're terrified of — is rare because it's expensive, and cheap because it's frequent. Lesan was designed around this reality, and that's what makes it elegant rather than hacky.

3. The best case: a blog

Let's build a blog. The classic models: user, category, tag, and article. We'll focus on just user and article — the heart of any blog.

With Lesan we declare the relationship once, on the side that needs it, and embedding happens on both sides automatically:

const articleRelations = {
  author: {
    schemaName: "user",
    type: "single",
    relatedRelations: {
      articles: {
        type: "multiple",
        limit: 50,
        sort: { field: "_id", order: "desc" },
      },
    },
  },
};

The effect: an article embeds its author (a pure snapshot of the user: _id, name, avatar, bio), and a user embeds their 50 most recent articles. Both sides stay in sync on every insert, update, and delete — automatically, with zero extra code.

3.1 Reads: this is where a blog lives

A blog is a read machine. Look at all the ways an article is fetched:

the latest articles (home feed),
the best articles (by score or votes),
the most visited articles,
related articles (same category),
the article page itself,
the "more by this author" strip at the bottom of an article (6–7 more articles by the same author).

And almost every one of these needs the author next to the article — the byline, the avatar, the author page link.

In a classic stack, each of those read paths needs a join or a second query for the author. With Lesan, the author's _id and pure info are already embedded inside the article document. Every one of those read paths is served by the same snapshot:

author's _id → instant lookup of the author's full profile when needed,
author's pure info → already there, no query at all,
the "more by this author" strip → served by the user's embedded articles array (50 newest), fetched in the same request as the article.

The read cost collapses to a handful of documents — the same O(log n) win from part 1, applied to every single read path of a real blog.

3.2 Writes: the cost is tiny because it's rare

Now the part that scared us: when an article is updated or deleted, how many places does it live?

the article document itself, and
the author's embedded articles array — and even that is bounded: the array holds only the 50 newest articles, so Lesan touches it only when the changed article is actually inside that window. An article that has already fallen past the limit lives only in the article collection — there is nothing to sync.

That's two places. And how often does an article change? Once when it's written, and maybe once more when it's edited. Meanwhile it's read a million times.

A million reads against two writes.

The balance is absurdly good. The sync Lesan does on those two rare writes is nothing compared to the reads it saves on every single view.

3.3 The harder write: the user updates or deletes themselves

The genuinely expensive scenario is the user changing. Now every article embedding them must be refreshed. And that number could be large — a popular author with thousands of articles.

But how large, really? Think about the nature of a user:

A user who publishes every single day for a year has at most 365 articles.
Updating or deleting that user means touching up to 365 embedded snapshots — a bounded, knowable, one-time cost.
Meanwhile, those same 365 articles are read hundreds of thousands of times a day.

Millions of reads every day, against 365 writes once a year.

That's not a compromise. That's a steal. The worst case for a blog is bounded by how many articles one person can realistically write — and that number is nothing compared to how often those articles are read.

3.4 Why the blog is the "best case"

The blog is the best case because it's the typical case. Content platforms, news sites, documentation, forums, catalogs — they all have this shape:

a small set of content entities (articles, products, posts) written rarely,
each embedded in its parent (author, category, store) in a few bounded places,
read constantly in many different orderings (latest, best, most-visited, related).

Wherever the write cost is real, the write frequency is minuscule. Lesan's embedding spends a little on the rare writes to save a lot on the constant reads.

4. The worst case: population statistics

Now let's be honest — because if this article only showed the easy case, you'd be right to distrust it. There is a scenario where embedding seems catastrophic. And studying it is exactly what teaches us the most.

Imagine an app that stores population statistics: a country model and a human model.

The country is embedded inside each human (so a human always knows their country).
The last ~50 humans are embedded inside each country (for first-page pagination; the rest come from the human model on later pages, and the country is embedded in each human so the query stays optimal).

Same pattern as the blog. Then disaster strikes: the country has a population field, and it changes every 5 seconds. To keep the world consistent, every human of that country must have their embedded country snapshot refreshed. India. China. More than a billion updates every 5 seconds.

This is the moment embedding looks like the worst idea in engineering history. And it's a real concern — it's why many teams are terrified of denormalization.

4.1 Solution 1: exclude the volatile field

The first fix is trivial. Tell Lesan not to embed population into humans:

const humanRelations = {
  country: {
    schemaName: "country",
    type: "single",
    excludes: ["population"],   // don't copy this field into humans
    relatedRelations: {
      // humans embedded in country, last 50, as before
    },
  },
};

Now updating population touches only the country document. The humans still know their country (name, flag, _id), just not its live population. Problem solved. Hooray.

But let's not stop there — because there's a more interesting solution, and it's the one that reveals the heart of Lesan.

4.2 Solution 2: let the nature of data guide you — have children

Go back to the essence of the model. What is population, really?

It isn't a stable property like a country's name or abb. It's a history — a series of values changing over time. A field that changes every 5 seconds isn't a field; it's an entity that wants to be born.

So instead of a field, make it a model:

const populationRelations = {
  country: {
    schemaName: "country",
    type: "single",
    relatedRelations: {
      populations: {
        type: "multiple",
        limit: 50,
        sort: { field: "recordedAt", order: "desc" },
      },
    },
  },
};

Now:

a country embeds its last 50 population records, and
each population record embeds its country.

Both sides are stored together, synced automatically, and — crucially — the whole thing becomes analytically rich:

every population record carries its own timestamp,
you can chart a country's population history, not just its current number,
you can compute deltas, trends, and statistics from real data,
and the human model's embedded country snapshot can simply exclude the volatile data entirely.

Did you notice what happened? The Lesan mechanism itself guided you to a better, more professional model. Instead of "country + a billion fragile embedded copies," you now have "country + a tidy population model + humans" — each with clean, bounded relationships.

This isn't a coincidence of this example. It's a documented principle in the Lesan docs on relationships:

"Every frequently-changing field can become a relationship."

A field that changes often is a sign that a new model wants to be born. Lesan doesn't just tolerate that — it encourages it, because its relationship engine makes the birth cheap and safe. The concept page put it beautifully: "If the relationship leads to the birth of a child, both parties accept the relationship."

4.3 The economics of the fix

After the promotion, what does a write cost?

Insert a new population record: one insert into the population collection — plus the automatic embed into the country's last-50 array.
No update to the country. No update to a billion humans.

In the absolute worst case — compared to the naive design — you do two operations instead of one (the insert plus the embed). Against millions of reads for statistics and analytics, that is nothing.

And here's the beautiful part: you didn't just fix the problem. You upgraded the model. The naive "update a population field" design could only ever answer "what's the population right now?" The model-design fix can answer "how has the population changed over the last month?" — because the history now exists as data.

5. The general rule

Put the two archetypes together and you get a practical design law you can apply to any project:

Deep, read-heavy graphs (blog, catalog, map, feed, org chart) — embed the relations and enjoy O(log n) reads. The rare writes are cheap to maintain; the constant reads are where your users actually live.
Volatile fields (population, price, stock, status) — don't embed them into a billion documents. Either exclude them from the snapshot, or promote them into their own model and let Lesan maintain the relationship.
Wherever writes are expensive, they are rare. Design for the reads.

The nature of data models is on your side. All you have to do is notice it.

6. The takeaway

In part 1 we showed that Lesan turns a ~2,550,250-document read into a ~25,250-document read. The obvious objection was "but what about the writes?"

This article is the answer:

In a blog, writing an article means syncing two places, against a million reads.
Even the worst case — updating a user who published every day for a year — is 365 writes once a year, against millions of reads every day.
And the truly volatile fields (population changing every 5 seconds) aren't embedding problems at all — they're a sign that a new model should be born, and Lesan makes that birth elegant and safe.

Lesan isn't fast because it's clever. It's fast because it understood the nature of data first.

If you've read this far, try it: look at your own database, find your most-read entity, and ask "how many places does it live, and how often does each copy change?" You'll find the same asymmetry. That's the nature of data — and it's why Lesan feels like it was designed for the real world.

Resources

Part 1 — Why Lesan: turning O(n²) into O(log n)
The philosophy — What Is the Relationship Really?
Why MongoDB — Why NoSQL?
Lesan on GitHub: github.com/MiaadTeam/lesan
Docs: miaadteam.github.io/lesan
License: AGPL-3.0

Why Lesan: We Built a Framework That Turns O(n2) Queries Into O(log n)

Syd Amir — Wed, 19 Aug 2026 11:01:04 +0000

How one design decision — treating relationships as data that keeps itself in sync — makes Lesan return data hundreds of times faster than the stacks most of us use today.

By the Lesan team · GitHub · Docs · Read part 2

1. The problem: a "simple" request that kills your API

Imagine you run an application where users, provinces, and cities all belong to a country. Now the frontend asks for one screen:

"Give me all 250 countries, and for each one: the 50 most recent users, the 50 oldest users, the 50 most populous provinces, and for each province the 50 most recent and 50 oldest users — and the same for the 50 most populous cities."

That's not an exotic request. It's a dashboard. A map view. An admin panel. And yet, in the most popular stacks on earth, this single screen is a performance disaster.

Let's count what has to happen:

Level	What you fetch	Documents
1	250 countries, by population	250
2	50 recent + 50 oldest users per country	250 × 2 × 50
3	50 populous provinces per country	250 × 50
4	50 recent + 50 oldest users per province	250 × 50 × 2 × 50
5	50 populous cities per country	250 × 50
6	50 recent + 50 oldest users per city	250 × 50 × 2 × 50
	Total	≈ 2,550,250 documents

Two and a half million documents — collected, joined, sorted, and assembled — just to paint one screen. And if your backend is doing this in a nested loop of ORM queries, you're not only paying for the database work; you're paying for 2.5 million network round-trips between your server and your database.

Now here's the uncomfortable question nobody in the "just use Prisma/Mongoose" world asks: why do we accept this as normal?

2. What is Lesan?

Lesan is a cross-platform TypeScript web framework + ODM for MongoDB that runs on Node.js, Bun, and Deno from a single codebase. It gives you:

Models — pure fields + relations, validated with superstruct at runtime.
Acts — your API endpoints, defined with per-act validators (set for input, get for output).
Client-driven projections — like GraphQL, the client chooses which fields (and how deep) it wants back, with no query language, no schema introspection server, and no backend refactoring when the frontend needs more.
Embedded, self-syncing relationships — the part this article is about.
A request pipeline (POST /lesan) that validates the model → act → input, runs optional auth hooks, executes the act, and applies the projection — all over a single endpoint.

The same lesan() factory, the same models, the same acts, run unmodified on Node.js, Bun, or Deno. There's no build step to install a runtime-specific backend: the framework is a thin layer over the official MongoDB driver plus the platform's native HTTP.

Lesan is open source: github.com/MiaadTeam/lesan. It's also used in production by real applications (including ZiWound, a war-crimes documentation platform with 13 models and 98 acts).

But let's get to the heart of it.

3. The core idea: relationships as self-maintaining data

Every modern web framework treats relationships as something you compute at read time. You store foreign keys; when a client asks for a country with its provinces, the framework joins — in SQL with JOINs, in MongoDB with $lookup or a nested find loop.

Lesan flips this. Relationships are one-directional in definition, but embedded bi-directionally in storage — and Lesan keeps the embedded copies in sync for you.

Concretely: when you define a province that belongs to a country, Lesan automatically embeds a snapshot of that province inside the country document, and a snapshot of the country inside the province document. When a province is inserted, updated, or deleted, Lesan updates every embedded copy automatically. You, the backend developer, write zero sync code.

Let's see what that looks like. This is the complete model definition from the article's companion example:

const pure = {
  name: string(),
  population: number(),
  abb: string(),
};

const countryRelations = {};
const countries = coreApp.odm.newModel(
  "country",
  pure,
  countryRelations,
);

const provinceRelations = {
  country: {
    optional: false,
    schemaName: "country",
    type: "single",
    relatedRelations: {
      provinces: {
        type: "multiple",
        limit: 50,
        sort: { field: "_id", order: "desc" },
      },
      provincesByPopulation: {
        type: "multiple",
        limit: 50,
        sort: { field: "population", order: "desc" },
      },
    },
  },
};

const provinces = coreApp.odm.newModel(
  "province",
  pure,
  provinceRelations,
);

Read the relatedRelations block like a contract: "when a province points at a country, that country gains two fields — provinces, the 50 newest provinces, and provincesByPopulation, the 50 most populous provinces."

Two embedded, pre-sorted, limited arrays. Kept in sync by Lesan. Two different orderings of the same data, stored and maintained for free.

Why two arrays?

Because in a real app you need both orderings. The recent-items list (dashboard) and the by-population list (map). In a classic setup you'd write two queries per country. Here, both arrays already live inside the country document, already sorted, already limited — so reading them is a single document fetch with zero sorting at read time.

What's actually stored, and what isn't

Two details matter here, and both are easy to miss:

The back-reference arrays are stored on the target, not the source. provinces and provincesByPopulation live inside the country document. The province document itself only stores a country snapshot. Lesan builds this from a single declaration — the province says "I belong to a country," and Lesan derives the reverse side automatically. This is the opposite of how most ODMs work, where you'd hand-maintain country.provinces yourself.
Each embedded entry is a pure projection, not a full document. Lesan embeds only the pure fields of the province (plus the relation's declared excludes). You decide what a province snapshot carries when you define the model. That's what keeps a provinces array of 50 small, and what keeps the country document far below MongoDB's 16 MB limit even as it accumulates several such arrays.

Because the embedded copies are pure projections, the system also has a bounded, predictable cost model: limit caps array length, excludes caps entry size, and the number of back-references is fixed at model-definition time. No hidden growth, no surprise bloat.

The "one step less depth" principle

Lesan's read path has a simple rule: for each request, penetrate one level less than a naive traversal would. In a classic stack, fetching countries → provinces → cities → users means at each level you issue a query against the child collection. With embedded snapshots, the children are already inside the parent document — so the deep query that would touch three collections instead reads one collection (the countries) and lets the projection engine resolve the embedded levels that are already present. The result is that a relationship that used to require a round-trip now costs nothing at read time — it was paid for, once, at write time.

4. The magic, in code: insert a province, and everything updates

Now the writes. Adding a country needs no relation code at all:

const addCountryValidator = () => {
  return object({
    set: object(pure),
    get: coreApp.schemas.selectStruct("country", 1),
  });
};

const addCountry: ActFn = async (body) => {
  const { name, population, abb } = body.details.set;
  return await countries.insertOne({
    doc: { name, population, abb },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "country",
  actName: "addCountry",
  validator: addCountryValidator(),
  fn: addCountry,
});

Adding a province takes the country's _id and — that's it:

const addProvinceValidator = () => {
  return object({
    set: object({ ...pure, countryId: objectIdValidation }),
    get: coreApp.schemas.selectStruct("province", 1),
  });
};

const addProvince: ActFn = async (body) => {
  const { name, population, abb, countryId } = body.details.set;
  return await provinces.insertOne({
    doc: { name, population, abb },
    relations: {
      country: {
        _ids: new ObjectId(countryId),
        relatedRelations: {
          provinces: true,
          provincesByPopulation: true,
        },
      },
    },
    projection: body.details.get,
  });
};

coreApp.acts.setAct({
  schema: "province",
  actName: "addProvince",
  validator: addProvinceValidator(),
  fn: addProvince,
});

That's the entire relation-handling code for inserting a province: declare the target, declare which relatedRelations to refresh, done. Lesan:

Inserts the province document.
Embeds a province snapshot inside the country's provinces array (positioned by _id sort).
Embeds a province snapshot inside the country's provincesByPopulation array (positioned by population sort).
Embeds a country snapshot inside the province (the forward side).
Evicts the 51st-oldest entries to respect each limit: 50.

The same thing happens on update and delete — automatically, with zero extra code. If the province's population changes, Lesan re-sorts provincesByPopulation. If the province is deleted, both arrays are repaired. No arrayFilters, no updateMany, no sagas, no sync jobs.

The embedded snapshots are also pure projections (just the fields you care about, trimmed via excludes) — so a 50-item array of full provinces never bloat a country document past MongoDB's 16 MB ceiling.

5. The numbers: O(n²) becomes O(log n)

Here's the payoff. Revisit the million-document request from section 1 — now against Lesan:

The 250 countries are 250 documents — one query.
Each country document already contains its 50 recent users, 50 oldest users, 50 populous provinces, 50 populous cities — embedded and pre-sorted.

So fetching the whole tree is just the 250 country documents.

Stack	Documents fetched
PostgreSQL (nested queries / ORM)	~2,550,250
MongoDB (nested `find` loop)	~2,550,250
MongoDB (`$lookup` pipelines)	~2,550,250 (one pipeline, but still massive join work)
Lesan	25,250

Wait — why 25,250 and not 250? Because at selectStruct("country", 2) depth 2, you ask for countries → provinces/cities → users. The users embedded inside provinces/cities are fetched by Lesan's projection engine at that deeper level. Still — 25,250 documents instead of 2,550,250 is a ~100× reduction, and those 25,250 come back in a handful of database round-trips instead of thousands.

In complexity terms: a naive N+1-style traversal is O(n²) (actually O(n^depth) — with three levels of nesting, it's n^3). Lesan's embedded model reduces the collection work to O(log n) — the embedded arrays are just fields of a document you already fetched. More importantly, it removes the 2.5 million network round-trips between server and database, which is where most of your latency actually lives.

Let me be careful about what O(log n) means here, because a reviewer will (rightly) poke at it. The claim isn't that MongoDB has magical indexing on embedded arrays. The claim is about your code's data-collection cost: the number of documents your application must fetch and assemble to answer a deep request. In a nested-query stack that number grows with the product of the depth and the fan-out (n × m × k). In Lesan, the deep levels are already inside the documents you fetch at the top level — so the application-level cost of that same request is dominated by the top-level documents, which scales as O(log n) (a handful of index hits). MongoDB's index on _id (and on any createIndex you declare) is what makes each of those lookups logarithmic.

Where the "25,250" comes from

In the example above I set selectStruct("country", 2) — depth 2 — which means: countries at the top level, provinces/cities at depth 1 (already embedded in the country documents), and their users at depth 2 (already embedded in the province/city snapshots). Because every level below the top is embedded, the only collection query is for the 250 country documents; the users inside provinces and cities are resolved from the already-fetched snapshots by the projection engine. So:

250 country documents — one indexed query.
25,000 users — already inside those 250 documents as embedded snapshots.

Total application-level work: 25,250 documents. Same screen, same data, ~100× less fetching.

And here's the part that matters even more than the document count: the classic stack doesn't just fetch 2.5M documents — it fetches them as 2.5M sequential round-trips in an N+1 loop (or one giant pipeline that materializes all of them in memory). The dominant cost in real systems is usually that per-query overhead and the wire time, not the documents themselves. Lesan collapses 2.5M round-trips into one query.

Let's make this concrete with the read act:

const getCountriesValidator = () => {
  return object({
    set: object({}),
    get: coreApp.schemas.selectStruct("country", 2),
  });
};

const getCountries: ActFn = async (body) => {
  const { set, get } = body.details;
  return await countries
    .aggregation({ pipeline: [], projection: get })
    .toArray();
};

coreApp.acts.setAct({
  schema: "country",
  actName: "getCountries",
  validator: getCountriesValidator(),
  fn: getCountries,
});

The backend act is tiny — because the client decides what to fetch. A single POST carries the projection tree:

POST http://localhost:7500/lesan
{
  "service": "main",
  "model": "country",
  "act": "getCountries",
  "details": {
    "set": { "page": 1, "limit": 250 },
    "get": {
      "_id": 1,
      "name": 1,
      "population": 1,
      "provincesByPopulation": {
        "_id": 1, "name": 1, "population": 1,
        "users": { "_id": 1, "name": 1, "family": 1, "age": 1 },
        "usersByAge": { "_id": 1, "name": 1, "family": 1, "age": 1 }
      }
    }
  }
}

The client asks, Lesan answers. No new endpoint, no backend refactor, no GraphQL schema to maintain.

6. What you no longer have to write

The draft of this article contained a very long section on what manual embedding costs. Let me show you why Lesan exists, by showing you the alternative.

If you embed data yourself, you must keep it in sync by hand. Here is a minimal version of updating one user across the nested arrays of just two collections — using MongoDB's updateMany with arrayFilters:

// WITHOUT Lesan: update one user across every place they're embedded
await db.collection('countries').updateMany(
  { "recentUsers.userId": userId },
  { $set: { "recentUsers.$[elem]": updatedUserData } },
  { arrayFilters: [{ "elem.userId": userId }] }
);

await db.collection('countries').updateMany(
  { "oldestUsers.userId": userId },
  { $set: { "oldestUsers.$[elem]": updatedUserData } },
  { arrayFilters: [{ "elem.userId": userId }] }
);

await db.collection('countries').updateMany(
  { "provinces.recentUsers.userId": userId },
  { $set: { "provinces.$[].recentUsers.$[elem]": updatedUserData } },
  { arrayFilters: [{ "elem.userId": userId }] }
);

await db.collection('countries').updateMany(
  { "provinces.oldestUsers.userId": userId },
  { $set: { "provinces.$[].oldestUsers.$[elem]": updatedUserData } },
  { arrayFilters: [{ "elem.userId": userId }] }
);

Now multiply that by: cities, the forward-side snapshots, the second (by-population) ordering, deletes, and the subtle bugs where a user moves between provinces and their old snapshot lingers. This is exactly the class of bug that produces stale data in production — and it's why most teams simply give up on embedding and go back to joins.

Why the manual approach always breaks

Three structural problems doom hand-rolled embedding at scale:

The update fan-out is unbounded. Every write must find every document that could contain a snapshot — which is every document in every collection that ever referenced this entity. You can't $set your way out of a 50-item sorted array that needs re-sorting; you have to remove the stale entry and re-insert the updated one in the right position, for every ordering you maintain, across every referencing document.
Delete is the worst case. Removing a province means walking every country, every ordering, and any parent that transitively embedded it. Miss one spot and you've shipped a phantom record to your users.
Consistency is eventual — at best. There's no transaction across your N updateMany calls. A crash mid-way leaves your data in a half-updated state with no reconciliation job.

Lesan removes this entire class of code and these failure modes. Update the user document once; every embedded copy is re-projected automatically. The update/delete sync engine handles forward + reverse propagation, sort-window maintenance, and limit eviction — tested, not trusted.

7. The real benchmarks

The query-count argument is architectural. But we also ran actual head-to-head benchmarks against real stacks, and the results back up the claim. You can reproduce everything in the MiaadTeam/benchmark repo.

Client response time — vs the same request on other stacks

Stack	Lesan is faster by
vs `prisma-express-rest` (PostgreSQL)	1,168%
vs `prisma-express-graphql` (PostgreSQL)	1,417%
vs `mongoose-express-rest` (unsorted)	4,435%
vs `mongo-express-rest` (unsorted)	72,289%
vs `mongoose-express-rest` (with sort)	298,971%

Formula: (B − A) ÷ A × 100. The chart lives in the repo: chart.svg.

Honesty note: these are relative numbers. 298,971% sounds absurd because the baseline (mongoose-express-rest with a sort over a nested traversal) is catastrophically slow — that's the point. The absolute takeaway is the same: nested-query stacks pay for the same data many times over, and Lesan pays once.

HTTP throughput — Lesan's own server

Lesan's server handles over 10,000 requests/second on Bun and Deno, with sub-10 ms latency — because it's just the platform's native HTTP on top of the official MongoDB driver. (Full cross-runtime numbers in the benchmarks doc.)

8. Tradeoffs: when NOT to use Lesan

No engineering decision is free, and the HN/Reddit crowd will (correctly) push on this. Here's the honest version.

Embedding trades write cost for read cost. Every insert/update/delete that touches a relationship touches the embedded copies too. For write-heavy workloads where the reads don't need the depth, this is extra work. Lesan mitigates it with limit, excludes, and pure projections — but it's a real consideration.

Duplication is real. The same province appears in provinces, provincesByPopulation, and its own collection. That's storage overhead — but each embedded copy is a pure projection (a trimmed snapshot), not a full document. In practice the duplication is a small fraction of total size, and it's the price of O(log n) reads.

The 16 MB document ceiling. MongoDB documents cap at 16 MB. Lesan's limit on every back-reference is exactly what keeps a country from accumulating 100,000 embedded provinces. Design your limit/excludes and you never approach the ceiling.

High-cardinality reverse lists. If one document legitimately needs all 100,000 children embedded, embedding is the wrong tool — keep the back-reference limited and query the child collection with an index instead.

When embedding is overkill. If your relations are shallow and your reads are simple single-document fetches, Lesan still works perfectly — it just won't be the dramatic win. The win is proportional to relationship depth.

The maintenance cost of the sync engine itself. Every relationship operation runs Lesan's relation pipeline (forward + reverse projection, sort windows, limit eviction). For most workloads this is negligible next to the read savings — but it's real. Lesan's answer is to keep the pipeline small, index-driven, and to let you tune limit/excludes so each sync touches as little data as possible.

When is Lesan the right choice?

In practice the profile that wins is: deep, read-heavy relationship graphs with bounded fan-out per node — exactly the shape of dashboards, content trees, map views, org charts, catalogs, and social feeds. If you're building one of those, the tradeoff is heavily in Lesan's favor: you trade a little extra write work and storage for reads that are an order of magnitude cheaper to fetch and, more importantly, an order of magnitude fewer round-trips.

If your workload is write-heavy with shallow reads — a write-only event logger, a pure time-series ingest — embedding buys you little, and Lesan won't be dramatically faster than anything else. It still runs correctly and cross-platform; it just won't be the story of this article.

9. Run it yourself

Everything in this article runs on your machine in minutes. The full example lives in the repo at examples/whyLesan/performance.ts — all four models, the embedded relations, and the acts, exactly as written above.

# requires MongoDB + Deno (or Node/Bun)
deno run -A examples/whyLesan/performance.ts

Then open the Lesan Playground, add a country, add a province with a countryId, and inspect the country document in Mongo Compass — you'll see provinces and provincesByPopulation, both already sorted and limited. Then call getCountries with the projection above and watch the whole tree come back in one shot.

10. Conclusion

The database industry spent decades optimizing queries. Lesan's bet is different: if the data you need is already embedded, sorted, and in the document, the query barely has to exist.

Relationships are one-directional in definition, embedded bi-directionally in storage, and self-syncing.
Reads drop from ~2.5 million documents to ~25 thousand for the same screen — from O(n²)-style nested traversals to O(log n).
You stop writing updateMany + arrayFilters sync code, and you stop shipping stale-data bugs.
It's cross-platform (Node.js / Bun / Deno), GraphQL-like (client-driven projections), and open source.

We built Lesan because we were tired of watching dashboards do 2.5 million queries to paint one screen. If that pain sounds familiar — try it, benchmark it against your own stack, and open an issue if you think we're wrong. We'd love to be proven right.

Resources

Read this article on Medium: Why Lesan: We Built a Framework That Turns O(n²) Queries Into O(log n)
Part 2 — The Nature of Data: Why Lesan's Relationships Win in the Real World
Lesan on GitHub: github.com/MiaadTeam/lesan
Docs: miaadteam.github.io/lesan
Benchmark repo (reproduce everything): github.com/MiaadTeam/benchmark
Companion example: examples/whyLesan
Intro video (Farsi)
License: AGPL-3.0