iris-ecs 0.0.1

package/dist/resource.js

@@ -0,0 +1,86 @@
+import { addComponent, getComponentValue, hasComponent, removeComponent, setComponentValue } from "./component.js";
+/**
+ * Adds a global resource (singleton) to the world using the component-on-self pattern.
+ *
+ * Resources are stored by adding the component to itself as an entity. Idempotent if already present.
+ *
+ * @param world - World instance
+ * @param component - Component definition to use as resource
+ * @param data - Initial values for the resource
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * const Time = defineComponent("Time", { delta: Type.f32() });
+ * addResource(world, Time, { delta: 0.016 });
+ * ```
+ */
+export function addResource(world, component, data) {
+    addComponent(world, component, component, data);
+}
+/**
+ * Removes a global resource from the world.
+ *
+ * @param world - World instance
+ * @param component - Component definition (acting as resource handle)
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * removeResource(world, Time);
+ * ```
+ */
+export function removeResource(world, component) {
+    removeComponent(world, component, component);
+}
+/**
+ * Checks if a global resource exists in the world.
+ *
+ * @param world - World instance
+ * @param component - Component definition (acting as resource handle)
+ * @returns True if the resource exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasResource(world, Time)) {
+ *   // Time resource is available
+ * }
+ * ```
+ */
+export function hasResource(world, component) {
+    return hasComponent(world, component, component);
+}
+/**
+ * Gets the value of a specific field on a global resource.
+ *
+ * @param world - World instance
+ * @param component - Component definition
+ * @param key - Field name to retrieve
+ * @returns The field value, or undefined if the resource is not present
+ *
+ * @example
+ * ```typescript
+ * const dt = getResourceValue(world, Time, "delta");
+ * ```
+ */
+export function getResourceValue(world, component, key) {
+    return getComponentValue(world, component, component, key);
+}
+/**
+ * Sets the value of a specific field on a global resource.
+ *
+ * @param world - World instance
+ * @param component - Component definition
+ * @param key - Field name to set
+ * @param value - New value for the field
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * setResourceValue(world, Time, "delta", 0.033);
+ * ```
+ */
+export function setResourceValue(world, component, key, value) {
+    setComponentValue(world, component, component, key, value);
+}
+//# sourceMappingURL=resource.js.map

package/dist/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKnH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CACzB,KAAY,EACZ,SAAuB,EACvB,IAA0B;IAE1B,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,SAAmB;IAC9D,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,SAAmB;IAC3D,OAAO,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAY,EACZ,SAAuB,EACvB,GAAM;IAEN,OAAO,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAY,EACZ,SAAuB,EACvB,GAAM,EACN,KAAwB;IAExB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/dist/scheduler.d.ts

@@ -0,0 +1,106 @@
+import type { World } from "./world.js";
+/**
+ * Schedule identifier.
+ *
+ * Provides autocomplete for common schedules while allowing custom names.
+ */
+export type ScheduleId = "runtime" | "startup" | "shutdown" | (string & {});
+/**
+ * System function signature.
+ *
+ * Takes world, returns void or Promise for async systems.
+ */
+export type SystemRunner = (world: World) => void | Promise<void>;
+/**
+ * Options for system registration.
+ */
+export type SystemOptions = {
+    /**
+     * Custom name (overrides function.name). Required for anonymous functions.
+     */
+    name?: string;
+    /**
+     * Schedule this system belongs to. Defaults to 'runtime'.
+     */
+    schedule?: ScheduleId;
+    /**
+     * Run before these systems (within same schedule).
+     */
+    before?: string | string[];
+    /**
+     * Run after these systems (within same schedule).
+     */
+    after?: string | string[];
+};
+/**
+ * System metadata stored in registry.
+ */
+export type SystemMeta = {
+    /**
+     * Function to execute.
+     */
+    runner: SystemRunner;
+    /**
+     * Schedule this system belongs to.
+     */
+    schedule: ScheduleId;
+    /**
+     * Registration order (for stable sort).
+     */
+    index: number;
+    /**
+     * Systems this one must execute before (these run after this system).
+     */
+    before: string[];
+    /**
+     * Systems this one must execute after (these run before this system).
+     */
+    after: string[];
+};
+/**
+ * Registers a system in the world for later scheduling.
+ *
+ * @param world - World instance
+ * @param runner - System function (must be named unless name option provided)
+ * @param options - Registration options (name, schedule, before, after)
+ * @returns void
+ * @example
+ * addSystem(world, physicsSystem);
+ * addSystem(world, renderSystem, { after: "physicsSystem" });
+ */
+export declare function addSystem(world: World, runner: SystemRunner, options?: SystemOptions): void;
+/**
+ * Builds an execution order from registered systems using topological sort.
+ * Systems are ordered by before/after constraints, with registration order as tiebreaker.
+ *
+ * @param world - World instance
+ * @param scheduleId - Schedule identifier (defaults to "runtime")
+ * @returns void
+ * @example
+ * buildSchedule(world);
+ * buildSchedule(world, "startup");
+ */
+export declare function buildSchedule(world: World, scheduleId?: ScheduleId): void;
+/**
+ * Executes a schedule synchronously. Throws if any system returns a Promise.
+ *
+ * @param world - World instance
+ * @param scheduleId - Schedule identifier (defaults to "runtime")
+ * @returns void
+ * @example
+ * executeSchedule(world);
+ * executeSchedule(world, "startup");
+ */
+export declare function executeSchedule(world: World, scheduleId?: ScheduleId): void;
+/**
+ * Executes a schedule with async support. Awaits systems that return Promises.
+ *
+ * @param world - World instance
+ * @param scheduleId - Schedule identifier (defaults to "runtime")
+ * @returns Promise that resolves when all systems complete
+ * @example
+ * await executeScheduleAsync(world);
+ * await executeScheduleAsync(world, "startup");
+ */
+export declare function executeScheduleAsync(world: World, scheduleId?: ScheduleId): Promise<void>;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;IAEtB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;OAEG;IACH,QAAQ,EAAE,UAAU,CAAC;IAErB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAuB3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,GAAE,UAAsB,GAAG,IAAI,CAwFpF;AA0BD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,GAAE,UAAsB,GAAG,IAAI,CA2BtF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,GAAE,UAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B1G"}

