Add Typescript Types (#51)

* Add package.json, tsconfig.json, and change gitignore

* Typescript Types

* Make World a single class, refactor of all query types

* Fix InferComponents types due to typo / misunderstanding

* Bump dependencies

* Fix get type to include undefined and add documentation

* Remove non-user facing types

* Rename PossiblyUndefinedPack -> Nullable

* Some changes to how EntityIndex is handled

* Consistent formatting

* Remove EntityIndex related type definitions

* Match API

* Doc comments

.gitignore

@@ -46,6 +46,10 @@ Packages
 wally.lock
 WallyPatches
 
+# Typescript
+/node_modules
+/include
+
 # Misc
 roblox.toml
 sourcemap.json

lib/index.d.ts

@@ -0,0 +1,153 @@
+type Query<T extends unknown[]> = {
+  without: (...components: Entity[]) => Query<T>;
+} & IterableFunction<LuaTuple<[Entity, ...T]>>;
+
+// Utility Types
+export type Entity<T = unknown> = number & { __nominal_type_dont_use: T };
+export type EntityType<T> = T extends Entity<infer A> ? A : never;
+export type InferComponents<A extends Entity[]> = {
+  [K in keyof A]: EntityType<A[K]>;
+};
+type Nullable<T extends unknown[]> = {
+  [K in keyof T]: T[K] | undefined;
+};
+
+export class World {
+  /**
+   * Creates a new World
+   */
+  constructor();
+
+  /**
+   * Creates a new entity
+   * @returns Entity
+   */
+  entity(): Entity;
+
+  /**
+   * Creates a new entity located in the first 256 ids.
+   * These should be used for static components for fast access.
+   * @returns Entity<T>
+   */
+  component<T = unknown>(): Entity<T>;
+
+  /**
+   * Gets the target of a relationship. For example, when a user calls
+   * `world.target(id, ChildOf(parent))`, you will obtain the parent entity.
+   * @param id Entity
+   * @param relation The Relationship
+   * @returns The Parent Entity if it exists
+   */
+  target(id: Entity, relation: Entity): Entity | undefined;
+
+  /**
+   * Deletes an entity and all its related components and relationships.
+   * @param id Entity to be destroyed
+   */
+  delete(id: Entity): void;
+
+  /**
+   * Adds a component to the entity with no value
+   * @param id Target Entity
+   * @param component Component
+   */
+  add<T>(id: Entity, component: Entity<T>): void;
+
+  /**
+   * Assigns a value to a component on the given entity
+   * @param id Target Entity
+   * @param component Target Component
+   * @param data Component Data
+   */
+  set<T>(id: Entity, component: Entity<T>, data: T): void;
+
+  /**
+   * Removes a component from the given entity
+   * @param id Target Entity
+   * @param component Target Component
+   */
+  remove(id: Entity, component: Entity): void;
+
+  // Manually typed out get since there is a hard limit.
+
+  /**
+   * Retrieves the value of one component. This value may be undefined.
+   * @param id Target Entity
+   * @param component Target Component
+   * @returns Data associated with the component if it exists
+   */
+  get<A>(id: number, component: Entity<A>): A | undefined;
+
+  /**
+   * Retrieves the value of two components. This value may be undefined.
+   * @param id Target Entity
+   * @param component Target Component 1
+   * @param component2 Target Component 2
+   * @returns Data associated with the components if it exists
+   */
+  get<A, B>(
+    id: number,
+    component: Entity<A>,
+    component2: Entity<B>
+  ): LuaTuple<Nullable<[A, B]>>;
+
+  /**
+   * Retrieves the value of three components. This value may be undefined.
+   * @param id Target Entity
+   * @param component Target Component 1
+   * @param component2 Target Component 2
+   * @param component3 Target Component 3
+   * @returns Data associated with the components if it exists
+   */
+  get<A, B, C>(
+    id: number,
+    component: Entity<A>,
+    component2: Entity<B>,
+    component3: Entity<C>
+  ): LuaTuple<Nullable<[A, B, C]>>;
+
+  /**
+   * Retrieves the value of four components. This value may be undefined.
+   * @param id Target Entity
+   * @param component Target Component 1
+   * @param component2 Target Component 2
+   * @param component3 Target Component 3
+   * @param component4 Target Component 4
+   * @returns Data associated with the components if it exists
+   */
+  get<A, B, C, D>(
+    id: number,
+    component: Entity<A>,
+    component2: Entity<B>,
+    component3: Entity<C>,
+    component4: Entity<D>
+  ): LuaTuple<Nullable<[A, B, C, D]>>;
+
+  /**
+   * Searches the world for entities that match a given query
+   * @param components Queried Components
+   * @returns Iterable function
+   */
+  query<T extends Entity[]>(...components: T): Query<InferComponents<T>>;
+}
+
+/**
+ * Creates a composite key.
+ * @param pred The first entity
+ * @param obj The second entity
+ * @returns The composite key
+ */
+export const pair: (pred: Entity, obj: Entity) => Entity;
+
+/**
+ * Checks if the entity is a composite key
+ * @param e The entity to check
+ * @returns If the entity is a pair
+ */
+export const IS_PAIR: (e: Entity) => boolean;
+
+export const OnAdd: Entity;
+export const OnRemove: Entity;
+export const OnSet: Entity;
+export const Wildcard: Entity;
+export const Rest: Entity;

package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rbxts/jecs",
+  "version": "0.1.0",
+  "description": "Stupidly fast Entity Component System",
+  "main": "lib/init.lua",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ukendio/jecs.git"
+  },
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "Ukendio",
+  "contributors": [
+    "Ukendio",
+    "EncodedVenom"
+  ],
+  "homepage": "https://github.com/ukendio/jecs",
+  "license": "MIT",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^2.3.0-types.1",
+    "@rbxts/types": "^1.0.781",
+    "@typescript-eslint/eslint-plugin": "^5.8.0",
+    "@typescript-eslint/parser": "^5.8.0",
+    "eslint": "^8.5.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "eslint-plugin-roblox-ts": "^0.0.32",
+    "prettier": "^2.5.1",
+    "roblox-ts": "^2.3.0",
+    "typescript": "^5.4.2"
+  }
+}

tsconfig.json

@@ -0,0 +1,26 @@
+{
+    "compilerOptions": {
+      // required
+      "allowSyntheticDefaultImports": true,
+      "downlevelIteration": true,
+      "jsx": "react",
+      "jsxFactory": "Roact.createElement",
+      "jsxFragmentFactory": "Roact.Fragment",
+      "module": "commonjs",
+      "moduleResolution": "Node",
+      "noLib": true,
+      "resolveJsonModule": true,
+      "strict": true,
+      "target": "ESNext",
+      "typeRoots": ["node_modules/@rbxts"],
+  
+      // configurable
+      "rootDir": "lib",
+      "outDir": "out",
+      "baseUrl": "lib",
+      "incremental": true,
+      "tsBuildInfoFile": "out/tsconfig.tsbuildinfo",
+  
+      "moduleDetection": "force"
+    }
+  }