first commit

app_vue/node_modules/gensync/README.md

@@ -0,0 +1,196 @@
+# gensync
+
+This module allows for developers to write common code that can share
+implementation details, hiding whether an underlying request happens
+synchronously or asynchronously. This is in contrast with many current Node
+APIs which explicitly implement the same API twice, once with calls to
+synchronous functions, and once with asynchronous functions.
+
+Take for example `fs.readFile` and `fs.readFileSync`, if you're writing an API
+that loads a file and then performs a synchronous operation on the data, it
+can be frustrating to maintain two parallel functions.
+
+
+## Example
+
+```js
+const fs = require("fs");
+const gensync = require("gensync");
+
+const readFile = gensync({
+  sync: fs.readFileSync,
+  errback: fs.readFile,
+});
+
+const myOperation = gensync(function* (filename) {
+  const code = yield* readFile(filename, "utf8");
+
+  return "// some custom prefix\n" + code;
+});
+
+// Load and add the prefix synchronously:
+const result = myOperation.sync("./some-file.js");
+
+// Load and add the prefix asynchronously with promises:
+myOperation.async("./some-file.js").then(result => {
+
+});
+
+// Load and add the prefix asynchronously with promises:
+myOperation.errback("./some-file.js", (err, result) => {
+
+});
+```
+
+This could even be exposed as your official API by doing
+```js
+// Using the common 'Sync' suffix for sync functions, and 'Async' suffix for
+// promise-returning versions.
+exports.myOperationSync = myOperation.sync;
+exports.myOperationAsync = myOperation.async;
+exports.myOperation = myOperation.errback;
+```
+or potentially expose one of the async versions as the default, with a
+`.sync` property on the function to expose the synchronous version.
+```js
+module.exports = myOperation.errback;
+module.exports.sync = myOperation.sync;
+````
+
+
+## API
+
+### gensync(generatorFnOrOptions)
+
+Returns a function that can be "await"-ed in another `gensync` generator
+function, or executed via
+
+* `.sync(...args)` - Returns the computed value, or throws.
+* `.async(...args)` - Returns a promise for the computed value.
+* `.errback(...args, (err, result) => {})` - Calls the callback with the computed value, or error.
+
+
+#### Passed a generator
+
+Wraps the generator to populate the `.sync`/`.async`/`.errback` helpers above to
+allow for evaluation of the generator for the final value.
+
+##### Example
+
+```js
+const readFile = function* () {
+  return 42;
+};
+
+const readFileAndMore = gensync(function* (){
+  const val = yield* readFile();
+  return 42 + val;
+});
+
+// In general cases
+const code = readFileAndMore.sync("./file.js", "utf8");
+readFileAndMore.async("./file.js", "utf8").then(code => {})
+readFileAndMore.errback("./file.js", "utf8", (err, code) => {});
+
+// In a generator being called indirectly with .sync/.async/.errback
+const code = yield* readFileAndMore("./file.js", "utf8");
+```
+
+
+#### Passed an options object
+
+* `opts.sync`
+
+  Example: `(...args) => 4`
+
+  A function that will be called when `.sync()` is called on the `gensync()`
+  result, or when the result is passed to `yield*` in another generator that
+  is being run synchronously.
+
+  Also called for `.async()` calls if no async handlers are provided.
+
+* `opts.async`
+
+  Example: `async (...args) => 4`
+
+  A function that will be called when `.async()` or `.errback()` is called on
+  the `gensync()` result, or when the result is passed to `yield*` in another
+  generator that is being run asynchronously.
+
+* `opts.errback`
+
+  Example: `(...args, cb) => cb(null, 4)`
+
+  A function that will be called when `.async()` or `.errback()` is called on
+  the `gensync()` result, or when the result is passed to `yield*` in another
+  generator that is being run asynchronously.
+
+  This option allows for simpler compatibility with many existing Node APIs,
+  and also avoids introducing the extra even loop turns that promises introduce
+  to access the result value.
+
+* `opts.name`
+
+  Example: `"readFile"`
+
+  A string name to apply to the returned function. If no value is provided,
+  the name of `errback`/`async`/`sync` functions will be used, with any
+  `Sync` or `Async` suffix stripped off. If the callback is simply named
+  with ES6 inference (same name as the options property), the name is ignored.
+
+* `opts.arity`
+
+  Example: `4`
+
+  A number for the length to set on the returned function. If no value
+  is provided, the length will be carried over from the `sync` function's
+  `length` value.
+
+##### Example
+
+```js
+const readFile = gensync({
+  sync: fs.readFileSync,
+  errback: fs.readFile,
+});
+
+const code = readFile.sync("./file.js", "utf8");
+readFile.async("./file.js", "utf8").then(code => {})
+readFile.errback("./file.js", "utf8", (err, code) => {});
+```
+
+
+### gensync.all(iterable)
+
+`Promise.all`-like combinator that works with an iterable of generator objects
+that could be passed to `yield*` within a gensync generator.
+
+#### Example
+
+```js
+const loadFiles = gensync(function* () {
+  return yield* gensync.all([
+    readFile("./one.js"),
+    readFile("./two.js"),
+    readFile("./three.js"),
+  ]);
+});
+```
+
+
+### gensync.race(iterable)
+
+`Promise.race`-like combinator that works with an iterable of generator objects
+that could be passed to `yield*` within a gensync generator.
+
+#### Example
+
+```js
+const loadFiles = gensync(function* () {
+  return yield* gensync.race([
+    readFile("./one.js"),
+    readFile("./two.js"),
+    readFile("./three.js"),
+  ]);
+});
+```