@kaciras/deasync - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

index.d.ts

@@ -21,3 +21,3 @@ /**
  */
-export declare function awaitSync<T>(promise: PromiseLike<T> | T): T;
+export declare function awaitSync<T>(promise: T): Awaited<T>;
 export {};

index.js

@@ -10,3 +10,3 @@ "use strict";
         if (pred())
-            binding_node_1.run();
+            (0, binding_node_1.run)();
     }
@@ -13,0 +13,0 @@ }

package.json

 {
   "name": "@kaciras/deasync",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Turns async code into sync via JavaScript wrapper of Node event loop, support both callback and promise",
@@ -32,16 +32,15 @@ "author": "Kaciras <[e-mail]>",
   "dependencies": {
-    "follow-redirects": "^1.14.4",
+    "follow-redirects": "^1.14.8",
     "tar-fs": "^2.1.1"
   },
   "devDependencies": {
-    "@istanbuljs/nyc-config-typescript": "^1.0.1",
-    "@kaciras/eslint-config-core": "^2.0.0",
-    "@kaciras/eslint-config-typescript": "^2.0.0",
-    "@types/mocha": "^9.0.0",
-    "@types/node": "^16.11.1",
-    "eslint": "^8.0.1",
-    "mocha": "^9.1.3",
-    "nyc": "^15.1.0",
-    "ts-node": "^10.3.0",
-    "typescript": "^4.4.4"
+    "@kaciras/eslint-config-core": "^2.3.0",
+    "@kaciras/eslint-config-typescript": "^2.3.0",
+    "@types/mocha": "^9.1.0",
+    "@types/node": "^17.0.18",
+    "c8": "^7.11.0",
+    "eslint": "^8.9.0",
+    "mocha": "^9.2.0",
+    "ts-node": "^10.5.0",
+    "typescript": "^4.5.5"
   },
@@ -52,5 +51,6 @@ "scripts": {
     "compile:ts": "tsc",
-    "test": "mocha",
-    "test:coverage": "nyc mocha"
-  }
+    "test": "mocha && tsc --project tsconfig-test.json",
+    "test:coverage": "c8 --reporter=lcov mocha"
+  },
+  "readme": "# DeAsync\n\n[![Npm Version](https://img.shields.io/npm/v/@kaciras/deasync)](https://www.npmjs.com/package/@kaciras/deasync)\n![node-current (scoped)](https://img.shields.io/node/v/@kaciras/deasync)\n[![Test](https://github.com/Kaciras/deasync/actions/workflows/test.yml/badge.svg)](https://github.com/Kaciras/deasync/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/Kaciras/deasync/branch/master/graph/badge.svg?token=ST7ROWQH0Z)](https://codecov.io/gh/Kaciras/deasync)\n[![GitHub license](https://img.shields.io/github/license/Kaciras/deasync)](https://github.com/Kaciras/deasync/blob/master/LICENSE)\n\nDeAsync turns async code into sync, implemented with a blocking mechanism by calling Node.js event loop at JavaScript layer. The core of deasync is written in C++.\n\nThis project is forked from [abbr/deasync](https://github.com/abbr/deasync) and rewritten in modern code. There are some new features added: TypeScript types, Promise support, and prebuild binaries.\n\n## Motivation\n\nSuppose you maintain a library that exposes a function `getData`. Your users call it to get actual data:   \n`const myData = getData()`  \nUnder the hood data is saved in a file so you implemented `getData` using Node.js built-in `fs.readFileSync`. It's obvious both `getData` and `fs.readFileSync` are sync functions. One day you were told to switch the underlying data source to a repo such as MongoDB which can only be accessed asynchronously. You were also told for backward compatibility, `getData` API cannot be changed to return merely a promise or demand a callback parameter. How do you meet both requirements?\n\nYou may tempted to use [node-fibers](https://github.com/laverdet/node-fibers) or a module derived from it, but node fibers can only wrap async function call into a sync function inside a fiber. In the case above you cannot assume all  callers are inside fibers. On the other hand, if you start a fiber in `getData` then `getData` itself will still return immediately without waiting for the async call result. For similar reason ES6 generators introduced in Node v0.11 won't work either. \n\nWhat really needed is a way to block subsequent JavaScript from running without blocking entire thread by yielding to allow other events in the event loop to be handled. Ideally the blockage is removed as soon as the result of async function is available. A less ideal but often acceptable alternative is a `sleep` function which you can use to implement the blockage like ```while(!done) sleep(100);```. It is less ideal because sleep duration has to be guessed. It is important the `sleep` function not only shouldn't block entire thread, but also shouldn't incur busy wait that pegs the CPU to 100%. \n\nDeAsync supports both alternatives.\n\n## Installation\n\n```shell\nnpm install @kaciras/deasync\n```\n\nDeAsync downloads prebuild binary from GitHub releases during installation, if the download fails, try to build locally. You can skip the installation phase by set environment variable `NO_PREBUILD=1`.\n\nDeAsync uses node-gyp to compile C++ source code, so to build Deasync you may need the compilers listed in [node-gyp](https://github.com/nodejs/node-gyp).\n\n## Usage\n\nDeasync exports two APIs: `deasync` for callback style function, and `awaitSync` for Promise.\n\n### `deasync(function)`\n\nGeneric wrapper of async function with conventional API signature `function(...args, (error, result) => {})`. Returns `result` and throws `error` as exception if not null.\n\nSleep (a wrapper of setTimeout):\n\n```javascript\nconst { deasync } = require(\"@kaciras/deasync\");\n\nconst sleep = deasync((timeout, done) => {\n\tsetTimeout(() => done(null, \"wake up!\"), timeout);\n});\n\nconsole.log(\"Timestamp before: \" + performance.now());\nconsole.log(sleep(1000));\nconsole.log(\"Timestamp after: \" + performance.now());\n```\n\n### `awaitSync(promise)`\n\nThe `awaitSync` causes execution to pause until a Promise is settled (that is, fulfilled or rejected), and to resume execution of after fulfillment. When resumed, the returned value of the `awaitSync` is that of the fulfilled Promise. If the Promise is rejected, the `awaitSync` throws the rejected value.\n\nThis function is similar with the keyword `await` but synchronously.\n\n```javascript\nconst { awaitSync } = require(\"@kaciras/deasync\");\nconst { performance } = require(\"perf_hooks\");\n\nconsole.log(\"Timestamp before: \" + performance.now());\nconst promise = new Promise(resolve => setTimeout(resolve, 1000)).then(() => \"wake up!\")\nconsole.log(awaitSync(promise));\nconsole.log(\"Timestamp after: \" + performance.now());\n```\n\n## Recommendation\n\nUnlike other (a)sync js packages that mostly have only syntactic impact, DeAsync also changes code execution sequence. As such, it is intended to solve niche cases like the above one. If all you are facing is syntactic problem such as callback hell, using a less drastic package implemented in pure js is recommended.\n\n## Support\nPull requests and issue reporting are welcome. For issues to be considered by maintainer\n1. they must be reproducible\n2. there must be evidence the issue is related to DeAsync\n\nTo that end, the issue should contain platform information, error message relevant to DeAsync, and preferably code snippet. If code snippet is supplied, it must be self-contained, i.e. independent from your runtime environment or other modules not explicitly specified via `require` in the code snippet.\n"
 }

