Merge pull request #19489 from bizen241/vfile

[vfile]: add types

types/vfile/index.d.ts

@@ -0,0 +1,152 @@
+// Type definitions for VFile 2.2
+// Project: https://github.com/vfile/vfile
+// Definitions by: bizen241 <https://github.com/bizen241>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.2
+
+/// <reference types='node' />
+
+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>): 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;
+            };
+        };
+    }
+}

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"
+    ]
+}

types/vfile/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }

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);