DEV Community: babyfish-ct

A Node Optimization Idea: Solving GC Bottlenecks Under Concurrency

babyfish-ct — Thu, 26 Mar 2026 13:15:50 +0000

What If Node.js Could Have Zero-GC Request Handling — Without You Changing a Single Line of Code?

A Proposal for a Hybrid Arena + GC Memory Model Baked into the JavaScript Runtime

Original link: https://github.com/orgs/nodejs/discussions/5143

The Problem Nobody Talks About Enough

Node.js handles millions of requests per day in production systems worldwide. And yet, the GC pause problem never truly goes away.

You know the symptom: p99 latency spikes. Not p50, not p95 — but that brutal p99 tail that your SLA demands you fix, and that you can never quite eliminate. The culprit is almost always the same: V8's garbage collector kicking in at the worst possible moment, pausing your event loop, freezing your in-flight requests.

The standard advice? Tune --max-old-space-size. Reduce allocations. Use object pooling. Profile with --trace-gc.

These are band-aids. They don't address the root cause.

The root cause is this: V8 has no idea where your request boundaries are.

It doesn't know that the 300 objects you just allocated for request #4821 will all be dead in 12 milliseconds when the response is sent. It just sees a heap full of objects and runs its mark-and-sweep algorithm on its own schedule, indiscriminately.

What if the runtime did know? What if it could use that knowledge to make almost all of your request objects essentially free to allocate and free?

The Idea: Request-Scoped Arena Allocation, Invisible to Developers

Here's the core proposal, stated simply:

When a short-lived request (e.g., HTTP request/response cycle) enters the Node.js runtime, the runtime automatically creates an Arena — a contiguous memory region — bound to that request's async context. All JavaScript objects allocated during that request's async scope are placed in this Arena. If the request is lucky enough, when it ends, all JavaScript objects are no longer useful, and the entire arena is released in a single operation. No GC needed.

What's discussed here is the lucky scenario; the unlucky scenario will be discussed later.

The Architecture: Dual Heap with Address-Masked Write Barriers

The Core Solution: Rather than forcing the GC to guess which small fraction of objects are short-lived, let the GC expose an SPI — and let the Node layer use that SPI to tell the GC what is actually true in real-world business workloads: the majority of objects are short-lived.

The end goal: business code remains completely unaware that any of this is happening.

Two Heaps, Not One

The fundamental architectural choice is a dual heap model:

GC Heap: The standard V8 managed heap. All long-lived objects live here. GC traces, marks, and sweeps this heap as normal.
Arena Heap: A separate memory region, outside the GC heap's address range, used exclusively for Arena-allocated objects.

heap membership is determined entirely by address range. An object is an Arena object if and only if its address falls within the Arena Heap's address range. No object header modification. No layout disruption to V8's densely packed object format.

The GC exposes the following SPI:

Arena *createArena();
void releaseArena(Arena *arena);
void setContextArena(Arena *arena);

createArena: Allocates an Arena from the Arena heap. Initially small (e.g., 1KB), but supports dynamic growth via a linked chunk chain.
releaseArena: Releases the Arena, all objects residing within it are automatically destroyed.
setContextArena: Sets the Arena for the current main thread context.

The mechanism works as follows:

When Node begins processing a request, it creates an Arena. Once all async flows complete — regardless of success or failure — the Arena is released. Throughout this process, the Arena context is tracked by the associated AsyncContext.
When the main thread gains control, it sets the Arena context. Before yielding control, it sets it back to NULL.
Whenever the main thread creates a JavaScript object, the following rules apply:
- Large objects ignore the Arena context entirely and are allocated directly on the GC heap — born as GC objects from the start.
- If the current Arena context is NULL, the object is allocated directly on the GC heap — born as a GC object. This covers all scenarios where no one has called the SPI, especially non-Node environments.
- If the current Arena context is non-NULL, memory is allocated from the current Arena, yielding an Arena object rather than a GC object.

The Invariant

The scenario discussed earlier — where all JavaScript objects in the arena are no longer useful upon request completion — is a very lucky case. However, reality is not always so ideal.

One invariant governs the entire model:

Arena objects may reference GC objects. GC objects must never reference Arena objects.

Arena objects holding references into the GC heap is perfectly safe — GC objects outlive the Arena, so those references are always valid. The dangerous direction is the reverse: a GC object referencing an Arena object would become a dangling pointer the moment the Arena is freed.

Write Barrier via Address Masking

V8 already maintains write barriers for generational GC. This proposal extends the write barrier with a single, extremely cheap check:

on every reference write: target[field] = value

  if address_of(value) is in Arena Heap range:
    if address_of(target) is NOT in Arena Heap range:
      // GC object attempting to hold Arena reference → promote
      promote(value)

The address range check is implemented as a bitmask operation — one AND, one compare. This is effectively free in the context of a write barrier that already runs on every reference write. No hash lookups, no metadata tables, no object header reads.

When promote(value) is triggered, a depth-first traversal from value promotes all reachable Arena objects to the GC heap, ensuring the invariant is restored before the write completes.

The Write barrier is important. This promote mechanism is critical to prevent dangling pointers caused by premature Arena release.

Arena-Tagged Allocation

