Skip to content

Latest commit

 

History

History
81 lines (58 loc) · 2.67 KB

NOTES.md

File metadata and controls

81 lines (58 loc) · 2.67 KB

TypeScript

esbuild is a real stickler with extensions so it is necessary to require "parser.hera". TypeScript then needs a parser.hera.d.ts to work with CoffeeSense. Alternatively an esbuild resolver plugin could be used.

So far the clean way of handling it is to declare all the types in ./types/ and import then export = SomeType in the individual .d.ts files adjacent to the sources.

Building with tsc is not necessary if we're only using CoffeeScript sources since ./types/main.d.ts is pointed to by the type field in package.json. If there are other TypeScript sources then tsc will need to be involved in the build process.

export = vs export default

export = Something is necessary for Something = require('...') to get picked up properly. export default Something works with {default:Something} = require...

export = cannot be used with export {something}.

Since all the modern tools are moving in the direction of ES6 import/export it may simplify integration with some tools to also move in that direction.

Ambient Declarations

A typescript file that exports will ignore ambient declare statements. In order to have ambient they must all be declare.

Ambient declarations also cannot import other types but a work around is to use declare global and put vars inside there. See ./types/ambient.d.ts

Namespaces as types

Cannot use namespace 'Observable' as type.

use typeof Observable

TypeDoc

TypeDoc seems to work pretty good by default when using .ts files with ES6 style exports.

TypeDoc and other more modern tools strongly prefer ES6 module imports/exports. .d.ts files prefer it (there is no way to both export = and also have named exports even if those exports are just types).

JSDoc

JS written with JSDoc type annotations and compiled with tsc -d --allowJs will output type declarations.

CoffeeSense + TypeScript

VSCode Intellisense is the primary documentation target. That means that the docs should be optimized for how things appear in the IDE. 2nd target is a standalone website generated by TypeDoc or some other tool. Still need to test TypeDoc with a .coffee -> .js -> .d.ts -> TypeDoc pipeline and see how it goes.

Need to set checkJs to true or add #@ts-check to enable type checking in CoffeeSense.

It is possible to alias a bunch of imported types at the top to make using comments for inline types easier inside the file.

###*
@typedef {import("../types/types").Element} El
@typedef {import("../types/types").Context} Context
@typedef {import("../types/types").JadeletAttribute} JadeletAttribute
@typedef {import("../types/types").JadeletAST} JadeletAST
###