From 6b59047eea32928d5f2d5e327e7093a5814d5215 Mon Sep 17 00:00:00 2001 From: Nathan Walker Date: Mon, 26 Dec 2022 11:19:28 -0800 Subject: [PATCH 1/3] feat: scoped platform API types --- active-rfcs/0000-scope-platform-apis.md | 91 +++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 active-rfcs/0000-scope-platform-apis.md diff --git a/active-rfcs/0000-scope-platform-apis.md b/active-rfcs/0000-scope-platform-apis.md new file mode 100644 index 0000000..6a2c63b --- /dev/null +++ b/active-rfcs/0000-scope-platform-apis.md @@ -0,0 +1,91 @@ +- Start Date: 2022-12-26 +- Target Major Version: 9.x + +# Summary + +Historically NativeScript has always provided platform API types on the global scope, for example: + +``` +// available anywhere you type +NSString. +java. +``` + +On the surface it sounds adverse to common JavaScript standards. In practice it's actually not as bad as it sounds mainly because NativeScript is it's own JavaScript runtime so it's rules our customizable and controllable. The problem often comes down to TypeScript types and the fact that you really don't need all the platform API types available in the global scope. NativeScript 8.2 helped this be confining the types and clarifying how you can include more if you want, see [this post](https://blog.nativescript.org/where-did-my-types-go/). + +It's long been debated and even attacked as to whether platform API types should be on the global scope. + +# Basic example + +Progressive ideas around handling platform API types have emerged in 2022 among TSC discussions. + +Here are the biggest three options in consideration. + +## A. import from runtime packages + +``` +import { NSString } from '@nativescript/ios' + +import { java } from '@nativescript/android' +``` + +The types could ship with the runtimes themselves either directly or via proxy to `@nativescript/types`. + +## B. import from existing types packages explicitly + +``` +import { NSString } from '@nativescript/types-ios' + +import { java } from '@nativescript/types-android' +``` + +## B. import specifiers + +[See how Node is handling here](https://nodejs.org/api/fs.html#file-system), eg `... from 'node:fs'` + +Prior Art: https://github.com/nodejs/node/issues/43413 + +``` +// esm: +import { NSString } from 'native:Foundation'; +// commonjs: +const NSString = require('native:Foundation').NSString; +``` + +For third party vendors: + +``` +// Objective C/Swift +import { LOTAnimationView } from 'native:Lottie'; + +// Java/Kotlin +import { LottieAnimationView } from 'native:com.airbnb.lottie'; +``` + +# Motivation + +This would improve developer experience and help the TSC optimize various compiler behaviors. + +# Drawbacks + +Why should we *not* do this? Please consider: + +- breaking change +- community migration +- is it more clear or less clear + +# Alternatives + +What [was done in 8.2](https://blog.nativescript.org/where-did-my-types-go/). Pairing down of types to give the developer more control over which they need at anytime. + +# Adoption strategy + +This approach could be introduced with NativeScript 9.0 purely as an option. Could be a flag enabled in `nativescript.config` which would enable the bundler to be aware of one way or the other. It may not need a flag as it's possible you could use both approaches for awhile. + +This would be a slow migration between version 9 to 12 likely. + +TSC could introduce several migrations for plugin vendors and projects until eventually all that exists is the scoped types. + +# Unresolved questions + +Other approaches are likely possible. From 68a5d6cd7d38c36f9b8229e3109221a2b965b327 Mon Sep 17 00:00:00 2001 From: Nathan Walker Date: Mon, 26 Dec 2022 11:46:48 -0800 Subject: [PATCH 2/3] chore: cleanup --- active-rfcs/0000-scope-platform-apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/active-rfcs/0000-scope-platform-apis.md b/active-rfcs/0000-scope-platform-apis.md index 6a2c63b..5aad5e1 100644 --- a/active-rfcs/0000-scope-platform-apis.md +++ b/active-rfcs/0000-scope-platform-apis.md @@ -11,7 +11,7 @@ NSString. java. ``` -On the surface it sounds adverse to common JavaScript standards. In practice it's actually not as bad as it sounds mainly because NativeScript is it's own JavaScript runtime so it's rules our customizable and controllable. The problem often comes down to TypeScript types and the fact that you really don't need all the platform API types available in the global scope. NativeScript 8.2 helped this be confining the types and clarifying how you can include more if you want, see [this post](https://blog.nativescript.org/where-did-my-types-go/). +On the surface it sounds adverse to common JavaScript standards. In practice it's actually not as bad as it sounds mainly because NativeScript is it's own JavaScript runtime so it's rules are customizable and controllable. The problem often comes down to TypeScript types and the fact that you really don't need all the platform API types available in the global scope. NativeScript 8.2 helped this be confining the types and clarifying how you can include more if you want, see [this post](https://blog.nativescript.org/where-did-my-types-go/). It's long been debated and even attacked as to whether platform API types should be on the global scope. From 832d367160b475ba45f10ca68516ad7fc3004ac8 Mon Sep 17 00:00:00 2001 From: Nathan Walker Date: Mon, 26 Dec 2022 13:26:01 -0800 Subject: [PATCH 3/3] chore: cleanup --- active-rfcs/0000-scope-platform-apis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/active-rfcs/0000-scope-platform-apis.md b/active-rfcs/0000-scope-platform-apis.md index 5aad5e1..f8def58 100644 --- a/active-rfcs/0000-scope-platform-apis.md +++ b/active-rfcs/0000-scope-platform-apis.md @@ -1,5 +1,5 @@ - Start Date: 2022-12-26 -- Target Major Version: 9.x +- Target Major Version: 9.0 or 10.0 # Summary @@ -82,7 +82,7 @@ What [was done in 8.2](https://blog.nativescript.org/where-did-my-types-go/). Pa This approach could be introduced with NativeScript 9.0 purely as an option. Could be a flag enabled in `nativescript.config` which would enable the bundler to be aware of one way or the other. It may not need a flag as it's possible you could use both approaches for awhile. -This would be a slow migration between version 9 to 12 likely. +This would be a slow migration between version 9/10 to 12 likely. TSC could introduce several migrations for plugin vendors and projects until eventually all that exists is the scoped types.