README.md

 # DeAsync
 
 [![Npm Version](https://img.shields.io/npm/v/@kaciras/deasync)](https://www.npmjs.com/package/@kaciras/deasync)
+![node-current (scoped)](https://img.shields.io/node/v/@kaciras/deasync)
 [![Test](https://github.com/Kaciras/deasync/actions/workflows/test.yml/badge.svg)](https://github.com/Kaciras/deasync/actions/workflows/test.yml)
@@ -16,3 +17,3 @@ [![codecov](https://codecov.io/gh/Kaciras/deasync/branch/master/graph/badge.svg?token=ST7ROWQH0Z)](https://codecov.io/gh/Kaciras/deasync)
 `const myData = getData()`  
-Under the hood data is saved in a file so you implemented `getData` using Node.js built-in `fs.readFileSync`. It's obvious both `getData` and `fs.readFileSync` are sync functions. One day you were told to switch the underlying data source to a repo such as MongoDB which can only be accessed asynchronously. You were also told to avoid pissing off your users, `getData` API cannot be changed to return merely a promise or demand a callback parameter. How do you meet both requirements?
+Under the hood data is saved in a file so you implemented `getData` using Node.js built-in `fs.readFileSync`. It's obvious both `getData` and `fs.readFileSync` are sync functions. One day you were told to switch the underlying data source to a repo such as MongoDB which can only be accessed asynchronously. You were also told for backward compatibility, `getData` API cannot be changed to return merely a promise or demand a callback parameter. How do you meet both requirements?
 
@@ -75,2 +76,9 @@ You may tempted to use [node-fibers](https://github.com/laverdet/node-fibers) or a module derived from it, but node fibers can only wrap async function call into a sync function inside a fiber. In the case above you cannot assume all  callers are inside fibers. On the other hand, if you start a fiber in `getData` then `getData` itself will still return immediately without waiting for the async call result. For similar reason ES6 generators introduced in Node v0.11 won't work either.
 
-Unlike other (a)sync js packages that mostly have only syntactic impact, DeAsync also changes code execution sequence. As such, it is intended to solve niche cases like the above one. If all you are facing is syntatic problem such as callback hell, using a less drastic package implemented in pure js is recommended.
+Unlike other (a)sync js packages that mostly have only syntactic impact, DeAsync also changes code execution sequence. As such, it is intended to solve niche cases like the above one. If all you are facing is syntactic problem such as callback hell, using a less drastic package implemented in pure js is recommended.
+
+## Support
+Pull requests and issue reporting are welcome. For issues to be considered by maintainer
+1. they must be reproducible
+2. there must be evidence the issue is related to DeAsync
+
+To that end, the issue should contain platform information, error message relevant to DeAsync, and preferably code snippet. If code snippet is supplied, it must be self-contained, i.e. independent from your runtime environment or other modules not explicitly specified via `require` in the code snippet.

No alert changes

Improved metrics

Total package byte prevSize

20961

increased by40.72%

Dev dependency count

9

decreased by-10%

Number of lines in readme file

83

increased by10.67%

Dependency changes

• Updatedfollow-redirects@^1.14.8