Merge pull request #1 from medayo/feat/shims

Feat/shims
This commit is contained in:
Ben Heidemann 2021-02-20 04:09:06 +00:00 committed by GitHub
commit a60d2b4cfc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 165 additions and 0 deletions

View File

@ -54,6 +54,103 @@ requirejs(['filer'], function(Filer) {...}
var Filer = window.Filer;
```
### Webpack
Filer can be used as a drop-in replacement for the node.js [fs module](http://nodejs.org/api/fs.html) using webpack.
In order to use filer in place of fs, insert the following into your webpack config:
```javascript
// webpack.config.js
module.exports = {
resolve: {
alias: {
'fs': 'filer/shims/fs.js',
}
}
}
```
You can then import the node.js [fs module](http://nodejs.org/api/fs.html) as normal
and the shim will ensure that calls to fs are appropriately handled by filer.
```javascript
import fs from 'fs';
```
If any calls are made to fs or fs.promises methods before the file system has been
initialised, the shim will automatically delay the call until the file system is ready.
If you're using filer in a typescript project, the fs shim has the added
benefit of allowing you to use the types for the node.js [fs module](http://nodejs.org/api/fs.html),
which filer tries to match as closely as possible. Note that some methods from fs are
not available, even though typescript will tell you that they are! See [Getting Started](#getting-started)
for more details on filers limitations.
If you wish to use an alternative file sytem in place of the default (IndexedDB), you must also
include an alias for this in your webpack config. For example, if you wish to use an "in memory"
file system, configure webpack as shown below.
```javascript
// webpack.config.js
module.exports = {
resolve: {
alias: {
'fsprovider': 'filer/shims/providers/memory.js',
'fs': 'filer/shims/fs.js',
}
}
}
```
The current options for file system providers are:
* Default (IndexedDB) - filer/shims/providers/default.js
* IndexedDB - filer/shims/providers/default.js
* Memory - filer/shims/providers/memory.js
Though it's technically optional, it is recommended to include an alias for fsprovider in your
webpack config. This will prevent webpack from logging unnecessary warnings.
If you wish to use your own file system provider with the node.js [fs module](http://nodejs.org/api/fs.html)
shim, it will be necessary to include an alias for fsprovider which points to your providers implementation.
This can be done as follows:
```javascript
// webpack.config.js
const path = require('path');
module.exports = {
resolve: {
alias: {
'fsprovider': path.resolve(__dirname, 'example/dir/provider.js'),
'fs': 'filer/shims/fs.js',
}
}
}
```
The node.js [path module](http://nodejs.org/api/path.html) also has a shim available, which can
be applied in a similar manner to the node.js [fs module](http://nodejs.org/api/fs.html) shim.
```javascript
// webpack.config.js
module.exports = {
resolve: {
alias: {
'path': 'filer/shims/path.js',
}
}
}
```
You can then import the node.js [path module](http://nodejs.org/api/path.html) as normal and the
shim will ensure that calls to path are appropriately handled by filer.
```javascript
import path from 'path';
```
### Getting Started
Filer is as close to the node.js [fs module](http://nodejs.org/api/fs.html) as possible,

56
shims/fs.js Normal file
View File

@ -0,0 +1,56 @@
const { FileSystem } = require('../src/index');
let Provider;
try {
Provider = require('fsprovider');
}
catch {
Provider = require('./providers/default');
}
const provider = new Provider();
let onFsReady;
let onFsError;
let fsReady = new Promise((resolve, reject) => {
onFsReady = resolve;
onFsError = reject;
});
var fsInstance = new FileSystem({ provider }, (err) => {
if (err) {
onFsError(err);
} else {
onFsReady(true);
}
});
const fsPromises = new Proxy(fsInstance.promises, {
get(target, prop) {
return async (...args) => {
await fsReady;
return await target[prop](...args);
};
},
});
const fs = new Proxy(fsInstance, {
get(target, prop) {
if (prop === 'promises') {
return fsPromises;
}
return (...args) => {
(async () => {
await fsReady;
target[prop](...args);
})();
};
},
});
module.exports = {
__esModule: true,
default: fs,
};

6
shims/path.js Normal file
View File

@ -0,0 +1,6 @@
const path = require("./path.js");
module.exports = {
__esModule: true,
default: path,
};

View File

@ -0,0 +1,2 @@
const { Default } = require('../../src/providers/index');
module.exports = Default;

View File

@ -0,0 +1,2 @@
const IndexedDB = require('../../src/providers/indexeddb');
module.exports = IndexedDB;

View File

@ -0,0 +1,2 @@
const Memory = require('../../src/providers/memory');
module.exports = Memory;