TypeScript support

[3mcd]

I'm submitting a ...

• feature request

What is the current behavior?

ogl does not have TypeScript support.

What is the expected behavior?

I would love to see this project support TypeScript, either through source or a library definition file. TS support is very important for me (and I suspect a lot of other users) as it gives you so many guarantees and improved developer experience that plain JS cannot.

What is the motivation / use case for changing the behavior?

Without TS support, I'd either have to maintain my own library definition file, or allow imports from ogl to be automatically cast to any. Both of these solutions increase the surface area for potential bugs in my codebase.

TypeScript has risen in popularity over the last few years and, in my experience, is very commonly used to build web apps of medium->large complexity. Other popular WebGL libraries (like three and babylon.js) have support for TypeScript, and I think it would be a great addition to this library, too!

Other information

@endel addresses this PR in #23

[gordonnl]

As discussed here I'd be willing to revisit once the library doesn't require large amounts of work. If types and private properties were supported it wouldn't be an issue, however I'm against forcing people to require a build step when possible.

[3mcd]

It makes sense to hold off on a rewrite until the project is in a more stable spot!

One option could be to run your prepublish script locally (or in CI), archive the directory, make a release on GitHub, and update the "Download" link in the README to point to the release rather than the master branch archive. Then users without a build system would import your ES modules from ./ogl/lib instead of ./ogl/src.

[designstorming]

Hi, I managed to generate typescript definition for this awesome library using Microsoft's dts-gen. This is totally generic file as I did not go deep into defining types but it should make it work for ts projects. Also, I understand due to the active development of this repo, this typing may become obsolete but... for now it works. Here is the gist

[eXponenta]

We need it. I think pr #23 is fine, and i don't know why it was be rejected.

[munrocket]

however I'm against forcing people to require a build step when possible.

They don't need build step with typescript. You just compile your typescript code to es5/es6 and they include bundle it as it was before.

import typescript from 'rollup-plugin-typescript';
import pkg from './package.json';

export default [
    {
        input: 'src/index.ts',
        output: [
            { file: pkg.browser, format: 'cjs' },
                        { file: pkg.module, format: 'es' },
                        { file: pkg.unpkg, format: 'umd', name: 'ogl' },
        ],
        plugins: [
            typescript({lib: ["es5", "es6", "dom"], target: "es5" })
        ]
    }
];

This is all that you need in config files.

[nshen]

I just port ogl HEAD to typescript based on @endel 's work. then I use @babel/preset-typescript to bundle it

https://github.nshen.net/ogl-typescript/dist/ogl.es.min.js

and I change all examples to import from this small bundle file , like this

 import {Renderer, Camera, Transform, Texture, Program, Geometry, Mesh} from '../dist/ogl.es.min.js';
 import {Plane} from '../dist/ogl.es.min.js';

it works fine, please check my fork

https://github.com/nshen/ogl-typescript

and all examples here

https://nshen.github.io/ogl-typescript/examples

[manspaniel]

Would love TypeScript support! I think there are two key bonuses which I haven't seen mentioned so far:

1. Both TS and plain JS users alike will get excellent autocomplete and tooltips when using VSCode, since VSCode still reads type definition files from modules, even in plain JavaScript mode!
2. If the API does change (eg. rename a function or class, change arguments or properties), users will immediately see an error in their code, which they can fix easily enough without even having to check the OGL docs or codebase.

@munrocket is right — no extra build step or configuration is required for end users, and only a small modification is needed to get it building.

TypeScript is also pretty easy, as long as you're using an editor which supports it (like VSCode). There are certainly advanced TypeScript features which can cause headaches for newbies to TS, however I don't think those features would be necessary for this library. PLUS, TypeScript has built-in support for WebGL types, so there's that!

This library is great, it's so clean and well constructed and I can't wait to see it develop! I've already used it on two production sites and I'm looking forward to the next one! Thank you!

[talentlessguy]

Hello there, I think it doesn't worth rewriting to ts. It's easier to put .d.ts file in root with module declaration.

There won't be a need to rewrite anything and typescript users will be happy

[vanrez-nez]

A quick and dirty file definition I put together from @nshen port https://gist.github.com/radixzz/ac11b2b605a8a1577df7dd5724b725a1

[jt3k]

Typescript is unnecessary!

[tkjaergaard]

Maybe 2021 is the year we go TS for OGL @gordonnl 🙏

[gordonnl]

Currently, my preference would be to implement type annotations as comments - as per this 5 year old issue https://github.com/microsoft/TypeScript/issues/9694 I don't really want to restart the TS discussion, but just giving a small update of where I'm at on the TS conversation ;)

[milewski]

I think annotation comments are not useful for those using typescript and indifferent for the ones using vanilla javascript, I think it's wiser to either convert the source code to typescript in the best-case scenario or create only the typings and shipping it alongside to npm...

