@cardano-sdk/util-dev 0.4.1-nightly.3 → 0.4.1-nightly.6

package/README.md

@@ -7,3 +7,78 @@ Utilities for tests in other packages
 See [code coverage report].
 
 [code coverage report]: https://input-output-hk.github.io/cardano-js-sdk/coverage/util-dev
+
+## TestLogger
+
+A _unit tests_ dedicated _logger_.
+
+```typescript
+import { createLogger, logger } from '@cardano-sdk/util-dev';
+import { deepStrictEqual } from 'assert';
+
+logger.debug('Some debug data');
+logger.error('Some error data');
+// etc...
+
+const newLogger = createLogger({ record: true });
+
+newLogger.info('another message');
+newLogger.debug({ test: 42 }, 'some message');
+newLogger.error('error message', new Error('example error'));
+
+deepStrictEqual(newLogger.messages, [
+  { level: 'info', message: ['another message'] },
+  { level: 'debug', message: [{ test: 42 }, 'some message'] },
+  { level: 'error', message: ['error message', new Error('example error')] }
+]);
+```
+
+This logger is expressly designed to be used in unit tests: it keeps the unit tests output as clean as possible (logging only messages with `fatal` level), but, when required, it offers a quick and easy way to increase the verbosity of the tests without the need to change any file.
+
+It also offer the option to record **all the logged values** to perform checks on what is logged by the tested program.
+
+### Tests development flow
+
+While developing / maintaining / reviewing unit tests we often run the unit test command from our shell:
+
+```
+yarn test
+```
+
+As long as all the tests pass, we don't even need `TestLogger`.
+
+But sometimes it may happen that some tests fail... sometimes...
+
+In order to investigate the reason of the failure of a test, may be useful to access the logs.
+
+If the test was written using `TestLogger`, the latter allows us to access and / or customize the logs through simple environment variables.
+
+To increase the log level, just use the `TL_LEVEL` environment variable:
+
+```
+TL_LEVEL=info yarn test
+```
+
+By default, `TestLogger` uses [util.inspect](https://nodejs.org/api/util.html#utilinspectobject-options) and its `options` object can be customized with following environment variables:
+
+- `TL_ARRAY` maps to `maxArrayLength`. Defaults to `100`. `0` maps to `Infinity`.
+- `TL_BREAK` maps to `breakLength`. Defaults to tty width on a tty or `90` otherwise. `0` maps to `Infinity`.
+- `TL_COLOR` maps to `colors`. Defaults to `true` on a tty `false` otherwise.
+- `TL_COMPACT` maps to `compact`. Defaults to `3`. `0` maps to `false`.
+- `TL_DEPTH` maps to `depth`. Defaults to `2`. `0` maps to `Infinity`.
+- `TL_HIDDEN` maps to `showHidden`. Defaults to `false`.
+- `TL_PROXY` maps to `showProxy`. Defaults to `false`.
+- `TL_STRING` maps to `maxStringLength`. Defaults to `1000` (not `10000` as `util.inspect` does). `0` maps to `Infinity`.
+
+so if (for example) we need to log full nested objects and `Proxy`s we could run our test command with:
+
+```
+TL_PROXY=true TL_DEPTH=0 TL_LEVEL=info yarn test
+```
+
+Even if `util.inspect` can be deeply customized (letting us to customize our log as well), it has the drawback that its output can't be cut and pasted on a source file or to perform a POST etc.
+If we need to cut paste something from our log we can instruct `TestLogger` to use `JSONBig.stringify` instead; this will obviously make `TestLogger` to ignore environment variables which customize `util.inspect`.
+
+```
+TL_LEVEL=info TL_JSON=true yarn test
+```

package/dist/cjs/TestLogger.d.ts

@@ -0,0 +1,35 @@
+/// <reference types="node" />
+declare const logLevels: {
+    debug: number;
+    error: number;
+    fatal: number;
+    info: number;
+    trace: number;
+    warn: number;
+};
+declare type LogLevel = keyof typeof logLevels;
+export declare type LogFunction = (...args: unknown[]) => void;
+export declare type LoggedMessage = {
+    level: LogLevel;
+    message: unknown[];
+};
+export declare type Logger = {
+    [l in LogLevel]: LogFunction;
+};
+export declare type TestLogger = Logger & {
+    messages: LoggedMessage[];
+};
+declare type TestStream = {
+    columns?: number;
+    isTTY?: boolean;
+    write: Function;
+};
+export interface TestLoggerOptions {
+    env?: NodeJS.ProcessEnv;
+    record?: boolean;
+    stream?: TestStream;
+}
+export declare const createLogger: (options?: TestLoggerOptions) => TestLogger;
+export declare const logger: TestLogger;
+export {};
+//# sourceMappingURL=TestLogger.d.ts.map

package/dist/cjs/TestLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestLogger.d.ts","sourceRoot":"","sources":["../../src/TestLogger.ts"],"names":[],"mappings":";AAMA,QAAA,MAAM,SAAS;;;;;;;CAA+D,CAAC;AAG/E,aAAK,QAAQ,GAAG,MAAM,OAAO,SAAS,CAAC;AAMvC,oBAAY,WAAW,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAKvD,oBAAY,aAAa,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AAKpE,oBAAY,MAAM,GAAG;KAAG,CAAC,IAAI,QAAQ,GAAG,WAAW;CAAE,CAAC;AAMtD,oBAAY,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAEhE,aAAK,UAAU,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAKzE,MAAM,WAAW,iBAAiB;IAIhC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAKxB,MAAM,CAAC,EAAE,OAAO,CAAC;IAKjB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAsCD,eAAO,MAAM,YAAY,aAAa,iBAAiB,eA0CtD,CAAC;AAKF,eAAO,MAAM,MAAM,YAAiB,CAAC"}

package/dist/cjs/TestLogger.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.createLogger = void 0;
+const envalid = __importStar(require("envalid"));
+const util_1 = require("util");
+const json_bigint_1 = __importDefault(require("json-bigint"));
+const logLevels = { debug: 2, error: 5, fatal: 6, info: 3, trace: 1, warn: 4 };
+const logLevelLabels = ['', 'TRACE  ', 'DEBUG  ', 'INFO   ', 'WARNING', 'ERROR  ', 'FATAL  '];
+const getConfig = (env, stream) => {
+    const { TL_ARRAY, TL_BREAK, TL_COLOR, TL_COMPACT, TL_DEPTH, TL_HIDDEN, TL_JSON, TL_LEVEL, TL_PROXY, TL_STRING } = envalid.cleanEnv(env, {
+        TL_ARRAY: envalid.num({ default: 100 }),
+        TL_BREAK: envalid.num({ default: stream?.columns ? stream?.columns - 33 : 90 }),
+        TL_COLOR: envalid.bool({ default: stream?.isTTY || false }),
+        TL_COMPACT: envalid.num({ default: 3 }),
+        TL_DEPTH: envalid.num({ default: 2 }),
+        TL_HIDDEN: envalid.bool({ default: false }),
+        TL_JSON: envalid.bool({ default: false }),
+        TL_LEVEL: envalid.str({ choices: Object.keys(logLevels), default: 'fatal' }),
+        TL_PROXY: envalid.bool({ default: false }),
+        TL_STRING: envalid.num({ default: 1000 })
+    });
+    const inspectOptions = {
+        breakLength: TL_BREAK || Number.POSITIVE_INFINITY,
+        colors: TL_COLOR,
+        compact: TL_COMPACT || false,
+        depth: TL_DEPTH || Number.POSITIVE_INFINITY,
+        maxArrayLength: TL_ARRAY || Number.POSITIVE_INFINITY,
+        maxStringLength: TL_STRING || Number.POSITIVE_INFINITY,
+        showHidden: TL_HIDDEN,
+        showProxy: TL_PROXY,
+        sorted: true
+    };
+    return { inspectOptions, minHeight: logLevels[TL_LEVEL], useJSON: TL_JSON };
+};
+const createLogger = (options = {}) => {
+    const { env, record, stream } = { env: process.env, stream: process.stdout, ...options };
+    const { minHeight, inspectOptions, useJSON } = getConfig(env, stream);
+    const messages = [];
+    const stringify = (data) => {
+        switch (typeof data) {
+            case 'bigint':
+            case 'boolean':
+            case 'number':
+            case 'symbol':
+                return data.toString();
+            case 'string':
+                return data;
+            case 'undefined':
+                return 'undefined';
+            case 'object':
+                if (useJSON)
+                    return json_bigint_1.default.stringify(data);
+            case 'function':
+                return (0, util_1.inspect)(data, inspectOptions);
+        }
+    };
+    const getLogFunction = ([level, height]) => {
+        const label = logLevelLabels[height];
+        return (...message) => {
+            if (record)
+                messages.push({ level, message });
+            if (height < minHeight)
+                return;
+            const line = message.map(stringify).join(' ');
+            const now = new Date().toISOString().replace('T', ' ').replace('Z', '');
+            const lines = line.split('\n').map((_) => `${now} ${label} ${_}\n`);
+            stream.write(lines.join(''));
+        };
+    };
+    const logger = Object.fromEntries(Object.entries(logLevels).map((_) => [_[0], getLogFunction(_)]));
+    return { messages, ...logger };
+};
+exports.createLogger = createLogger;
+exports.logger = (0, exports.createLogger)();
+//# sourceMappingURL=TestLogger.js.map

package/dist/cjs/TestLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestLogger.js","sourceRoot":"","sources":["../../src/TestLogger.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,iDAAmC;AACnC,+BAA+C;AAC/C,8DAAkC;AAElC,MAAM,SAAS,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/E,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAgD9F,MAAM,SAAS,GAAG,CAAC,GAAsB,EAAE,MAAmB,EAAE,EAAE;IAChE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,GAC7G,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE;QACpB,QAAQ,EAAI,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QACzC,QAAQ,EAAI,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACjF,QAAQ,EAAI,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,KAAK,EAAE,CAAC;QAC7D,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACvC,QAAQ,EAAI,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACvC,SAAS,EAAG,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5C,OAAO,EAAK,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5C,QAAQ,EAAI,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAe,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAC5F,QAAQ,EAAI,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5C,SAAS,EAAG,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KAC3C,CAAC,CAAC;IAEL,MAAM,cAAc,GAAmB;QACrC,WAAW,EAAM,QAAQ,IAAI,MAAM,CAAC,iBAAiB;QACrD,MAAM,EAAW,QAAQ;QACzB,OAAO,EAAU,UAAU,IAAI,KAAK;QACpC,KAAK,EAAY,QAAQ,IAAI,MAAM,CAAC,iBAAiB;QACrD,cAAc,EAAG,QAAQ,IAAI,MAAM,CAAC,iBAAiB;QACrD,eAAe,EAAE,SAAS,IAAI,MAAM,CAAC,iBAAiB;QACtD,UAAU,EAAO,SAAS;QAC1B,SAAS,EAAQ,QAAQ;QACzB,MAAM,EAAW,IAAI;KACtB,CAAC;IAEF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9E,CAAC,CAAC;AAQK,MAAM,YAAY,GAAG,CAAC,UAA6B,EAAE,EAAE,EAAE;IAC9D,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAoB,EAAE,GAAG,OAAO,EAAE,CAAC;IACvG,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,CAAC,IAAa,EAAE,EAAE;QAClC,QAAQ,OAAO,IAAI,EAAE;YACnB,KAAK,QAAQ,CAAC;YACd,KAAK,SAAS,CAAC;YACf,KAAK,QAAQ,CAAC;YACd,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzB,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC;YACd,KAAK,WAAW;gBACd,OAAO,WAAW,CAAC;YACrB,KAAK,QAAQ;gBACX,IAAI,OAAO;oBAAE,OAAO,qBAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAE9C,KAAK,UAAU;gBACb,OAAO,IAAA,cAAO,EAAC,IAAI,EAAE,cAAc,CAAC,CAAC;SACxC;IACH,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAc,EAAE,EAAE;QACtD,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QAErC,OAAO,CAAC,GAAG,OAAkB,EAAE,EAAE;YAC/B,IAAI,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YAE9C,IAAI,MAAM,GAAG,SAAS;gBAAE,OAAO;YAE/B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;YAEpE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAiB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpH,OAAmB,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC;AAC7C,CAAC,CAAC;AA1CW,QAAA,YAAY,gBA0CvB;AAKW,QAAA,MAAM,GAAG,IAAA,oBAAY,GAAE,CAAC"}

package/dist/cjs/index.d.ts

@@ -1,6 +1,7 @@
 export * as AssetId from './assetId';
 export * as CslTestUtil from './cslTestUtil';
 export * as TxTestUtil from './txTestUtil';
+export * from './TestLogger';
 export * from './util';
 export * from './createStubStakePoolProvider';
 export * from './stubLogger';

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,WAAW,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,cAAc,QAAQ,CAAC;AACvB,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,WAAW,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/cjs/index.js

@@ -30,6 +30,7 @@ exports.TxTestUtil = exports.CslTestUtil = exports.AssetId = void 0;
 exports.AssetId = __importStar(require("./assetId"));
 exports.CslTestUtil = __importStar(require("./cslTestUtil"));
 exports.TxTestUtil = __importStar(require("./txTestUtil"));
+__exportStar(require("./TestLogger"), exports);
 __exportStar(require("./util"), exports);
 __exportStar(require("./createStubStakePoolProvider"), exports);
 __exportStar(require("./stubLogger"), exports);

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,qDAAqC;AACrC,6DAA6C;AAC7C,2DAA2C;AAC3C,yCAAuB;AACvB,gEAA8C;AAC9C,+CAA6B;AAC7B,kDAAgC;AAChC,2DAAyC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,qDAAqC;AACrC,6DAA6C;AAC7C,2DAA2C;AAC3C,+CAA6B;AAC7B,yCAAuB;AACvB,gEAA8C;AAC9C,+CAA6B;AAC7B,kDAAgC;AAChC,2DAAyC"}