Generate typescript definitions (d.ts)

[snebjorn]

What would it take to generate typescript definitions (d.ts) for fabric.js? (#6763 (comment))

According to https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html it looks simple. But after trying it out the d.ts file is empty. I believe it's because fabric.js is written in the IIFE style.

Does anyone know if IIFEs can be made to work?
Alternatively the code base could be converted to ES Module. But that's extra work and it might break stuff.

[asturur]

We can start from improving those:
https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

Converting to es modules is a whole new journey that has less impact and for me has very low priority.

[snebjorn]

I played around with it and I don't think it's as simple as just improving the JSDoc - unfortunately :(

Problem is that typescript doesn't play nice with IIFEs.

I.E. it doesn't generate any types for the following

(function (ns) {
    function foo() {
    }
    ns.foo = foo;
})(exports.ns || (exports.ns = {}));

It does however understand

exports.ns = (() => {
    const ns = {};
    ns.foo = function () {

    }
    return ns;
})();

But that's CommonJS and it doesn't allow for exporting another ns that mutates it. Which fabric.js relies on.

So it doesn't look good.

[asturur]

could we take the typedef in the types library, fix it, and update it regularly?

[asturur]

i hope there was some kind of static analyzer of jsdocs, if jsdocs can create a full website from the doc notations it can also write a typedef file. I hoped someone created the template for it

[snebjorn]

Okay! I just needed to sleep on it :)
I think I found a way. But it will require a little refactoring.

See TypeScript Playground Example

The IIFEs will have to assign their content like so

fabric.util.animateColor = (function() {
  // omitted
  return animateColor;
})();

I was able to generate the following

declare namespace fabric {
    const version: string;
    namespace util {
        /**
         * Changes the color from one to another within certain period of time, invoking callbacks as value is being changed.
         * @memberOf fabric.util
         * @param {String} fromColor The starting color in hex or rgb(a) format.
         * @param {String} toColor The starting color in hex or rgb(a) format.
         * @param {Number} [duration] Duration of change (in ms).
         * @param {Object} [options] Animation options
         * @param {Function} [options.onChange] Callback; invoked on every value change
         * @param {Function} [options.onComplete] Callback; invoked when value change is completed
         * @param {Function} [options.colorEasing] Easing function. Note that this function only take two arguments (currentTime, duration). Thus the regular animation easing functions cannot be used.
         * @param {Function} [options.abort] Additional function with logic. If returns true, onComplete is called.
         */
        function animateColor(fromColor: string, toColor: string, duration?: number, options?: {
            onChange?: Function;
            onComplete?: Function;
            colorEasing?: Function;
            abort?: Function;
        }): void;
    }
}

[ShaMan123]

+1
@asturur I think ts must be included in this project for it to enhance DEV UX, make it easier to use and make it even more popular than it already is.
The current definitions are lacking. I myself have a huge patch file for them and I don't bother to PR because it's too complicated IMO.
I think that if it would be part of the project when creating a PR you can enforce the PR to update the ts files.
I am sure the community will take part. I can say the least about myself!

I think this approach is a killer, going around instead of simply getting it done.
@asturur I understand you don't use ts (I have no idea why 😯). It is very similar to JSDOC and has many benefits (like the build process).
I do think that if you want this amazing project to be more accessible and easy to use it is a must.
Another thought, an open source project must evolve for and from the community.
So to summarize I think that adding .d.ts files is the solution.
And again, I believe the community will help, I know I will.

[asturur]

Adding a d.ts file is what we want to do indeed.

[asturur]

Also i do not use d.ts because my day to day work is in JS, and this library is in JS.
So i just do not have occasion to use it regularly, and when i do not work or code fabricJS i do things unrelated to programming.

[asturur]

If you want to move on on this, we need someone that pick up an existiing t.ds file, delete the wrong parts that are not compatible with 4.5.0 and commits it.
Then we neeed a list of things to fix and we can start fixing it.

[ShaMan123]

I've started a draft.
My approach is to create a types folder as the exact copy of src. I think it will make maintaining it much easier, as opposed to a huge index.d.ts file.
The second advantage is that this approach doesn't use namespace, which is not recommended by the spec. This is import because of the extend approach of fabric, types must be esaily extended and namespace makes it harder I believe.
I have set it up in terms of configuration so now it's ready for work.

[ShaMan123]

@snebjorn How did you manage to emit the declaration files? I didn't understand.

[ShaMan123]

https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

[snebjorn]

@snebjorn How did you manage to emit the declaration files? I didn't understand.

Here's my config, with that I just ran tsc

// tsconfig.json
{
  // Change this to match your project
  "include": ["dist/fabric.js"],
  "compilerOptions": {
    // Tells TypeScript to read JS files, as
    // normally they are ignored as source files
    "allowJs": true,
    // Generate d.ts files
    "declaration": true,
    // This compiler run should only output d.ts files
    "emitDeclarationOnly": true,
    // Types should go into this directory.
    // Removing this would place the .d.ts files
    // next to the .js files
    "outDir": "types"
  }
}

But it'll require changes to the js files mention here #7017 (comment)

[bobbhy]

Any updates please 🙏 I'm using right now version 5.3.1 in my end of year project, and I'm not into creating another JS project alongside a huge angular app for a simple canva.com like editor, I have tried using tools like dts-gen and npm-dts for d.ts generation and I have also followed this guide https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html using a clone of fabric JS repo without any success I get endless errors, and I'm really stuck right now 😔.

[ShaMan123]

#7596