typed-factorio 1.3.1 → 1.5.0

package/Changelog.md

@@ -1,6 +1,38 @@
+# v1.5.0
+
+### BREAKING
+
+- Read-only forms of concepts (the most common form used) is now specified with just the name; forms with a `Read` or `Table` suffix have been removed.
+- Write forms are now specified as either a union of table and array forms, or with a `Write` suffix for concepts.
+  - For table-or-array concepts: `MapPositionRead` -> `MapPosition`, `MapPosition` -> `MapPosition | PositionArray`
+  - For table concepts: `ScriptAreaRead` -> `ScriptArea`, `ScriptArea` -> `ScriptAreaWrite`
+- The minimum TSTL version has been increased to v1.6.1 (A bug with documentation comments was fixed in that version).
+
+### Other
+
+- Updated to factorio version 1.1.63.
+- Upgraded to factorio api docs json version 3.
+- The new type `nil` is used instead of `undefined` (they are equivalent).
+- More complete type for `BlueprintEntity`.
+- Fixed missing read-write forms for more concepts.
+- Improved documentation comments (enabled by json docs version 3).
+- Improved documentation comments for variant parameter groups.
+
+# v1.4.0
+
+- Improve doc comments for enum concepts
+- Improve doc comment formatting
+- Improve types of concepts with literal union types
+- Add read-specific types to AutoplaceControl and ComparatorString
+
+# v1.3.2
+
+- Move "notes" comment into the main body of doc comment, instead of in @remarks. This works around #13.
+- Add manually defined overload for LuaControl::teleport().
+
 # v1.3.1
 
-- Use @linkplain instead of @link for web links. This works around issue #13
+- Use @linkplain instead of @link for web links. This hopefully works around issue #13
 
 # v1.3.0
 
@@ -60,8 +92,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.
@@ -77,17 +109,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
 
@@ -123,7 +155,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

@@ -64,41 +64,36 @@ If you have a need for types to more lualib modules, feel free to open an issue
 
 ### The `global` table
 
-The `global` table is just a lua table which can have any shape the mod desires, so it is not defined in typed-factorio. Instead, you can either:
+The `global` table is a lua table which can have any shape, so it is not defined in typed-factorio. Instead, you can either:
 
 - add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide, or
-- add `declare const global: {...}` to each module/file where needed. This way, you can also only define attributes that each module/file specifically uses.
+- add `declare const global: {...}` to each module/file where needed. This way, you can define only attributes that each module/file specifically uses.
 
 ## Type features
 
-Here is a quick overview of type features:
+### `nil`
 
-### Nullability
-
-The types consistently use `undefined` to represent `nil`.
+`nil` is equivalent to `undefined`.
 
 A class attribute is marked as possibly undefined only if the _read_ type is possibly `nil`. For properties where `nil` is not possible on _read_, but possible on _write_, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
 
 ### Parameter Variants
 
-Parameters with variants (with "additional fields can be specified depending on type ...") are defined as a union of all variants. The type for a specific variant is prefixed with the variant name, or "Other" types variants without extra properties (e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`).
+Parameter tables with variants (having "additional attributes can be specified depending on type ...") are defined as a union of all variants. The type for a specific variant is prefixed with the variant name, or "Other" types variants without extra properties (e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`).
 
 ### Events
 
-Event IDs (`defines.events`) carry information about their event type and possible filters, which is used by the various methods on `script`.
-You can pass a type parameter to `script.generate_event_name<T>()`, and it will return an `EventId` that holds type info of the event data.
+Event IDs (`defines.events`) carry information about their event type and filters, which is used by the various methods on `script`.
+You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that holds type info of the event data.
 
 ### Array-like classes
 
-Classes that have an index operator, a length operator, and have an array-like structure, inherit from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`. This allows you to use these classes like arrays, meaning having array methods, and `.length` translating to the lua length operator. However, this also means, like typescript arrays, they are **0-indexed, not 1-indexed**.
-
-### Table-or-array concepts, and "Read" variants
-
-For table-or-array types (e.g. Position), there also are types such as `PositionTable` and `PositionArray` that refer to the table or array form.
+Classes that have an index operator, a length operator, and have an array-like structure, inherit from `(Readonly)Array` (these are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`). This allows you to use these classes like arrays, meaning having array methods, and `.length` translating to the lua length operator. However, this also means, like typescript arrays, they are **0-indexed, not 1-indexed**.
 
