iris-ecs 0.0.1

package/dist/event.d.ts

@@ -0,0 +1,237 @@
+import type { Schema, SchemaRecord } from "./schema.js";
+import type { World } from "./world.js";
+/**
+ * Event ID brand for nominal typing.
+ */
+declare const EVENT_BRAND: unique symbol;
+/**
+ * Event schema brand for carrying schema type in Event.
+ */
+declare const EVENT_SCHEMA_BRAND: unique symbol;
+/**
+ * Event schema type.
+ *
+ * Maps field names to their schema definitions (same as component schema).
+ */
+export type EventSchema = SchemaRecord;
+/**
+ * Event data type inference.
+ *
+ * - Empty schema {} -> undefined (tag event)
+ * - Non-empty schema -> resolved data object
+ */
+export type EventData<T extends EventSchema> = keyof T extends never ? undefined : {
+    [K in keyof T]: T[K] extends Schema<infer U> ? U : never;
+};
+/**
+ * Event ID (branded type).
+ *
+ * Nominal type for events defined via defineEvent().
+ */
+export type EventId<S extends EventSchema = EventSchema> = number & {
+    [EVENT_BRAND]: true;
+    [EVENT_SCHEMA_BRAND]: S;
+};
+/**
+ * Event definition.
+ *
+ * Global event definition with schema for type-safe event data.
+ */
+export type Event<S extends EventSchema = EventSchema> = {
+    /**
+     * Unique event ID.
+     */
+    readonly id: EventId<S>;
+    /**
+     * Event name (user-defined).
+     */
+    readonly name: string;
+    /**
+     * Field schemas for event data (empty for tag events).
+     */
+    readonly schema: S;
+};
+/**
+ * Internal event entry with tick.
+ *
+ * Stores event data along with the tick it was emitted at.
+ */
+export type EventEntry<T extends EventSchema = EventSchema> = {
+    /**
+     * Event data (undefined for tag events).
+     */
+    data: EventData<T>;
+    /**
+     * Tick when event was emitted.
+     */
+    tick: number;
+};
+/**
+ * Per-world event queue metadata.
+ */
+export type EventQueueMeta<T extends EventSchema = EventSchema> = {
+    /**
+     * Event definition reference.
+     */
+    event: Event<T>;
+    /**
+     * Queue of event entries.
+     */
+    events: EventEntry<T>[];
+    /**
+     * Execution tick tracking for event consumption.
+     */
+    lastTick: {
+        /**
+         * Tick when events last consumed outside any system.
+         */
+        self: number;
+        /**
+         * Per-system consumption ticks: systemId -> tick
+         */
+        bySystemId: Map<string, number>;
+    };
+};
+/**
+ * Number of ticks before events expire.
+ *
+ * Events persist for this many ticks to ensure systems can read regardless
+ * of execution order.
+ */
+export declare const EVENT_EXPIRY_TICKS = 2;
+/**
+ * Define event type.
+ *
+ * Allocates unique event ID with optional schema for type-safe event data.
+ * Tag events (no schema) use void for data type - emit() requires no data argument.
+ *
+ * @param name - Event name for debugging
+ * @param schema - Optional field schema record (omit for tag events)
+ * @returns Event definition
+ *
+ * @example
+ * ```typescript
+ * // Tag event (no data)
+ * const GameStarted = defineEvent("GameStarted");
+ * emit(world, GameStarted); // No data argument
+ *
+ * // Data event
+ * const DamageDealt = defineEvent("DamageDealt", {
+ *   target: Type.u32(),
+ *   amount: Type.f32(),
+ * });
+ * emit(world, DamageDealt, { target: enemy, amount: 25 });
+ * ```
+ */
+export declare function defineEvent<S extends EventSchema = Record<never, never>>(name: string, schema?: S): Event<S>;
+/**
+ * Ensure event queue exists for given event in world.
+ *
+ * Creates queue lazily on first access (emit or fetch).
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Event queue metadata
+ */
+export declare function ensureEventQueue<S extends EventSchema>(world: World, event: Event<S>): EventQueueMeta<S>;
+/**
+ * Emit event to world.
+ *
+ * Tag events (empty schema) require no data argument.
+ * Data events require data matching the schema.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @param args - Event data (only for data events)
+ */
+export declare function emitEvent<S extends EventSchema>(world: World, event: Event<S>, ...args: keyof S extends never ? [] : [data: EventData<S>]): void;
+/**
+ * Fetch events emitted since last call.
+ *
+ * Per-system isolated: each system has independent tracking of which events
+ * it has consumed. Multiple systems can consume the same events independently.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Generator yielding event data
+ *
+ * @example
+ * ```typescript
+ * for (const event of fetchEvents(world, DamageDealt)) {
+ *   applyDamage(event.target, event.amount);
+ * }
+ * ```
+ */
+export declare function fetchEvents<S extends EventSchema>(world: World, event: Event<S>): Generator<EventData<S>>;
+/**
+ * Check if there are unread events for current context.
+ *
+ * Does not mark events as read or trigger cleanup.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns True if unread events exist
+ *
+ * @example
+ * ```typescript
+ * if (hasEvents(world, DamageDealt)) {
+ *   // Process damage events
+ * }
+ * ```
+ */
+export declare function hasEvents<S extends EventSchema>(world: World, event: Event<S>): boolean;
+/**
+ * Count unread events for current context.
+ *
+ * Does not mark events as read or trigger cleanup.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Number of unread events
+ *
+ * @example
+ * ```typescript
+ * const damageCount = countEvents(world, DamageDealt);
+ * console.log(`${damageCount} damage events this tick`);
+ * ```
+ */
+export declare function countEvents<S extends EventSchema>(world: World, event: Event<S>): number;
+/**
+ * Fetch only the most recent event, marking all as read.
+ *
+ * Useful when only the latest state matters (e.g., input, config changes).
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Most recent event data, or undefined if no unread events
+ *
+ * @example
+ * ```typescript
+ * // Only care about the latest input state
+ * const input = fetchLastEvent(world, InputChanged);
+ * if (input) {
+ *   updatePlayerDirection(input.direction);
+ * }
+ * ```
+ */
+export declare function fetchLastEvent<S extends EventSchema>(world: World, event: Event<S>): EventData<S> | undefined;
+/**
+ * Clear events (mark as read without processing).
+ *
+ * Useful when a system needs to skip events under certain conditions.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ *
+ * @example
+ * ```typescript
+ * if (isPaused) {
+ *   // Skip damage events while paused
+ *   clearEvents(world, DamageDealt);
+ *   return;
+ * }
+ * ```
+ */
+export declare function clearEvents<S extends EventSchema>(world: World, event: Event<S>): void;
+export {};
+//# sourceMappingURL=event.d.ts.map

