simple-log-methods 0.5.0

package/dist/constants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * define the supported log levels
+ */
+export declare enum LogLevel {
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    DEBUG = "debug"
+}
+export declare const isOfLogLevel: import("type-fns").AssessWithAssure<string | number | symbol, LogLevel>;
+/**
+ * define specifically supported environments
+ */
+export declare enum SupportedEnvironment {
+    /**
+     * the local environment balances information -vs- oversharing
+     * - metadata is stringified to not cause too much visual "noise" in the console
+     * - log level should default to being conservatively balanced, to reduce noise in the console
+     *   - especially when considering the ease of retrying requests with more permissive log-level specified
+     */
+    LOCAL = "LOCAL",
+    /**
+     * the aws environment has a few extra considerations for logging
+     * - metadata should not be json-stringified, and should be simply nested instead for cloudwatch insights parsing
+     * - log level should default to be more permissive, as cloudwatch costs are low enough to be worth the increased visibility in most cases
+     */
+    AWS_LAMBDA = "AWS_LAMBDA",
+    /**
+     * the web browser environment allows us to focus on accessibility of information
+     * - the metadata should not be json-stringified. instead, it should be simply nested for devtools console accessibility
+     * - log level should default to being conservatively balanced, to reduce noise in the console
+     *   - especially when considering the ease of retrying requests with more permissive log-level specified
+     */
+    WEB_BROWSER = "WEB_BROWSER"
+}

package/dist/constants.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupportedEnvironment = exports.isOfLogLevel = exports.LogLevel = void 0;
+const type_fns_1 = require("type-fns");
+/**
+ * define the supported log levels
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["ERROR"] = "error";
+    LogLevel["WARN"] = "warn";
+    LogLevel["INFO"] = "info";
+    LogLevel["DEBUG"] = "debug";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+exports.isOfLogLevel = (0, type_fns_1.createIsOfEnum)(LogLevel);
+/**
+ * define specifically supported environments
+ */
+var SupportedEnvironment;
+(function (SupportedEnvironment) {
+    /**
+     * the local environment balances information -vs- oversharing
+     * - metadata is stringified to not cause too much visual "noise" in the console
+     * - log level should default to being conservatively balanced, to reduce noise in the console
+     *   - especially when considering the ease of retrying requests with more permissive log-level specified
+     */
+    SupportedEnvironment["LOCAL"] = "LOCAL";
+    /**
+     * the aws environment has a few extra considerations for logging
+     * - metadata should not be json-stringified, and should be simply nested instead for cloudwatch insights parsing
+     * - log level should default to be more permissive, as cloudwatch costs are low enough to be worth the increased visibility in most cases
+     */
+    SupportedEnvironment["AWS_LAMBDA"] = "AWS_LAMBDA";
+    /**
+     * the web browser environment allows us to focus on accessibility of information
+     * - the metadata should not be json-stringified. instead, it should be simply nested for devtools console accessibility
+     * - log level should default to being conservatively balanced, to reduce noise in the console
+     *   - especially when considering the ease of retrying requests with more permissive log-level specified
+     */
+    SupportedEnvironment["WEB_BROWSER"] = "WEB_BROWSER";
+})(SupportedEnvironment || (exports.SupportedEnvironment = SupportedEnvironment = {}));
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAA,uCAA0C;AAE1C;;GAEG;AACH,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;AACjB,CAAC,EALW,QAAQ,wBAAR,QAAQ,QAKnB;AACY,QAAA,YAAY,GAAG,IAAA,yBAAc,EAAC,QAAQ,CAAC,CAAC;AAErD;;GAEG;AACH,IAAY,oBAuBX;AAvBD,WAAY,oBAAoB;IAC9B;;;;;OAKG;IACH,uCAAe,CAAA;IAEf;;;;OAIG;IACH,iDAAyB,CAAA;IAEzB;;;;;OAKG;IACH,mDAA2B,CAAA;AAC7B,CAAC,EAvBW,oBAAoB,oCAApB,oBAAoB,QAuB/B"}

package/dist/formatLogContentsForEnvironment.d.ts

@@ -0,0 +1,17 @@
+import { LogLevel } from './constants';
+export declare const formatLogContentsForEnvironment: ({ level, timestamp, message, metadata, }: {
+    level: LogLevel;
+    timestamp: string;
+    message: string;
+    metadata?: Record<string, any>;
+}) => string | {
+    level: LogLevel;
+    timestamp: string;
+    message: string;
+    metadata: string;
+} | {
+    level: LogLevel;
+    timestamp: string;
+    message: string;
+    metadata: Record<string, any> | undefined;
+};

