typed-factorio 0.15.0 → 0.16.0

package/Changelog.md

@@ -1,3 +1,8 @@
+# v0.16.0
+
+- `LuaCustomTable` can be iterated on in a for-of loop directly (without using `pairs`). This requires TSTL v1.3.0 or later.
+- TSTL dependency minimum version is now v1.3.0.
+
 # v0.15.0
 
 - Table or array concepts are now declared in table form wherever it is an "read" position.
@@ -7,7 +12,7 @@
 - Arrays which are known to be in a "write" only form (e.g. method parameters) now are marked readonly. This means you can now pass readonly-only arrays to these methods.
 - `MapPosition` is now a table or array concept.
 - Classes with subclasses are now declared with all properties, instead of an intersection of subclasses (reversion)
-- Subclass specializations are added for some missing classes
+- Subclass specializations added for some missing classes
 
 # v0.14.1
 

package/README.md

@@ -73,7 +73,7 @@ The `global` table is just a lua table which can have any shape the mod desires,
 
 Typed-factorio has 100% complete types for the runtime stage. Description-only concepts and some not documented types are filled in manually.
 
-Here are some details on particular type features in the definitions:
+Here are some details on particular type features:
 
 ### Lua features
 
@@ -96,6 +96,7 @@ The type for a specific variant is prefixed with the variant name, or with "Othe
 ### Types with subclasses
 
 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:
+
 - a "Base" type, e.g. `BaseEntity`, which only contains members usable by all subclasses
 - individual subclass types, e.g. `CraftingMachineEntity`, which extends the base type with members specific to that subclass
 
@@ -111,9 +112,13 @@ You can pass a type parameter to `script.generate_event_name<T>()`, and it will
 
 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**.
 
-### Table or array types
+### Table or array types, and "Read" concepts
+
+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.
+
+Table-or-array types will appear in the Table form when known to be in a read position. This also applies to other concepts/complex types that have table-or-array attributes.
 
-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.
+For some concepts, there is also a special form for when the concept is used in a "read" position, where all table-or-array types are in Table form. These types are suffixed with `Read`, e.g. `ScriptPositionRead`.
 
 ### LuaGuiElement
 

package/generated/classes.d.ts

@@ -1939,7 +1939,7 @@ interface LuaCustomInputPrototype {
   help(): string
 }
 
-type CustomTableIndex<K extends keyof any, V>
+type CustomTableIndex<K extends string | number, V>
 /**
  * Access an element of this custom table.
  *
@@ -2012,7 +2012,9 @@ interface LuaCustomTableMembers {
  *   global.p = game.players  -- This has high potential to make the game unsaveable
  *   ```
  */
-type LuaCustomTable<K extends keyof any, V> = LuaCustomTableMembers & CustomTableIndex<K, V>
+type LuaCustomTable<K extends string | number, V> = LuaCustomTableMembers &
+  CustomTableIndex<K, V> &
+  LuaPairsIterable<[number] extends [K] ? number : K, V>
 
 /**
  * Prototype of a damage.

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "typed-factorio",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Featureful typescript definitions for the the Factorio modding lua api.",
   "keywords": [
-    "factorio", "types", "typescript-to-lua", "tstl"
+    "factorio",
+    "types",
+    "typescript-to-lua",
+    "tstl"
   ],
   "repository": "https://github.com/GlassBricks/typed-factorio",
   "license": "MIT",
@@ -25,7 +28,7 @@
   },
   "peerDependencies": {
     "lua-types": "^2.11.0",
-    "typescript-to-lua": "^1.0.0"
+    "typescript-to-lua": "^1.3.1"
   },
   "devDependencies": {
     "@types/jest": "^27.0.3",
@@ -50,6 +53,6 @@
     "ts-jest": "^27.1.0",
     "ts-node": "^10.4.0",
     "typescript": "4.5.2",
-    "typescript-to-lua": "^1.2.0"
+    "typescript-to-lua": "^1.3.1"
   }
 }

package/runtime/pairs.d.ts

@@ -1,13 +1,14 @@
 /** @noSelfInFile */
 
-/** Iterating with `pairs` will only iterate the array part of a {@link LuaCustomTable}. */
-declare function pairs<V>(table: LuaCustomTable<number | string, V>): LuaIterable<LuaMultiReturn<[number, V]>>
-
-declare function pairs<K extends keyof any, V>(table: LuaCustomTable<K, V>): LuaIterable<LuaMultiReturn<[K, V]>>
-
 /**
- * {@link LuaCustomTable} cannot be iterated with `ipairs`. Use `pairs` instead.
+ * Iterating with `pairs` will only iterate the array part of a {@link LuaCustomTable}.
  *
- * @deprecated
+ * **Note**: you can also iterate on a LuaCustomTable directly without using `pairs`, e.g. `for(const [k, v] of table)`.
  */
+declare function pairs<V>(table: LuaCustomTable<number | string, V>): LuaIterable<LuaMultiReturn<[number, V]>>
+
+/** **Note**: you can also iterate on a LuaCustomTable directly without using `pairs`, e.g. `for(const [k, v] of table)`. */
+declare function pairs<K extends number | string, V>(table: LuaCustomTable<K, V>): LuaIterable<LuaMultiReturn<[K, V]>>
+
+/** @deprecated {@link LuaCustomTable} cannot be iterated with `ipairs`; Use {@link pairs} instead. */
 declare function ipairs(table: LuaCustomTable<any, any>): never