When a short-lived async context is created (e.g., HTTP request), Node creates an Arena in the Arena Heap and associates it with that context via AsyncContext. All allocations within this context use pointer-bump allocation within the Arena. When no Arena context is active — including all non-Node environments and long-lived connection scenarios — allocation falls through to the standard GC heap.

Request Completion = Arena Release

When the async context ends, the Arena is freed in a single operation — one free() call, potentially releasing thousands of objects simultaneously. No tracing, no marking, no sweeping.

This Is Generational GC — Reimagined for Business Workloads

It is worth being explicit about what this model is at a deeper level.

This is a variant of generational garbage collection.

Classical generational GC is built on the generational hypothesis: most objects die young. The young generation is a small, fast-collected region; objects that survive enough GC cycles are promoted to the old generation.

This proposal takes the same hypothesis and applies it with business domain knowledge that the GC runtime has never had before:

Classical young generation: small (a few MB), collected every few milliseconds, objects survive by outlasting GC cycles
Arena generation: as large as a request demands, collected exactly once (at request end), objects survive by being explicitly promoted

The key insight is that for high-throughput HTTP workloads, the request boundary is a far more precise and meaningful lifetime boundary than anything a generic GC cycle can infer. Rather than letting the GC guess which objects are short-lived by watching allocation pressure, we tell the runtime exactly where the lifetime boundary is.

The Arena is a young generation that perfectly matches the business workload's actual object lifetime distribution. It is not a small, eagerly-collected nursery — it is a request-sized generation that is collected exactly once, with zero tracing overhead, at exactly the right moment.

Why This Works: Most Objects Are Boring

The insight that makes this viable is embarrassingly simple:

The vast majority of objects in a typical web request have a lifespan of exactly one request.

Your ORM query result? Dead at response time. Your DTO? Dead at response time. Your middleware context object? Dead at response time. Your parsed JSON body? Dead at response time.

In a well-structured Node.js application, perhaps 95%+ of allocated objects never escape the request that created them. They're born, used, and should die together. But today's GC doesn't know this — so it treats them the same as long-lived objects, tracing them repeatedly before eventually collecting them.

With request-scoped Arenas, these objects cost almost nothing:

Allocation: pointer bump. Near zero cost.
Deallocation: the entire Arena is freed at once when the request ends. Near zero cost per object.
GC involvement: zero. The GC never sees these objects at all.

The minority of objects that genuinely escape — items placed in a Redis-like in-memory cache, singleton services, WebSocket state — are promoted by the runtime when a cross-boundary write is detected, and the GC handles them normally.

Invariants

The model maintains two critical invariants:

No cross-heap references from GC to Arena: After promotion, no GC-managed object may reference an Arena object. The write barrier enforces this by promoting entire reachable subgraphs when escape is detected.
Arena objects are request-scoped: All objects allocated within an Arena share exactly one lifetime — the request that created them. An Arena object cannot outlive its request without being explicitly promoted to the GC heap.

These invariants guarantee that when a request completes, the entire Arena can be freed in a single operation without risk of dangling pointers.

Zero Developer Awareness Required

This is not a new allocator API for application developers. This is not a pragma or annotation. This is not a new language feature.

You write:

app.get('/users/:id', async (req, res) => {
  const user = await db.findUser(req.params.id);  // Arena allocated
  const dto = transformUser(user);                 // Arena allocated
  const response = buildResponse(dto);             // Arena allocated
  res.json(response);
  // Request ends → Arena freed → all of the above gone instantly
});

Nothing changes. No arena.alloc(). No defer arena.free(). No lifetime annotations. Your existing code, your existing third-party libraries, your existing ORM — all of it silently benefits. express, fastify, koa — they all just work. Because this lives entirely inside the runtime.

The `promote()` Case: When You Actually Need Global State

const cache = new Map(); // GC-managed (module scope, no Arena)

app.get('/config', async (req, res) => {
  const config = await loadConfig(); // Arena allocated initially
  cache.set('config', config);       // Write barrier fires!
                                     // address_of(config) → Arena Heap range
                                     // address_of(cache entry) → GC Heap range
                                     // → promote(config) triggered
                                     // config and its entire object graph move to GC heap
  res.json(config);
});

The developer wrote nothing special. The write barrier detected the address range violation and promoted the object graph automatically. config is now GC-managed and lives until removed from cache. All other objects from this request still die with the Arena.

Bonus: Async JSON Serialization via libuv Thread Pool

One additional optimization becomes possible under this model — and it addresses a long-standing Node.js pain point: JSON.stringify blocking the main thread.

Under this proposal, the runtime knows at serialization time whether the root object being serialized is a GC object or an Arena object. This distinction opens a new optimization path:

Case A: GC root — The object graph may contain long-lived references and shared state. Serialization proceeds on the main thread as today. No change.

Case B: Arena root — The object graph is request-scoped. It is, by construction, not shared with any other concurrent request. This makes it safe to serialize off the main thread.

When the serialization root is an Arena object, the runtime dispatches a serialization task to libuv's thread pool. The I/O thread walks the object graph and serializes it. If it encounters a reference to a GC object (which is valid — Arena objects may reference GC objects), it writes a placeholder in the output buffer and records the reference.

When the I/O thread completes, control returns to the main thread. If placeholders exist, the main thread serializes only those GC-rooted fragments and splices them into the output. If no placeholders exist, the result is ready immediately.

