typed-factorio 0.13.2 → 0.16.0

package/Changelog.md

@@ -1,105 +1,135 @@
-# 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
-
-# v0.13.0
-
-- Update to factorio version 1.1.49
-
-# v0.12.0
-
-- Update to factorio version 1.1.48
-
-# v0.11.1
-
-- Localised strings now accept boolean and undefined.
-
-# v0.11.0
-
-- Update to factorio version 1.1.46
-
-# v0.10.0
-
-- LuaGuiElement.style and LuaControl.opened now have different get/set types (more specific get type).
-- The array form of LocalizedString is now readonly.
-
-# v0.9.0
-
-- Update to factorio version 1.1.43
-- The `defines.events `_type_ was renamed to `defines.Events`, to reduce confusion between the namespace/type
-
-# v0.8.0
-
-- All event types now explicitly extend `EventData`
-- Variant parameter groups without additional fields now have their own type, instead of all being grouped into `Other`
-
-# v0.7.3
-
-- Update to factorio version 1.1.42
-    - No api changes, but improvements to descriptions
-
-# v0.7.2
-
-- Fix minor issue for event types
-
-# v0.7.0
-
-- Updated to factorio version 1.1.41 (no changes to lua api)
-- Improved smart types for events
-
-# v0.6.1
-
-- Added type for BlueprintControlBehavior
-
-# v0.6.0
-
-- Updated to factorio version 1.1.40
-- Fixed regression with duplicate strings in string union types
-
-# v0.5.0
-
-- Updated to factorio version 1.1.39
-- Documentation links now point to the new API docs website. More info here: https://forums.factorio.com/viewtopic.php?f=34&t=99797
-
-# v0.4.1
-
-### Changed
-
-- LuaRemote.addInterface now lets remote functions take any arguments.
-
-# v0.4.0
-
-## **BREAKING**
-
-- Only the latest version api is now provided.
-- It is now accessed using `typed-factorio/runtime` instead of `typed-factorio/<version>`
-
-### Added
-
-- Basic types for settings and data stage. See README for more details.
-- Types for "util" and "mod-gui" lualib modules
-
-### Fixed
-
-- LuaGuiElement::add with a literal now give diagnostic if you supply a field that shouldn't be there.
-
-### Internal
-
-- Split generated files into multiple files
-- Improved compilation tests
-
-# v0.3.0
-
-- Added factorio version `1.1.38`
-
-# v0.2.0
-
-- `AnyBasic` now uses type `table` instead of type `Record<any, AnyBasic>`
-- README changes
-
-# v0.1.0
-
-- Initial release
+# v0.16.0
+
+- `LuaCustomTable` can be iterated on in a for-of loop directly (without using `pairs`). This requires TSTL v1.3.0 or later.
+- TSTL dependency minimum version is now v1.3.0.
+
+# 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.
+- 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-only arrays to these methods.
+- `MapPosition` is now a table or array concept.
+- Classes with subclasses are now declared with all properties, instead of an intersection of subclasses (reversion)
+- Subclass specializations added for some missing classes
+
+# v0.14.1
+
+- LuaStyle: `extra_margin/padding_when_activated` is now for subclass scroll_pane
+
+# v0.14.0
+
+- 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.
+
+# 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
+
+# v0.13.0
+
+- Update to factorio version 1.1.49
+
+# v0.12.0
+
+- Update to factorio version 1.1.48
+
+# v0.11.1
+
+- Localised strings now accept boolean and undefined.
+
+# v0.11.0
+
+- Update to factorio version 1.1.46
+
+# v0.10.0
+
+- LuaGuiElement.style and LuaControl.opened now have different get/set types (more specific get type).
+- The array form of LocalizedString is now readonly.
+
+# v0.9.0
+
+- Update to factorio version 1.1.43
+- The `defines.events `_type_ was renamed to `defines.Events`, to reduce confusion between the namespace/type
+
+# v0.8.0
+
+- All event types now explicitly extend `EventData`
+- Variant parameter groups without additional fields now have their own type, instead of all being grouped into `Other`
+
+# v0.7.3
+
+- Update to factorio version 1.1.42
+  - No api changes, but improvements to descriptions
+
+# v0.7.2
+
+- Fix minor issue for event types
+
+# v0.7.0
+
+- Updated to factorio version 1.1.41 (no changes to lua api)
+- Improved smart types for events
+
+# v0.6.1
+
+- Added type for BlueprintControlBehavior
+
+# v0.6.0
+
+- Updated to factorio version 1.1.40
+- Fixed regression with duplicate strings in string union types
+
+# v0.5.0
+
+- Updated to factorio version 1.1.39
+- Documentation links now point to the new API docs website. More info here: https://forums.factorio.com/viewtopic.php?f=34&t=99797
+
+# v0.4.1
+
+### Changed
+
+- LuaRemote.addInterface now lets remote functions take any arguments.
+
+# v0.4.0
+
+## **BREAKING**
+
+- Only the latest version api is now provided.
+- It is now accessed using `typed-factorio/runtime` instead of `typed-factorio/<version>`
+
+### Added
+
+- Basic types for settings and data stage. See README for more details.
+- Types for "util" and "mod-gui" lualib modules
+
+### Fixed
+
+- LuaGuiElement::add with a literal now give diagnostic if you supply a field that shouldn't be there.
+
+### Internal
+
+- Split generated files into multiple files
+- Improved compilation tests
+
+# v0.3.0
+
+- Added factorio version `1.1.38`
+
+# v0.2.0
+
+- `AnyBasic` now uses type `table` instead of type `Record<any, AnyBasic>`
+- README changes
+
+# v0.1.0
+
+- Initial release

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 Benjamin Ye
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2021 Benjamin Ye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,113 +1,133 @@
-# Typed Factorio
-
-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 API that are as complete as possible. This means minimal `any`s and `unknown`s, correct nullability, and smart types where possible. The generator integrates both the Factorio JSON api docs and manually defined additions and overrides.
-
-## Installation
-
-To use in your TypescriptToLua project:
-
-1. Install this package
-
-```
-npm install typed-factorio
-
-or
-
-yarn add typed-factorio
-```
-
-2. Add to your `tsconfig.json`:
-
-```diff
-{
-  "compilerOptions": {
-+    "types": [ "typed-factorio/runtime" ]
-  }
-}
-```
-
-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.
-
-### Settings and data stage
-
-There are also definitions for the settings/data stage.
-
-To avoid type conflicts, the global tables for the settings/data stages have to be declared manually where you need them. These types can be imported from `typed-factorio/data/types` or `typed-factorio/settings/types`.
-
-Example:
-
-```ts
-import { Data, Mods } from "typed-factorio/data/types"
-// or 
-import { Data, Mods } from "typed-factorio/settings/types"
-
-declare const data: Data
-declare const mods: Mods
-
-data.extend([{ ... }])
-```
-
-There are currently full types for settings stage, but only basic types for the data stage.
-
-### Factorio lualib modules
-
-Currently, there are types for the following modules:
-
-- `util`
-- `mod-gui`
-
-If you have a need for types to more lualib modules, feel free to open an issue or pull request on GitHub.
-
-## Type features
-
-Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
-
-### Lua features
-
-The types include [TypescriptToLua language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions/)
-and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2) as dependencies.
-
-This is to use tstl features such as `LuaLengthMethod` and `LuaMultiReturn`.
-
-### `nil`
-
-The types consistently use `undefined` to represent `nil`.
-`null` is not used, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `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 is possible on _write_, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
-
-### Variant parameter types
-
-Variant parameter types (types with "additional fields can be specified depending on ...") are handled as discriminated unions. This gives proper type checking for individual variants.
-
-The type for a specific variant is prefixed with the either variant name or "Other" for variants without additional fields, e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`
-
-### 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.
-
-You can pass a type parameter to `script.generate_event_name()`, and it will return an `EventId` that holds type info of the event data. Event functions on `script` can then use the type data when the `EventId` is passed.
-
-### Array-like types
-
-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
-
-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 specifically.
-
-### LuaGuiElement
-
-`LuaGuiElement` is broken up into a discriminated union for each gui element type (See [here](https://basarat.gitbook.io/typescript/type-system/discriminated-unions) for information on discriminated unions). The type for a specific GuiElement type is `<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`.
-
-This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
-
-### Examples
-
-Check out the `test` directory on GitHub for more examples on particular type features.
+# Typed Factorio
+
+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.
+
+## Installation
+
+To use in your TypescriptToLua project:
+
+1. Install this package
+
+```
+npm install typed-factorio
+
+or
+
+yarn add typed-factorio
+```
+
+2. Add to your `tsconfig.json`:
+
+```diff
+{
+  "compilerOptions": {
++    "types": [ "typed-factorio/runtime" ]
+  }
+}
+```
+
+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.
+
+### Settings and data stage
+
+There are also definitions for the settings/data stage.
+
+To avoid type conflicts, the global tables for the settings/data stages have to be declared manually where you need them. These types can be imported from `typed-factorio/data/types` or `typed-factorio/settings/types`.
+
+Example:
+
+```ts
+import { Data, Mods } from "typed-factorio/data/types"
+// or 
+import { Data, Mods } from "typed-factorio/settings/types"
+
+declare const data: Data
+declare const mods: Mods
+
+data.extend([{ ... }])
+```
+
+There are currently full types for settings stage, but only basic types for the data stage.
+
+### Factorio lualib modules
+
+Currently, there are types for the following modules:
+
+- `util`
+- `mod-gui`
+
+If you have a need for types to more lualib modules, feel free to open an issue or pull request on GitHub.
+
+### 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:
+
+- 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.
+
+## Type features
+
+Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
+
+Here are some details on particular type features:
+
+### Lua features
+
+The types include [TypescriptToLua language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions/)
+and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2) as dependencies.
+
+### `nil`
+
+The types consistently use `undefined` to represent `nil`.
+`null` is not used, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `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 is possible on _write_, you can write `nil` by using `undefined!` or `myNullableValue!`, e.g. `controlBehavior.parameters = undefined!`.
+
+### Variant parameter types
+
+Variant parameter types (types with "additional fields can be specified depending on type") are handled as a union of all variants (which is often a [discriminated union](https://basarat.gitbook.io/typescript/type-system/discriminated-unions#discriminated-union)). This gives proper type checking for each variant.
+
+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.
+
+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 functions on `script` can then use the type data when the `EventId` is passed.
+
+### Array-like types
+
+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, and "Read" concepts
+
+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.
+
+Table-or-array types will appear in the Table form when known to be in a read position. This also applies to other concepts/complex types that have table-or-array attributes.
+
+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`.
+
+### 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.
+
+This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
+
+### Examples
+
+Check out the `test` directory on GitHub for more examples on particular type features.

package/data/types.d.ts

@@ -1,13 +1,13 @@
-export interface Data {
-  readonly raw: Record<string, Record<string, any>>
-
-  /**
-   * The `data` table expects a specific format for each item in the table. Missing properties will either fall back to
-   * default values or give an error indicating what's missing. Extra properties that the game isn't looking for are
-   * simply ignored.
-   */
-  extend(prototypes: Record<string, any>[]): void
-}
-
-/** A mapping of mod names to mod version for all enabled mods. */
-export type Mods = Record<string, string>
+export interface Data {
+  readonly raw: Record<string, Record<string, any>>
+
+  /**
+   * The `data` table expects a specific format for each item in the table. Missing properties will either fall back to
+   * default values or give an error indicating what's missing. Extra properties that the game isn't looking for are
+   * simply ignored.
+   */
+  extend(prototypes: Record<string, any>[]): void
+}
+
+/** A mapping of mod names to mod version for all enabled mods. */
+export type Mods = Record<string, string>