package/dist/formatLogContentsForEnvironment.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLogContentsForEnvironment = void 0;
+const constants_1 = require("./constants");
+const identifyEnvironment_1 = require("./identifyEnvironment");
+const formatLogContentsForEnvironment = ({ level, timestamp, message, metadata, }) => {
+    const env = (0, identifyEnvironment_1.identifyEnvironment)();
+    // if its a "local" environment, then dont stringify the contents - but stringify the metadata to cut down on visual noise
+    if (env === constants_1.SupportedEnvironment.LOCAL) {
+        return {
+            level,
+            timestamp,
+            message,
+            metadata: JSON.stringify(metadata), // json stringify it to cut down on the visual noise in the console
+        };
+    }
+    // if its an aws-lambda environment, then stringify the contents - without stringifying the metadata - to make sure log is fully readable and parseable by cloudwatch
+    if (env === constants_1.SupportedEnvironment.AWS_LAMBDA) {
+        return JSON.stringify({
+            level,
+            timestamp,
+            message,
+            metadata,
+        });
+    }
+    // if its a web-browser environment, then dont stringify the contents - nor the metadata - to make sure log is fully accessible through console devtools
+    if (env === constants_1.SupportedEnvironment.WEB_BROWSER) {
+        return {
+            level,
+            timestamp,
+            message,
+            metadata,
+        };
+    }
+    // if it was not one of the above, we have not supported this environment yet
+    throw new Error('unsupported environment detected. this should never occur - and is a bug within simple-log-methods'); // fail fast
+};
+exports.formatLogContentsForEnvironment = formatLogContentsForEnvironment;
+//# sourceMappingURL=formatLogContentsForEnvironment.js.map

package/dist/formatLogContentsForEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatLogContentsForEnvironment.js","sourceRoot":"","sources":["../src/formatLogContentsForEnvironment.ts"],"names":[],"mappings":";;;AAAA,2CAA6D;AAC7D,+DAA4D;AAErD,MAAM,+BAA+B,GAAG,CAAC,EAC9C,KAAK,EACL,SAAS,EACT,OAAO,EACP,QAAQ,GAMT,EAAE,EAAE;IACH,MAAM,GAAG,GAAG,IAAA,yCAAmB,GAAE,CAAC;IAElC,0HAA0H;IAC1H,IAAI,GAAG,KAAK,gCAAoB,CAAC,KAAK,EAAE,CAAC;QACvC,OAAO;YACL,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,mEAAmE;SACxG,CAAC;IACJ,CAAC;IAED,qKAAqK;IACrK,IAAI,GAAG,KAAK,gCAAoB,CAAC,UAAU,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IAED,wJAAwJ;IACxJ,IAAI,GAAG,KAAK,gCAAoB,CAAC,WAAW,EAAE,CAAC;QAC7C,OAAO;YACL,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,MAAM,IAAI,KAAK,CACb,oGAAoG,CACrG,CAAC,CAAC,YAAY;AACjB,CAAC,CAAC;AA/CW,QAAA,+BAA+B,mCA+C1C"}

package/dist/formatLogContentsForEnvironment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/formatLogContentsForEnvironment.test.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const _1 = require(".");
+const constants_1 = require("./constants");
+const formatLogContentsForEnvironment_1 = require("./formatLogContentsForEnvironment");
+const identifyEnvironment_1 = require("./identifyEnvironment");
+jest.mock('./identifyEnvironment');
+const identifyEnvironmentMock = identifyEnvironment_1.identifyEnvironment;
+describe('formatMetadataForEnvironment', () => {
+    it('should not stringify the contents - but should stringify the metadata - if in the local environment', () => {
+        identifyEnvironmentMock.mockReturnValue(constants_1.SupportedEnvironment.LOCAL);
+        const metadata = { name: 'bob', likes: ['oranges', 'apples'] };
+        const logContents = {
+            level: _1.LogLevel.INFO,
+            timestamp: new Date().toISOString(),
+            message: 'hello world!',
+            metadata,
+        };
+        const formatted = (0, formatLogContentsForEnvironment_1.formatLogContentsForEnvironment)(logContents);
+        expect(formatted).toEqual({
+            ...logContents,
+            metadata: JSON.stringify(metadata),
+        });
+    });
+    it('should stringify the contents in the aws lambda environment', () => {
+        identifyEnvironmentMock.mockReturnValue(constants_1.SupportedEnvironment.AWS_LAMBDA);
+        const metadata = { name: 'bob', likes: ['oranges', 'apples'] };
+        const logContents = {
+            level: _1.LogLevel.INFO,
+            timestamp: new Date().toISOString(),
+            message: 'hello world!',
+            metadata,
+        };
+        const formatted = (0, formatLogContentsForEnvironment_1.formatLogContentsForEnvironment)(logContents);
+        expect(formatted).toEqual(JSON.stringify(logContents));
+    });
+    it('should not stringify the contents nor the metadata if in web browser environment', () => {
+        identifyEnvironmentMock.mockReturnValue(constants_1.SupportedEnvironment.WEB_BROWSER);
+        const metadata = { name: 'bob', likes: ['oranges', 'apples'] };
+        const logContents = {
+            level: _1.LogLevel.INFO,
+            timestamp: new Date().toISOString(),
+            message: 'hello world!',
+            metadata,
+        };
+        const formatted = (0, formatLogContentsForEnvironment_1.formatLogContentsForEnvironment)(logContents);
+        expect(formatted).toEqual(logContents);
+    });
+});
+//# sourceMappingURL=formatLogContentsForEnvironment.test.js.map

