sdk-logs 0.6.12

package/dist/domain.objects/LogTrail.d.ts

@@ -0,0 +1,20 @@
+import type { Procedure, ProcedureContext } from 'domain-glossary-procedure';
+import type { LogMethods } from '../domain.operations/generateLogMethods';
+/**
+ * .what = the procedure invocation trail
+ */
+export type LogTrail = string[];
+export interface ContextLogTrail {
+    /**
+     * .what = the log context which can be used; methods, trail, etc
+     */
+    log: LogMethods & {
+        _orig?: LogMethods;
+    } & {
+        /**
+         * .what = the log trail which has been collected
+         */
+        trail?: LogTrail;
+    };
+}
+export type HasContextLogTrail<T extends Procedure> = ProcedureContext<T> extends ContextLogTrail ? T : never;

package/dist/domain.objects/LogTrail.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=LogTrail.js.map

package/dist/domain.objects/LogTrail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LogTrail.js","sourceRoot":"","sources":["../../src/domain.objects/LogTrail.ts"],"names":[],"mappings":""}

package/dist/domain.objects/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/domain.objects/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/domain.objects/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/domain.objects/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/domain.operations/formatLogContentsForEnvironment.d.ts

@@ -0,0 +1,17 @@
+import { type LogLevel } from '../domain.objects/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/domain.operations/formatLogContentsForEnvironment.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLogContentsForEnvironment = void 0;
+const constants_1 = require("../domain.objects/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 sdk-logs'); // fail fast
+};
+exports.formatLogContentsForEnvironment = formatLogContentsForEnvironment;
+//# sourceMappingURL=formatLogContentsForEnvironment.js.map

package/dist/domain.operations/formatLogContentsForEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatLogContentsForEnvironment.js","sourceRoot":"","sources":["../../src/domain.operations/formatLogContentsForEnvironment.ts"],"names":[],"mappings":";;;AAAA,6DAGuC;AAEvC,+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,0FAA0F,CAC3F,CAAC,CAAC,YAAY;AACjB,CAAC,CAAC;AA/CW,QAAA,+BAA+B,mCA+C1C"}

package/dist/domain.operations/generateLogMethod.d.ts

