Require Path: 'runtime/Volume'

A Volume is a kind of container object intended to provide a sort of simplified "file system"-like interface, where there are objects (usually DataSegments) stored at "paths", and optionally associated with metadata.

Normalized Paths

Internally, all Volumes use the same kind of normalized path strings. This form is percent-encoded strings separated by forward slashes /. So, you can create a normalized path string from an array of strings this way:

var pathParts = ['Folder A', 'Folder B', 'Folder C', 'File.txt'];
var path = pathParts.map(encodeURIComponent).join('/');
// --> Folder%20A/Folder%20B/Folder%20C/File.txt

...and you can reverse the process this way:

var path = '1/2/3';
var partParts = path.split('/').map(decodeURIComponent);
// --> ['1', '2', '3']

For convenience, you can use Volume.splitNormalizedPath(path) and Volume.joinNormalizedPath(parts) to do this.

Note that since they get percent-encoded, the parts of a path can contain any character, including new-line characters, the / character, the null \0 character, etc. Since space characters are encoded, a normalized path string can be used as a valid HTML5 element id.

A path-part cannot be zero-length. It is not valid for a normalized path to start with /, end with /, or have two or more / in a row. You can use the regular expression Volume.normalizedPathPattern to test a string is a valid normalized path pattern.

Localized Paths

As well as normalized paths, which are a universal format across all Volumes, there is also a concept of localized paths which vary depending on the kind of Volume it is. The default localized path form is similar to the normalized form, except the parts are not percent-encoded, and the parts cannot contain a /.

Each Volume has these properties and methods that specify how its localized paths work:

• volume.splitLocalizedPath(path): returns path.split(this.localizedPathSeparator).map(this.decodeLocalizedPathPart)
• volume.joinLocalizedPath(parts): returns parts.map(this.encodeLocalizedPathPart).join(this.localizedPathSeparator)
• volume.localizedPathSeparator: '/'
• volume.decodeLocalizedPathPart(part): returns part unchanged
• volume.encodeLocalizedPathPart(part): throws an Error if !this.localizedPathPartPattern.match(part), otherwise returns part unchanged
• volume.localizedPathPartPattern: /^[^\/]+$/

You only need to replace .splitLocalizedPath() and .joinLocalizedPath() to fully define it. The rest of the properties and methods are used only by the default implementation of these methods.