@ -1,11 +1,10 @@
/ * * / * *
* Way data is stored for this database * Way data is stored for this database .
* For a Node . js / Node Webkit database it ' s the file system * This version is the Node . js / Node Webkit version .
* For a browser - side database it ' s localforage , which uses the best backend available ( IndexedDB then WebSQL then localStorage ) * It ' s essentially fs , mkdirp and crash safe write and read functions .
* For a react - native database , we use @ react - native - async - storage / async - storage
* *
* This version is the Node . js / Node Webkit version * @ see module : storageBrowser
* It ' s essentially fs , mkdirp and crash safe write and read functions * @ see module : storageReactNative
* @ module storage * @ module storage
* / * /
const fs = require ( 'fs' ) const fs = require ( 'fs' )
@ -20,7 +19,7 @@ const { Readable } = require('stream')
* / * /
/ * * / * *
* Callback returns true if file exists * Callback returns true if file exists .
* @ param { string } file * @ param { string } file
* @ param { module : storage ~ existsCallback } cb * @ param { module : storage ~ existsCallback } cb
* @ alias module : storage . exists * @ alias module : storage . exists
@ -29,16 +28,17 @@ const { Readable } = require('stream')
const exists = ( file , cb ) => fs . access ( file , fs . constants . F _OK , ( err ) => { cb ( ! err ) } ) const exists = ( file , cb ) => fs . access ( file , fs . constants . F _OK , ( err ) => { cb ( ! err ) } )
/ * * / * *
* Returns Promise < true > if file exists * Async version of { @ link module : storage . exists } .
* @ param { string } file * @ param { string } file
* @ return { Promise < boolean > } * @ return { Promise < boolean > }
* @ async * @ async
* @ alias module : storage . existsAsync * @ alias module : storage . existsAsync
* @ see module : storage . exists
* / * /
const existsAsync = file => fsPromises . access ( file , fs . constants . F _OK ) . then ( ( ) => true , ( ) => false ) const existsAsync = file => fsPromises . access ( file , fs . constants . F _OK ) . then ( ( ) => true , ( ) => false )
/ * * / * *
* Node . js ' fs . rename * Node . js ' [ fs . rename ] { @ link https : //nodejs.org/api/fs.html#fsrenameoldpath-newpath-callback}.
* @ function * @ function
* @ param { string } oldPath * @ param { string } oldPath
* @ param { string } newPath * @ param { string } newPath
@ -49,18 +49,19 @@ const existsAsync = file => fsPromises.access(file, fs.constants.F_OK).then(() =
const rename = fs . rename const rename = fs . rename
/ * * / * *
* Node . js ' fs . promises . rename * Async version of { @ link module : storage . rename } .
* @ function * @ function
* @ param { string } oldPath * @ param { string } oldPath
* @ param { string } newPath * @ param { string } newPath
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . renameAsync * @ alias module : storage . renameAsync
* @ async * @ async
* @ see module : storage . rename
* / * /
const renameAsync = fsPromises . rename const renameAsync = fsPromises . rename
/ * * / * *
* Node . js ' fs . writeFile * Node . js ' [ fs . writeFile ] { @ link https : //nodejs.org/api/fs.html#fswritefilefile-data-options-callback}.
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { string } data * @ param { string } data
@ -71,7 +72,7 @@ const renameAsync = fsPromises.rename
const writeFile = fs . writeFile const writeFile = fs . writeFile
/ * * / * *
* Node . js ' fs . promises . writeFile * Async version of { @ link module : storage . writeFile } .
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { string } data * @ param { string } data
@ -79,11 +80,12 @@ const writeFile = fs.writeFile
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . writeFileAsync * @ alias module : storage . writeFileAsync
* @ async * @ async
* @ see module : storage . writeFile
* / * /
const writeFileAsync = fsPromises . writeFile const writeFileAsync = fsPromises . writeFile
/ * * / * *
* Node . js ' fs . createWriteStream * Node . js ' [ fs . createWriteStream ] { @ link https : //nodejs.org/api/fs.html#fscreatewritestreampath-options}.
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { Object } [ options ] * @ param { Object } [ options ]
@ -93,7 +95,7 @@ const writeFileAsync = fsPromises.writeFile
const writeFileStream = fs . createWriteStream const writeFileStream = fs . createWriteStream
/ * * / * *
* Node . js ' fs . unlink * Node . js ' [ fs . unlink ] { @ link https : //nodejs.org/api/fs.html#fsunlinkpath-callback}.
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { function } callback * @ param { function } callback
@ -102,17 +104,18 @@ const writeFileStream = fs.createWriteStream
const unlink = fs . unlink const unlink = fs . unlink
/ * * / * *
* Node . js ' fs . promises . unlink * Async version of { @ link module : storage . unlink } .
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ return { Promise < void > } * @ return { Promise < void > }
* @ async * @ async
* @ alias module : storage . unlinkAsync * @ alias module : storage . unlinkAsync
* @ see module : storage . unlink
* / * /
const unlinkAsync = fsPromises . unlink const unlinkAsync = fsPromises . unlink
/ * * / * *
* Node . js ' fs . appendFile * Node . js ' [ fs . appendFile ] { @ link https : //nodejs.org/api/fs.html#fsappendfilepath-data-options-callback}.
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { string } data * @ param { string } data
@ -123,7 +126,7 @@ const unlinkAsync = fsPromises.unlink
const appendFile = fs . appendFile const appendFile = fs . appendFile
/ * * / * *
* Node . js ' fs . promises . appendFile * Async version of { @ link module : storage . appendFile } .
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { string } data * @ param { string } data
@ -131,10 +134,12 @@ const appendFile = fs.appendFile
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . appendFileAsync * @ alias module : storage . appendFileAsync
* @ async * @ async
* @ see module : storage . appendFile
* / * /
const appendFileAsync = fsPromises . appendFile const appendFileAsync = fsPromises . appendFile
/ * * / * *
* Node . js ' fs . readFile * Node . js ' [ fs . readFile ] { @ link https : //nodejs.org/api/fs.html#fsreadfilepath-options-callback}
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { object } options * @ param { object } options
@ -142,18 +147,21 @@ const appendFileAsync = fsPromises.appendFile
* @ alias module : storage . readFile * @ alias module : storage . readFile
* / * /
const readFile = fs . readFile const readFile = fs . readFile
/ * * / * *
* Node . js ' fs . promises . readFile * Async version of { @ link module : storage . readFile } .
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { object } [ options ] * @ param { object } [ options ]
* @ return { Promise < Buffer > } * @ return { Promise < Buffer > }
* @ alias module : storage . readFileAsync * @ alias module : storage . readFileAsync
* @ async * @ async
* @ see module : storage . readFile
* / * /
const readFileAsync = fsPromises . readFile const readFileAsync = fsPromises . readFile
/ * * / * *
* Node . js ' fs . createReadStream * Node . js ' [ fs . createReadStream ] { @ link https : //nodejs.org/api/fs.html#fscreatereadstreampath-options}.
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { Object } [ options ] * @ param { Object } [ options ]
@ -161,8 +169,9 @@ const readFileAsync = fsPromises.readFile
* @ alias module : storage . readFileStream * @ alias module : storage . readFileStream
* / * /
const readFileStream = fs . createReadStream const readFileStream = fs . createReadStream
/ * * / * *
* Node . js ' fs . mkdir * Node . js ' [ fs . mkdir ] { @ link https : //nodejs.org/api/fs.html#fsmkdirpath-options-callback}.
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { object } options * @ param { object } options
@ -170,28 +179,33 @@ const readFileStream = fs.createReadStream
* @ alias module : storage . mkdir * @ alias module : storage . mkdir
* / * /
const mkdir = fs . mkdir const mkdir = fs . mkdir
/ * * / * *
* Node . js ' fs . promises . mkdir * Async version of { @ link module : storage . mkdir } .
* @ function * @ function
* @ param { string } path * @ param { string } path
* @ param { object } options * @ param { object } options
* @ return { Promise < void | string > } * @ return { Promise < void | string > }
* @ alias module : storage . mkdirAsync * @ alias module : storage . mkdirAsync
* @ async * @ async
* @ see module : storage . mkdir
* / * /
const mkdirAsync = fsPromises . mkdir const mkdirAsync = fsPromises . mkdir
/ * * / * *
* Async version of { @ link module : storage . ensureFileDoesntExist }
* @ param { string } file * @ param { string } file
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . ensureFileDoesntExistAsync * @ alias module : storage . ensureFileDoesntExistAsync
* @ async * @ async
* @ see module : storage . ensureFileDoesntExist
* / * /
const ensureFileDoesntExistAsync = async file => { const ensureFileDoesntExistAsync = async file => {
if ( await existsAsync ( file ) ) await unlinkAsync ( file ) if ( await existsAsync ( file ) ) await unlinkAsync ( file )
} }
/ * * / * *
* Removes file if it exists .
* @ param { string } file * @ param { string } file
* @ param { NoParamCallback } callback * @ param { NoParamCallback } callback
* @ alias module : storage . ensureFileDoesntExist * @ alias module : storage . ensureFileDoesntExist
@ -199,7 +213,7 @@ const ensureFileDoesntExistAsync = async file => {
const ensureFileDoesntExist = ( file , callback ) => callbackify ( ensureFileDoesntExistAsync ) ( file , err => callback ( err ) ) const ensureFileDoesntExist = ( file , callback ) => callbackify ( ensureFileDoesntExistAsync ) ( file , err => callback ( err ) )
/ * * / * *
* Flush data in OS buffer to storage if corresponding option is set * Flush data in OS buffer to storage if corresponding option is set .
* @ param { object | string } options If options is a string , it is assumed that the flush of the file ( not dir ) called options was requested * @ param { object | string } options If options is a string , it is assumed that the flush of the file ( not dir ) called options was requested
* @ param { string } [ options . filename ] * @ param { string } [ options . filename ]
* @ param { boolean } [ options . isDir = false ] Optional , defaults to false * @ param { boolean } [ options . isDir = false ] Optional , defaults to false
@ -209,13 +223,14 @@ const ensureFileDoesntExist = (file, callback) => callbackify(ensureFileDoesntEx
const flushToStorage = ( options , callback ) => callbackify ( flushToStorageAsync ) ( options , callback ) const flushToStorage = ( options , callback ) => callbackify ( flushToStorageAsync ) ( options , callback )
/ * * / * *
* Flush data in OS buffer to storage if corresponding option is set * Async version of { @ link module : storage . flushToStorage } .
* @ param { object | string } options If options is a string , it is assumed that the flush of the file ( not dir ) called options was requested * @ param { object | string } options
* @ param { string } [ options . filename ] * @ param { string } [ options . filename ]
* @ param { boolean } [ options . isDir = false ] Optional , defaults to false * @ param { boolean } [ options . isDir = false ]
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . flushToStorageAsync * @ alias module : storage . flushToStorageAsync
* @ async * @ async
* @ see module : storage . flushToStorage
* / * /
const flushToStorageAsync = async ( options ) => { const flushToStorageAsync = async ( options ) => {
let filename let filename
@ -266,10 +281,10 @@ const flushToStorageAsync = async (options) => {
} }
/ * * / * *
* Fully write or rewrite the datafile * Fully write or rewrite the datafile .
* @ param { string } filename * @ param { string } filename
* @ param { string [ ] } lines * @ param { string [ ] } lines
* @ param { NoParamCallback } callback * @ param { NoParamCallback } [ callback = ( ) => { } ]
* @ alias module : storage . writeFileLines * @ alias module : storage . writeFileLines
* / * /
const writeFileLines = ( filename , lines , callback = ( ) => { } ) => { const writeFileLines = ( filename , lines , callback = ( ) => { } ) => {
@ -293,17 +308,18 @@ const writeFileLines = (filename, lines, callback = () => {}) => {
} }
} }
/ * * / * *
* Fully write or rewrite the datafile * Async version of { @ link module : storage . writeFileLines } .
* @ param { string } filename * @ param { string } filename
* @ param { string [ ] } lines * @ param { string [ ] } lines
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . writeFileLinesAsync * @ alias module : storage . writeFileLinesAsync
* @ async * @ async
* @ see module : storage . writeFileLines
* / * /
const writeFileLinesAsync = ( filename , lines ) => promisify ( writeFileLines ) ( filename , lines ) const writeFileLinesAsync = ( filename , lines ) => promisify ( writeFileLines ) ( filename , lines )
/ * * / * *
* Fully write or rewrite the datafile , immune to crashes during the write operation ( data will not be lost ) * Fully write or rewrite the datafile , immune to crashes during the write operation ( data will not be lost ) .
* @ param { string } filename * @ param { string } filename
* @ param { string [ ] } lines * @ param { string [ ] } lines
* @ param { NoParamCallback } [ callback ] Optional callback , signature : err * @ param { NoParamCallback } [ callback ] Optional callback , signature : err
@ -313,11 +329,12 @@ const crashSafeWriteFileLines = (filename, lines, callback = () => {}) => {
callbackify ( crashSafeWriteFileLinesAsync ) ( filename , lines , callback ) callbackify ( crashSafeWriteFileLinesAsync ) ( filename , lines , callback )
} }
/ * * / * *
* Fully write or rewrite the datafile , immune to crashes during the write operation ( data will not be lost ) * Async version of { @ link module : storage . crashSafeWriteFileLines } .
* @ param { string } filename * @ param { string } filename
* @ param { string [ ] } lines * @ param { string [ ] } lines
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . crashSafeWriteFileLinesAsync * @ alias module : storage . crashSafeWriteFileLinesAsync
* @ see module : storage . crashSafeWriteFileLines
* / * /
const crashSafeWriteFileLinesAsync = async ( filename , lines ) => { const crashSafeWriteFileLinesAsync = async ( filename , lines ) => {
const tempFilename = filename + '~' const tempFilename = filename + '~'
@ -337,7 +354,7 @@ const crashSafeWriteFileLinesAsync = async (filename, lines) => {
} }
/ * * / * *
* Ensure the datafile contains all the data , even if there was a crash during a full file write * Ensure the datafile contains all the data , even if there was a crash during a full file write .
* @ param { string } filename * @ param { string } filename
* @ param { NoParamCallback } callback signature : err * @ param { NoParamCallback } callback signature : err
* @ alias module : storage . ensureDatafileIntegrity * @ alias module : storage . ensureDatafileIntegrity
@ -345,10 +362,11 @@ const crashSafeWriteFileLinesAsync = async (filename, lines) => {
const ensureDatafileIntegrity = ( filename , callback ) => callbackify ( ensureDatafileIntegrityAsync ) ( filename , callback ) const ensureDatafileIntegrity = ( filename , callback ) => callbackify ( ensureDatafileIntegrityAsync ) ( filename , callback )
/ * * / * *
* Ensure the datafile contains all the data , even if there was a crash during a full file write * Async version of { @ link module : storage . ensureDatafileIntegrity } .
* @ param { string } filename * @ param { string } filename
* @ return { Promise < void > } * @ return { Promise < void > }
* @ alias module : storage . ensureDatafileIntegrityAsync * @ alias module : storage . ensureDatafileIntegrityAsync
* @ see module : storage . ensureDatafileIntegrity
* / * /
const ensureDatafileIntegrityAsync = async filename => { const ensureDatafileIntegrityAsync = async filename => {
const tempFilename = filename + '~' const tempFilename = filename + '~'
Timothée Rebours
3 years ago