typed-factorio 2.5.2 → 2.7.0

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,7 +42,9 @@ 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.
@@ -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

@@ -1,7 +1,7 @@
 /** @noResolution */
 declare module "factorio:common" {
   import { ModSetting } from "factorio:runtime"
-  import { PrototypeMap as PrototypePrototypeMap } from "factorio:prototype"
+  import { Data } from "factorio:prototype"
   import { PrototypeMap as SettingsPrototypeMap } from "factorio:settings"
   /**
    * A type map of type name -> prototype type.
@@ -16,21 +16,23 @@ declare module "factorio:common" {
     readonly name: string
   }
 
+  /**
+   * See {@link Data} for documentation.
+   */
   export interface DataGlobal<M = GlobalPrototypeMap> {
     /**
      * A table of the already added prototypes.
      * Indexed by prototype type, then by prototype name.
      */
     readonly raw: {
-      readonly [T in keyof M]: {
-        readonly [name in string]?: M[T]
+      readonly [type in keyof M]: {
+        readonly [name in string]?: M[type]
       }
     }
 
-    /**
-     * Add additional prototypes.
-     */
     extend<P extends AnyPrototype<M>>(prototypes: readonly P[]): void
+
+    is_demo: boolean
   }
 
   export interface SettingsGlobal {
@@ -57,7 +59,7 @@ declare module "factorio:common" {
    * data.extend(...)
    * ```
    */
-  export type PrototypeData = DataGlobal<PrototypePrototypeMap>
+  export type PrototypeData = Data
 
   /**
    * Represents a `data` global variable for the settings stage.
@@ -71,4 +73,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.2",
+  "version": "2.7.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"
   }
 }