Typesafe API for defining Components and creating Entities

docs/Component.md

@@ -295,3 +295,22 @@ Position.properties = {
   coord: '0x0'
 };
  ```
+
+# TypedComponent
+
+There's an additional API for creating typed Components, which have typed `.properties` defined for the Component class and fields of those types on the instances. This uses the mixin pattern in TypeScript.
+
+To create a `TypedComponent`:
+
+```ts
+class Position extends ApeECS.TypedComponent({x: 0, y: 0}) {};
+```
+
+This creates a `Position` class with `typeof properties === {x: number, y: number}`.
+A `TypedComponent` can have `properties` typed as a superset of the initial properties. For example:
+
+```ts
+class Position extends ApeECS.TypedComponent<{x: number, y?: number}>({x: 0}) {};
+```
+
+These types are used in the [world.createEntityTypesafe](./World.md#createEntityTypesafe) API.

docs/World.md

@@ -210,6 +210,31 @@ const playerEntity = world.createEntity({
 
 💭 **Ape ECS** uses a very fast unique id generator for `Components` and `Entities` if you don't specify a given id upon creation. Look at the code in [src/util.js](../src/util.js).
 
+## createEntityTypesafe
+
+Create a new Entity, including its type-checked `Components`. This API is slightly reduced from `createEntity`, in that it does not take `components`, only `c`.
+The `type` of the `Component` is used to check the types of the initial arguments.
+
+```ts
+class Position extends TypedComponent<{x: number, y?: number}> {};
+class Texture extends TypedComponent<{filePath: string}> {};
+
+const playerEntity = world.createEntityTypesafe({
+  id: 'Player', // optional
+  tags: ['Character', 'Visible'], //optional
+  c: [ // optional
+    {
+      type: Position,
+      x: 15
+    },
+    {
+      type: Texture,
+      filePath: "/assets/img.png",
+    }
+  }
+});
+```
+
 ## getObject
 
 Retrieves a serializable object that includes all of the Entities and their Components in the World.

package.json

@@ -29,7 +29,6 @@
     "url": "https://github.com/fritzy/ape-ecs/issues"
   },
   "homepage": "https://github.com/fritzy/ape-ecs#readme",
-  "dependencies": {},
   "devDependencies": {
     "@hapi/eslint-plugin-hapi": "^4.3.5",
     "@types/chai": "^4.2.12",
@@ -42,7 +41,7 @@
     "markdown-link-check": "^3.8.3",
     "mocha": "^8.1.2",
     "nyc": "^15.1.0",
-    "prettier": "^2.2.0",
+    "prettier": "^2.3.2",
     "ts-node": "^9.0.0",
     "typescript": "^4.0.2",
     "webpack": "^4.43.0",

src/index.d.ts

@@ -72,14 +72,14 @@ export declare class Query {
   trackAdded: boolean;
   trackRemoved: boolean;
   from(...entities: (Entity | string)[]): Query;
-  fromReverse<T extends typeof Component>(
+  fromReverse<T extends ComponentClass>(
     entity: Entity | string,
     componentName: string | T
   ): Query;
-  fromAll(...types: (string | (new () => Component))[]): Query;
-  fromAny(...types: (string | (new () => Component))[]): Query;
-  not(...types: (string | (new () => Component))[]): Query;
-  only(...types: (string | (new () => Component))[]): Query;
+  fromAll(...types: (string | ComponentClass)[]): Query;
+  fromAny(...types: (string | ComponentClass)[]): Query;
+  not(...types: (string | ComponentClass)[]): Query;
+  only(...types: (string | ComponentClass)[]): Query;
   persist(trackAdded?: boolean, trackRemoved?: boolean): Query;
   refresh(): Query;
   execute(filter?: IQueryExecuteConfig): Set<Entity>;
@@ -90,12 +90,15 @@ export interface IComponentUpdate {
   [others: string]: any;
 }
 
-// in order to reference the class rather than the instance
-interface ComponentClass {
-  new (): Component;
-}
+type DefaultProperties = Record<string, any>;
+type Constructor<T> = new (...args: any[]) => T;
+type ComponentClass<T = DefaultProperties> = ClassType<Component<T>>;
+type ClassType<T> = { new (): T };
+export function TypedComponent<TProperties extends DefaultProperties>(
+  properties: TProperties
+): ClassType<Component<TProperties>> & Constructor<Component & TProperties>;
 
-export declare class Component {
+export declare class Component<TProperties extends DefaultProperties = {}> {
   preInit(initial: any): any;
   init(initial: any): void;
   get type(): string;
@@ -108,6 +111,7 @@ export declare class Component {
   entity: Entity;
   id: string;
   update(values?: IComponentUpdate): void;
+  properties: TProperties;
   [name: string]: any;
   static properties: Object;
   static serialize: Boolean;
@@ -188,6 +192,22 @@ export interface IEntityObject {
 // export interface IWorldSubscriptions {
 //   [name: string]: System;
 // }
+type TypedComponentConfig<T = any> = T extends Component<infer TProperties>
+  ? {
+      type: ClassType<T>;
+      key?: string;
+    } & TProperties
+  : never;
+
+export type TypedComponentConfigVal<T = any> = T extends Component<
+  infer TProperties
+>
+  ? {
+      type: ClassType<T>;
+      id?: string;
+      entity?: string;
+    } & TProperties
+  : never;
 
 export declare class Entity {
   types: IEntityByType;
@@ -208,6 +228,9 @@ export declare class Entity {
   addComponent(
     properties: IComponentConfig | IComponentObject
   ): Component | undefined;
+  addTypedComponent<T extends Component>(
+    properties: TypedComponentConfig<T>
+  ): Component | undefined;
   removeComponent(component: Component | string): boolean;
   getObject(componentIds?: boolean): IEntityObject;
   destroy(): void;
@@ -228,6 +251,18 @@ export interface IEntityConfig {
   c?: IComponentConfigValObject;
 }
 
+export type TypedEntityConfig<TComponents extends Component[] = []> = {
+  id?: string;
+  tags?: string[];
+  c?: {
+    [TComponent in keyof TComponents]: TComponents[TComponent] extends Component<
+      infer TProperties
+    >
+      ? TypedComponentConfigVal<TComponents[TComponent]>
+      : never;
+  };
+};
+
 export interface IPoolStat {
   active: number;
   pooled: number;
@@ -257,7 +292,7 @@ export declare class World {
   registerTags(...tags: string[]): void;
 
   // Both options allow the passing of a class that extends Component
-  registerComponent<T extends typeof Component>(
+  registerComponent<T extends ComponentClass | string>(
     klass: T,
     spinup?: number
   ): void;
@@ -266,6 +301,9 @@ export declare class World {
   logStats(freq: number, callback?: Function): void;
 
   createEntity(definition: IEntityConfig | IEntityObject): Entity;
+  createEntityTypesafe<T extends Array<Component>>(
+    definition: TypedEntityConfig<T>
+  ): Entity;
   getObject(): IEntityObject[];
   createEntities(definition: IEntityConfig[] | IEntityObject[]): void;
   copyTypes(world: World, types: string[]): void;

src/index.js

@@ -1,9 +1,18 @@
 const { EntityRef, EntitySet, EntityObject } = require('./entityrefs');
+const Component = require('./component');
+
+function TypedComponent(props) {
+  const typedClass = class TypedComponent extends Component {};
+  typedClass.properties = { ...props };
+  return typedClass;
+}
+
 module.exports = {
   World: require('./world'),
   System: require('./system'),
-  Component: require('./component'),
   Entity: require('./entity'),
+  Component,
+  TypedComponent,
   EntityRef,
   EntitySet,
   EntityObject

src/world.js

@@ -255,6 +255,16 @@ module.exports = class World {
     this.componentPool.set(name, new ComponentPool(this, name, spinup));
   }
 
+  createEntityTypesafe(definition) {
+    definition = {
+      ...definition,
+      c: definition.c.map((c) => {
+        return { ...c, type: c.type.name };
+      })
+    };
+    return this.createEntity(definition);
+  }
+
   createEntity(definition) {
     return this.entityPool.get(definition);
   }