package/dist/scheduler.js

@@ -0,0 +1,204 @@
+/**
+ * Registers a system in the world for later scheduling.
+ *
+ * @param world - World instance
+ * @param runner - System function (must be named unless name option provided)
+ * @param options - Registration options (name, schedule, before, after)
+ * @returns void
+ * @example
+ * addSystem(world, physicsSystem);
+ * addSystem(world, renderSystem, { after: "physicsSystem" });
+ */
+export function addSystem(world, runner, options) {
+    // Derive system name from function name or explicit option
+    const name = options?.name ?? runner.name;
+    if (!name || name === "anonymous") {
+        throw new TypeError("System function must be named or provide name option");
+    }
+    if (world.systems.byId.has(name)) {
+        throw new Error(`System "${name}" already registered`);
+    }
+    // Normalize before/after constraints to arrays for consistent handling
+    const before = options?.before;
+    const after = options?.after;
+    world.systems.byId.set(name, {
+        runner,
+        schedule: options?.schedule ?? "runtime",
+        index: world.systems.nextIndex++,
+        before: !before ? [] : Array.isArray(before) ? before : [before],
+        after: !after ? [] : Array.isArray(after) ? after : [after],
+    });
+}
+/**
+ * Builds an execution order from registered systems using topological sort.
+ * Systems are ordered by before/after constraints, with registration order as tiebreaker.
+ *
+ * @param world - World instance
+ * @param scheduleId - Schedule identifier (defaults to "runtime")
+ * @returns void
+ * @example
+ * buildSchedule(world);
+ * buildSchedule(world, "startup");
+ */
+export function buildSchedule(world, scheduleId = "runtime") {
+    // Filter systems belonging to this schedule
+    const scheduleSystems = new Map();
+    for (const [name, meta] of world.systems.byId) {
+        if (meta.schedule === scheduleId) {
+            scheduleSystems.set(name, meta);
+        }
+    }
+    if (scheduleSystems.size === 0) {
+        world.schedules.byId.set(scheduleId, []);
+        return;
+    }
+    // Build dependency graph for Kahn's algorithm
+    const adjacency = new Map();
+    const inDegree = new Map();
+    for (const name of scheduleSystems.keys()) {
+        adjacency.set(name, []);
+        inDegree.set(name, 0);
+    }
+    // Convert before/after constraints into directed edges
+    for (const [name, meta] of scheduleSystems) {
+        for (const beforeName of meta.before) {
+            if (!scheduleSystems.has(beforeName)) {
+                throw new Error(`System "${name}" references unknown system "${beforeName}" in schedule "${scheduleId}"`);
+            }
+            // "A before B" means edge A -> B (A must run first)
+            adjacency.get(name).push(beforeName);
+            inDegree.set(beforeName, inDegree.get(beforeName) + 1);
+        }
+        for (const afterName of meta.after) {
+            if (!scheduleSystems.has(afterName)) {
+                throw new Error(`System "${name}" references unknown system "${afterName}" in schedule "${scheduleId}"`);
+            }
+            // "A after B" means edge B -> A (B must run first)
+            adjacency.get(afterName).push(name);
+            inDegree.set(name, inDegree.get(name) + 1);
+        }
+    }
+    // Initialize queue with systems having no dependencies
+    const queue = [];
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) {
+            insertSorted(queue, name, scheduleSystems);
+        }
+    }
+    // Process queue, maintaining sorted order by registration index
+    const result = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        result.push(current);
+        for (const dependent of adjacency.get(current)) {
+            const newDegree = inDegree.get(dependent) - 1;
+            inDegree.set(dependent, newDegree);
+            if (newDegree === 0) {
+                insertSorted(queue, dependent, scheduleSystems);
+            }
+        }
+    }
+    // Detect circular dependencies (remaining systems with non-zero in-degree)
+    if (result.length !== scheduleSystems.size) {
+        const remaining = [];
+        for (const [name, degree] of inDegree) {
+            if (degree > 0) {
+                remaining.push(name);
+            }
+        }
+        throw new Error(`Circular dependency in schedule "${scheduleId}": ${remaining.join(", ")}`);
+    }
+    world.schedules.byId.set(scheduleId, result);
+}
+/**
+ * Inserts a system name into the queue maintaining sorted order by registration index.
+ * Uses binary search for O(log n) insertion position lookup.
+ * This ensures deterministic ordering when multiple systems have no dependency constraints.
+ */
+function insertSorted(queue, name, systems) {
+    const index = systems.get(name).index;
+    let low = 0;
+    let high = queue.length;
+    // Binary search for correct insertion position
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (systems.get(queue[mid]).index < index) {
+            low = mid + 1;
+        }
+        else {
+            high = mid;
+        }
+    }
+    queue.splice(low, 0, name);
+}
+/**
+ * Executes a schedule synchronously. Throws if any system returns a Promise.
+ *
+ * @param world - World instance
+ * @param scheduleId - Schedule identifier (defaults to "runtime")
+ * @returns void
+ * @example
+ * executeSchedule(world);
+ * executeSchedule(world, "startup");
+ */
+export function executeSchedule(world, scheduleId = "runtime") {
+    const order = world.schedules.byId.get(scheduleId);
+    if (!order) {
+        throw new Error(`Schedule "${scheduleId}" not built`);
+    }
+    // Track execution context for systems that need to know their environment
+    world.execution.scheduleId = scheduleId;
+    world.execution.tick++;
+    try {
+        for (const systemId of order) {
+            world.execution.systemId = systemId;
+            const meta = world.systems.byId.get(systemId);
+            const result = meta.runner(world);
+            // Fail fast if async system detected in sync execution
+            if (result instanceof Promise) {
+                throw new Error(`System "${systemId}" returned Promise - use runScheduleAsync`);
+            }
+        }
+    }
+    finally {
+        // Always clear execution context, even on error
+        world.execution.scheduleId = null;
+        world.execution.systemId = null;
+    }
+}
+/**
+ * Executes a schedule with async support. Awaits systems that return Promises.
+ *
+ * @param world - World instance
+ * @param scheduleId - Schedule identifier (defaults to "runtime")
+ * @returns Promise that resolves when all systems complete
+ * @example
+ * await executeScheduleAsync(world);
+ * await executeScheduleAsync(world, "startup");
+ */
+export async function executeScheduleAsync(world, scheduleId = "runtime") {
+    const order = world.schedules.byId.get(scheduleId);
+    if (!order) {
+        throw new Error(`Schedule "${scheduleId}" not built`);
+    }
+    // Track execution context for systems that need to know their environment
+    world.execution.scheduleId = scheduleId;
+    world.execution.tick++;
+    try {
+        for (const systemId of order) {
+            world.execution.systemId = systemId;
+            const meta = world.systems.byId.get(systemId);
+            const result = meta.runner(world);
+            // Await async systems, sync systems pass through unchanged
+            if (result instanceof Promise) {
+                await result;
+            }
+        }
+    }
+    finally {
+        // Always clear execution context, even on error
+        world.execution.scheduleId = null;
+        world.execution.systemId = null;
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

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

package/dist/schema.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Typed array constructor type.
+ *
+ * Union of all typed array constructors that can be used for numeric storage.
+ */
+export type TypedArrayConstructor = Int8ArrayConstructor | Int16ArrayConstructor | Int32ArrayConstructor | Uint32ArrayConstructor | Float32ArrayConstructor | Float64ArrayConstructor;
+/**
+ * Type descriptor for columnar storage.
+ *
+ * Describes how component data should be stored (typed arrays for numbers,
+ * regular arrays for primitives/objects). Created via Type namespace factories.
+ *
+ * @template T - TypeScript type of stored values (inferred via phantom __type field)
+ *
+ * @example
+ * ```typescript
+ * const posX: Schema<number> = Type.f32();
+ * const name: Schema<string> = Type.string();
+ * ```
+ */
+export type Schema<T = unknown> = {
+    kind: "typed" | "primitive" | "generic";
+    arrayConstructor: TypedArrayConstructor | ArrayConstructor;
+    typeName: string;
+    __type?: T;
+};
+/**
+ * Schema factory namespace for defining component storage types.
+ *
+ * Provides constructors for typed arrays (i8, f32, etc.), primitives (bool, string),
+ * and generic objects. Use these to define component schemas.
+ *
+ * @example
+ * ```typescript
+ * const Position = { x: Type.f32(), y: Type.f32() };
+ * const Health = { hp: Type.i32() };
+ * const Name = { value: Type.string() };
+ * ```
+ */
+export declare const Type: {
+    /**
+     * 8-bit signed integer schema (Int8Array).
+     *
+     * @returns Schema for Int8Array storage
+     */
+    i8: () => Schema<number>;
+    /**
+     * 16-bit signed integer schema (Int16Array).
+     *
+     * @returns Schema for Int16Array storage
+     */
+    i16: () => Schema<number>;
+    /**
+     * 32-bit signed integer schema (Int32Array).
+     *
+     * @returns Schema for Int32Array storage
+     */
+    i32: () => Schema<number>;
+    /**
+     * 32-bit unsigned integer schema (Uint32Array).
+     *
+     * @returns Schema for Uint32Array storage
+     */
+    u32: () => Schema<number>;
+    /**
+     * 32-bit floating point schema (Float32Array).
+     *
+     * @returns Schema for Float32Array storage
+     */
+    f32: () => Schema<number>;
+    /**
+     * 64-bit floating point schema (Float64Array).
+     *
+     * @returns Schema for Float64Array storage
+     */
+    f64: () => Schema<number>;
+    /**
+     * Boolean schema (Array<boolean>).
+     *
+     * @returns Schema for Array<boolean> storage
+     */
+    bool: () => Schema<boolean>;
+    /**
+     * String schema (Array<string>).
+     *
+     * @returns Schema for Array<string> storage
+     */
+    string: () => Schema<string>;
+    /**
+     * Generic object schema (Array<T>).
+     *
+     * @template T - TypeScript type of objects stored
+     * @returns Schema for Array<T> storage
+     */
+    object: <T>() => Schema<T>;
+};
+/**
+ * Infer TypeScript type from a schema using the phantom __type field.
+ *
+ * @template S - Schema type to infer from
+ */
+export type InferSchema<S extends Schema> = S extends Schema<infer T> ? T : never;
+/**
+ * Schema record for component fields.
+ *
+ * Maps field names to their schema definitions.
+ */
+export type SchemaRecord = Record<string, Schema>;
+/**
+ * Infer TypeScript types from component schema record.
+ *
+ * Maps each schema field to its inferred type via phantom __type field.
+ */
+export type InferSchemaRecord<S extends SchemaRecord> = {
+    [K in keyof S]: S[K] extends Schema<infer T> ? T : never;
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,CAAC;AAE5B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,GAAG,OAAO,IAAI;IAChC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IACxC,gBAAgB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;IACf;;;;OAIG;cACK,MAAM,CAAC,MAAM,CAAC;IAMtB;;;;OAIG;eACM,MAAM,CAAC,MAAM,CAAC;IAMvB;;;;OAIG;eACM,MAAM,CAAC,MAAM,CAAC;IAMvB;;;;OAIG;eACM,MAAM,CAAC,MAAM,CAAC;IAMvB;;;;OAIG;eACM,MAAM,CAAC,MAAM,CAAC;IAMvB;;;;OAIG;eACM,MAAM,CAAC,MAAM,CAAC;IAMvB;;;;OAIG;gBACO,MAAM,CAAC,OAAO,CAAC;IAMzB;;;;OAIG;kBACS,MAAM,CAAC,MAAM,CAAC;IAM1B;;;;;OAKG;aACM,CAAC,OAAK,MAAM,CAAC,CAAC,CAAC;CAKzB,CAAC;AAMF;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAMlF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,YAAY,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACzD,CAAC"}

package/dist/schema.js

@@ -0,0 +1,113 @@
+// ============================================================================
+// Type Definitions
+// ============================================================================
+// ============================================================================
+// Schema Factories
+// ============================================================================
+/**
+ * Schema factory namespace for defining component storage types.
+ *
+ * Provides constructors for typed arrays (i8, f32, etc.), primitives (bool, string),
+ * and generic objects. Use these to define component schemas.
+ *
+ * @example
+ * ```typescript
+ * const Position = { x: Type.f32(), y: Type.f32() };
+ * const Health = { hp: Type.i32() };
+ * const Name = { value: Type.string() };
+ * ```
+ */
+export const Type = {
+    /**
+     * 8-bit signed integer schema (Int8Array).
+     *
+     * @returns Schema for Int8Array storage
+     */
+    i8: () => ({
+        kind: "typed",
+        arrayConstructor: Int8Array,
+        typeName: "number",
+    }),
+    /**
+     * 16-bit signed integer schema (Int16Array).
+     *
+     * @returns Schema for Int16Array storage
+     */
+    i16: () => ({
+        kind: "typed",
+        arrayConstructor: Int16Array,
+        typeName: "number",
+    }),
+    /**
+     * 32-bit signed integer schema (Int32Array).
+     *
+     * @returns Schema for Int32Array storage
+     */
+    i32: () => ({
+        kind: "typed",
+        arrayConstructor: Int32Array,
+        typeName: "number",
+    }),
+    /**
+     * 32-bit unsigned integer schema (Uint32Array).
+     *
+     * @returns Schema for Uint32Array storage
+     */
+    u32: () => ({
+        kind: "typed",
+        arrayConstructor: Uint32Array,
+        typeName: "number",
+    }),
+    /**
+     * 32-bit floating point schema (Float32Array).
+     *
+     * @returns Schema for Float32Array storage
+     */
+    f32: () => ({
+        kind: "typed",
+        arrayConstructor: Float32Array,
+        typeName: "number",
+    }),
+    /**
+     * 64-bit floating point schema (Float64Array).
+     *
+     * @returns Schema for Float64Array storage
+     */
+    f64: () => ({
+        kind: "typed",
+        arrayConstructor: Float64Array,
+        typeName: "number",
+    }),
+    /**
+     * Boolean schema (Array<boolean>).
+     *
+     * @returns Schema for Array<boolean> storage
+     */
+    bool: () => ({
+        kind: "primitive",
+        arrayConstructor: Array,
+        typeName: "boolean",
+    }),
+    /**
+     * String schema (Array<string>).
+     *
+     * @returns Schema for Array<string> storage
+     */
+    string: () => ({
+        kind: "primitive",
+        arrayConstructor: Array,
+        typeName: "string",
+    }),
+    /**
+     * Generic object schema (Array<T>).
+     *
+     * @template T - TypeScript type of objects stored
+     * @returns Schema for Array<T> storage
+     */
+    object: () => ({
+        kind: "generic",
+        arrayConstructor: Array,
+        typeName: "unknown",
+    }),
+};
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAoC/E,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB;;;;OAIG;IACH,EAAE,EAAE,GAAmB,EAAE,CAAC,CAAC;QACzB,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,SAAS;QAC3B,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;OAIG;IACH,GAAG,EAAE,GAAmB,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,UAAU;QAC5B,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;OAIG;IACH,GAAG,EAAE,GAAmB,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,UAAU;QAC5B,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;OAIG;IACH,GAAG,EAAE,GAAmB,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,WAAW;QAC7B,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;OAIG;IACH,GAAG,EAAE,GAAmB,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,YAAY;QAC9B,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;OAIG;IACH,GAAG,EAAE,GAAmB,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,OAAO;QACb,gBAAgB,EAAE,YAAY;QAC9B,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;OAIG;IACH,IAAI,EAAE,GAAoB,EAAE,CAAC,CAAC;QAC5B,IAAI,EAAE,WAAW;QACjB,gBAAgB,EAAE,KAAK;QACvB,QAAQ,EAAE,SAAS;KACpB,CAAC;IAEF;;;;OAIG;IACH,MAAM,EAAE,GAAmB,EAAE,CAAC,CAAC;QAC7B,IAAI,EAAE,WAAW;QACjB,gBAAgB,EAAE,KAAK;QACvB,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF;;;;;OAKG;IACH,MAAM,EAAE,GAAiB,EAAE,CAAC,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,gBAAgB,EAAE,KAAK;QACvB,QAAQ,EAAE,SAAS;KACpB,CAAC;CACH,CAAC"}