diff options
| author | littleblack111 <littleblack11111@gmail.com> | 2026-05-18 23:10:59 +0800 |
|---|---|---|
| committer | littleblack111 <littleblack11111@gmail.com> | 2026-05-18 23:41:44 +0800 |
| commit | fc87c009806dcc98867f6b58efe29b042aa01dee (patch) | |
| tree | 8f59b3f4a5b66e9dfef2d40c8d318e258a521228 /node_modules/gensync/README.md | |
| parent | 3336b2356ee6152d9c6ae59bd9b87ccbc0958407 (diff) | |
node: updatemain
Diffstat (limited to 'node_modules/gensync/README.md')
| -rw-r--r-- | node_modules/gensync/README.md | 196 |
1 files changed, 0 insertions, 196 deletions
diff --git a/node_modules/gensync/README.md b/node_modules/gensync/README.md deleted file mode 100644 index f68ce1a3..00000000 --- a/node_modules/gensync/README.md +++ /dev/null @@ -1,196 +0,0 @@ -# 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"), - ]); -}); -``` |
