feat: improved types

[psychedelicious]

Improved types, mostly in Node.ts.

Notes:

• There should no code changes, only typing changes.
• I've explicitly typed the return value of many functions that previously had their return types inferred. This provides insurance against unintentional changes to return types.
• I wrote some docstrings for the export config methods. Please carefully review these for accuracy.

Followups:

• I'm not sure how the API docs are created. I assume generated from the JSDoc annotations? If so, I can work on those.

[psychedelicious]

I'd like to type this.attrs as Partial<Config>, but this will require some minor code changes, so I've left it out of this PR.

[lavrton]

The issue with this type, as it limits to config only. But it is possible to write ANY custom data into attributes.

[psychedelicious]

Maybe a better name is Dimensions?

[psychedelicious]

I'd like to improve the types of this._cache. Currently it is Map<string, any>.

I had a couple ideas to improve this, but I'm not sure of the intended use of the cache. Is it intended to be a generic cache with arbitrary keys, or can we be strict about what keys are used for it?

If we can be strict, I was thinking about a simple wrapper:

const CacheKey = {
  ABSOLUTE_OPACITY: 'absoluteOpacity',
  ALL_LISTENERS: 'allEventListeners',
  ABSOLUTE_TRANSFORM: 'absoluteTransform',
  ... // the rest of the keys
} as const;

type CacheKeyMap = {
  [CacheKey.ABSOLUTE_OPACITY]: number;
  [CacheKey.ALL_LISTENERS]: unknown; // not sure what this should be
  [CacheKey.ABSOLUTE_TRANSFORM]: Transform;
  ... // the rest of the keys & their types
};

class CacheMap extends Map {
  get<T extends keyof CacheKeyMap>(key: T): CacheKeyMap[T] | undefined {
    return super.get(key);
  }
  set<T extends keyof CacheKeyMap>(key: T, value: CacheKeyMap[T]): this {
    return super.set(key, value);
  }
  delete<T extends keyof CacheKeyMap>(key: T): boolean {
    return super.delete(key);
  }
}

This merits discussion - and would require code changes - so I've left it out of this PR.

[lavrton]

I don't think we need additional code just for types. Ok, if it is types only, but not if it is a real class.
_cache is not exposed to public API, so as it is very well tested, I don't think we need to care much about its types.

[lavrton]

The issue with this type, as it limits to config only. But it is possible to write ANY custom data into attributes.

[lavrton]

Personally, I don't like having return types everywhere. I prefer less code as it is more clean.

I've explicitly typed the return value of many functions that previously had their return types inferred. This provides insurance against unintentional changes to return types.

It is a good point. But still I prefer not to write type. Probably is is a good idea to write them on complex functions with many returns. But on small one, with one return, most likely we don't really need it. Especially if it is just one direct value return.

[lavrton]

We can set any data in attrs. Not just what is inside Config.

[lavrton]

I would prefer to keep this type here directly in the code, so it is not defined somewhere else in the code base. I don't think we reuse this type anywhere.

[lavrton]

I don't think we need additional code just for types. Ok, if it is types only, but not if it is a real class.
_cache is not exposed to public API, so as it is very well tested, I don't think we need to care much about its types.