Keeping the level of abstraction low helps to make the library easier to understand, extend, and also makes it more practical as a WebGL learning resource.

Nothing better than typescript/typings to make this library easier to understand, extend, and it helps a lot on WebGL learning...

[talentlessguy]

Currently, my preference would be to implement type annotations as comments - as per this 5 year old issue microsoft/TypeScript#9694 I don't really want to restart the TS discussion, but just giving a small update of where I'm at on the TS conversation ;)

what about .d.ts files? they will not impact the source code and will be a separate file located in the repo root

[nshen]

my TypeScript version is keep following

replace import { ... } from 'ogl' with import { ... } from 'ogl-typescript'

you'll get some type info, you can change it back later.

[CodyJasonBennett]

I've created TypeScript .d.ts definitions that are 1-1 with the current version of OGL. It is only missing types for GLTFAnimation and GLTFLoader, but I've added what I can without looking deeper at the glTF spec and its usage. These types can be sent to https://github.com/DefinitelyTyped/DefinitelyTyped to be available under @types/ogl. IDEs will pick this up automatically, and TypeScript users can install them alongside OGL, similar to how this is done with three (see https://github.com/three-types/three-ts-types).

You can find these types in their current state here (these would need to be broken up to reflect the file structure of OGL but can otherwise be used as-is):

• https://github.com/CodyJasonBennett/ogl-types

However, I'd like these to be easily accessible to the community with localized issues/PRs to manage alongside development here. Would this project be open to creating a repository under https://github.com/oframe to house this? I suggest including these elsewhere from the OGL repository to isolate noise from TypeScript users from actual library development. However, I'd like to centralize types somewhere close to OGL rather than a personal repository, so users know it's both genuine and approachable for contribution.

[pschroen]

Following-up on the TypeScript definitions.

I'd consider removing the TS fork of the library from the readme, it hasn't been updated since 2021 and is a prime example of why TypeScript definitions should be kept with DefinitelyTyped or committed directly to OGL.

My recommendation here is to follow the same approach as GSAP, adding a types directory with the definitions for each class, and adding the "types" property to the package.json.

    "types": "types/index.d.ts",

I'd also like to propose building on the types already done by @nshen from 2021 and @CodyJasonBennett from last year, and I can help with finishing the remaining definitions.

I suggest including these elsewhere from the OGL repository to isolate noise from TypeScript users from actual library development.

Related to #175 I just opened, this library doesn't change a lot and don't think there will be much more noise if we commit the types directly to the repo?

cc @nshen @CodyJasonBennett @gordonnl ☝️

Let me know what you think!

References:

• https://github.com/CodyJasonBennett/ogl-types
• https://github.com/pmndrs/react-ogl
• https://github.com/nshen/ogl-typescript

[gordonnl]

That sounds great to me! Thanks for your considered analysis

[gordonnl]

And yes fine to commit directly to a types folder within OGL

[pschroen]

Ok sounds good, I'll connect with @CodyJasonBennett on getting the types working for non-React TypeScript builds first (ogl-types isn't working for me in Angular) and then we can prepare the files in a separate PR.

The types should work with:

• Vanilla TypeScript project
• React
• Angular

Anything else we should add to the list for testing?

[CodyJasonBennett]

Vanilla types should work regardless of framework -- I didn't do anything special for React. I'd expect related TS configuration to be more relevant for testing, but I don't anticipate anything exotic like method overloads for example that would break dynamic inference. I started rewriting the library in TypeScript offline for no other purpose but to double check the correctness of types with the implementation which can be converted back into annotations via the TS compiler (and keep only those ofc). That may be a sane way to update things since prior efforts was best effort for a lot of dynamic types.

[pschroen]

Yup agreed, it should work out of the box for all frameworks, though we should still test on a few boilerplate projects to be sure, it's possible there could be different TypeScript configurations. 🤔

I'll troubleshoot why it's not working with my Angular setup (when @types/three does work), if I find anything with ogl-types would you prefer I open an issue there, or I could also create a new fork of OGL we could use for testing?

Not sure how much of a difference a namespace vs. a module makes, for comparison @types/three is also using a namespace like:

export as namespace OGL

Where GSAP is using a module like:

declare module 'ogl' {
...
}

I do have my own typings for OGL working locally with a module declaration, what's the preferred approach here?

[CodyJasonBennett]

See the readme for the project. It's supposed to be installed as @types/ogl which TS will assume belongs to the ogl module. If types are sent to DefinitelyTyped or co-located in the library, you won't need to do anything special since it's recognized as ogl itself.

// package.json
{
  "dependencies": {
    "@types/ogl": "npm:ogl-types@^0.0.99"
  }
}

[f4rrysh]

Any update on this?

[pschroen]

Yes, it's in progress with #177.

I'll have work to share shortly. 😊