diff --git a/types/vfile-message/index.d.ts b/types/vfile-message/index.d.ts new file mode 100644 index 0000000000..908f72027b --- /dev/null +++ b/types/vfile-message/index.d.ts @@ -0,0 +1,79 @@ +// Type definitions for vfile-message 1.0 +// Project: https://github.com/vfile/vfile-message#readme +// Definitions by: Junyoung Choi +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 3.0 + +/// + +import * as Unist from 'unist'; + +declare namespace vfileMessage { + interface AnyNode extends Unist.Node { + [key: string]: unknown; + } + + /** + * Create a virtual message. + */ + interface VFileMessage extends Error { + /** + * Constructor of a message for `reason` at `position` from `origin`. + * When an error is passed in as `reason`, copies the `stack`. + * + * @param reason Reason for message (`string` or `Error`). Uses the stack and message of the error if given. + * @param position Place at which the message occurred in a file (`Node`, `Position`, or `Point`, optional). + * @param origin Place in code the message originates from (`string`, optional). + */ + (reason: string | Error, position?: AnyNode | Unist.Position | Unist.Point, origin?: string): VFileMessage; + /** + * Category of message. + */ + ruleId: string | null; + /** + * Reason for message. + */ + reason: string; + /** + * Starting line of error. + */ + line: number | null; + /** + * Starting column of error. + */ + column: number | null; + /** + * Full range information, when available. + * Has start and end properties, both set to an object with line and column, set to number?. + */ + location: Unist.Position; + /** + * Namespace of warning. + */ + source: string | null; + /** + * If true, marks associated file as no longer processable. + */ + fatal?: boolean | null; + /** + * You may add a file property with a path of a file (used throughout the VFile ecosystem). + */ + file?: string; + /** + * You may add a note property with a long form description of the message (supported by vfile-reporter). + */ + note?: string; + /** + * You may add a url property with a link to documentation for the message. + */ + url?: string; + /** + * It’s OK to store custom data directly on the VMessage, some of those are handled by utilities. + */ + [key: string]: unknown; + } +} + +declare const vfileMessage: vfileMessage.VFileMessage; + +export = vfileMessage; diff --git a/types/vfile-message/tsconfig.json b/types/vfile-message/tsconfig.json new file mode 100644 index 0000000000..9e35438c08 --- /dev/null +++ b/types/vfile-message/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "vfile-message-tests.ts" + ] +} diff --git a/types/vfile-message/tslint.json b/types/vfile-message/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/vfile-message/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" } diff --git a/types/vfile-message/vfile-message-tests.ts b/types/vfile-message/vfile-message-tests.ts new file mode 100644 index 0000000000..ed9086631f --- /dev/null +++ b/types/vfile-message/vfile-message-tests.ts @@ -0,0 +1,32 @@ +import vfileMessage = require('vfile-message'); + +const message = vfileMessage('Error!'); +vfileMessage(new Error()); +vfileMessage('Error!', { + type: 'random node' +}); +vfileMessage('Error!', { + start: { + line: 1, + column: 1 + }, + end: { + line: 1, + column: 1 + } +}); +vfileMessage('Error!', { + line: 1, + column: 1 +}); +vfileMessage('Error!', undefined, 'test'); + +message.file = ''; +message.name = ''; +message.reason = ''; +message.message = ''; +message.stack = ''; +message.fatal = null; +message.fatal = true; +message.column = 1; +message.line = 1; diff --git a/types/vfile/index.d.ts b/types/vfile/index.d.ts index df729e0a49..efb07e288d 100644 --- a/types/vfile/index.d.ts +++ b/types/vfile/index.d.ts @@ -8,15 +8,11 @@ /// import * as Unist from 'unist'; +import * as vfileMessage from 'vfile-message'; declare namespace vfile { type VFileContents = string | Buffer; - interface NodeWithPosition extends Unist.Node { - position: Unist.Position; - [key: string]: any; - } - interface VFileOptions { contents?: VFileContents; path?: string; @@ -29,86 +25,18 @@ declare namespace vfile { [key: string]: any; } - /** - * File-related message describing something at certain position. - */ - interface VFileMessage { - /** - * File-path, when the message was triggered. - */ - file: string; - /** - * Category of message. - */ - ruleId: string | null; - /** - * Reason for message. - */ - reason: string; - /** - * Starting line of error. - */ - line: number | null; - /** - * Starting column of error. - */ - column: number | null; - /** - * Full range information, when available. - * Has start and end properties, both set to an object with line and column, set to number?. - */ - location: Unist.Position; - /** - * Namespace of warning. - */ - source: string | null; - /** - * If true, marks associated file as no longer processable. - */ - fatal?: boolean | null; - } - - /** - * Associates a message with the file for `reason` at `position`. - * When an error is passed in as `reason`, copies the stack. - * Each message has a `fatal` property which by default is set to `false` (ie. `warning`). - * @param reason Reason for message. Uses the stack and message of the error if given. - * @param position Place at which the message occurred in `vfile`. - * @param ruleId Category of message. - */ - type Message = (reason: string, position?: Unist.Point | Unist.Position | NodeWithPosition, ruleId?: string) => VFileMessage; - /** - * Associates a fatal message with the file, then immediately throws it. - * Note: fatal errors mean a file is no longer processable. - * Calls `message()` internally. - * @param reason Reason for message. Uses the stack and message of the error if given. - * @param position Place at which the message occurred in `vfile`. - * @param ruleId Category of message. - */ - type Fail = (reason: string, position?: Unist.Point | Unist.Position | NodeWithPosition, ruleId?: string) => never; - /** - * Associates an informational message with the file, where `fatal` is set to `null`. - * Calls `message()` internally. - * @param reason Reason for message. Uses the stack and message of the error if given. - * @param position Place at which the message occurred in `vfile`. - * @param ruleId Category of message. - */ - type Info = (reason: string, position?: Unist.Point | Unist.Position | NodeWithPosition, ruleId?: string) => void; - - /** - * Convert contents of `vfile` to string. - * @param encoding If `contents` is a buffer, `encoding` is used to stringify buffers (default: `'utf8'`). - */ - type ToString = (encoding?: BufferEncoding) => string; - interface VFile { /** + * Create a new virtual file. If `options` is `string` or `Buffer`, treats it as `{contents: options}`. + * If `options` is a `VFile`, returns it. All other options are set on the newly created `vfile`. + * + * Path related properties are set in the following order (least specific to most specific): `history`, `path`, `basename`, `stem`, `extname`, `dirname`. + * + * It’s not possible to set either `dirname` or `extname` without setting either `history`, `path`, `basename`, or `stem` as well. + * * @param options If `options` is `string` or `Buffer`, treats it as `{contents: options}`. If `options` is a `VFile`, returns it. All other options are set on the newly created `vfile`. */ (input?: VFileContents | F | VFileOptions): F; - message: Message; - fail: Fail; - info: Info; /** * List of file-paths the file moved between. */ @@ -121,7 +49,7 @@ declare namespace vfile { /** * List of messages associated with the file. */ - messages: VFileMessage[]; + messages: vfileMessage.VFileMessage[]; /** * Raw value. */ @@ -157,15 +85,40 @@ declare namespace vfile { * Defaults to `process.cwd()`. */ cwd: string; - toString: ToString; + /** + * Convert contents of `vfile` to string. + * @param encoding If `contents` is a buffer, `encoding` is used to stringify buffers (default: `'utf8'`). + */ + toString: (encoding?: BufferEncoding) => string; + /** + * Associates a message with the file for `reason` at `position`. + * When an error is passed in as `reason`, copies the stack. + * Each message has a `fatal` property which by default is set to `false` (ie. `warning`). + * @param reason Reason for message. Uses the stack and message of the error if given. + * @param position Place at which the message occurred in `vfile`. + * @param ruleId Category of message. + */ + message: (reason: string, position?: Unist.Point | Unist.Position | vfileMessage.AnyNode, ruleId?: string) => vfileMessage.VFileMessage; + /** + * Associates a fatal message with the file, then immediately throws it. + * Note: fatal errors mean a file is no longer processable. + * Calls `message()` internally. + * @param reason Reason for message. Uses the stack and message of the error if given. + * @param position Place at which the message occurred in `vfile`. + * @param ruleId Category of message. + */ + fail: (reason: string, position?: Unist.Point | Unist.Position | vfileMessage.AnyNode, ruleId?: string) => never; + /** + * Associates an informational message with the file, where `fatal` is set to `null`. + * Calls `message()` internally. + * @param reason Reason for message. Uses the stack and message of the error if given. + * @param position Place at which the message occurred in `vfile`. + * @param ruleId Category of message. + */ + info: (reason: string, position?: Unist.Point | Unist.Position | vfileMessage.AnyNode, ruleId?: string) => vfileMessage.VFileMessage; } } -/** - * Create a new virtual file. - * Path related properties are set in the following order (least specific to most specific): `history`, `path`, `basename`, `stem`, `extname`, `dirname`. - * It’s not possible to set either `dirname` or `extname` without setting either `history`, `path`, `basename`, or `stem` as well. - */ declare const vfile: vfile.VFile; export = vfile; diff --git a/types/vfile/vfile-tests.ts b/types/vfile/vfile-tests.ts index 5c14c8502b..b89df6db23 100644 --- a/types/vfile/vfile-tests.ts +++ b/types/vfile/vfile-tests.ts @@ -1,5 +1,6 @@ import vfile = require('vfile'); import * as Unist from 'unist'; +import vfileMessage = require('vfile-message'); // Instantiation const file: vfile.VFile = vfile(); @@ -15,24 +16,7 @@ file.dirname = '~'; file.extname = '.md'; file.basename = 'test.text'; file.history = ['~/test.txt']; // => ['~/example.txt', '~/example.md', '~/index.text'] -file.messages = [{ - file: '~/test.txt', - ruleId: '', - reason: '', - line: 1, - column: 1, - location: { - start: { - line: 1, - column: 1, - }, - end: { - line: 1, - column: 1, - } - }, - source: '' -}]; +file.messages = [vfileMessage('random error')]; const startPoint: Unist.Point = { line: 1, @@ -46,7 +30,7 @@ const position: Unist.Position = { }, }; -file.message('test', startPoint); +const message: vfileMessage.VFileMessage = file.message('test', startPoint, 'test origin'); file.message('test', position); file.message('test', { type: 'ramdom node', @@ -56,6 +40,10 @@ file.message('test', { file.message('test', { start: 'invalid point' }); // $ExpectError +file.fail('test'); + +const infoMessage: vfileMessage.VFileMessage = file.info('test'); + // Using `data` prop interface CustomData { message: string;