typed-factorio 2.5.1 → 2.6.0

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,8 +1,8 @@
 # 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/).
+Complete and featureful typescript definitions for the Factorio modding lua API, for use 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 project aims to provide type definitions are as complete as possible.
 The generator uses both the Factorio api docs JSON and manually defined additions.
 
 ## Installation
@@ -10,14 +10,15 @@ The generator uses both the Factorio api docs JSON and manually defined addition
 To use in your [TypescriptToLua](https://typescripttolua.github.io/) project:
 
 1. Install this package: `npm install typed-factorio`
-    - Note: When types are updated for a new factorio version, you will need to the npm package to get the latest types.
+    - Note: When types are updated for a new factorio version, you will need to update this package.
 
-2. Add the types for the [stages](https://lua-api.factorio.com/1.1.89/index.html) used to `tsconfig.json > compilerOptions > types`.
+2. Add types for the [stages](https://lua-api.factorio.com/1.1.89/index.html) used to `tsconfig.json > compilerOptions > types`.
    The available stages are `"typed-factorio/settings"`, `"typed-factorio/prototype"`, and `"typed-factorio/runtime"`.
 
 Example:
 
 ```diff
+// in tsconfig.json
 {
   "compilerOptions": {
 +    "types": [ "typed-factorio/runtime" ]
@@ -25,14 +26,14 @@ Example:
 }
 ```
 
-The stages selected will control the global variables defined.
-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.
+The stages used will select the global variables defined.
+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.
 
-## Usage
+## Usage notes
 
-Global variables will be defined for the stage(s) selected.
+Here are some notes on using the types:
 
-### Types
+### Types for other stages
 
 No matter which stage(s) are selected, _type_ definitions for all stages are available in the modules `"factorio:settings"`, `"factorio:prototype"`, and `"factorio:runtime"`: 
 ```ts
@@ -41,13 +42,15 @@ import { ItemPrototype } from "factorio:prototype"
 import { LuaEntity } from "factorio:runtime"
 ```
 
-### `data.extend()`
+You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
+
+### `data.extend()` types
 In the settings and prototype stages, the `data` global variable is available. 
 
 For [performance reasons](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-base-types-over-unions), `data.extend()` is by default loosely typed.
 To get full type checking, you can use specific types in one of the following ways:
 ```ts
-// Use `satisfies` on types to check types
+// Use `satisfies` to check types:
 data.extend([
    {
      type: "ammo-category",
@@ -98,37 +101,33 @@ If you wish to see types for more lualib modules, feel free to open an issue or
 
 ### The `global` table
 
-The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can:
+The `global` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can define it yourself:
 
-- 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 file where needed. This way, you can define only properties that each file specifically uses.
+- Add `declare const global: <Your type>` in a `.d.ts` file included in your project, to apply it project-wide.
+- Add `declare const global: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
 
 ## Using multiple stages in the same project
 
 Every Factorio loading stage declares different global variables.
-To add types for multiple Factorio stages, you have a few options, with different pros and cons:
+To add types for multiple Factorio stages, you have a few options:
 
 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.
-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:
+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:
    ```ts
    // -- For the prototype stage --
    import { PrototypeData, ActiveMods } from "factorio:common"
-   declare const data: PrtotopyeData
+   declare const data: PrototypeData
    declare const mods: ActiveMods
    // The `settings` global variable is already declared in the runtime stage.
-   // However, in the prototype stage _only_ startup settings are available.
+   // However, in the prototype stage _only_ `settings.startup` are available.
    ```
    ```ts
    // -- For the settings stage --
    import { SettingsData, ActiveMods } from "factorio:common"
-   declare const settings: SettingsData
+   declare const data: SettingsData
    declare const mods: ActiveMods
    ```
-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.
-
-### Additional notes
-
-You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
+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.
 
 ## Type features
 
@@ -149,6 +148,22 @@ Event IDs (`defines.events`) hold type info for their corresponding event type a
 
 You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that includes type info.
 
+### Optional custominput name checking
+You can optionally enable type-checking for custom input names (for `script.on_event` and `CustomInputPrototype`).
+To do so, specify names by extending the CustomInputNames interface like so:
+
+```ts
+declare module "factorio:common" {
+  export interface CustomInputNames {
+    "my-custom-input": any
+  }
+}
+
+script.on_event("my-custom-input", ()=>{}) // type-checked
+```
+
+If not specified, `CustomInputName` defaults to just `string`.
+
 ### Array-like classes
 
 Classes that have an index operator, a length operator, and have an array-like structure subclass from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`.

package/common/serpent.d.ts

@@ -1,15 +1,16 @@
 // from https://lua-api.factorio.com/latest/Libraries.html
-// last updated for 1.1.35, 1.1.36, 1.1.37
 
 /** @noSelfInFile */
 
 /**
- * Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable `serpent` for
- * all mods to use. It allows for easy debugging of tables, because serpent makes it trivial to print them, for example
- * by using `serpent.block()`. However, serpent cannot pretty-print LuaObjects such as LuaEntity. The serpent library
- * was modified to improve determinism, e.g. comments are turned off by default to avoid returning table addresses.
- * Furthermore, two options were added: `refcomment` (true/false/maxlevel) and `tablecomment` (true/false/maxlevel),
- * which allow to separately control the self-reference and table value output of the `comment` option.
+ * Factorio provides the {@link https://github.com/pkulchenko/serpent serpent library} as a global variable named
+ * `serpent` for all mods to use. Its purpose is to allow for easy printing of Lua tables (using `serpent.block()` for
+ * example), which can be useful when debugging. It can't pretty-print LuaObjects such as {@link LuaEntity} however.
+ *
+ * The serpent library was modified for determinism, e.g. comments are turned off by default to avoid returning table
+ * addresses. Furthermore, two options were added: `refcomment` (true/false/maxlevel) and `tablecomment`
+ * (true/false/maxlevel), which allow to separately control the self-reference and table value output of the comment
+ * option.
  */
 declare namespace serpent {
   /** @noSelf */

package/common/types.d.ts

@@ -71,4 +71,32 @@ declare module "factorio:common" {
    * ```
    */
   export type SettingsData = DataGlobal<SettingsPrototypeMap>
+
+  /**
+   * You can optionally extend this interface to provide type checking and autocompletion for custom input names, like so:
+   * ```ts
+   * declare module "factorio:common" {
+   *    export interface CustomInputNames {
+   *        "my-custom-event": true
+   *    }
+   * }
+   *
+   * // this enables type checking for the following:
+   * script.on_event("my-custom-event", ...)
+   *
+   * data.extend<CustomInputPrototype>([{
+   *   type: "custom-input",
+   *   name: "my-custom-event", // type checked
+   * }])
+   * ```
+   * @see CustomInputName
+   */
+  export interface CustomInputNames {}
+
+  /**
+   * All custom event names. See {@link CustomInputNames}.
+   *
+   * If none are specified, this is just `string`.
+   */
+  export type CustomInputName = [keyof CustomInputNames] extends [never] ? string : keyof CustomInputNames
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typed-factorio",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Featureful typescript definitions for the Factorio modding api.",
   "keywords": [
     "factorio",
@@ -9,6 +9,7 @@
     "tstl"
   ],
   "repository": "https://github.com/GlassBricks/typed-factorio",
+  "homepage": "https://github.com/GlassBricks/typed-factorio#readme",
   "license": "MIT",
   "files": [
     "**/*.d.ts",
@@ -16,7 +17,7 @@
     "!generator/**/*"
   ],
   "type": "module",
-  "homepage": "https://github.com/GlassBricks/typed-factorio#readme",
+  "packageManager": "npm@9.5.0",
   "scripts": {
     "generate": "ts-node --esm -P generator/tsconfig.json generator/main.ts",
     "generate-no-format": "ts-node --swc -T --esm -P generator/tsconfig.json generator/main.ts --no-format",
@@ -34,25 +35,25 @@
     "typescript-to-lua": "^1.10.0"
   },
   "devDependencies": {
-    "@swc/core": "^1.3.82",
-    "@types/download": "^8.0.2",
-    "@types/node": "^20.5.9",
-    "@typescript-eslint/eslint-plugin": "^6.5.0",
-    "@typescript-eslint/parser": "^6.5.0",
+    "@swc/core": "^1.3.101",
+    "@types/download": "^8.0.5",
+    "@types/node": "^20.10.5",
+    "@typescript-eslint/eslint-plugin": "^6.16.0",
+    "@typescript-eslint/parser": "^6.16.0",
     "chalk": "^5.3.0",
     "download": "^8.0.0",
-    "eslint": "~8.48.0",
-    "eslint-config-prettier": "^9.0.0",
-    "eslint-import-resolver-typescript": "^3.6.0",
+    "eslint": "~8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-import": "^2.28.1",
+    "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-prettier": "^5.0.0",
+    "eslint-plugin-prettier": "^5.1.2",
     "lua-types": "^2.13.1",
-    "prettier": "^3.0.3",
-    "rimraf": "^5.0.1",
-    "ts-node": "^10.9.1",
+    "prettier": "^3.1.1",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.2",
     "typescript": "~5.2.2",
-    "typescript-to-lua": "^1.19.0"
+    "typescript-to-lua": "^1.22.0"
   }
 }