Typescript declarations

[Glinkis]

It would be very helpful if there existed type declarations for all the JavaScript functionality. A simple type declarations file published on Definitely Typed would suffice.

For an example of how these can be written, see my attempt at at least partially declaring the Sugar cube types

An alternative is to publish SugarCube as a NPM package, and include the typings there.

[tmedwards]

I've already written a basic SugarCube v2 ambient module file for TypeScript for someone else. I just tossed in on GitHub as a Gist:

• sugarcube.d.ts — SugarCube v2 Ambient Module

[Glinkis]

Fantastic, thank you.

[tmedwards]

Updated the Gist to include the contributions by @hogart and additions from v2.32.0.

• sugarcube.d.ts

[tmedwards]

Updated the Gist to fix various issues.

• sugarcube.d.ts

[tmedwards]

Updated the Gist (again) to fix various issues.

• sugarcube.d.ts

[tmedwards]

In reference to the definitions that were submitted to DefinitelyTyped: (see: DefinitelyTyped/DefinitelyTyped#46236 )

1. I don't know how I feel about the documentation being included with them, considering it's not static. If it's not guaranteed to be kept up to date, then it shouldn't be there. Just reference the actual docs.
2. They include obsolete, legacy interfaces from v1 that should definitely not be included.
3. They're missing interfaces that should be there—e.g., jQuery.wiki(), meaning JQueryStatic not the instance method of the same name.
4. I'm sure I saw some non-public/private interfaces in there too.
5. Various names are misspelled—e.g., MacroContex, JQueryAreaClickOptions.
6. Various errors—e.g., interface MacroArgsArray extends Array<string> should be Array<any>, Config.saves.autoload union type value 'promt' should be 'prompt'.
7. Some of the decisions seem odd—e.g., defining PassageBase rather than simply using Pick<Passage, 'tags' | 'text' | 'title'> in the one instance it's needed.

I'll stop there as I don't want to be too critical, as I certainly appreciate the effort that went into it and what I, and others, have been working on here clearly isn't perfect either.

What I'd like to see is for both sets of definitions be reconciled—and be correct, obviously.

CC: @ezsh

[ezsh]

Thank you for looking into the typings, @tmedwards! I intend to keep them up to date with the documentation and will be happy to correct any other mistakes. So, please, feel free to be as critical as you can. The PR to the DefinitelyTyped repo was created because of microsoft/TypeScript#39691 and because some time ago your gist with the typings contained a comment saying you do not want to invest more efforts in them.

They include obsolete, legacy interfaces from v1 that should definitely not be included.
I'm sure I saw some non-public/private interfaces in there too.

Are those interfaces (still) mentioned in the documentation?

[tmedwards]

[…] your gist with the typings contained a comment saying you do not want to invest more efforts in them.

That's not really what it said. It said that proper interface definitions should be done for SugarCube's internal modules, but the simple ones (implied: in that revision) would satisfy TypeScript. It did not say that I would never revisit them. If I never intended to revisit them, I wouldn't have bothered to put the note there in the first place.

Having time to work on things is the primary factor behind that comment and, frankly, spending time on something that the vast majority of SugarCube users, including myself, will never use is, unfortunately, not high on my list of priorities. I mean, continued work on v2 keeps stealing time away from my work on v3, let alone something most will never use.

Are those interfaces (still) mentioned in the documentation?

No, or they shouldn't be—if some are, I'd consider that a documentation bug needing to be fixed.

Anyway, to explain in more detail.

• Deprecated public v2 APIs are in the docs—e.g., postdisplay or State.initPRNG()—and should be included, though marked as deprecated via @deprecated in a comment or whatever.
• Obsolete v1 and v2 APIs are not in the docs and should not be included.

For example, wiki.d.ts should look more like the following: (obsolete APIs removed)

export interface WikifierAPI {
	createExternalLink(destination: string, url: string, text: string): HTMLElement;
	createInternalLink(destination: string, passage: string, text: string, callback: () => void): HTMLElement;
	isExternalLink(link: string): boolean;
	wikifyEval(text: string): string;
}

export {}; // QUESTION: Is there a reason for the empty export statements?  It's unnecessary, and kind of bizarre, from a purely ES Modules standpoint.

Though, that's not quite complete and the destination params are incorrectly typed.

Ideally, you should probably be declaring it as a class so you can include the constructor, at least. For example, something like the following might be better:

type OutputDestination = DocumentFragment | HTMLElement | JQuery;

declare class Wikifier {
	constructor(destination: OutputDestination | null, source: string, options: object);

	static createExternalLink(destination: OutputDestination, url: string, text: string): HTMLElement;
	static createInternalLink(destination: OutputDestination, passage: string, text: string, callback: () => void): HTMLElement;
	static isExternalLink(link: string): boolean;
	static wikifyEval(text: string): string;
}

export { OutputDestination, Wikifier };

Note: The above example was not tested and may need tweaking, but it should give you the idea.

[ezsh]

That's not really what it said.

I must have misunderstood you, since my takeaway from the note was that you do not want to invest efforts in that, and basic definitions in that file look sufficient.

Having time to work on things is the primary factor behind that comment and, frankly, spending time on something that the vast majority of SugarCube users, including myself, will never use is, unfortunately, not high on my list of priorities. I mean, continued work on v2 keeps stealing time away from my work on v3, let alone something most will never use.

That's where the DefinitelyTyped repository comes of use: those who use typings will find them and will get a way to improve them. You are listed as the owner and should be noticed of any PRs.

No, or they shouldn't be—if some are, I'd consider that a documentation bug needing to be fixed.

Anyway, to explain in more detail.

• Deprecated public v2 APIs are in the docs—e.g., postdisplay or State.initPRNG()—and should be included, though marked as deprecated via @deprecated in a comment or whatever.
• Obsolete v1 and v2 APIs are not in the docs and should not be included.

Thank you! Is it then correct to assume that what is absent from the docs and not marked as private in the sources is nevertheless private? For example, UIBar.update().

For example, wiki.d.ts should look more like the following: (obsolete APIs removed)
Ah, yes, thank you! That wiki object bothered me. I knew I get it wrong.

export {}; // QUESTION: Is there a reason for the empty export statements? It's unnecessary, and kind of bizarre, from a purely ES Modules standpoint.

This is to tell TypeScript that the file is a module. It's empty because declarations are exported individually already.

Though, that's not quite complete and the destination params are incorrectly typed.

What is the correct type, please?

Ideally, you should probably be declaring it as a class so you can include the constructor, at least. For example, something like the following might be better:

Thank you, I changed its declaration. I would appreciate your review for the PR with corrections and update to 2.33.

[ezsh]

Sadly, no one seems to be interested in reviewing DefinitelyTyped/DefinitelyTyped#46340. BTW, it was updated to 2.33 quicker than the linked gist and includes Jquery event definitions, which means it now covers the SugarCube API completely.

[ezsh]

@tmedwards , I voluntary added you as an author to those typings in the DefinitelyTyped repo, because I copied the documentation. I probably should not have done that in the first place. But now their PR management system seem to be expecting for your approvals. Please let me know if you are insterested in those typings, otherwise I'm going to remove you from them to unblock workflow. Thank you.

[tmedwards]

Considering the spam of commits and changes to the issue, you can't expect someone to shift through all that mess single every time. If you were done with the changes 8 days ago, as it seems from the issue logs, then you should have pinged me then, rather than waiting until 2 days ago—1 day for kant2002. I get you want to get that done, but other people have lives too you know.

Anyway. The changes look good to me and I've approved them.

For SugarCube+TypeScript users, I thank you for your hard work.

[tmedwards]

@ezsh BTW, for reference, what's the method to grab the definitions?

Based on the path name, I assume something like the following?

npm install --save-dev @types/twine-sugarcube

[ezsh]

Thank you! I pinged you here, but if you prefer, for the next update I'll do that from a PR.

@types/twine-sugarcube

Yes, that's the correct package name.

[tmedwards]

Leaving this open as a note to myself to put the Definitely Typed package information into the docs someplace.