[types] documenting features as typescript

[sonicolasj]

Hi!

Context: in the README's features, there are block codes used to shown what's included in a feature (ex: https://github.com/zloirock/core-js/blob/v3.21.1/README.md#new-collections-methods). These blocks look a lot like typescript type declarations, but aren't.

First: shouldn't these blocks be tagged as typescript instead of javascript (sed /```js/```ts/g), so we can have proper syntax coloration?

Second: as a stepping point to #568, we could make these blocks correct typescript, so TS users can copy/paste them safely in their codebase when importing the polyfills (especially proposals).

If that's interesting, I could probably start a PR on that!

[zloirock]

Hi. This is not a TypeScript. TypeScript is not the only superset of JavaScript. JavaScript haven't own IDL for definition typing signatures, so this a kind of pseudocode.

If you wanna help to add TypeScript definitions - it's another issue - feel free to work on it.

When JavaScript will have own IDL (for example, this proposal) or at least "types as comments" - core-js will be adapted to it.

[sonicolasj]

JavaScript haven't own IDL for definition typing signatures, so this a kind of pseudocode.

Yes, of course!
But this pseudo-code already looks like a lot like TypeScript. In my opinion, writing them would not really change anything for JavaScript users, and help TypeScript users by giving them a snippet to copy/paste while waiting for the proper types definition to be available!

Ex: current js block

class Set {
  constructor(iterable?: Iterable<value>): Set;
  add(key: any): this;
  clear(): void;
  delete(key: any): boolean;
  forEach((value: any, key: any, target: any) => void, thisArg: any): void;
  has(key: any): boolean;
  values(): Iterator<value>;
  keys(): Iterator<value>;
  entries(): Iterator<[value, value]>;
  @@iterator(): Iterator<value>;
  readonly attribute size: number;
}

ts version:

class Set<TValue> {
    constructor(iterable?: Iterable<TValue>);
    add(key: TValue): this;
    clear(): void;
    delete(key: TValue): boolean;
    forEach(fn: (value: TValue, key: number, target: this) => void, thisArg?: any): void;
    has(key: TValue): boolean;
    values(): Iterator<TValue>;
    keys(): Iterator<TValue>;
    entries(): Iterator<[number, TValue]>;
    [Symbol.iterator](): Iterator<TValue>;
    readonly size: number;
}

If you wanna help to add TypeScript definitions - #568 - feel free to work on it.

Yes, I'm planning to write some typings, as I currently did in my code!

[zloirock]

entries(): Iterator<[number, TValue]>;

Not exactly.

But this pseudo-code already looks like a lot like TypeScript. In my opinion, writing them would not really change anything for JavaScript users, and help TypeScript users by giving them a snippet to copy/paste while waiting for the proper types definition to be available!

Hmm, why not... Ok, feel free to do it.

[sonicolasj]

entries(): Iterator<[number, TValue]>;

Not exactly.

Good catch, it was me assuming it worked like that. Same goes for forEach then!

[zloirock]

@sonicolasj hey, any progress?

[sonicolasj]

Hi!
Yes, I'm documenting everything when using stuff (for the proposals mainly), I'll push when I have something good to show!

[zloirock]

Due to the lack of activity here, I'm adding a help wanted label.

[zloirock]

https://github.com/Kingwl/core-dts