http and file-system naming changed to use "-"

file-system/file-system-access.android.ts

@@ -0,0 +1,431 @@
+import appModule = require("application/application");
+import textModule = require("text/text");
+
+export class FileSystemAccess {
+    private _pathSeparator = java.io.File.separator.toString();
+
+    public getLastModified(path: string): Date {
+        var javaFile = new java.io.File(path);
+        return new Date(javaFile.lastModified());
+    }
+
+    public getParent(path: string, onError?: (error: any) => any): { path: string; name: string } {
+        try {
+            var javaFile = new java.io.File(path);
+            var parent = javaFile.getParentFile();
+
+            return { path: parent.getAbsolutePath(), name: parent.getName() };
+        } catch (exception) {
+            // TODO: unified approach for error messages
+            if (onError) {
+                onError(exception);
+            }
+
+            return undefined;
+        }
+    }
+
+    public getFile(path: string, onError?: (error: any) => any): { path: string; name: string; extension: string } {
+        return this.ensureFile(new java.io.File(path), false, onError);
+    }
+
+    public getFolder(path: string, onError?: (error: any) => any): { path: string; name: string } {
+        var javaFile = new java.io.File(path);
+        var dirInfo = this.ensureFile(javaFile, true, onError);
+        if (!dirInfo) {
+            return undefined;
+        }
+
+        return { path: dirInfo.path, name: dirInfo.name };
+    }
+
+    public eachEntity(path: string, onEntity: (file: { path: string; name: string; extension: string }) => boolean, onError?: (error: any) => any) {
+        if (!onEntity) {
+            return;
+        }
+
+        this.enumEntities(path, onEntity, onError);
+    }
+
+    public getEntities(path: string, onSuccess: (files: Array<{ path: string; name: string; extension: string }>) => any, onError?: (error: any) => any) {
+        if (!onSuccess) {
+            return;
+        }
+
+        var fileInfos = new Array<{ path: string; name: string; extension: string }>();
+        var onEntity = function (entity: { path: string; name: string; extension: string }): boolean {
+            fileInfos.push(entity);
+            return true;
+        }
+
+        var errorOccurred;
+        var localError = function (error: any) {
+            if (onError) {
+                onError(error);
+            }
+
+            errorOccurred = true;
+        }
+
+        this.enumEntities(path, onEntity, localError);
+
+        if (!errorOccurred) {
+            onSuccess(fileInfos);
+        }
+    }
+
+    public fileExists(path: string): boolean {
+        var file = new java.io.File(path);
+        return file.exists();
+    }
+
+    public folderExists(path: string): boolean {
+        var file = new java.io.File(path);
+        var exists = file.exists();
+        var dir = file.isDirectory();
+        var isFile = file.isFile();
+        var hidden = file.isHidden();
+
+        // return file.exists() && file.getCanonicalFile().isDirectory();
+        return exists && dir;
+    }
+
+    public deleteFile(path: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        try {
+            var javaFile = new java.io.File(path);
+            if (!javaFile.isFile()) {
+                if (onError) {
+                    onError({ message: "The specified parameter is not a File entity." });
+                }
+
+                return;
+            }
+
+            if (!javaFile.delete()) {
+                if (onError) {
+                    onError({ message: "File deletion failed" });
+                }
+            } else if (onSuccess) {
+                onSuccess();
+            }
+        } catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+        }
+    }
+
+    public deleteFolder(path: string, isKnown?: boolean, onSuccess?: () => any, onError?: (error: any) => any) {
+        try {
+            var javaFile = new java.io.File(path);
+            if (!javaFile.getCanonicalFile().isDirectory()) {
+                if (onError) {
+                    onError({ message: "The specified parameter is not a Folder entity." });
+                }
+
+                return;
+            }
+
+            // TODO: Asynchronous
+            this.deleteFolderContent(javaFile);
+
+            if (!isKnown) {
+                if (javaFile.delete()) {
+                    if (onSuccess) {
+                        onSuccess();
+                    }
+                } else {
+                    if (onError) {
+                        onError({ message: "Folder deletion failed." });
+                    }
+                }
+            } else {
+                // TODO: Notify error?
+            }
+        } catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+        }
+    }
+
+    public emptyFolder(path: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        try {
+            var javaFile = new java.io.File(path);
+            if (!javaFile.getCanonicalFile().isDirectory()) {
+                if (onError) {
+                    onError({ message: "The specified parameter is not a Folder entity." });
+                }
+
+                return;
+            }
+
+            // TODO: Asynchronous
+            this.deleteFolderContent(javaFile);
+
+            if (onSuccess) {
+                onSuccess();
+            }
+
+        } catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+        }
+    }
+
+    public rename(path: string, newPath: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        var javaFile = new java.io.File(path);
+        if (!javaFile.exists()) {
+            if (onError) {
+                onError(new Error("The file to rename does not exist"));
+            }
+
+            return;
+        }
+
+        var newFile = new java.io.File(newPath);
+        if (newFile.exists()) {
+            if (onError) {
+                onError(new Error("A file with the same name already exists."));
+            }
+
+            return;
+        }
+
+        if (!javaFile.renameTo(newFile)) {
+            if (onError) {
+                onError(new Error("Failed to rename file '" + path + "' to '" + newPath + "'"));
+            }
+
+            return;
+        }
+
+        if (onSuccess) {
+            onSuccess();
+        }
+    }
+
+    public getDocumentsFolderPath(): string {
+        var context = appModule.android.context;
+        var dir = context.getFilesDir();
+        return dir.getAbsolutePath();
+    }
+
+    public getTempFolderPath(): string {
+        var context = appModule.android.context;
+        var dir = context.getCacheDir();
+        return dir.getAbsolutePath();
+    }
+
+    public readText(path: string, onSuccess: (content: string) => any, onError?: (error: any) => any, encoding?: string) {
+        try {
+            var javaFile = new java.io.File(path);
+            var stream = new java.io.FileInputStream(javaFile);
+
+            var actualEncoding = encoding;
+            if (!actualEncoding) {
+                actualEncoding = textModule.encoding.UTF_8;
+            }
+            var reader = new java.io.InputStreamReader(stream, actualEncoding);
+            var bufferedReader = new java.io.BufferedReader(reader);
+
+            // TODO: We will need to read the entire file to a CharBuffer instead of reading it line by line
+            // TODO: bufferedReader.read(CharBuffer) does not currently work
+            var line = undefined;
+            var result = "";
+            while (true) {
+                line = bufferedReader.readLine();
+                if (!line) {
+                    break;
+                }
+
+                if (result.length > 0) {
+                    // add the new line manually to the result
+                    // TODO: Try with CharBuffer at a later stage, when the Bridge allows it
+                    result += "\n";
+                }
+
+                result += line;
+            }
+
+            bufferedReader.close();
+
+            if (onSuccess) {
+                onSuccess(result);
+            }
+        } catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+        }
+    }
+
+    public writeText(path: string, content: string, onSuccess?: () => any, onError?: (error: any) => any, encoding?: string) {
+        try {
+            var javaFile = new java.io.File(path);
+            var stream = new java.io.FileOutputStream(javaFile);
+
+            var actualEncoding = encoding;
+            if (!actualEncoding) {
+                actualEncoding = textModule.encoding.UTF_8;
+            }
+            var writer = new java.io.OutputStreamWriter(stream, actualEncoding);
+
+            writer.write(content);
+            writer.close();
+
+            if (onSuccess) {
+                onSuccess();
+            }
+        } catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+        }
+    }
+
+    private deleteFolderContent(file: java.io.File): boolean {
+        var filesList = file.listFiles();
+
+        var i,
+            childFile: java.io.File,
+            success: boolean = false;
+
+        for (i = 0; i < filesList.length; i++) {
+            childFile = filesList[i];
+            if (childFile.getCanonicalFile().isDirectory()) {
+                success = this.deleteFolderContent(childFile);
+                if (!success) {
+                    break;
+                }
+            }
+
+            success = childFile.delete();
+        }
+
+        return success;
+    }
+
+    private ensureFile(javaFile: java.io.File, isFolder: boolean, onError?: (error: any) => any): { path: string; name: string; extension: string } {
+        try {
+            if (!javaFile.exists()) {
+                var created;
+                if (isFolder) {
+                    created = javaFile.mkdirs();
+                } else {
+                    created = javaFile.createNewFile();
+                }
+
+                if (!created) {
+                    // TODO: unified approach for error messages
+                    if (onError) {
+                        onError("Failed to create new java File for path " + javaFile.getAbsolutePath());
+                    }
+
+                    return undefined;
+                } else {
+                    javaFile.setReadable(true);
+                    javaFile.setWritable(true);
+                }
+            }
+
+            var path = javaFile.getAbsolutePath();
+            return { path: path, name: javaFile.getName(), extension: this.getFileExtension(path) };
+        } catch (exception) {
+            // TODO: unified approach for error messages
+            if (onError) {
+                onError(exception);
+            }
+
+            return undefined;
+        }
+    }
+
+    // TODO: This method is the same as in the iOS implementation.
+    // Make it in a separate file / module so it can be reused from both implementations.
+    private getFileExtension(path: string): string {
+        var dotIndex = path.lastIndexOf(".");
+        if (dotIndex && dotIndex >= 0 && dotIndex < path.length) {
+            return path.substring(dotIndex);
+        }
+
+        return "";
+    }
+
+    private enumEntities(path: string, callback: (entity: { path: string; name: string; extension: string }) => boolean, onError?: (error) => any) {
+        try {
+            var javaFile = new java.io.File(path);
+            if (!javaFile.getCanonicalFile().isDirectory()) {
+                if (onError) {
+                    onError("There is no folder existing at path " + path);
+                }
+
+                return;
+            }
+
+            var filesList = javaFile.listFiles();
+            var length = filesList.length,
+                i,
+                filePath,
+                info,
+                retVal;
+
+            for (i = 0; i < length; i++) {
+                javaFile = filesList[i];
+
+                info = {
+                    path: javaFile.getAbsolutePath(),
+                    name: javaFile.getName()
+                };
+
+                if (javaFile.isFile()) {
+                    info.extension = this.getFileExtension(info.path);
+                }
+
+                retVal = callback(info);
+                if (retVal === false) {
+                    break;
+                }
+            }
+        } catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+        }
+    }
+
+    public getPathSeparator(): string {
+        return this._pathSeparator;
+    }
+
+    public normalizePath(path: string): string {
+        var file = new java.io.File(path);
+        return file.getAbsolutePath();
+    }
+
+    public joinPath(left: string, right: string): string {
+        var file1 = new java.io.File(left);
+        var file2 = new java.io.File(file1, right);
+
+        return file2.getAbsolutePath();
+    }
+
+    public joinPaths(paths: string[]): string {
+        if (!paths || paths.length === 0) {
+            return "";
+        }
+
+        if (paths.length === 1) {
+            return paths[0];
+        }
+
+        var i,
+            result = paths[0];
+        for (i = 1; i < paths.length; i++) {
+            result = this.joinPath(result, paths[i]);
+        }
+
+        return this.normalizePath(result);
+    }
+}

