# file-disk > Handles reads / writes on disk image files. Latest version **8.0.1** (published 2020-11-26) · Apache-2.0 license · 0 weekly downloads > **Deprecated.** This package is deprecated. ## Install ```sh npm install file-disk pnpm add file-disk yarn add file-disk bun add file-disk ``` ## Health **Score 10/100 (F)** — status: deprecated. Negative: deprecated. ## Facts | | | |---|---| | Version | 8.0.1 | | Published | 2020-11-26 | | First published | 2017-04-25 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 1 | | Unpacked size | 56.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 7 | | Author | Petros Angelatos | | Maintainers | balena.io | ## Links - npm: https://www.npmjs.com/package/file-disk - Repository: https://github.com/balena-io-modules/file-disk - Issues: https://github.com/balena-io-modules/file-disk/issues - npm.io page: https://npm.io/package/file-disk ## Dependencies (1) - [tslib](https://npm.io/package/tslib.md) ^2.0.0 ## Recent versions - 8.0.1 (latest) — 2020-11-26 - 6.0.2-tslib2-1b3f73adf72fa22e6660358d4abd029695544560 (tslib2-1b3f73adf72fa22e6660358d4abd029695544560) — 2020-07-14 - 6.0.2-tslib3-50e6bfcbb5e6e724819c965ff8b200500f4be712 (tslib3-50e6bfcbb5e6e724819c965ff8b200500f4be712) — 2020-07-14 - 6.0.2-tslib-1b3f73adf72fa22e6660358d4abd029695544560 (tslib-1b3f73adf72fa22e6660358d4abd029695544560) — 2020-07-14 - 6.0.2-tslib-a970141ed38ea00958d13f9e2de71f40b7ce7002 (tslib-a970141ed38ea00958d13f9e2de71f40b7ce7002) — 2020-07-14 - 6.0.2-tslib-c1e8b22d02821019031db6dd6e2a13003ff6f4ec (tslib-c1e8b22d02821019031db6dd6e2a13003ff6f4ec) — 2020-07-14 - 6.0.2-tslib-dbecf5c9eadfb3834f212949c4f11e83b21f7702 (tslib-dbecf5c9eadfb3834f212949c4f11e83b21f7702) — 2020-07-14 - 6.0.2-tslib-b3f1223d58637164ef3b99d7d4cd8d011097f011 (tslib-b3f1223d58637164ef3b99d7d4cd8d011097f011) — 2020-07-14 - 6.0.2-tslib-e118190a2547a7003f2fc15bb430812078618551 (tslib-e118190a2547a7003f2fc15bb430812078618551) — 2020-07-14 - 8.0.1-add-versionbot-changelog-be30ba6813603008ef4444cc1acdbb85cdf31db3 — 2020-11-26 - 8.0.0 — 2020-07-27 - 8.0.0-remove-bluebird-94c51dce0084a5241e5b8e0d04d8d02e795cf404 — 2020-07-27 - 8.0.0-remove-bluebird-c3e7f3368eefd8df31c25f92afb858501c3b10aa — 2020-07-27 - 7.0.1 — 2020-07-24 - 7.0.1-exclude-tests-8ef57a5649fb1873a6b91afa00fd99b7401d5ebb — 2020-07-24 - … 32 more at https://npm.io/package/file-disk/versions ## README # file-disk Handles reads / writes on disk image files. ## API **Warning: The API exposed by this library is still forming and can change at any time!** ### FileDisk `new FileDisk(fd, readOnly, recordWrites, recordReads, discardIsZero=true)` - `fd` is a file descriptor returned by `fs.open` - `readOnly` a boolean (default `false`) - `recordWrites`, a boolean (default `false`); if you use `readOnly` without `recordWrites`, all write requests will be lost. - `recordReads`, a boolean (default `false`): cache reads in memory - `discardIsZero`, a boolean (default `true`): don't read discarded regions, return zero filled buffers instead. `FileDisk.getCapacity()`: `Promise` `FileDisk.read(buffer, bufferOffset, length, fileOffset)`: `Promise<{ bytesRead: Number, buffer: Buffer }>` - behaves like [fs.read](https://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) `FileDisk.write(buffer, bufferOffset, length, fileOffset)`: `Promise<{ bytesWritten: Number, buffer: Buffer }>` - behaves like [fs.write](https://nodejs.org/api/fs.html#fs_fs_write_fd_buffer_offset_length_position_callback) `FileDisk.flush()`: `Promise` - behaves like [fs.fdatasync](https://nodejs.org/api/fs.html#fs_fs_fdatasync_fd_callback) `FileDisk.discard(offset, length)`: `Promise` `FileDisk.getStream([position, [length, [highWaterMark]]])`: `Promise` - `position` start reading from this offset (defaults to 0) - `length` read that amount of bytes (defaults to (disk capacity - position)) - `highWaterMark` (defaults to 16384, minimum 16) is the size of chunks that will be read `FileDisk.getDiscardedChunks()` returns the list of discarded chunks. Each chunk has a `start` and `end` properties. `end` position is inclusive. `FileDisk.getRanges(blockSize)`: `Promise` - using the disk's discarded chunks and the given blockSize, it returns a Promise of an array of `Range`s: `{ offset: number, length: number }`. ### S3Disk `S3Disk` has been moved to a [separate repository](https://github.com/balena-io-modules/s3-disk). ## Examples ### Read 1024 first bytes, write them starting at position 1024 then flush. ```javascript const filedisk = require('file-disk'); await filedisk.withOpenFile('/path/to/some/file', 'r+', async (handle) => { const disk = new filedisk.FileDisk(handle) // get file size const size = await disk.getCapacity(); console.log("size:", size); const buf = Buffer.alloc(1024); // read `buf.length` bytes starting at 0 from the file into `buf` const { bytesRead, buffer } = await disk.read(buf, 0, buf.length, 0); // write `buffer` into file starting at `buffer.length` (in the file) await disk.write(buf, 0, buf.length, buf.length); // flush await disk.flush(); }); ``` ### Open a file readOnly, use the recordWrites mode, then stream the contents somewhere. ```javascript const filedisk = require('file-disk'); const BUF = Buffer.alloc(1024); await filedisk.withOpenFile('/path/to/some/file', 'r', async (handle) => { const disk = new filedisk.FileDisk(handle, true, true); let bytesRead, bytesWritten, buffer; // read `BUF.length` bytes starting at 0 from the file into `BUF` { bytesRead, buffer } = await disk.read(BUF, 0, BUF.length, 0); // write `buffer` into file starting at `buffer.length` (in the file) { bytesWritten, buffer } = await disk.write(buffer, 0, buffer.length, buffer.length); const buf2 = Buffer.alloc(1024); // read what we've just written { bytesRead, buffer } = await disk.read(buf2, 0, buffer.length, 0); // writes are stored in memory assert(BUF.equals(buffer)); const stream = await disk.getStream(); // pipe the stream somewhere await new Promise((resolve, reject) => { stream.pipe(someWritableStream) .on('close', resolve) .on('error', reject); }); }); ``` --- _Source: https://npm.io/package/file-disk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._