typed-factorio 0.19.0 → 0.20.0

package/Changelog.md

@@ -1,3 +1,9 @@
+# v0.20.0
+
+- Updated to factorio version 1.1.56
+- 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
 
 - Updated to factorio version 1.1.53
@@ -33,8 +39,8 @@
 # v0.15.0
 
 - Table or array concepts are now declared in table form wherever it is an "read" position.
-    - This works with setter overloading for applicable properties: `player.color.x; player.color = [1, 1, 1]` is now valid!
-    - This also applies to concepts/complex types which contain table_or_array properties.
+  - This works with setter overloading for applicable properties: `player.color.x; player.color = [1, 1, 1]` is now valid!
+  - This also applies to concepts/complex types which contain table_or_array properties.
 - Some concepts now also have a special form where it is known to be in a "read" position, where all table_or_array concepts are declared in table form. These concepts are suffixed with "Read", e.g. `ScriptAreaRead`.
 - Arrays which are known to be in a "write" only form (e.g. method parameters) now are marked readonly. This means you can now pass readonly arrays to these methods.
 - `MapPosition` is now a table or array concept.
@@ -50,17 +56,17 @@
 - LuaStyle size, margin/padding setters now have more specific array types. These array types are `SizeArray` and `StyleValuesArray` for size and margin/padding, respectively.
 - `@noSelf` annotation is now only present when necessary.
 - For classes with subclasses:
-    - The original class name (e.g. `LuaItemStack`) still contains attributes of all subclasses (same as before).
-    - There is now a `Base` type (e.g. `BaseItemStack`) which only includes attributes common to all subclasses.
-    - There is a separate type definition for each subclass, e.g. `BlueprintItem`. Note that one instance may still belong to multiple subclasses (the subclasses are not mutually exclusive).
-    - The above two can be optionally used for stricter types.
+  - The original class name (e.g. `LuaItemStack`) still contains attributes of all subclasses (same as before).
+  - There is now a `Base` type (e.g. `BaseItemStack`) which only includes attributes common to all subclasses.
+  - There is a separate type definition for each subclass, e.g. `BlueprintItem`. Note that one instance may still belong to multiple subclasses (the subclasses are not mutually exclusive).
+  - The above two can be optionally used for stricter types.
 
 # v0.13.2
 
 - Fix: resize_to_sprite property should not be on subclass sprite-button
 - Fix: ChooseElemButtonSpec filters should be named elem_filters
 - Switch back to `/latest` api docs link
-    - New version of web api docs is now active
+  - New version of web api docs is now active
 
 # v0.13.0
 
@@ -96,7 +102,7 @@
 # v0.7.3
 
 - Update to factorio version 1.1.42
-    - No api changes, but improvements to descriptions
+  - No api changes, but improvements to descriptions
 
 # v0.7.2
 

package/README.md

@@ -2,7 +2,7 @@
 
 Complete and featureful typescript definitions for the Factorio modding lua api. This is intended to be used with [TypescriptToLua](https://typescripttolua.github.io/).
 
-This project aims to provide type definitions for the Factorio lua API that are as complete as possible. This means no `any`s or `unknown`s, correct nullability, and smart types where possible. The generator integrates both the Factorio JSON api docs and manually defined additions and overrides.
+This project aims to provide type definitions for the Factorio lua API that are as complete as possible. This means no `any`s or `unknown`s, correct nullability, and lots of smart type features. The generator integrates both the Factorio JSON api docs and manually defined additions and overrides.
 
 ## Installation
 
@@ -42,7 +42,7 @@ Example:
 
 ```ts
 import { Data, Mods } from "typed-factorio/data/types"
-// or 
+// or
 import { Data, Mods } from "typed-factorio/settings/types"
 
 declare const data: Data
@@ -93,15 +93,6 @@ Variant parameter types (types with "additional fields can be specified dependin
 
 The type for a specific variant is prefixed with the variant name, or with "Other" for variants without additional fields (e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`).
 
-### Types with subclasses
-
-Some classes have attributes that are documented to only work on particular subclasses. For these classes, e.g. `LuaEntity`, there are also these other types that you can _optionally_ use:
-
-- a "Base" type, e.g. `BaseEntity`, which only contains members usable by all subclasses
-- individual subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass
-
-The simple class name, `LuaEntity` in this example, still contains attributes for _all_ subclasses.
-
 ### Events
 
 `script.on_event()`, `script.get/set_filters()`, and `script.raise_event()` all have type checking on the event data/filter type, inferred from what is passed as the event name/id.
@@ -120,14 +111,28 @@ 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:
+
+- a "Base" type, e.g. `BaseEntity`, which only contains members usable by all subclasses
+- individual subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass
+
+The simple class name, `LuaEntity` in this example, contains attributes for _all_ subclasses.
+
 ### LuaGuiElement
 
 `LuaGuiElement` is broken up into a [discriminated union](https://basarat.gitbook.io/typescript/type-system/discriminated-unions), with a separate type for each gui element type. Individual gui element types can be referred to by `<Type>GuiElement`, e.g. `ButtonGuiElement`.
 
-Similarly, the table passed to `LuaGuiElement.add`, referred to as `GuiSpec`, is also broken up into a discriminated union for each gui element type. The type for a specific GuiSpec type is `<Type>GuiSpec`, e.g. `ListBoxGuiSpec`. `LuaGuiElement.add` will return the appropriate gui element type corresponding to the gui spec type received.
+Similarly, the table passed to `LuaGuiElement.add`, referred to as `GuiSpec`, is also broken up into a discriminated union. The type for a specific GuiSpec is `<Type>GuiSpec`, e.g. `ListBoxGuiSpec`. `LuaGuiElement.add` will return the appropriate gui element type corresponding to the gui spec type received.
 
 This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
 
-### Examples
+### Strict index types
+
+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"`).
 
-Check out the `test` directory on GitHub for more examples on particular type features.
+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

@@ -0,0 +1,22 @@
+// This references the same files as "typed-factorio/runtime".
+// 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.
+
+/// <reference types="lua-types/5.2" />
+
+// generated
+/// <reference types="typed-factorio/generated/builtin-types.d.ts" />
+/// <reference types="typed-factorio/generated/global-objects.d.ts" />
+/// <reference types="typed-factorio/generated/defines.d.ts" />
+/// <reference types="typed-factorio/generated/events.d.ts" />
+/// <reference types="typed-factorio/generated/classes.d.ts" />
+/// <reference types="typed-factorio/generated/concepts.d.ts" />
+/// <reference types="typed-factorio/generated/index-types.d.ts" />
+
+// other runtime
+/// <reference types="typed-factorio/runtime/librariesAndFunctions.d.ts" />
+/// <reference types="typed-factorio/runtime/pairs.d.ts" />
+
+// lualib
+/// <reference types="typed-factorio/runtime/util.d.ts" />
+/// <reference types="typed-factorio/runtime/mod-gui.d.ts" />