vinyl: types for v2.0.0

gulp-util/index.d.ts

@@ -11,7 +11,7 @@ import vinyl = require('vinyl');
 import chalk = require('chalk');
 import through2 = require('through2');
 
-export class File extends vinyl { }
+export { vinyl as File };
 
 /**
 * Replaces a file extension in a path. Returns the new path.

vinyl/index.d.ts

@@ -1,133 +1,327 @@
-// Type definitions for vinyl 1.2.0
+// Type definitions for vinyl 2.0.0
 // Project: https://github.com/gulpjs/vinyl
-// Definitions by: vvakame <https://github.com/vvakame/>, jedmao <https://github.com/jedmao>
+// Definitions by: vvakame <https://github.com/vvakame/>, jedmao <https://github.com/jedmao>, Georgii Dolzhykov <https://github.com/thorn0>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
 /// <reference types="node" />
 
+import * as fs from 'fs';
 
-
-import fs = require("fs");
-
-/**
- * A virtual file format.
- */
-declare class File {
-    constructor(options?: {
-
-        /**
-        * Default: process.cwd()
-        */
-        cwd?: string;
-
-        /**
-         * Used for relative pathing. Typically where a glob starts.
-         */
-        base?: string;
-
-        /**
-         * Full path to the file.
-         */
-        path?: string;
-
-        /**
-         * Path history. Has no effect if options.path is passed.
-         */
-        history?: string[];
-
-        /**
-         * The result of an fs.stat call. See fs.Stats for more information.
-         */
-        stat?: fs.Stats;
-
-        /**
-         * File contents.
-         * Type: Buffer, Stream, or null
-         */
-        contents?: Buffer | NodeJS.ReadWriteStream;
-    });
+interface ConstructorOptions {
+    /**
+    * The current working directory of the file. Default: process.cwd()
+    */
+    cwd?: string;
 
     /**
-     * Default: process.cwd()
+     * Used for relative pathing. Typically where a glob starts. Default: options.cwd
      */
-    public cwd: string;
-
-    /**
-     * Used for relative pathing. Typically where a glob starts.
-     */
-    public dirname: string;
-    public basename: string;
-    public base: string;
+    base?: string;
 
     /**
      * Full path to the file.
      */
-    public path: string;
-    public stat: fs.Stats;
+    path?: string;
 
     /**
-     * Gets and sets stem (filename without suffix) for the file path.
+     * Stores the path history. If `options.path` and `options.history` are both passed,
+     * `options.path` is appended to `options.history`. All `options.history` paths are
+     * normalized by the `file.path` setter.
+     * Default: `[]` (or `[options.path]` if `options.path` is passed)
      */
-    public stem: string;
+    history?: string[];
 
     /**
-     * Gets and sets path.extname for the file path
+     * The result of an fs.stat call. This is how you mark the file as a directory or
+     * symbolic link. See `isDirectory()`, `isSymbolic()` and `fs.Stats` for more information.
+     * http://nodejs.org/api/fs.html#fs_class_fs_stats
      */
-    public extname: string;
+    stat?: fs.Stats;
 
     /**
-     * Array of path values the file object has had
+     * File contents.
+     * Type: `Buffer`, `Stream`, or null
+     * Default: null
      */
-    public history: string[];
+    contents?: Buffer | NodeJS.ReadableStream | null;
 
     /**
-     * Type: Buffer|Stream|null (Default: null)
+     * Any custom option properties will be directly assigned to the new Vinyl object.
      */
-    public contents: Buffer | NodeJS.ReadableStream;
+    [customOption: string]: any;
+}
+
+interface FileConstructor {
+    new (options: ConstructorOptions & { contents: null }): NullFile;
+    new (options: ConstructorOptions & { contents: Buffer }): BufferFile;
+    new (options: ConstructorOptions & { contents: NodeJS.ReadableStream }): StreamFile;
+    new (options?: ConstructorOptions): File;
 
     /**
-     * Returns path.relative for the file base and file path.
+     * Checks if a given object is a vinyl file.
+     */
+    isVinyl(obj: any): obj is File;
+
+    /**
+     * Checks if a property is not managed internally.
+     */
+    isCustomProp(name: string): boolean;
+
+    prototype: File;
+}
+
+export = File;
+
+declare let File: FileConstructor;
+
+interface File {
+    /**
+     * Gets and sets the contents of the file. If set to a `Stream`, it is wrapped in
+     * a `cloneable-readable` stream.
+     *
+     * Throws when set to any value other than a `Stream`, a `Buffer` or `null`.
+     */
+    contents: Buffer | NodeJS.ReadableStream | null;
+
+    /**
+     * Gets and sets current working directory. Will always be normalized and have trailing
+     * separators removed.
+     *
+     * Throws when set to any value other than non-empty strings.
+     */
+    cwd: string;
+
+    //
+    /**
+     * Gets and sets base directory. Used for relative pathing (typically where a glob starts).
+     * When `null` or `undefined`, it simply proxies the `file.cwd` property. Will always be
+     * normalized and have trailing separators removed.
+     *
+     * Throws when set to any value other than non-empty strings or `null`/`undefined`.
+     *
+     * The setter's type is actually `string | null | undefined`, but TypeScript doesn't allow
+     * get/set accessors to be of different type. The property is declared as `string` for the
+     * compiler not to require useless null checks for the getter. (Hopefully, noone will need
+     * to assign `null` to this property.)
+     */
+    base: string;
+
+    /**
+     * Gets and sets the absolute pathname string or `undefined`. Setting to a different value
+     * appends the new path to `file.history`. If set to the same value as the current path, it
+     * is ignored. All new values are normalized and have trailing separators removed.
+     *
+     * Throws when set to any value other than a string.
+     *
+     * The getter is actually of type `string | undefined` whereas the setter is just `string`,
+     * however TypeScript doesn't allow get/set accessors to be of different type. See the
+     * comment for the `base` properties.
+     */
+    path: string;
+
+    /**
+     * Array of `file.path` values the Vinyl object has had, from `file.history[0]` (original)
+     * through `file.history[file.history.length - 1]` (current). `file.history` and its elements
+     * should normally be treated as read-only and only altered indirectly by setting `file.path`.
+     */
+    readonly history: ReadonlyArray<string>;
+
+    /**
+     * Gets the result of `path.relative(file.base, file.path)`.
+     *
+     * Throws when set or when `file.path` is not set.
+     *
      * Example:
-     *  var file = new File({
-     *    cwd: "/",
-     *    base: "/test/",
-     *    path: "/test/file.js"
-     *  });
-     *  console.log(file.relative); // file.js
+     *
+     * ```js
+     * var file = new File({
+     *   cwd: '/',
+     *   base: '/test/',
+     *   path: '/test/file.js'
+     * });
+     *
+     * console.log(file.relative); // file.js
+     * ```
      */
-    public relative: string;
+    relative: string;
 
     /**
-     * Returns true if file.contents is a Buffer.
+     * Gets and sets the dirname of `file.path`. Will always be normalized and have trailing
+     * separators removed.
+     *
+     * Throws when `file.path` is not set.
+     *
+     * Example:
+     *
+     * ```js
+     * var file = new File({
+     *   cwd: '/',
+     *   base: '/test/',
+     *   path: '/test/file.js'
+     * });
+     *
+     * console.log(file.dirname); // /test
+     *
+     * file.dirname = '/specs';
+     *
+     * console.log(file.dirname); // /specs
+     * console.log(file.path); // /specs/file.js
+     * ```
      */
-    public isBuffer(): boolean;
+    dirname: string;
 
     /**
-     * Returns true if file.contents is a Stream.
+     * Gets and sets the basename of `file.path`.
+     *
+     * Throws when `file.path` is not set.
+     *
+     * Example:
+     *
+     * ```js
+     * var file = new File({
+     *   cwd: '/',
+     *   base: '/test/',
+     *   path: '/test/file.js'
+     * });
+     *
+     * console.log(file.basename); // file.js
+     *
+     * file.basename = 'file.txt';
+     *
+     * console.log(file.basename); // file.txt
+     * console.log(file.path); // /test/file.txt
+     * ```
      */
-    public isStream(): boolean;
+    basename: string;
 
     /**
-     * Returns true if file.contents is null.
+     * Gets and sets stem (filename without suffix) of `file.path`.
+     *
+     * Throws when `file.path` is not set.
+     *
+     * Example:
+     *
+     * ```js
+     * var file = new File({
+     *   cwd: '/',
+     *   base: '/test/',
+     *   path: '/test/file.js'
+     * });
+     *
+     * console.log(file.stem); // file
+     *
+     * file.stem = 'foo';
+     *
+     * console.log(file.stem); // foo
+     * console.log(file.path); // /test/foo.js
+     * ```
      */
-    public isNull(): boolean;
+    stem: string;
 
     /**
-     * Returns true if this is a directory.
+     * Gets and sets extname of `file.path`.
+     *
+     * Throws when `file.path` is not set.
+     *
+     * Example:
+     *
+     * ```js
+     * var file = new File({
+     *   cwd: '/',
+     *   base: '/test/',
+     *   path: '/test/file.js'
+     * });
+     *
+     * console.log(file.extname); // .js
+     *
+     * file.extname = '.txt';
+     *
+     * console.log(file.extname); // .txt
+     * console.log(file.path); // /test/file.txt
+     * ```
      */
-    public isDirectory(): boolean;
+    extname: string;
 
     /**
-     * Returns a new File object with all attributes cloned. Custom attributes are deep-cloned.
+     * Gets and sets the path where the file points to if it's a symbolic link. Will always
+     * be normalized and have trailing separators removed.
+     *
+     * Throws when set to any value other than a string.
      */
-    public clone(opts?: { contents?: boolean, deep?: boolean }): File;
+    symlink: string | null;
+
+    stat: fs.Stats | null;
+
+    [customProperty: string]: any;
 
     /**
+     * Returns `true` if the file contents are a `Buffer`, otherwise `false`.
+     */
+    isBuffer(): this is BufferFile;
+
+    /**
+     * Returns `true` if the file contents are a `Stream`, otherwise `false`.
+     */
+    isStream(): this is StreamFile;
+
+    /**
+     * Returns `true` if the file contents are `null`, otherwise `false`.
+     */
+    isNull(): this is NullFile;
+
+    /**
+     * Returns `true` if the file represents a directory, otherwise `false`.
+     *
+     * A file is considered a directory when:
+     *
+     * - `file.isNull()` is `true`
+     * - `file.stat` is an object
+     * - `file.stat.isDirectory()` returns `true`
+     *
+     * When constructing a Vinyl object, pass in a valid `fs.Stats` object via `options.stat`.
+     * If you are mocking the `fs.Stats` object, you may need to stub the `isDirectory()` method.
+     */
+    isDirectory(): this is DirectoryFile;
+
+    /**
+     * Returns `true` if the file represents a symbolic link, otherwise `false`.
+     *
+     * A file is considered symbolic when:
+     *
+     * - `file.isNull()` is `true`
+     * - `file.stat` is an object
+     * - `file.stat.isSymbolicLink()` returns `true`
+     *
+     * When constructing a Vinyl object, pass in a valid `fs.Stats` object via `options.stat`.
+     * If you are mocking the `fs.Stats` object, you may need to stub the `isSymbolicLink()` method.
+     */
+    isSymbolic(): this is SymbolicFile;
+
+    /**
+     * Returns a new Vinyl object with all attributes cloned.
+     *
+     * __By default custom attributes are cloned deeply.__
+     *
+     * If `options` or `options.deep` is `false`, custom attributes will not be cloned deeply.
+     *
+     * If `file.contents` is a `Buffer` and `options.contents` is `false`, the `Buffer` reference
+     * will be reused instead of copied.
+     */
+    clone(opts?: { contents?: boolean, deep?: boolean } | boolean): this;
+
+    /**
+     * Returns a formatted-string interpretation of the Vinyl object.
+     * Automatically called by node's `console.log`.
+     */
+    inspect(): string;
+
+    /**
+     * @deprecated This method was removed in v2.0.
      * If file.contents is a Buffer, it will write it to the stream.
      * If file.contents is a Stream, it will pipe it to the stream.
      * If file.contents is null, it will do nothing.
      */
-    public pipe<T extends NodeJS.ReadWriteStream>(
+    pipe<T extends NodeJS.WritableStream>(
         stream: T,
         opts?: {
             /**
@@ -135,21 +329,43 @@ declare class File {
              */
             end?: boolean;
         }): T;
-
-    /**
-     * Returns a pretty String interpretation of the File. Useful for console.log.
-     */
-    public inspect(): string;
-
-    /**
-     * Checks if a given object is a vinyl file.
-     */
-    public static isVinyl(obj: any): boolean;
-
-    /**
-     * Checks if a property is not managed internally.
-     */
-    public static isCustomProp(name: string): boolean;
 }
 
-export = File;
+// See https://github.com/Microsoft/TypeScript/issues/11796
+
+interface BufferFile extends File {
+    contents: Buffer;
+    isStream(): this is never;
+    isBuffer(): true;
+    isNull(): this is never;
+    isDirectory(): this is never;
+    isSymbolic(): this is never;
+}
+
+interface StreamFile extends File {
+    contents: NodeJS.ReadableStream;
+    isStream(): true;
+    isBuffer(): this is never;
+    isNull(): this is never;
+    isDirectory(): this is never;
+    isSymbolic(): this is never;
+}
+
+interface NullFile extends File {
+    contents: null;
+    isStream(): this is never;
+    isBuffer(): this is never;
+    isNull(): true;
+    isDirectory(): this is DirectoryFile;
+    isSymbolic(): this is SymbolicFile;
+}
+
+interface DirectoryFile extends NullFile {
+    isDirectory(): true;
+    isSymbolic(): this is never;
+}
+
+interface SymbolicFile extends NullFile {
+    isDirectory(): this is never;
+    isSymbolic(): true;
+}

vinyl/tsconfig.json

@@ -3,7 +3,7 @@
         "module": "commonjs",
         "target": "es6",
         "noImplicitAny": true,
-        "strictNullChecks": false,
+        "strictNullChecks": true,
         "baseUrl": "../",
         "typeRoots": [
             "../"
@@ -16,4 +16,4 @@
         "index.d.ts",
         "vinyl-tests.ts"
     ]
-}
+}