0
# Jest Docblock
1

2
Jest Docblock is a TypeScript library that extracts, parses, and manipulates specially-formatted JavaScript/TypeScript comments called "docblocks" that appear at the top of files. It provides functionality to process file-level metadata embedded in source code comments, making it essential for build tools, documentation generators, and code analysis systems.
3

4
## Package Information
5

6
- **Package Name**: jest-docblock
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jest-docblock`
10

11
## Core Imports
12

13
```typescript
14
import { extract, strip, parse, parseWithComments, print } from "jest-docblock";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { extract, strip, parse, parseWithComments, print } = require("jest-docblock");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { extract, strip, parse, parseWithComments, print } from "jest-docblock";
27

28
const code = `
29
/**
30
 * Everything is awesome!
31
 *
32
 * @everything is:awesome
33
 * @flow
34
 */
35

36
export const everything = Object.create(null);
37
export default function isAwesome(something) {
38
  return something === everything;
39
}
40
`;
41

42
// Extract the docblock
43
const docblock = extract(code);
44
console.log(docblock); // "/**\n * Everything is awesome!\n * \n * @everything is:awesome\n * @flow\n */"
45

46
// Strip the docblock from code
47
const stripped = strip(code);
48
console.log(stripped); // "export const everything = Object.create(null);\n export default function isAwesome(something) {\n return something === everything;\n }"
49

50
// Parse pragmas only
51
const pragmas = parse(docblock);
52
console.log(pragmas); // { everything: "is:awesome", flow: "" }
53

54
// Parse both comments and pragmas
55
const parsed = parseWithComments(docblock);
56
console.log(parsed); // { comments: "Everything is awesome!", pragmas: { everything: "is:awesome", flow: "" } }
57

58
// Print back to docblock format
59
console.log(print({ comments: "hi!", pragmas })); // /**\n * hi!\n *\n * @everything is:awesome\n * @flow\n */
60

61
// Handle multiple values for the same pragma
62
const multiPragmaCode = `
63
/**
64
 * @x foo
65
 * @x bar
66
 * @y baz
67
 */
68
`;
69
const multiResult = parse(extract(multiPragmaCode));
70
console.log(multiResult); // { x: ["foo", "bar"], y: "baz" }
71

72
// Work with regular block comments
73
const regularComment = "/* @flow */";
74
console.log(parse(regularComment)); // { flow: "" }
75
```
76

77
## Capabilities
78

79
### Docblock Extraction
80

81
Extracts a docblock from file contents. Returns the complete docblock if found, or an empty string if no docblock exists at the beginning of the file.
82

83
```typescript { .api }
84
/**
85
 * Extracts a docblock from some file contents
86
 * @param contents - Source code string to extract docblock from
87
 * @returns The extracted docblock or empty string if none found
88
 */
89
function extract(contents: string): string;
90
```
91

92
### Docblock Removal
93

94
Strips the top docblock from a file and returns the remaining content. If no docblock exists at the top of the file, returns the original content unchanged.
95

96
```typescript { .api }
97
/**
98
 * Strips the top docblock from a file and return the result
99
 * @param contents - Source code string to strip docblock from
100
 * @returns Source code with docblock removed, or original if no docblock found
101
 */
102
function strip(contents: string): string;
103
```
104

105
### Pragma Parsing
106

107
Parses the pragmas (annotations prefixed with @) in a docblock string into a structured object. Each pragma becomes a key-value pair where the key is the pragma name and the value is either a string or array of strings for multiple values.
108

109
```typescript { .api }
110
/**
111
 * Parses the pragmas in a docblock string into an object
112
 * @param docblock - Docblock string to parse
113
 * @returns Object with pragma keys and their values
114
 */
115
function parse(docblock: string): Pragmas;
116
```
117

118
### Comment and Pragma Parsing
119

120
Similar to `parse`, but also extracts the comment text separate from the pragma annotations. This is useful when you need to preserve both the textual content and the structured metadata.
121

122
```typescript { .api }
123
/**
124
 * Parses both comments and pragmas from a docblock
125
 * @param docblock - Docblock string to parse
126
 * @returns Object containing both comments and pragmas
127
 */
128
function parseWithComments(docblock: string): {
129
  comments: string;
130
  pragmas: Pragmas;
131
};
132
```
133

134
### Docblock Generation
135

136
Formats comments and pragmas back into a properly formatted docblock string. This allows you to programmatically create or modify docblocks.
137

138
```typescript { .api }
139
/**
140
 * Prints an object of key-value pairs back into a docblock
141
 * @param options - Configuration object
142
 * @param options.comments - Comment text to include
143
 * @param options.pragmas - Pragma key-value pairs to include
144
 * @returns Formatted docblock string
145
 */