file-system/file-system-access.d.ts

@@ -0,0 +1,35 @@
+// TODO: Implement "hidden" notation so that such declarations are not included in the d.ts file we will provide for the users.
+//@hidden
+
+export declare class FileSystemAccess {
+    getLastModified(path: string): Date;
+
+    getParent(path: string, onError?: (error: any) => any): { path: string; name: string };
+    getFile(path: string, onError?: (error: any) => any): { path: string; name: string; extension: string };
+    getFolder(path: string, onError?: (error: any) => any): { path: string; name: string };
+
+    getEntities(path: string, onSuccess: (files: Array<{ path: string; name: string; extension: string }>) => any, onError?: (error: any) => any);
+    eachEntity(path: string, onSuccess: (entity: { path: string; name: string; extension: string }) => boolean, onError?: (error: any) => any);
+
+    fileExists(path: string): boolean;
+    folderExists(path: string): boolean;
+    
+    deleteFile(path: string, onSuccess?: () => any, onError?: (error: any) => any);
+    deleteFolder(path: string, isKnown: boolean, onSuccess?: () => any, onError?: (error: any) => any);
+    emptyFolder(path: string, onSuccess?: () => any, onError?: (error: any) => any): void;
+    rename(path: string, newPath: string, onSuccess?: () => any, onError?: (error: any) => any): void;
+    getDocumentsFolderPath(): string;
+    getTempFolderPath(): string;
+
+    readText(path: string, onSuccess: (content: string) => any, onError?: (error: any) => any, encoding?: string);
+    writeText(path: string, content: string, onSuccess?: () => any, onError?: (error: any) => any, encoding?: string);
+
+    getFileExtension(path: string): string;
+
+    // path methods
+    getPathSeparator(): string;
+    normalizePath(path: string): string;
+    joinPath(left: string, right: string): string;
+    joinPaths(paths: string[]): string;
+}
+ 

