typed-factorio 0.13.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/Changelog.md CHANGED
@@ -1,105 +1,115 @@
1
- # v0.13.2
2
-
3
- - Fix: resize_to_sprite property should not be on subclass sprite-button
4
- - Fix: ChooseElemButtonSpec filters should be named elem_filters
5
- - Switch back to `/latest` api docs link
6
- - New version of web api docs is now active
7
-
8
- # v0.13.0
9
-
10
- - Update to factorio version 1.1.49
11
-
12
- # v0.12.0
13
-
14
- - Update to factorio version 1.1.48
15
-
16
- # v0.11.1
17
-
18
- - Localised strings now accept boolean and undefined.
19
-
20
- # v0.11.0
21
-
22
- - Update to factorio version 1.1.46
23
-
24
- # v0.10.0
25
-
26
- - LuaGuiElement.style and LuaControl.opened now have different get/set types (more specific get type).
27
- - The array form of LocalizedString is now readonly.
28
-
29
- # v0.9.0
30
-
31
- - Update to factorio version 1.1.43
32
- - The `defines.events `_type_ was renamed to `defines.Events`, to reduce confusion between the namespace/type
33
-
34
- # v0.8.0
35
-
36
- - All event types now explicitly extend `EventData`
37
- - Variant parameter groups without additional fields now have their own type, instead of all being grouped into `Other`
38
-
39
- # v0.7.3
40
-
41
- - Update to factorio version 1.1.42
42
- - No api changes, but improvements to descriptions
43
-
44
- # v0.7.2
45
-
46
- - Fix minor issue for event types
47
-
48
- # v0.7.0
49
-
50
- - Updated to factorio version 1.1.41 (no changes to lua api)
51
- - Improved smart types for events
52
-
53
- # v0.6.1
54
-
55
- - Added type for BlueprintControlBehavior
56
-
57
- # v0.6.0
58
-
59
- - Updated to factorio version 1.1.40
60
- - Fixed regression with duplicate strings in string union types
61
-
62
- # v0.5.0
63
-
64
- - Updated to factorio version 1.1.39
65
- - Documentation links now point to the new API docs website. More info here: https://forums.factorio.com/viewtopic.php?f=34&t=99797
66
-
67
- # v0.4.1
68
-
69
- ### Changed
70
-
71
- - LuaRemote.addInterface now lets remote functions take any arguments.
72
-
73
- # v0.4.0
74
-
75
- ## **BREAKING**
76
-
77
- - Only the latest version api is now provided.
78
- - It is now accessed using `typed-factorio/runtime` instead of `typed-factorio/<version>`
79
-
80
- ### Added
81
-
82
- - Basic types for settings and data stage. See README for more details.
83
- - Types for "util" and "mod-gui" lualib modules
84
-
85
- ### Fixed
86
-
87
- - LuaGuiElement::add with a literal now give diagnostic if you supply a field that shouldn't be there.
88
-
89
- ### Internal
90
-
91
- - Split generated files into multiple files
92
- - Improved compilation tests
93
-
94
- # v0.3.0
95
-
96
- - Added factorio version `1.1.38`
97
-
98
- # v0.2.0
99
-
100
- - `AnyBasic` now uses type `table` instead of type `Record<any, AnyBasic>`
101
- - README changes
102
-
103
- # v0.1.0
104
-
105
- - Initial release
1
+ # v0.14.0
2
+
3
+ - LuaStyle size, margin/padding setters now have more specific array types. These array types are `SizeArray` and `StyleValuesArray` for size and margin/padding, respectively.
4
+ - `@noSelf` annotation is now only present when necessary.
5
+ - For classes with subclasses:
6
+ - The original class name (e.g. `LuaItemStack`) still contains attributes of all subclasses (same as before).
7
+ - There is now a `Base` type (e.g. `BaseItemStack`) which only includes attributes common to all subclasses.
8
+ - 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).
9
+ - The above two can be optionally used for stricter types.
10
+
11
+ # v0.13.2
12
+
13
+ - Fix: resize_to_sprite property should not be on subclass sprite-button
14
+ - Fix: ChooseElemButtonSpec filters should be named elem_filters
15
+ - Switch back to `/latest` api docs link
16
+ - New version of web api docs is now active
17
+
18
+ # v0.13.0
19
+
20
+ - Update to factorio version 1.1.49
21
+
22
+ # v0.12.0
23
+
24
+ - Update to factorio version 1.1.48
25
+
26
+ # v0.11.1
27
+
28
+ - Localised strings now accept boolean and undefined.
29
+
30
+ # v0.11.0
31
+
32
+ - Update to factorio version 1.1.46
33
+
34
+ # v0.10.0
35
+
36
+ - LuaGuiElement.style and LuaControl.opened now have different get/set types (more specific get type).
37
+ - The array form of LocalizedString is now readonly.
38
+
39
+ # v0.9.0
40
+
41
+ - Update to factorio version 1.1.43
42
+ - The `defines.events `_type_ was renamed to `defines.Events`, to reduce confusion between the namespace/type
43
+
44
+ # v0.8.0
45
+
46
+ - All event types now explicitly extend `EventData`
47
+ - Variant parameter groups without additional fields now have their own type, instead of all being grouped into `Other`
48
+
49
+ # v0.7.3
50
+
51
+ - Update to factorio version 1.1.42
52
+ - No api changes, but improvements to descriptions
53
+
54
+ # v0.7.2
55
+
56
+ - Fix minor issue for event types
57
+
58
+ # v0.7.0
59
+
60
+ - Updated to factorio version 1.1.41 (no changes to lua api)
61
+ - Improved smart types for events
62
+
63
+ # v0.6.1
64
+
65
+ - Added type for BlueprintControlBehavior
66
+
67
+ # v0.6.0
68
+
69
+ - Updated to factorio version 1.1.40
70
+ - Fixed regression with duplicate strings in string union types
71
+
72
+ # v0.5.0
73
+
74
+ - Updated to factorio version 1.1.39
75
+ - Documentation links now point to the new API docs website. More info here: https://forums.factorio.com/viewtopic.php?f=34&t=99797
76
+
77
+ # v0.4.1
78
+
79
+ ### Changed
80
+
81
+ - LuaRemote.addInterface now lets remote functions take any arguments.
82
+
83
+ # v0.4.0
84
+
85
+ ## **BREAKING**
86
+
87
+ - Only the latest version api is now provided.
88
+ - It is now accessed using `typed-factorio/runtime` instead of `typed-factorio/<version>`
89
+
90
+ ### Added
91
+
92
+ - Basic types for settings and data stage. See README for more details.
93
+ - Types for "util" and "mod-gui" lualib modules
94
+
95
+ ### Fixed
96
+
97
+ - LuaGuiElement::add with a literal now give diagnostic if you supply a field that shouldn't be there.
98
+
99
+ ### Internal
100
+
101
+ - Split generated files into multiple files
102
+ - Improved compilation tests
103
+
104
+ # v0.3.0
105
+
106
+ - Added factorio version `1.1.38`
107
+
108
+ # v0.2.0
109
+
110
+ - `AnyBasic` now uses type `table` instead of type `Record<any, AnyBasic>`
111
+ - README changes
112
+
113
+ # v0.1.0
114
+
115
+ - Initial release
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2021 Benjamin Ye
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2021 Benjamin Ye
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,113 +1,128 @@
1
- # Typed Factorio
2
-
3
- Complete and featureful typescript definitions for the Factorio modding lua api. This is intended to be used with [TypescriptToLua](https://typescripttolua.github.io/).
4
-
5
- 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.
6
-
7
- ## Installation
8
-
9
- To use in your TypescriptToLua project:
10
-
11
- 1. Install this package
12
-
13
- ```
14
- npm install typed-factorio
15
-
16
- or
17
-
18
- yarn add typed-factorio
19
- ```
20
-
21
- 2. Add to your `tsconfig.json`:
22
-
23
- ```diff
24
- {
25
- "compilerOptions": {
26
- + "types": [ "typed-factorio/runtime" ]
27
- }
28
- }
29
- ```
30
-
31
- This will add the types for the runtime stage to your entire project.
32
-
33
- Note: When types are updated, or released for a new factorio version, you will need update your package version to get the types.
34
-
35
- ### Settings and data stage
36
-
37
- There are also definitions for the settings/data stage.
38
-
39
- 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`.
40
-
41
- Example:
42
-
43
- ```ts
44
- import { Data, Mods } from "typed-factorio/data/types"
45
- // or
46
- import { Data, Mods } from "typed-factorio/settings/types"
47
-
48
- declare const data: Data
49
- declare const mods: Mods
50
-
51
- data.extend([{ ... }])
52
- ```
53
-
54
- There are currently full types for settings stage, but only basic types for the data stage.
55
-
56
- ### Factorio lualib modules
57
-
58
- Currently, there are types for the following modules:
59
-
60
- - `util`
61
- - `mod-gui`
62
-
63
- If you have a need for types to more lualib modules, feel free to open an issue or pull request on GitHub.
64
-
65
- ## Type features
66
-
67
- Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
68
-
69
- ### Lua features
70
-
71
- The types include [TypescriptToLua language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions/)
72
- and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2) as dependencies.
73
-
74
- This is to use tstl features such as `LuaLengthMethod` and `LuaMultiReturn`.
75
-
76
- ### `nil`
77
-
78
- The types consistently use `undefined` to represent `nil`.
79
- `null` is not used, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `undefined`.
80
-
81
- 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!`.
82
-
83
- ### Variant parameter types
84
-
85
- 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.
86
-
87
- The type for a specific variant is prefixed with the either variant name or "Other" for variants without additional fields, e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`
88
-
89
- ### Events
90
-
91
- `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.
92
-
93
- 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.
94
-
95
- ### Array-like types
96
-
97
- 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**.
98
-
99
- ### Table or array types
100
-
101
- 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.
102
-
103
- ### LuaGuiElement
104
-
105
- `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`.
106
-
107
- 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`.
108
-
109
- This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
110
-
111
- ### Examples
112
-
113
- Check out the `test` directory on GitHub for more examples on particular type features.
1
+ # Typed Factorio
2
+
3
+ Complete and featureful typescript definitions for the Factorio modding lua api. This is intended to be used with [TypescriptToLua](https://typescripttolua.github.io/).
4
+
5
+ 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.
6
+
7
+ ## Installation
8
+
9
+ To use in your TypescriptToLua project:
10
+
11
+ 1. Install this package
12
+
13
+ ```
14
+ npm install typed-factorio
15
+
16
+ or
17
+
18
+ yarn add typed-factorio
19
+ ```
20
+
21
+ 2. Add to your `tsconfig.json`:
22
+
23
+ ```diff
24
+ {
25
+ "compilerOptions": {
26
+ + "types": [ "typed-factorio/runtime" ]
27
+ }
28
+ }
29
+ ```
30
+
31
+ This will add the types for the runtime stage to your entire project.
32
+
33
+ Note: When types are updated, or released for a new factorio version, you will need update your package version to get the types.
34
+
35
+ ### Settings and data stage
36
+
37
+ There are also definitions for the settings/data stage.
38
+
39
+ 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`.
40
+
41
+ Example:
42
+
43
+ ```ts
44
+ import { Data, Mods } from "typed-factorio/data/types"
45
+ // or
46
+ import { Data, Mods } from "typed-factorio/settings/types"
47
+
48
+ declare const data: Data
49
+ declare const mods: Mods
50
+
51
+ data.extend([{ ... }])
52
+ ```
53
+
54
+ There are currently full types for settings stage, but only basic types for the data stage.
55
+
56
+ ### Factorio lualib modules
57
+
58
+ Currently, there are types for the following modules:
59
+
60
+ - `util`
61
+ - `mod-gui`
62
+
63
+ If you have a need for types to more lualib modules, feel free to open an issue or pull request on GitHub.
64
+
65
+ ### The `global` table
66
+
67
+ 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:
68
+
69
+ - add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide, or
70
+ - add `declare const global: {...}` to each module/file where needed. This way, you can also only define attributes that each module/file specifically uses.
71
+
72
+ ## Type features
73
+
74
+ Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
75
+
76
+ Here are some details on particular type features in the definitions:
77
+
78
+ ### Lua features
79
+
80
+ The types include [TypescriptToLua language extensions](https://typescripttolua.github.io/docs/advanced/language-extensions/)
81
+ and [lua-types](https://github.com/TypeScriptToLua/lua-types) (for v5.2) as dependencies.
82
+
83
+ ### `nil`
84
+
85
+ The types consistently use `undefined` to represent `nil`.
86
+ `null` is not used, because `undefined` in typescript is much more similar to `nil` in lua, and optional parameters/properties already use `undefined`.
87
+
88
+ 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!`.
89
+
90
+ ### Variant parameter types
91
+
92
+ 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.
93
+
94
+ The type for a specific variant is prefixed with the variant name, or with "Other" for variants without additional fields (e.g. `AmmoDamageTechnologyModifier`, `OtherTechnologyModifier`).
95
+
96
+ ### Types with subclasses
97
+
98
+ 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:
99
+ - a "Base" type, e.g. `BaseEntity`, which only contains members usable by all subclasses
100
+ - individual subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass
101
+
102
+ The simple class name, `LuaEntity` in this example, still contains attributes for _all_ subclasses.
103
+
104
+ ### Events
105
+
106
+ `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.
107
+
108
+ 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.
109
+
110
+ ### Array-like types
111
+
112
+ 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**.
113
+
114
+ ### Table or array types
115
+
116
+ 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.
117
+
118
+ ### LuaGuiElement
119
+
120
+ `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`.
121
+
122
+ 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.
123
+
124
+ This is done both to provide more accurate types, and for possible integration with [JSX](https://typescripttolua.github.io/docs/jsx/).
125
+
126
+ ### Examples
127
+
128
+ Check out the `test` directory on GitHub for more examples on particular type features.
package/data/types.d.ts CHANGED
@@ -1,13 +1,13 @@
1
- export interface Data {
2
- readonly raw: Record<string, Record<string, any>>
3
-
4
- /**
5
- * The `data` table expects a specific format for each item in the table. Missing properties will either fall back to
6
- * default values or give an error indicating what's missing. Extra properties that the game isn't looking for are
7
- * simply ignored.
8
- */
9
- extend(prototypes: Record<string, any>[]): void
10
- }
11
-
12
- /** A mapping of mod names to mod version for all enabled mods. */
13
- export type Mods = Record<string, string>
1
+ export interface Data {
2
+ readonly raw: Record<string, Record<string, any>>
3
+
4
+ /**
5
+ * The `data` table expects a specific format for each item in the table. Missing properties will either fall back to
6
+ * default values or give an error indicating what's missing. Extra properties that the game isn't looking for are
7
+ * simply ignored.
8
+ */
9
+ extend(prototypes: Record<string, any>[]): void
10
+ }
11
+
12
+ /** A mapping of mod names to mod version for all enabled mods. */
13
+ export type Mods = Record<string, string>