sdk-logs 0.6.13 → 0.8.0

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

@@ -0,0 +1,33 @@
+import type { LogLevel } from './constants';
+/**
+ * .what = a log event that flows through outlets
+ * .why = standardized shape for log data across destinations
+ */
+export interface LogEvent {
+    level: LogLevel;
+    timestamp: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * .what = an outlet that receives log events
+ * .why = enables logs to route to external destinations (e.g., CloudWatch)
+ */
+export interface LogOutlet {
+    /**
+     * .what = send a log event to this outlet
+     * .why = buffers or dispatches the event to the destination
+     */
+    send: (event: LogEvent) => void;
+    /**
+     * .what = flush buffered events to the destination
+     * .why = ensures all buffered logs are sent before process exit
+     */
+    flush: () => Promise<void>;
+    /**
+     * .what = close the outlet and release resources
+     * .why = cleans up timers and process listeners to prevent leaks in tests
+     * .note = optional - not all outlets require cleanup
+     */
+    close?: () => void;
+}

package/dist/domain.objects/LogOutlet.js

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

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

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

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

@@ -1,20 +1,36 @@
 import type { Procedure, ProcedureContext } from 'domain-glossary-procedure';
-import type { LogMethods } from '../domain.operations/generateLogMethods';
+import type { LogMethods } from '../domain.operations/genLogMethods';
 /**
- * .what = the procedure invocation trail
+ * .what = the procedure invocation trail with external identifier
  */
-export type LogTrail = string[];
+export interface LogTrail {
+    /**
+     * .what = external identifier for request correlation
+     * .why = enables log correlation across a single request
+     */
+    exid: string | null;
+    /**
+     * .what = the procedure call stack
+     * .why = tracks call depth through withLogTrail wraps
+     */
+    stack: 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;
+        /**
+         * .what = environment context for log output
+         */
+        env?: {
+            commit: string;
+        };
     };
 }
 export type HasContextLogTrail<T extends Procedure> = ProcedureContext<T> extends ContextLogTrail ? T : never;

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

@@ -0,0 +1,5 @@
+/**
+ * .what = returns current UTC timestamp in ISO 8601 format
+ * .why = extracts decode-friction from orchestrators
+ */
+export declare const asCurrentIsoTimestamp: () => string;

package/dist/domain.operations/asCurrentIsoTimestamp.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asCurrentIsoTimestamp = void 0;
+/**
+ * .what = returns current UTC timestamp in ISO 8601 format
+ * .why = extracts decode-friction from orchestrators
+ */
+const asCurrentIsoTimestamp = () => {
+    return new Date().toISOString();
+};
+exports.asCurrentIsoTimestamp = asCurrentIsoTimestamp;
+//# sourceMappingURL=asCurrentIsoTimestamp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asCurrentIsoTimestamp.js","sourceRoot":"","sources":["../../src/domain.operations/asCurrentIsoTimestamp.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACI,MAAM,qBAAqB,GAAG,GAAW,EAAE;IAChD,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC,CAAC;AAFW,QAAA,qBAAqB,yBAEhC"}

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

@@ -1,15 +1,34 @@
 import { type LogLevel } from '../domain.objects/constants';