146
function print(options: {
147
  comments?: string;
148
  pragmas?: Pragmas;
149
}): string;
150
```
151

152
## Types
153

154
```typescript { .api }
155
/**
156
 * Type representing parsed pragma key-value pairs
157
 * Values can be strings or arrays of strings for multiple values
158
 */
159
type Pragmas = Record<string, string | Array<string>>;
160
```
161

162
## Features
163

164
### Multi-line Pragma Support
165

166
The library handles pragmas that span multiple lines by normalizing them into single-line values:
167

168
```typescript
169
const docblock = `/**
170
 * @class A long declaration of a class
171
 *        goes here, so we can read it and enjoy
172
 */`;
173

174
const result = parse(docblock);
175
// { class: "A long declaration of a class goes here, so we can read it and enjoy" }
176
```
177

178
### Multiple Pragma Values
179

180
When the same pragma appears multiple times, values are collected into an array:
181

182
```typescript
183
const docblock = `/**
184
 * @x foo
185
 * @x bar
186
 * @y baz
187
 */`;
188

189
const result = parse(docblock);
190
// { x: ["foo", "bar"], y: "baz" }
191
```
192

193
### Cross-platform Newline Support
194

195
The library automatically detects and preserves the newline style (LF or CRLF) used in the original docblock:
196

197
```typescript
198
// CRLF input produces CRLF output
199
const crlfDocblock = "/**\r\n * foo\r\n * bar\r\n*/";
200
const parsed = parseWithComments(crlfDocblock);
201
// parsed.comments === "foo\r\nbar"
202

203
// LF input produces LF output  
204
const lfDocblock = "/**\n * foo\n * bar\n*/";
205
const parsed2 = parseWithComments(lfDocblock);
206
// parsed2.comments === "foo\nbar"
207
```
208

209
### URL and Special Character Support
210

211
The library preserves URLs and special characters (including slashes) within pragma values:
212

213
```typescript
214
// URLs are preserved in pragma values
215
const urlDocblock = `/**
216
 * @see: https://example.com
217
 */`;
218
const urlResult = parse(urlDocblock);
219
// { "see:": "https://example.com" }
220

221
// Slashes in pragma values are supported
222
const teamDocblock = `/**
223
 * @team apple/banana
224
 */`;
225
const teamResult = parse(teamDocblock);
226
// { team: "apple/banana" }
227
```
228

229
### Comment Types Support
230

231
The library works with both JSDoc-style comments (`/** */`) and regular block comments (`/* */`):
232

233
```typescript
234
// Both formats are parsed identically
235
const jsdoc = "/** @flow */";
236
const regular = "/* @flow */";
237

238
parse(jsdoc);   // { flow: "" }
239
parse(regular); // { flow: "" }
240
```
241

242
### Line Comment Handling
243

244
Line comments within docblocks are preserved in comment text but stripped from pragma values:
245

246
```typescript
247
const docblock = `/**
248
 * This is a comment
249
 * @format everything
250
 * // This line comment is preserved
251
 */`;
252

253
const result = parseWithComments(docblock);
254
// {
255
//   comments: "This is a comment\n// This line comment is preserved",
256
//   pragmas: { format: "everything" }
257
// }
258

259
// Line comments are stripped from pragma values but preserved in comments
260
const pragmaWithComment = `/**
261
 * @format: everything
262
 * // keep me
263
 */`;
264

265
const pragmaResult = parseWithComments(pragmaWithComment);
266
// {
267
//   comments: "// keep me",
268
//   pragmas: { "format:": "everything" }
269
// }
270
```
271

272
### Leading Whitespace Preservation
273

274
The library preserves leading whitespace in multiline comments:
275

276
```typescript
277
const whitespaceDocblock = `/**
278
 *  hello
279
 *   world
280
 */`;
281

282
const whitespaceResult = parseWithComments(whitespaceDocblock);
283
// whitespaceResult.comments === " hello\n  world"
284
```
285

286
### Leading Newline Removal
287

288
Leading newlines are automatically removed from extracted comments:
289

290
```typescript
291
const leadingNewlineDocblock = `/**
292
 * @snailcode
293
 *
294
 *  hello world
295
 */`;
296

297
const leadingResult = parseWithComments(leadingNewlineDocblock);
298
// leadingResult.comments === " hello world"
299
// Leading newline after pragma is removed
300
```