\r\n\r\n----\r\n\r\n[](https://dl.circleci.com/status-badge/redirect/gh/atmajs/atma-io/tree/master)\r\n[](http://badge.fury.io/js/atma-io)\r\n\r\nFeatures:\r\n\r\n- File Class.\r\n- Directory Class.\r\n- File IO Middlewares to preprocess reads and writes actions.\r\n- File Transport middleware for custom file protocols, e.g. `s3://uploads/avatar.png`\r\n- Sync and Async\r\n- Safe Files to ensure thread-safe and process-safe file writes.\r\n- File-locks to make custom process-safe actions easy to implement.\r\n- File watcher: cross-platform file watchers.\r\n- AES-256 Encryption\r\n- HTTP Transport: `get`, `post`, `put`, `head` and `delete` methods to handle files.\r\n\r\n\r\n----\r\n[📚 API Documentation](https://docs.atma.dev/atma-io)\r\n----\r\n\r\n> In comparison to NodeJS sync-async contract: all functions with generic name are synchronous, and the `**Async` are asynchronous with the same interface. Sync versions never throw exceptions and are designed to be used in not performance critical applications, like bash scripts, etc. _Go `Async`._\r\n\r\n- [File](#file)\r\n - [API](#file-methods)\r\n - [Cache](#cache)\r\n - [Middleware](#file-middleware)\r\n - [Virtual File](#virtual-files)\r\n- [Directory](#directory)\r\n - [API](#directory-methods)\r\n\r\n### File\r\n\r\n#### File methods\r\n\r\n##### File constructor\r\n```ts\r\nimport { File } from 'atma-io'\r\n\r\nconst file = new File('./test.txt');\r\n```\r\n\r\nPath is relative to the `cwd` (_except windows os, when drive letter is used_). To specify system absolute path, use `file://` protocol.\r\n\r\n##### `read` `readAsync`\r\nRead file's content. If `encoding` is set to null raw `Buffer` is returned.\r\nFor each `read` middleware pipeline is used, to skip it, set `skipHooks` to true.\r\n\r\n> Hooks will be per default executed. For example, when reading from `*.json` file the string will be deserialized to json object\r\n\r\n```ts\r\nlet content = file.read( options?: {\r\n encoding?: 'buffer' | 'utf8' //> default 'utf8'\r\n skipHooks?: boolean //> false\r\n aes256?: { secret: string }\r\n});\r\n\r\nlet content = await file.readAsync (options?: {\r\n encoding?: 'buffer' | 'utf8', //> 'utf8'\r\n skipHooks?: boolean //> false\r\n aes256?: { secret: string }\r\n});\r\n```\r\n\r\n##### `readRange` `readRangeAsync`\r\nGet bytes or string for a range from the file\r\n\r\n```ts\r\nlet content = file.readRange(position, length);\r\n\r\nlet content = await file.readRangeAsync(position, length)\r\n```\r\n\r\n##### `write` `writeAsync`\r\n\r\n> Hooks will be per default executed. For example, when writing to `*.json` file and providing an object, this object will be serialized to json string\r\n\r\n```ts\r\nfile.write(string | Buffer | any, options?: {\r\n skipHooks?: boolean\r\n aes256?: { secret: string }\r\n})\r\n\r\nfile\r\n .writeAsync(content: string | Buffer | any, options?: {\r\n skipHooks?: boolean\r\n aes256?: { secret: string }\r\n })\r\n .then(() => {}, (err) => {})\r\n```\r\n\r\n\r\n##### `append` `appendAsync`\r\n```ts\r\nfile.append(content: string)\r\n\r\nawait file.appendAsync(string);\r\n```\r\n\r\n##### `exists` `existsAsync`\r\n```ts\r\nlet b: boolean = file.exists()\r\n\r\nlet b: boolean = await file.existsAsync();\r\n```\r\n\r\n##### `copyTo` `copyToAsync`\r\n```ts\r\ninterface IFileCopyOpts {\r\n silent?: boolean\r\n baseSource?: string\r\n}\r\n/**\r\n * @param path: Target file path or directory, when ends with slash\r\n */\r\nfile.copyTo(path: string, opts?: IFileCopyOpts): boolean\r\n\r\nfile.copyToAsync(path: string, opts?: IFileCopyOpts): Promise\r\n```\r\n\r\n##### `rename` `renameAsync`\r\n```ts\r\nfile.rename(filename: string)\r\n\r\nfile.renameAsync(filename: string): Promise\r\n```\r\n\r\n##### `replace` `replaceAsync`\r\nReads the content as string, replaces the matches and writes the result.\r\nExpected arguments are the same as for JavaScripts string `replace`.\r\nReturns new content.\r\n\r\n```ts\r\nfile.replace(search: string | RegExp, replacer: string | Function): string\r\n\r\nfile.replaceAsync(search: string | RegExp, replacer: string | Function): Promise\r\n```\r\n\r\n##### `remove` `removeAsync`\r\n```ts\r\nfile.remove(): boolean\r\n\r\nfile.removeAsync(): Promise\r\n```\r\n\r\n##### `watch`\r\n\r\nWatch file for changes\r\n\r\n```ts\r\nfile.watch(cb: (path) => void)\r\n```\r\n\r\n##### unwatch\r\n```ts\r\nfile.unwatch(cb?: (path) => void): boolean\r\n```\r\n\r\n#### Cache\r\nEach `read` will be cached. To control cache behavior use next methods:\r\n\r\n##### clearCache\r\n```ts\r\nFile.clearCache( path);\r\n```\r\nWhen `path` is `null`, then all cache is dropped.\r\n##### disableCache\r\n```ts\r\nFile.disableCache();\r\n```\r\n##### enableCache\r\n```ts\r\nFile.disableCache();\r\n```\r\n\r\n#### short forms\r\nThere are some static methods, so that there is no need to initialize the File instance.\r\n```ts\r\nFile[method] //> Function(filepath, [..args])\r\n// methods:\r\n 'exists'\r\n 'existsAsync'\r\n 'read'\r\n 'readAsync'\r\n 'readRange'\r\n 'readRangeAsync'\r\n 'write'\r\n 'writeAsync'\r\n 'append'\r\n 'appendAsync'\r\n 'remove'\r\n 'removeAsync'\r\n 'replace'\r\n 'replaceAsync'\r\n 'rename'\r\n 'renameAsync'\r\n 'copyTo'\r\n 'copyToAsync'\r\n\r\n// sample\r\nFile\r\n .readAsync('/baz.txt')\r\n .done(function(content){\r\n console.log(content);\r\n })\r\n .fail(function(error){\r\n console.error(error);\r\n })\r\n ;\r\n```\r\n\r\n### File Middleware\r\nMiddleware pattern is used for all reads and writes. It can be used, for example, to compile coffee script to javascript on the fly. Or when reading `*.yml` file, the resulted content is not a YAML string, but already parsed object.\r\n\r\n#### Extensions\r\n\r\nTo get the idea, look at the hook definition sample:\r\n```ts\r\nimport { File } from 'atma-io'\r\nFile.registerExtensions({\r\n 'coffee':[\r\n 'conditions:read',\r\n 'coffee-compiler:read',\r\n 'uglify:write'\r\n ]\r\n});\r\n```\r\nEach middleware has unique name and is registered in this way:\r\n```ts\r\nimport { File } from 'atma-io'\r\nFile.middleware['coffee'] = {\r\n read: function( file,
\r\n