From 341edc76faabd58a2f184d4c9de66b5787cef26c Mon Sep 17 00:00:00 2001 From: bizen241 Date: Fri, 1 Sep 2017 01:48:38 +0900 Subject: [PATCH] [vfile]: add types --- types/vfile/index.d.ts | 152 +++++++++++++++++++++++++++++++++++++ types/vfile/tsconfig.json | 22 ++++++ types/vfile/tslint.json | 1 + types/vfile/vfile-tests.ts | 47 ++++++++++++ 4 files changed, 222 insertions(+) create mode 100644 types/vfile/index.d.ts create mode 100644 types/vfile/tsconfig.json create mode 100644 types/vfile/tslint.json create mode 100644 types/vfile/vfile-tests.ts diff --git a/types/vfile/index.d.ts b/types/vfile/index.d.ts new file mode 100644 index 0000000000..590fed550b --- /dev/null +++ b/types/vfile/index.d.ts @@ -0,0 +1,152 @@ +// Type definitions for VFile 2.2 +// Project: https://github.com/vfile/vfile +// Definitions by: bizen241 +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.2 + +/// + +import * as Unist from 'unist'; + +export = VFile; + +/** + * 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. + * @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`. + */ +declare function VFile(options?: string | Buffer | Partial): VFile.VFile; + +declare namespace VFile { + interface VFile { + [key: string]: any; + /** + * Raw value. + */ + contents: string | Buffer | null; + /** + * Base of `path`. + * Defaults to `process.cwd()`. + */ + cwd: string; + /** + * Path of `vfile`. + * Cannot be nullified. + */ + path?: string; + /** + * Current name (including extension) of `vfile`. + * Cannot contain path separators. + * Cannot be nullified either (use `file.path = file.dirname` instead). + */ + basename?: string; + /** + * Name (without extension) of `vfile`. + * Cannot be nullified, and cannot contain path separators. + */ + stem?: string; + /** + * Extension (with dot) of `vfile`. + * Cannot be set if there's no `path` yet and cannot contain path separators. + */ + extname?: string; + /** + * Path to parent directory of `vfile`. + * Cannot be set if there's no `path` yet. + */ + dirname?: string; + /** + * List of file-paths the file moved between. + */ + history: string[]; + /** + * List of messages associated with the file. + */ + messages: VFileMessage[]; + /** + * Place to store custom information. + * It's OK to store custom data directly on the `vfile`, moving it to `data` gives a little more privacy. + */ + data: object; + /** + * Convert contents of `vfile` to string. + * @param encoding If `contents` is a buffer, `encoding` is used to stringify buffers (default: `'utf8'`). + */ + toString(encoding?: string): 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 | Error, position?: Unist.Node | Unist.Point | Unist.Position, ruleId?: string): VFileMessage; + /** + * 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 | Error, position?: Unist.Node | Unist.Point | Unist.Position, 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. + */ + fail(reason: string | Error, position?: Unist.Node | Unist.Point | Unist.Position, ruleId?: string): VFileMessage; + } + + /** + * File-related message describing something at certain position. + */ + interface VFileMessage extends Error { + /** + * File-path, when the message was triggered. + */ + file: string; + /** + * Reason for message. + */ + reason: string; + /** + * Category of message. + */ + ruleId: string | null; + /** + * Namespace of warning. + */ + source: string | null; + /** + * If true, marks associated file as no longer processable. + */ + fatal: boolean | null; + /** + * 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: { + start: { + line: number | null; + column: number | null; + }; + end: { + line: number | null; + column: number | null; + }; + }; + } +} diff --git a/types/vfile/tsconfig.json b/types/vfile/tsconfig.json new file mode 100644 index 0000000000..7615c6e59a --- /dev/null +++ b/types/vfile/tsconfig.json @@ -0,0 +1,22 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "vfile-tests.ts" + ] +} diff --git a/types/vfile/tslint.json b/types/vfile/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/vfile/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" } diff --git a/types/vfile/vfile-tests.ts b/types/vfile/vfile-tests.ts new file mode 100644 index 0000000000..aae566154b --- /dev/null +++ b/types/vfile/vfile-tests.ts @@ -0,0 +1,47 @@ +import * as vfile from 'vfile'; +import * as Unist from 'unist'; + +vfile(); +vfile('string'); +vfile(Buffer.from('string')); +vfile(vfile()); +vfile({ stem: 'readme', extname: '.md' }); +vfile({ custom: 'data' }); +try { + vfile({ extname: '.md' }); +} catch (e) { + console.log('Error: set extname without path'); +} + +const file: vfile.VFile = vfile({ contents: 'contents' }); + +file.path = '~/readme.txt'; +file.basename = 'example.txt'; +file.stem = 'readme'; +file.extname = '.md'; +file.data = { + key: 'value', +}; + +const history: string[] = file.history; +const contents: string = file.toString(); + +console.log('file.history =>', history); +console.log('file.contents =>', contents); + +const position: Unist.Point = { + line: 1, + column: 1, +}; + +file.message('reason', position); +file.info('reason', position); +try { + file.fail('reason', position); +} catch (e) { + console.log('Error: associated a fatal message'); +} + +const messages: vfile.VFileMessage[] = file.messages; + +console.log('file.messages =>', messages);