Create @cesium/utils package

[jfayot]

Description

This PR is an experimental approach to tackle different subjects through the creation of an additional package @cesium/utils (I realize that it could be renamed @cesium/utility to match cesium native component):

• Continue further splitting of @cesium/engine into smaller packages
• Start Typescript migration into an iterative way on a per package basis
• Use Vite as a build tool to manage Browser / Node outputs and get rid of tsd-jsdoc

For the moment, only a few files have been moved to the new package @cesium/utils:

• defer.js
• defined.js / d.ts
• Check.js / d.ts
• DeveloperError.js
• RuntimeError.js
• Fullscreen .js
• FeatureDetection.js

Corresponding Specs have been moved too, but unit test FeatureDetection / "detects WebGL2 support" had to be removed as it pulled unwanted dependency Scene.

There have been some imports reordering during the process, which makes quite a lot of modified files. This is because I temporarily used organize-imports-cli. This could be added as a lint-stage.

For the documentation generation, I'm still using jsdoc comment headers, but as it is with typescript files, I had to use the jsdoc-babel plugin. It works quite well, and allows to keep consistent doc across js and ts. But it could be interesting to evaluate other tools such as typedoc which are specifically made for typescript.

For the declaration types, I'm using the one bundled by dts vite plugin, and then inserting it at the end of Cesium.d.ts (see function createTypeScriptDefinitions).

If this approach is something you'd like to continue with, let me know, so that we can agree on what to put inside @cesium/utils, and help me identify what's missing in the build / ci scripts (for instance debug pragma strip out...)

Issue number and link

Addresses following issues:

• #10636
• #10455
• #4434

Testing plan

• All tests should still pass
• ESLint should be OK
• Documentation generation OK with new @cesium/utils section
• make-zip should be OK
• build-ts should be OK
• build-release should be OK

Author checklist

• [x] I have submitted a Contributor License Agreement
• [x] I have added my name to CONTRIBUTORS.md
• [ ] I have updated CHANGES.md with a short summary of my change
• [x] I have added or updated unit tests to ensure consistent code coverage
• [x] I have updated the inline documentation, and included code examples where relevant
• [x] I have performed a self-review of my code

[github-actions[bot]]

Thank you for the pull request, @jfayot!

:white_check_mark: We can confirm we have a CLA on file for you.

[ggetz]

Hi @jfayot, I'm happy to see the interest in this! We've been eyeing doing something similar for math and other non-rendering 3D and geospatial classes.

A few thoughts up front:

• We currently use esbuild for our bundling and other build processes, which is one of the bundlers vite depends on. I think we would likely stick with that approach over pulling in vite as a bundler. Though, it would be in our best interest to clean up our existing build scripts in anticipation ad adding additional entry points, like new CesiumJS packages and Sandcastle.
• The utils package architecture as you describe it here makes total sense to me, and I'm glad to see you removed the Scene dependency from FeatureDetection to support it. Are there any other files which also should be considered? Maybe clone, Event and EventHelper, Resource and buildModuleUrl, etc?
• Some of these functions should probably be deprecated over being moved. While I don't want to blow up the scope of a PR, deprecating first be better to reduce noise.
  • defer.js was added as a workaround, and is an anti-pattern which we'd like to discourage in favor of using Promise directly.
  • FeatureDetection has several functions which check for extensions or other WebGL features which have been widely supported for years, and that we assume support for in most areas of the codebase. For example supportsTypedArrays. We also explicitly do not support IE anymore, so we shouldn't need to check for it.
• I have not yet looked at your approach to generating documentation, but am interested to see your solution and take a look at typedoc. We are interested in moving away from tsc-jsdoc.

[jfayot]

Thanks @ggetz for your review.

We currently use esbuild for our bundling and other build processes

Sure I can try to stick back to esbuild, but I guess that the new Sandcastle will also be using vite as build system, so it's not really like we'll add it specifically for @ceium/utils. And here, vite is only used for new packages, @cesium/engine and @cesium/widget still rely on esbuild. This would be the opportunity to progressively modernize cesium's build system. Let me know if you still prefer to have @cesium/utils use esbuild.

Are there any other files which also should be considered?

I was thinking of the following files to move to @cesium/utils:

• AssociativeArray
• DoublyLinkedList
• Event
• EventHelper
• Frozen
• GregorianDate
• Heap
• Interval
• Iso8601
• JulianDate
• KeyboardEventModifier
• LeapSecond
• ManagedArray
• Proxy
• Queue
• Request
• RequestErrorEvent
• RequestScheduler
• RequestState
• RequestType
• TimeConstants
• TimeInterval
• TimeIntervalCollection
• TimeStandard
• appendForwardSlash
• arrayRemoveDuplicates
• binarySearch
• clone
• combine
• createGuid
• deprecationWarning
• destroyObject
• formatError
• getBaseUri
• getAbsoluteUri
• getExtensionFromUri
• getFilenameFromUri
• getImageFromTypedArray
• getImagePixels
• getJsonFromTypedArray
• getMagic
• getStringFromTypedArray
• getTimestamp
• isBitSet
• isBlobUriuri
• isCrossOriginUrl
• isDataUri
• isLeapYear
• loadAndExecuteScript
• mergeSort
• objectToQuery
• oneTimeWarning
• parseResponseHeaders
• queryToObject
• srgbToLinear
• subdivideArray
• wrapFunction

I've excluded everything that uses Math or that has an indirect dependency on Math, as it would create circular dependency. Resource and buildModuleUrl are in this case. One potential solution would be to create another package @cesium/http-helpers that would depend on @cesium/math and @cesium/utils

Some of these functions should probably be deprecated over being moved

Do you mean that those deprecations should be done prior to this PR?

[ggetz]

Sure I can try to stick back to esbuild, but I guess that the new Sandcastle will also be using vite as build system, so it's not really like we'll add it specifically for @ceium/utils.

I think we can circle to back to that discussion after we sort out the structure of the proposed package. I don't think it's a matter of esbuild or vite being more modern, but what are the granularity of options needed. 🙂

Do you mean that those deprecations should be done prior to this PR?

I think that would be helpful over including the deprecations in this PR. That way they can be reviewed separately and don't need to depend on the rest of the code reorg here, which will likely have more discussion.

I'll follow up with a few more thoughts on what belong in each package, but I agree there should likely be a distinction between what goes in this proposed utils package and the Math-related modules. :+1:

[javagl]

I have not yet looked at all changes and the details of all things that are proposed to be pulled out. One quick, drive-by comment is that

• Iso8601
• JulianDate
• LeapSecond
• TimeConstants
• TimeInterval
• TimeIntervalCollection
• TimeStandard
• getTimestamp (?)
• isLeapYear

look like they could be a candidate for an own package, or, depending on whether there are considerations to have some additional structure within the packages, some Temporal subdirectory.

Also, such a http-helpers package sounds reasonable (although it's not clear which of the listed classes/functions would go into that exactly, there are many that sound like they could belong there).

[jfayot]

Sorry for the long period of inactivity, but I guess you must be quite busy too with the upcoming Cesium developer conference :grin: !

I'll try to catch up and continue the work on this PR next week...