file-system/file-system-access.ios.ts

@@ -0,0 +1,382 @@
+import app_module = require("application/application");
+import utilsModule = require("utils/utils_ios");
+import textModule = require("text/text");
+
+// TODO: Implement all the APIs receiving callback using async blocks
+// TODO: Check whether we need try/catch blocks for the iOS implementation
+
+export class FileSystemAccess {
+    private keyFileType = "NSFileType";
+    private keyModificationTime = "NSFileModificationDate";
+    private keyReadonly = "NSFileImmutable";
+    private documentDir = 9;
+    private cachesDir = 13;
+    private userDomain = 1;
+    private NSUTF8StringEncoding = 4;
+
+    public getLastModified(path: string): Date {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+        var attributes = fileManager.attributesOfItemAtPathError(path, null);
+
+        if (attributes) {
+            var date = attributes.objectForKey(this.keyModificationTime);
+            var interval = date.timeIntervalSince1970();
+
+            // time interval is in seconds, Date constructor expects milliseconds, hence this multiply by 1000
+            return new Date(interval * 1000);
+        } else {
+            return new Date();
+        }
+    }
+
+    public getParent(path: string, onError?: (error: any) => any): { path: string; name: string } {
+        try {
+            var fileManager = Foundation.NSFileManager.defaultManager();
+            var nsString = Foundation.NSString.initWithString(path);
+
+            var parentPath = nsString.stringByDeletingLastPathComponent();
+            var name = fileManager.displayNameAtPath(parentPath);
+
+            return {
+                path: parentPath.toString(),
+                name: name
+            };
+        }
+        catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+
+            return undefined;
+        }
+    }
+
+    public getFile(path: string, onError?: (error: any) => any): { path: string; name: string; extension: string } {
+        try {
+            var fileManager = Foundation.NSFileManager.defaultManager();
+            var exists = fileManager.fileExistsAtPath(path);
+
+            if (!exists) {
+                if (!fileManager.createFileAtPathContentsAttributes(path, null, null)) {
+                    if (onError) {
+                        onError(new Error("Failed to create folder at path '" + path + "'"));
+                    }
+
+                    return undefined;
+                }
+            }
+
+            var fileName = fileManager.displayNameAtPath(path);
+            
+            return {
+                path: path,
+                name: fileName,
+                extension: this.getFileExtension(path)
+            };
+        }
+        catch (exception) {
+            if (onError) {
+                onError(exception);
+            }
+
+            return undefined;
+        }
+    }
+
+    public getFolder(path: string, onError?: (error: any) => any): { path: string; name: string } {
+        try {
+            var fileManager = Foundation.NSFileManager.defaultManager();
+            var exists = this.folderExists(path);
+
+            if (!exists) {
+                if (!fileManager.createDirectoryAtPathWithIntermediateDirectoriesAttributesError(path, true, null, null)) {
+                    // error
+                    if (onError) {
+                        onError(new Error("Failed to create folder at path '" + path + "'"));
+                    }
+
+                    return undefined;
+                }
+            }
+
+            var dirName = fileManager.displayNameAtPath(path);
+            
+            return {
+                path: path,
+                name: dirName
+            };
+        }
+        catch (ex) {
+            if (onError) {
+                onError(new Error("Failed to create folder at path '" + path + "'"));
+            }
+
+            return undefined;
+        }
+    }
+
+    public eachEntity(path: string, onEntity: (file: { path: string; name: string; extension: string }) => any, onError?: (error: any) => any) {
+        if (!onEntity) {
+            return;
+        }
+
+        this.enumEntities(path, onEntity, onError);
+    }
+
+    public getEntities(path: string, onSuccess: (files: Array<{ path: string; name: string; extension: string }>) => any, onError?: (error: any) => any) {
+        if (!onSuccess) {
+            return;
+        }
+
+        var fileInfos = new Array<{ path: string; name: string; extension: string }>();
+        var onEntity = function (entity: { path: string; name: string; extension: string }): boolean {
+            fileInfos.push(entity);
+            return true;
+        }
+
+        var errorOccurred;
+        var localError = function (error: any) {
+            if (onError) {
+                onError(error);
+            }
+
+            errorOccurred = true;
+        }
+
+        this.enumEntities(path, onEntity, onError);
+
+        if (!errorOccurred) {
+            onSuccess(fileInfos);
+        }
+    }
+
+    public fileExists(path: string): boolean {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+        return fileManager.fileExistsAtPath(path);
+    }
+
+    public folderExists(path: string): boolean {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+
+        var buffer = NativePointer.create(PrimitiveType.BOOL, 1);
+        var exists = fileManager.fileExistsAtPathIsDirectory(path, buffer);
+
+        var isDir = buffer[0] && buffer[0] > 0;
+
+        buffer.delete();
+
+        return exists && isDir;
+    }
+
+    public concatPath(left: string, right: string): string {
+        // TODO: This probably is not efficient, we may try concatenation with the "/" character
+        var nsArray = utilsModule.Collections.jsArrayToNSArray([left, right]);
+        var nsString = Foundation.NSString.pathWithComponents(nsArray);
+
+        return nsString.toString();
+    }
+
+    public deleteFile(path: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        this.deleteEntity(path, onSuccess, onError);
+    }
+
+    public deleteFolder(path: string, isKnown?: boolean, onSuccess?: () => any, onError?: (error: any) => any) {
+        this.deleteEntity(path, onSuccess, onError);
+    }
+
+    public emptyFolder(path: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+
+        var filesEnum = function (files: Array<{ path: string; name: string; extension: string }>) {
+            var i;
+            for (i = 0; i < files.length; i++) {
+                if (!fileManager.removeItemAtPathError(files[i].path, null)) {
+                    if (onError) {
+                        onError(new Error("Failed to empty folder '" + path + "'"));
+                    }
+
+                    return;
+                }
+            }
+
+            if (onSuccess) {
+                onSuccess();
+            }
+        }
+
+        this.getEntities(path, filesEnum, onError);
+    }
+
+    public rename(path: string, newPath: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+        if (!fileManager.moveItemAtPathToPathError(path, newPath, null)) {
+            if (onError) {
+                onError(new Error("Failed to rename '" + path + "' to '" + newPath + "'"));
+            }
+        } else if (onSuccess) {
+            onSuccess();
+        }
+    }
+
+    public getDocumentsFolderPath(): string {
+        return this.getKnownPath(this.documentDir);
+    }
+
+    public getTempFolderPath(): string {
+        return this.getKnownPath(this.cachesDir);
+    }
+
+    public readText(path: string, onSuccess: (content: string) => any, onError?: (error: any) => any, encoding?: string) {
+        var actualEncoding = encoding;
+        if (!actualEncoding) {
+            actualEncoding = textModule.encoding.UTF_8;
+        }
+
+        var nsString = Foundation.NSString.stringWithContentsOfFileEncodingError(path, actualEncoding, null);
+        if (!nsString) {
+            if (onError) {
+                onError(new Error("Failed to read file at path '" + path + "'"));
+            }
+        } else if (onSuccess) {
+            onSuccess(nsString.toString());
+        }
+    }
+
+    public writeText(path: string, content: string, onSuccess?: () => any, onError?: (error: any) => any, encoding?: string) {
+        var nsString = Foundation.NSString.initWithString(content);
+
+        var actualEncoding = encoding;
+        if (!actualEncoding) {
+            actualEncoding = textModule.encoding.UTF_8;
+        }
+
+        // TODO: verify the useAuxiliaryFile parameter should be false
+        if (!nsString.writeToFileAtomicallyEncodingError(path, false, actualEncoding, null)) {
+            if (onError) {
+                onError(new Error("Failed to write to file '" + path + "'"));
+            }
+        } else if (onSuccess) {
+            onSuccess();
+        }
+    }
+
+    private getKnownPath(folderType: number): string {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+        var paths = fileManager.URLsForDirectoryInDomains(folderType, this.userDomain);
+
+        var url = paths.objectAtIndex(0);
+        return url.path();
+    }
+
+    // TODO: This method is the same as in the iOS implementation. 
+    // Make it in a separate file / module so it can be reused from both implementations.
+    private getFileExtension(path: string): string {
+        // TODO [For Panata]: The definitions currently specify "any" as a return value of this method
+        //var nsString = Foundation.NSString.stringWithString(path);
+        //var extension = nsString.pathExtension();
+
+        //if (extension && extension.length > 0) {
+        //    extension = extension.concat(".", extension);
+        //}
+
+        //return extension;
+        var dotIndex = path.lastIndexOf(".");
+        if (dotIndex && dotIndex >= 0 && dotIndex < path.length) {
+            return path.substring(dotIndex);
+        }
+
+        return "";
+    }
+
+    private deleteEntity(path: string, onSuccess?: () => any, onError?: (error: any) => any) {
+        var fileManager = Foundation.NSFileManager.defaultManager();
+        if (!fileManager.removeItemAtPathError(path, null)) {
+            if (onError) {
+                onError(new Error("Failed to delete file at path '" + path + "'"));
+            }
+        } else {
+            if (onSuccess) {
+                onSuccess();
+            }
+        }
+    }
+
+    private enumEntities(path: string, callback: (entity: { path: string; name: string; extension: string }) => boolean, onError?: (error) => any) {
+        try {
+            var fileManager = Foundation.NSFileManager.defaultManager();
+            var files = fileManager.contentsOfDirectoryAtPathError(path, null);
+
+            if (!files) {
+                if (onError) {
+                    onError(new Error("Failed to enum files for forlder '" + path + "'"));
+                }
+
+                return;
+            }
+
+            var fileInfos = new Array<{ path: string; name: string; extension: string }>();
+            var file,
+                i,
+                info,
+                retVal;
+
+
+            for (i = 0; i < files.count(); i++) {
+                file = files.objectAtIndex(i);
+
+                info = {
+                    path: this.concatPath(path, file),
+                    name: file
+                };
+
+                if (!this.folderExists(file)) {
+                    info.extension = this.getFileExtension(info.path);
+                }
+
+                retVal = callback(info);
+                if (retVal === false) {
+                    // the callback returned false meaning we should stop the iteration
+                    break;
+                }
+            }
+        }
+        catch (ex) {
+            if (onError) {
+                onError(ex);
+            }
+        }
+    }
+
+    public getPathSeparator(): string {
+        return "/";
+    }
+
+    public normalizePath(path: string): string {
+        var nsString: Foundation.NSString = Foundation.NSString.stringWithString(path);
+        var normalized = nsString.stringByStandardizingPath();
+
+        return normalized;
+    }
+
+    public joinPath(left: string, right: string): string {
+        var nsString: Foundation.NSString = Foundation.NSString.stringWithString(left);
+        return nsString.stringByAppendingPathComponent(right);
+    }
+
+    public joinPaths(paths: string[]): string {
+        if (!paths || paths.length === 0) {
+            return "";
+        }
+
+        var nsArray = new Foundation.NSMutableArray(paths.length);
+
+        var i;
+        for (i = 0; i < paths.length; i++) {
+            nsArray.addObject(paths[i]);
+        }
+
+        // TODO: Static methods return NSString instance to enable its methods
+        var nsString: any = Foundation.NSString.pathWithComponents(nsArray);
+        return nsString.stringByStandardizingPath();
+    }
+}