package/dist/formatLogContentsForEnvironment.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatLogContentsForEnvironment.test.js","sourceRoot":"","sources":["../src/formatLogContentsForEnvironment.test.ts"],"names":[],"mappings":";;AAAA,wBAA6B;AAC7B,2CAAmD;AACnD,uFAAoF;AACpF,+DAA4D;AAE5D,IAAI,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;AACnC,MAAM,uBAAuB,GAAG,yCAAgC,CAAC;AAEjE,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,qGAAqG,EAAE,GAAG,EAAE;QAC7G,uBAAuB,CAAC,eAAe,CAAC,gCAAoB,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC/D,MAAM,WAAW,GAAG;YAClB,KAAK,EAAE,WAAQ,CAAC,IAAI;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,OAAO,EAAE,cAAc;YACvB,QAAQ;SACT,CAAC;QACF,MAAM,SAAS,GAAG,IAAA,iEAA+B,EAAC,WAAW,CAAC,CAAC;QAC/D,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;YACxB,GAAG,WAAW;YACd,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;SACnC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,uBAAuB,CAAC,eAAe,CAAC,gCAAoB,CAAC,UAAU,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC/D,MAAM,WAAW,GAAG;YAClB,KAAK,EAAE,WAAQ,CAAC,IAAI;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,OAAO,EAAE,cAAc;YACvB,QAAQ;SACT,CAAC;QACF,MAAM,SAAS,GAAG,IAAA,iEAA+B,EAAC,WAAW,CAAC,CAAC;QAC/D,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,kFAAkF,EAAE,GAAG,EAAE;QAC1F,uBAAuB,CAAC,eAAe,CAAC,gCAAoB,CAAC,WAAW,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC/D,MAAM,WAAW,GAAG;YAClB,KAAK,EAAE,WAAQ,CAAC,IAAI;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,OAAO,EAAE,cAAc;YACvB,QAAQ;SACT,CAAC;QACF,MAAM,SAAS,GAAG,IAAA,iEAA+B,EAAC,WAAW,CAAC,CAAC;QAC/D,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/generateLogMethod.d.ts

@@ -0,0 +1,6 @@
+import { LogLevel } from './constants';
+export type LogMethod = (message: string, metadata: any) => void;
+export declare const generateLogMethod: ({ level, minimalLogLevel, }: {
+    level: LogLevel;
+    minimalLogLevel: LogLevel;
+}) => (message: string, metadata?: object) => void;

package/dist/generateLogMethod.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLogMethod = void 0;
+const constants_1 = require("./constants");
+const formatLogContentsForEnvironment_1 = require("./formatLogContentsForEnvironment");
+/*
+  define priority order of log levels and make it easy to ask questions about
+*/
+const logLevelPriorityOrder = [
+    constants_1.LogLevel.ERROR,
+    constants_1.LogLevel.WARN,
+    constants_1.LogLevel.INFO,
+    constants_1.LogLevel.DEBUG,
+];
+const aIsEqualOrMoreImportantThanB = ({ a, b }) => logLevelPriorityOrder.indexOf(a) - logLevelPriorityOrder.indexOf(b) <= 0;
+const generateLogMethod = ({ level, minimalLogLevel, }) => {
+    return (message, metadata) => {
+        if (aIsEqualOrMoreImportantThanB({ a: level, b: minimalLogLevel })) {
+            // determine the console level (i.e., use warn if we can to make the logs stand out more)
+            const consoleMethod = aIsEqualOrMoreImportantThanB({
+                a: level,
+                b: constants_1.LogLevel.WARN,
+            })
+                ? console.warn
+                : console.log; // tslint:disable-line no-console
+            // output the message to console, which will get picked up by cloudwatch when deployed lambda is invoked
+            consoleMethod((0, formatLogContentsForEnvironment_1.formatLogContentsForEnvironment)({
+                level,
+                timestamp: new Date().toISOString(),
+                message,
+                metadata,
+            }));
+        }
+    };
+};
+exports.generateLogMethod = generateLogMethod;
+//# sourceMappingURL=generateLogMethod.js.map