In the common case — a fully Arena-rooted response object with no GC references — JSON.stringify completes entirely off the main thread, with zero main thread blocking time.

This is particularly significant for large API responses: the serialization of a 500KB response object currently occupies the event loop for the entire duration. Under this model, that work moves to a background thread, keeping the event loop free to accept and begin processing the next request.

Note: This optimization is proposed here as a direction worth exploring, not a fully specified design. The interaction between Arena lifetime, thread safety, and GC object references during concurrent serialization requires careful analysis. It is presented to illustrate the broader potential of the dual-heap model beyond GC pressure reduction.

Edge Cases: When Arena Is Not Used

Not all asynchronous contexts are suitable for Arena allocation:

WebSockets and SSE: Long-lived connections spanning minutes or hours bypass Arena allocation. The runtime detects these persistent contexts and allocates directly to the GC heap.
Streaming responses: The runtime may create a fresh Arena per chunk rather than per request.
Nested request contexts: When one request spawns another (e.g., internal fetch), the child inherits the parent's Arena by default.
Non-Node environments: CLI tools, build scripts, long-running background workers — none of these set Arena*, so they see exactly the same behavior as today.

The decision is made at context creation time based on the async resource type. HTTP request/response is the primary beneficiary. Everything else is unchanged.

Comparison With Existing Approaches

Approach	Pros	Cons
Object pooling	Reuses objects, reduces allocation	Requires developer effort; only works for specific types
Reducing allocations	Less GC pressure	Fights JavaScript's grain; makes code ugly
Bun / JavaScriptCore	Faster I/O, native code	Same GC model; doesn't solve the root problem
Rust/Go rewrite	Zero GC, predictable latency	Discards ecosystem and team knowledge
This proposal	Zero developer effort; all existing code benefits; solves the root cause	Requires V8 implementation work

The Hard Parts (Being Honest)

This is not a trivial change to V8. The challenges are real:

Dual heap address space management: Reserving and managing a separate Arena Heap address range requires coordination with the OS allocator and V8's existing memory management. The address masking approach avoids object header changes but requires careful virtual memory layout.
Write barrier completeness: The address-range write barrier must cover all reference write paths — compiled JIT code, interpreter, native extensions, WeakMaps, and internal V8 structures. Missing one path is a memory safety bug.
Promotion atomicity: The DFS traversal that promotes an object graph must be atomic with respect to JavaScript execution. No interleaving GC or other operations should observe a partially promoted graph.
Tooling: Chrome DevTools memory profiler, heap snapshots, and allocation trackers would need to understand the dual heap model.

None of these are unsolvable. But they require V8 team involvement — this is an RFC-level proposal, not a weekend project.

The Philosophical Point

The systems programming world has known about Arena allocation for decades. Game engines use it. Compilers use it. High-performance C++ servers use it. Apache's apr_pool_t has been doing request-scoped Arena allocation since the early 2000s.

The conventional wisdom has been that managed languages can't have this because "you don't control allocation."

But that's only true if you think of the runtime as a black box that the language sits on top of. If the runtime is the implementation — if Node.js chooses to implement this — then the managed language gets all the ergonomics of GC and the performance characteristics of Arena allocation, for the common case.

GC is not the enemy. GC doing work it doesn't need to do is the enemy.

Most of your objects don't need GC. They need a bump allocator and a free() at request end. Let GC focus on the objects that actually need it.

Conclusion

This proposal is not about replacing GC. It is about giving the runtime semantic awareness of request boundaries — awareness it could always have had, but never used — and using that awareness to implement a form of generational GC that is perfectly tuned to the actual object lifetime distribution of high-throughput HTTP workloads.

The result:

Arena objects: ~95% of request allocations. Near-zero allocation cost. Near-zero deallocation cost. GC never touches them.
GC objects: ~5% that genuinely escape. Handled normally.
Developer experience: Unchanged. Zero new APIs to learn. Zero migration cost. All existing code benefits.
Async JSON serialization: A path toward moving large response serialization off the main thread entirely.

The best performance optimization is the one your users don't have to think about.

ChenTao

March 26, 2026

High-quality documentation for my ORM framework is completed

babyfish-ct — Fri, 22 Sep 2023 15:48:28 +0000

The high-quality documentation for my ORM framework is now complete: https://babyfish-ct.github.io/jimmer/

Based on suggestions from a group of Jimmer users, I spent a full four months writing this high-quality documentation.

In the past, I’ve introduced this ORM framework before, but for over a year prior, I invested 100% of my energy into continuously implementing planned features, with no time to write quality docs to tell more users what Jimmer actually is.

Now, the high-quality documentation is finally complete. It not only clearly shows what the current 0.8.23 version of Jimmer has accomplished, but also tells users what features it will add in the future.

Simple problems keep getting repeatedly solved, while truly complex problems are constantly ignored. I really hope to solve these truly complex problems. Therefore, I have contemplated these problems for over a decade, eventually summarizing a methodology, and providing abstraction and implementation.

Jimmer will bring tremendous value. If it obviously makes developing projects much easier for everyone, that will be the greatest reward for my persistent efforts thus far.

Finally, the kotlin API and External Cache are supported, and my ORM is finished.

babyfish-ct — Fri, 26 Aug 2022 09:01:48 +0000

