feat(core): implement component merge behavior for repeated sets

- Add merge option to ComponentOptions interface
- Store and retrieve merge callbacks in component registry
- Apply merge logic in world commands and sync phases
- Support merge for relations and singleton components
- Add comprehensive tests for merge functionality

Author: codehz

src/__tests__/entity.test.ts

@@ -503,6 +503,15 @@ describe("Component Options", () => {
     expect(isDontFragmentComponent(combinedComp)).toBe(true);
   });
 
+  it("should store and retrieve component merge callback", () => {
+    const merge = (prev: number[], next: number[]) => [...prev, ...next];
+    const mailboxComp = component<number[]>({ merge });
+
+    const options = getComponentOptions(mailboxComp);
+    expect(options.merge).toBeDefined();
+    expect(options.merge?.([1], [2, 3])).toEqual([1, 2, 3]);
+  });
+
   it("should throw error for invalid component ID", () => {
     expect(() => getComponentOptions(0 as ComponentId)).toThrow("Invalid component ID");
     expect(() => getComponentOptions(1025 as ComponentId)).toThrow("Invalid component ID");

src/__tests__/world-component-management.test.ts

@@ -41,6 +41,89 @@ describe("World - Component Management", () => {
     expect(world.get(entity, positionComponent)).toEqual(position2);
   });
 
+  it("should keep last value for repeated set in one sync when merge is not configured", () => {
+    const world = new World();
+    const entity = world.new();
+    const position1: Position = { x: 10, y: 20 };
+    const position2: Position = { x: 30, y: 40 };
+
+    world.set(entity, positionComponent, position1);
+    world.set(entity, positionComponent, position2);
+    world.sync();
+
+    expect(world.get(entity, positionComponent)).toEqual(position2);
+  });
+
+  it("should merge repeated sets in one sync for merge-enabled components", () => {
+    const world = new World();
+    const entity = world.new();
+    const Mailbox = component<string[]>({
+      merge: (prev, next) => [...prev, ...next],
+    });
+
+    world.set(entity, Mailbox, ["A"]);
+    world.set(entity, Mailbox, ["B", "C"]);
+    world.sync();
+
+    expect(world.get(entity, Mailbox)).toEqual(["A", "B", "C"]);
+  });
+
+  it("should reset merge accumulation after remove in one sync", () => {
+    const world = new World();
+    const entity = world.new();
+    const Mailbox = component<string[]>({
+      merge: (prev, next) => [...prev, ...next],
+    });
+
+    world.set(entity, Mailbox, ["A1"]);
+    world.set(entity, Mailbox, ["A2"]);
+    world.remove(entity, Mailbox);
+    world.set(entity, Mailbox, ["B1"]);
+    world.set(entity, Mailbox, ["B2"]);
+    world.sync();
+
+    expect(world.get(entity, Mailbox)).toEqual(["B1", "B2"]);
+  });
+
+  it("should merge relation sets by exact component type only", () => {
+    const world = new World();
+    const entity = world.new();
+    const target1 = world.new();
+    const target2 = world.new();
+    const MailRel = component<string[]>({
+      merge: (prev, next) => [...prev, ...next],
+    });
+    const rel1 = relation(MailRel, target1);
+    const rel2 = relation(MailRel, target2);
+
+    world.set(entity, rel1, ["T1-A"]);
+    world.set(entity, rel2, ["T2-A"]);
+    world.set(entity, rel1, ["T1-B"]);
+    world.set(entity, rel2, ["T2-B"]);
+    world.sync();
+
+    expect(world.get(entity, rel1)).toEqual(["T1-A", "T1-B"]);
+    expect(world.get(entity, rel2)).toEqual(["T2-A", "T2-B"]);
+  });
+
+  it("should apply merge for singleton(component entity) sets", () => {
+    const world = new World();
+    const Inbox = component<string[]>({
+      merge: (prev, next) => [...prev, ...next],
+    });
+
+    world.set(Inbox, ["A"]);
+    world.set(Inbox, ["B"]);
+    world.sync();
+    expect(world.get(Inbox)).toEqual(["A", "B"]);
+
+    world.remove(Inbox);
+    world.set(Inbox, ["C"]);
+    world.set(Inbox, ["D"]);
+    world.sync();
+    expect(world.get(Inbox)).toEqual(["C", "D"]);
+  });
+
   it("should remove components from entities", () => {
     const world = new World();
     const entity = world.new();

src/core/component-registry.ts

@@ -13,11 +13,12 @@ import {
 const globalComponentIdAllocator = new ComponentIdAllocator();
 
 const ComponentIdForNames: Map<string, ComponentId<any>> = new Map();
+type ComponentMerge<T = any> = (prev: T, next: T) => T;
 
 /**
  * Component options that define intrinsic properties
  */
-export interface ComponentOptions {
+export interface ComponentOptions<T = any> {
   /**
    * Optional name for the component (for serialization/debugging)
    */
@@ -43,6 +44,10 @@ export interface ComponentOptions {
    * Inspired by Flecs' DontFragment trait.
    */
   dontFragment?: boolean;
+  /**
+   * Custom merge behavior for repeated set() of the same componentType in a single sync batch.
+   */
+  merge?: ComponentMerge<T>;
 }
 
 // Array for component names (Component ID range: 1-1023)
@@ -52,6 +57,7 @@ const componentNames: (string | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
 const exclusiveFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const cascadeDeleteFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const componentMerges: (ComponentMerge<any> | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
 
 /**
  * Allocate a new component ID from the global allocator.
@@ -67,11 +73,11 @@ const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
  * // With name and options
  * const ChildOf = component({ name: "ChildOf", exclusive: true });
  */
-export function component<T = void>(nameOrOptions?: string | ComponentOptions): ComponentId<T> {
+export function component<T = void>(nameOrOptions?: string | ComponentOptions<T>): ComponentId<T> {
   const id = globalComponentIdAllocator.allocate<T>();
 
   let name: string | undefined;
-  let options: ComponentOptions | undefined;
+  let options: ComponentOptions<T> | undefined;
 
   // Parse the parameter
   if (typeof nameOrOptions === "string") {
@@ -97,6 +103,7 @@ export function component<T = void>(nameOrOptions?: string | ComponentOptions):
     if (options.exclusive) exclusiveFlags.set(id);
     if (options.cascadeDelete) cascadeDeleteFlags.set(id);
     if (options.dontFragment) dontFragmentFlags.set(id);
+    if (options.merge) componentMerges[id] = options.merge;
   }
 
   return id;
@@ -124,7 +131,7 @@ export function getComponentNameById(id: ComponentId<any>): string | undefined {
  * @param id The component ID
  * @returns The component options
  */
-export function getComponentOptions(id: ComponentId<any>): ComponentOptions {
+export function getComponentOptions<T = any>(id: ComponentId<T>): ComponentOptions<T> {
   if (!isComponentId(id)) {
     throw new Error("Invalid component ID");
   }
@@ -137,9 +144,30 @@ export function getComponentOptions(id: ComponentId<any>): ComponentOptions {
     exclusive: hasExclusive ? true : undefined,
     cascadeDelete: hasCascadeDelete ? true : undefined,
     dontFragment: hasDontFragment ? true : undefined,
+    merge: componentMerges[id] as ComponentMerge<T> | undefined,
   };
 }
 
+function getBaseComponentId(componentType: EntityId<any>): ComponentId<any> | undefined {
+  if (isComponentId(componentType)) {
+    return componentType;
+  }
+
+  const decoded = decodeRelationRaw(componentType);
+  if (decoded === null) return undefined;
+  return isValidComponentId(decoded.componentId) ? (decoded.componentId as ComponentId<any>) : undefined;
+}
+
+/**
+ * Get merge callback for a componentType (including relation component types).
+ * Returns undefined if the base component has no merge callback.
+ */
+export function getComponentMerge<T = any>(componentType: EntityId<any>): ComponentMerge<T> | undefined {
+  const baseComponentId = getBaseComponentId(componentType);
+  if (baseComponentId === undefined) return undefined;
+  return componentMerges[baseComponentId] as ComponentMerge<T> | undefined;
+}
+
 /**
  * Check if a component is marked as exclusive
  * @param id The component ID

src/core/entity.ts

@@ -49,6 +49,7 @@ export type { ComponentOptions } from "./component-registry";
 export {
   component,
   getComponentIdByName,
+  getComponentMerge,
   getComponentNameById,
   getComponentOptions,
   isCascadeDeleteComponent,

src/core/world-commands.ts

@@ -4,6 +4,7 @@ import type { Archetype } from "./archetype";
 import { normalizeComponentTypes } from "./component-type-utils";
 import {
   getComponentIdFromRelationId,
+  getComponentMerge,
   isDontFragmentComponent,
   isDontFragmentRelation,
   isDontFragmentWildcard,
@@ -67,6 +68,13 @@ function processSetCommand(
     }
   }
 
+  const merge = getComponentMerge(componentType);
+  if (merge !== undefined && changeset.adds.has(componentType)) {
+    const prev = changeset.adds.get(componentType);
+    changeset.set(componentType, merge(prev, component));
+    return;
+  }
+
   changeset.set(componentType, component);
 }
 

src/core/world.ts

@@ -13,6 +13,7 @@ import {
   EntityIdManager,
   RELATION_SHIFT,
   getComponentIdFromRelationId,
+  getComponentMerge,
   getDetailedIdType,
   getTargetIdFromRelationId,
   isCascadeDeleteRelation,
@@ -1157,28 +1158,45 @@ export class World {
       return;
     }
 
+    const pendingSetValues = new Map<EntityId<any>, any>();
+
     for (const command of commands) {
       if (command.type === "set" && command.componentType) {
+        const merge = getComponentMerge(command.componentType);
+        let nextValue = command.component;
+        if (merge !== undefined && pendingSetValues.has(command.componentType)) {
+          const prevValue = pendingSetValues.get(command.componentType);
+          nextValue = merge(prevValue, command.component);
+        }
+
+        pendingSetValues.set(command.componentType, nextValue);
         const data = this.getComponentEntityComponents(entityId, true)!;
-        data.set(command.componentType, command.component);
+        data.set(command.componentType, nextValue);
       } else if (command.type === "delete" && command.componentType) {
         const data = this.componentEntityComponents.get(entityId);
-        if (!data) continue;
 
         if (isWildcardRelationId(command.componentType)) {
           const componentId = getComponentIdFromRelationId(command.componentType);
           if (componentId !== undefined) {
-            for (const key of Array.from(data.keys())) {
+            if (data) {
+              for (const key of Array.from(data.keys())) {
+                if (getComponentIdFromRelationId(key) === componentId) {
+                  data.delete(key);
+                }
+              }
+            }
+            for (const key of Array.from(pendingSetValues.keys())) {
               if (getComponentIdFromRelationId(key) === componentId) {
-                data.delete(key);
+                pendingSetValues.delete(key);
               }
             }
           }
         } else {
-          data.delete(command.componentType);
+          data?.delete(command.componentType);
+          pendingSetValues.delete(command.componentType);
         }
 
-        if (data.size === 0) {
+        if (data?.size === 0) {
           this.clearComponentEntityComponents(entityId);
         }
       }