@codehz/ecs 0.8.2 → 0.10.0

package/src/component/registry.ts

@@ -138,7 +138,7 @@ export interface ComponentOptions<T = any> {
    *   `cascadeDelete`, deleting the target entity will both (a) delete the
    *   referencing entity, and (b) the exclusivity constraint prevents the
    *   entity from having multiple cascade-delete relations of the same type.
-   * - **`dontFragment`**: Compatible. Exclusivity is enforced at the data level
+   * - **`sparse`**: Compatible. Exclusivity is enforced at the data level
    *   regardless of whether the archetype is fragmented.
    *
    * @example
@@ -196,7 +196,8 @@ export interface ComponentOptions<T = any> {
    */
   cascadeDelete?: boolean;
   /**
-   * If true, relations with this component will not cause archetype fragmentation.
+   * If true, relations with this component use sparse storage and will not cause
+   * archetype fragmentation.
    *
    * **Problem it solves**: By default, each unique relation pair `(component, target)`
    * creates a **separate archetype**. If 100 entities each have a `ChildOf` relation
@@ -204,28 +205,28 @@ export interface ComponentOptions<T = any> {
    * Queries that iterate over all entities with a `ChildOf` relation must check all
    * 100 archetypes, which degrades iteration performance and increases memory overhead.
    *
-   * **How it works**: When `dontFragment` is enabled, the relation's target does **not**
-   * contribute to the archetype signature. Entities with different targets for the same
-   * relation component share a **single archetype**, and the per-entity target data is
-   * stored in a separate `DontFragmentStore` (a `Map<EntityId, Map<EntityId, any>>`).
-   * A wildcard relation marker (`relation(Comp, "*")`) is placed in the archetype
-   * component list so queries can still discover matching archetypes.
+   * **How it works (sparse storage)**: When `sparse` is enabled, the relation's target
+   * does **not** contribute to the archetype signature. Entities with different targets
+   * for the same relation component share a **single archetype**, and the per-entity
+   * target data is stored in a separate side store (historically called
+   * `DontFragmentStore`, now `SparseStore`). A wildcard relation marker (`relation(Comp, "*")`) is placed
+   * in the archetype component list so queries can still discover matching archetypes.
    *
    * **Use cases**:
    * - **Hierarchy/ownership**: `ChildOf` relations where thousands of entities each
    *   point to different parent entities.
    * - **Dynamic targeting**: Relations where targets change frequently (e.g., AI
-   *   targeting, inventory slots) — without `dontFragment`, each target change would
-   *   cause an archetype migration, which is expensive.
+   *   targeting, inventory slots) — without `sparse`, each target change would cause
+   *   an archetype migration, which is expensive.
    * - **High-cardinality relations**: Any relation where the number of unique targets
    *   is large compared to the number of entities.
    *
    * **Performance implications**:
-   * - **Without `dontFragment`**: Archetype count grows linearly with unique targets.
+   * - **Without `sparse`**: Archetype count grows linearly with unique targets.
    *   Each archetype migration (changing a relation target) requires moving the entity's
    *   data between component arrays.
-   * - **With `dontFragment`**: Archetype count stays constant regardless of target
-   *   diversity. Changing a relation target is an O(1) update in the `DontFragmentStore`.
+   * - **With `sparse`**: Archetype count stays constant regardless of target diversity.
+   *   Changing a relation target is an O(1) update in the sparse side store.
    *   The trade-off is an extra map lookup when accessing the relation data.
    *
    * **Constraints**:
@@ -234,13 +235,16 @@ export interface ComponentOptions<T = any> {
    *   archetype carries a wildcard marker so queries can discover it.
    * - Works with `exclusive` and `cascadeDelete` simultaneously.
    *
+   * **Backward compatibility**: The legacy key `dontFragment` is still accepted and
+   * behaves identically. Prefer `sparse` in new code.
+   *
    * @example
    * ```ts
-   * // Without dontFragment: 100 entities with different parents = 100 archetypes
+   * // Without sparse: 100 entities with different parents = 100 archetypes
    * const ChildOf = component(); // default: fragmentation happens
    *
-   * // With dontFragment: 100 entities with different parents = 1 archetype
-   * const ChildOf = component({ dontFragment: true });
+   * // With sparse: 100 entities with different parents = 1 archetype
+   * const ChildOf = component({ sparse: true });
    *
    * for (let i = 0; i < 100; i++) {
    *   const parent = world.new();
@@ -249,11 +253,17 @@ export interface ComponentOptions<T = any> {
    *   world.set(child, relation(ChildOf, parent));
    * }
    * world.sync();
-   * // dontFragment: 1 archetype for all 100 entities
+   * // sparse: 1 archetype for all 100 entities
    * // without: 100 archetypes, one per unique parent
    * ```
    *
-   * Inspired by Flecs' `DontFragment` trait.
+   * Inspired by Flecs' `DontFragment` trait (now exposed as the clearer `sparse` option).
+   */
+  sparse?: boolean;
+  /**
+   * @deprecated Use `sparse: true` instead. This key is kept solely for backward
+   * compatibility; `component({ dontFragment: true })` continues to work exactly
+   * as before and is equivalent to `sparse: true`.
    */
   dontFragment?: boolean;
   /**
@@ -324,7 +334,7 @@ const componentNames: (string | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
 // BitSets for fast component option checks (Component ID range: 1-1023)
 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 sparseFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const componentMerges: (ComponentMerge<any> | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
 
 /**
@@ -370,7 +380,8 @@ export function component<T = void>(nameOrOptions?: string | ComponentOptions<T>
     // Set bitset flags for fast lookup
     if (options.exclusive) exclusiveFlags.set(id);
     if (options.cascadeDelete) cascadeDeleteFlags.set(id);
-    if (options.dontFragment) dontFragmentFlags.set(id);
+    // Support both `sparse` (preferred) and the legacy `dontFragment` alias for BC
+    if (options.sparse || options.dontFragment) sparseFlags.set(id);
     if (options.merge) componentMerges[id] = options.merge;
   }
 
@@ -406,12 +417,14 @@ export function getComponentOptions<T = any>(id: ComponentId<T>): ComponentOptio
   const hasName = componentNames[id] !== undefined;
   const hasExclusive = exclusiveFlags.has(id);
   const hasCascadeDelete = cascadeDeleteFlags.has(id);
-  const hasDontFragment = dontFragmentFlags.has(id);
+  const hasSparse = sparseFlags.has(id);
   return {
     name: hasName ? componentNames[id] : undefined,
     exclusive: hasExclusive ? true : undefined,
     cascadeDelete: hasCascadeDelete ? true : undefined,
-    dontFragment: hasDontFragment ? true : undefined,
+    sparse: hasSparse ? true : undefined,
+    // For full backward compatibility with code that inspects options.dontFragment
+    dontFragment: hasSparse ? true : undefined,
     merge: componentMerges[id] as ComponentMerge<T> | undefined,
   };
 }
@@ -487,20 +500,21 @@ export function isCascadeDeleteComponent(id: ComponentId<any>): boolean {
 }
 
 /**
- * Check if a component is marked as `dontFragment`.
+ * Check if a component is marked as `sparse` (sparse storage for relations).
  *
- * When a component has `dontFragment: true`, relations using it do not cause
- * archetype fragmentation — entities with different relation targets can share
- * the same archetype. This is a fast O(1) bitset lookup.
+ * When a component has `sparse: true`, relations using it do not cause archetype
+ * fragmentation — entities with different relation targets can share the same
+ * archetype. This is a fast O(1) bitset lookup. The legacy `dontFragment` key
+ * is still accepted and sets the same internal flag.
  *
  * @param id - The component ID to check.
- * @returns `true` if the component was created with `dontFragment: true`.
+ * @returns `true` if the component was created with `sparse: true` (or the
+ *   legacy `dontFragment: true`).
  *
- * @see {@link ComponentOptions.dontFragment} for the full explanation of how
- *   `dontFragment` prevents archetype fragmentation.
+ * @see {@link ComponentOptions.sparse} for the full explanation of sparse storage.
  */
-export function isDontFragmentComponent(id: ComponentId<any>): boolean {
-  return dontFragmentFlags.has(id);
+export function isSparseComponent(id: ComponentId<any>): boolean {
+  return sparseFlags.has(id);
 }
 
 /**
@@ -511,9 +525,8 @@ export function isDontFragmentComponent(id: ComponentId<any>): boolean {
  * ID and checking: (1) the ID is a valid relation, (2) the component ID is in the
  * valid range, (3) the target satisfies the condition, and (4) the flag bit is set.
  *
- * Used as the fast-path implementation for `isDontFragmentRelation`,
- * `isDontFragmentWildcard`, `isExclusiveRelation`, `isExclusiveWildcard`,
- * and `isCascadeDeleteRelation`.
+ * Used as the fast-path implementation for `isSparseRelation`, `isSparseWildcard`,
+ * `isExclusiveRelation`, `isExclusiveWildcard`, and `isCascadeDeleteRelation`.
  *
  * @param id - The entity/relation ID to check.
  * @param flagBitSet - The bitset tracking which component IDs have the flag.
@@ -534,53 +547,41 @@ function checkRelationFlag(
 }
 
 /**
- * Check if an ID is a specific (non-wildcard) relation backed by a `dontFragment`
- * component.
+ * Check if an ID is a specific (non-wildcard) relation backed by a `sparse`
+ * component (i.e. stored in the side sparse store rather than the archetype).
  *
  * This is used in hot paths (archetype resolution, command processing) to determine
- * whether a relation should be excluded from the archetype signature. Relations with
- * `dontFragment` components are stored in the shared {@link DontFragmentStore} instead
- * of being part of the archetype's component type list.
- *
- * This is an optimized function that avoids the overhead of `getDetailedIdType`
- * by directly decoding and checking the relation's component ID against the
- * `dontFragment` bitset.
+ * whether a relation should be excluded from the archetype signature.
  *
  * @param id - The entity/relation ID to check (must be a relation ID, not a plain
  *   component ID).
  * @returns `true` if this is a specific-target relation (not wildcard) whose base
- *   component was created with `dontFragment: true`.
+ *   component was created with `sparse: true` (or legacy `dontFragment: true`).
  *
- * @see {@link isDontFragmentWildcard} for the wildcard variant.
- * @see {@link ComponentOptions.dontFragment} for the full explanation.
+ * @see {@link isSparseWildcard} for the wildcard variant.
+ * @see {@link ComponentOptions.sparse} for the full explanation.
  */
-export function isDontFragmentRelation(id: EntityId<any>): boolean {
-  return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
+export function isSparseRelation(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, sparseFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
 }
 
 /**
  * Check if an ID is a wildcard relation (`relation(Comp, "*")`) backed by a
- * `dontFragment` component.
- *
- * Wildcard markers for `dontFragment` components are placed in the archetype
- * component list so that queries can discover archetypes containing entities
- * with that relation type. This function is used in `filterRegularComponentTypes`
- * to **keep** these wildcard markers in the archetype signature while stripping
- * out specific-target `dontFragment` relations.
+ * `sparse` component.
  *
- * This is an optimized function that avoids the overhead of `getDetailedIdType`
- * by directly decoding and checking the relation's component ID against the
- * `dontFragment` bitset.
+ * Wildcard markers for sparse components are placed in the archetype component
+ * list so that queries can discover archetypes containing entities with that
+ * relation type.
  *
  * @param id - The entity/relation ID to check.
  * @returns `true` if this is a wildcard relation (`"*"` target) whose base
- *   component was created with `dontFragment: true`.
+ *   component was created with `sparse: true` (or legacy `dontFragment: true`).
  *
- * @see {@link isDontFragmentRelation} for the specific-target variant.
- * @see {@link ComponentOptions.dontFragment} for the full explanation.
+ * @see {@link isSparseRelation} for the specific-target variant.
+ * @see {@link ComponentOptions.sparse} for the full explanation.
  */
-export function isDontFragmentWildcard(id: EntityId<any>): boolean {
-  return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
+export function isSparseWildcard(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, sparseFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
 }
 
 /**

package/src/entity/index.ts

@@ -54,10 +54,13 @@ export {
   getComponentOptions,
   isCascadeDeleteComponent,
   isCascadeDeleteRelation,
-  isDontFragmentComponent,
-  isDontFragmentRelation,
-  isDontFragmentWildcard,
+  isSparseComponent as isDontFragmentComponent,
+  isSparseRelation as isDontFragmentRelation,
+  isSparseWildcard as isDontFragmentWildcard,
   isExclusiveComponent,
   isExclusiveRelation,
   isExclusiveWildcard,
+  isSparseComponent,
+  isSparseRelation,
+  isSparseWildcard,
 } from "../component/registry";

package/src/index.ts

@@ -32,6 +32,8 @@ export type {
 } from "./storage/serialization";
 export { EntityBuilder } from "./world/builder";
 export type { ComponentDef } from "./world/builder";
+export { SingletonHandle } from "./world/singleton";
+export type { SingletonHandleOps } from "./world/singleton";
 export { World } from "./world/world";
 
 // Query class
@@ -39,3 +41,16 @@ export { Query } from "./query/query";
 
 // Type utilities
 export type { ComponentTuple, ComponentType, LifecycleCallback, LifecycleHook } from "./types";
+
+// Debug / observability types
+export type { DebugStatsCollector, SyncDebugStats } from "./types";
+
+// Sparse / dontFragment flag checks (preferred + legacy aliases for BC)
+export {
+  isSparseComponent as isDontFragmentComponent,
+  isSparseRelation as isDontFragmentRelation,
+  isSparseWildcard as isDontFragmentWildcard,
+  isSparseComponent,
+  isSparseRelation,
+  isSparseWildcard,
+} from "./component/registry";

package/src/query/filter.ts

@@ -1,12 +1,6 @@
 import type { Archetype } from "../archetype/archetype";
 import type { EntityId } from "../entity";
-import {
-  getComponentIdFromRelationId,
-  getDetailedIdType,
-  isDontFragmentComponent,
-  isRelationId,
-  relation,
-} from "../entity";
+import { getComponentIdFromRelationId, getDetailedIdType, isRelationId, isSparseComponent, relation } from "../entity";
 
 /**
  * Filter options for queries
@@ -41,13 +35,13 @@ export function matchesComponentTypes(archetype: Archetype, componentTypes: Enti
     } else if (
       (detailedType.type === "entity-relation" || detailedType.type === "component-relation") &&
       detailedType.componentId !== undefined &&
-      isDontFragmentComponent(detailedType.componentId)
+      isSparseComponent(detailedType.componentId)
     ) {
-      // For specific dontFragment relations, check if archetype has the wildcard marker
+      // For specific sparse relations, check if archetype has the wildcard marker
       const wildcardMarker = relation(detailedType.componentId, "*");
       return archetype.componentTypeSet.has(wildcardMarker);
     } else {
-      // For regular components and non-dontFragment relations, check direct inclusion
+      // For regular components and non-sparse relations, check direct inclusion
       return archetype.componentTypeSet.has(type);
     }
   });

package/src/query/query.ts

@@ -1,7 +1,7 @@
 import type { Archetype } from "../archetype/archetype";
 import { normalizeComponentTypes } from "../component/type-utils";
 import type { EntityId, WildcardRelationId } from "../entity";
-import { getDetailedIdType, isDontFragmentComponent } from "../entity";
+import { getDetailedIdType, isSparseComponent } from "../entity";
 import type { ComponentTuple, ComponentType } from "../types";
 import type { World } from "../world/world";
 import { matchesComponentTypes, matchesFilter, type QueryFilter } from "./filter";
@@ -33,8 +33,8 @@ export class Query {
   _cacheKey: string | undefined;
   /** Cached wildcard component types for faster entity filtering */
   private wildcardTypes: WildcardRelationId<any>[];
-  /** Cached specific dontFragment relation types that need entity-level filtering */
-  private specificDontFragmentTypes: EntityId<any>[];
+  /** Cached specific sparse relation types that need entity-level filtering */
+  private specificSparseRelationTypes: EntityId<any>[];
 
   /**
    * @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
@@ -47,13 +47,13 @@ export class Query {
     this.wildcardTypes = this.componentTypes.filter(
       (ct) => getDetailedIdType(ct).type === "wildcard-relation",
     ) as WildcardRelationId<any>[];
-    // Pre-compute specific dontFragment relation types that need entity-level filtering
-    this.specificDontFragmentTypes = this.componentTypes.filter((ct) => {
+    // Pre-compute specific sparse relation types that need entity-level filtering
+    this.specificSparseRelationTypes = this.componentTypes.filter((ct) => {
       const detailedType = getDetailedIdType(ct);
       return (
         (detailedType.type === "entity-relation" || detailedType.type === "component-relation") &&
         detailedType.componentId !== undefined &&
-        isDontFragmentComponent(detailedType.componentId)
+        isSparseComponent(detailedType.componentId)
       );
     });
     this.updateCache();
@@ -86,8 +86,8 @@ export class Query {
   getEntities(): EntityId[] {
     this.ensureNotDisposed();
 
-    // Fast path: no wildcard relations and no specific dontFragment relations
-    if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
+    // Fast path: no wildcard relations and no specific sparse relations
+    if (this.wildcardTypes.length === 0 && this.specificSparseRelationTypes.length === 0) {
       const result: EntityId[] = [];
       for (const archetype of this.cachedArchetypes) {
         for (const entity of archetype.getEntities()) {
@@ -100,7 +100,7 @@ export class Query {
     // Slow path: need to filter entities that actually have the required relations
     // This is necessary for:
     // 1. Wildcard relations where an archetype can contain entities with/without the relation
-    // 2. Specific dontFragment relations where the archetype only has the wildcard marker
+    // 2. Specific sparse relations where the archetype only has the wildcard marker
     const result: EntityId[] = [];
     for (const archetype of this.cachedArchetypes) {
       for (const entity of archetype.getEntities()) {
@@ -113,7 +113,7 @@ export class Query {
   }
 
   /**
-   * Check if entity matches all query requirements (wildcards and specific dontFragment relations)
+   * Check if entity matches all query requirements (wildcards and specific sparse relations)
    */
   private entityMatchesQuery(archetype: Archetype, entity: EntityId): boolean {
     // Check wildcard relations
@@ -124,8 +124,8 @@ export class Query {
       }
     }
 
-    // Check specific dontFragment relations
-    for (const specificType of this.specificDontFragmentTypes) {
+    // Check specific sparse relations
+    for (const specificType of this.specificSparseRelationTypes) {
       const result = archetype.getOptional(entity, specificType);
       if (result === undefined) {
         return false;

package/src/storage/serialization.ts

@@ -33,9 +33,9 @@ export type SerializedComponent = {
 };
 
 /**
- * Encode an internal EntityId into a SerializedEntityId for snapshots
+ * Core encoding logic (no cache). Extracted so cached wrapper can reuse it without duplication.
  */
-export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
+function encodeEntityIdCore(id: EntityId<any>): SerializedEntityId {
   const detailed = getDetailedIdType(id);
   switch (detailed.type) {
     case "component": {
@@ -81,6 +81,33 @@ export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
   }
 }
 
+/**
+ * Encode an internal EntityId into a SerializedEntityId for snapshots.
+ * Use encodeEntityIdCached when serializing many entities to benefit from memoization
+ * of repeated component/relation type IDs.
+ */
+export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
+  return encodeEntityIdCore(id);
+}
+
+/**
+ * Encode an EntityId, using an optional cache Map to avoid repeated getDetailedIdType
+ * + name lookup work for IDs that appear many times (typical during full world snapshot).
+ */
+export function encodeEntityIdCached(
+  id: EntityId<any>,
+  cache?: Map<EntityId<any>, SerializedEntityId>,
+): SerializedEntityId {
+  if (cache) {
+    const cached = cache.get(id);
+    if (cached !== undefined) return cached;
+    const result = encodeEntityIdCore(id);
+    cache.set(id, result);
+    return result;
+  }
+  return encodeEntityIdCore(id);
+}
+
 /**
  * Decode a SerializedEntityId back into an internal EntityId
  */

package/src/types/index.ts

@@ -97,3 +97,74 @@ export interface LifecycleHookEntry {
   /** Archetypes that match this hook, used for precise cleanup on unsubscription */
   matchedArchetypes?: Set<any>;
 }
+
+/**
+ * Statistics payload delivered to callbacks registered via `World.createDebugStatsCollector`.
+ *
+ * All structural counts are snapshots taken after the sync that triggered delivery.
+ * `activity` always reflects work performed during that specific sync.
+ *
+ * Timestamps are raw `performance.now()` values suitable for `performance.measure`.
+ */
+export interface SyncDebugStats {
+  readonly timestamps: {
+    readonly syncStart: number;
+    readonly syncEnd: number;
+    readonly commandBufferStart: number;
+    readonly commandBufferEnd: number;
+  };
+
+  /** Number of iterations the internal command buffer loop performed during this sync. */
+  readonly commandIterations: number;
+
+  readonly entities: {
+    readonly total: number;
+    readonly freelistSize: number;
+    readonly nextId: number;
+  };
+
+  readonly archetypes: {
+    readonly total: number;
+    readonly empty: number;
+  };
+
+  readonly queries: {
+    readonly cached: number;
+    readonly registered: number;
+  };
+
+  readonly hooks: {
+    readonly total: number;
+  };
+
+  /** Sizes of stable internal reverse indices (conservative set). */
+  readonly indices: {
+    readonly entityReferences: number;
+    readonly entityToReferencingArchetypes: number;
+    readonly archetypesByComponent: number;
+  };
+
+  /**
+   * Activity that occurred as a direct result of this sync.
+   * All fields are always present (never optional).
+   */
+  readonly activity: {
+    /** Number of entities that performed an archetype migration (hasArchetypeStructuralChange was true). */
+    readonly migrations: number;
+    /** Total number of individual hook callback invocations (invokeHook calls). */
+    readonly hooksExecuted: number;
+    /** Number of new archetypes created during this sync. */
+    readonly archetypesCreated: number;
+    /** Number of archetypes removed during this sync. */
+    readonly archetypesRemoved: number;
+  };
+}
+
+/**
+ * Handle returned by `World.createDebugStatsCollector`.
+ * The object itself carries no data — its only responsibility is lifetime management.
+ * Use with `using` or call `[Symbol.dispose]()` when you no longer need collection.
+ */
+export interface DebugStatsCollector {
+  [Symbol.dispose](): void;
+}