From b974dd9e524821dce96385d5ca2f47faf9fa2d66 Mon Sep 17 00:00:00 2001 From: maeriil Date: Mon, 1 Dec 2025 13:55:07 -0500 Subject: [PATCH] ts type update --- src/jecs.d.ts | 474 +++++++++++++++++++++++++++----------------------- 1 file changed, 253 insertions(+), 221 deletions(-) diff --git a/src/jecs.d.ts b/src/jecs.d.ts index d2cb20d..dc59016 100755 --- a/src/jecs.d.ts +++ b/src/jecs.d.ts @@ -3,12 +3,12 @@ * The generic type T defines the data type when this entity is used as a component */ export type Entity = number & { - readonly __nominal_Entity: unique symbol; - readonly __type_TData: TData; + readonly __nominal_Entity: unique symbol; + readonly __type_TData: TData; }; type TagDiscriminator = { - readonly __nominal_Tag: unique symbol; + readonly __nominal_Tag: unique symbol; }; /** @@ -22,23 +22,27 @@ export type Tag = Entity; * - `obj` is the type of the "object" entity. */ export type Pair

= number & { - readonly __nominal_Pair: unique symbol; - readonly __pred: P; - readonly __obj: O; + readonly __nominal_Pair: unique symbol; + readonly __pred: P; + readonly __obj: O; }; /** * An `Id` can be either a single Entity or a Pair of Entities. * By providing `TData`, you can specifically require an Id that yields that type. */ -export type Id = Entity | Pair | Pair; +export type Id = + | Entity + | Pair + | Pair; -export type InferComponent = E extends Entity - ? D - : E extends Pair - ? P extends TagDiscriminator - ? O - : P - : never; +export type InferComponent = + E extends Entity + ? D + : E extends Pair + ? P extends TagDiscriminator + ? O + : P + : never; type FlattenTuple = T extends [infer U] ? U : LuaTuple; type Nullable = { [K in keyof T]: T[K] | undefined }; @@ -48,232 +52,260 @@ type ArchetypeId = number; export type Column = T[]; export type Archetype = { - id: number; - types: Entity[]; - type: string; - entities: Entity[]; - columns: Column[]; - columns_map: { [K in T[number]]: Column> }; + id: number; + types: Entity[]; + type: string; + entities: Entity[]; + columns: Column[]; + columns_map: { [K in T[number]]: Column> }; }; type IterFn = IterableFunction]>>; type Iter = IterFn & { - /** - * This isn't callable - * @hidden - * @deprecated - */ - (): never + /** + * This isn't callable + * @hidden + * @deprecated + */ + (): never; }; export type CachedQuery = { - /** - * Returns an iterator that produces a tuple of [Entity, ...queriedComponents]. - */ - iter(): IterFn; + /** + * Returns an iterator that produces a tuple of [Entity, ...queriedComponents]. + */ + iter(): IterFn; - /** - * Returns the matched archetypes of the query - * @returns An array of archetypes of the query - */ - archetypes(): Archetype[]; + /** + * Returns the matched archetypes of the query + * @returns An array of archetypes of the query + */ + archetypes(): Archetype[]; + + has(entity: Entity): boolean; + + ids: Id[]; + + filter_with?: Id[]; + + filter_without?: Id[]; + + archetypes_map: Map; } & Iter; export type Query = { - /** - * Returns an iterator that produces a tuple of [Entity, ...queriedComponents]. - */ - iter(): IterFn; + /** + * Returns an iterator that produces a tuple of [Entity, ...queriedComponents]. + */ + iter(): IterFn; - /** - * Creates and returns a cached version of this query for efficient reuse. - * Call refinement methods (with/without) on the query before caching. - * @returns A cached query - */ - cached(): CachedQuery; + /** + * Creates and returns a cached version of this query for efficient reuse. + * Call refinement methods (with/without) on the query before caching. + * @returns A cached query + */ + cached(): CachedQuery; - /** - * Modifies the query to include specified components. - * @param components The components to include. - * @returns A new Query with the inclusion applied. - */ - with(...components: Id[]): Query; + /** + * Modifies the query to include specified components. + * @param components The components to include. + * @returns A new Query with the inclusion applied. + */ + with(...components: Id[]): Query; - /** - * Modifies the Query to exclude specified components. - * @param components The components to exclude. - * @returns A new Query with the exclusion applied. - */ - without(...components: Id[]): Query; + /** + * Modifies the Query to exclude specified components. + * @param components The components to exclude. + * @returns A new Query with the exclusion applied. + */ + without(...components: Id[]): Query; - /** - * Returns the matched archetypes of the query - * @returns An array of archetypes of the query - */ - archetypes(): Archetype[]; + /** + * Returns the matched archetypes of the query + * @returns An array of archetypes of the query + */ + archetypes(): Archetype[]; + + has(entity: Entity): boolean; + + ids: Id[]; + + filter_with?: Id[]; + + filter_without?: Id[]; } & Iter; export class World { - /** - * Creates a new World. - */ - private constructor(); + /** + * Creates a new World. + */ + private constructor(); - /** - * Enforces a check for entities to be created within a desired range. - * @param range_begin The starting point - * @param range_end The end point (optional) - */ - range(range_begin: number, range_end?: number): void; + /** + * Enforces a check for entities to be created within a desired range. + * @param range_begin The starting point + * @param range_end The end point (optional) + */ + range(range_begin: number, range_end?: number): void; - /** - * Creates a new entity. - * @returns An entity (Tag) with no data. - */ - entity(): Tag; - entity(id: T): T; + /** + * Creates a new entity. + * @returns An entity (Tag) with no data. + */ + entity(): Tag; + entity(id: T): T; - /** - * Creates a new entity in the first 256 IDs, typically used for static - * components that need fast access. - * @returns A typed Entity with `TData`. - */ - component(): Entity; + /** + * Creates a new entity in the first 256 IDs, typically used for static + * components that need fast access. + * @returns A typed Entity with `TData`. + */ + component(): Entity; - /** - * Gets the target of a relationship. For example, if we say - * `world.target(entity, ChildOf)`, this returns the parent entity. - * @param entity The entity using a relationship pair. - * @param relation The "relationship" component/tag (e.g., ChildOf). - * @param index If multiple targets exist, specify an index. Defaults to 0. - */ - target(entity: Entity, relation: Entity, index?: number): Entity | undefined; + /** + * Gets the target of a relationship. For example, if we say + * `world.target(entity, ChildOf)`, this returns the parent entity. + * @param entity The entity using a relationship pair. + * @param relation The "relationship" component/tag (e.g., ChildOf). + * @param index If multiple targets exist, specify an index. Defaults to 0. + */ + target(entity: Entity, relation: Entity, index?: number): Entity | undefined; - /** - * Deletes an entity (and its components/relationships) from the world entirely. - * @param entity The entity to delete. - */ - delete(entity: Entity): void; + /** + * Deletes an entity (and its components/relationships) from the world entirely. + * @param entity The entity to delete. + */ + delete(entity: Entity): void; - /** - * Adds a component (with no value) to the entity. - * @param entity The target entity. - * @param component The component (or tag) to add. - */ - add(entity: Entity, component: TagDiscriminator extends InferComponent ? C : Id): void; + /** + * Adds a component (with no value) to the entity. + * @param entity The target entity. + * @param component The component (or tag) to add. + */ + add( + entity: Entity, + component: TagDiscriminator extends InferComponent ? C : Id, + ): void; - /** - * Installs a hook on the given component. - * @param component The target component. - * @param hook The hook to install. - * @param value The hook callback. - */ - set(component: Entity, hook: StatefulHook, value: (e: Entity, id: Id, data: T) => void): void; - set(component: Entity, hook: StatelessHook, value: (e: Entity, id: Id) => void): void; - /** - * Assigns a value to a component on the given entity. - * @param entity The target entity. - * @param component The component definition (could be a Pair or Entity). - * @param value The value to store with that component. - */ - set>(entity: Entity, component: E, value: InferComponent): void; + /** + * Installs a hook on the given component. + * @param component The target component. + * @param hook The hook to install. + * @param value The hook callback. + */ + set( + component: Entity, + hook: StatefulHook, + value: (e: Entity, id: Id, data: T) => void, + ): void; + set(component: Entity, hook: StatelessHook, value: (e: Entity, id: Id) => void): void; + /** + * Assigns a value to a component on the given entity. + * @param entity The target entity. + * @param component The component definition (could be a Pair or Entity). + * @param value The value to store with that component. + */ + set>(entity: Entity, component: E, value: InferComponent): void; - /** - * Cleans up the world by removing empty archetypes and rebuilding the archetype collections. - * This helps maintain memory efficiency by removing unused archetype definitions. - */ - cleanup(): void; + /** + * Cleans up the world by removing empty archetypes and rebuilding the archetype collections. + * This helps maintain memory efficiency by removing unused archetype definitions. + */ + cleanup(): void; - /** - * Removes all instances of specified component - */ - // purge(component: Id): void + /** + * Removes all instances of specified component + */ + // purge(component: Id): void - /** - * Clears all components and relationships from the given entity, but - * does not delete the entity from the world. - * @param entity The entity to clear. - */ - clear(entity: Entity): void; + /** + * Clears all components and relationships from the given entity, but + * does not delete the entity from the world. + * @param entity The entity to clear. + */ + clear(entity: Entity): void; - /** - * Removes a component from the given entity. - * @param entity The target entity. - * @param component The component to remove. - */ - remove(entity: Entity, component: Id): void; + /** + * Removes a component from the given entity. + * @param entity The target entity. + * @param component The component to remove. + */ + remove(entity: Entity, component: Id): void; - /** - * Retrieves the values of up to 4 components on a given entity. Missing - * components will return `undefined`. - * @param entity The entity to query. - * @param components Up to 4 components/tags to retrieve. - * @returns A tuple of data (or a single value), each possibly undefined. - */ - get( - entity: Entity, - ...components: T - ): FlattenTuple>>; + /** + * Retrieves the values of up to 4 components on a given entity. Missing + * components will return `undefined`. + * @param entity The entity to query. + * @param components Up to 4 components/tags to retrieve. + * @returns A tuple of data (or a single value), each possibly undefined. + */ + get( + entity: Entity, + ...components: T + ): FlattenTuple>>; - /** - * Returns `true` if the given entity has all of the specified components. - * A maximum of 4 components can be checked at once. - * @param entity The entity to check. - * @param components Upto 4 components to check for. - */ - has(entity: Entity, ...components: Id[]): boolean; + /** + * Returns `true` if the given entity has all of the specified components. + * A maximum of 4 components can be checked at once. + * @param entity The entity to check. + * @param components Upto 4 components to check for. + */ + has(entity: Entity, ...components: Id[]): boolean; - /** - * Gets the parent (the target of a `ChildOf` relationship) for an entity, - * if such a relationship exists. - * @param entity The entity whose parent is queried. - */ - parent(entity: Entity): Entity | undefined; + /** + * Gets the parent (the target of a `ChildOf` relationship) for an entity, + * if such a relationship exists. + * @param entity The entity whose parent is queried. + */ + parent(entity: Entity): Entity | undefined; - /** - * Checks if an entity exists in the world. - * @param entity The entity to verify. - */ - contains(entity: Entity): boolean; + /** + * Checks if an entity exists in the world. + * @param entity The entity to verify. + */ + contains(entity: Entity): boolean; - /** - * Checks if an entity exists in the world. - * @param entity The entity to verify. - */ - contains(entity: number): entity is Entity; + /** + * Checks if an entity exists in the world. + * @param entity The entity to verify. + */ + contains(entity: number): entity is Entity; - /** - * Checks if an entity with the given ID is currently alive, ignoring its generation. - * @param entity The entity to verify. - * @returns boolean true if any entity with the given ID exists (ignoring generation), false otherwise - */ - exists(entity: Entity): boolean; + /** + * Checks if an entity with the given ID is currently alive, ignoring its generation. + * @param entity The entity to verify. + * @returns boolean true if any entity with the given ID exists (ignoring generation), false otherwise + */ + exists(entity: Entity): boolean; - /** - * Returns an iterator that yields all entities that have the specified component or relationship. - * @param id The component or relationship ID to search for - * @returns An iterator function that yields entities - */ - each(id: Id): IterableFunction; + /** + * Returns an iterator that yields all entities that have the specified component or relationship. + * @param id The component or relationship ID to search for + * @returns An iterator function that yields entities + */ + each(id: Id): IterableFunction; - /** - * Returns an iterator that yields all child entities of the specified parent entity. - * Uses the ChildOf relationship internally. - * @param parent The parent entity to get children for - * @returns An iterator function that yields child entities - */ - children(parent: Entity): IterableFunction; + /** + * Returns an iterator that yields all child entities of the specified parent entity. + * Uses the ChildOf relationship internally. + * @param parent The parent entity to get children for + * @returns An iterator function that yields child entities + */ + children(parent: Entity): IterableFunction; - /** - * Searches the world for entities that match specified components. - * @param components The list of components to query. - * @returns A Query object to iterate over results. - */ - query(...components: T): Query; + /** + * Searches the world for entities that match specified components. + * @param components The list of components to query. + * @returns A Query object to iterate over results. + */ + query(...components: T): Query; - added(component: Entity, listener: (e: Entity, id: Id, value: T) => void): () => void; - changed(component: Entity, listener: (e: Entity, id: Id, value: T) => void): () => void; - removed(component: Entity, listener: (e: Entity, id: Id) => void): () => void; + added(component: Entity, listener: (e: Entity, id: Id, value: T) => void): () => void; + changed( + component: Entity, + listener: (e: Entity, id: Id, value: T) => void, + ): () => void; + removed(component: Entity, listener: (e: Entity, id: Id) => void): () => void; } export function world(): World; @@ -320,10 +352,10 @@ export function ECS_PAIR_FIRST(pair: Pair): number; export function ECS_PAIR_SECOND(pair: Pair): number; type StatefulHook = Entity<(e: Entity, id: Id, data: T) => void> & { - readonly __nominal_StatefulHook: unique symbol; + readonly __nominal_StatefulHook: unique symbol; }; type StatelessHook = Entity<(e: Entity, id: Id) => void> & { - readonly __nominal_StatelessHook: unique symbol; + readonly __nominal_StatelessHook: unique symbol; }; export declare const OnAdd: StatefulHook; @@ -342,34 +374,34 @@ export declare const Exclusive: Tag; export declare const Rest: Entity; export type ComponentRecord = { - records: Map; - counts: Map; - size: number; + records: Map; + counts: Map; + size: number; }; export function component_record(world: World, id: Id): ComponentRecord; -type TagToUndefined = T extends TagDiscriminator ? undefined : T -type TrimOptional = T extends [...infer L, infer R] - ? unknown extends R - ? L | T | TrimOptional - : R extends undefined - ? L | T | TrimOptional - : T - : T +type TagToUndefined = T extends TagDiscriminator ? undefined : T; +type TrimOptional = T extends [...infer L, infer R] + ? unknown extends R + ? L | T | TrimOptional + : R extends undefined + ? L | T | TrimOptional + : T + : T; export function bulk_insert( - world: World, - entity: Entity, - ids: C, - values: TrimOptional<{ [K in keyof C]: TagToUndefined> }>, + world: World, + entity: Entity, + ids: C, + values: TrimOptional<{ [K in keyof C]: TagToUndefined> }>, ): void; export function bulk_remove(world: World, entity: Entity, ids: Id[]): void; export type EntityRecord = { - archetype: Archetype, - row: number, - dense: number, + archetype: Archetype; + row: number; + dense: number; }; export function record(world: World, entity: Entity): EntityRecord;