-Table-or-array types will appear in Table form when known to be in a read position. This also applies to other concepts/types that have table-or-array attributes.
+### Read and write variants
 
-For some concepts, there is also a special form for when it 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`, `BoundingBoxRead`.
+For concepts that can take a table or array form, the main type (e.g. `MapPosition`) defines the table form, and an `Array` suffix (e.g. `MapPositionArray`) defines the array form.
+Concepts in a "read" position will always be in the table form, and concepts in a "write" position may be either in table or array form (e.g. `MapPosition | MapPositionArray`). This is including within other concepts (e.g. in `ScriptArea`, via the `ScriptAreaWrite` type).
 
 ### Classes with subclasses
 
@@ -113,7 +108,7 @@ For stricter types, use the `Base` type generally, and the specific subclass typ
 You can also create your own type-narrowing functions, like so:
 
 ```ts
-function isCraftingMachineEntity(entity: LuaEntity): entity is CraftingMachineEntity {
+function isCraftingMachineEntity(entity: BaseEntity): entity is CraftingMachineEntity {
   return entity.type === "crafting-machine"
 }
 ```
@@ -122,7 +117,7 @@ function isCraftingMachineEntity(entity: LuaEntity): entity is CraftingMachineEn
 
 `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. 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.
+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 GuiSpec type received.
 
 This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
 
@@ -130,6 +125,6 @@ This is done both to provide more accurate types, and for possible integration w
 
 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"`).
 
-Some `uint` types which represent unique indices, e.g. player_index, entity_number, can be "branded" numbers with their own type, e.g. `PlayerIndex` and `EntityNumber`. If opted-in, these index-types will be still assignable to `number`, but a plain `number` is not directly assignable to them. This helps ensure correctness.
+Some `uint` types which represent unique indices, e.g. player_index, entity_number, can be "branded" numbers, e.g. `PlayerIndex` and `EntityNumber`. If opted-in, these index-types will be still assignable to `number`, but a plain `number` is not directly assignable to them. This helps ensure their correct use.
 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

@@ -7,6 +7,7 @@
 // generated
 /// <reference types="typed-factorio/generated/builtin-types.d.ts" />
 /// <reference types="typed-factorio/generated/global-objects.d.ts" />
+/// <reference types="typed-factorio/generated/global-functions.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" />

package/generated/builtin-types.d.ts

@@ -4,63 +4,68 @@
 
 /**
  * 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}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#float Online documentation}
  */
 type float = number
 
 /**
  * A double-precision floating-point number. This is the same data type as all Lua numbers use.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#double View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#double Online documentation}
  */
 type double = number
 
 /**
  * 32-bit signed integer. Possible values are -2,147,483,648 to 2,147,483,647.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#int View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#int Online documentation}
  */
 type int = number
 
 /**
  * 8-bit signed integer. Possible values are -128 to 127.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#int8 View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#int8 Online documentation}
  */
 type int8 = number
 
 /**
  * 32-bit unsigned integer. Possible values are 0 to 4,294,967,295.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint Online documentation}
  */
 type uint = number
 
 /**
  * 8-bit unsigned integer. Possible values are 0 to 255.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint8 View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint8 Online documentation}
  */
 type uint8 = number
 
 /**
  * 16-bit unsigned integer. Possible values are 0 to 65535.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint16 View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint16 Online documentation}
  */
 type uint16 = number
 
 /**
  * 64-bit unsigned integer. Possible values are 0 to 18,446,744,073,709,551,615.
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint64 View documentation}
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#uint64 Online documentation}
  */
 type uint64 = number
 
 /**
- * Tables are enclosed in curly brackets, like this `{}`
- *
- * {@link https://lua-api.factorio.com/latest/Builtin-Types.html#table View documentation}
+ * Nil is the type of the value `nil`, whose main property is to be different from any other value. It usually represents the absence of a useful value.
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#nil Online documentation}
+ */
+type nil = undefined
+
+/**
+ * Tables are enclosed in curly brackets, like this `{}`.
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#table Online documentation}
  */
 type table = object
+
+/**
+ * Any LuaObject listed on the {@linkplain https://lua-api.factorio.com/latest/Classes.html Classes} page.
+ * @see {@link https://lua-api.factorio.com/latest/Builtin-Types.html#LuaObject Online documentation}
+ */
+interface LuaObject {
+  readonly object_name: string
+}