feat: add typings for neutrino config and api

packages/neutrino/package.json

@@ -3,6 +3,7 @@
   "version": "9.0.0-rc.3",
   "description": "Create and build JS applications with managed configurations",
   "main": "index.js",
+  "typings": "types/index.d.ts",
   "bin": {
     "neutrino": "bin/neutrino.js"
   },
@@ -17,7 +18,8 @@
   "homepage": "https://neutrinojs.org",
   "bugs": "https://github.com/neutrinojs/neutrino/issues",
   "scripts": {
-    "test": "ava test"
+    "test": "ava test",
+    "test:types": "tsc -p ./types/test/tsconfig.json"
   },
   "engines": {
     "node": "^8.10 || >=10",
@@ -29,5 +31,8 @@
     "semver": "^6.3.0",
     "webpack-chain": "^6.0.0",
     "yargs-parser": "^14.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^3.6.3"
   }
 }

packages/neutrino/types/index.d.ts

@@ -0,0 +1,39 @@
+import * as webpack from "webpack";
+import * as Config from "webpack-chain";
+
+export = Neutrino;
+
+declare class Neutrino<O extends Neutrino.Options = Neutrino.Options> {
+  constructor(options?: O);
+  options: O;
+  config: Config;
+  use(middleware: Neutrino.Middleware<O, any>): void;
+  register(name: string, handler: Neutrino.OutputHandler<any, any, any>): void;
+  regexFromExtensions(extensions?: string[]): RegExp;
+  webpack(): webpack.Configuration;
+  inspect(): void;
+}
+
+declare namespace Neutrino {
+  type Middleware<O extends Options = Options, N extends Neutrino<O> = Neutrino<O>> = (neutrino: N) => void;
+  type OutputHandler<R extends any = any, O extends Options = Options, N extends Neutrino<O> = Neutrino<O>> = (neutrino: N) => R;
+  type Register<T extends OutputHandler<any, any, any>, O extends Options = Options> = T extends (neutrino: any) => infer R
+    ? () => R
+    : never;
+
+  interface Options {
+    debug?: boolean;
+    root?: string;
+    source?: string;
+    output?: string;
+    tests?: string;
+    mains?: Record<string, string | Record<string, string>>;
+    packageJson?: string | null;
+    extensions?: string[];
+  }
+
+  interface Configuration<O extends Options = Options> {
+    options?: O;
+    use?: Middleware<O, any> | (Middleware<O, any> | false)[];
+  }
+}

packages/neutrino/types/test/neutrino-api.js

@@ -0,0 +1,72 @@
+/* eslint-disable */
+import Neutrino from 'neutrino';
+
+// Just for type-checking
+/** @type {string}                              | */ let isString;
+/** @type {string | undefined}                  | */ let isStringOrUndefined;
+/** @type {string[] | undefined}                | */ let isArrayOfStringOrUndefined;
+/** @type {boolean}                             | */ let isBoolean;
+/** @type {boolean | undefined}                 | */ let isBooleanOrUndefined;
+/** @type {Neutrino.Options}                    | */ let isOptions;
+/** @type {import('webpack-chain')}             | */ let isConfig;
+
+/**
+ * @type {import('neutrino').Options}
+ */
+const options = {
+  debug: false,
+  extensions: ['string', 'string'],
+  mains: {
+    entry: 'string',
+    page: {
+      entry: 'string',
+    },
+  },
+  output: 'string',
+  packageJson: 'string',
+  root: 'string',
+  source: 'string',
+  tests: 'string',
+};
+
+const neutrino = new Neutrino(options);
+
+neutrino.config.mode('development');
+isArrayOfStringOrUndefined = neutrino.options.extensions;
+isBooleanOrUndefined = neutrino.options.debug;
+isOptions = neutrino.options;
+isStringOrUndefined = neutrino.options.output;
+isStringOrUndefined = neutrino.options.source;
+isStringOrUndefined = neutrino.options.tests;
+neutrino.options.mains;
+
+if (neutrino.options.mains) {
+  // string | object
+  if (typeof neutrino.options.mains.entry === 'string') {
+    neutrino.options.mains.entry.toLowerCase();
+  }
+  if (typeof neutrino.options.mains.page === 'object') {
+    // string
+    if (neutrino.options.mains.page.entry) {
+      neutrino.options.mains.page.entry.toLowerCase();
+    }
+  }
+}
+
+neutrino.regexFromExtensions().test('example');
+neutrino.use(api => {
+  api.config.mode('development');
+});
+
+// With custom options
+/**
+ * @type {import('neutrino').Options & { alpha: string, beta: boolean }}
+ */
+const customOptions = {
+  alpha: 'string',
+  beta: true,
+};
+const customNeutrino = new Neutrino(customOptions);
+
+isString = customNeutrino.options.alpha;
+isBoolean = customNeutrino.options.beta;

