feat: add TypeScript typings #654

LinusU · 2022-09-07T09:03:19Z

I've made this typings by copying in everything from the readme and then formatting it properly. Opening as a draft for now as I would like to investigate some way to make sure that the typings and readme are always in sync. Potentially ts-readme-generator or a similar script. Otherwise I fear that the typings and readme file will drift away from each other 😅

ctavan · 2022-09-10T09:35:48Z

I think this looks really good, although – given my lack of TS experience – I can't judge the quality of the types. Questions that come to my mind:

Does this solve the issue raised in Have validate accept null and undefined #606 which seems to exist in the current DefinitelyTyped types?
In the current Types we use rather complicated interfaces. What are the pros and cons of something like that?
Also big +1 to auto-generating the docs from the types!

In any case, thanks a lot for putting this together and moving this long-requested feature forward!

SimenB · 2022-09-12T06:34:14Z

package.json

@@ -29,7 +29,11 @@
        "import": "./dist/esm-browser/index.js",
        "require": "./dist/commonjs-browser/index.js"
      },
-      "default": "./dist/esm-browser/index.js"
+      "default": "./dist/esm-browser/index.js",
+      "types": {


types should be first for some reason: https://www.typescriptlang.org/docs/handbook/esm-node.html#packagejson-exports-imports-and-self-referencing

SimenB · 2022-09-12T06:34:39Z

package.json

-      "default": "./dist/esm-browser/index.js"
+      "default": "./dist/esm-browser/index.js",
+      "types": {
+        "module": "./types.d.mts",


Suggested change

"module": "./types.d.mts",

"import": "./types.d.mts",

I've not seen module as an export condition before - could you point to its origin?

I believe this is a webpack thing, possibly adopted by other packaging tools as well?

Ah, cool. These are types tho, and the TS docs only point to node (where the spec comes from), and they don't have a module condition listed there: https://nodejs.org/api/packages.html#conditional-exports

I took it from DefinitelyTyped/DefinitelyTyped#57194, but it was changed to import later which is correct. Good catch! 👍

LinusU · 2022-09-13T14:33:41Z

types.d.ts

+ * uuidValidateV4(v1Uuid); // ⇨ false
+ * ```
+ */
+export function validate(str: string): boolean


In order to support #606:

Suggested change

export function validate(str: string): boolean

export function validate(str: any): str is string

nominal types would have made this way cleaner 😛

Yeah for sure!

broofa · 2022-09-13T14:42:28Z

Would it make sense to use JSDoc to document the actual source, then have tsc generate type definitions from that?

LinusU · 2022-09-13T14:45:32Z

Does this solve the issue raised in Have validate accept null and undefined #606 which seems to exist in the current DefinitelyTyped types?

Left a note to myself to adress this 👍

In the current Types we use rather complicated interfaces. What are the pros and cons of something like that?

I'm actually not sure why it was made that way 🤔

It seems like it was introduced in DefinitelyTyped/DefinitelyTyped#16264.

@felipeochoa sorry for a ping for something you made 5 years ago 🙈, but do you happen to remember why use used:

export type v1String = (options?: V1Options) => string;
export type v1Buffer = <T extends OutputBuffer>(options: V1Options | null | undefined, buffer: T, offset?: number) => T;
export type v1 = v1String & v1Buffer;

instead of using an overloaded function?

export function v1(options?: V1Options | null): string
export function v1<T extends ArrayLike<number>>(options: V1Options | null | undefined, buffer: T, offset?: number): T

Also big +1 to auto-generating the docs from the types!

Awesome 🙌

LinusU · 2022-09-13T14:50:04Z

Would it make sense to use JSDoc to document the actual source, then have tsc generate type definitions from that?

This was actually my first approach, but I ran into a number of small issues. The biggest hurdle was probably that that would generate one .d.ts file per JavaScript-file, which then would have had to been copied to all the right places since we ship so many different versions 😅 It would be cool with something similar to Rollup but for .d.ts files!

If we go that route we could also run the TypeScript compiler to type check our JavaScript codebase with --allowJs and --checkJs. It looks at the JSDoc annotations and uses that to type check the code!

SimenB · 2022-09-13T14:53:45Z

types.d.ts

+ * uuidVersion('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ 4
+ * ```
+ */
+export function version(str: string): boolean


Suggested change

export function version(str: string): boolean

export function version(str: string): 1 | 3 | 4 | 5

or number? deffo not boolean, tho 🙂

Hehe, not sure how it ended up as boolean 😅

It can return 0 also, but yeah number union seems like a great return value, thanks! 👍

Hmm... worth adding a unit-test for types of some sort? Jest + tsc a few sample scripts to verify it does / doesn't throw the expected type warnings?

I'd recommend using tsd or something. In the jest repo we use https://github.com/jest-community/jest-runner-tsd which works great (if you already use jest), but tsd is great for type tests

LinusU · 2022-10-08T14:58:24Z

I made some progress on keeping the docs in sync. The most things are already supported by ts-readme-generator, and I've added some small missing things now.

There is still some things left though, the main thing being how to handle overloaded functions 😅

But we only need a solution that's good enough for our specific needs, so that makes it a bit easier. I'm thinking now that it could compare if the overload only appends new arguments, and then merge them into just one heading. Should be quite easy!

I've put a todo list in the PR description to track what's left...

broofa · 2022-10-08T15:08:19Z

I've put a todo list in the PR description to track what's left...

Might want to add an item for removing runmd support. ( remove from devDependencies, remove README_js.md)

LinusU · 2022-10-09T09:04:56Z

@broofa I haven't looked closely at exactly how to integrate it, but ts-readme-generator only modifies the ## API section of the readme, so I think that it can coexist with runmd. We could also add a flag to ts-readme-generator to just print the result to stdout, that way it could be integrated with runmd as well.

Ahh, I see now that runmd is only used in the examples in the ## API section 😅

types.d.ts

LinusU · 2023-03-20T05:51:37Z

Note to self: change return value to `${string}-${string}-${string}-${string}-${string}`?

ref: DefinitelyTyped/DefinitelyTyped#64798, microsoft/TypeScript-DOM-lib-generator#1432

broofa · 2023-03-20T15:08:24Z

Note to self: change return value to `${string}-${string}-${string}-${string}-${string}`?

Is this a Template Literal Type? Seems like an appropriate change.

LinusU · 2023-03-21T11:42:17Z

Note to self: change return value to `${string}-${string}-${string}-${string}-${string}`?

Is this a Template Literal Type? Seems like an appropriate change.

Yes it is!

Yeah, I think it's a good change, since it would allow people to be stricter with functions that only accept uuids, and not any string 🚀

Also, sorry for falling behind on this, unfortunately I have a bit limited time at the moment, but I really want to push thru with this!

broofa · 2023-03-21T12:52:00Z

Also, sorry for falling behind on this, unfortunately I have a bit limited time at the moment

No need to apologize. We're all in the same boat. ⛵️

feat: add TypeScript typings

ea26232

LinusU mentioned this pull request Sep 7, 2022

New version release plan? #598

Closed

SimenB reviewed Sep 12, 2022

View reviewed changes

ctavan mentioned this pull request Sep 12, 2022

Have validate accept null and undefined #606

Open

LinusU commented Sep 13, 2022

View reviewed changes

SimenB reviewed Sep 13, 2022

View reviewed changes

LinusU mentioned this pull request Oct 8, 2022

Towards uuid support, part 1 LinusU/ts-readme-generator#7

Merged

LinusU mentioned this pull request Nov 10, 2022

types not considered? LinusU/ts-readme-generator#8

Open

leostera reviewed Nov 20, 2022

View reviewed changes

types.d.ts Show resolved Hide resolved

LinusU mentioned this pull request Dec 20, 2022

Could not find a declaration file for module 'uuid' (Incompatibility with ES6 Import) #668

Closed

LinusU added 2 commits January 11, 2023 17:36

fix: typing of version function

3bc4c6a

fix: add description to stringify typings

61f2854

broofa mentioned this pull request Oct 12, 2023

Support TypeScript #630

Closed

broofa mentioned this pull request Jan 5, 2024

Add UUID type to use in TypeScript #741

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add TypeScript typings #654

feat: add TypeScript typings #654

LinusU commented Sep 7, 2022 •

edited

ctavan commented Sep 10, 2022 •

edited

SimenB Sep 12, 2022

SimenB Sep 12, 2022

broofa Sep 12, 2022

SimenB Sep 13, 2022

LinusU Sep 13, 2022

LinusU Sep 13, 2022

SimenB Sep 13, 2022

LinusU Sep 13, 2022

broofa commented Sep 13, 2022

LinusU commented Sep 13, 2022

LinusU commented Sep 13, 2022

SimenB Sep 13, 2022

LinusU Sep 13, 2022

broofa Sep 13, 2022

SimenB Sep 13, 2022

LinusU commented Oct 8, 2022

broofa commented Oct 8, 2022

LinusU commented Oct 9, 2022

LinusU commented Mar 20, 2023

broofa commented Mar 20, 2023

LinusU commented Mar 21, 2023

broofa commented Mar 21, 2023

	export function validate(str: string): boolean
	export function validate(str: any): str is string

	export function version(str: string): boolean
	export function version(str: string): 1 \| 3 \| 4 \| 5

feat: add TypeScript typings #654

Are you sure you want to change the base?

feat: add TypeScript typings #654

Conversation

LinusU commented Sep 7, 2022 • edited

ctavan commented Sep 10, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

broofa commented Sep 13, 2022

LinusU commented Sep 13, 2022

LinusU commented Sep 13, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LinusU commented Oct 8, 2022

broofa commented Oct 8, 2022

LinusU commented Oct 9, 2022

LinusU commented Mar 20, 2023

broofa commented Mar 20, 2023

LinusU commented Mar 21, 2023

broofa commented Mar 21, 2023

LinusU commented Sep 7, 2022 •

edited

ctavan commented Sep 10, 2022 •

edited