file-system/file-system.d.ts

@@ -0,0 +1,152 @@
+import promises = require("promises/promises");
+
+export declare class FileSystemEntity {
+    /**
+      * Gets the Date object specifying the last time this entity was modified.
+      */
+    public lastModified: Date;
+
+    /**
+      * Gets the name of the entity.
+      */
+    public name: string;
+
+    /**
+      * Gets the fully-qualified path (including the extension for a File) of the entity.
+      */
+    public path: string;
+
+    /**
+    * Gets the Folder object representing the parent of this entity. 
+    * Will be null for a root folder like Documents or Temporary.
+    * This property is readonly.
+    */
+    public parent: Folder;
+
+    /**
+      * Removes (deletes) the current Entity from the file system.
+      */
+    public remove(): promises.Promise<any>;
+
+    /**
+    * Renames the current entity using the specified name.
+    */
+    public rename(newName: string): promises.Promise<any>;
+}
+
+export declare class File extends FileSystemEntity {
+    /**
+      * Checks whether a File with the specified path already exists.
+      */
+    public static exists(path: string): boolean;
+
+    /**
+      * Gets the extension of the file.
+      */
+    public extension: string;
+
+    /**
+      * Gets a value indicating whether the file is currently locked, meaning a background operation associated with this file is running.
+      */
+    public isLocked: boolean;
+
+    /**
+      * Gets or creates a File entity at the specified path.
+      */
+    public static fromPath(path: string): File;
+    
+    /**
+      * Reads the content of the file as a string using the specified encoding (defaults to UTF-8).
+      */
+    public readText(encoding?: string): promises.Promise<string>;
+
+    /**
+      * Writes the provided string to the file, using the specified encoding (defaults to UTF-8).
+      */
+    public writeText(content: string, encoding?: string): promises.Promise<any>;
+}
+
+export declare class Folder extends FileSystemEntity {
+    /**
+      * Determines whether this instance is a KnownFolder (accessed through the KnownFolders object).
+      */
+    public isKnown: boolean;
+
+    /**
+      * Gets or creates a Folder entity at the specified path.
+      */
+    public static fromPath(path: string): Folder;
+
+    /**
+      * Checks whether a Folder with the specified path already exists.
+      */
+    public static exists(path: string): boolean;
+
+    /**
+    Checks whether this Folder contains an Entity with the specified name.
+    The path of the folder is added to the name to resolve the complete path to check for.
+      */
+    public contains(name: string): boolean;
+
+    /**
+      * Deletes all the files and folders (recursively), contained within this Folder.
+      */
+    public clear(): promises.Promise<any>;
+
+    /**
+      * Gets or creates a File entity with the specified name within this Folder.
+      */
+    public getFile(name: string): File;
+
+    /**
+    * Gets or creates a Folder entity with the specified name within this Folder.
+    */
+    public getFolder(name: string): Folder;
+
+    /**
+    * Gets all the top-level entities residing within this folder.
+    */
+    public getEntities(): promises.Promise<Array<FileSystemEntity>>;
+
+    /**
+    Enumerates all the top-level FileSystem entities residing within this folder.
+    The first parameter is a callback that receives the current entity.
+    If the callback returns false this will mean for the iteration to stop.
+    */
+    public eachEntity(onEntity: (entity: FileSystemEntity) => boolean);
+}
+
+/**
+  * Provides access to the top-level Folders instances that are accessible from the application. Use these as entry points to access the FileSystem.
+  */
+export declare module knownFolders {
+    /**
+    * Gets the Documents folder available for the current application. This Folder is private for the application and not accessible from Users/External apps.
+    */
+    export function documents(): Folder;
+
+    /**
+    * Gets the Temporary (Caches) folder available for the current application. This Folder is private for the application and not accessible from Users/External apps.
+    */
+    export function temp(): Folder;
+}
+
+/**
+* Enables path-specific operations like join, extension, etc.
+*/
+export declare module path {
+    /**
+    * Normalizes a path, taking care of occurrances like ".." and "//"
+    */
+    export function normalize(path: string): string;
+
+    /**
+    * Joins all the provided string components, forming a valid and normalized path.
+    */
+    export function join(...paths: string[]): string;
+
+    /**
+    * Gets the string used to separate file paths.
+    */
+    export var separator: string;
+}

