typed-factorio 3.18.0 → 3.19.1

package/README.md

@@ -4,18 +4,17 @@
 
 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 are as complete as possible.
-The generator uses both the Factorio api docs JSON and manually defined additions.
+This project aims to provide type definitions that are as complete as possible.
 
 ## Installation
 
 To use in your [TypescriptToLua](https://typescripttolua.github.io/) project:
 
-1. Install this package: `npm install typed-factorio`
+1. Install this package: `npm install --save-dev typed-factorio`
 
-   - Note: When types are updated for a new factorio version, you will need to update this package.
+   > Note: When types are updated for a new factorio version, you will need to update this package.
 
-2. Add 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 [Factorio stages](https://lua-api.factorio.com/latest) used to your `tsconfig.json` under `compilerOptions > types`.
    The available stages are `"typed-factorio/settings"`, `"typed-factorio/prototype"`, and `"typed-factorio/runtime"`.
 
 Example:
@@ -29,16 +28,16 @@ Example:
 }
 ```
 
-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-loading-stages-in-the-same-project) for more info.
+Each stage will define the global variables used in that stage.
+You can include multiple stages, but there are some caveats. For more info, see [Using multiple stages in the same project](#using-multiple-loading-stages-in-the-same-project).
 
 ## Usage notes
 
-Here are some notes on using the types:
+Some more info on using 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"`:
+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
 import { BoolSettingDefinition } from "factorio:settings"
@@ -46,14 +45,39 @@ import { ItemPrototype } from "factorio:prototype"
 import { LuaEntity } from "factorio:runtime"
 ```
 
-You can also include just `"typed-factorio"` in your `types` field. This will include only global variables available to _all_ stages.
+You can also include just `"typed-factorio"` in your tsconfig's `types`. This will define only global variables that are available to _all_ stages.
 
-### `data.extend()` types
+### The `storage` table
+
+The `storage` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can define it yourself:
+
+- Add `declare const storage: <Your type>` in a `.d.ts` file. Make sure this file is included by your tsconfig!
+- Add `declare global { const storage: <Your type> }` in a `.ts` file included in your project.
+- Add `declare const storage: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
+
+### Factorio lualib modules
+
+There are types for the following [Factorio lualib modules](https://github.com/wube/factorio-data/tree/master/core/lualib):
+
+- `util`
+- `mod-gui`
+
+These can be imported as modules:
+
+```ts
+import * as util from "util"
+
+const foo = util.copy(bar)
+```
+
+If you wish to see types for more lualib modules, feel free to open an issue or pull request.
+
+### Types for `data.extend()`
 
 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:
+To get full strict type checking, you can use one of the following methods:
 
 ```ts
 // Use `satisfies` to check types:
@@ -69,7 +93,7 @@ data.extend([
   } satisfies ItemPrototype,
 ])
 
-// List types as a type argument to `extend`:
+// List types used as a type argument to `extend`:
 data.extend<AmmoCategory | ItemPrototype>([
   {
     type: "ammo-category",
@@ -92,31 +116,6 @@ const barItem: ItemPrototype = {
 data.extend([fooCategory, barItem])
 ```
 
-### Factorio lualib modules
-
-There are types for the following [Factorio lualib modules](https://github.com/wube/factorio-data/tree/master/core/lualib):
-
-- `util`
-- `mod-gui`
-
-These can be imported as modules:
-
-```ts
-import * as util from "util"
-
-const foo = util.copy(bar)
-```
-
-If you wish to see types for more lualib modules, feel free to open an issue or pull request.
-
-### The `storage` table
-
-The `storage` table (in the runtime stage) can have any shape, so it is not defined here. Instead, you can define it yourself:
-
-- Add `declare const storage: <Your type>` in a `.d.ts` file. Make sure this file is included by your tsconfig!
-- Add `declare global { const storage: <Your type> }` in a `.ts` file included in your project.
-- Add `declare const storage: {...}` to each file where needed. This way, you can define only properties that each file specifically uses.
-
 ## Using multiple loading stages in the same project
 
 Every Factorio loading stage declares different global variables.
@@ -157,11 +156,11 @@ Parameter tables with variants (having "additional attributes can be specified d
 
 ### Events
 
-Event IDs (`defines.events`) hold type info for their corresponding event type and filters, which is used by various methods in `script`.
+Event IDs (`defines.events`) hold type info on their corresponding event data type and filters, which is used by various methods in `script`.
 
-You can pass an event data type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that includes type info.
+You can pass a type parameter to `script.generate_event_name<T>()`, and it will return a `CustomEventId` that includes type info.
 
-### Optional custominput name checking
+### 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:
@@ -174,27 +173,29 @@ declare module "factorio:common" {
 }
 
 script.on_event("my-custom-input", () => {}) // type-checked
+// script.on_event("my-customm-input", () => {}) // mispelled, will error
 ```
 
-If not specified, `CustomInputName` defaults to just `string`.
+The type `CustomInputName` (not plural) will be a union of strings, for all custom input names.
+If not specified like above, `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`.
+A few classes that have an index operator, a length operator, and have an array-like structure, which will subclass from `(Readonly)Array`. These are `LuaInventory`, `LuaFluidBox`, `LuaTransportLine`.
 This allows you to use these classes like arrays, e.g. having array methods and `.length` translating to the lua length operator. However, this means like typescript arrays, they are **0-indexed, not 1-indexed**.
 
 ### Read and write variants
 
-For concepts that can take a table or array form, the main type (e.g. `MapPosition`) defines the table form, and an `Array` suffix (e.g. `MapPositionArray`) defines the array form.
-Concepts in a "read" position are in table form, and concepts in a "write" position may be either in table or array form (e.g. `MapPosition | MapPositionArray`).
+For concepts that can take a table-or-array form, the main type (e.g. `MapPosition`) defines the table form, and a type suffixed with `Array` (e.g. `MapPositionArray`) defines the array form.
+Concepts in a "read" position are in table form. Concepts in a "write" position may be in either table or array form (e.g. `MapPosition | MapPositionArray`).
 Concepts that include table-or-array concepts may have an additional `Write` variant (e.g. `ScriptArea`, `ScriptAreaWrite`).
 
 ### Classes with subclasses
 
-Some classes have attributes that only work for particular subclasses. For these classes (e.g. `LuaEntity`) there are specific types that you can _optionally_ use:
+Some classes have attributes that only work for particular subclasses (e.g. LuaEntity.recipe only works if this is crafting-machine). For these classes, there are more specific types you can _optionally_ use:
 
 - A "Base" type (e.g. `BaseEntity`) which contains only members usable by all subclasses
-- Multiple subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass.
+- Subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass.
 
 The original class name (e.g. `LuaEntity`) contains attributes for _all_ subclasses.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typed-factorio",
-  "version": "3.18.0",
+  "version": "3.19.1",
   "description": "Featureful typescript definitions for the Factorio modding api.",
   "keywords": [
     "factorio",
@@ -62,5 +62,5 @@
     "typescript": "~5.4.2",
     "typescript-to-lua": "^1.25.0"
   },
-  "factorioVersion": "2.0.43"
+  "factorioVersion": "2.0.44"
 }