@compas/stdlib - npm Package Compare versions

Comparing version 0.0.115 to 0.0.116

package.json

 {
   "name": "@compas/stdlib",
-  "version": "0.0.115",
+  "version": "0.0.116",
   "description": "All kinds of utility functions",
@@ -16,4 +16,4 @@ "main": "./index.js",
   "dependencies": {
-    "@compas/insight": "0.0.115",
-    "@types/node": "14.14.25",
+    "@compas/insight": "0.0.116",
+    "@types/node": "14.14.27",
     "dotenv": "8.2.0",
@@ -43,3 +43,3 @@ "lodash.merge": "4.6.2"
   },
-  "gitHead": "2bb525228f13305555f6dfd8de6d6e07013f149c"
+  "gitHead": "240f978002efe57c446650a5de9213961e2c06cb"
 }

src/datatypes.js

@@ -5,2 +5,11 @@ import crypto from "crypto";
 /**
+ * Vendor uuid v4 generator from uuidjs/uuid.
+ * If we are on Node.js 15 or above, we use the built-in import("crypto").randomUUID.
+ * This variant is a bit faster and allows us to drop the vendor code.
+ * This function also has an `uuid.isValid` function, which returns a boolean depending
+ * on if the passed in string is a valid uuid.
+ *
+ * @since 0.1.0
+ * @summary Returns a new uuid v4
+ *
  * @function
@@ -7,0 +16,0 @@ * @returns {string}

src/env.js

@@ -7,14 +7,24 @@ /**
 /**
- * Repopulate the cached environment copy.
- * This should only be necessary when you or a sub package mutates the environment.
+ * This should only be necessary when you or a package mutates the environment variables.
  * The `mainFn` / `mainTestFn` / `mainBenchFn` / ... will call this function by default
  * after loading your `.env` file.
  *
- * Accessing process.env.XXX is relatively in Node.js.
- * Benchmark of a plain object property access and accessing process.env.NODE_ENV:
+ * Accessing an environment variable via `process.env.XXXX` is relatively slow compared
+ * to direct property access. The following benchmark result of a plain object property
+ * access and accessing process.env.NODE_ENV:
  *
+ * ```txt
  * property access       500000000  iterations     0  ns/op
+ * ```
+ *
+ * ```txt
  * process.env access      5000000  iterations   246  ns/op
+ * ```
  *
- * See this thread: https://github.com/nodejs/node/issues/3104
+ * See this thread: https://github.com/nodejs/node/issues/3104 for more information.
+ *
+ * @since 0.1.0
+ * @summary Repopulate the cached environment copy.
+ *
+ * @returns {undefined}
  */