-export declare const formatLogContentsForEnvironment: ({ level, timestamp, message, metadata, }: {
+import type { LogTrail } from '../domain.objects/LogTrail';
+export declare const formatLogContentsForEnvironment: ({ level, timestamp, message, metadata, trail, env, }: {
     level: LogLevel;
     timestamp: string;
     message: string;
     metadata?: Record<string, any>;
+    trail?: LogTrail;
+    env?: {
+        commit: string;
+    };
 }) => string | {
+    env?: {
+        commit: string;
+    } | undefined;
+    trail?: {
+        stack: string[];
+        exid?: string | undefined;
+    } | undefined;
     level: LogLevel;
     timestamp: string;
     message: string;
     metadata: string;
 } | {
+    env?: {
+        commit: string;
+    } | undefined;
+    trail?: {
+        stack: string[];
+        exid?: string | undefined;
+    } | undefined;
     level: LogLevel;
     timestamp: string;
     message: string;

package/dist/domain.operations/formatLogContentsForEnvironment.js

@@ -1,39 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatLogContentsForEnvironment = void 0;
+const helpful_errors_1 = require("helpful-errors");
 const constants_1 = require("../domain.objects/constants");
 const identifyEnvironment_1 = require("./identifyEnvironment");
-const formatLogContentsForEnvironment = ({ level, timestamp, message, metadata, }) => {
-    const env = (0, identifyEnvironment_1.identifyEnvironment)();
+const formatLogContentsForEnvironment = ({ level, timestamp, message, metadata, trail, env, }) => {
+    const environment = (0, identifyEnvironment_1.identifyEnvironment)();
+    // build trail output: omit if not provided, omit exid if null
+    const trailOutput = trail
+        ? {
+            ...(trail.exid !== null ? { exid: trail.exid } : {}),
+            stack: trail.stack,
+        }
+        : undefined;
+    // build env output: omit if not provided or commit is null
+    const envOutput = env?.commit ? { commit: env.commit } : undefined;
     // 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) {
+    if (environment === 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
+            ...(trailOutput ? { trail: trailOutput } : {}),
+            ...(envOutput ? { env: envOutput } : {}),
         };
     }
     // 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) {
+    if (environment === constants_1.SupportedEnvironment.AWS_LAMBDA) {
         return JSON.stringify({
             level,
             timestamp,
             message,
             metadata,
+            ...(trailOutput ? { trail: trailOutput } : {}),
+            ...(envOutput ? { env: envOutput } : {}),
         });
     }
     // 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) {
+    if (environment === constants_1.SupportedEnvironment.WEB_BROWSER) {
         return {
             level,
             timestamp,
             message,
             metadata,
+            ...(trailOutput ? { trail: trailOutput } : {}),
+            ...(envOutput ? { env: envOutput } : {}),
         };
     }
     // 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
+    throw new helpful_errors_1.UnexpectedCodePathError('unsupported environment detected. this should never occur - and is a bug within sdk-logs');
 };
 exports.formatLogContentsForEnvironment = formatLogContentsForEnvironment;
 //# sourceMappingURL=formatLogContentsForEnvironment.js.map

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

@@ -1 +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"}
+{"version":3,"file":"formatLogContentsForEnvironment.js","sourceRoot":"","sources":["../../src/domain.operations/formatLogContentsForEnvironment.ts"],"names":[],"mappings":";;;AAAA,mDAAyD;AAEzD,6DAGuC;AAGvC,+DAA4D;AAErD,MAAM,+BAA+B,GAAG,CAAC,EAC9C,KAAK,EACL,SAAS,EACT,OAAO,EACP,QAAQ,EACR,KAAK,EACL,GAAG,GAQJ,EAAE,EAAE;IACH,MAAM,WAAW,GAAG,IAAA,yCAAmB,GAAE,CAAC;IAE1C,8DAA8D;IAC9D,MAAM,WAAW,GAAG,KAAK;QACvB,CAAC,CAAC;YACE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB;QACH,CAAC,CAAC,SAAS,CAAC;IAEd,2DAA2D;IAC3D,MAAM,SAAS,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,0HAA0H;IAC1H,IAAI,WAAW,KAAK,gCAAoB,CAAC,KAAK,EAAE,CAAC;QAC/C,OAAO;YACL,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,mEAAmE;YACvG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzC,CAAC;IACJ,CAAC;IAED,qKAAqK;IACrK,IAAI,WAAW,KAAK,gCAAoB,CAAC,UAAU,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ;YACR,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,wJAAwJ;IACxJ,IAAI,WAAW,KAAK,gCAAoB,CAAC,WAAW,EAAE,CAAC;QACrD,OAAO;YACL,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ;YACR,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzC,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,MAAM,IAAI,wCAAuB,CAC/B,0FAA0F,CAC3F,CAAC;AACJ,CAAC,CAAC;AApEW,QAAA,+BAA+B,mCAoE1C"}

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

@@ -0,0 +1,28 @@
+import { LogLevel } from '../domain.objects/constants';
+import type { ContextLogTrail } from '../domain.objects/LogTrail';
+/**
+ * .what = create a log context with trail and env injection
+ * .why = enables request correlation via trail.exid and code version via env.commit
+ */
+export declare const genContextLogTrail: ({ trail, env, minimalLogLevel, }: {
+    /**
+     * .what = the trail context for log correlation
+     * .why = forces caller to explicitly provide or pass null
+     */
+    trail: {
+        exid: string | null;
+        stack: string[];
+    } | null;
+    /**
+     * .what = the environment context
+     * .why = forces caller to explicitly provide or pass null
+     */
+    env: {
+        commit: string | null;
+    } | null;
+    /**
+     * .what = the minimum log level to emit
+     * .why = allows filter of logs by level
+     */
+    minimalLogLevel?: LogLevel;
+}) => ContextLogTrail;

package/dist/domain.operations/genContextLogTrail.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genContextLogTrail = void 0;
+const constants_1 = require("../domain.objects/constants");
+const generateLogMethod_1 = require("./generateLogMethod");
+const getRecommendedMinimalLogLevelForEnvironment_1 = require("./getRecommendedMinimalLogLevelForEnvironment");
+/**
+ * .what = create a log context with trail and env injection
+ * .why = enables request correlation via trail.exid and code version via env.commit
+ */
+const genContextLogTrail = ({ trail, env, minimalLogLevel = (0, getRecommendedMinimalLogLevelForEnvironment_1.getRecommendedMinimalLogLevelForEnvironment)(), }) => {
+    // build the trail object: only include if provided
+    const trailForLog = trail
+        ? { exid: trail.exid, stack: trail.stack }
+        : undefined;
+    // build the env object: only include if commit is not null
+    const envForLog = env?.commit !== null && env?.commit !== undefined
+        ? { commit: env.commit }
+        : undefined;
+    // generate the log methods with trail/env injected
+    const logMethods = {
+        error: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.ERROR,
+            minimalLogLevel,
+            trail: trailForLog,
+            env: envForLog,
+        }),
+        warn: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.WARN,
+            minimalLogLevel,
+            trail: trailForLog,
+            env: envForLog,
+        }),
+        info: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.INFO,
+            minimalLogLevel,
+            trail: trailForLog,
+            env: envForLog,
+        }),
+        debug: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.DEBUG,
+            minimalLogLevel,
+            trail: trailForLog,
+            env: envForLog,
+        }),
+    };
+    // return the context with log methods, trail, env, and config
+    return {
+        log: {
+            ...logMethods,
+            trail: trailForLog,
+            env: envForLog,
+            _: Object.freeze({ level: minimalLogLevel }),
+        },
+    };
+};
+exports.genContextLogTrail = genContextLogTrail;
+//# sourceMappingURL=genContextLogTrail.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"genContextLogTrail.js","sourceRoot":"","sources":["../../src/domain.operations/genContextLogTrail.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAGzD,2DAAwD;AACxD,+GAA4G;AAE5G;;;GAGG;AACI,MAAM,kBAAkB,GAAG,CAAC,EACjC,KAAK,EACL,GAAG,EACH,eAAe,GAAG,IAAA,yFAA2C,GAAE,GAwBhE,EAAmB,EAAE;IACpB,mDAAmD;IACnD,MAAM,WAAW,GAAyB,KAAK;QAC7C,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;QAC1C,CAAC,CAAC,SAAS,CAAC;IAEd,2DAA2D;IAC3D,MAAM,SAAS,GACb,GAAG,EAAE,MAAM,KAAK,IAAI,IAAI,GAAG,EAAE,MAAM,KAAK,SAAS;QAC/C,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;QACxB,CAAC,CAAC,SAAS,CAAC;IAEhB,mDAAmD;IACnD,MAAM,UAAU,GAAG;QACjB,KAAK,EAAE,IAAA,qCAAiB,EAAC;YACvB,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe;YACf,KAAK,EAAE,WAAW;YAClB,GAAG,EAAE,SAAS;SACf,CAAC;QACF,IAAI,EAAE,IAAA,qCAAiB,EAAC;YACtB,KAAK,EAAE,oBAAQ,CAAC,IAAI;YACpB,eAAe;YACf,KAAK,EAAE,WAAW;YAClB,GAAG,EAAE,SAAS;SACf,CAAC;QACF,IAAI,EAAE,IAAA,qCAAiB,EAAC;YACtB,KAAK,EAAE,oBAAQ,CAAC,IAAI;YACpB,eAAe;YACf,KAAK,EAAE,WAAW;YAClB,GAAG,EAAE,SAAS;SACf,CAAC;QACF,KAAK,EAAE,IAAA,qCAAiB,EAAC;YACvB,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe;YACf,KAAK,EAAE,WAAW;YAClB,GAAG,EAAE,SAAS;SACf,CAAC;KACH,CAAC;IAEF,8DAA8D;IAC9D,OAAO;QACL,GAAG,EAAE;YACH,GAAG,UAAU;YACb,KAAK,EAAE,WAAW;YAClB,GAAG,EAAE,SAAS;YACd,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;SAC7C;KACF,CAAC;AACJ,CAAC,CAAC;AA5EW,QAAA,kBAAkB,sBA4E7B"}