file-system/file-system.ts

@@ -0,0 +1,400 @@
+import file_access_module = require("file-system/file-system-access");
+import promises = require("promises/promises");
+
+// The FileSystemAccess implementation, used through all the APIs.
+var fileAccess;
+var getFileAccess = function (): file_access_module.FileSystemAccess {
+    if (!fileAccess) {
+        fileAccess = new file_access_module.FileSystemAccess();
+    }
+
+    return fileAccess;
+};
+
+// we are defining these as private variables within the IO scope and will use them to access the corresponding properties for each FSEntity instance.
+// this allows us to encapsulate (hide) the explicit property setters and force the users go through the exposed APIs to receive FSEntity instances.
+var nameProperty = "_name";
+var pathProperty = "_path";
+var isKnownProperty = "_isKnown";
+var fileLockedProperty = "_locked";
+var extensionProperty = "_extension";
+var lastModifiedProperty = "_lastModified";
+
+var createFile = function (info: { path: string; name: string; extension: string }) {
+    var file = new File();
+    file[pathProperty] = info.path;
+    file[nameProperty] = info.name;
+    file[extensionProperty] = info.extension;
+
+    return file;
+};
+
+var createFolder = function (info: { path: string; name: string; }) {
+    var documents = knownFolders.documents();
+    if (info.path === documents.path) {
+        return documents;
+    }
+
+    var temp = knownFolders.temp();
+    if (info.path === temp.path) {
+        return temp;
+    }
+
+    var folder = new Folder();
+
+    folder[pathProperty] = info.path;
+    folder[nameProperty] = info.name;
+
+    return folder;
+};
+
+export class FileSystemEntity {
+    /**
+    * Gets the Folder object representing the parent of this entity. Will be null for a root folder like Documents or Temporary.
+    */
+    get parent(): Folder {
+        var onError = function (error) {
+            throw error;
+        }
+
+        var folderInfo = getFileAccess().getParent(this.path, onError);
+        if (!folderInfo) {
+            return undefined;
+        }
+
+        return createFolder(folderInfo);
+    }
+
+    public remove(): promises.Promise<any> {
+        var fileAccess = getFileAccess();
+        var promise = promises.defer<any>();
+
+        var localSucces = function () {
+            promise.resolve();
+        }
+        var localError = function (error: any) {
+            promise.reject(error);
+        }
+
+        if (this instanceof File) {
+            fileAccess.deleteFile(this.path, localSucces, localError);
+        } else if (this instanceof Folder) {
+            fileAccess.deleteFolder(this.path, this[isKnownProperty], localSucces, localError);
+        }
+
+        return promise.promise();
+    }
+
+    public rename(newName: string): promises.Promise<any> {
+        var deferred = promises.defer<any>();
+
+        if (this instanceof Folder) {
+            if (this[isKnownProperty]) {
+                deferred.reject(new Error("Cannot rename known folder."));
+                return deferred.promise();
+            }
+        }
+
+        var parentFolder = this.parent;
+        if (!parentFolder) {
+            deferred.reject(new Error("No parent folder."));
+            return deferred.promise();
+        }
+
+        var fileAccess = getFileAccess();
+        var path = parentFolder.path;
+        var newPath = fileAccess.joinPath(path, newName);
+
+        var that = this;
+        var localSucceess = function () {
+            that[pathProperty] = newPath;
+            that[nameProperty] = newName;
+
+            if (that instanceof File) {
+                that[extensionProperty] = fileAccess.getFileExtension(newPath);
+            }
+
+            deferred.resolve();
+        }
+
+        var localError = function (error) {
+            deferred.reject(error);
+        }
+
+        fileAccess.rename(this.path, newPath, localSucceess, localError);
+
+        return deferred.promise();
+    }
+
+    get name(): string {
+        return this[nameProperty];
+    }
+
+    get path(): string {
+        return this[pathProperty];
+    }
+
+    get lastModified(): Date {
+        var value = this[lastModifiedProperty];
+        if (!this[lastModifiedProperty]) {
+            value = this[lastModifiedProperty] = getFileAccess().getLastModified(this.path);
+        }
+
+        return value;
+    }
+}
+
+export class File extends FileSystemEntity {
+
+    public static fromPath(path: string) {
+        var onError = function (error) {
+            throw error;
+        }
+
+        var fileInfo = getFileAccess().getFile(path, onError);
+        if (!fileInfo) {
+            return undefined;
+        }
+
+        return createFile(fileInfo);
+    }
+
+    public static exists(path: string): boolean {
+        return getFileAccess().fileExists(path);
+    }
+
+    get extension(): string {
+        return this[extensionProperty];
+    }
+
+    get isLocked(): boolean {
+        return this[fileLockedProperty];
+    }
+
+    public readText(encoding?: string): promises.Promise<string> {
+        this.checkAccess();
+
+        var deferred = promises.defer<string>();
+        this[fileLockedProperty] = true;
+
+        var that = this;
+        var localSuccess = function (content: string) {
+            that[fileLockedProperty] = false;
+            deferred.resolve(content);
+        }
+
+        var localError = function (error) {
+            that[fileLockedProperty] = false;
+            deferred.reject(error);
+        }
+
+        // TODO: Asyncronous
+        getFileAccess().readText(this.path, localSuccess, localError, encoding);
+
+        return deferred.promise();
+    }
+
+    public writeText(content: string, encoding?: string): promises.Promise<any> {
+        this.checkAccess();
+
+        var deferred = promises.defer<string>();
+        this[fileLockedProperty] = true;
+
+        var that = this;
+        var localSuccess = function () {
+            that[fileLockedProperty] = false;
+            deferred.resolve();
+        };
+
+        var localError = function (error) {
+            that[fileLockedProperty] = false;
+            deferred.reject(error);
+        };
+
+        // TODO: Asyncronous
+        getFileAccess().writeText(this.path, content, localSuccess, localError, encoding);
+
+        return deferred.promise();
+    }
+
+    private checkAccess() {
+        if (this.isLocked) {
+            throw new Error("Cannot access a locked file.");
+        }
+    }
+}
+
+export class Folder extends FileSystemEntity {
+
+    public static fromPath(path: string): Folder {
+        var onError = function (error) {
+            throw error;
+        }
+
+        var folderInfo = getFileAccess().getFolder(path, onError);
+        if (!folderInfo) {
+            return undefined;
+        }
+
+        return createFolder(folderInfo);
+    }
+
+    public static exists(path: string): boolean {
+        return getFileAccess().folderExists(path);
+    }
+
+    public contains(name: string): boolean {
+        var fileAccess = getFileAccess();
+        var path = fileAccess.joinPath(this.path, name);
+
+        if (fileAccess.fileExists(path)) {
+            return true;
+        }
+
+        return fileAccess.folderExists(path);
+    }
+
+    public clear(): promises.Promise<any> {
+        var deferred = promises.defer<any>();
+
+        var onSuccess = function () {
+            deferred.resolve();
+        }
+        var onError = function (error) {
+            deferred.reject(error);
+        }
+
+        getFileAccess().emptyFolder(this.path, onSuccess, onError);
+
+        return deferred.promise();
+    }
+
+    get isKnown(): boolean {
+        return this[isKnownProperty];
+    }
+
+    public getFile(name: string): File {
+        var fileAccess = getFileAccess();
+        var path = fileAccess.joinPath(this.path, name);
+
+        var onError = function (error) {
+            throw error;
+        }
+
+        var fileInfo = fileAccess.getFile(path, onError);
+        if (!fileInfo) {
+            return undefined;
+        }
+
+        return createFile(fileInfo);
+    }
+
+    public getFolder(name: string): Folder {
+        var fileAccess = getFileAccess();
+        var path = fileAccess.joinPath(this.path, name);
+
+        var onError = function (error) {
+            throw error;
+        }
+
+        var folderInfo = fileAccess.getFolder(path, onError);
+        if (!folderInfo) {
+            return undefined;
+        }
+
+        return createFolder(folderInfo);
+    }
+
+    public getEntities(): promises.Promise<Array<FileSystemEntity>> {
+        var deferred = promises.defer<Array<FileSystemEntity>>();
+
+        var onSuccess = function (fileInfos: Array<{ path: string; name: string; extension: string }>) {
+            var entities = new Array<FileSystemEntity>();
+            var i,
+                path: string,
+                entity: FileSystemEntity;
+
+            for (i = 0; i < fileInfos.length; i++) {
+                if (fileInfos[i].extension) {
+                    entities.push(createFile(fileInfos[i]));
+                } else {
+                    entities.push(createFolder(fileInfos[i]));
+                }
+            }
+
+            deferred.resolve(entities);
+        }
+
+        var onError = function (error) {
+            throw error;
+        }
+
+        getFileAccess().getEntities(this.path, onSuccess, onError);
+
+        return deferred.promise();
+    }
+
+    public eachEntity(onEntity: (entity: FileSystemEntity) => boolean) {
+        if (!onEntity) {
+            return;
+        }
+
+        var onSuccess = function (fileInfo: { path: string; name: string; extension: string }): boolean {
+            var entity;
+            if (fileInfo.extension) {
+                entity = createFile(fileInfo);
+            } else {
+                entity = createFolder(fileInfo);
+            }
+
+            return onEntity(entity);
+        }
+
+        var onError = function (error) {
+            throw error;
+        }
+
+        getFileAccess().eachEntity(this.path, onSuccess, onError);
+    }
+}
+
+export module knownFolders {
+    var _documents: Folder;
+    var _temp: Folder;
+
+    export var documents = function (): Folder {
+        if (!_documents) {
+            var path = getFileAccess().getDocumentsFolderPath();
+            _documents = new Folder();
+            _documents[pathProperty] = path;
+            _documents[isKnownProperty] = true;
+        }
+
+        return _documents;
+    };
+
+    export var temp = function (): Folder {
+        if (!_temp) {
+            var path = getFileAccess().getTempFolderPath();
+            _temp = new Folder();
+            _temp[pathProperty] = path;
+            _temp[isKnownProperty] = true;
+        }
+
+        return _temp;
+    }
+}
+
+export module path {
+
+    export function normalize(path: string): string {
+        return getFileAccess().normalizePath(path);
+    }
+
+    export function join(...paths: string[]): string {
+        var fileAccess = getFileAccess();
+        return fileAccess.joinPaths(paths);
+    }
+
+    export var separator = getFileAccess().getPathSeparator();
+}

file-system/index.ts

@@ -0,0 +1,2 @@
+declare var module, require;
+module.exports = require("filesystem/file_system");