package/dist/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"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"}

package/dist/event.js

@@ -0,0 +1,293 @@
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Number of ticks before events expire.
+ *
+ * Events persist for this many ticks to ensure systems can read regardless
+ * of execution order.
+ */
+export const EVENT_EXPIRY_TICKS = 2;
+/**
+ * Global event registry singleton.
+ */
+const EVENT_REGISTRY = {
+    byId: new Map(),
+    nextId: 0,
+};
+// ============================================================================
+// Event Definition
+// ============================================================================
+/**
+ * Define event type.
+ *
+ * Allocates unique event ID with optional schema for type-safe event data.
+ * Tag events (no schema) use void for data type - emit() requires no data argument.
+ *
+ * @param name - Event name for debugging
+ * @param schema - Optional field schema record (omit for tag events)
+ * @returns Event definition
+ *
+ * @example
+ * ```typescript
+ * // Tag event (no data)
+ * const GameStarted = defineEvent("GameStarted");
+ * emit(world, GameStarted); // No data argument
+ *
+ * // Data event
+ * const DamageDealt = defineEvent("DamageDealt", {
+ *   target: Type.u32(),
+ *   amount: Type.f32(),
+ * });
+ * emit(world, DamageDealt, { target: enemy, amount: 25 });
+ * ```
+ */
+export function defineEvent(name, schema) {
+    const id = EVENT_REGISTRY.nextId++;
+    const event = {
+        id,
+        name,
+        schema: schema ?? {},
+    };
+    EVENT_REGISTRY.byId.set(id, event);
+    return event;
+}
+// ============================================================================
+// Per-World Event Queue Management
+// ============================================================================
+/**
+ * Ensure event queue exists for given event in world.
+ *
+ * Creates queue lazily on first access (emit or fetch).
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Event queue metadata
+ */
+export function ensureEventQueue(world, event) {
+    let queue = world.events.byId.get(event.id);
+    if (!queue) {
+        queue = {
+            event: event,
+            events: [],
+            lastTick: {
+                self: 0,
+                bySystemId: new Map(),
+            },
+        };
+        world.events.byId.set(event.id, queue);
+    }
+    return queue;
+}
+// ============================================================================
+// Event Emission
+// ============================================================================
+/**
+ * Emit event to world.
+ *
+ * Tag events (empty schema) require no data argument.
+ * Data events require data matching the schema.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @param args - Event data (only for data events)
+ */
+export function emitEvent(world, event, ...args) {
+    const queue = ensureEventQueue(world, event);
+    const data = args[0];
+    const tick = world.execution.tick;
+    queue.events.push({ data, tick });
+}
+// ============================================================================
+// Event Reading
+// ============================================================================
+/**
+ * Update lastTick for current execution context.
+ *
+ * Internal helper shared by fetchEvents, fetchLastEvent, and clearEvents.
+ *
+ * @param world - World instance
+ * @param queue - Event queue metadata
+ */
+function markEventsRead(world, queue) {
+    const { systemId, tick } = world.execution;
+    if (systemId === null) {
+        queue.lastTick.self = tick;
+    }
+    else {
+        queue.lastTick.bySystemId.set(systemId, tick);
+    }
+}
+/**
+ * Remove expired events from queue.
+ *
+ * Events older than EVENT_EXPIRY_TICKS are removed to prevent unbounded growth.
+ *
+ * @param world - World instance
+ * @param queue - Event queue metadata
+ */
+function cleanupExpiredEvents(world, queue) {
+    const expiryTick = world.execution.tick - EVENT_EXPIRY_TICKS;
+    // Find first non-expired index
+    let firstValidIndex = 0;
+    while (firstValidIndex < queue.events.length && queue.events[firstValidIndex].tick <= expiryTick) {
+        firstValidIndex++;
+    }
+    // Remove expired events from front
+    if (firstValidIndex > 0) {
+        queue.events.splice(0, firstValidIndex);
+    }
+}
+/**
+ * Fetch events emitted since last call.
+ *
+ * Per-system isolated: each system has independent tracking of which events
+ * it has consumed. Multiple systems can consume the same events independently.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Generator yielding event data
+ *
+ * @example
+ * ```typescript
+ * for (const event of fetchEvents(world, DamageDealt)) {
+ *   applyDamage(event.target, event.amount);
+ * }
+ * ```
+ */
+export function* fetchEvents(world, event) {
+    const queue = ensureEventQueue(world, event);
+    const { systemId, tick } = world.execution;
+    // Get lastTick for this execution context
+    const lastTick = systemId === null ? queue.lastTick.self : (queue.lastTick.bySystemId.get(systemId) ?? 0);
+    try {
+        for (let i = 0; i < queue.events.length; i++) {
+            const entry = queue.events[i];
+            // Event must have been emitted AFTER lastTick but AT or BEFORE current tick
+            if (entry.tick > lastTick && entry.tick <= tick) {
+                yield entry.data;
+            }
+        }
+    }
+    finally {
+        markEventsRead(world, queue);
+        cleanupExpiredEvents(world, queue);
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Check if there are unread events for current context.
+ *
+ * Does not mark events as read or trigger cleanup.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns True if unread events exist
+ *
+ * @example
+ * ```typescript
+ * if (hasEvents(world, DamageDealt)) {
+ *   // Process damage events
+ * }
+ * ```
+ */
+export function hasEvents(world, event) {
+    const queue = ensureEventQueue(world, event);
+    const { systemId, tick } = world.execution;
+    const lastTick = systemId === null ? queue.lastTick.self : (queue.lastTick.bySystemId.get(systemId) ?? 0);
+    for (let i = 0; i < queue.events.length; i++) {
+        const entry = queue.events[i];
+        if (entry.tick > lastTick && entry.tick <= tick) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Count unread events for current context.
+ *
+ * Does not mark events as read or trigger cleanup.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Number of unread events
+ *
+ * @example
+ * ```typescript
+ * const damageCount = countEvents(world, DamageDealt);
+ * console.log(`${damageCount} damage events this tick`);
+ * ```
+ */
+export function countEvents(world, event) {
+    const queue = ensureEventQueue(world, event);
+    const { systemId, tick } = world.execution;
+    const lastTick = systemId === null ? queue.lastTick.self : (queue.lastTick.bySystemId.get(systemId) ?? 0);
+    let count = 0;
+    for (let i = 0; i < queue.events.length; i++) {
+        const entry = queue.events[i];
+        if (entry.tick > lastTick && entry.tick <= tick) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Fetch only the most recent event, marking all as read.
+ *
+ * Useful when only the latest state matters (e.g., input, config changes).
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ * @returns Most recent event data, or undefined if no unread events
+ *
+ * @example
+ * ```typescript
+ * // Only care about the latest input state
+ * const input = fetchLastEvent(world, InputChanged);
+ * if (input) {
+ *   updatePlayerDirection(input.direction);
+ * }
+ * ```
+ */
+export function fetchLastEvent(world, event) {
+    const queue = ensureEventQueue(world, event);
+    const { systemId, tick } = world.execution;
+    const lastTick = systemId === null ? queue.lastTick.self : (queue.lastTick.bySystemId.get(systemId) ?? 0);
+    // Find last matching event (iterate backwards, break early)
+    let result;
+    for (let i = queue.events.length - 1; i >= 0; i--) {
+        const entry = queue.events[i];
+        if (entry.tick > lastTick && entry.tick <= tick) {
+            result = entry.data;
+            break;
+        }
+    }
+    markEventsRead(world, queue);
+    cleanupExpiredEvents(world, queue);
+    return result;
+}
+/**
+ * Clear events (mark as read without processing).
+ *
+ * Useful when a system needs to skip events under certain conditions.
+ *
+ * @param world - World instance
+ * @param event - Event definition
+ *
+ * @example
+ * ```typescript
+ * if (isPaused) {
+ *   // Skip damage events while paused
+ *   clearEvents(world, DamageDealt);
+ *   return;
+ * }
+ * ```
+ */
+export function clearEvents(world, event) {
+    const queue = ensureEventQueue(world, event);
+    markEventsRead(world, queue);
+    cleanupExpiredEvents(world, queue);
+}
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"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"}

package/dist/filters.d.ts

@@ -0,0 +1,121 @@
+import type { Archetype } from "./archetype.js";
+import type { EntityId } from "./encoding.js";
+import type { Observer } from "./observer.js";
+import type { World } from "./world.js";
+/**
+ * Filter terms for archetype matching.
+ *
+ * Specifies inclusion and exclusion constraints for archetype selection.
+ */
+export type FilterTerms = {
+    /**
+     * Required component IDs (all must be present).
+     */
+    include: EntityId[];
+    /**
+     * Excluded component IDs (none must be present).
+     */
+    exclude: EntityId[];
+};
+/**
+ * Filter metadata for registry caching.
+ *
+ * Stores filter terms, matched archetypes, and observer callbacks.
+ */
+export type FilterMeta = {
+    /**
+     * Filter terms (include/exclude constraints).
+     */
+    terms: FilterTerms;
+    /**
+     * Matched archetypes (cached result of findMatchingArchetypes).
+     */
+    archetypes: Archetype[];
+    /**
+     * Observer callback for archetype creation.
+     */
+    onArchetypeCreate: Observer<"archetypeCreated">;
+    /**
+     * Observer callback for archetype destruction.
+     */
+    onArchetypeDelete: Observer<"archetypeDestroyed">;
+};
+/**
+ * Generates a unique hash string for filter terms.
+ *
+ * @param terms - Filter terms containing include/exclude type arrays
+ * @returns Deterministic hash string (e.g., "+1:5:12|-3:7")
+ *
+ * @example
+ * const hash = hashFilterTerms({ include: [5, 1, 12], exclude: [7, 3] });
+ * // Returns "+1:5:12|-3:7" (sorted for consistency)
+ */
+export declare function hashFilterTerms(terms: FilterTerms): string;
+/**
+ * Tests whether an archetype satisfies the given filter terms.
+ *
+ * @param archetype - Archetype to test against filter
+ * @param terms - Filter terms with include/exclude type constraints
+ * @returns True if archetype contains ALL included types and NONE of excluded types
+ *
+ * @example
+ * const matches = matchesFilterTerms(archetype, {
+ *   include: [PositionType, VelocityType],
+ *   exclude: [DisabledType]
+ * });
+ */
+export declare function matchesFilterTerms(archetype: Archetype, terms: FilterTerms): boolean;
+/**
+ * Finds all archetypes matching filter terms using rarest-type optimization.
+ *
+ * Uses the "rarest type first" strategy: starts with the type that appears in
+ * the fewest archetypes, then filters that smaller set. This minimizes the
+ * number of archetypes we need to check.
+ *
+ * @param world - World instance containing archetype registry
+ * @param terms - Filter terms with include/exclude type constraints
+ * @returns Array of archetypes that match all filter criteria
+ *
+ * @example
+ * const archetypes = findMatchingArchetypes(world, {
+ *   include: [PositionType, VelocityType],
+ *   exclude: []
+ * });
+ */
+export declare function findMatchingArchetypes(world: World, terms: FilterTerms): Archetype[];
+/**
+ * Gets or creates a filter with observer-based cache invalidation.
+ *
+ * Filters are cached by their terms hash. When created, observers are registered
+ * to automatically update the cached archetype list as archetypes are created
+ * or destroyed.
+ *
+ * @param world - World instance containing filter registry
+ * @param terms - Filter terms defining which archetypes to match
+ * @returns FilterMeta with cached matching archetypes
+ *
+ * @example
+ * const filter = ensureFilter(world, {
+ *   include: [PositionType, VelocityType],
+ *   exclude: [DisabledType]
+ * });
+ * // filter.archetypes contains all matching archetypes
+ */
+export declare function ensureFilter(world: World, terms: FilterTerms): FilterMeta;
+/**
+ * Iterates all entities matching a filter in reverse order.
+ *
+ * Reverse iteration allows safe entity deletion during iteration without
+ * skipping entities or invalidating indices.
+ *
+ * @param filter - Filter metadata containing cached matching archetypes
+ * @returns Generator yielding entity IDs from all matching archetypes
+ *
+ * @example
+ * for (const entity of iterateFilterEntities(filter)) {
+ *   // Safe to delete entity here due to reverse iteration
+ *   destroyEntity(world, entity);
+ * }
+ */
+export declare function iterateFilterEntities(filter: FilterMeta): IterableIterator<EntityId>;
+//# sourceMappingURL=filters.d.ts.map

package/dist/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,KAAK,EAAE,WAAW,CAAC;IACnB;;OAEG;IACH,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB;;OAEG;IACH,iBAAiB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAChD;;OAEG;IACH,iBAAiB,EAAE,QAAQ,CAAC,oBAAoB,CAAC,CAAC;CACnD,CAAC;AAMF;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAK1D;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAkBpF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,CAwCpF;AAqBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,UAAU,CAyCzE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAiB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAYrF"}