@@ -0,0 +1,6 @@
+import { LogLevel } from '../domain.objects/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/domain.operations/generateLogMethod.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLogMethod = void 0;
+const constants_1 = require("../domain.objects/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/domain.operations/generateLogMethod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLogMethod.js","sourceRoot":"","sources":["../../src/domain.operations/generateLogMethod.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAEzD,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/domain.operations/generateLogMethods.d.ts

@@ -0,0 +1,36 @@
+import { LogLevel } from '../domain.objects/constants';
+import { type 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/domain.operations/generateLogMethods.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLogMethods = void 0;
+const constants_1 = require("../domain.objects/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/domain.operations/generateLogMethods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateLogMethods.js","sourceRoot":"","sources":["../../src/domain.operations/generateLogMethods.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAEzD,2DAAwE;AACxE,+GAA4G;AAgC5G;;;;GAIG;AACI,MAAM,kBAAkB,GAAG,CAAC,EACjC,eAAe,GAAG,IAAA,yFAA2C,GAAE,MAG7D,EAAE,EAAc,EAAE;IACpB,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;AAZW,QAAA,kBAAkB,sBAY7B"}

package/dist/domain.operations/getRecommendedMinimalLogLevelForEnvironment.d.ts

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

package/dist/domain.operations/getRecommendedMinimalLogLevelForEnvironment.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRecommendedMinimalLogLevelForEnvironment = void 0;
+const constants_1 = require("../domain.objects/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/domain.operations/getRecommendedMinimalLogLevelForEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRecommendedMinimalLogLevelForEnvironment.js","sourceRoot":"","sources":["../../src/domain.operations/getRecommendedMinimalLogLevelForEnvironment.ts"],"names":[],"mappings":";;;AAAA,6DAIuC;AAEvC,+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/domain.operations/identifyEnvironment.d.ts

@@ -0,0 +1,6 @@
+import { SupportedEnvironment } from '../domain.objects/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/domain.operations/identifyEnvironment.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identifyEnvironment = void 0;
+const constants_1 = require("../domain.objects/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/domain.operations/identifyEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifyEnvironment.js","sourceRoot":"","sources":["../../src/domain.operations/identifyEnvironment.ts"],"names":[],"mappings":";;;AAAA,6DAAqE;AAErE;;;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/domain.operations/withLogTrail.d.ts

@@ -0,0 +1,52 @@
+import { type IsoDuration } from 'iso-time';
+import type { LogLevel } from '../domain.objects/constants';
+import type { ContextLogTrail } from '../domain.objects/LogTrail';
+/**
+ * enables input output logging and tracing for a method
+ *
+ * todo: - add tracing identifier w/ async-context
+ * todo: - hookup visual tracing w/ external lib (vi...lo...)
+ * todo: - bundle this with its own logging library which supports scoped logs
+ */
+export declare const withLogTrail: <TInput, TContext extends ContextLogTrail, TOutput>(logic: (input: TInput, context: TContext) => TOutput, { name: declaredName, log: logOptions, duration, }: {
+    /**
+     * specifies the name of the function, if the function does not have a name assigned already
+     */
+    name?: string | undefined;
+    /**
+     * enable redacting parts of the input or output from logging
+     */
+    log?: {
+        /**
+         * specifies the level to log the trail with
+         *
+         * note:
+         * - defaults input & output logs to level .debug // todo: debug to .trail
+         * - defaults error logs to level .warn
+         * - error level is only overridable via the object form (to prevent accidental downgrade of error logs)
+         */
+        level?: LogLevel | {
+            input?: LogLevel | undefined;
+            output?: LogLevel | undefined;
+            error?: LogLevel | undefined;
+        } | undefined;
+        /**
+         * what of the input to log
+         */
+        input?: ((input: TInput, context: TContext) => any) | undefined;
+        /**
+         * what of the output to log
+         */
+        output?: ((value: Awaited<TOutput>) => any) | undefined;
+        /**
+         * what of the error to log
+         */
+        error?: ((error: Error) => any) | undefined;
+    } | undefined;
+    /**
+     * specifies the threshold after which a duration will be included on the output log
+     */
+    duration?: {
+        threshold: IsoDuration;
+    } | undefined;
+}) => (input: TInput, context: TContext) => TOutput;

package/dist/domain.operations/withLogTrail.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLogTrail = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const iso_time_1 = require("iso-time");
+const type_fns_1 = require("type-fns");
+const noOp = (...input) => input;
+const omitContext = (...input) => input[0]; // standard pattern for args = [input, context]
+const pickErrorMessage = (input) => ({
+    error: { message: input.message },
+});
+const roundToHundredths = (num) => Math.round(num * 100) / 100; // https://stackoverflow.com/a/14968691/3068233
+const DEFAULT_DURATION_REPORT_THRESHOLD = process.env
+    .VISUALOGIC_DURATION_THRESHOLD
+    ? parseInt(process.env.VISUALOGIC_DURATION_THRESHOLD)
+    : (0, iso_time_1.toMilliseconds)({ seconds: 1 });
+/**
+ * enables input output logging and tracing for a method
+ *
+ * todo: - add tracing identifier w/ async-context
+ * todo: - hookup visual tracing w/ external lib (vi...lo...)
+ * todo: - bundle this with its own logging library which supports scoped logs
+ */
+const withLogTrail = (logic, { name: declaredName, log: logOptions, duration = {
+    threshold: { milliseconds: DEFAULT_DURATION_REPORT_THRESHOLD },
+}, }) => {
+    // cache the name of the function per wrapping
+    const name = logic.name || declaredName || null; // use `\\` since `logic.name` returns `""` for anonymous functions
+    // if no name is identifiable, throw an error here to fail fast
+    if (!name)
+        throw new helpful_errors_1.UnexpectedCodePathError('could not identify name for wrapped function');
+    // if the name specified does not match the name of the function, throw an error here to fail fast
+    if (declaredName && name !== declaredName)
+        throw new helpful_errors_1.UnexpectedCodePathError('the natural name of the function is different than the declared name', { declaredName, naturalName: name });
+    // extract the log levels per operation
+    const logLevelInput = (typeof logOptions?.level === 'object'
+        ? logOptions.level.input
+        : logOptions?.level) ?? 'debug';
+    const logLevelOutput = (typeof logOptions?.level === 'object'
+        ? logOptions.level.output
+        : logOptions?.level) ?? 'debug';
+    const logLevelError = 
+    // note: error level is only overridable via the object form, to prevent `level: 'info'` from accidentally downgrading error logs
+    (typeof logOptions?.level === 'object' ? logOptions.level.error : null) ??
+        'warn';
+    // extract the log methods
+    const logInputMethod = logOptions?.input ?? omitContext;
+    const logOutputMethod = logOptions?.output ?? noOp;
+    const logErrorMethod = logOptions?.error ?? pickErrorMessage;
+    // define the duration threshold
+    const durationReportingThreshold = duration.threshold;
+    const durationReportingThresholdInSeconds = (0, iso_time_1.toMilliseconds)(durationReportingThreshold) / 1000;
+    // wrap the function
+    return (input, context) => {
+        // now log the input
+        context.log[logLevelInput](`${name}.input`, {
+            input: logInputMethod(input, context),
+        });
+        // begin tracking duration
+        const startTimeInMilliseconds = new Date().getTime();
+        // define the context.log method that will be given to the logic
+        const logMethodsWithContext = {
+            // add the trail
+            trail: [...(context.log.trail ?? []), name],
+            // track the orig logger
+            _orig: context.log?._orig ?? context.log,
+            // add the scoped methods
+            debug: (message, metadata) => context.log.debug(`${name}.progress: ${message}`, metadata),
+            info: (message, metadata) => context.log.info(`${name}.progress: ${message}`, metadata),
+            warn: (message, metadata) => context.log.warn(`${name}.progress: ${message}`, metadata),
+            error: (message, metadata) => context.log.error(`${name}.progress: ${message}`, metadata),
+        };
+        // define what to do when we have an error
+        const logError = (error) => {
+            const endTimeInMilliseconds = new Date().getTime();
+            const durationInMilliseconds = endTimeInMilliseconds - startTimeInMilliseconds;
+            const durationInSeconds = roundToHundredths(durationInMilliseconds / 1e3); // https://stackoverflow.com/a/53970656/3068233
+            context.log[logLevelError](`${name}.error`, {
+                input: logInputMethod(input, context),
+                output: logErrorMethod(error),
+                ...(durationInSeconds >= durationReportingThresholdInSeconds
+                    ? { duration: `${durationInSeconds} sec` } // only include the duration if the threshold was crossed
+                    : {}),
+            });
+        };
+        // now execute the method, wrapped to catch sync errors
+        let result;
+        try {
+            result = logic(input, {
+                ...context,
+                log: logMethodsWithContext,
+            });
+        }
+        catch (error) {
+            // log the error for sync functions that throw
+            if (error instanceof Error)
+                logError(error);
+            throw error;
+        }
+        // if the result was a promise, log when that method crosses the reporting threshold, to identify which procedures are slow
+        if ((0, type_fns_1.isAPromise)(result)) {
+            // define how to log the breach, on breach
+            const onDurationBreach = () => context.log[logLevelOutput](`${name}.duration.breach`, {
+                input: logInputMethod(input, context),
+                already: { duration: `${durationReportingThresholdInSeconds} sec` },
+            });
+            // define a timeout which will trigger on duration threshold
+            const onBreachTrigger = setTimeout(onDurationBreach, durationReportingThresholdInSeconds * 1000);
+            // remove the timeout when the operation completes, to prevent logging if completes before duration
+            void result
+                .finally(() => clearTimeout(onBreachTrigger))
+                .catch(() => {
+                // do nothing when there's an error; just catch it, to ensure it doesn't get propagated further as an uncaught exception
+            });
+        }
+        // define what to do when we have output
+        const logOutput = (output) => {
+            const endTimeInMilliseconds = new Date().getTime();
+            const durationInMilliseconds = endTimeInMilliseconds - startTimeInMilliseconds;
+            const durationInSeconds = roundToHundredths(durationInMilliseconds / 1e3); // https://stackoverflow.com/a/53970656/3068233
+            context.log[logLevelOutput](`${name}.output`, {
+                input: logInputMethod(input, context),
+                output: logOutputMethod(output),
+                ...(durationInSeconds >= durationReportingThresholdInSeconds
+                    ? { duration: `${durationInSeconds} sec` } // only include the duration if the threshold was crossed
+                    : {}),
+            });
+        };
+        // if result is a promise, ensure we log after the output resolves
+        if ((0, type_fns_1.isAPromise)(result))
+            return result
+                .then((output) => {
+                logOutput(output);
+                return output;
+            })
+                .catch((error) => {
+                logError(error);
+                throw error;
+            });
+        // otherwise, its not a promise, so its done, so log now and return the result
+        logOutput(result);
+        return result;
+    };
+};
+exports.withLogTrail = withLogTrail;
+//# sourceMappingURL=withLogTrail.js.map

package/dist/domain.operations/withLogTrail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withLogTrail.js","sourceRoot":"","sources":["../../src/domain.operations/withLogTrail.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { LogLevel } from './domain.objects/constants';
+export type { ContextLogTrail, HasContextLogTrail, LogTrail, } from './domain.objects/LogTrail';
+export type { LogMethod } from './domain.operations/generateLogMethod';
+export type { LogMethods } from './domain.operations/generateLogMethods';
+export { generateLogMethods } from './domain.operations/generateLogMethods';
+export { withLogTrail } from './domain.operations/withLogTrail';

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLogTrail = exports.generateLogMethods = exports.LogLevel = void 0;
+var constants_1 = require("./domain.objects/constants");
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return constants_1.LogLevel; } });
+var generateLogMethods_1 = require("./domain.operations/generateLogMethods");
+Object.defineProperty(exports, "generateLogMethods", { enumerable: true, get: function () { return generateLogMethods_1.generateLogMethods; } });
+var withLogTrail_1 = require("./domain.operations/withLogTrail");
+Object.defineProperty(exports, "withLogTrail", { enumerable: true, get: function () { return withLogTrail_1.withLogTrail; } });
+//# 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,wDAAsD;AAA7C,qGAAA,QAAQ,OAAA;AAQjB,6EAA4E;AAAnE,wHAAA,kBAAkB,OAAA;AAC3B,iEAAgE;AAAvD,4GAAA,YAAY,OAAA"}

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 ehmpathy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "sdk-logs",
+  "author": "ehmpathy",
+  "description": "a simple and opinionated logging library. plays well with aws lambda + cloudwatch.",
+  "version": "0.6.12",
+  "repository": "ehmpathy/sdk-logs",
+  "homepage": "https://github.com/ehmpathy/sdk-logs",
+  "keywords": [
+    "log",
+    "logs",
+    "level",
+    "simple",
+    "filter",
+    "aws",
+    "lambda",
+    "cloudwatch",
+    "requestId"
+  ],
+  "bugs": "https://github.com/ehmpathy/sdk-logs/issues",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/dist"
+  ],
+  "dependencies": {
+    "@ehmpathy/error-fns": "^1.3.7",
+    "domain-glossary-procedure": "^1.0.0",
+    "domain-objects": "0.31.10",
+    "helpful-errors": "1.7.3",
+    "iso-time": "^1.11.5",
+    "type-fns": "1.21.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@commitlint/cli": "19.5.0",
+    "@commitlint/config-conventional": "19.5.0",
+    "@swc/core": "1.15.3",
+    "@swc/jest": "0.2.39",
+    "@tsconfig/node20": "20.1.5",
+    "@tsconfig/strictest": "2.0.5",
+    "@types/jest": "30.0.0",
+    "@types/node": "22.15.21",
+    "cz-conventional-changelog": "3.3.0",
+    "declapract": "^0.13.18",
+    "declapract-typescript-ehmpathy": "^0.47.14",
+    "declastruct": "1.7.3",
+    "declastruct-github": "1.3.0",
+    "depcheck": "1.4.3",
+    "esbuild-register": "3.6.0",
+    "husky": "8.0.3",
+    "jest": "30.2.0",
+    "rhachet": "1.41.4",
+    "rhachet-brains-anthropic": "^0.4.1",
+    "rhachet-brains-xai": "^0.3.3",
+    "rhachet-roles-bhrain": "0.27.6",
+    "rhachet-roles-bhuild": "0.21.4",
+    "rhachet-roles-ehmpathy": "1.35.0",
+    "rhachet-roles-rhachet": "^0.1.7",
+    "test-fns": "1.4.2",
+    "tsc-alias": "1.8.10",
+    "tsx": "4.20.6",
+    "typescript": "5.4.5",
+    "yalc": "1.0.0-pre.53"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "scripts": {
+    "build:ts": "tsc -p ./tsconfig.build.json",
+    "commit:with-cli": "npx cz",
+    "fix:format:biome": "biome check --write",
+    "fix:format": "npm run fix:format:biome",
+    "fix:lint": "biome check --write",
+    "fix": "npm run fix:format && npm run fix:lint",
+    "build:clean": "chmod -R u+w dist 2>/dev/null; rm -rf dist/",
+    "build:compile": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
+    "build": "npm run build:clean && npm run build:compile && npm run build:complete --if-present",
+    "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.json --noEmit",
+    "test:format:biome": "biome format",
+    "test:format": "npm run test:format:biome",
+    "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
+    "test:lint:biome": "biome check --diagnostic-level=error",
+    "test:lint:biome:all": "biome check",
+    "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
+    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "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 $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "prepush": "npm run test && npm run build",
+    "prepublish": "npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "prepare:husky": "husky install && chmod ug+x .husky/*",
+    "prepare:rhachet": "rhachet init --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect reflector dreamer dispatcher"
+  }
+}

package/readme.md

@@ -0,0 +1,45 @@
+# sdk-logs
+
+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 sdk-logs
+```
+
+# usage
+
+### init
+```ts
+// e.g., in `src/utils/log.ts
+import { generateLogMethods } from 'sdk-logs';
+
+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)
+```