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. ⛵️

broofa · 2024-06-05T20:24:49Z

FWIW, the more I think about this issue (adding type declarations to this project), the more I'm of the opinion that we should just port everything to TS, and let tsc generate the declarations for us. Especially in light of the recent RFC9562 work.

Having this code be in TS would've given me more confidence that we're not introducing regressions. It would also force us to be more strict about what types are supported (e.g. "What type, exactly, are binary UUIDs?"). And, of course, it'd avoid having to manually update the *.d.ts file here.

@pmccarren What's your comfort level with Typescript? Would porting this codebase to TS help or hinder your interest in helping to maintain this project?

pmccarren · 2024-06-06T16:10:16Z

@broofa I'm all in for typescript, and I believe it a worthwhile investment. I too feel it would build confidence working throughout the repo

As for comfort level, I've worked extensively with typed languages and while bit newer to the TS scene specifically, I've began adopting it exclusively for all new JS projects.

v10 focused on RFC9562, v11 TS + deploy tooling?

broofa · 2024-06-06T20:30:52Z

v10 focused on RFC9562, v11 TS + #681 (comment)?

Yup. TS and deploy tooling are out of scope for v10.0.0 (which I'd like to release ASAP).

FWIW, I expect deploy tooling to be independent of semver releases. (although I expect we'll want to do actual testing of the deploy pipeline, that can/should happen with prerelease tags that stay off the main release timeline.) As for TS, switching to TS in and of itself wouldn't necessitate a major release since the API wouldn't necessarily change. That said, it wouldn't surprise me if one of the side effects was tighter type restrictions in the API (e.g. Uint8Array adoption) that did break the API.

... but whatevs. Cross those bridges post 10.0.0.

broofa · 2024-06-09T14:20:55Z

Closing. This PR seems to have eddied out (for now), and I think the path forward will be to port the uuid codebase to TS.

@LinusU Thanks for the effort. Sorry we didn't get this merged. So... uh... 'feel like porting some JS to TS?? 😉

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

Closed

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

broofa closed this Jun 9, 2024

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

Loading

ctavan commented Sep 10, 2022 •

edited

Loading

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

broofa commented Jun 5, 2024

pmccarren commented Jun 6, 2024

broofa commented Jun 6, 2024 •

edited

Loading

broofa commented Jun 9, 2024

	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

feat: add TypeScript typings #654

Conversation

LinusU commented Sep 7, 2022 • edited Loading

ctavan commented Sep 10, 2022 • edited Loading

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

broofa commented Jun 5, 2024

pmccarren commented Jun 6, 2024

broofa commented Jun 6, 2024 • edited Loading

broofa commented Jun 9, 2024

LinusU commented Sep 7, 2022 •

edited

Loading

ctavan commented Sep 10, 2022 •

edited

Loading

broofa commented Jun 6, 2024 •

edited

Loading