Merge pull request #1072 from y-lohse/jz/better-typings

Release 2.2.5

.eslintrc.js

@@ -15,7 +15,6 @@ module.exports = {
   },
   plugins: [
     "@typescript-eslint",
-    "@typescript-eslint/tslint",
     "import",
     "jsdoc",
     "prefer-arrow",
@@ -27,17 +26,21 @@ module.exports = {
     "@typescript-eslint/no-namespace": "off",
     "@typescript-eslint/explicit-module-boundary-types": "off",
     "@typescript-eslint/no-unsafe-assignment": "off",
+    "@typescript-eslint/no-unsafe-argument": "off",
     "@typescript-eslint/no-unsafe-call": "off",
     "@typescript-eslint/no-unsafe-member-access": "off",
     "@typescript-eslint/no-unsafe-return": "off",
     "@typescript-eslint/restrict-plus-operands": "off",
     "@typescript-eslint/no-non-null-assertion": "off",
     "@typescript-eslint/restrict-template-expressions": "off",
+    "@typescript-eslint/no-base-to-string": "off",
     "@typescript-eslint/ban-types": "off",
     "@typescript-eslint/unbound-method": "off",
     "@typescript-eslint/no-this-alias": "off",
     "@typescript-eslint/no-inferrable-types": "off",
     "@typescript-eslint/no-unnecessary-type-assertion": "off",
+    "@typescript-eslint/no-redundant-type-constituents": "off",
+    "@typescript-eslint/no-unsafe-enum-comparison": "off",
     "prefer-const": "off",
     "prefer-spread": "off",
     "prefer-rest-params": "off",

.github/workflows/checks.yml

@@ -17,9 +17,9 @@ jobs:
         run: npm install
       - name: Install codecov
         run: npm install codecov
-      - name: Lint
-        run: npm run lint
       - name: Build
         run: npm run build
       - name: tests
         run: npm run test
+      - name: Lint
+        run: npm run lint

.gitignore

@@ -1,8 +1,11 @@
 /engine/
 /compiler/
 dist/
+bin/
 test/stories/
 /tests/specs/
+/ink.js
+/ink.js.map
 
 # Logs
 logs

.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "trailingComma": "es5"
+}

README.md

@@ -71,7 +71,18 @@ You can find some boilerplate code for node.js [here](https://github.com/y-lohse
 
 ### Loading inkjs
 
-Require the module: `var Story = require('inkjs').Story;`.
+#### require
+
+You can require the module: 
+```javascript 
+var Story = require('inkjs').Story;
+```
+
+#### import
+You can use import style: 
+```javascript
+import { Story } from 'inkjs';
+`
 
 ### Loading a json file
 
@@ -135,45 +146,28 @@ var result = EvaluateFunction('my_ink_function', ['arg1', 'arg2'], true);
 // result.output is the text that was written to the output while the function was evaluated
 ```
 
-## Using TypeScript
-
-As this library is a port from C#, it requires a less standard way to assign the `Story` class, including all other classes, to a variable:
-
-```ts
-import { Story } from 'inkjs';
-import { Compiler } from 'inkjs/full'; // Compiler is not provided in the default inkjs package
-
-let story: InstanceType<typeof Story>;
-let compiler: InstanceType<typeof Compiler>;
-```
-
-Further, to minimize the verbose assignment, you can also create aliases in your project:
-
-```ts
-import { Story, Compiler } from 'inkjs/full'; // Story is also provided in the "full" subpackage.
-
-export type InkStory = InstanceType<typeof Story>;
-export type InkCompiler= InstanceType<typeof Compiler>;
-```
-
 ## Compiler
 
 ### inkjs-compiler.js
 
 ```shell
 $ node inkjs-compiler.js -h
 
-Usage: inkjs-compiler <options> <ink file>
+Usage: inkjs-compiler <options> <ink or json file>
    -o <filename>:   Output file name
    -c:              Count all visits to knots, stitches and weave points, not
                     just those referenced by TURNS_SINCE and read counts.
-   -p:              Play mode
+   -p:              Play mode (automatic if a json file is passed as argument)
 
 ```
 
+If you install the package globally it is available as the `inkjs-compiler` command.  
+Alternatively, you can call it using `npx inkjs`
+
 ### online compiler
 
 ```javascript
+const inkjs = require("inkjs/full") //the `full` submodule contains the Compiler
 const story = new inkjs.Compiler(`Hello World`).Compile();
 // story is an inkjs.Story that can be played right away
 
@@ -187,6 +181,28 @@ You can use this in combination with [Webpack and TypeScript](docs/working-with-
 
 See [Differences with the C# Compiler](docs/compiler-differences.md).
 
+## Using TypeScript
+
+Inkjs is also packaged to be usable with typescript imports, the main classes (`Story`, `InkList`, `Compiler`) are available under the `/types`submodule.
+
+```ts
+import { Story, Compiler } from 'inkjs/types'; // shortcut
+
+let story: Story;
+let compiler: Compiler;
+```
+
+It is also possible to import deeply nested classes if needed
+
+```ts
+import { Story } from 'inkjs/engine/Story';
+import { Compiler } from 'inkjs/compiler/Compiler';
+
+import { Choice } from 'inkjs/engine/Choice'
+import { Identifier } from 'inkjs/compiler/Parser/ParsedHierarchy/Identifier';
+
+```
+
 ## Compatibility table
 
 | _inklecate_ version | _inkjs_ version | _json_ version |
@@ -207,4 +223,4 @@ See [Differences with the C# Compiler](docs/compiler-differences.md).
 |        0.8.3        | 1.10.0 – 1.10.5 |                |
 |        0.9.0        |     1.11.0      |       19       |
 |        1.0.0        |  2.0.0 - 2.1.0  |       20       |
-|        1.1.1        |      2.2.0      |       21       |
+|        1.1.1        |      2.2.*      |       21       |

docs/compiler-differences.md

@@ -16,15 +16,15 @@ Inkjs provides 2 file handlers :
 * A POSIX file handler : delivered as a separate `inkjs-full-posixhandler.js` file that must be included/required : similar to the one used in the C# compiler that will look for files in folders. Example when installing the package from npm :
 
 ```javascript
-var Inkjs = require('inkjs');
+var inkjs = require('inkjs/full');
 var { PosixFileHandler } = require('inkjs/compiler/FileHandler/PosixFileHandler');
 
 const inkFile = fs.readFileSync(`${PATH_TO_STORY_FOLDER}/main.ink`, 'UTF-8').replace(/^\uFEFF/, '');
 const fileHandler = new PosixFileHandler(`${PATH_TO_STORY_FOLDER}/`);
 const errorHandler = (message, errorType) => {
    console.log(message + "\n");
 }
-const story = new Inkjs.Compiler(inkFile, {fileHandler, errorHandler}).Compile();
+const story = new inkjs.Compiler(inkFile, {fileHandler, errorHandler}).Compile();
 //story.Continue()
 ```
 

docs/working-with-typescript-and-webpack.md

@@ -22,11 +22,11 @@ rules: [
 
 We can then `import` (or `require`) the ink file and compile it.
 
-```typescript
-import * as Inkjs from 'inkjs';
+```javascript
+import { Compiler } from 'inkjs/full';
 import data from '../assets/myStory.ink';
 
-const inkStory = new Inkjs.Compiler(data).Compile();
+const inkStory = new Compiler(data).Compile();
 ```
 
 If you are working in JavaScript, then that is all you need.

ink.d.mts

@@ -1,41 +1,4 @@
-import { Story, InkList } from './engine/Story'
-import { Compiler } from './compiler/Compiler'
-import { CompilerOptions } from './compiler/CompilerOptions'
-import { PosixFileHandler } from './compiler/FileHandler/PosixFileHandler'
-import { JsonFileHandler } from './compiler/FileHandler/JsonFileHandler'
-
-declare interface Inkjs {
-    /**
-     * A Story is the core class that represents a complete Ink narrative, and
-     * manages runtime evaluation and state.
-     */
-    Story: typeof Story
-
-    /**
-     * The underlying type for a list item in Ink.
-     */
-    InkList: typeof InkList
-
-    /**
-     * Compiles Ink stories from source.
-     */
-    Compiler: typeof Compiler
-
-    /**
-     * Metadata options for a compiler pass.
-     */
-    CompilerOptions: typeof CompilerOptions
-
-    /**
-     * Resolves and loads Ink sources from a POSIX filesystem.
-     */
-    PosixFileHandler: typeof PosixFileHandler
-
-    /**
-     * Resolves and loads Ink sources from a JSON hierarchy.
-     */
-    JsonFileHandler: typeof JsonFileHandler
-}
-
-declare let inkjs: Inkjs
-export default inkjs
+export { Story, InkList } from "./engine/Story";
+export { Compiler, CompilerOptions } from "./compiler/Compiler";
+export { PosixFileHandler } from "./compiler/FileHandler/PosixFileHandler";
+export { JsonFileHandler } from "./compiler/FileHandler/JsonFileHandler";

ink.d.ts

@@ -1,41 +1,4 @@
-import { Story, InkList } from './engine/Story'
-import { Compiler } from './compiler/Compiler'
-import { CompilerOptions } from './compiler/CompilerOptions'
-import { PosixFileHandler } from './compiler/FileHandler/PosixFileHandler'
-import { JsonFileHandler } from './compiler/FileHandler/JsonFileHandler'
-
-declare interface Inkjs {
-    /**
-     * A Story is the core class that represents a complete Ink narrative, and
-     * manages runtime evaluation and state.
-     */
-    Story: typeof Story
-
-    /**
-     * The underlying type for a list item in Ink.
-     */
-    InkList: typeof InkList
-
-    /**
-     * Compiles Ink stories from source.
-     */
-    Compiler: typeof Compiler
-
-    /**
-     * Metadata options for a compiler pass.
-     */
-    CompilerOptions: typeof CompilerOptions
-
-    /**
-     * Resolves and loads Ink sources from a POSIX filesystem.
-     */
-    PosixFileHandler: typeof PosixFileHandler
-
-    /**
-     * Resolves and loads Ink sources from a JSON hierarchy.
-     */
-    JsonFileHandler: typeof JsonFileHandler
-}
-
-declare let inkjs: Inkjs
-export default inkjs
+export { Story, InkList } from "./engine/Story";
+export { Compiler, CompilerOptions } from "./compiler/Compiler";
+export { PosixFileHandler } from "./compiler/FileHandler/PosixFileHandler";
+export { JsonFileHandler } from "./compiler/FileHandler/JsonFileHandler";