typed-factorio 0.18.1 → 0.20.0-beta.1

package/Changelog.md

@@ -1,3 +1,19 @@
+# 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.
+
+# v0.19.0
+
+- Updated to factorio version 1.1.53
+- Updated to json api version 2
+- Improved documentation comments
+
+## Changes
+
+- `Position`, `PositionArray`, and `PositionTable` have been replaced by `MapPosition`, `MapPositionArray`, and `MapPositionTable` respectively. These are now deprecated and may be removed in a future version.
+
 # v0.18.1
 
 - `TechnologyIdentification` now also has a more specific type when read.
@@ -23,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.
@@ -40,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
 
@@ -86,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
 
@@ -30,7 +30,10 @@ yarn add typed-factorio
 
 This will add the types for the runtime stage to your entire project.
 
-Note: When types are updated, or released for a new factorio version, you will need update your package version to get the types.
+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.
 
 ### Settings and data stage
 
@@ -42,7 +45,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 +96,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 +114,31 @@ 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 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.
 
-Check out the `test` directory on GitHub for more examples on particular type features.
+- `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.

package/custom-index-template.d.ts

@@ -0,0 +1,24 @@
+// 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.
+
+// 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
+/// <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" />

package/generated/builtin-types.d.ts

@@ -3,9 +3,7 @@
 /** @noSelfInFile */
 
 /**
- * A floating-point number. This is a single-precision floating point number. Whilst Lua only uses double-precision
- * numbers, when a function takes a float, the game engine will immediately convert the double-precision number to
- * single-precision.
+ * A floating-point number. This is a single-precision floating point number. Whilst Lua only uses double-precision numbers, when a function takes a float, the game engine will immediately convert the double-precision number to single-precision.
  *
  * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#float View documentation}
  */