types: add type definitions for micromark #17

ChristianMurphy · 2020-09-10T23:15:26Z

alternative to #16

ChristianMurphy · 2020-09-10T23:25:51Z

/cc @Rokt33r @Murderlon @remcohaszing @BarryThePenguin

ChristianMurphy · 2020-09-11T02:58:08Z

shared-types.d.ts

+    notSureWhatThisIs:
+      | Construct
+      | Construct[]
+      | {[code: number]: Construct | Construct[]},


What is this construct like parameter called?

I dunno!

I’ve been calling the third form “hooks”, as it defines which character codes are “hooked”. But that doesn’t say too much.

Maybe something like “usable” in unified? Attempt?

ChristianMurphy · 2020-09-11T02:58:43Z

shared-types.d.ts

+  write: (value: number) => Event[]
+}
+
+export type Construct = unknown


What is a construct?
Is it a function?

A construct is an object with:

a tokenize function

resolve, resolveTo, and resolveAll functions (which take a certain slice of events and can mutate them)

partial (bit ugly, used for things that aren’t really constructs, like whitespace)

concrete, used for multiline constructs such as HTML and fenced code that and how they mix with containers (e.g., > <div>\n> > this is html, not a second block quote)

Content has a name

ChristianMurphy · 2020-09-11T03:00:23Z

shared-types.d.ts

+/**
+ *
+ */
+export type Okay = (code: number) => () => void


Does the inner function have any parameters?

Should the params in check/lazy/interrupt also be called “returnState” and “bogusState”.

The tokenizer function gets effects, ok, nok, which is kind of like the executor function given to Promise: resolve, reject.
On the outside, you can pass returnState, bogusState, which is kind of like the functions given to then: onfulfill, onreject

They all get character codes

All these functions also should return another function: the next state-as-a-function to go to.
But there is one case where they return void: for the eof character code (at the end of a value)
The reason being: well, there isn’t any state that makes sense, so void works well. Practically that has also helped: if for some reason it was a mistake, then an exception is throw because there is no next function, meaning it surfaces early.

meritozh · 2020-09-11T03:25:30Z

I don't think syncing type definitions manually is a better way. *.d.ts should be generated by tsc.

ChristianMurphy · 2020-09-11T04:21:11Z

@meritozh originally micromark was going to be in TypeScript (see remarkjs/remark#439 and #4) however the direction changed. Bringing back native typescript was proposed again and declined #16 (comment).

This has also been discussed before in unifiedjs/unified#76, most of the rest of unified also has typings files rather than being native TypeScript (see: https://github.com/search?p=2&q=org%3Asyntax-tree+typescript&type=Issues and https://github.com/search?q=org%3Aunifiedjs+typescript&type=Issues)
There is also a general propals to use JSDoc to run TypeScript unifiedjs/rfcs#5, which is stalled at the moment.

If you want to move native TypeScript or jsdoc based TypeScript forward, starting a thread at https://github.com/micromark/micromark/discussions would be a good place to have the discussion.
Tacking the discussion on to this PR, is not a good place to restart that broad discussion.

wooorm · 2020-09-11T07:05:23Z

shared-types.d.ts

+/**
+ *
+ */
+export type Okay = (code: number) => () => void


Should the params in check/lazy/interrupt also be called “returnState” and “bogusState”.

The tokenizer function gets effects, ok, nok, which is kind of like the executor function given to Promise: resolve, reject.
On the outside, you can pass returnState, bogusState, which is kind of like the functions given to then: onfulfill, onreject

They all get character codes

wooorm · 2020-09-11T07:08:10Z

shared-types.d.ts

+/**
+ *
+ */
+export type Okay = (code: number) => () => void


All these functions also should return another function: the next state-as-a-function to go to.
But there is one case where they return void: for the eof character code (at the end of a value)
The reason being: well, there isn’t any state that makes sense, so void works well. Practically that has also helped: if for some reason it was a mistake, then an exception is throw because there is no next function, meaning it surfaces early.

wooorm · 2020-09-11T07:17:20Z

shared-types.d.ts

+  write: (value: number) => Event[]
+}
+
+export type Construct = unknown


A construct is an object with:

a tokenize function

resolve, resolveTo, and resolveAll functions (which take a certain slice of events and can mutate them)

partial (bit ugly, used for things that aren’t really constructs, like whitespace)

concrete, used for multiline constructs such as HTML and fenced code that and how they mix with containers (e.g., > <div>\n> > this is html, not a second block quote)

Content has a name

wooorm · 2020-09-11T07:20:21Z

shared-types.d.ts

+  /**
+   * Consume deals with a character, and moves to the next
+   */
+  consume: (code: number) => void


Would it be a good idea to make a specific type for the character codes?

It can be any result (positive int) from String.charCodeAt (except NaN). And the following special codes are used:

micromark/lib/character/codes.js

Lines 1 to 7 in 005ad17

// This module is compiled away!

exports.carriageReturn = -5

