c8js - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

lib/c8js.d.ts

@@ -49,16 +49,51 @@ import type { Report }                              from 'c8';
 
-type ReportOptions = ConstructorParameters<typeof Report>[0];
+type InheritableC8Options =
+Undefinedable<Omit<ConstructorParameters<typeof Report>[0], 'reporter' | 'src' | 'watermarks'>>;
 
-type Undefinedable<Type> = { [Key in keyof Type]: Type[Key] | undefined };
+type Undefinedable<Type> = { [Key in keyof Type]: Type[Key] | undefined; };
 
-type Watermark = [number, number];
+/** Thresholds for low and high code coverage watermarks. */
+type Watermark = [low: number, high: number];
 
+/**
+ * Thresholds for low and high code coverage watermarks for branches, functions, lines and
+ * statements.
+ */
 interface Watermarks
 {
+    /** Thresholds for branches. */
     branches?:      Watermark | undefined;
+
+    /** Thresholds for functions. */
     functions?:     Watermark | undefined;
+
+    /** Thresholds for lines. */
     lines?:         Watermark | undefined;
+
+    /** Thresholds for statements. */
     statements?:    Watermark | undefined;
 }
 
+/**
+ * Executes a command, generates a coverage report and optionally checks that code coverage is
+ * within the specified thresholds.
+ *
+ * @param command
+ * The command to run.
+ * This can be a binary executable or a Node.js module.
+ * If a promise is specified, the resolved value will be used.
+ *
+ * @param args
+ * A list of arguments passed to the command.
+ *
+ * @param options
+ * Options for the function.
+ *
+ * @returns
+ * A promise that settles after the command has terminated.
+ * The promise will resolve with an object similar to the return value of
+ * [`child_process.spawnSync`](
+ * https://nodejs.org/api/child_process.html#child_processspawnsynccommand-args-options) with an
+ * additional property holding the coverage map.
+ */
 declare const c8js:
@@ -90,2 +125,12 @@ {
 
+/**
+ * Checks that code coverage is within the specified thresholds.
+ *
+ * @param options
+ * Options for the function.
+ *
+ * @returns
+ * A promise that resolves if code coverage is within the thresholds, and rejects otherwise, or if
+ * an error occurs.
+ */
 declare function checkCoverage
@@ -97,6 +142,14 @@ (options?: checkCoverage.Options & Partial<c8js.Options>):
 {
-    interface Options
-    extends CommonOptions, Undefinedable<Omit<ReportOptions, 'reporter' | 'src' | 'watermarks'>>
+    interface Options extends CommonOptions, InheritableC8Options
     {
         /**
+         * If `true`, all files specified with the options `src`, `include`, `exclude` and
+         * `extension` will be loaded into the report.
+         * If any of those files remain uncovered, they will be factored into the report with a
+         * default of 0% coverage.
+         * @default false
+         */
+        all?:                   boolean | undefined;
+
+        /**
          * Fails if coverage falls below 100%.
@@ -115,2 +168,8 @@ * @default false
         /**
+         * Glob patterns matching files that should be excluded from coverage.
+         * @default await import('@istanbuljs/schema/default-exclude.js')
+         */
+        exclude?:               string | string[] | undefined;
+
+        /**
          * Whether or not to exclude all `'node_module'` folders.
@@ -122,2 +181,8 @@ * @default true
         /**
+         * Only files matching these extensions will be included in coverage.
+         * @default ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx']
+         */
+        extension?:             string | string[] | undefined;
+
+        /**
          * Percentage of functions that must be covered for the check to pass.
@@ -130,2 +195,9 @@ * This setting is ignored if option `100` is used.
         /**
+         * Glob patterns matching files that should be included in coverage.
+         * An empty array matches all files.
+         * @default []
+         */
+        include?:               string | string[] | undefined;
+
+        /**
          * Percentage of lines that must be covered for the check to pass.
@@ -159,7 +231,13 @@ * This setting is ignored if option `100` is used.
 
+/** Common commands for c8js. */
 declare const commands:
 {
-    get node(): Promise<string>;
-    get npm():  Promise<string>;
-    get npx():  Promise<string>;
+    /** A new promise that resolves to the path of node. */
+    readonly node:  Promise<string>;
+
+    /** A new promise that resolves to the path of npm. */
+    readonly npm:   Promise<string>;
+
+    /** A new promise that resolves to the path of npx. */
+    readonly npx:   Promise<string>;
 };
@@ -172,4 +250,24 @@
 ):
-Promise<SpawnSyncReturns<string | Buffer>>;
+Promise<exec.Result>;
 
+/**
+ * Executes a command, ensuring that temporary code coverage data is created.
+ *
+ * @param command
+ * The command to run.
+ * This can be a binary executable or a Node.js module.
+ * If a promise is specified, the resolved value will be used.
+ *
+ * @param args
+ * A list of arguments passed to the command.
+ *
+ * @param options
+ * Options for the function.
+ *
+ * @returns
+ * A promise that settles after the command has terminated.
+ * The promise will resolve with an object similar to the return value of
+ * [`child_process.spawnSync`](
+ * https://nodejs.org/api/child_process.html#child_processspawnsynccommand-args-options).
+ */
 declare function exec
@@ -181,3 +279,3 @@ (
 ):
-Promise<SpawnSyncReturns<string | Buffer>>;
+Promise<exec.Result>;
 
@@ -253,4 +351,18 @@ declare namespace exec
     }
+
+    interface Result extends SpawnSyncReturns<string | Buffer>
+    { }
 }
 