package/dist/generateLogMethod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLogMethod.js","sourceRoot":"","sources":["../src/generateLogMethod.ts"],"names":[],"mappings":";;;AAAA,2CAAuC;AACvC,uFAAoF;AAEpF;;EAEE;AACF,MAAM,qBAAqB,GAAG;IAC5B,oBAAQ,CAAC,KAAK;IACd,oBAAQ,CAAC,IAAI;IACb,oBAAQ,CAAC,IAAI;IACb,oBAAQ,CAAC,KAAK;CACf,CAAC;AACF,MAAM,4BAA4B,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAgC,EAAE,EAAE,CAC9E,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAUpE,MAAM,iBAAiB,GAAG,CAAC,EAChC,KAAK,EACL,eAAe,GAIhB,EAAE,EAAE;IACH,OAAO,CAAC,OAAe,EAAE,QAAiB,EAAE,EAAE;QAC5C,IAAI,4BAA4B,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;YACnE,yFAAyF;YACzF,MAAM,aAAa,GAAG,4BAA4B,CAAC;gBACjD,CAAC,EAAE,KAAK;gBACR,CAAC,EAAE,oBAAQ,CAAC,IAAI;aACjB,CAAC;gBACA,CAAC,CAAC,OAAO,CAAC,IAAI;gBACd,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,iCAAiC;YAElD,wGAAwG;YACxG,aAAa,CACX,IAAA,iEAA+B,EAAC;gBAC9B,KAAK;gBACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,OAAO;gBACP,QAAQ;aACT,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC,CAAC;AA5BW,QAAA,iBAAiB,qBA4B5B"}

