Skip to content

Commit 7ee2c8f

Browse files
Rokt33rhrajchert
authored andcommitted
Add typescript definitions
* Add type definitions, `dtslint`, type tests, and expose types in `package.json` * Add docs for `.data()` without arguments * Format readme Closes GH-43. Reviewed-by: Titus Wormer <[email protected]> Reviewed-by: Christian Murphy <[email protected]> Co-authored-by: Hernan Rajchert <[email protected]>
1 parent 7dc311b commit 7ee2c8f

File tree

6 files changed

+435
-6
lines changed

6 files changed

+435
-6
lines changed

package.json

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,15 @@
2020
"contributors": [
2121
"Titus Wormer <[email protected]> (https://wooorm.com)"
2222
],
23+
"types": "types/index.d.ts",
2324
"files": [
25+
"types/index.d.ts",
2426
"index.js",
2527
"lib"
2628
],
2729
"dependencies": {
30+
"@types/unist": "^2.0.0",
31+
"@types/vfile": "^3.0.0",
2832
"bail": "^1.0.0",
2933
"extend": "^3.0.0",
3034
"is-plain-obj": "^1.1.0",
@@ -34,22 +38,25 @@
3438
},
3539
"devDependencies": {
3640
"browserify": "^16.0.0",
41+
"dtslint": "^0.4.1",
3742
"esmangle": "^1.0.0",
3843
"nyc": "^13.0.0",
3944
"prettier": "^1.12.1",
4045
"remark-cli": "^6.0.0",
4146
"remark-preset-wooorm": "^4.0.0",
4247
"tape": "^4.4.0",
48+
"typescript": "^3.2.2",
4349
"xo": "^0.23.0"
4450
},
4551
"scripts": {
46-
"format": "remark . -qfo && prettier --write '**/*.js' && xo --fix",
52+
"format": "remark . -qfo && prettier --write '**/{*.js,*.ts}' && xo --fix",
4753
"build-bundle": "browserify index.js -s unified > unified.js",
4854
"build-mangle": "esmangle unified.js > unified.min.js",
4955
"build": "npm run build-bundle && npm run build-mangle",
5056
"test-api": "node test",
5157
"test-coverage": "nyc --reporter lcov tape test",
52-
"test": "npm run format && npm run build && npm run test-coverage"
58+
"test-types": "dtslint types",
59+
"test": "npm run format && npm run build && npm run test-coverage && npm run test-types"
5360
},
5461
"nyc": {
5562
"check-coverage": true,

readme.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ no issues found
119119
* [processor.runSync(node\[, file\])](#processorrunsyncnode-file)
120120
* [processor.process(file|value\[, done\])](#processorprocessfilevalue-done)
121121
* [processor.processSync(file|value)](#processorprocesssyncfilevalue)
122-
* [processor.data(key\[, value\])](#processordatakey-value)
122+
* [processor.data(\[key\[, value\]\])](#processordatakey-value)
123123
* [processor.freeze()](#processorfreeze)
124124
* [Plugin](#plugin)
125125
* [function attacher(\[options\])](#function-attacheroptions)
@@ -739,21 +739,22 @@ Yields:
739739
</html>
740740
```
741741

742-
### `processor.data(key[, value])`
742+
### `processor.data([key[, value]])`
743743

744744
Get or set information in an in-memory key-value store accessible to all phases
745745
of the process. An example is a list of HTML elements which are self-closing,
746746
which is needed when parsing, transforming, and compiling HTML.
747747

748748
###### Parameters
749749

750-
* `key` (`string`) — Identifier
750+
* `key` (`string`, optional) — Identifier
751751
* `value` (`*`, optional) — Value to set. Omit if getting `key`
752752

753753
###### Returns
754754

755755
* `processor` — If setting, the processor on which `data` is invoked
756756
* `*` — If getting, the value at `key`
757+
* `object` - Without arguments, the key-value store
757758

758759
###### Note
759760

@@ -767,9 +768,11 @@ The following example show how to get and set information:
767768
```js
768769
var unified = require('unified')
769770

770-
unified()
771+
var processor = unified()
771772
.data('alpha', 'bravo')
772773
.data('alpha') // => 'bravo'
774+
775+
processor.data() // {alpha: 'bravo'}
773776
```
774777

775778
### `processor.freeze()`

types/index.d.ts

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
// TypeScript Version: 3.0
2+
3+
import * as Unist from 'unist'
4+
import vfile = require('vfile')
5+
6+
declare namespace unified {
7+
interface Processor {
8+
/**
9+
* @returns New unfrozen processor which is configured to function the same as its ancestor. But when the descendant processor is configured in the future it does not affect the ancestral processor.
10+
*/
11+
(): Processor
12+
13+
/**
14+
* Configure the processor to use a plugin and optionally configure that plugin with options.
15+
*
16+
* @param plugin unified plugin
17+
* @param options Configuration for plugin]
18+
* @returns The processor on which use is invoked
19+
*/
20+
use(plugin: Plugin, options?: unknown): Processor
21+
/**
22+
* @param preset `Object` with an optional plugins (set to list), and/or an optional settings object
23+
*/
24+
use(preset: Preset): Processor
25+
/**
26+
* @param pluginTuple pairs, plugin and options in an array
27+
*/
28+
use(pluginTuple: PluginTuple): Processor
29+
/**
30+
* @param list List of plugins, presets, and pairs
31+
*/
32+
use(list: PluggableList): Processor
33+
34+
/**
35+
* Parse text to a syntax tree.
36+
*
37+
* @param file VFile or anything which can be given to vfile()
38+
* @returns Syntax tree representation of input.
39+
*/
40+
parse(file: VFileCompatible): Unist.Node
41+
42+
/**
43+
* Function handling the parsing of text to a syntax tree.
44+
* Used in the parse phase in the process and invoked with a `string` and `VFile` representation of the document to parse.
45+
*
46+
* `Parser` can be a normal function in which case it must return a `Node`: the syntax tree representation of the given file.
47+
*
48+
* `Parser` can also be a constructor function (a function with keys in its `prototype`) in which case it’s invoked with `new`. Instances must have a parse method which is invoked without arguments and must return a `Node`.
49+
*/
50+
Parser: ParserFunction | typeof Parser
51+
52+
/**
53+
* Compile a syntax tree to text.
54+
*
55+
* @param node
56+
* @param file `VFile` or anything which can be given to `vfile()`
57+
* @returns String representation of the syntax tree file
58+
*/
59+
stringify(node: Unist.Node, file?: VFileCompatible): string
60+
61+
/**
62+
* Function handling the compilation of syntax tree to a text.
63+
* Used in the stringify phase in the process and invoked with a `Node` and `VFile` representation of the document to stringify.
64+
*
65+
* `Compiler` can be a normal function in which case it must return a `string`: the text representation of the given syntax tree.
66+
*
67+
* `Compiler` can also be a constructor function (a function with keys in its `prototype`) in which case it’s invoked with `new`.
68+
* Instances must have a `compile` method which is invoked without arguments and must return a `string`.
69+
*/
70+
Compiler: CompilerFunction | typeof Compiler
71+
72+
/**
73+
* Transform a syntax tree by applying plugins to it.
74+
*
75+
* @param node
76+
* @param file `VFile` or anything which can be given to `vfile()`
77+
* @param done Invoked when transformation is complete.
78+
* Either invoked with an error or a syntax tree and a file.
79+
* @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree.
80+
*/
81+
run(node: Unist.Node): Promise<Unist.Node>
82+
run(node: Unist.Node, file: VFileCompatible): Promise<Unist.Node>
83+
run(node: Unist.Node, done: RunCallback): void
84+
run(node: Unist.Node, file: VFileCompatible, done: RunCallback): void
85+
86+
/**
87+
* Transform a syntax tree by applying plugins to it.
88+
*
89+
* If asynchronous plugins are configured an error is thrown.
90+
*
91+
* @param node
92+
* @param file `VFile` or anything which can be given to `vfile()`
93+
* @returns The given syntax tree.
94+
*/
95+
runSync(node: Unist.Node, file?: VFileCompatible): Unist.Node
96+
97+
/**
98+
* Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally.
99+
* @param file
100+
* @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile.
101+
* @returns `Promise` if `done` is not given.
102+
* Rejected with an error or resolved with the resulting file.
103+
*/
104+
process(file: VFileCompatible): Promise<vfile.VFile>
105+
process(file: VFileCompatible, done: ProcessCallback): void
106+
107+
/**
108+
* Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally.
109+
*
110+
* If asynchronous plugins are configured an error is thrown.
111+
*
112+
* @param file
113+
* @returns Virtual file with modified contents.
114+
*/
115+
processSync(file: VFileCompatible): vfile.VFile
116+
117+
/**
118+
* Get or set information in an in-memory key-value store accessible to all phases of the process.
119+
* An example is a list of HTML elements which are self-closing, which is needed when parsing, transforming, and compiling HTML.
120+
*
121+
* @returns key-value store object
122+
*/
123+
data(): {[key: string]: unknown}
124+
/**
125+
* @param key Identifier
126+
* @returns If getting, the value at key
127+
*/
128+
data(key: string): unknown
129+
/**
130+
* @param value Value to set. Omit if getting key
131+
* @returns If setting, the processor on which data is invoked
132+
*/
133+
data(key: string, value: any): Processor
134+
135+
/**
136+
* Freeze a processor. Frozen processors are meant to be extended and not to be configured or processed directly.
137+
*
138+
* Once a processor is frozen it cannot be unfrozen. New processors functioning just like it can be created by invoking the processor.
139+
*
140+
* It’s possible to freeze processors explicitly, by calling `.freeze()`, but `.parse()`, `.run()`, `.stringify()`, and `.process()` call `.freeze()` to freeze a processor too.
141+
*
142+
* @returns The processor on which freeze is invoked.
143+
*/
144+
freeze(): Processor
145+
}
146+
147+
type Plugin = Attacher
148+
type Settings = {
149+
[key: string]: unknown
150+
}
151+
/**
152+
* Presets provide a potentially sharable way to configure processors.
153+
* They can contain multiple plugins and optionally settings as well.
154+
*/
155+
interface Preset {
156+
plugins?: PluggableList
157+
settings?: Settings
158+
}
159+
type PluginTuple = [Plugin, Settings]
160+
type Pluggable = Plugin | Preset | PluginTuple
161+
type PluggableList = Pluggable[]
162+
163+
/**
164+
* An attacher is the thing passed to `use`.
165+
* It configures the processor and in turn can receive options.
166+
*
167+
* Attachers can configure processors, such as by interacting with parsers and compilers, linking them to other processors, or by specifying how the syntax tree is handled.
168+
*
169+
* @this Processor context object is set to the invoked on processor.
170+
* @param options Configuration
171+
* @returns Optional.
172+
*/
173+
interface Attacher {
174+
(this: Processor, options?: unknown): Transformer | void
175+
}
176+
177+
/**
178+
* Transformers modify the syntax tree or metadata of a file. A transformer is a function which is invoked each time a file is passed through the transform phase.
179+
* If an error occurs (either because it’s thrown, returned, rejected, or passed to `next`), the process stops.
180+
*
181+
* The transformation process in unified is handled by `trough`, see it’s documentation for the exact semantics of transformers.
182+
*
183+
* @param node
184+
* @param file
185+
* @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`.
186+
* @returns
187+
* - `Error` — Can be returned to stop the process
188+
* - `Node` — Can be returned and results in further transformations and `stringify`s to be performed on the new tree
189+
* - `Promise` — If a promise is returned, the function is asynchronous, and must be resolved (optionally with a `Node`) or rejected (optionally with an `Error`)
190+
*/
191+
interface Transformer {
192+
(
193+
node: Unist.Node,
194+
file: VFileCompatible,
195+
next?: (error: Error | null, tree: Unist.Node, file: vfile.VFile) => {}
196+
): Error | Unist.Node | Promise<Unist.Node>
197+
}
198+
199+
class Parser {
200+
parse(file: VFileCompatible): Unist.Node
201+
}
202+
203+
type ParserFunction = (file: VFileCompatible) => Unist.Node
204+
205+
class Compiler {
206+
compile(node: Unist.Node, file?: VFileCompatible): string
207+
}
208+
type CompilerFunction = (node: Unist.Node, file?: VFileCompatible) => string
209+
210+
type RunCallback = (
211+
error: Error | null,
212+
node: Unist.Node,
213+
file: vfile.VFile
214+
) => void
215+
216+
type ProcessCallback = (error: Error | null, file: vfile.VFile) => void
217+
218+
type VFileCompatible = vfile.VFile | vfile.VFileOptions | vfile.VFileContents
219+
}
220+
221+
/**
222+
* Object describing how to process text.
223+
*/
224+
declare function unified(): unified.Processor
225+
226+
export = unified

types/tsconfig.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"compilerOptions": {
3+
"lib": ["es2015"],
4+
"strict": true,
5+
"noImplicitAny": true,
6+
"noImplicitThis": true,
7+
"strictNullChecks": true,
8+
"strictFunctionTypes": true,
9+
"baseUrl": ".",
10+
"paths": {
11+
"unified": ["index.d.ts"]
12+
}
13+
}
14+
}

types/tslint.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"extends": "dtslint/dtslint.json",
3+
"rules": {
4+
"callable-types": false,
5+
"max-line-length": false,
6+
"no-redundant-jsdoc": false,
7+
"no-void-expression": false,
8+
"only-arrow-functions": false,
9+
"semicolon": false,
10+
"unified-signatures": false,
11+
"whitespace": false,
12+
"interface-over-type-literal": false
13+
}
14+
}

0 commit comments

Comments
 (0)