@@ -26,2 +36,7 @@ export function refreshEnvironmentCache() {
 /**
+ * Returns true when the `NODE_ENV` variable is not set, or when it does not equal to
+ * `development`. This allows for a 'safe by default' experience.
+ *
+ * @since 0.1.0
+ *
  * @returns {boolean}
@@ -34,2 +49,7 @@ */
 /**
+ * Returns true when `NODE_ENV` is explicitly set to 'development' or when the
+ * environment variable `IS_STAGING` is explicitly set to 'true'.
+ *
+ * @since 0.1.0
+ *
  * @returns {boolean}
@@ -36,0 +56,0 @@ */

src/error.js

 import { inspect } from "util";
 
+/**
+ * Standard error to use. This contains a key, status code and info object.
+ * Mostly provided to make it easier to return errors from your API's.
+ *
+ * @since 0.1.0
+ * @class
+ */
 export class AppError extends Error {
@@ -4,0 +11,0 @@ /**

src/lodash.js

 import lodashMerge from "lodash.merge";
 
 /**
- * @param {*=} item
+ * Check if a value is `null` or `undefined`
+ *
+ * @since 0.1.0
+ *
+ * @param {*} [item]
  * @returns {boolean}
@@ -12,3 +16,7 @@ */
 /**
- * @param {*=} item
+ * Check if a value is a plain JavaScript object.
+ *
+ * @since 0.1.0
+ *
+ * @param {*} [item]
  * @returns {boolean}
@@ -26,3 +34,8 @@ */
 /**
- * @param {object} object The destination object.
+ * Deep merge source objects on to 'target'. Mutates 'target' in place.
+ *
+ * @function
+ * @since 0.1.0
+ *
+ * @param {object} target The destination object.
  * @param {...object} [sources] The source objects.
@@ -34,5 +47,10 @@ * @returns {object} Returns `object`.
 /**
+ * Flatten nested objects in to a new object where the keys represent the original access
+ * path. Only goes through plain JavaScript objects and ignores arrays.
+ *
+ * @since 0.1.0
+ *
  * @param {object} data The object to serialize
- * @param [result]
- * @param [path]
+ * @param {*} [result]
+ * @param {string} [path]
  * @returns {object.<string, *>}
@@ -59,2 +77,6 @@ */
 /**
+ * The opposite of 'flatten'.
+ *
+ * @since 0.1.0
+ *
  * @param {object} data
@@ -83,3 +105,7 @@ * @returns {object}
 /**
- * @param input
+ *
+ * @since 0.1.0
+ *
+ * @param {string} input
+ * @returns {string}
  */
@@ -86,0 +112,0 @@ export function camelToSnakeCase(input) {

src/node.js

 import { exec as cpExec, spawn as cpSpawn } from "child_process";
 import { lstatSync, readdirSync } from "fs";
 import { lstat, readdir } from "fs/promises";
-import { join } from "path";
-import { pipeline } from "stream";
+import { posix } from "path";
 import { promisify } from "util";
 
 const internalExec = promisify(cpExec);
-const internalPipeline = promisify(pipeline);
 
-export { join as pathJoin };
+/**
+ * Join all arguments together and normalize the resulting path. Arguments must be
+ * strings. Using Node.js built-in path.posix.join().
+ * Which forces use of Posix path separators, '/'.
+ *
+ * @param {...string} paths
+ * @returns {string}
+ */
+export function pathJoin(...paths) {
+  return posix.join(...paths);
+}
 
 /**
- * @callback Exec
+ * Wrap around Node.js child_process#exec. Resolving when the sub process has exited. The
+ * resulting object contains the 'exitCode' of the sub process.
+ *
+ * @since 0.1.0
+ *
  * @param {string} command
@@ -39,2 +51,8 @@ * @param {ExecOptions} [opts={}]
 /**
+ * Wrap around Node.js child_process#spawn. Resolving when the sub process has exited. The
+ * resulting object contains the 'exitCode' of the sub process.
+ * By default 'stdio' is inherited from the current process.
+ *
+ * @since 0.1.0
+ *
  * @param {string} command
@@ -58,18 +76,33 @@ * @param {string[]} args
  * Read a readable stream completely, and return as Buffer
- * @param {ReadableStream} stream
+ *
+ * @since 0.1.0
+ *
+ * @param {NodeJS.ReadableStream} stream
  * @returns {Promise<Buffer>}
  */
 export async function streamToBuffer(stream) {
-  const buffers = [];
-  await internalPipeline(stream, async function* (transform) {
-    for await (const chunk of transform) {
+  if (!stream || typeof stream._read !== "function") {
+    return Buffer.from([]);
+  }
+
+  return new Promise((resolve, reject) => {
+    const buffers = [];
+
+    stream.on("data", function (chunk) {
       buffers.push(chunk);
-      yield chunk;
-    }
+    });
+    stream.on("end", function () {
+      resolve(Buffer.concat(buffers));
+    });
+    stream.on("error", function (err) {
+      reject(err);
+    });
   });
-
-  return Buffer.concat(buffers);
 }
 
 /**
+ * Recursively act on all files in a directory, awaiting on callback calls.
+ *
+ * @since 0.1.0
+ *
  * @param {string} dir
@@ -95,3 +128,3 @@ * @param {Function} cb
 
-    const newPath = join(dir, file);
+    const newPath = pathJoin(dir, file);
     const stat = await lstat(newPath);
@@ -109,2 +142,4 @@ if (stat.isDirectory()) {
  *
+ * @since 0.1.0
+ *
  * @param {string} dir
@@ -132,3 +167,3 @@ * @param {Function} cb
 
-    const newPath = join(dir, file);
+    const newPath = pathJoin(dir, file);
     const stat = lstatSync(newPath);
@@ -135,0 +170,0 @@ if (stat.isDirectory()) {

src/utils.js

@@ -13,2 +13,6 @@ import { lstatSync, realpathSync } from "fs";
 /**
+ * Get the number of seconds since Unix epoch (1-1-1970).
+ *
+ * @since 0.1.0
+ *
  * @returns {number}
@@ -21,2 +25,6 @@ */
 /**
+ * A function that returns 'undefined'.
+ *
+ * @since 0.1.0
+ *
  * @returns {undefined}
@@ -29,5 +37,5 @@ */
 /**
- * Internal gc function reference
+ * Internal gc function reference.
  * Note that this is undefined if the gc function is not called and Node is not running
- * with --expose-gc on
+ * with --expose-gc on.
  */
@@ -38,2 +46,6 @@ let internalGc = global.gc;
  * HACKY
+ *
+ * @since 0.1.0
+ *
+ * @returns {undefined}
  */
@@ -50,4 +62,12 @@ export function gc() {
 /**
+ * Checks if the provided import.meta source is used as the project entrypoint.
+ * If so, reads the .env file, prepares the environmentCache, adds some handlers for
+ * uncaught exceptions,  and calls the provided callback
+ *
+ * @since 0.1.0
+ * @summary Process entrypoint executor
+ *
  * @param {ImportMeta} meta
  * @param {MainFnCallback} cb
+ * @returns {undefined}
  */
@@ -106,2 +126,6 @@ export function mainFn(meta, cb) {
 /**
+ * ES module compatibility counterpart of the CommonJS __filename
+ *
+ * @since 0.1.0
+ *
  * @param {ImportMeta} meta
@@ -115,2 +139,6 @@ * @returns {string}
 /**
+ * ES module compatibility counterpart of the CommonJS __dirname
+ *
+ * @since 0.1.0
+ *
  * @param {ImportMeta} meta
@@ -117,0 +145,0 @@ * @returns {string}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

34616

increased by10.44%

Lines of code

1091

increased by12.82%

Dependency changes

• + Added@compas/insight@0.0.116(transitive)

• + Added@types/node@14.14.27(transitive)

• - Removed@compas/insight@0.0.115(transitive)

• - Removed@types/node@14.14.25(transitive)

• Updated@compas/insight@0.0.116

• Updated@types/node@14.14.27