NASA-AMMOS / NASA-AMMOS/3DTilesRendererJS

Expanding types / type safety in js

Open
#190 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation enhancement
Dominant language
JavaScript
Stars
2.5k
Forks
416
Avg merge
17h 52m
Merged PRs (30d)
37

Description

While adding the small adjustments to the priority queue in #189 I took a small stab at using jsdoc style comments and // @ts-check to get some type safety.

Overall summary of changes / example changeset can be viewed here: https://github.com/matterport/3DTilesRendererJS/pull/1

  • Add a generic type to LRUCache / PriorityQueue which enables some type safety of dev time in the TilesRendererBase.js file.

  • Add more detailed Tile types

    • TileBase: intended to be the baseline type of the object from the 3d-tiles spec
    • Tile: Intention here was that this would be the type exposed for the PriorityQueue, and these would be considered the 'documented' values as used by the priority functions which the end-user can replace.
    • TileInternal: Provide some documentation of what the internally used tile properties are for developers to work with, not intended for real publishing, but after turning on the // @ts-check in the TilesRendererBase, this ended up being the type needed for the typescript checking to function?!
      TilesRendererBase.js

Add jsdoc type import, and // @ts-check magic comment.. the import type comments are pretty cumbersome, but I feel like they'll help the maintaining experience over time? I thought there was a better way to reference existing .d.ts files, but I'm not finding it offhand yet?!

TilesRendererBase.js:
image

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with TilesRendererBase.js and the existing LRUCache and PriorityQueue definitions. Review the example changeset linked in the issue, including its JSDoc imports, @ts-check usage, and TileBase, Tile, and TileInternal types. Done means the intended type safety and developer-facing type documentation are applied consistently without breaking the JavaScript code.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
developer-experience, tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.