typed-factorio 0.20.0-beta.1 → 0.20.0

package/Changelog.md

@@ -1,8 +1,8 @@
 # v0.20.0
 
 - Updated to factorio version 1.1.56
-- Added custom-index-template.d.ts. You can use this if you would like to make a "custom" modification of the type definitions.
-- **This is an opt-in**: Some numeric types which represent indices/number,e.g. player_index, entity_number, are now branded numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. See the README for more info.
+- This is an **opt-in** feature: Some numeric types which represent indices/number,e.g. player_index, entity_number, are now branded numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. See the README for more info.
+- Added custom-index-template.d.ts to assist trying out custom changes to types in a project.
 
 # v0.19.0
 

package/README.md

@@ -30,10 +30,7 @@ yarn add typed-factorio
 
 This will add the types for the runtime stage to your entire project.
 
-Notes:
-> When types are updated, or released for a new factorio version, you will need update your package version to get the types.
-> 
-> There is an opt-in feature for stricter index types, see [Strict index types](#Strict index types) for more details.
+Note: When types are updated, or released for a new factorio version, you will need update your package version to get the types.
 
 ### Settings and data stage
 
@@ -114,7 +111,6 @@ Table-or-array types will appear in the Table form when known to be in a read po
 
 For some concepts, there is also a special form for when the concept is used in a "read" position, where all table-or-array types are in Table form. These types are suffixed with `Read`, e.g. `ScriptPositionRead`.
 
-
 ### Types with subclasses
 
 Some classes have attributes that are documented to only work on particular subclasses. For these classes, e.g. `LuaEntity`, there are specific types that you can _optionally_ use:
@@ -134,11 +130,9 @@ This is done both to provide more accurate types, and for possible integration w
 
 ### Strict index types
 
-This feature is recommended, but currently is a **opt-in**. To opt in, use `typed-factorio/runtime/strict-index-types` instead of `typed-factorio/runtime` in your `tsconfig.json`.
-
-Some `uint` types which represent indices, e.g. player_index, entity_number, are now "branded" numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. These are assignable to `number`, but `number` is not assignable to them.
-These are indices that do not index into an array-like structure, and otherwise should usually not have arithmetic done to them. So, using a separate type helps ensure correctness.
-You can still use these types as keys in an index signature, e.g. `{ [index: PlayerIndex]: "foo" }`.
-You can cast "plain" numbers to these types, e.g. `2 as PlayerIndex`, only do this with some care.
+This is a recommended **opt-in** feature. To opt in, add `"typed-factorio/strict-index-types"` to `compilerOptions > types` in your tsconfig.json (in addition to `"typed-factorio/runtime"`).
 
-- `player_index` and `surface_index` still allow the numeric constant 1 as a valid index, representing the first player or the default surface, respectively. This is allowed as this is a common enough use case.
+Some `uint` types which represent indices, e.g. player_index, entity_number, can be "branded" numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. These are assignable to `number`, but a plain `number` is not directly assignable to them. This helps ensure correctness.
+These are indices that do not index into an array-like structure, and otherwise should usually not have arithmetic done to them.
+You can use these types as keys in an index signature, e.g. `{ [index: PlayerIndex]: "foo" }`.
+You can cast "plain" numbers to these types, e.g. `1 as PlayerIndex`, do this with caution.

package/custom-index-template.d.ts

@@ -2,8 +2,6 @@
 // For example, if you want to modify a file, copy the file you want to modify to your project and make the changes. Then, copy this template file into your project and remove the line corresponding to modified file.
 // If you think your modification will be useful to others, please consider making a change suggestion by creating an issue on GitHub.
 
-// Replace "index-types.d.ts" with "index-types-strict.d.ts" below if you want strict index types.
-
 /// <reference types="lua-types/5.2" />
 
 // generated

package/generated/classes.d.ts

@@ -2000,7 +2000,12 @@ interface LuaCustomTableMembers {
  */
 type LuaCustomTable<K extends string | number, V> = LuaCustomTableMembers &
   CustomTableIndexer<K, V> &
-  LuaPairsIterable<[number] extends [K] ? number : K, V>
+  LuaPairsIterable<
+    // this convoluted expression gives a number type if K includes a number, even if it includes a string, and K otherwise.
+    // it also preserves number branding
+    [number] extends [K extends number & IndexBrand<infer A> ? number : K] ? (K extends string ? never : K) : K,
+    V
+  >
 
 /**
  * Prototype of a damage.

package/generated/index-types.d.ts

@@ -3,36 +3,47 @@
 /** @noSelfInFile */
 
 /**
- * See {@link LuaPlayer#index LuaPlayer.index}..
+ * See {@link LuaPlayer#index LuaPlayer.index}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as PlayerIndex`.
  */
-type PlayerIndex = uint
+type PlayerIndex = uint & IndexBrand<"_playerIndexBrand">
 
 /**
- * See {@link LuaSurface#index LuaSurface.index}..
+ * See {@link LuaSurface#index LuaSurface.index}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as SurfaceIndex`.
  */
-type SurfaceIndex = uint
+type SurfaceIndex = uint & IndexBrand<"_surfaceIndexBrand">
 
 /**
- * See {@link LuaEntity#unit_number LuaEntity.unit_number}..
+ * See {@link LuaEntity#unit_number LuaEntity.unit_number}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as UnitNumber`.
  */
-type UnitNumber = uint
+type UnitNumber = uint & IndexBrand<"_unitNumberBrand">
 
 /**
- * See {@link LuaGuiElement#index LuaGuiElement.index}..
+ * See {@link LuaGuiElement#index LuaGuiElement.index}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as GuiElementIndex`.
  */
-type GuiElementIndex = uint
+type GuiElementIndex = uint & IndexBrand<"_guiElementIndexBrand">
 
 /**
- * See {@link LuaBootstrap#register_on_entity_destroyed LuaBootstrap.register_on_entity_destroyed}..
+ * See {@link LuaBootstrap#register_on_entity_destroyed LuaBootstrap.register_on_entity_destroyed}.
  *
- * This can be a "branded" type for stricter types; see docs on how to opt-in to this.
+ * If using strict-index-types, and you need to use a plain number for this type, you can use a cast, e.g. `1 as RegistrationNumber`.
  */
-type RegistrationNumber = uint64
+type RegistrationNumber = uint64 & IndexBrand<"_registrationNumberBrand">
+
+interface __OptInFeatures {}
+
+/**
+ * Equals a branded type when __OptInFeatures contains strictIndexTypes, otherwise equals `unknown`.
+ */
+type IndexBrand<B extends string> = "strictIndexTypes" extends keyof __OptInFeatures
+  ? {
+      [K in B]: any
+    }
+  : unknown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typed-factorio",
-  "version": "0.20.0-beta.1",
+  "version": "0.20.0",
   "description": "Featureful typescript definitions for the the Factorio modding lua api.",
   "keywords": [
     "factorio",

package/runtime/pairs.d.ts

@@ -1,15 +1,10 @@
 /** @noSelfInFile */
 ///<reference types="lua-types/5.2" />
 
-/**
- * Iterating with `pairs` will only iterate the array part of a {@link LuaCustomTable}.
- *
- * **Note**: you can also iterate on a LuaCustomTable directly without using `pairs`, e.g. `for(const [k, v] of table)`.
- */
-declare function pairs<V>(table: LuaCustomTable<number | string, V>): LuaIterable<LuaMultiReturn<[number, V]>>
-
 /** **Note**: you can also iterate on a LuaCustomTable directly without using `pairs`, e.g. `for(const [k, v] of table)`. */
-declare function pairs<K extends number | string, V>(table: LuaCustomTable<K, V>): LuaIterable<LuaMultiReturn<[K, V]>>
+declare function pairs<T extends LuaCustomTable<any, any>>(
+  table: T
+): LuaIterable<LuaMultiReturn<T extends Iterable<infer E> ? E : never>>
 
 /** @deprecated {@link LuaCustomTable} cannot be iterated with `ipairs`; Use {@link pairs} instead. */
 declare function ipairs(table: LuaCustomTable<any, any>): never

package/strict-index-types.d.ts

@@ -0,0 +1,3 @@
+interface __OptInFeatures {
+  strictIndexTypes: true
+}

package/generated/index-types-strict.d.ts

@@ -1,52 +0,0 @@
-// This is an auto-generated file. Do not edit directly!
-
-/** @noSelfInFile */
-
-/**
- * See {@link LuaPlayer#index LuaPlayer.index}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as PlayerIndex`.
- */
-type PlayerIndex =
-  | (uint & {
-      _playerIndexBrand: void
-    })
-  | 1
-
-/**
- * See {@link LuaSurface#index LuaSurface.index}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as SurfaceIndex`.
- */
-type SurfaceIndex =
-  | (uint & {
-      _surfaceIndexBrand: void
-    })
-  | 1
-
-/**
- * See {@link LuaEntity#unit_number LuaEntity.unit_number}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as UnitNumber`.
- */
-type UnitNumber = uint & {
-  _unitNumberBrand: void
-}
-
-/**
- * See {@link LuaGuiElement#index LuaGuiElement.index}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as GuiElementIndex`.
- */
-type GuiElementIndex = uint & {
-  _guiElementIndexBrand: void
-}
-
-/**
- * See {@link LuaBootstrap#register_on_entity_destroyed LuaBootstrap.register_on_entity_destroyed}.
- *
- * If you need to use a number/numeric literal for this type, you can use a cast, e.g. `2 as RegistrationNumber`.
- */
-type RegistrationNumber = uint64 & {
-  _registrationNumberBrand: void
-}

package/runtime/strict-index-types.d.ts

@@ -1,18 +0,0 @@
-/// <reference types="lua-types/5.2" />
-
-// generated
-/// <reference path="../generated/builtin-types.d.ts" />
-/// <reference path="../generated/global-objects.d.ts" />
-/// <reference path="../generated/defines.d.ts" />
-/// <reference path="../generated/events.d.ts" />
-/// <reference path="../generated/classes.d.ts" />
-/// <reference path="../generated/concepts.d.ts" />
-/// <reference path="../generated/index-types-strict.d.ts" />
-
-// other runtime
-/// <reference path="librariesAndFunctions.d.ts" />
-/// <reference path="pairs.d.ts" />
-
-// lualib
-/// <reference path="util.d.ts" />
-/// <reference path="mod-gui.d.ts" />