package/dist/domain.operations/{generateLogMethods.d.ts → genLogMethods.d.ts}

@@ -1,4 +1,5 @@
 import { LogLevel } from '../domain.objects/constants';
+import type { LogOutlet } from '../domain.objects/LogOutlet';
 import { type LogMethod } from './generateLogMethod';
 export interface LogMethods {
     /**
@@ -25,12 +26,22 @@ export interface LogMethods {
      * - 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;
+    /**
+     * .what = internal config for log methods
+     */
+    readonly _: Readonly<{
+        level: LogLevel;
+    }>;
 }
 /**
  * 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
+ * - allows you to specify outlets for log events to flow to external destinations
  */
-export declare const generateLogMethods: ({ minimalLogLevel, }?: {
-    minimalLogLevel?: LogLevel;
+export declare const genLogMethods: ({ level, outlets, }?: {
+    level?: {
+        minimum?: LogLevel;
+    };
+    outlets?: LogOutlet[];
 }) => LogMethods;

package/dist/domain.operations/genLogMethods.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genLogMethods = 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
+ * - allows you to specify outlets for log events to flow to external destinations
+ */
+const genLogMethods = ({ level, outlets, } = {}) => {
+    // derive minimal log level
+    const derivedMinimalLogLevel = level?.minimum ?? (0, getRecommendedMinimalLogLevelForEnvironment_1.getRecommendedMinimalLogLevelForEnvironment)();
+    // generate the methods
+    return {
+        error: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.ERROR,
+            minimalLogLevel: derivedMinimalLogLevel,
+            outlets,
+        }),
+        warn: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.WARN,
+            minimalLogLevel: derivedMinimalLogLevel,
+            outlets,
+        }),
+        info: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.INFO,
+            minimalLogLevel: derivedMinimalLogLevel,
+            outlets,
+        }),
+        debug: (0, generateLogMethod_1.generateLogMethod)({
+            level: constants_1.LogLevel.DEBUG,
+            minimalLogLevel: derivedMinimalLogLevel,
+            outlets,
+        }),
+        _: Object.freeze({ level: derivedMinimalLogLevel }),
+    };
+};
+exports.genLogMethods = genLogMethods;
+//# sourceMappingURL=genLogMethods.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"genLogMethods.js","sourceRoot":"","sources":["../../src/domain.operations/genLogMethods.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAGzD,2DAAwE;AACxE,+GAA4G;AAqC5G;;;;;GAKG;AACI,MAAM,aAAa,GAAG,CAAC,EAC5B,KAAK,EACL,OAAO,MAIL,EAAE,EAAc,EAAE;IACpB,2BAA2B;IAC3B,MAAM,sBAAsB,GAC1B,KAAK,EAAE,OAAO,IAAI,IAAA,yFAA2C,GAAE,CAAC;IAElE,uBAAuB;IACvB,OAAO;QACL,KAAK,EAAE,IAAA,qCAAiB,EAAC;YACvB,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe,EAAE,sBAAsB;YACvC,OAAO;SACR,CAAC;QACF,IAAI,EAAE,IAAA,qCAAiB,EAAC;YACtB,KAAK,EAAE,oBAAQ,CAAC,IAAI;YACpB,eAAe,EAAE,sBAAsB;YACvC,OAAO;SACR,CAAC;QACF,IAAI,EAAE,IAAA,qCAAiB,EAAC;YACtB,KAAK,EAAE,oBAAQ,CAAC,IAAI;YACpB,eAAe,EAAE,sBAAsB;YACvC,OAAO;SACR,CAAC;QACF,KAAK,EAAE,IAAA,qCAAiB,EAAC;YACvB,KAAK,EAAE,oBAAQ,CAAC,KAAK;YACrB,eAAe,EAAE,sBAAsB;YACvC,OAAO;SACR,CAAC;QACF,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;KACpD,CAAC;AACJ,CAAC,CAAC;AAnCW,QAAA,aAAa,iBAmCxB"}

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

