typed-factorio 2.5.2 → 2.6.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/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,8 +1,8 @@
1
1
  # Typed Factorio
2
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/).
3
+ Complete and featureful typescript definitions for the Factorio modding lua API, for use with [TypescriptToLua](https://typescripttolua.github.io/).
4
4
 
5
- This project aims to provide type definitions for the Factorio lua API that are as complete as possible.
5
+ This project aims to provide type definitions are as complete as possible.
6
6
  The generator uses both the Factorio api docs JSON and manually defined additions.
7
7
 
8
8
  ## Installation
@@ -10,14 +10,15 @@ The generator uses both the Factorio api docs JSON and manually defined addition
10
10
  To use in your [TypescriptToLua](https://typescripttolua.github.io/) project:
11
11
 
12
12
  1. Install this package: `npm install typed-factorio`
13
- - Note: When types are updated for a new factorio version, you will need to the npm package to get the latest types.
13
+ - Note: When types are updated for a new factorio version, you will need to update this package.
14
14
 
15
- 2. Add the types for the [stages](https://lua-api.factorio.com/1.1.89/index.html) used to `tsconfig.json > compilerOptions > types`.
15
+ 2. Add types for the [stages](https://lua-api.factorio.com/1.1.89/index.html) used to `tsconfig.json > compilerOptions > types`.
16
16
  The available stages are `"typed-factorio/settings"`, `"typed-factorio/prototype"`, and `"typed-factorio/runtime"`.
17
17
 
18
18
  Example:
19
19
 
20
20
  ```diff
21
+ // in tsconfig.json
21
22
  {
22
23
  "compilerOptions": {
23
24
  + "types": [ "typed-factorio/runtime" ]
@@ -25,14 +26,14 @@ Example:
25
26
  }
26
27
  ```
27
28
 
28
- The stages selected will control the global variables defined.
29
- It is possible to include multiple stages, but there are some caveats. See [Using multiple stages in the same project](#using-multiple-stages-in-the-same-project) for more info.
29
+ The stages used will select the global variables defined.
30
+ You can include multiple stages, but there are some caveats. See [Using multiple stages in the same project](#using-multiple-stages-in-the-same-project) for more info.
30
31
 
31
- ## Usage
32
+ ## Usage notes
32
33
 
33
- Global variables will be defined for the stage(s) selected.
34
+ Here are some notes on using the types:
34
35
 
35
- ### Types
36
+ ### Types for other stages
36
37
 
37
38
  No matter which stage(s) are selected, _type_ definitions for all stages are available in the modules `"factorio:settings"`, `"factorio:prototype"`, and `"factorio:runtime"`:
38
39
  ```ts
@@ -41,7 +42,9 @@ import { ItemPrototype } from "factorio:prototype"
41
42
  import { LuaEntity } from "factorio:runtime"
42
43
  ```
43
44
 
44
- ### `data.extend()`
45
+ You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
46
+
47
+ ### `data.extend()` types
45
48
  In the settings and prototype stages, the `data` global variable is available.
46
49
 
47
50
  For [performance reasons](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-base-types-over-unions), `data.extend()` is by default loosely typed.
@@ -98,37 +101,33 @@ If you wish to see types for more lualib modules, feel free to open an issue or
98
101
 
99
102
  ### The `global` table
100
103
 
101
- The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can:
104
+ The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can define it yourself:
102
105
 
103
- - add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide, or
104
- - add `declare const global: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
106
+ - Add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide.
107
+ - Add `declare const global: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
105
108
 
106
109
  ## Using multiple stages in the same project
107
110
 
108
111
  Every Factorio loading stage declares different global variables.
109
- To add types for multiple Factorio stages, you have a few options, with different pros and cons:
112
+ To add types for multiple Factorio stages, you have a few options:
110
113
 
111
114
  1. Add multiple stages to the "types" field, e.g. `"types": ["typed-factorio/prototype", "typed-factorio/runtime"]`. This will define global variables for _all_ stages selected. With this option, take care that you only use global variables available in the stages the code is run.
112
- 2. Add _only_ the runtime stage to your types, then manually declare other global variables in other stages, only in files that use them. There are types in `"factorio:common"` to allow this:
115
+ 2. Add _only_ the runtime stage, then manually declare other global variables in files that use them. There are types in `"factorio:common"` to allow this:
113
116
  ```ts
114
117
  // -- For the prototype stage --
115
118
  import { PrototypeData, ActiveMods } from "factorio:common"
116
- declare const data: PrtotopyeData
119
+ declare const data: PrototypeData
117
120
  declare const mods: ActiveMods
118
121
  // The `settings` global variable is already declared in the runtime stage.
119
- // However, in the prototype stage _only_ startup settings are available.
122
+ // However, in the prototype stage _only_ `settings.startup` are available.
120
123
  ```
121
124
  ```ts
122
125
  // -- For the settings stage --
123
126
  import { SettingsData, ActiveMods } from "factorio:common"
124
- declare const settings: SettingsData
127
+ declare const data: SettingsData
125
128
  declare const mods: ActiveMods
126
129
  ```
127
- 3. Use a separate `tsconfig.json` for each stage. In each `tsconfig.json`, include only files in that stage in the `"include"` field, e.g. `include: ["src/control.ts"]` for the runtime stage. However, this means you need to run `tstl` separately for each stage, and files shared by multiple stages will be compiled multiple times.
128
-
129
- ### Additional notes
130
-
131
- You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
130
+ 3. Use a separate `tsconfig.json` for each stage. In each `tsconfig.json`, add only files in that stage to the `"include"` field, e.g. `include: ["src/control.ts"]` for the runtime stage. However, this means you need to run `tstl` separately for each stage, and files shared by multiple stages will be compiled multiple times.
132
131
 
133
132
  ## Type features
134
133
 
@@ -149,6 +148,22 @@ Event IDs (`defines.events`) hold type info for their corresponding event type a
149
148
 
150
149
  You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that includes type info.
151
150
 
151
+ ### Optional custominput name checking
152
+ You can optionally enable type-checking for custom input names (for `script.on_event` and `CustomInputPrototype`).
153
+ To do so, specify names by extending the CustomInputNames interface like so:
154
+
155
+ ```ts
156
+ declare module "factorio:common" {
157
+ export interface CustomInputNames {
158
+ "my-custom-input": any
159
+ }
160
+ }
161
+
162
+ script.on_event("my-custom-input", ()=>{}) // type-checked
163
+ ```
164
+
165
+ If not specified, `CustomInputName` defaults to just `string`.
166
+
152
167
  ### Array-like classes
153
168
 
154
169
  Classes that have an index operator, a length operator, and have an array-like structure subclass from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`.
@@ -1,15 +1,16 @@
1
1
  // from https://lua-api.factorio.com/latest/Libraries.html
2
- // last updated for 1.1.35, 1.1.36, 1.1.37
3
2
 
4
3
  /** @noSelfInFile */
5
4
 
6
5
  /**
7
- * Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable `serpent` for
8
- * all mods to use. It allows for easy debugging of tables, because serpent makes it trivial to print them, for example
9
- * by using `serpent.block()`. However, serpent cannot pretty-print LuaObjects such as LuaEntity. The serpent library
10
- * was modified to improve determinism, e.g. comments are turned off by default to avoid returning table addresses.
11
- * Furthermore, two options were added: `refcomment` (true/false/maxlevel) and `tablecomment` (true/false/maxlevel),
12
- * which allow to separately control the self-reference and table value output of the `comment` option.
6
+ * Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable named
7
+ * `serpent` for all mods to use. Its purpose is to allow for easy printing of Lua tables (using `serpent.block()` for
8
+ * example), which can be useful when debugging. It can't pretty-print LuaObjects such as {@link LuaEntity} however.
9
+ *
10
+ * The serpent library was modified for determinism, e.g. comments are turned off by default to avoid returning table
11
+ * addresses. Furthermore, two options were added: `refcomment` (true/false/maxlevel) and `tablecomment`
12
+ * (true/false/maxlevel), which allow to separately control the self-reference and table value output of the comment
13
+ * option.
13
14
  */
14
15
  declare namespace serpent {
15
16
  /** @noSelf */
package/common/types.d.ts CHANGED
@@ -71,4 +71,32 @@ declare module "factorio:common" {
71
71
  * ```
72
72
  */
73
73
  export type SettingsData = DataGlobal<SettingsPrototypeMap>
74
+
75
+ /**
76
+ * You can optionally extend this interface to provide type checking and autocompletion for custom input names, like so:
77
+ * ```ts
78
+ * declare module "factorio:common" {
79
+ * export interface CustomInputNames {
80
+ * "my-custom-event": true
81
+ * }
82
+ * }
83
+ *
84
+ * // this enables type checking for the following:
85
+ * script.on_event("my-custom-event", ...)
86
+ *
87
+ * data.extend<CustomInputPrototype>([{
88
+ * type: "custom-input",
89
+ * name: "my-custom-event", // type checked
90
+ * }])
91
+ * ```
92
+ * @see CustomInputName
93
+ */
94
+ export interface CustomInputNames {}
95
+
96
+ /**
97
+ * All custom event names. See {@link CustomInputNames}.
98
+ *
99
+ * If none are specified, this is just `string`.
100
+ */
101
+ export type CustomInputName = [keyof CustomInputNames] extends [never] ? string : keyof CustomInputNames
74
102
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typed-factorio",
3
- "version": "2.5.2",
3
+ "version": "2.6.0",
4
4
  "description": "Featureful typescript definitions for the Factorio modding api.",
5
5
  "keywords": [
6
6
  "factorio",
@@ -9,6 +9,7 @@
9
9
  "tstl"
10
10
  ],
11
11
  "repository": "https://github.com/GlassBricks/typed-factorio",
12
+ "homepage": "https://github.com/GlassBricks/typed-factorio#readme",
12
13
  "license": "MIT",
13
14
  "files": [
14
15
  "**/*.d.ts",
@@ -16,7 +17,7 @@
16
17
  "!generator/**/*"
17
18
  ],
18
19
  "type": "module",
19
- "homepage": "https://github.com/GlassBricks/typed-factorio#readme",
20
+ "packageManager": "npm@9.5.0",
20
21
  "scripts": {
21
22
  "generate": "ts-node --esm -P generator/tsconfig.json generator/main.ts",
22
23
  "generate-no-format": "ts-node --swc -T --esm -P generator/tsconfig.json generator/main.ts --no-format",
@@ -34,25 +35,25 @@
34
35
  "typescript-to-lua": "^1.10.0"
35
36
  },
36
37
  "devDependencies": {
37
- "@swc/core": "^1.3.82",
38
- "@types/download": "^8.0.2",
39
- "@types/node": "^20.5.9",
40
- "@typescript-eslint/eslint-plugin": "^6.5.0",
41
- "@typescript-eslint/parser": "^6.5.0",
38
+ "@swc/core": "^1.3.101",
39
+ "@types/download": "^8.0.5",
40
+ "@types/node": "^20.10.5",
41
+ "@typescript-eslint/eslint-plugin": "^6.16.0",
42
+ "@typescript-eslint/parser": "^6.16.0",
42
43
  "chalk": "^5.3.0",
43
44
  "download": "^8.0.0",
44
- "eslint": "~8.48.0",
45
- "eslint-config-prettier": "^9.0.0",
46
- "eslint-import-resolver-typescript": "^3.6.0",
45
+ "eslint": "~8.56.0",
46
+ "eslint-config-prettier": "^9.1.0",
47
+ "eslint-import-resolver-typescript": "^3.6.1",
47
48
  "eslint-plugin-eslint-comments": "^3.2.0",
48
- "eslint-plugin-import": "^2.28.1",
49
+ "eslint-plugin-import": "^2.29.1",
49
50
  "eslint-plugin-node": "^11.1.0",
50
- "eslint-plugin-prettier": "^5.0.0",
51
+ "eslint-plugin-prettier": "^5.1.2",
51
52
  "lua-types": "^2.13.1",
52
- "prettier": "^3.0.3",
53
- "rimraf": "^5.0.1",
54
- "ts-node": "^10.9.1",
53
+ "prettier": "^3.1.1",
54
+ "rimraf": "^5.0.5",
55
+ "ts-node": "^10.9.2",
55
56
  "typescript": "~5.2.2",
56
- "typescript-to-lua": "^1.19.0"
57
+ "typescript-to-lua": "^1.22.0"
57
58
  }
58
59
  }