aurelia / aurelia/framework

Allow better typing for module configuration

Open
#940 4 comments 3 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
11.7k
Forks
608
PR merge metrics
No merged PRs in 30d

Description

**I'm submitting a feature request**

* **Library Version:**
1.3.1

**Please tell us about your environment:**
* **Operating System:**
Windows 10

* **Node Version:**
12.8.0

* **NPM Version:**
6.11.3

* **Aurelia CLI OR JSPM OR Webpack AND Version**
none

* **Browser:**
all

* **Language:**
TypeScript

**Current behavior:**
During intial configuration when modules are included, the module configuration argument is of type any:

```
aurelia.use.plugin("my-module", options?: any)
```

It is currently not possible for module authors to improve typings for their module, as `aurelia.use` is of type `FrameworkConfiguration`, and it is not possible to extend classes with typings in typescript.

**Expected/desired behavior:**

It would be really neat if the `FramworkConfiguration` implemented an interface, say `IFramworkConfiguration` for the builder api instead of the `FrameworkConfiguration` itself.
The interface should of cause contain all all the properties/methods of `FramworkConfiguration`, and the return type for the methods should be changed to `IFrameworkConfiguration`.

This change would enable module authors to include typing aided configuration. Say for example:

```
import { IFrameworkConfiguration } from "aurelia-framework";
import { CacheOptions } from "./cache-options";

declare module "aurelia-framework" {
interface IFrameworkConfiguration {
plugin(plugin: "aurelia-workbox-cachecontrol", configureAction?: (options: CacheOptions) => unknown): FrameworkConfiguration;
}
}
```

To make this work with `PLATFORM.moduleName()` in webpack environments, its typing definitation should be changed from:

```
moduleName(moduleName: string, options?: ModuleNameOptions): string;
moduleName(moduleName: string, chunk?: string): string;
```
to:
```
moduleName(moduleName: T, options?: ModuleNameOptions): T;
moduleName(moduleName: T, chunk?: string): T;
```
to specifically tell typescript that the same module name is returned.

![image](https://user-images.githubusercontent.com/2112306/65672592-95161e80-e049-11e9-920b-06fb087e81ba.png)

* **What is the motivation / use case for changing the behavior?**
To make for a more robust plugin experience where configuration is typed.

Contributor guide

Open the contributing guide

Research direction

Start by locating the TypeScript declarations for FrameworkConfiguration, IFrameworkConfiguration, and PLATFORM.moduleName(). Review the existing builder methods and module-name overloads, then determine how the proposed interface augmentation and generic return types should fit the public API. Done means module authors can add typed plugin configuration and PLATFORM.moduleName() preserves the literal module name without breaking existing usage.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.