packages/neutrino/types/test/neutrino-api.ts

@@ -0,0 +1,102 @@
+import Neutrino = require("neutrino");
+import Config = require("webpack-chain");
+import webpack = require("webpack");
+
+// Just for type-checking
+const is = <A>(v: A): v is A => true;
+
+const options: Neutrino.Options = {
+  debug: false,
+  extensions: ["string"],
+  mains: {
+    index: "index",
+    other: {
+      page: "string"
+    }
+  },
+  output: "string",
+  packageJson: "string",
+  root: "string",
+  source: "string",
+  tests: "string"
+};
+
+const neutrino = new Neutrino(options);
+
+is<Neutrino>(neutrino);
+is<Neutrino.Options>(neutrino.options);
+is<boolean | undefined>(neutrino.options.debug);
+is<string | undefined>(neutrino.options.root);
+is<string | undefined>(neutrino.options.source);
+is<string | undefined>(neutrino.options.output);
+is<string | undefined>(neutrino.options.tests);
+is<Record<string, string | Record<string, string>> | undefined>(
+  neutrino.options.mains
+);
+is<string | undefined | null>(neutrino.options.packageJson);
+is<string[] | undefined>(neutrino.options.extensions);
+is<Config>(neutrino.config);
+is<void>(neutrino.inspect());
+is<webpack.Configuration>(neutrino.webpack());
+is<RegExp>(neutrino.regexFromExtensions());
+
+neutrino.use(api => {
+  is<Neutrino>(api);
+});
+neutrino.register("something", api => {
+  is<Neutrino>(api);
+});
+
+// With custom options
+interface CustomOptions extends Neutrino.Options {
+  alpha: number;
+  beta: boolean;
+  gamma: string;
+}
+const neutrinoWithCustomOpts = new Neutrino<CustomOptions>({
+  alpha: 123,
+  beta: true,
+  gamma: '123',
+});
+
+is<Neutrino.Options>(neutrinoWithCustomOpts.options);
+is<CustomOptions>(neutrinoWithCustomOpts.options);
+is<number>(neutrinoWithCustomOpts.options.alpha);
+is<boolean>(neutrinoWithCustomOpts.options.beta);
+is<string>(neutrinoWithCustomOpts.options.gamma);
+
+// With output handlers & custom options
+type CustomNeutrino = Neutrino<CustomOptions> & {
+  handler1: Neutrino.Register<typeof handler1>
+  handler2: Neutrino.Register<typeof handler2>
+}
+
+const handler1: Neutrino.OutputHandler<string, CustomOptions, CustomNeutrino> = neutrino => { // using Neutrino.OutputHandler
+  is<Neutrino>(neutrino);
+  is<CustomNeutrino>(neutrino);
+  is<() => string>(neutrino.handler1); // self
+  is<() => number>(neutrino.handler2);
+  is<CustomOptions>(neutrino.options);
+  return "string";
+};
+const handler2 = (neutrino: CustomNeutrino) => {
+  is<Neutrino>(neutrino);
+  is<CustomNeutrino>(neutrino);
+  is<() => string>(neutrino.handler1);
+  is<() => number>(neutrino.handler2); // self
+  return Number(123);
+};
+
+const neutrinoWithHandlers = new Neutrino() as CustomNeutrino;
+neutrinoWithHandlers.register("handler1", handler1);
+neutrinoWithHandlers.register("handler2", handler2);
+
+const middleware = (neutrino: CustomNeutrino) => {
+  is<string>(neutrino.handler1())
+  is<number>(neutrino.handler2())
+}
+
+neutrinoWithHandlers.use(middleware)
+
+is<() => string>(neutrinoWithHandlers.handler1);
+is<() => number>(neutrinoWithHandlers.handler2);