@@ -1,6 +1,13 @@
 import { LogLevel } from '../domain.objects/constants';
+import type { LogOutlet } from '../domain.objects/LogOutlet';
+import type { LogTrail } from '../domain.objects/LogTrail';
 export type LogMethod = (message: string, metadata?: any) => void;
-export declare const generateLogMethod: ({ level, minimalLogLevel, }: {
+export declare const generateLogMethod: ({ level, minimalLogLevel, trail, env, outlets, }: {
     level: LogLevel;
     minimalLogLevel: LogLevel;
+    trail?: LogTrail;
+    env?: {
+        commit: string;
+    };
+    outlets?: LogOutlet[];
 }) => (message: string, metadata?: object) => void;

package/dist/domain.operations/generateLogMethod.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateLogMethod = void 0;
 const constants_1 = require("../domain.objects/constants");
+const asCurrentIsoTimestamp_1 = require("./asCurrentIsoTimestamp");
 const formatLogContentsForEnvironment_1 = require("./formatLogContentsForEnvironment");
 /*
   define priority order of log levels and make it easy to ask questions about
@@ -13,23 +14,40 @@ const logLevelPriorityOrder = [
     constants_1.LogLevel.DEBUG,
 ];
 const aIsEqualOrMoreImportantThanB = ({ a, b }) => logLevelPriorityOrder.indexOf(a) - logLevelPriorityOrder.indexOf(b) <= 0;
-const generateLogMethod = ({ level, minimalLogLevel, }) => {
+const generateLogMethod = ({ level, minimalLogLevel, trail, env, outlets, }) => {
     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)({
+        // check level threshold
+        if (!aIsEqualOrMoreImportantThanB({ a: level, b: minimalLogLevel }))
+            return;
+        // create timestamp once for consistency
+        const timestamp = (0, asCurrentIsoTimestamp_1.asCurrentIsoTimestamp)();
+        // 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,
+            message,
+            metadata,
+            trail,
+            env,
+        }));
+        // dispatch to outlets (fail-fast: errors propagate to caller)
+        if (outlets && outlets.length > 0) {
+            const event = {
                 level,
-                timestamp: new Date().toISOString(),
+                timestamp,
                 message,
-                metadata,
-            }));
+                metadata: metadata,
+            };
+            for (const outlet of outlets) {
+                outlet.send(event);
+            }
         }
     };
 };

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

@@ -1 +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"}
+{"version":3,"file":"generateLogMethod.js","sourceRoot":"","sources":["../../src/domain.operations/generateLogMethod.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAIzD,mEAAgE;AAChE,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,EACf,KAAK,EACL,GAAG,EACH,OAAO,GAOR,EAAE,EAAE;IACH,OAAO,CAAC,OAAe,EAAE,QAAiB,EAAE,EAAE;QAC5C,wBAAwB;QACxB,IAAI,CAAC,4BAA4B,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC;YAAE,OAAO;QAE5E,wCAAwC;QACxC,MAAM,SAAS,GAAG,IAAA,6CAAqB,GAAE,CAAC;QAE1C,yFAAyF;QACzF,MAAM,aAAa,GAAG,4BAA4B,CAAC;YACjD,CAAC,EAAE,KAAK;YACR,CAAC,EAAE,oBAAQ,CAAC,IAAI;SACjB,CAAC;YACA,CAAC,CAAC,OAAO,CAAC,IAAI;YACd,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,iCAAiC;QAElD,wGAAwG;QACxG,aAAa,CACX,IAAA,iEAA+B,EAAC;YAC9B,KAAK;YACL,SAAS;YACT,OAAO;YACP,QAAQ;YACR,KAAK;YACL,GAAG;SACJ,CAAC,CACH,CAAC;QAEF,8DAA8D;QAC9D,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,KAAK,GAAa;gBACtB,KAAK;gBACL,SAAS;gBACT,OAAO;gBACP,QAAQ,EAAE,QAA+C;aAC1D,CAAC;YACF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC,CAAC;AArDW,QAAA,iBAAiB,qBAqD5B"}

package/dist/domain.operations/outlets/cloudwatch/asCloudWatchBatches.d.ts

@@ -0,0 +1,8 @@
+import type { LogEvent } from '../../../domain.objects/LogOutlet';
+/**
+ * .what = splits log events into CloudWatch-compliant batches
+ * .why = CloudWatch rejects batches over 1MB or 10k events
+ *
+ * @returns array of batches, each within CloudWatch limits
+ */
+export declare const asCloudWatchBatches: (events: LogEvent[]) => LogEvent[][];

package/dist/domain.operations/outlets/cloudwatch/asCloudWatchBatches.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asCloudWatchBatches = void 0;
+const computeLogEventSize_1 = require("./computeLogEventSize");
+/**
+ * .what = CloudWatch PutLogEvents limits
+ * .why = CloudWatch rejects batches that exceed these limits
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html
+ */
+const CLOUDWATCH_MAX_BATCH_SIZE = 1048576; // 1MB
+const CLOUDWATCH_MAX_BATCH_COUNT = 10000;
+const CLOUDWATCH_EVENT_OVERHEAD = 26; // bytes per event
+/**
+ * .what = splits log events into CloudWatch-compliant batches
+ * .why = CloudWatch rejects batches over 1MB or 10k events
+ *
+ * @returns array of batches, each within CloudWatch limits
+ */
+const asCloudWatchBatches = (events) => {
+    if (events.length === 0)
+        return [];
+    const batches = [];
+    let currentBatch = [];
+    let currentBatchSize = 0;
+    for (const event of events) {
+        const eventSize = (0, computeLogEventSize_1.computeLogEventSize)(event) + CLOUDWATCH_EVENT_OVERHEAD;
+        // check if event would exceed batch limits
+        const wouldExceedSize = currentBatchSize + eventSize > CLOUDWATCH_MAX_BATCH_SIZE;
+        const wouldExceedCount = currentBatch.length >= CLOUDWATCH_MAX_BATCH_COUNT;
+        // start new batch if limits exceeded
+        if (currentBatch.length > 0 && (wouldExceedSize || wouldExceedCount)) {
+            batches.push(currentBatch);
+            currentBatch = [];
+            currentBatchSize = 0;
+        }
+        currentBatch.push(event);
+        currentBatchSize += eventSize;
+    }
+    // push final batch if non-empty
+    if (currentBatch.length > 0) {
+        batches.push(currentBatch);
+    }
+    return batches;
+};
+exports.asCloudWatchBatches = asCloudWatchBatches;
+//# sourceMappingURL=asCloudWatchBatches.js.map

package/dist/domain.operations/outlets/cloudwatch/asCloudWatchBatches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asCloudWatchBatches.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/asCloudWatchBatches.ts"],"names":[],"mappings":";;;AAEA,+DAA4D;AAE5D;;;;;GAKG;AACH,MAAM,yBAAyB,GAAG,OAAS,CAAC,CAAC,MAAM;AACnD,MAAM,0BAA0B,GAAG,KAAM,CAAC;AAC1C,MAAM,yBAAyB,GAAG,EAAE,CAAC,CAAC,kBAAkB;AAExD;;;;;GAKG;AACI,MAAM,mBAAmB,GAAG,CAAC,MAAkB,EAAgB,EAAE;IACtE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,IAAI,YAAY,GAAe,EAAE,CAAC;IAClC,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,IAAA,yCAAmB,EAAC,KAAK,CAAC,GAAG,yBAAyB,CAAC;QAEzE,2CAA2C;QAC3C,MAAM,eAAe,GACnB,gBAAgB,GAAG,SAAS,GAAG,yBAAyB,CAAC;QAC3D,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM,IAAI,0BAA0B,CAAC;QAE3E,qCAAqC;QACrC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,gBAAgB,CAAC,EAAE,CAAC;YACrE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC3B,YAAY,GAAG,EAAE,CAAC;YAClB,gBAAgB,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,gBAAgB,IAAI,SAAS,CAAC;IAChC,CAAC;IAED,gCAAgC;IAChC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAhCW,QAAA,mBAAmB,uBAgC9B"}

package/dist/domain.operations/outlets/cloudwatch/asCloudWatchLogEvents.d.ts

@@ -0,0 +1,9 @@
+import type { LogEvent } from '../../../domain.objects/LogOutlet';
+/**
+ * .what = transforms LogEvents to CloudWatch PutLogEvents format
+ * .why = extracts decode-friction from orchestrator
+ */
+export declare const asCloudWatchLogEvents: (events: LogEvent[]) => Array<{
+    timestamp: number;
+    message: string;
+}>;

package/dist/domain.operations/outlets/cloudwatch/asCloudWatchLogEvents.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asCloudWatchLogEvents = void 0;
+/**
+ * .what = transforms LogEvents to CloudWatch PutLogEvents format
+ * .why = extracts decode-friction from orchestrator
+ */
+const asCloudWatchLogEvents = (events) => {
+    return events.map((e) => ({
+        timestamp: Date.parse(e.timestamp),
+        message: JSON.stringify(e),
+    }));
+};
+exports.asCloudWatchLogEvents = asCloudWatchLogEvents;
+//# sourceMappingURL=asCloudWatchLogEvents.js.map

package/dist/domain.operations/outlets/cloudwatch/asCloudWatchLogEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asCloudWatchLogEvents.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/asCloudWatchLogEvents.ts"],"names":[],"mappings":";;;AAEA;;;GAGG;AACI,MAAM,qBAAqB,GAAG,CACnC,MAAkB,EAC6B,EAAE;IACjD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAClC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;KAC3B,CAAC,CAAC,CAAC;AACN,CAAC,CAAC;AAPW,QAAA,qBAAqB,yBAOhC"}

package/dist/domain.operations/outlets/cloudwatch/asDefaultLogStreamName.d.ts

@@ -0,0 +1,6 @@
+/**
+ * .what = generates a default log stream name for CloudWatch
+ * .why = matches Lambda's log stream format: YYYY/MM/DD/[$LATEST]instance-id
+ * .note = explicit opt-in: user adds outlet only when automatic forwarder absent
+ */
+export declare const asDefaultLogStreamName: () => string;

package/dist/domain.operations/outlets/cloudwatch/asDefaultLogStreamName.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asDefaultLogStreamName = void 0;
+const crypto_1 = require("crypto");
+/**
+ * .what = extracts date in Lambda log stream format (YYYY/MM/DD)
+ * .why = matches Lambda's native log stream date format
+ */
+const asLambdaDatePrefix = (input) => {
+    const iso = input.from.toISOString().split('T')[0];
+    return iso.replace(/-/g, '/'); // YYYY-MM-DD -> YYYY/MM/DD
+};
+/**
+ * .what = generates a default log stream name for CloudWatch
+ * .why = matches Lambda's log stream format: YYYY/MM/DD/[$LATEST]instance-id
+ * .note = explicit opt-in: user adds outlet only when automatic forwarder absent
+ */
+const asDefaultLogStreamName = () => {
+    const datePrefix = asLambdaDatePrefix({ from: new Date() });
+    const instanceId = (0, crypto_1.randomUUID)();
+    return `${datePrefix}/[$LATEST]${instanceId}`;
+};
+exports.asDefaultLogStreamName = asDefaultLogStreamName;
+//# sourceMappingURL=asDefaultLogStreamName.js.map

package/dist/domain.operations/outlets/cloudwatch/asDefaultLogStreamName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asDefaultLogStreamName.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/asDefaultLogStreamName.ts"],"names":[],"mappings":";;;AAAA,mCAAoC;AAEpC;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,KAAqB,EAAU,EAAE;IAC3D,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACpD,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,2BAA2B;AAC5D,CAAC,CAAC;AAEF;;;;GAIG;AACI,MAAM,sBAAsB,GAAG,GAAW,EAAE;IACjD,MAAM,UAAU,GAAG,kBAAkB,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,IAAA,mBAAU,GAAE,CAAC;IAChC,OAAO,GAAG,UAAU,aAAa,UAAU,EAAE,CAAC;AAChD,CAAC,CAAC;AAJW,QAAA,sBAAsB,0BAIjC"}

package/dist/domain.operations/outlets/cloudwatch/asLambdaStyleLogGroupName.d.ts

@@ -0,0 +1,18 @@
+/**
+ * .what = generates a lambda-style log group name
+ * .why = CloudWatch log groups follow `/aws/lambda/{service}-{env}` pattern
+ *
+ * .note = performs I/O when service is not provided:
+ *         - reads package.json from cwd for service name
+ *         - reads env vars (ENVIRONMENT_ACCESS, ENV_ACCESS, STAGE, NODE_ENV) for env.access
+ *         for pure usage, pass both service and env.access explicitly.
+ *
+ * @param service - service name (default: reads from package.json)
+ * @param env.access - environment access level (default: from env vars, fallback 'local')
+ */
+export declare const asLambdaStyleLogGroupName: ({ service, env, }?: {
+    service?: string;
+    env?: {
+        access?: string;
+    };
+}) => string;