exports.lineFeed = -4

exports.carriageReturnLineFeed = -3

exports.horizontalTab = -2

exports.virtualSpace = -1

exports.eof = null

It could be a good idea.
Both the known types and character codes could be turned in a union of known types or turned into an opaque type, currently both are transparent primitives.

If micromark is written in native TypeScript, we can use TypeScript's const enum feature for these constant values.

By using const enum, those import statements will be removed while compiling (just like what script/babel-transform-constants.js does). And we also have an easy way to define types for character codes.

However, TypeScript doesn't allow null as a value of const enum, so we have to do something special for eof.

wooorm · 2020-09-11T07:22:35Z

shared-types.d.ts

+  column: number
+  offset: number
+  _index?: number
+  _bufferIndex?: number


For the underscore props, as those are kinda for internal use in this project, should they be left undocumented?

Is there some comment to add here to say to TS that it shouldn’t be exported to library users?

We could tag these with tsdoc

/** * @internal */

I'm cautious about removing them entirely, since extensions/plugins may leverage some of the internal attributes.

wooorm · 2020-09-11T07:24:18Z

lib/compile/html.d.ts

@@ -0,0 +1,3 @@
+declare function compileHTML(): void


compileHtml?

ChristianMurphy · 2020-10-03T23:49:00Z

closing in favor of #25 which builds on this

ChristianMurphy force-pushed the types/add-typings branch from fe3cb66 to 27a2530 Compare September 10, 2020 23:16

ChristianMurphy requested review from a team September 10, 2020 23:22

ChristianMurphy added ☂️ area/types This affects typings 🛠 blocked/wip This cannot progress yet, it’s being worked on 🦋 type/enhancement This is great to have labels Sep 10, 2020

ChristianMurphy force-pushed the types/add-typings branch 4 times, most recently from 47ce9a1 to 9f0c358 Compare September 10, 2020 23:55

This comment has been minimized.

Sign in to view

ChristianMurphy force-pushed the types/add-typings branch from 9f0c358 to 9aca9bc Compare September 11, 2020 00:20

ChristianMurphy added the help wanted 🙏 This could use your insight or help label Sep 11, 2020

types: add type definitions for micromark

8f64181

ChristianMurphy force-pushed the types/add-typings branch from 9aca9bc to 8f64181 Compare September 11, 2020 02:57

ChristianMurphy commented Sep 11, 2020

View reviewed changes

ChristianMurphy mentioned this pull request Sep 11, 2020

[WIP] migrate to typescript #16

Closed

ChristianMurphy commented Sep 11, 2020

View reviewed changes

wooorm reviewed Sep 11, 2020

View reviewed changes

ChristianMurphy mentioned this pull request Sep 20, 2020

Provide typescript definitions syntax-tree/mdast-util-from-markdown#1

Closed

ocavue mentioned this pull request Oct 3, 2020

Add types #25

Merged

ChristianMurphy closed this Oct 3, 2020

wooorm removed help wanted 🙏 This could use your insight or help 🛠 blocked/wip This cannot progress yet, it’s being worked on 🦋 type/enhancement This is great to have labels Oct 4, 2020

wooorm added the 🤷 no/invalid This cannot be acted upon label Oct 4, 2020

ChristianMurphy deleted the types/add-typings branch December 30, 2021 20:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

types: add type definitions for micromark #17

types: add type definitions for micromark #17

ChristianMurphy commented Sep 10, 2020

ChristianMurphy commented Sep 10, 2020

This comment has been minimized.

ChristianMurphy Sep 11, 2020

wooorm Sep 11, 2020

ChristianMurphy Sep 11, 2020

wooorm Sep 11, 2020

ChristianMurphy Sep 11, 2020

wooorm Sep 11, 2020

wooorm Sep 11, 2020

meritozh commented Sep 11, 2020

ChristianMurphy commented Sep 11, 2020

wooorm Sep 11, 2020

wooorm Sep 11, 2020

wooorm Sep 11, 2020

wooorm Sep 11, 2020

ChristianMurphy Sep 11, 2020

ocavue Oct 3, 2020 •

edited

wooorm Sep 11, 2020

ChristianMurphy Sep 11, 2020

wooorm Sep 11, 2020

ChristianMurphy commented Oct 3, 2020

	// This module is compiled away!
	exports.carriageReturn = -5
	exports.lineFeed = -4
	exports.carriageReturnLineFeed = -3
	exports.horizontalTab = -2
	exports.virtualSpace = -1
	exports.eof = null

types: add type definitions for micromark #17

types: add type definitions for micromark #17

Conversation

ChristianMurphy commented Sep 10, 2020

ChristianMurphy commented Sep 10, 2020

This comment has been minimized.

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

meritozh commented Sep 11, 2020

ChristianMurphy commented Sep 11, 2020

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

ocavue Oct 3, 2020 • 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

ChristianMurphy commented Oct 3, 2020

ocavue Oct 3, 2020 •

edited