Path: blob/trunk/javascript/selenium-webdriver/io/index.js
2884 views
// Licensed to the Software Freedom Conservancy (SFC) under one1// or more contributor license agreements. See the NOTICE file2// distributed with this work for additional information3// regarding copyright ownership. The SFC licenses this file4// to you under the Apache License, Version 2.0 (the5// "License"); you may not use this file except in compliance6// with the License. You may obtain a copy of the License at7//8// http://www.apache.org/licenses/LICENSE-2.09//10// Unless required by applicable law or agreed to in writing,11// software distributed under the License is distributed on an12// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY13// KIND, either express or implied. See the License for the14// specific language governing permissions and limitations15// under the License.1617'use strict'1819const fs = require('node:fs')20const path = require('node:path')21const tmp = require('tmp')2223/**24* @param {!Function} fn .25* @return {!Promise<T>} .26* @template T27*/28function checkedCall(fn) {29return new Promise((resolve, reject) => {30try {31fn((err, value) => {32if (err) {33reject(err)34} else {35resolve(value)36}37})38} catch (e) {39reject(e)40}41})42}4344/**45* Recursively removes a directory and all of its contents. This is equivalent46* to {@code rm -rf} on a POSIX system.47* @param {string} dirPath Path to the directory to remove.48* @return {!Promise} A promise to be resolved when the operation has49* completed.50*/51function rmDir(dirPath) {52return new Promise(function (fulfill, reject) {53fs.rm(dirPath, { recursive: true, maxRetries: 2 }, function (err) {54if (err && err.code === 'ENOENT') {55fulfill()56} else if (err) {57reject(err)58}59fulfill()60})61})62}6364/**65* Copies one file to another.66* @param {string} src The source file.67* @param {string} dst The destination file.68* @return {!Promise<string>} A promise for the copied file's path.69*/70function copy(src, dst) {71return new Promise(function (fulfill, reject) {72const rs = fs.createReadStream(src)73rs.on('error', reject)7475const ws = fs.createWriteStream(dst)76ws.on('error', reject)77ws.on('close', () => fulfill(dst))7879rs.pipe(ws)80})81}8283/**84* Recursively copies the contents of one directory to another.85* @param {string} src The source directory to copy.86* @param {string} dst The directory to copy into.87* @param {(RegExp|function(string): boolean)=} opt_exclude An exclusion filter88* as either a regex or predicate function. All files matching this filter89* will not be copied.90* @return {!Promise<string>} A promise for the destination91* directory's path once all files have been copied.92*/93function copyDir(src, dst, opt_exclude) {94let predicate = opt_exclude95if (opt_exclude && typeof opt_exclude !== 'function') {96predicate = function (p) {97return !opt_exclude.test(p)98}99}100101if (!fs.existsSync(dst)) {102fs.mkdirSync(dst)103}104105let files = fs.readdirSync(src)106files = files.map(function (file) {107return path.join(src, file)108})109110if (predicate) {111files = files.filter(/** @type {function(string): boolean} */ (predicate))112}113114const results = []115files.forEach(function (file) {116const stats = fs.statSync(file)117const target = path.join(dst, path.basename(file))118119if (stats.isDirectory()) {120if (!fs.existsSync(target)) {121fs.mkdirSync(target, stats.mode)122}123results.push(copyDir(file, target, predicate))124} else {125results.push(copy(file, target))126}127})128129return Promise.all(results).then(() => dst)130}131132/**133* Tests if a file path exists.134* @param {string} aPath The path to test.135* @return {!Promise<boolean>} A promise for whether the file exists.136*/137function exists(aPath) {138return new Promise(function (fulfill, reject) {139let type = typeof aPath140if (type !== 'string') {141reject(TypeError(`expected string path, but got ${type}`))142} else {143fulfill(fs.existsSync(aPath))144}145})146}147148/**149* Calls `stat(2)`.150* @param {string} aPath The path to stat.151* @return {!Promise<!fs.Stats>} A promise for the file stats.152*/153function stat(aPath) {154return checkedCall((callback) => fs.stat(aPath, callback))155}156157/**158* Deletes a name from the filesystem and possibly the file it refers to. Has159* no effect if the file does not exist.160* @param {string} aPath The path to remove.161* @return {!Promise} A promise for when the file has been removed.162*/163function unlink(aPath) {164return new Promise(function (fulfill, reject) {165const exists = fs.existsSync(aPath)166if (exists) {167fs.unlink(aPath, function (err) {168;(err && reject(err)) || fulfill()169})170} else {171fulfill()172}173})174}175176/**177* @return {!Promise<string>} A promise for the path to a temporary directory.178* @see https://www.npmjs.org/package/tmp179*/180function tmpDir() {181return checkedCall((callback) => tmp.dir({ unsafeCleanup: true }, callback))182}183184/**185* @param {{postfix: string}=} opt_options Temporary file options.186* @return {!Promise<string>} A promise for the path to a temporary file.187* @see https://www.npmjs.org/package/tmp188*/189function tmpFile(opt_options) {190return checkedCall((callback) => {191/** check fixed in v > 0.2.1 if192* (typeof options === 'function') {193* return [{}, options];194* }195*/196tmp.file(opt_options, callback)197})198}199200/**201* Searches the {@code PATH} environment variable for the given file.202* @param {string} file The file to locate on the PATH.203* @param {boolean=} opt_checkCwd Whether to always start with the search with204* the current working directory, regardless of whether it is explicitly205* listed on the PATH.206* @return {?string} Path to the located file, or {@code null} if it could207* not be found.208*/209function findInPath(file, opt_checkCwd) {210const dirs = []211if (opt_checkCwd) {212dirs.push(process.cwd())213}214dirs.push.apply(dirs, process.env['PATH'].split(path.delimiter))215216let foundInDir = dirs.find((dir) => {217let tmp = path.join(dir, file)218try {219let stats = fs.statSync(tmp)220return stats.isFile() && !stats.isDirectory()221/*eslint no-unused-vars: "off"*/222} catch (ex) {223return false224}225})226227return foundInDir ? path.join(foundInDir, file) : null228}229230/**231* Reads the contents of the given file.232*233* @param {string} aPath Path to the file to read.234* @return {!Promise<!Buffer>} A promise that will resolve with a buffer of the235* file contents.236*/237function read(aPath) {238return checkedCall((callback) => fs.readFile(aPath, callback))239}240241/**242* Writes to a file.243*244* @param {string} aPath Path to the file to write to.245* @param {(string|!Buffer)} data The data to write.246* @return {!Promise} A promise that will resolve when the operation has247* completed.248*/249function write(aPath, data) {250return checkedCall((callback) => fs.writeFile(aPath, data, callback))251}252253/**254* Creates a directory.255*256* @param {string} aPath The directory path.257* @return {!Promise<string>} A promise that will resolve with the path of the258* created directory.259*/260function mkdir(aPath) {261return checkedCall((callback) => {262fs.mkdir(aPath, undefined, (err) => {263if (err && err.code !== 'EEXIST') {264callback(err)265} else {266callback(null, aPath)267}268})269})270}271272/**273* Recursively creates a directory and any ancestors that do not yet exist.274*275* @param {string} dir The directory path to create.276* @return {!Promise<string>} A promise that will resolve with the path of the277* created directory.278*/279function mkdirp(dir) {280return checkedCall((callback) => {281fs.mkdir(dir, undefined, (err) => {282if (!err) {283callback(null, dir)284return285}286287switch (err.code) {288case 'EEXIST':289callback(null, dir)290return291case 'ENOENT':292return mkdirp(path.dirname(dir))293.then(() => mkdirp(dir))294.then(295() => callback(null, dir),296(err) => callback(err),297)298default:299callback(err)300return301}302})303})304}305306/**307* Recursively walks a directory, returning a promise that will resolve with308* a list of all files/directories seen.309*310* @param {string} rootPath the directory to walk.311* @return {!Promise<!Array<{path: string, dir: boolean}>>} a promise that will312* resolve with a list of entries seen. For each entry, the recorded path313* will be relative to `rootPath`.314*/315function walkDir(rootPath) {316const seen = []317return (function walk(dir) {318return checkedCall((callback) => fs.readdir(dir, callback)).then((files) =>319Promise.all(320files.map((file) => {321file = path.join(dir, file)322return checkedCall((cb) => fs.stat(file, cb)).then((stats) => {323seen.push({324path: path.relative(rootPath, file),325dir: stats.isDirectory(),326})327return stats.isDirectory() && walk(file)328})329}),330),331)332})(rootPath).then(() => seen)333}334335// PUBLIC API336module.exports = {337walkDir,338rmDir,339mkdirp,340mkdir,341write,342read,343findInPath,344tmpFile,345tmpDir,346unlink,347copy,348copyDir,349exists,350stat,351}352353354