♻️ core: refactor internals to follow ref-instance pattern

Author: krispya

README.md

@@ -95,10 +95,10 @@ function RocketView({ entity }) {
 Use actions to safely modify Koota from inside of React in either effects or events.
 
 ```js
-import { createActions } from 'koota'
+import { defineActions } from 'koota'
 import { useActions } from 'koota/react'
 
-const actions = createActions((world) => ({
+const actions = defineActions((world) => ({
   spawnShip: (position) => world.spawn(Position(position), Velocity),
   destroyAllShips: () => {
     world.query(Position, Velocity).forEach((entity) => {
@@ -808,7 +808,7 @@ const positions = getStore(world, Position)
 
 A Koota query is a lot like a database query. Parameters define how to find entities and efficiently process them in batches. Queries are the primary way to update and transform your app state, similar to how you'd use SQL to filter and modify database records.
 
-#### Caching queries
+#### Defining queries
 
 Inline queries are great for readability and are optimized to be as fast as possible, but there is still some small overhead in hashing the query each time it is called.
 
@@ -820,13 +820,13 @@ function updateMovement(world) {
 }
 ```
 
-While this is not likely to be a bottleneck in your code compared to the actual update function, if you want to save these CPU cycles you can cache the query ahead of time and use the returned key. This will have the additional effect of creating the internal query immediately on a worlds, otherwise it will get created the first time it is run.
+While this is not likely to be a bottleneck in your code compared to the actual update function, if you want to save these CPU cycles you can cache the query ahead of time and use the returned ref. This will have the additional effect of creating the internal query immediately on all worlds, otherwise it will get created the first time it is run.
 
 ```js
 // The internal query is created immediately before it is invoked
-const movementQuery = cacheQuery(Position, Velocity)
+const movementQuery = defineQuery(Position, Velocity)
 
-// They query key is hashed ahead of time and we just use it
+// The query ref is used for fast array-based lookup
 function updateMovement(world) {
   world.query(movementQuery).updateEach(([pos, vel]) => {})
 }
@@ -1016,11 +1016,11 @@ useTraitEffect(world, GameState, (state) => {
 
 ### `useActions`
 
-Returns actions bound to the world that is context. Use actions created by `createActions`.
+Returns actions bound to the world that is in context. Use actions created by `defineActions`.
 
 ```js
 // Create actions
-const actions = createActions((world) => ({
+const actions = defineActions((world) => ({
     spawnPlayer: () => world.spawn(IsPlayer).
     destroyAllPlayers: () => {
         world.query(IsPlayer).forEach((player) => {

packages/core/architecture.md

@@ -0,0 +1,29 @@
+A work in progress document for the architecture of Koota.
+
+Koota allows for many worlds. To make this experience simple there are global, stateless **refs** that get lazily **instantiated** on a world whenever it is used. Examples of this are:
+
+- Traits
+- Relations
+- Queries
+- Actions
+- Tracking modifiers
+
+A world is the context and holds the underlying storage, manages entities and the general lifecycle for data changes. Refs get instantiated on a world and use the id as a key for its instance.
+
+Traits are a user-facing handle for storage. The user never interacts with stores directly and isntead deals with the mental model of traits -- composable pieces of semantic data.
+
+## Glossary
+
+**Ref.** A stateless, global definition returned by factory functions (`trait()`, `relation()`, `createQuery()`, `createActions()`). Refs are world-agnostic and contain only definition data (schema, configuration) plus a unique ID for fast lookups. Users interact primarily with refs. Since the user is not aware of internals like instances and only see the ref, the ref type is usually named as the target concept, such as `Trait` or `Query`.
+
+**Instance.** Per-world state created from a ref. Contains world-specific data like stores, subscriptions, query results, and bitmasks. Examples: `TraitInstance`, `QueryInstance`. Instances are internal — users don't interact with them directly.
+
+**Register.** The process of creating an instance for a ref on a world. Happens lazily on first use. Allocates storage, sets up bitmasks, and integrates with the world's query system.
+
+**Create.** The verb used for all factory functions. `create*` functions return refs (`createQuery`, `createActions`, `createAdded`) or instances (`createWorld`). The primitives `trait()` and `relation()` omit the verb for brevity. We used to use `define*` to differentiate creating a ref and creating an instance, but we now juse use `create*` in all cases and try to make this process hidden from the user.
+
+**World.** The context that holds all per-world state. Contains storage, trait instances, query instances, action instances, and manages the lifecycle of data changes.
+
+**Schema.** The shape definition for trait data. Can be SoA (struct of arrays), AoS (array of structs via factory function), or empty (tag trait).
+
+**Store.** The actual per-world storage for trait data, created from a schema. SoA stores have one array per property; AoS stores have one array of objects.

packages/core/src/actions/create-actions.ts

@@ -1,24 +1,46 @@
+import { $internal } from '../common';
 import type { World } from '../world';
-import type { ActionGetter, ActionInitializer, Actions } from './types';
+import type { Actions, ActionsInitializer, ActionRecord } from './types';
 
-const actionCache = new WeakMap<World, Map<(...args: any[]) => any, Actions>>();
+let actionsId = 0;
 
-export function createActions<T extends Actions>(initializer: ActionInitializer<T>): ActionGetter<T> {
-	return (world: World): T => {
-		let worldCache = actionCache.get(world);
+export function createActions<T extends ActionRecord>(
+	initializer: ActionsInitializer<T>
+): Actions<T> {
+	const id = actionsId++;
 
-		if (!worldCache) {
-			worldCache = new Map();
-			actionCache.set(world, worldCache);
-		}
+	const actions = Object.assign(
+		(world: World): T => {
+			const ctx = world[$internal];
+
+			// Try array lookup first (faster)
+			let instance = ctx.actionInstances[id];
 
-		let actions = worldCache.get(initializer);
+			if (!instance) {
+				// Create and cache actions instance
+				instance = initializer(world);
 
-		if (!actions) {
-			actions = initializer(world);
-			worldCache.set(initializer, actions);
+				// Ensure array is large enough
+				if (id >= ctx.actionInstances.length) {
+					ctx.actionInstances.length = id + 1;
+				}
+				ctx.actionInstances[id] = instance;
+			}
+
+			return instance as T;
+		},
+		{
+			initializer,
 		}
+	) as Actions<T>;
+
+	// Add public read-only id property
+	Object.defineProperty(actions, 'id', {
+		value: id,
+		writable: false,
+		enumerable: true,
+		configurable: false,
+	});
 
-		return actions as T;
-	};
+	return actions;
 }

packages/core/src/actions/types.ts

@@ -1,5 +1,12 @@
 import type { World } from '../world';
 
-export type Actions = Record<string, (...args: any[]) => void>;
-export type ActionInitializer<T extends Actions> = (world: World) => T;
-export type ActionGetter<T extends Actions> = (world: World) => T;
+export type ActionRecord = Record<string, (...args: any[]) => void>;
+export type ActionsInitializer<T extends ActionRecord> = (world: World) => T;
+export type Actions<T extends ActionRecord> = {
+	/** Public read-only ID for fast array lookups */
+	readonly id: number;
+	/** Initializer function */
+	readonly initializer: ActionsInitializer<T>;
+} & ((world: World) => T);
+
+export type ActionInstance = ActionRecord;

packages/core/src/common.ts

@@ -1 +1,7 @@
 export const $internal = Symbol.for('koota.internal');
+
+/**
+ * Type utility for symbol-branded runtime type checks.
+ * Allows accessing a symbol property while maintaining type safety.
+ */
+export type Brand<S extends symbol> = { readonly [K in S]?: true };

packages/core/src/entity/entity-methods-patch.ts

@@ -5,13 +5,9 @@
 
 import { $internal } from '../common';
 import { setChanged } from '../query/modifiers/changed';
-import {
-	getFirstRelationTarget,
-	getRelationTargets,
-	hasRelationPair,
-	isRelationPair,
-} from '../relation/relation';
+import { getFirstRelationTarget, getRelationTargets, hasRelationPair } from '../relation/relation';
 import type { Relation, RelationPair } from '../relation/types';
+import { isRelationPair } from '../relation/utils/is-relation';
 import { addTrait, getTrait, hasTrait, removeTrait, setTrait } from '../trait/trait';
 import type { ConfigurableTrait, Trait } from '../trait/types';
 import { destroyEntity, getEntityWorld } from './entity';

packages/core/src/index.ts

@@ -1,5 +1,5 @@
 export { createActions } from './actions/create-actions';
-export type { ActionGetter, ActionInitializer, Actions } from './actions/types';
+export type { Actions, ActionsInitializer, ActionRecord } from './actions/types';
 export { $internal } from './common';
 export type { Entity } from './entity/types';
 export { unpackEntity } from './entity/utils/pack-entity';
@@ -8,24 +8,26 @@ export { createChanged } from './query/modifiers/changed';
 export { Not } from './query/modifiers/not';
 export { Or } from './query/modifiers/or';
 export { createRemoved } from './query/modifiers/removed';
-export { IsExcluded } from './query/query';
+export { $modifier } from './query/modifier';
+export { createQuery, IsExcluded } from './query/query';
 export type {
 	EventType,
 	InstancesFromParameters,
 	IsNotModifier,
-	ModifierData,
+	Modifier,
 	Query,
-	QueryHash,
 	QueryModifier,
 	QueryParameter,
 	QueryResult,
 	QueryResultOptions,
 	QuerySubscriber,
 	QueryUnsubscriber,
+	QueryHash,
 	StoresFromParameters,
 } from './query/types';
-export { cacheQuery } from './query/utils/cache-query';
-export { isRelation, Pair, relation } from './relation/relation';
+export { $queryRef } from './query/symbols';
+export { relation } from './relation/relation';
+export { $relationPair, $relation } from './relation/symbols';
 export type { Relation, RelationPair, RelationTarget } from './relation/types';
 export { getStore, trait } from './trait/trait';
 export type {
@@ -37,13 +39,30 @@ export type {
 	SetTraitCallback,
 	TagTrait,
 	Trait,
-	TraitData,
 	TraitRecord,
 	TraitTuple,
 	TraitValue,
 } from './trait/types';
 export type { AoSFactory, Norm, Schema, Store, StoreType } from './storage/types';
 export type { TraitType } from './trait/types';
 export { universe } from './universe/universe';
-export type { World, WorldInternal, WorldOptions } from './world';
+export type { World, WorldOptions } from './world';
 export { createWorld } from './world';
+
+/**
+ * Deprecations. To be removed in v0.7.0.
+ */
+
+import { createQuery } from './query/query';
+/** @deprecated Use createQuery instead */
+export const cacheQuery = createQuery;
+
+import type { TraitInstance } from './trait/types';
+/** @deprecated Use TraitInstance instead */
+export type TraitData = TraitInstance;
+
+/** @deprecated Will remove this internal type entirely */
+export type { TraitInstance } from './trait/types';
+
+/** @deprecated Will remove this internal type entirely */
+export type { QueryInstance } from './query/types';

packages/core/src/query/modifier.ts

@@ -1,23 +1,23 @@
-import { $internal } from '../common';
+import { Brand } from '../common';
 import { Trait } from '../trait/types';
-import { ModifierData, QueryParameter } from './types';
+import { Modifier, QueryParameter } from './types';
 
 export const $modifier = Symbol('modifier');
 
 export function createModifier<TTrait extends Trait[] = Trait[], TType extends string = string>(
 	type: TType,
 	id: number,
 	traits: TTrait
-): ModifierData<TTrait, TType> {
+): Modifier<TTrait, TType> {
 	return {
 		[$modifier]: true,
 		type,
 		id,
 		traits,
-		traitIds: traits.map((trait) => trait[$internal].id),
+		traitIds: traits.map((trait) => trait.id),
 	} as const;
 }
 
-export function isModifier(param: QueryParameter): param is ModifierData {
-	return $modifier in param;
+export /* @inline @pure */ function isModifier(param: QueryParameter): param is Modifier {
+	return (param as Brand<typeof $modifier> | null | undefined)?.[$modifier] as unknown as boolean;
 }

packages/core/src/query/modifiers/added.ts

@@ -1,9 +1,9 @@
 import { $internal } from '../../common';
-import { isRelation } from '../../relation/relation';
+import { isRelation } from '../../relation/utils/is-relation';
 import type { Trait, TraitOrRelation } from '../../trait/types';
 import { universe } from '../../universe/universe';
 import { createModifier } from '../modifier';
-import type { ModifierData } from '../types';
+import type { Modifier } from '../types';
 import { createTrackingId, setTrackingMasks } from '../utils/tracking-cursor';
 
 export function createAdded() {
@@ -16,7 +16,7 @@ export function createAdded() {
 
 	return <T extends TraitOrRelation[] = TraitOrRelation[]>(
 		...inputs: T
-	): ModifierData<Trait[], `added-${number}`> => {
+	): Modifier<Trait[], `added-${number}`> => {
 		const traits = inputs.map((input) => (isRelation(input) ? input[$internal].trait : input));
 		return createModifier(`added-${id}`, id, traits);
 	};

packages/core/src/query/modifiers/changed.ts

@@ -1,14 +1,14 @@
 import { $internal } from '../../common';
 import type { Entity } from '../../entity/types';
 import { getEntityId } from '../../entity/utils/pack-entity';
-import { isRelation } from '../../relation/relation';
+import { isRelation } from '../../relation/utils/is-relation';
 import { hasTrait, registerTrait } from '../../trait/trait';
-import { getTraitData, hasTraitData } from '../../trait/trait-data';
+import { getTraitInstance, hasTraitInstance } from '../../trait/trait-instance';
 import type { Trait, TraitOrRelation } from '../../trait/types';
 import { universe } from '../../universe/universe';
 import type { World } from '../../world';
 import { createModifier } from '../modifier';
-import type { ModifierData } from '../types';
+import type { Modifier } from '../types';
 import { checkQueryTrackingWithRelations } from '../utils/check-query-tracking-with-relations';
 import { createTrackingId, setTrackingMasks } from '../utils/tracking-cursor';
 
@@ -22,7 +22,7 @@ export function createChanged() {
 
 	return <T extends TraitOrRelation[] = TraitOrRelation[]>(
 		...inputs: T
-	): ModifierData<Trait[], `changed-${number}`> => {
+	): Modifier<Trait[], `changed-${number}`> => {
 		const traits = inputs.map((input) => (isRelation(input) ? input[$internal].trait : input));
 		return createModifier(`changed-${id}`, id, traits);
 	};
@@ -35,14 +35,14 @@ export function setChanged(world: World, entity: Entity, trait: Trait) {
 	if (!hasTrait(world, entity, trait)) return;
 
 	// Register the trait if it's not already registered.
-	if (!hasTraitData(ctx.traitData, trait)) registerTrait(world, trait);
-	const data = getTraitData(ctx.traitData, trait)!;
+	if (!hasTraitInstance(ctx.traitInstances, trait)) registerTrait(world, trait);
+	const data = getTraitInstance(ctx.traitInstances, trait)!;
 
 	// Mark the trait as changed for the entity.
 	// This is used for filling initial values for Changed modifiers.
 	for (const changedMask of ctx.changedMasks.values()) {
 		const eid = getEntityId(entity);
-		const data = getTraitData(ctx.traitData, trait)!;
+		const data = getTraitInstance(ctx.traitInstances, trait)!;
 		const { generationId, bitflag } = data;
 
 		// Ensure the generation array exists