or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-jest-docblock

A package that can extract and parse a specially-formatted comment called a 'docblock' at the top of a file.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jest-docblock@30.0.x

To install, run

npx @tessl/cli install tessl/npm-jest-docblock@30.0.0

index.mddocs/

Jest Docblock

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.

Package Information

  • Package Name: jest-docblock
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install jest-docblock

Core Imports

import { extract, strip, parse, parseWithComments, print } from "jest-docblock";

For CommonJS:

const { extract, strip, parse, parseWithComments, print } = require("jest-docblock");

Basic Usage

import { extract, strip, parse, parseWithComments, print } from "jest-docblock";

const code = `
/**
 * Everything is awesome!
 *
 * @everything is:awesome
 * @flow
 */

export const everything = Object.create(null);
export default function isAwesome(something) {
  return something === everything;
}
`;

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

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

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

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

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

// Handle multiple values for the same pragma
const multiPragmaCode = `
/**
 * @x foo
 * @x bar
 * @y baz
 */
`;
const multiResult = parse(extract(multiPragmaCode));
console.log(multiResult); // { x: ["foo", "bar"], y: "baz" }

// Work with regular block comments
const regularComment = "/* @flow */";
console.log(parse(regularComment)); // { flow: "" }

Capabilities

Docblock Extraction

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.

/**
 * Extracts a docblock from some file contents
 * @param contents - Source code string to extract docblock from
 * @returns The extracted docblock or empty string if none found
 */
function extract(contents: string): string;

Docblock Removal

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.

/**
 * Strips the top docblock from a file and return the result
 * @param contents - Source code string to strip docblock from
 * @returns Source code with docblock removed, or original if no docblock found
 */
function strip(contents: string): string;

Pragma Parsing

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.

/**
 * Parses the pragmas in a docblock string into an object
 * @param docblock - Docblock string to parse
 * @returns Object with pragma keys and their values
 */
function parse(docblock: string): Pragmas;

Comment and Pragma Parsing

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.

/**
 * Parses both comments and pragmas from a docblock
 * @param docblock - Docblock string to parse
 * @returns Object containing both comments and pragmas
 */
function parseWithComments(docblock: string): {
  comments: string;
  pragmas: Pragmas;
};

Docblock Generation

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

/**
 * Prints an object of key-value pairs back into a docblock
 * @param options - Configuration object
 * @param options.comments - Comment text to include
 * @param options.pragmas - Pragma key-value pairs to include
 * @returns Formatted docblock string
 */
function print(options: {
  comments?: string;
  pragmas?: Pragmas;
}): string;

Types

/**
 * Type representing parsed pragma key-value pairs
 * Values can be strings or arrays of strings for multiple values
 */
type Pragmas = Record<string, string | Array<string>>;

Features

Multi-line Pragma Support

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

const docblock = `/**
 * @class A long declaration of a class
 *        goes here, so we can read it and enjoy
 */`;

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

Multiple Pragma Values

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

const docblock = `/**
 * @x foo
 * @x bar
 * @y baz
 */`;

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

Cross-platform Newline Support

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

// CRLF input produces CRLF output
const crlfDocblock = "/**\r\n * foo\r\n * bar\r\n*/";
const parsed = parseWithComments(crlfDocblock);
// parsed.comments === "foo\r\nbar"

// LF input produces LF output  
const lfDocblock = "/**\n * foo\n * bar\n*/";
const parsed2 = parseWithComments(lfDocblock);
// parsed2.comments === "foo\nbar"

URL and Special Character Support

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

// URLs are preserved in pragma values
const urlDocblock = `/**
 * @see: https://example.com
 */`;
const urlResult = parse(urlDocblock);
// { "see:": "https://example.com" }

// Slashes in pragma values are supported
const teamDocblock = `/**
 * @team apple/banana
 */`;
const teamResult = parse(teamDocblock);
// { team: "apple/banana" }

Comment Types Support

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

// Both formats are parsed identically
const jsdoc = "/** @flow */";
const regular = "/* @flow */";

parse(jsdoc);   // { flow: "" }
parse(regular); // { flow: "" }

Line Comment Handling

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

const docblock = `/**
 * This is a comment
 * @format everything
 * // This line comment is preserved
 */`;

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

// Line comments are stripped from pragma values but preserved in comments
const pragmaWithComment = `/**
 * @format: everything
 * // keep me
 */`;

const pragmaResult = parseWithComments(pragmaWithComment);
// {
//   comments: "// keep me",
//   pragmas: { "format:": "everything" }
// }

Leading Whitespace Preservation

The library preserves leading whitespace in multiline comments:

const whitespaceDocblock = `/**
 *  hello
 *   world
 */`;

const whitespaceResult = parseWithComments(whitespaceDocblock);
// whitespaceResult.comments === " hello\n  world"

Leading Newline Removal

Leading newlines are automatically removed from extracted comments:

const leadingNewlineDocblock = `/**
 * @snailcode
 *
 *  hello world
 */`;

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