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 +115 -105
- package/LICENSE +21 -21
- package/README.md +128 -113
- package/data/types.d.ts +13 -13
- package/generated/classes.d.ts +2127 -1750
- package/generated/concepts.d.ts +6 -0
- package/generated/index.d.ts +2 -0
- package/package.json +58 -58
- package/runtime/index.d.ts +10 -10
- package/runtime/librariesAndFunctions.d.ts +123 -123
- package/runtime/mod-gui.d.ts +11 -11
- package/runtime/pairs.d.ts +13 -13
- package/runtime/util.d.ts +120 -120
- package/settings/types.d.ts +120 -120
package/Changelog.md
CHANGED
@@ -1,105 +1,115 @@
|
|
1
|
-
# v0.
|
2
|
-
|
3
|
-
-
|
4
|
-
-
|
5
|
-
-
|
6
|
-
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
-
|
33
|
-
|
34
|
-
# v0.
|
35
|
-
|
36
|
-
-
|
37
|
-
-
|
38
|
-
|
39
|
-
# v0.
|
40
|
-
|
41
|
-
- Update to factorio version 1.1.
|
42
|
-
|
43
|
-
|
44
|
-
# v0.
|
45
|
-
|
46
|
-
-
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
-
|
66
|
-
|
67
|
-
# v0.
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
|
75
|
-
|
76
|
-
|
77
|
-
|
78
|
-
|
79
|
-
|
80
|
-
|
81
|
-
|
82
|
-
|
83
|
-
|
84
|
-
|
85
|
-
|
86
|
-
|
87
|
-
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
-
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
101
|
-
-
|
102
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
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
|
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
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
|
75
|
-
|
76
|
-
|
77
|
-
|
78
|
-
|
79
|
-
|
80
|
-
|
81
|
-
|
82
|
-
|
83
|
-
###
|
84
|
-
|
85
|
-
|
86
|
-
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
111
|
-
|
112
|
-
|
113
|
-
|
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>
|