Hi Guys

It's been a few more months since the last message, my ORM is completely finished, with two important changes.

Kotlin API is supported, all the code snippets in the documentation become tab containing 2 cards: Java and Kotlin.
Support powerful external cache.

Does not affect user's choice of caching technology_(The examples use Caffeine and Redis)_.
For object trees with arbitrary depth, not simple objects.
Automatically guarantee data consistency between database and cache.

Youtube link: https://www.youtube.com/watch?v=Rt5zNv0YR2E

(The framework supports Java API and kotlin API, but for easy understanding, this video only uses kotlin to explain)

Total time: 36 minutes.

Object Fetcher: Query object trees with arbitrary depth*(06:10)*
Save Command: Save object trees with arbitrary depth*(06:44)*
External Cache: Cache object trees with arbitrary depth, ensure data consistency*(12:09)*
Dynamic table joins (01:23)
Paging query (01:50)
Quickly build Spring GraphQL applications (05:27)

The story of the project, its creative process

In the past nearly 20 years of work, I have deeply used too many ORM frameworks, and read all the source code of some of them, but none of them can meet my expectations.

So I quit my job in June last year, stay at home, work hard for my ideals, develop several open source projects. The last project is to create a revolutionary ORM, to be the most powerful and fastest.

Q: The competition for ORM ended many years ago, why create new ORM?

A: To solve deep-seated problems, a large number of developers are troubled by these problems every day, but they are not aware of it.

Q: Why give up all income to create these projects?

A: My environment that seeks short-term interests, not long-term ones. Lack of innovation and no support for innovation.

Keep trying, keep looking for the best solution. During this period, I also encountered a lot of unhappy things. For example, others were not optimistic, and the r/java community of reddit blocked my account on the grounds that they were not allowed to promote their related matters. But these are not important, I tried to solve all the problems I faced before, and finally today, jimmer is fully completed, and all my pre-design goals have been achieved.

During the 14 months of voluntarily giving up any income for the sake of the ideal. I contributed to three projects, in chronological order:

A small project for web developers: https://github.com/babyfish-ct/graphql-ts-client.
A small project for web developers: https://github.com/babyfish-ct/graphql-state.
A medium project for Java and Kotlin developers: https://github.com/babyfish-ct/jimmer.

In any case, now I'm happy because all my ideas became reality.

A benchmark to show you how fast my ORM framework is

babyfish-ct — Mon, 18 Jul 2022 19:12:11 +0000

I've create a new ORM framework Jimmer, it has achieved the following two goals

More powerful than other ORM frameworks
Faster than other ORM frameworks

Regarding the first point, it is difficult to explain in the limited space. Users must read all the contents of the documentation before they can understand it.

However, regarding the second point, one benchmark picture can tell everything.

The abscissa represents the count of data objects queried from the database.
The ordinate represents the operation count per second.

If you want to view full benchmark report, click here please.

If you want to run the benchmark, run this project please.

A new Java ORM and why we need it

babyfish-ct — Mon, 20 Jun 2022 12:35:24 +0000

I've created a framework about immutable data and ORM for immutable data.

Project name: Jimmer

Project Home: https://babyfish-ct.github.io/jimmer-doc/

Overview

Jimmer is divided into two parts, jimmer-core and jimmer-sql.

jimmer-core: Immutable data
jimmer-sql: ORM based on jimmer-core

Their respective responsibilities are as follows

jimmer-core

Porting a well-known project immer for Java, modifying immutable objects in the way of mutable objects.

Jimmer can be used in any context where immutable data structures are required to replace java records. Immutable data structures allow for (effective) change detection: if the reference to the object hasn't changed, then neither has the object itself. Also, it makes cloning relatively cheap: unchanged parts of the data tree do not need to be copied and are shared in memory with older versions of the same state.

In general, these benefits are achieved by ensuring that you never change any properties of an object or list, but always create a changed copy. In practice, this can lead to very cumbersome code to write, and it is easy to accidentally violate these constraints. Jimmer will help you follow the immutable data paradigm by addressing the following pain points:
1. Jimmer will detect an unexpected mutation and throw an error.
2. Jimmer will eliminate the need to create the typical boilerplate code required when doing deep updates to immutable objects: without Jimmer, you would need to manually make copies of objects at each level. Usually by using a lot of copy construction.
3. When using JImmer, changes are made to the draft object, which records the changes and takes care of creating the necessary copies without affecting the original.
When using Jimmer, you don't need to learn specialized APIs or data structures to benefit from paradigms.

In addition, to support ORM, Jimmer adds object dynamics to immer. Any property of an object is allowed to be missing.
- Missing properties cause exceptions when accessed directly by code
- Missing properties are automatically ignored during Jackson serialization and will not cause an exception
jimmer-sql

ORM based on jimmer-core dynamic immutable objects.

In terms of implementation, jimmer-sql is incredibly lightweight, with no dependencies other than JDBC, not even some lightweight encapsulation for database connection like SqlSession of myBatis.

Similar to QueryDsl, JOOQ, JPA Criteria, with strongly typed SQL DSLs, most SQL errors are reported at compile time rather than as runtime exceptions.

However, strongly-typed SQL DSL does not conflict with Native SQL. Through elegant API, Native SQL is mixed into strongly-typed SQL DSL, and developers are encouraged to use features specific to specific database products, such as analytical functions and regularization.