package/dist/generateLogMethod.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/generateLogMethod.test.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const constants_1 = require("./constants");
+const generateLogMethod_1 = require("./generateLogMethod");
+describe('generateLogMethod', () => {
+    beforeEach(() => jest.clearAllMocks());
+    it('should generate a method that outputs to console.log if below warn level', () => {
+        const spy = jest.spyOn(console, 'log');
+        const logError = (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.INFO,
+            minimalLogLevel: constants_1.LogLevel.DEBUG,
+        });
+        logError('testMessage');
+        expect(spy).toHaveBeenCalledTimes(1);
+    });
+    it('should generate a method that outputs to console.warn if at or above warn level', () => {
+        const spy = jest.spyOn(console, 'warn');
+        const logError = (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.ERROR,
+            minimalLogLevel: constants_1.LogLevel.DEBUG,
+        });
+        logError('testMessage');
+        expect(spy).toHaveBeenCalledTimes(1);
+    });
+    it('should generate a method that outputs timestamp, level, message, and metadata', () => {
+        const spy = jest.spyOn(console, 'warn');
+        const logError = (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.ERROR,
+            minimalLogLevel: constants_1.LogLevel.DEBUG,
+        });
+        logError('testMessage', { nested: { object: true } });
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(spy).toHaveBeenCalledWith(expect.objectContaining({
+            level: constants_1.LogLevel.ERROR,
+            message: 'testMessage',
+            metadata: JSON.stringify({ nested: { object: true } }),
+        }));
+        expect(spy.mock.calls[0][0]).toHaveProperty('timestamp');
+    });
+    it('should not output anything if level is below minimum', () => {
+        const spy = jest.spyOn(console, 'log');
+        const logDebug = (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.DEBUG,
+            minimalLogLevel: constants_1.LogLevel.WARN,
+        });
+        logDebug('testMessage');
+        expect(spy).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=generateLogMethod.test.js.map

package/dist/generateLogMethod.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLogMethod.test.js","sourceRoot":"","sources":["../src/generateLogMethod.test.ts"],"names":[],"mappings":";;AAAA,2CAAuC;AACvC,2DAAwD;AAExD,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;IACvC,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAClF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAA,qCAAiB,EAAC;YACjC,KAAK,EAAE,oBAAQ,CAAC,IAAI;YACpB,eAAe,EAAE,oBAAQ,CAAC,KAAK;SAChC,CAAC,CAAC;QACH,QAAQ,CAAC,aAAa,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,iFAAiF,EAAE,GAAG,EAAE;QACzF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAA,qCAAiB,EAAC;YACjC,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe,EAAE,oBAAQ,CAAC,KAAK;SAChC,CAAC,CAAC;QACH,QAAQ,CAAC,aAAa,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,+EAA+E,EAAE,GAAG,EAAE;QACvF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAA,qCAAiB,EAAC;YACjC,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe,EAAE,oBAAQ,CAAC,KAAK;SAChC,CAAC,CAAC;QACH,QAAQ,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAC9B,MAAM,CAAC,gBAAgB,CAAC;YACtB,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,aAAa;YACtB,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;SACvD,CAAC,CACH,CAAC;QACF,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAA,qCAAiB,EAAC;YACjC,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe,EAAE,oBAAQ,CAAC,IAAI;SAC/B,CAAC,CAAC;QACH,QAAQ,CAAC,aAAa,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACrC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/generateLogMethods.d.ts

@@ -0,0 +1,36 @@
+import { LogLevel } from './constants';
+import { LogMethod } from './generateLogMethod';
+export interface LogMethods {
+    /**
+     * `error` level logs are used to indicate a critical and urgent failure that requires immediate resolution
+     * - these logs are often associated with someone on-call being notified immediately, regardless of the time or day
+     * - when choosing to log something with a log level of "error", you are saying that someone should be woken up in the middle of the night if this occurs
+     */
+    error: LogMethod;
+    /**
+     * `warn` level logs are used to indicate that something is going wrong, but can wait to be resolved until a convenient time
+     * - these logs are often associated with someone following up on them during business hours
+     * - when choosing to log something with a log level of "warn", you are saying that someone should look at this as soon as reasonably possible
+     */
+    warn: LogMethod;
+    /**
+     * `info` level logs are used to indicate an interesting event that should be kept track of
+     * - these logs are often associated with health metrics, dashboard statistics, or custom log queries for investigations or reporting
+     * - when choosing to log something with a log level of "info", you are saying that someone will be interested in this information indefinitely
+     */
+    info: LogMethod;
+    /**
+     * `debug` level logs are used to output information that can aid users in tracking down bugs or confirming that things are working as expected
+     * - these logs are often associated with common actions that happen within code, that may only be relevant when debugging your applications
+     * - when choosing to log something with a log level of "debug", you are saying that someone will only be interested in this information when debugging
+     */
+    debug: LogMethod;
+}
+/**
+ * define how to generate the log methods
+ * - allows you to specify the minimal log level to use for your application
+ * - defaults to recommended levels for the environment
+ */
+export declare const generateLogMethods: ({ minimalLogLevel, }?: {
+    minimalLogLevel?: LogLevel;
+}) => LogMethods;

package/dist/generateLogMethods.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLogMethods = void 0;
+const constants_1 = require("./constants");
+const generateLogMethod_1 = require("./generateLogMethod");
+const getRecommendedMinimalLogLevelForEnvironment_1 = require("./getRecommendedMinimalLogLevelForEnvironment");
+/**
+ * define how to generate the log methods
+ * - allows you to specify the minimal log level to use for your application
+ * - defaults to recommended levels for the environment
+ */
+const generateLogMethods = ({ minimalLogLevel = (0, getRecommendedMinimalLogLevelForEnvironment_1.getRecommendedMinimalLogLevelForEnvironment)(), } = {}) => {
+    // generate the methods
+    return {
+        error: (0, generateLogMethod_1.generateLogMethod)({ level: constants_1.LogLevel.ERROR, minimalLogLevel }),
+        warn: (0, generateLogMethod_1.generateLogMethod)({ level: constants_1.LogLevel.WARN, minimalLogLevel }),
+        info: (0, generateLogMethod_1.generateLogMethod)({ level: constants_1.LogLevel.INFO, minimalLogLevel }),
+        debug: (0, generateLogMethod_1.generateLogMethod)({ level: constants_1.LogLevel.DEBUG, minimalLogLevel }),
+    };
+};
+exports.generateLogMethods = generateLogMethods;
+//# sourceMappingURL=generateLogMethods.js.map

package/dist/generateLogMethods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLogMethods.js","sourceRoot":"","sources":["../src/generateLogMethods.ts"],"names":[],"mappings":";;;AAAA,2CAAuC;AACvC,2DAAmE;AACnE,+GAA4G;AAgC5G;;;;GAIG;AACI,MAAM,kBAAkB,GAAG,CAAC,EACjC,eAAe,GAAG,IAAA,yFAA2C,GAAE,MAC7B,EAAE,EAAc,EAAE;IACpD,uBAAuB;IACvB,OAAO;QACL,KAAK,EAAE,IAAA,qCAAiB,EAAC,EAAE,KAAK,EAAE,oBAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC;QACpE,IAAI,EAAE,IAAA,qCAAiB,EAAC,EAAE,KAAK,EAAE,oBAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,CAAC;QAClE,IAAI,EAAE,IAAA,qCAAiB,EAAC,EAAE,KAAK,EAAE,oBAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,CAAC;QAClE,KAAK,EAAE,IAAA,qCAAiB,EAAC,EAAE,KAAK,EAAE,oBAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC,CAAC;AAVW,QAAA,kBAAkB,sBAU7B"}

package/dist/generateLogMethods.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/generateLogMethods.test.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const generateLogMethods_1 = require("./generateLogMethods");
+describe('generateLogMethods', () => {
+    it('should create the log methods', () => {
+        const log = (0, generateLogMethods_1.generateLogMethods)();
+        expect(log).toHaveProperty('error');
+        expect(log).toHaveProperty('warn');
+        expect(log).toHaveProperty('info');
+        expect(log).toHaveProperty('debug');
+    });
+});
+//# sourceMappingURL=generateLogMethods.test.js.map

package/dist/generateLogMethods.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLogMethods.test.js","sourceRoot":"","sources":["../src/generateLogMethods.test.ts"],"names":[],"mappings":";;AAAA,6DAA0D;AAE1D,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,GAAG,GAAG,IAAA,uCAAkB,GAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/getRecommendedMinimalLogLevelForEnvironment.d.ts

@@ -0,0 +1,2 @@
+import { LogLevel } from './constants';
+export declare const getRecommendedMinimalLogLevelForEnvironment: () => LogLevel;

package/dist/getRecommendedMinimalLogLevelForEnvironment.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRecommendedMinimalLogLevelForEnvironment = void 0;
+const constants_1 = require("./constants");
+const identifyEnvironment_1 = require("./identifyEnvironment");
+const getLogLevelFromEnvVar = () => {
+    // if LOG_LEVEL was specified, use that
+    const logLevelEnvVar = process.env.LOG_LEVEL || null; // cast falsy values to null
+    if (logLevelEnvVar) {
+        // if the log level is valid, use it
+        if ((0, constants_1.isOfLogLevel)(logLevelEnvVar))
+            return logLevelEnvVar;
+        // otherwise, warn and continue to attempt other options
+        console.warn(`environmental variable LOG_LEVEL was set to an invalid value: '${logLevelEnvVar}'. using the default instead`);
+    }
+    // if LOG_DEBUG was specified as true, use that (it's a common intuitive alias)
+    const logDebugEnvVar = process.env.LOG_DEBUG || null;
+    if (logDebugEnvVar === 'true')
+        return constants_1.LogLevel.DEBUG;
+    // todo: consider supporting other LOG_${level} options
+    // otherwise, null
+    return null;
+};
+const getRecommendedMinimalLogLevelForEnvironment = () => {
+    // if the LOG_LEVEL env var is defined, then use what is specified by that
+    const logLevelFromEnvVar = getLogLevelFromEnvVar();
+    if (logLevelFromEnvVar)
+        return logLevelFromEnvVar;
+    // identify the env we're in
+    const env = (0, identifyEnvironment_1.identifyEnvironment)();
+    // if we're in aws lambda env, then default to DEBUG - since cloudwatch costs are cheap and extra visibility is worth it in most cases
+    if (env === constants_1.SupportedEnvironment.AWS_LAMBDA)
+        return constants_1.LogLevel.DEBUG;
+    // otherwise, default to INFO - to balance signal -vs- noise
+    return constants_1.LogLevel.INFO;
+};
+exports.getRecommendedMinimalLogLevelForEnvironment = getRecommendedMinimalLogLevelForEnvironment;
+//# sourceMappingURL=getRecommendedMinimalLogLevelForEnvironment.js.map

package/dist/getRecommendedMinimalLogLevelForEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRecommendedMinimalLogLevelForEnvironment.js","sourceRoot":"","sources":["../src/getRecommendedMinimalLogLevelForEnvironment.ts"],"names":[],"mappings":";;;AAAA,2CAA2E;AAC3E,+DAA4D;AAE5D,MAAM,qBAAqB,GAAG,GAAoB,EAAE;IAClD,uCAAuC;IACvC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,4BAA4B;IAClF,IAAI,cAAc,EAAE,CAAC;QACnB,oCAAoC;QACpC,IAAI,IAAA,wBAAY,EAAC,cAAc,CAAC;YAAE,OAAO,cAAc,CAAC;QAExD,wDAAwD;QACxD,OAAO,CAAC,IAAI,CACV,kEAAkE,cAAc,8BAA8B,CAC/G,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;IACrD,IAAI,cAAc,KAAK,MAAM;QAAE,OAAO,oBAAQ,CAAC,KAAK,CAAC;IAErD,uDAAuD;IAEvD,kBAAkB;IAClB,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEK,MAAM,2CAA2C,GAAG,GAAa,EAAE;IACxE,0EAA0E;IAC1E,MAAM,kBAAkB,GAAG,qBAAqB,EAAE,CAAC;IACnD,IAAI,kBAAkB;QAAE,OAAO,kBAAkB,CAAC;IAElD,4BAA4B;IAC5B,MAAM,GAAG,GAAG,IAAA,yCAAmB,GAAE,CAAC;IAElC,sIAAsI;IACtI,IAAI,GAAG,KAAK,gCAAoB,CAAC,UAAU;QAAE,OAAO,oBAAQ,CAAC,KAAK,CAAC;IAEnE,4DAA4D;IAC5D,OAAO,oBAAQ,CAAC,IAAI,CAAC;AACvB,CAAC,CAAC;AAbW,QAAA,2CAA2C,+CAatD"}

package/dist/identifyEnvironment.d.ts

@@ -0,0 +1,6 @@
+import { SupportedEnvironment } from './constants';
+/**
+ * identifies the supported environment that this is being run in, as best as possible
+ * - defaults to LOCAL environment, as it has the most common settings and is not distinguishable otherwise
+ */
+export declare const identifyEnvironment: () => SupportedEnvironment;

package/dist/identifyEnvironment.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identifyEnvironment = void 0;
+const constants_1 = require("./constants");
+/**
+ * identifies the supported environment that this is being run in, as best as possible
+ * - defaults to LOCAL environment, as it has the most common settings and is not distinguishable otherwise
+ */
+const identifyEnvironment = () => {
+    // check if its an aws-lambda runtime environment
+    const isAwsLambdaEnvironment = !!process.env.AWS_LAMBDA_FUNCTION_NAME; // if this env var is defined, then its aws lambda env
+    if (isAwsLambdaEnvironment)
+        return constants_1.SupportedEnvironment.AWS_LAMBDA;
+    // check if its a browser environment
+    const isWebBrowserEnvironment = typeof window !== 'undefined' && typeof window.document !== 'undefined'; // if both are defined, then its a browser
+    if (isWebBrowserEnvironment)
+        return constants_1.SupportedEnvironment.WEB_BROWSER;
+    // default to local env
+    return constants_1.SupportedEnvironment.LOCAL;
+};
+exports.identifyEnvironment = identifyEnvironment;
+//# sourceMappingURL=identifyEnvironment.js.map

package/dist/identifyEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifyEnvironment.js","sourceRoot":"","sources":["../src/identifyEnvironment.ts"],"names":[],"mappings":";;;AAAA,2CAAmD;AAEnD;;;GAGG;AACI,MAAM,mBAAmB,GAAG,GAAyB,EAAE;IAC5D,iDAAiD;IACjD,MAAM,sBAAsB,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,sDAAsD;IAC7H,IAAI,sBAAsB;QAAE,OAAO,gCAAoB,CAAC,UAAU,CAAC;IAEnE,qCAAqC;IACrC,MAAM,uBAAuB,GAC3B,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC,CAAC,0CAA0C;IACrH,IAAI,uBAAuB;QAAE,OAAO,gCAAoB,CAAC,WAAW,CAAC;IAErE,uBAAuB;IACvB,OAAO,gCAAoB,CAAC,KAAK,CAAC;AACpC,CAAC,CAAC;AAZW,QAAA,mBAAmB,uBAY9B"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LogLevel } from './constants';
+export { LogMethod } from './generateLogMethod';
+export { generateLogMethods, LogMethods } from './generateLogMethods';

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLogMethods = exports.LogLevel = void 0;
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return constants_1.LogLevel; } });
+var generateLogMethods_1 = require("./generateLogMethods");
+Object.defineProperty(exports, "generateLogMethods", { enumerable: true, get: function () { return generateLogMethods_1.generateLogMethods; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA;AAEjB,2DAAsE;AAA7D,wHAAA,kBAAkB,OAAA"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "simple-log-methods",
+  "author": "ehmpathy",
+  "description": "a simple and opinionated logging library. plays well with aws lambda + cloudwatch.",
+  "version": "0.5.0",
+  "repository": "ehmpathy/simple-log-methods",
+  "homepage": "https://github.com/ehmpathy/simple-log-methods",
+  "keywords": [
+    "log",
+    "logs",
+    "level",
+    "simple",
+    "filter",
+    "aws",
+    "lambda",
+    "cloudwatch",
+    "requestId"
+  ],
+  "bugs": "https://github.com/ehmpathy/simple-log-methods/issues",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build:ts": "tsc -p ./tsconfig.build.json",
+    "commit:with-cli": "npx cz",
+    "fix:format:prettier": "prettier --write '**/*.ts' --config ./prettier.config.js",
+    "fix:format": "npm run fix:format:prettier",
+    "fix:lint": "eslint -c ./.eslintrc.js src/**/*.ts --fix",
+    "build:clean": "rm dist/ -rf",
+    "build:compile": "tsc -p ./tsconfig.build.json",
+    "build": "npm run build:clean && npm run build:compile",
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
+    "test:types": "tsc -p ./tsconfig.build.json --noEmit",
+    "test:format:prettier": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js",
+    "test:format": "npm run test:format:prettier",
+    "test:lint:deps": "npx depcheck -c ./depcheckrc.yml",
+    "test:lint:eslint": "eslint -c ./.eslintrc.js src/**/*.ts",
+    "test:lint": "npm run test:lint:eslint && npm run test:lint:deps",
+    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
+    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "test": "npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "prepush": "npm run test && npm run build",
+    "prepublish": "npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "postinstall": "[ -d .git ] && npm run prepare:husky || exit 0",
+    "prepare:husky": "npx husky install && chmod ug+x .husky/*"
+  },
+  "dependencies": {
+    "type-fns": "^1.16.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "19.3.0",
+    "@commitlint/config-conventional": "13.1.0",
+    "@trivago/prettier-plugin-sort-imports": "4.3.0",
+    "@tsconfig/node-lts-strictest": "18.12.1",
+    "@types/jest": "29.2.4",
+    "@typescript-eslint/eslint-plugin": "7.8.0",
+    "@typescript-eslint/parser": "7.8.0",
+    "core-js": "3.26.1",
+    "cz-conventional-changelog": "3.3.0",
+    "declapract": "^0.12.0",
+    "declapract-typescript-ehmpathy": "^0.39.5",
+    "depcheck": "1.4.3",
+    "eslint": "8.56.0",
+    "eslint-config-airbnb-typescript": "18.0.0",
+    "eslint-config-prettier": "8.5.0",
+    "eslint-plugin-import": "2.26.0",
+    "eslint-plugin-prettier": "4.2.1",
+    "husky": "8.0.3",
+    "jest": "29.3.1",
+    "prettier": "2.8.1",
+    "test-fns": "1.4.2",
+    "ts-jest": "29.1.3",
+    "ts-node": "10.9.2",
+    "typescript": "5.4.5"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,45 @@
+# simple-log-methods
+
+a simple and opinionated logging library. plays well with aws lambda + cloudwatch.
+
+# features
+
+- distinguish different priorities of logs with standard levels
+  - i.e., `log.debug`, `log.info`, `log.warn`, and `log.error`
+- filter which levels of log to emit
+  - i.e., choose based on environment whether to emit all logs or skip some of the logs
+- utilizes `console.warn` and `console.log` under the hood
+  - which ensures that the aws cloudwatch requestId is present on each log message automatically
+- formats log metadata based on environment
+  - i.e., stringify in local environments to reduce visual noise
+  - i.e., don't stringify in aws-lambda environment for optimal cloudwatch parsing
+
+
+# installation
+
+```
+npm install --save simple-log-methods
+```
+
+# usage
+
+### init
+```ts
+// e.g., in `src/utils/log.ts
+import { generateLogMethods } from 'simple-log-methods';
+
+export const log = generateLogMethods();
+```
+
+### use in code
+```ts
+import { log } from '../utils/log';
+
+log.error(`the sky is falling and we're loosing money!`, metadata); // use `.error` when you want someone to respond immediately, even if its 4am
+
+log.warn(`this shouldn't be happening and should be looked at asap`, metadata); // use `.warn` when you want someone to look at it asap, but not wake up in the middle of the night
+
+log.info(`we either want to or should keep track of this`, metadata); // use `.info` for anything we may be interested in knowing about
+
+log.debug(`this will help debug if things go wrong`, metadata); // use this for any information that could help debug when things go wrong (e.g., request/response data)
+```