packages/neutrino/types/test/neutrino-config.js

@@ -0,0 +1,39 @@
+/* eslint-disable */
+/**
+ * @type {import('neutrino').Middleware}
+ */
+const middleware = neutrino => {
+  neutrino.config.mode('development');
+};
+
+/**
+ * @type {import('neutrino').Configuration}
+ */
+const config = {
+  options: {
+    debug: false,
+    extensions: ['string'],
+    mains: {
+      index: 'index',
+      other: {
+        page: 'string',
+      },
+    },
+    output: 'string',
+    packageJson: 'string',
+    root: 'string',
+    source: 'string',
+    tests: 'string',
+  },
+  use: [
+    middleware, //fn
+    process.env.NODE_ENV === 'development' ? middleware : false,
+    neutrino => {
+      neutrino.options.debug;
+      neutrino.config.mode('development');
+      neutrino.regexFromExtensions().test('example');
+    },
+  ],
+};
+
+module.exports = config;

packages/neutrino/types/test/neutrino-config.ts

@@ -0,0 +1,39 @@
+import Neutrino = require("neutrino");
+import Config = require("webpack-chain");
+import webpack = require("webpack");
+
+// Just for type-checking
+const is = <A>(v: A): v is A => true;
+
+const middleware: Neutrino.Middleware = neutrino => {
+  is<Neutrino>(neutrino);
+};
+
+const config: Neutrino.Configuration = {
+  options: {
+    debug: false,
+    extensions: ["string"],
+    mains: {
+      index: "index",
+      other: {
+        page: "string"
+      }
+    },
+    output: "string",
+    packageJson: "string",
+    root: "string",
+    source: "string",
+    tests: "string"
+  },
+  use: [
+    middleware, //fn
+    process.env.NODE_ENV === "development" ? middleware : false,
+    neutrino => {
+      is<Neutrino>(neutrino);
+      is<webpack.Configuration>(neutrino.webpack());
+      is<Config>(neutrino.config);
+    }
+  ]
+};
+
+export default config;

packages/neutrino/types/test/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["es6"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strict": true,
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "esModuleInterop": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "paths": {
+      "neutrino": ["../index.d.ts"]
+    }
+  },
+  "files": [
+    "../index.d.ts",
+    "neutrino-api.ts",
+    "neutrino-api.js",
+    "neutrino-config.ts",
+    "neutrino-config.js"
+  ],
+  "compileOnSave": false
+}

packages/neutrino/types/typings.json

@@ -0,0 +1,4 @@
+{
+  "name": "neutrino",
+  "main": "index.d.ts"
+}

yarn.lock

@@ -13383,6 +13383,11 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
+typescript@^3.6.3:
+  version "3.6.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.6.3.tgz#fea942fabb20f7e1ca7164ff626f1a9f3f70b4da"
+  integrity sha512-N7bceJL1CtRQ2RiG0AQME13ksR7DiuQh/QehubYcghzv20tnh+MQnQIuJddTmsbqYj+dztchykemz0zFzlvdQw==
+
 uglify-js@3.4.x:
   version "3.4.10"
   resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.4.10.tgz#9ad9563d8eb3acdfb8d38597d2af1d815f6a755f"