@composerjs/virtual-file

Virtual-File

VirtualFile is an object that represents a Buffer and it's metadata. Though this object is comparable to a Vinyl object, the intention is that instances of `VirtualFile` are truly simple, and flat metadata objects. It does not provide output helpers. It's just metadata and the Buffer content.

Installation

  npm i -S @composerjs/virtual-file

Usage

  import fs from 'fs';
  import { VirtualFile } from '@composerjs/virtual-file';
  
  const file = VirtualFile.Factory({
    path: './package.json',
    content: fs.readFileSync('./package.json'),
    encoding: 'utf8',
    tags: ['npm-package']
  });
  
  console.info(file.toString());  // '{"name":"@composerjs/virtual-file"...
  console.info(file.mediaType);   // 'application/json'
  console.info(file.byteLength)   // 341 

API

VirtualFile.Factory({options})

Constructs a new instance of a VirtualFile where an instance represents a single file. All attributes of a VirtualFile are readonly so once constructed the properties cannot be changed.

options

options.path: string Required

Relative or absolute path location of the file.

options.content: Buffer Required

Buffer of the file.

options.encoding: string Optional

Encoding of the buffer.

Default: utf8

options.tags: string[]

An array of strings useful for adding additional metadata descriptions to an instance of VirtualFile.

Static Methods

VirtualFile.IsVirtualFile(file: VirtualFile): boolean

Returns true if the provided value is an instance of VirtualFile.

Instance Methods

file.toString(): string

Returns the Buffer as a string. Internally this uses StringDecoder, but only when encoding is set to utf8 or utf16

file.toJSON(): object

Called when an instance of VirtualFile has been JSON.stringify()'d. This returns a flat object of picked properties from the instance. Use file.toObject() instead as semantically it's more appropriate.

file.toObject(): object

Alias of file.toJSON().

file.extend(file: VirtualFile): void

Extends the instance with values from the provided VirtualFile instance.

file.clone(): VirtualFile

Returns a clone of the VirtualFile instance.

Instance Properties

file.content: Buffer

Buffer representation of the file content.

file.byteLength: number

Alias of this.content.byteLength. Returns the Buffer size in bytes.

Example: 341

file.encoding: string

file encoding string

Example: utf8, utf16, buffer

file.tags: string[]

An array of strings useful for adding additional context about the file the instance of VirtualFile is representing.

At the moment tags are just an array of strings to provide additional context for the file.

Example: \['package-json'\]

file.path: string

Complete file path supplied via constructor.

Example: dir/file.txt

file.name: string

Name of the file via via path.parse().

If path is a URL name will be a SLD i.e. google in google.com

Example: file

file.isURL: boolean

If the provided path is a valid URL this will be true.

Default: false

file.ext: string

File extension via path.parse().

If path is a URL ext will be TLD i.e. .com in google.com

Example: .txt

file.absolute: string

Absolute path via path.resolve().

Example: /home/user/dir/file.txt

file.dir: string

Directory of file via path.parse()

Example: /home/user/dir

file.base: string

Base name of file via path.parse()

Example: file.txt

file.root: string

Root path via path.parse()

Example: /

file.mediaType: string | undefined

Media Type (formerly called Mime Type) of the file.

This value may not be set.

Example: application/json

file.contentType: string | undefined

The Content-Type entity header value used in HTTP transactions.

This value may not be set.

Example: application/json

[Symbol.toStringTag]: string

Set by default in all instances. Calls to Object.prototype.toString.call(file) for instances of VirtualFile will return the constant string value.

Default: VirtualFile

nodejs.util.inspect.custom: string

Comparable to [Symbol.toStringTag] this symbol is used by node's util.inspect.