In addition to all ORM's must-have features, jimmer-sql provides 4 other features that far exceed other ORMs:

 - [Save command](https://babyfish-ct.github.io/jimmer-doc/docs/jimmer-sql/mutation/save-command)
 - [Object fetcher](https://babyfish-ct.github.io/jimmer-doc/docs/jimmer-sql/query/fetcher)
 - [Dynamic table joins](https://babyfish-ct.github.io/jimmer-doc/docs/jimmer-sql/table-join#dynamic-join)
 - [Smarter pagination queries](https://babyfish-ct.github.io/jimmer-doc/docs/jimmer-sql/query/pagination).

 These four powerful functions that are clearly different from other ORMs are the goals pursued by the ORM part of this framework.

1. Make User Bean powerful enough

1.1 Use immutable data, but support temporary mutable proxies.

@Immutable
public interface TreeNode {
    String name();
    TreeNode parent();
    List<TreeNode> childNodes();
}

The annotation processor will generate a mutable derived interface for the user: TreeNodeDraft. User can use it like this

// Step1: Create object from scratch
TreeNode oldTreeNode = TreeNodeDraft.$.produce(root ->  
    root
        .setName("Root")
        .addIntoChildNodes(child ->
            child.setName("Drinks")        
        )
        .addIntoChildNodes(child ->
            child.setName("Breads")        
        )
);

// Step2: Create object based on existing object
TreeNode newTreeNode = TreeNodeDraft.$.produce(
    oldTreeNode, // existing object
    root ->
      root.childNodes(false).get(0) // Get child proxy
          .setName("Dranks+"); // Change child proxy
);

System.out.println("Old tree node: ");
System.out.println(oldTreeNode);

System.out.println("New tree node: ");
System.out.println(newTreeNode);

The final print result is as follows

Old tree node: 
{"name": "Root", childNodes: [{"name": "Drinks"}, {"name": "Breads"}]}
New tree node: 
{"name": "Root", childNodes: [{"name": "`Drinks+`"}, {"name": "Breads"}]}

1.2 Dynamic object.

Any property of the data object can be unspecified.

Direct access to unspecified properties causes an exception.
Using Jackson serialization, Unspecified properties will be ignored, without exception throwing.

TreeNode current = TreeNodeDraft.$.produce(current ->
    node
        .setName("Current")
        .setParent(parent -> parent.setName("Father"))
        .addIntoChildNodes(child -> child.setName("Son"))
);

// You can access specified properties
System.out.println(current.name());
System.out.println(current.parent());
System.out.println(current.childNodes());

/*
 * But you cannot access unspecified fields, like this
 *
 * System.out.println(current.parent().parent());
 * System.out.println(
 *     current.childNodes().get(0).childNodes()
 * );
 *
 * , because direct access to unspecified 
 * properties causes an exception.
 */

/*
 * Finally You will get JSON string like this
 * 
 * {
 *     "name": "Current", 
 *     parent: {"name": "Father"},
 *     childNodes:[
 *         {"name": "Son"}
 *     ]
 * }
 *
 * , because unspecified will be ignored by 
 * jackson serialization, without exception throwing.
 */
String json = new ObjectMapper()
    .registerModule(new ImmutableModule())
    .writeValueAsString(current);

System.out.println(json);

Because entity objects are dynamic, users can build arbitrarily complex data structures. There are countless possibilities, such as

Lonely object, for example

TreeNode lonelyObject = TreeNodeDraft.$.produce(draft ->
    draft.setName("Lonely object")
);

Shallow object tree, for example

TreeNode shallowTree = TreeNodeDraft.$.produce(draft ->
    draft
        .setName("Shallow Tree")
        .setParent(parent -> parent.setName("Father"))
        .addIntoChildNodes(child -> parent.setName("Son"))
);

Deep object tree, for example

TreeNode deepTree = TreeNodeDraft.$.produce(draft ->
    draft
        .setName("Deep Tree")
        .setParent(parent -> 
             parent
                 .setName("Father")
                 .setParent(deeperParent ->
                     deeperParent.setName("Grandfather")
                 )
        )
        .addIntoChildNodes(child -> 
            child
                .setName("Son")
                .addIntoChildNodes(deeperChild -> 
                    deeperChild.setName("Grandson");
                )
        )
);

This object dynamism, which includes countless possibilities, is the fundamental reason why jimmer's ORM can provide more powerful features.

2. ORM base on immutable object.

In jimmer's ORM, entities are also immutable interfaces

@Entity
public interface TreeNode {

    @Id
    @GeneratedValue(
        strategy = GenerationType.SEQUENCE,
        generator = "sequence:TREE_NODE_ID_SEQ"
    )
    long id();

    @Key // jimmer annotation, `name()` is business key,
    // business key will be used when `id` property is not specified
    String name();

    @Key // Business key too
    @ManyToOne
    @OnDelete(DeleteAction.DELETE)
    TreeNode parent();

    @OneToMany(mappedBy = "parent")
    List<TreeNode> childNodes();
}

Note!

Although jimmer uses some JPA annotations to complete the mapping between entities and tables, jimmer is not JPA.

2.1 Save arbitrarily complex object tree into database

Save lonely entity

sqlClient.getEntities().save(
    TreeNode lonelyObject = TreeNodeDraft.$.produce(draft ->
        draft
            .setName("RootNode")
            .setParent((TreeNode)null)
    )
);

Save shallow entity tree

sqlClient.getEntities().save(
    TreeNode lonelyObject = TreeNodeDraft.$.produce(draft ->
        draft
            .setName("RootNode")
            .setParent(parent ->
                parent.setId(100L)
            )
            .addIntoChildNodes(child ->
                child.setId(101L)
            )
            .addIntoChildNodes(child ->
                child.setId(102L)
            )
    )
);

Save deep entity tree

sqlClient.getEntities().saveCommand(
    TreeNode lonelyObject = TreeNodeDraft.$.produce(draft ->
        draft
            .setName("RootNode")
            .setParent(parent ->
                parent
                    .setName("Parent")
                    .setParent(grandParent ->
                        grandParent.setName("Grand parent")
                    )
            )
            .addIntoChildNodes(child ->
                child
                    .setName("Child-1")
                    .addIntoChildNodes(grandChild ->
                        grandChild.setName("Child-1-1")
                    )
                   .addIntoChildNodes(grandChild ->
                        grandChild.setName("Child-1-2")
                    )
            )
            .addIntoChildNodes(child ->
                child
                    .setName("Child-2")
                    .addIntoChildNodes(grandChild ->
                        grandChild.setName("Child-2-1")
                    )
                    .addIntoChildNodes(grandChild ->
                        grandChild.setName("Child-2-2")
                    )
            )
    )
).configure(it ->
    // Auto insert associated objects 
    // if they do not exists in database
    it.setAutoAttachingAll()
).execute();

2.2 Query arbitrarily complex object trees from a database

Select root nodes from database (TreeNodeTable is a java class generated by annotation processor)

List<TreeNode> rootNodes = sqlClient
    .createQuery(TreeNodeTable.class, (q, treeNode) -> {
        q.where(treeNode.parent().isNull()) // filter roots
        return q.select(treeNode);
    })
    .execute();

Select root nodes and their child nodes from database (TreeNodeFetcher is a java class generated by annotation processor)

List<TreeNode> rootNodes = sqlClient
    .createQuery(TreeNodeTable.class, (q, treeNode) -> {
        q.where(treeNode.parent().isNull()) // filter roots
        return q.select(
            treeNode.fetch(
                TreeNodeFetcher.$
                    .allScalarFields()
                    .childNodes(
                        TreeNodeFetcher.$
                            .allScalarFields()
                    )
            )
        );
    })
    .execute();

Query the root nodes, with two levels of child nodes

You have two ways to do it

-   Specify a deeper tree format

    ```java
    List<TreeNode> rootNodes = sqlClient
    .createQuery(TreeNodeTable.class, (q, treeNode) -> {
        q.where(treeNode.parent().isNull()) // filter roots
        return q.select(
            treeNode.fetch(
                TreeNodeFetcher.$
                    .allScalarFields()
                    .childNodes( // level-1 child nodes
                        TreeNodeFetcher.$
                            .allScalarFields()
                            .childNodes( // level-2 child nodes
                                TreeNodeFetcher.$
                                    .allScalarFields()
                            )
                    )
            )
        );
    })
    .execute();
    ```

-   You can also specify depth for self-associative property, this is better way

    ```java
    List<TreeNode> rootNodes = sqlClient
    .createQuery(TreeNodeTable.class, (q, treeNode) -> {
        q.where(treeNode.parent().isNull()) // filter roots
        return q.select(
            treeNode.fetch(
                TreeNodeFetcher.$
                    .allScalarFields()
                    .childNodes(
                        TreeNodeFetcher.$
                            .allScalarFields(),
                        it -> it.depth(2) // Fetch 2 levels
                    )
            )
        );
    })
    .execute();
    ```

Query all root nodes, recursively get all child nodes, no matter how deep

List<TreeNode> rootNodes = sqlClient
.createQuery(TreeNodeTable.class, (q, treeNode) -> {
    q.where(treeNode.parent().isNull()) // filter roots
    return q.select(
        treeNode.fetch(
            TreeNodeFetcher.$
                .allScalarFields()
                .childNodes(
                    TreeNodeFetcher.$
                        .allScalarFields(),

                    // Recursively fetch all, 
                    // no matter how deep
                    it -> it.recursive() 
                )
        )
    );
})
.execute();

Query all root nodes, it is up to the developer to control whether each node needs to recursively query child nodes

List<TreeNode> rootNodes = sqlClient
.createQuery(TreeNodeTable.class, (q, treeNode) -> {
    q.where(treeNode.parent().isNull()) // filter roots
    return q.select(
        treeNode.fetch(
            TreeNodeFetcher.$
                .allScalarFields()
                .childNodes(
                    TreeNodeFetcher.$
                        .allScalarFields(),
                    it -> it.recursive(args ->
                        // - If the node name starts with `Tmp_`, 
                        // do not recursively query child nodes.
                        //
                        // - Otherwise, 
                        // recursively query child nodes.
                        !args.getEntity().name().startsWith("Tmp_")
                    )
                )
        )
    );
})
.execute();

2.3 Dynamic table joins.

In order to develop powerful dynamic queries, it is not enough to support dynamic where predicates, but dynamic table joins are required.

@Repository
public class TreeNodeRepository {

    private final SqlClient sqlClient;

    public TreeNodeRepository(SqlClient sqlClient) {
        this.sqlClient = sqlClient;
    }

    public List<TreeNode> findTreeNodes(
        @Nullable String name,
        @Nullable String parentName,
        @Nullable String grandParentName
    ) {
        return sqlClient
            .createQuery(TreeNodeTable.class, (q, treeNode) -> {
               if (name != null && !name.isEmpty()) {
                   q.where(treeNode.name().eq(name));
               }
               if (parentName != null && !parentName.isEmpty()) {
                   q.where(
                       treeNode
                       .parent() // Join: current -> parent
                       .name()
                       .eq(parentName)
                   );
               }
               if (grandParentName != null && !grandParentName.isEmpty()) {
                   q.where(
                       treeNode
                           .parent() // Join: current -> parent
                           .parent() // Join: parent -> grand parent
                           .name()
                           .eq(grandParentName)
                   );
               }
               return q.select(treeNode);
            })
            .execute();
    }
}

This dynamic query supports three nullable parameters.

When the parameter parentName is not null, the table join current -> parent is required
When the parameter grandParentName is not null, you need to join current -> parent -> grandParent

When the parameters parentName and grandParent are both specified, the table join paths current -> parent and current -> parent -> grandParent are both added to the query conditions. Among them, current->parent appears twice, jimmer will automatically merge the duplicate table joins.

This means

`current -> parent` 
+ 
`current -> parent -> grandParent` 
= 
--+-current
  |
  \--+-parent
     |
     \----grandParent

In the process of merging different table join paths into a join tree, duplicate table joins are removed.

The final SQL is

select 
    tb_1_.ID, tb_1_.NAME, tb_1_.PARENT_ID
from TREE_NODE as tb_1_

/* Two java joins are merged to one sql join*/
inner join TREE_NODE as tb_2_ 
    on tb_1_.PARENT_ID = tb_2_.ID

inner join TREE_NODE as tb_3_ 
    on tb_2_.PARENT_ID = tb_3_.ID
where
    tb_2_.NAME = ? /* parentName */
and
    tb_3_.NAME = ? /* grandParentName */

2.4 Automatically generate count-query by data-query.

Pagination query requires two SQL statements, one for querying the total row count of data, and the other one for querying data in one page, let's call them count-query and data-query.

Developers only need to focus on data-count, and count-query can be generated automatically.


// Developer create data-query
ConfigurableTypedRootQuery<TreeNodeTable, TreeNode> dataQuery = 
    sqlClient
        .createQuery(TreeNodeTable.class, (q, treeNode) -> {
            q
                .where(treeNode.parent().isNull())
                .orderBy(treeNode.name());
            return q.select(book);
        });

// Framework generates count-query
TypedRootQuery<Long> countQuery = dataQuery
    .reselect((oldQuery, book) ->
        oldQuery.select(book.count())
    )
    .withoutSortingAndPaging();

// Execute count-query
int rowCount = countQuery.execute().get(0).intValue();

// Execute data-query
List<TreeNode> someRootNodes = 
    dataQuery
        // limit(limit, offset), from 1/3 to 2/3
        .limit(rowCount / 3, rowCount / 3)
        .execute();

A 20-minute video introducing GraphQL-state

babyfish-ct — Wed, 22 Dec 2021 09:56:11 +0000

I created a 20-minute video introducing GraphQL-state(An intelligent react state management framework).

https://www.youtube.com/watch?v=05Xx_t8GC18
(My English is too bad, so I can only use AI to synthesize speech, sorry)

In daily development, React developers will encounter a type of complex problems that have not been solved by any other state management frameworks. GraphQL-state is committed to a simple and intelligent way to solve those complex problems.

This video can show you how powerful and smart it is.

Welcome everyone to put forward your valuable opinions, let's work together to make it better and better, smarter and smarter.

A new react state management framework

babyfish-ct — Thu, 18 Nov 2021 03:15:55 +0000

I created a new react state management framework https://github.com/babyfish-ct/graphql-state

This article does not intend to introduce the details of the framework itself, because the framework provides get-start example, documentation, comprehensive examples, and GIF animations, so I won’t repeat them here.

In this article, we discuss why this new framework was created, whether it is to reinvent the wheel, or whether it has its own unique insights and value.

How to consume GraphQL services in React can be divided into four levels

1. The first level, provides API to communicate with server

This level of framework is represented by https://github.com/prisma-labs/graphql-request.

This kind of framework is the most basic and simplest GraphQL client, which can use its API to communicate with the server, but it does not have any caching services.

When your application is very simple, the minimal function can bring the lowest learning difficulty and use cost. When the project is very simple so that each page is an island of information with a small amount of data, and you can deal with the lack of no cache through frequent refresh queries.

However, when you encounter a slightly more complex application, a variety of different data are presented on UI at the same time, and there are relationships and dependencies between them, you will start to be powerless, because you can't ignore performance issues and refresh all data frequently. You desperately need caching.

2. The second level, simple key/value cache

This level of framework is represented by https://github.com/tannerlinsley/react-query.

It is true that react-query is very powerful in terms of configurability; but the biggest problem is that the cache is a simple key/value cache. In fact, the real data model is a graph structure, and different objects are related to each other. E.g

BookStore <--1:n--> Book <--m:n--> Author

According to the associations in the example, a simple key/value cache will easily lead to the following two cache items

Cache data 1:

{
  __typename: "BookStore",
  id: 1,
  name: "O'REILLY",
  books: [
     {
         __typename: "Book",
         id: 2,
         name: "Learning GraphQL",
     },
     {
         __typename: "Book",
         id: 3,
         name: "Effective TypeScript"
     }
  ]
}

Cached data 2:

{
  __typename: "Author",
  id: 9,
  name: "Alex Banks",
  books: [
     {
         __typename: "Book",
         id: 2,
         name: "Learning GraphQL",
     }
  ]
}

In the above data, the book named "Learning GraphQL" exists in both the cache items. This redundancy will cause data inconsistency in subsequent data changes.

As the relationship between objects becomes more and more complex, you will find it more and more difficult to eliminate the side effects of redundancy. You urgently need to normalize the data in the cache, just as you do in RDBMS.

3. The third level, normalized-cache

This level of framework is represented by Apollo Client and Relay.

Apollo Client: https://github.com/apollographql/apollo-client (normalized cache is supported since 3.0, older versions are not supported)
Relay: https://github.com/facebook/relay

Normalized-cache stores data rows and the relationships between them just like RDBMS. Highly normalized data has no redundancy. Of course, this kind of internal relational data needs to be converted with the hierarchical data used by the user. Fortunately, the framework can easily black-box this conversion automatically, and users cannot perceive the existence of internal relational data.

Now, users don’t need to worry about data redundancy in the cache. But there is also a serious problem, that is, the mutation operation will be very complicated, developers need to maintain the consistency of the cache.

For example, the data in the existing cache is as follows

{
    "Query": {
        findBooks({"name": "e"}): [{ref: "Book:2"}, {ref: "Book:3"}],
        findBooks({"name": "g"}): [{ref: "Book:2"}]
    },
    "Book:2": {
        id: 2,
        name: "Learning GraphQL"
    },
    "Book:3": {
        id: 3,
        name: "Effective TypeScript"
    }
}

Among them, findBooks({"name": ...}) represents the query condition, and performs fuzzy matching and filtering on the name of the book.

Now, mutate the data, change {id:2, name: "Learning GraphQL"} to {id:2, name: "Learning TypeScript"}. After mutation, the new name "Learning TypeScript" no longer matches the query condition {name: "g"}. So, the new cache should look like this

{
    "Query": {
        findBooks({"name": "e"}): [{ref: "Book:3"}, {ref: "Book:3"}],

        // Extra mutation: old data references need to disappear
        findBooks({"name": "g"}): [] 
    },
    "Book:2": {
        id: 2,

        // Main mutation: the original intention of the developer
        name: "Learning TypeScript" 
    },
    "Book:3": {
        id: 3,
        name: "Effective TypeScript"
    }
}

The "main mutation" above is very simple, and this is the developer's intention in itself. However, "extra mutation" is very troublesome. It is the changes that other existing data in the cache have to make in order to adapt to the new data mutation.

The number of such "extra mutations" is affected by the amount of existing data in the cache and the complexity of the data structure. From a theoretical level, the complexity cannot be limited, and one main mutation can lead to countless extra mutations.

To allow the cache to complete the above "extra mutations", there are nothing more than two ways.

Manually change the local cache, which is a high-performance but not necessarily feasible method
Let the query Query.findBooks({name: "g"}) refetch latest data from the server again. This is a low-performance but always feasible method

For Apollo Client:
- Modify the cache: https://www.apollographql.com/docs/react/data/mutations/#updating-the-cache-directly
- Refetch: https://www.apollographql.com/docs/react/data/mutations/#refetching-queries
Relay prefers to modify the cache directly: https://relay.dev/docs/guided-tour/updating-data/graphql-mutations/#updater-functions

As explained above, the complexity of this "extra mutations" cannot be limited. It is foreseeable that if there are more UI modules, the data types inside the modules are richer, and the relationship between data types is more complex, then it will be more difficult to ensure cache consistency.

If you choose to modify the cache directly, the logic of the code you need to write will become more and more complex.
If you choose to let affected queries to refetch data again, it is also difficult to determine which queries will be affected by the current mutation.

In short, if you use Apollo Client or Relay, you will find that the pain point you face has become cache consistency maintenance, and the degree of pain is positively related to the complexity of the UI.

4. The fourth level, automatically guarantees cache consistency

In response to the problems of Apollo Client and Relay, I developed this new state management framework. One of the most important functions is to consume GraphQL services. The framework can automatically ensure the consistency of the cache after mutation. The method of directly modifying the cache is preferred, and if not feasible, it will be upgraded to a re-query. No matter how the framework chooses, everything is automatic.

For details on how to achieve this powerful goal, please visit the project homepage.

Attached:

Since it is known as the react state management framework, does it only support GraphQL? What about REST?

In the next version to be released, the framework can simulate GraphQL base on REST. Even for the REST server, it can be abstracted into GraphQL on the client side, enjoying its powerful language meaning and convenience. This feature is called "GraphQL style, but not GraphQL only", please look forward to it.