+/**
+ * Generates a coverage report and optionally checks that code coverage is
+ * within the specified thresholds.
+ *
+ * @param options
+ * Options for the function.
+ *
+ * @returns
+ * A promise that resolves with a coverage map, and rejects if code coverage is not within the
+ * thresholds, or if an error occurs.
+ */
 declare function report(options?: report.Options & Partial<c8js.Options>): Promise<CoverageMap>;
@@ -282,5 +394,3 @@
 
-        /**
-         * Thresholds for high and low code coverage watermarks, exposed by some reporters.
-         */
+        /** Thresholds for low and high code coverage watermarks, exposed by some reporters. */
         watermarks?:    Watermarks | undefined;
@@ -290,5 +400,6 @@ }
 
+/** The version string of c8js. */
 declare const version: string;
 
 export { c8js as default, checkCoverage, commands, exec, report, version };
-export type { CoverageMap, Watermark, Watermarks };
+export type { Watermark, Watermarks };

package.json

 {
   "name": "c8js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A modern, asynchronous Node.js API for c8",
@@ -12,3 +12,3 @@ "keywords": [
   ],
-  "homepage": "https://github.com/fasttime/c8js#readme",
+  "homepage": "https://github.com/origin-1/c8js#readme",
   "license": "ISC",
@@ -21,9 +21,10 @@ "author": "Francesco Trotta <[e-mail]> (https://github.com/fasttime)",
     "type": "git",
-    "url": "https://github.com/fasttime/c8js.git"
+    "url": "https://github.com/origin-1/c8js.git"
   },
   "scripts": {
-    "build": "npm install && npm run clean && npm run lint && npm run coverage",
+    "build": "npm install && node dev/clean && node dev/lint && node dev/coverage && node dev/make-docs",
     "clean": "node dev/clean",
     "coverage": "node dev/coverage",
     "lint": "node dev/lint",
+    "make-docs": "node dev/make-docs",
     "test": "mocha --check-leaks --timeout=10000 ./test/*.spec.js"
@@ -42,2 +43,4 @@ },
     "ts-node": "latest",
+    "typedoc": "latest",
+    "typedoc-plugin-markdown": "latest",
     "typescript": "latest"
@@ -44,0 +47,0 @@ },

README.md

@@ -1,5 +0,7 @@
-# c8js · [![npm version][npm badge]][npm url]
+# c8js
 
 A modern, asynchronous Node.js API for [c8](https://github.com/bcoe/c8).
 
+[![npm version][npm badge]][npm url]
+
 c8 leverages Node.js built-in [V8 JavaScript code coverage](https://v8.dev/blog/javascript-code-coverage) to produce [Istanbul](https://istanbul.js.org/)-compatible reports.
@@ -17,4 +19,8 @@
 
-## Example Usages
+## Usage
 
+See the [**API documentation**](https://origin-1.github.io/c8js/modules).
+
+## Examples
+
 ### Run Mocha
@@ -80,3 +86,7 @@
 
+## Compatibility
+
+c8js requires Node.js 14 or later.
+
 [npm badge]: https://badge.fury.io/js/c8js.svg
 [npm url]: https://www.npmjs.com/package/c8js

No alert changes

Improved metrics

Total package byte prevSize

38576

11.22%

Lines of code

1039

10.77%

Number of lines in readme file

91

12.35%

Worsened metrics

Dev dependency count

6

50%

No dependency changes