Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FEATURE] Introduce preview types #20180

Merged
merged 39 commits into from Sep 6, 2022
Merged

[FEATURE] Introduce preview types #20180

merged 39 commits into from Sep 6, 2022

Commits on Sep 1, 2022

  1. [FEATURE] Introduce a preview types package

    Copy the types from DefinitelyTyped, and set up a bare minimum config
    to make it possible to iterate on them. This particular commit fails all
    type checking and has an enormous amount of work to do, but provides a
    foundation on which we can iterate.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    6278a8b View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    414a763 View commit details
    Browse the repository at this point in the history
  3. Fix many errors in types preview

    - Improve the way we do a minimal representation of the Ember Object
      primitives and utilities.
    - Introduce our own copy of `@ember/string`.
    - Start workk on many of the tests for `Ember` namespace re-exports.
    - Stop distinguishing between Octane and everything else: we only care
      about Octane anyway in our public *TS* API, per RFC 0800.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    14acfd7 View commit details
    Browse the repository at this point in the history
  4. Configuration menu
    Copy the full SHA
    061f2b3 View commit details
    Browse the repository at this point in the history
  5. Configuration menu
    Copy the full SHA
    19507de View commit details
    Browse the repository at this point in the history
  6. Configuration menu
    Copy the full SHA
    f730d9e View commit details
    Browse the repository at this point in the history
  7. type test fixes for 'ember-tests'

    This file is a hot mess, and provides more and further evidence of two
    increasingly-obvious realities from a TS POV:
    
    - The Ember namespace is 99% useless; people should just use the
      module imports instead.
    - The Classic types are *awful*, because Classic *code* was a mess
      compared to Octane, because ES5 was a mess.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    66c28fc View commit details
    Browse the repository at this point in the history
  8. Configuration menu
    Copy the full SHA
    71e1e3f View commit details
    Browse the repository at this point in the history
  9. Configuration menu
    Copy the full SHA
    81655ae View commit details
    Browse the repository at this point in the history
  10. Configuration menu
    Copy the full SHA
    920901e View commit details
    Browse the repository at this point in the history
  11. Configuration menu
    Copy the full SHA
    a5e3642 View commit details
    Browse the repository at this point in the history
  12. Configuration menu
    Copy the full SHA
    9ca3053 View commit details
    Browse the repository at this point in the history
  13. Configuration menu
    Copy the full SHA
    d845d4a View commit details
    Browse the repository at this point in the history
  14. Configuration menu
    Copy the full SHA
    bb0811d View commit details
    Browse the repository at this point in the history
  15. Configuration menu
    Copy the full SHA
    52abdf1 View commit details
    Browse the repository at this point in the history
  16. Configuration menu
    Copy the full SHA
    2dab322 View commit details
    Browse the repository at this point in the history
  17. Configuration menu
    Copy the full SHA
    4730ecd View commit details
    Browse the repository at this point in the history
  18. Configuration menu
    Copy the full SHA
    b450bc8 View commit details
    Browse the repository at this point in the history
  19. Configuration menu
    Copy the full SHA
    cb5fb2b View commit details
    Browse the repository at this point in the history
  20. Configuration menu
    Copy the full SHA
    fe030dc View commit details
    Browse the repository at this point in the history
  21. Configuration menu
    Copy the full SHA
    d95a927 View commit details
    Browse the repository at this point in the history
  22. Configuration menu
    Copy the full SHA
    69eda9f View commit details
    Browse the repository at this point in the history
  23. Configuration menu
    Copy the full SHA
    d32122b View commit details
    Browse the repository at this point in the history
  24. Configuration menu
    Copy the full SHA
    20c6148 View commit details
    Browse the repository at this point in the history
  25. Introduce type utilities for safe get(Properties)

    These allows us to make `get` or `getProperties` correctly handle index
    access the same way direct field access would. This gets us back to the
    same level of safety we had with our old `UnwrapComputedProperty*`
    types for this kind of index access: those types did *many* things, but
    included among them was distributing across the requested properties.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    94716e4 View commit details
    Browse the repository at this point in the history
  26. Configuration menu
    Copy the full SHA
    2dc87a1 View commit details
    Browse the repository at this point in the history
  27. Ignore a case where Ember.get is distinct from get

    While we would prefer this to work, it is not a hard necessity, for (at
    least) two reasons:
    
    1. Use of `Ember.get` vs. the import from `@ember/object` is rare and
       should be discouraged.
    
    2. Use of `get` is itself fairly unusual to *need* these days; most
       uses either will not hit this case, as in the deep key lookup (which
       is always just `unknown` anyways) or should be trivially replaced
       with direct property access (since Ember 3.1!).
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    a0fd30a View commit details
    Browse the repository at this point in the history
  28. Simplify handling of preview types for get(Properties)

    Unlike in the previous pass, this does not try to handle index access
    'correctly', instead choosing to just push people to use normal JS if
    they want that safety.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    241a918 View commit details
    Browse the repository at this point in the history
  29. Finish getting preview types type checking

    - fix runloop test
    - provide an internal-only type for Resolver` that should be
      compatible with the one in `@types/ember-resolver`
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    d7667a5 View commit details
    Browse the repository at this point in the history
  30. Configuration menu
    Copy the full SHA
    225c291 View commit details
    Browse the repository at this point in the history
  31. Implement publishable types preview layout

    1.  Introduce a root import, `types/preview/index.d.ts`, which itself
        imports every module which is part of Ember's type definitions.
        Then wrap each module definition in a `declare module '<name>' {}`
        so that importing it makes the module visible in the type system.
        This makes it so that users can use the types by simply writing a
        single import:
    
        ```ts
        import 'ember-source/types/preview';
        ```
    
        This approach will scale forward to all sorts of future work in TS
        in Ember, including publishing at `ember-source/types/stable`, or
        for future editions e.g. at `ember-source/types/polaris`. Moreover,
        this allows these to happen *simultaneously*. That is, as we publish
        types from source, those can go directly into the `stable` directory
        and users can simply have both imports present:
    
        ```ts
        import 'ember-source/types/preview';
        import 'ember-source/types/stable';
        ```
    
        Similarly, because this relies on module declarations, module
        merging works and this will allow us to at some point publish
        stable types supporting *only* new editions, with the default type
        import being at `stable` but users being able to opt into types
        which support the old edition:
    
        ```ts
        import 'ember-source/types/stable';
        import 'ember-source/types/classic';
        ```
    
    2.  Extract the type tests for the published types into a `type-tests`
        directory, which actually *uses* those mechanics to validate that
        the types are all importable and usable as expected with that
        single import statement.
    
        Do *not* include that directory in `files` in `package.json`, so the
        tests are never published, only the type definitions themselves.
    
    Making those changes and getting the test suite passing also
    highlighted a number of errors in the existing type definitions (and
    tests!) for `EmberArray` and its related types, which had historically
    been masked by the way our tests incorporated the prototype extensions:
    *all* arrays appeared to act as a `NativeArray`. Fixing that involved
    pulling those type tests out into a dedicated test package, and then
    fixing all the bugs in the existing type definitions, including
    restructuring to match the *actual* structure of Ember's internals.
    
    However, fixing the *regular* types for arrays *also* highlighted that
    it is currently impossible to properly represent the array prototype
    extensions. Accordingly, those are excluded from this, and will be
    addressed in some other way.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    33fb32b View commit details
    Browse the repository at this point in the history
  32. Configuration menu
    Copy the full SHA
    dc1d4fd View commit details
    Browse the repository at this point in the history
  33. Add array prototype extension preview types

    These *do not work*. They will be removed in the next commit, but are
    added here for historical purposes.
    
    They do not work specifically because they introduce a circularity in
    the definition of `NativeArray`: `NativeArray` must extends from a
    *subset* of `Array` to correctly represent its public API and behavior,
    but introducing the `Array` prototype extension in turn must extend from
    `NativeArray`, which results in type errors because `NativeArray`
    extends from the subset rather than the full API of `Array`.
    
    This "worked" in the DefinitelyTyped version for two reasons:
    
    1.  All of our type tests actually just assumed the array prototype
        extensions were enabled (as discussed in the previous commit).
    
    2.  The type definition for `NativeArray` was *wrong*: at minimum it was
        substantially out of date; possibly it has always been incorrect.
        (It may have been incorrect *intentionally*, precisely to allow the
        prototype extension to work. The details are lost to time.)
    
    In any case, these type tests represent the "correct" APIs for the
    prototype extensions, so are committed here and removed in the next
    commit for historical purposes.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    434c714 View commit details
    Browse the repository at this point in the history
  34. Remove types for array prototype extensions

    See previous commit message for discussion of *why* these are being
    removed. If we decide to re-introduce these types later, it will require
    not only adding back in these tests but also taking some fairly distinct
    approach to their inclusion, given the problems with the way they work.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    17df5a1 View commit details
    Browse the repository at this point in the history
  35. Configuration menu
    Copy the full SHA
    121ab1c View commit details
    Browse the repository at this point in the history
  36. Types preview: import from 'ember-source/preview'

    Use `typesVersions` to resolve `preview` to `types/preview`; we can use
    `types` for stable and more `typesVersions` (or, eventually, `exports`)
    for other similar schemes in the future.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    303505a View commit details
    Browse the repository at this point in the history
  37. Types preview: remove private DT route types

    We continue to maintain support for these import locations in the types
    on DefinitelyTyped, but remove them here so that users trying the
    preview types do not accidentally depend on them.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    f8a9e83 View commit details
    Browse the repository at this point in the history
  38. Types: exclude from ESLint

    While having some guidance for the ambient types here would be needful
    for the long term, we do not intend to *keep* these all that long; this
    is intended as transitional. If we end up maintaining the ambient types
    for a long time, we can of course revisit this. In any case, we will
    want to run linting on any type tests we introduce for *stable* types
    (at a future `type-tests/stable` location). Net, exclude everything in
    `types` and the tests in `type-tests/preview`.
    chriskrycho committed Sep 1, 2022
    Configuration menu
    Copy the full SHA
    45a03df View commit details
    Browse the repository at this point in the history

Commits on Sep 6, 2022

  1. Types preview: remove dead imports

    The corresponding module declarations were removed earlier; this simply
    drops the 'side-effect' imports from `types/preview/index.d.ts`.
    chriskrycho committed Sep 6, 2022
    Configuration menu
    Copy the full SHA
    119b42c View commit details
    Browse the repository at this point in the history