sdk-logs 0.7.0 → 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.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/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 {
     /**
@@ -36,7 +37,11 @@ export interface LogMethods {
  * 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 genLogMethods: ({ minimalLogLevel, }?: {
-    minimalLogLevel?: LogLevel;
+export declare const genLogMethods: ({ level, outlets, }?: {
+    level?: {
+        minimum?: LogLevel;
+    };
+    outlets?: LogOutlet[];
 }) => LogMethods;

package/dist/domain.operations/genLogMethods.js

@@ -8,15 +8,34 @@ const getRecommendedMinimalLogLevelForEnvironment_1 = require("./getRecommendedM
  * 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 = ({ minimalLogLevel = (0, getRecommendedMinimalLogLevelForEnvironment_1.getRecommendedMinimalLogLevelForEnvironment)(), } = {}) => {
+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 }),
-        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 }),
-        _: Object.freeze({ level: minimalLogLevel }),
+        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;

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

@@ -1 +1 @@
-{"version":3,"file":"genLogMethods.js","sourceRoot":"","sources":["../../src/domain.operations/genLogMethods.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAEzD,2DAAwE;AACxE,+GAA4G;AAqC5G;;;;GAIG;AACI,MAAM,aAAa,GAAG,CAAC,EAC5B,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;QACpE,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;KAC7C,CAAC;AACJ,CAAC,CAAC;AAbW,QAAA,aAAa,iBAaxB"}
+{"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,11 +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, trail, env, }: {
+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,25 +14,40 @@ const logLevelPriorityOrder = [
     constants_1.LogLevel.DEBUG,
 ];
 const aIsEqualOrMoreImportantThanB = ({ a, b }) => logLevelPriorityOrder.indexOf(a) - logLevelPriorityOrder.indexOf(b) <= 0;
-const generateLogMethod = ({ level, minimalLogLevel, trail, env, }) => {
+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,
-                trail,
-                env,
-            }));
+                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;AAGzD,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,GAMJ,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;gBACR,KAAK;gBACL,GAAG;aACJ,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC,CAAC;AAlCW,QAAA,iBAAiB,qBAkC5B"}
+{"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;

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

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asLambdaStyleLogGroupName = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * .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')
+ */
+const asLambdaStyleLogGroupName = ({ service, env, } = {}) => {
+    const serviceName = service ?? getPackageJsonName();
+    const envAccess = env?.access ?? getEnvironmentAccessFromEnvVar();
+    return `/aws/lambda/${serviceName}-${envAccess}`;
+};
+exports.asLambdaStyleLogGroupName = asLambdaStyleLogGroupName;
+/**
+ * .what = reads package name from package.json in cwd
+ * .why = service name defaults to package name for consistency
+ */
+const getPackageJsonName = () => {
+    try {
+        const pkgPath = (0, path_1.join)(process.cwd(), 'package.json');
+        const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8'));
+        return pkg.name ?? 'unknown-service';
+    }
+    catch (error) {
+        // allowlist: file not found or parse errors are expected in some environments
+        if (error instanceof Error &&
+            (error.message.includes('ENOENT') ||
+                error.message.includes('Unexpected token') ||
+                error.message.includes('JSON'))) {
+            return 'unknown-service';
+        }
+        throw error;
+    }
+};
+/**
+ * .what = reads environment access from env var
+ * .why = enables environment-specific log groups (test, prep, prod)
+ */
+const getEnvironmentAccessFromEnvVar = () => {
+    // check common env var patterns
+    return (process.env.ENVIRONMENT_ACCESS ??
+        process.env.ENV_ACCESS ??
+        process.env.STAGE ??
+        process.env.NODE_ENV ??
+        'local');
+};
+//# sourceMappingURL=asLambdaStyleLogGroupName.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asLambdaStyleLogGroupName.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/asLambdaStyleLogGroupName.ts"],"names":[],"mappings":";;;AAAA,2BAAkC;AAClC,+BAA4B;AAE5B;;;;;;;;;;;GAWG;AACI,MAAM,yBAAyB,GAAG,CAAC,EACxC,OAAO,EACP,GAAG,MAID,EAAE,EAAU,EAAE;IAChB,MAAM,WAAW,GAAG,OAAO,IAAI,kBAAkB,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,GAAG,EAAE,MAAM,IAAI,8BAA8B,EAAE,CAAC;IAClE,OAAO,eAAe,WAAW,IAAI,SAAS,EAAE,CAAC;AACnD,CAAC,CAAC;AAVW,QAAA,yBAAyB,6BAUpC;AAEF;;;GAGG;AACH,MAAM,kBAAkB,GAAG,GAAW,EAAE;IACtC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAA,WAAI,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACvD,OAAO,GAAG,CAAC,IAAI,IAAI,iBAAiB,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,8EAA8E;QAC9E,IACE,KAAK,YAAY,KAAK;YACtB,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAC/B,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;gBAC1C,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EACjC,CAAC;YACD,OAAO,iBAAiB,CAAC;QAC3B,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,8BAA8B,GAAG,GAAW,EAAE;IAClD,gCAAgC;IAChC,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAC9B,OAAO,CAAC,GAAG,CAAC,UAAU;QACtB,OAAO,CAAC,GAAG,CAAC,KAAK;QACjB,OAAO,CAAC,GAAG,CAAC,QAAQ;QACpB,OAAO,CACR,CAAC;AACJ,CAAC,CAAC"}

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

@@ -0,0 +1,8 @@
+/**
+ * .what = validates AWS credentials are available via common sources
+ * .why = fail-fast at outlet creation rather than on first flush
+ *
+ * .note = checks env vars and shared credentials file.
+ *         async credential providers (SSO, IAM roles) are validated on first flush.
+ */
+export declare const assertAwsCredentialsPresent: () => void;

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertAwsCredentialsPresent = void 0;
+const error_fns_1 = require("@ehmpathy/error-fns");
+/**
+ * .what = validates AWS credentials are available via common sources
+ * .why = fail-fast at outlet creation rather than on first flush
+ *
+ * .note = checks env vars and shared credentials file.
+ *         async credential providers (SSO, IAM roles) are validated on first flush.
+ */
+const assertAwsCredentialsPresent = () => {
+    // check env var credentials (most common in non-Lambda environments)
+    const hasEnvCredentials = process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY;
+    // check if profile is specified (indicates shared credentials or SSO)
+    const hasProfile = process.env.AWS_PROFILE;
+    // check if role ARN is specified (indicates assume-role config)
+    const hasRoleArn = process.env.AWS_ROLE_ARN;
+    // check if web identity is configured (EKS/IRSA)
+    const hasWebIdentity = process.env.AWS_WEB_IDENTITY_TOKEN_FILE && process.env.AWS_ROLE_ARN;
+    // check if container credentials are configured (ECS/Fargate)
+    const hasContainerCredentials = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI ||
+        process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI;
+    // check if in EC2/Lambda (metadata service provides credentials)
+    const hasMetadataService = process.env.AWS_EXECUTION_ENV;
+    // if none of the common credential sources are present, fail fast
+    if (!hasEnvCredentials &&
+        !hasProfile &&
+        !hasRoleArn &&
+        !hasWebIdentity &&
+        !hasContainerCredentials &&
+        !hasMetadataService) {
+        throw new error_fns_1.BadRequestError('AWS credentials not configured. genCloudwatchOutlet requires valid AWS credentials.', {
+            hint: [
+                'configure credentials via one of:',
+                '  - env: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY',
+                '  - env: AWS_PROFILE (for shared credentials or SSO)',
+                '  - env: AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN (for EKS/IRSA)',
+                '  - container: execute in ECS/Fargate with task role',
+                '  - metadata: execute in EC2/Lambda with instance/execution role',
+            ].join('\n'),
+        });
+    }
+};
+exports.assertAwsCredentialsPresent = assertAwsCredentialsPresent;
+//# sourceMappingURL=assertAwsCredentialsPresent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertAwsCredentialsPresent.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/assertAwsCredentialsPresent.ts"],"names":[],"mappings":";;;AAAA,mDAAsD;AAEtD;;;;;;GAMG;AACI,MAAM,2BAA2B,GAAG,GAAS,EAAE;IACpD,qEAAqE;IACrE,MAAM,iBAAiB,GACrB,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAErE,sEAAsE;IACtE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAE3C,gEAAgE;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAE5C,iDAAiD;IACjD,MAAM,cAAc,GAClB,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAEtE,8DAA8D;IAC9D,MAAM,uBAAuB,GAC3B,OAAO,CAAC,GAAG,CAAC,sCAAsC;QAClD,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC;IAEjD,iEAAiE;IACjE,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAEzD,kEAAkE;IAClE,IACE,CAAC,iBAAiB;QAClB,CAAC,UAAU;QACX,CAAC,UAAU;QACX,CAAC,cAAc;QACf,CAAC,uBAAuB;QACxB,CAAC,kBAAkB,EACnB,CAAC;QACD,MAAM,IAAI,2BAAe,CACvB,qFAAqF,EACrF;YACE,IAAI,EAAE;gBACJ,mCAAmC;gBACnC,oDAAoD;gBACpD,sDAAsD;gBACtD,oEAAoE;gBACpE,sDAAsD;gBACtD,kEAAkE;aACnE,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CACF,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AA9CW,QAAA,2BAA2B,+BA8CtC"}

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

@@ -0,0 +1,8 @@
+/**
+ * .what = computes the serialized size of a log event
+ * .why = enables amortized O(1) buffer size checks via incremental sum
+ *
+ * .note = this function is O(n) where n = serialized size.
+ *         call once per send() and track sum to avoid full buffer re-serialize.
+ */
+export declare const computeLogEventSize: (event: object) => number;

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

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeLogEventSize = void 0;
+/**
+ * .what = computes the serialized size of a log event
+ * .why = enables amortized O(1) buffer size checks via incremental sum
+ *
+ * .note = this function is O(n) where n = serialized size.
+ *         call once per send() and track sum to avoid full buffer re-serialize.
+ */
+const computeLogEventSize = (event) => {
+    return JSON.stringify(event).length + 1; // +1 for array comma separator
+};
+exports.computeLogEventSize = computeLogEventSize;
+//# sourceMappingURL=computeLogEventSize.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computeLogEventSize.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/computeLogEventSize.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACI,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAU,EAAE;IAC3D,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,+BAA+B;AAC1E,CAAC,CAAC;AAFW,QAAA,mBAAmB,uBAE9B"}

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

@@ -0,0 +1,6 @@
+import type { LogEvent } from '../../../domain.objects/LogOutlet';
+/**
+ * .what = extracts all events from buffer and clears it
+ * .why = extracts decode-friction from orchestrator (splice atomically removes and returns)
+ */
+export declare const drainBuffer: (buffer: LogEvent[]) => LogEvent[];

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.drainBuffer = void 0;
+/**
+ * .what = extracts all events from buffer and clears it
+ * .why = extracts decode-friction from orchestrator (splice atomically removes and returns)
+ */
+const drainBuffer = (buffer) => {
+    return buffer.splice(0, buffer.length);
+};
+exports.drainBuffer = drainBuffer;
+//# sourceMappingURL=drainBuffer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"drainBuffer.js","sourceRoot":"","sources":["../../../../src/domain.operations/outlets/cloudwatch/drainBuffer.ts"],"names":[],"mappings":";;;AAEA;;;GAGG;AACI,MAAM,WAAW,GAAG,CAAC,MAAkB,EAAc,EAAE;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC,CAAC;AAFW,QAAA,WAAW,eAEtB"}

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

@@ -0,0 +1,24 @@
+import type { LogOutlet } from '../../../domain.objects/LogOutlet';
+/**
+ * .what = generates a CloudWatch outlet for log events
+ * .why = enables log events to flow to CloudWatch in environments without automatic collection
+ *
+ * .note = explicit opt-in: add this outlet only when automatic log collection is absent.
+ *         AWS Lambda and CloudWatch Agent environments auto-collect console.log output.
+ *         in those environments, omit this outlet to avoid duplicate logs.
+ *
+ * @param region - AWS region (required: from option or AWS_REGION/AWS_DEFAULT_REGION env)
+ * @param logGroup - CloudWatch log group name (default: /aws/lambda/{service}-{env})
+ * @param logStream - CloudWatch log stream name (default: Lambda-style YYYY/MM/DD/[$LATEST]uuid)
+ * @param skipLogGroupCreation - skip log group findsert (default: false)
+ * @param flushInterval - auto-flush interval in ms (default: 5000)
+ * @param maxBufferSize - buffer size threshold in bytes for force-flush (default: 256000)
+ */
+export declare const genCloudwatchOutlet: ({ region: regionOverride, logGroup, logStream, skipLogGroupCreation, flushInterval, maxBufferSize, }?: {
+    region?: string;
+    logGroup?: string;
+    logStream?: string;
+    skipLogGroupCreation?: boolean;
+    flushInterval?: number;
+    maxBufferSize?: number;
+}) => LogOutlet;

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

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genCloudwatchOutlet = void 0;
+const client_cloudwatch_logs_1 = require("@aws-sdk/client-cloudwatch-logs");
+const asCloudWatchBatches_1 = require("./asCloudWatchBatches");
+const asCloudWatchLogEvents_1 = require("./asCloudWatchLogEvents");
+const asDefaultLogStreamName_1 = require("./asDefaultLogStreamName");
+const asLambdaStyleLogGroupName_1 = require("./asLambdaStyleLogGroupName");
+const assertAwsCredentialsPresent_1 = require("./assertAwsCredentialsPresent");
+const computeLogEventSize_1 = require("./computeLogEventSize");
+const drainBuffer_1 = require("./drainBuffer");
+/**
+ * .what = generates a CloudWatch outlet for log events
+ * .why = enables log events to flow to CloudWatch in environments without automatic collection
+ *
+ * .note = explicit opt-in: add this outlet only when automatic log collection is absent.
+ *         AWS Lambda and CloudWatch Agent environments auto-collect console.log output.
+ *         in those environments, omit this outlet to avoid duplicate logs.
+ *
+ * @param region - AWS region (required: from option or AWS_REGION/AWS_DEFAULT_REGION env)
+ * @param logGroup - CloudWatch log group name (default: /aws/lambda/{service}-{env})
+ * @param logStream - CloudWatch log stream name (default: Lambda-style YYYY/MM/DD/[$LATEST]uuid)
+ * @param skipLogGroupCreation - skip log group findsert (default: false)
+ * @param flushInterval - auto-flush interval in ms (default: 5000)
+ * @param maxBufferSize - buffer size threshold in bytes for force-flush (default: 256000)
+ */
+const genCloudwatchOutlet = ({ region: regionOverride, logGroup, logStream, skipLogGroupCreation, flushInterval, maxBufferSize, } = {}) => {
+    // validate AWS credentials are present (fail-fast)
+    (0, assertAwsCredentialsPresent_1.assertAwsCredentialsPresent)();
+    // derive region (explicit > env > fail-fast)
+    const region = regionOverride ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+    if (!region) {
+        throw new Error('CloudWatch outlet requires AWS region. Set AWS_REGION env var or pass region option.');
+    }
+    // derive defaults
+    const logGroupName = logGroup ?? (0, asLambdaStyleLogGroupName_1.asLambdaStyleLogGroupName)();
+    const logStreamName = logStream ?? (0, asDefaultLogStreamName_1.asDefaultLogStreamName)();
+    // create client
+    const client = new client_cloudwatch_logs_1.CloudWatchLogsClient({ region });
+    // buffer for events
+    const buffer = [];
+    let bufferSize = 0; // track size incrementally for O(1) checks
+    let initialized = false;
+    let flushPromise = null;
+    // setup auto-flush with explicit crash on error
+    const intervalMs = flushInterval ?? 5000; // 5s default for faster emission
+    const bufferLimit = maxBufferSize ?? 256000; // 256KB default for frequent flushes
+    const flushTimer = setInterval(() => {
+        flush().catch((error) => {
+            console.error('CloudWatch flush failed:', error);
+            process.exit(1);
+        });
+    }, intervalMs);
+    flushTimer.unref(); // allow process to exit despite timer
+    // register process exit hooks (beforeExit keeps event loop alive for promises)
+    const handleExitFlush = () => {
+        flush()
+            .catch((error) => {
+            console.error('CloudWatch flush failed during exit:', error);
+        })
+            .finally(() => {
+            close();
+        });
+    };
+    process.once('beforeExit', handleExitFlush);
+    // signal handlers: flush then exit (promise chain keeps event loop alive)
+    let exitInProgress = false;
+    const handleSignalExit = (exitCode) => {
+        if (exitInProgress)
+            return;
+        exitInProgress = true;
+        flush()
+            .catch((error) => {
+            console.error('CloudWatch flush failed during signal exit:', error);
+        })
+            .finally(() => {
+            close();
+            process.exit(exitCode);
+        });
+    };
+    const handleSigterm = () => handleSignalExit(143); // 128 + 15 (SIGTERM)
+    const handleSigint = () => handleSignalExit(130); // 128 + 2 (SIGINT)
+    process.once('SIGTERM', handleSigterm);
+    process.once('SIGINT', handleSigint);
+    /**
+     * .what = close the outlet and release resources
+     * .why = cleans up timers and process listeners to prevent leaks in tests
+     */
+    const close = () => {
+        clearInterval(flushTimer);
+        process.removeListener('beforeExit', handleExitFlush);
+        process.removeListener('SIGTERM', handleSigterm);
+        process.removeListener('SIGINT', handleSigint);
+    };
+    /**
+     * .what = findsert log group
+     * .why = idempotent creation via ResourceAlreadyExistsException
+     */
+    const findsertLogGroup = async () => {
+        try {
+            await client.send(new client_cloudwatch_logs_1.CreateLogGroupCommand({ logGroupName }));
+        }
+        catch (error) {
+            if (error instanceof client_cloudwatch_logs_1.ResourceAlreadyExistsException)
+                return;
+            throw error;
+        }
+    };
+    /**
+     * .what = findsert log stream
+     * .why = idempotent creation via ResourceAlreadyExistsException
+     */
+    const findsertLogStream = async () => {
+        try {
+            await client.send(new client_cloudwatch_logs_1.CreateLogStreamCommand({ logGroupName, logStreamName }));
+        }
+        catch (error) {
+            if (error instanceof client_cloudwatch_logs_1.ResourceAlreadyExistsException)
+                return;
+            throw error;
+        }
+    };
+    /**
+     * .what = initialize log group and stream
+     * .why = lazy initialization on first flush
+     */
+    const init = async () => {
+        if (initialized)
+            return;
+        if (!skipLogGroupCreation)
+            await findsertLogGroup();
+        await findsertLogStream();
+        initialized = true;
+    };
+    /**
+     * .what = flush buffered events to CloudWatch
+     * .why = batch send for efficiency (max 1MB, 10k events per CloudWatch limits)
+     *
+     * .invariant = single-flush-at-a-time via flushPromise
+     *   - concurrent flush() calls wait on extant flushPromise
+     *   - after wait, recheck buffer for events added mid-flush
+     *   - recursive call handles events that arrived while awaited
+     *   - prevents concurrent PutLogEvents calls (CloudWatch sequence token issues)
+     */
+    const flush = async () => {
+        // if no events, skip
+        if (buffer.length === 0)
+            return;
+        // if flush in progress, wait then recheck for new events
+        if (flushPromise) {
+            await flushPromise;
+            if (buffer.length > 0)
+                return flush(); // recheck for events added while wait
+            return;
+        }
+        // start flush
+        flushPromise = (async () => {
+            // extract events from buffer (restore on failure)
+            const events = (0, drainBuffer_1.drainBuffer)(buffer);
+            const eventsSizeSnapshot = bufferSize;
+            bufferSize = 0;
+            try {
+                await init();
+                // split into CloudWatch-compliant batches (max 1MB, 10k events each)
+                const batches = (0, asCloudWatchBatches_1.asCloudWatchBatches)(events);
+                for (const batch of batches) {
+                    await client.send(new client_cloudwatch_logs_1.PutLogEventsCommand({
+                        logGroupName,
+                        logStreamName,
+                        logEvents: (0, asCloudWatchLogEvents_1.asCloudWatchLogEvents)(batch),
+                    }));
+                }
+            }
+            catch (error) {
+                // restore events to buffer on failure (prepend to preserve order)
+                buffer.unshift(...events);
+                bufferSize += eventsSizeSnapshot;
+                throw error;
+            }
+            finally {
+                flushPromise = null;
+            }
+        })();
+        await flushPromise;
+    };
+    return {
+        send: (event) => {
+            // track size incrementally (O(1) vs O(n) for full buffer stringify)
+            const eventSize = (0, computeLogEventSize_1.computeLogEventSize)(event);
+            bufferSize += eventSize;
+            buffer.push(event);
+            // force-flush if buffer exceeds size limit (explicit crash on error)
+            if (bufferSize > bufferLimit) {
+                flush().catch((error) => {
+                    console.error('CloudWatch flush failed:', error);
+                    process.exit(1);
+                });
+            }
+        },
+        flush,
+        close,
+    };
+};
+exports.genCloudwatchOutlet = genCloudwatchOutlet;
+//# sourceMappingURL=genCloudwatchOutlet.js.map

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

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

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 export { LogLevel } from './domain.objects/constants';
+export type { LogEvent, LogOutlet } from './domain.objects/LogOutlet';
 export type { ContextLogTrail, HasContextLogTrail, LogTrail, } from './domain.objects/LogTrail';
 export { genContextLogTrail } from './domain.operations/genContextLogTrail';
 export type { LogMethod } from './domain.operations/generateLogMethod';
 export type { LogMethods } from './domain.operations/genLogMethods';
 export { genLogMethods } from './domain.operations/genLogMethods';
+export { asDefaultLogStreamName } from './domain.operations/outlets/cloudwatch/asDefaultLogStreamName';
+export { asLambdaStyleLogGroupName } from './domain.operations/outlets/cloudwatch/asLambdaStyleLogGroupName';
+export { genCloudwatchOutlet } from './domain.operations/outlets/cloudwatch/genCloudwatchOutlet';
 export { withLogTrail } from './domain.operations/withLogTrail';

package/dist/index.js

@@ -1,12 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withLogTrail = exports.genLogMethods = exports.genContextLogTrail = exports.LogLevel = void 0;
+exports.withLogTrail = exports.genCloudwatchOutlet = exports.asLambdaStyleLogGroupName = exports.asDefaultLogStreamName = exports.genLogMethods = exports.genContextLogTrail = exports.LogLevel = void 0;
 var constants_1 = require("./domain.objects/constants");
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return constants_1.LogLevel; } });
 var genContextLogTrail_1 = require("./domain.operations/genContextLogTrail");
 Object.defineProperty(exports, "genContextLogTrail", { enumerable: true, get: function () { return genContextLogTrail_1.genContextLogTrail; } });
 var genLogMethods_1 = require("./domain.operations/genLogMethods");
 Object.defineProperty(exports, "genLogMethods", { enumerable: true, get: function () { return genLogMethods_1.genLogMethods; } });
+var asDefaultLogStreamName_1 = require("./domain.operations/outlets/cloudwatch/asDefaultLogStreamName");
+Object.defineProperty(exports, "asDefaultLogStreamName", { enumerable: true, get: function () { return asDefaultLogStreamName_1.asDefaultLogStreamName; } });
+var asLambdaStyleLogGroupName_1 = require("./domain.operations/outlets/cloudwatch/asLambdaStyleLogGroupName");
+Object.defineProperty(exports, "asLambdaStyleLogGroupName", { enumerable: true, get: function () { return asLambdaStyleLogGroupName_1.asLambdaStyleLogGroupName; } });
+var genCloudwatchOutlet_1 = require("./domain.operations/outlets/cloudwatch/genCloudwatchOutlet");
+Object.defineProperty(exports, "genCloudwatchOutlet", { enumerable: true, get: function () { return genCloudwatchOutlet_1.genCloudwatchOutlet; } });
 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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,wDAAsD;AAA7C,qGAAA,QAAQ,OAAA;AAMjB,6EAA4E;AAAnE,wHAAA,kBAAkB,OAAA;AAG3B,mEAAkE;AAAzD,8GAAA,aAAa,OAAA;AACtB,iEAAgE;AAAvD,4GAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,wDAAsD;AAA7C,qGAAA,QAAQ,OAAA;AAOjB,6EAA4E;AAAnE,wHAAA,kBAAkB,OAAA;AAG3B,mEAAkE;AAAzD,8GAAA,aAAa,OAAA;AACtB,wGAAuG;AAA9F,gIAAA,sBAAsB,OAAA;AAC/B,8GAA6G;AAApG,sIAAA,yBAAyB,OAAA;AAClC,kGAAiG;AAAxF,0HAAA,mBAAmB,OAAA;AAC5B,iEAAgE;AAAvD,4GAAA,YAAY,OAAA"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "sdk-logs",
   "author": "ehmpathy",
   "description": "a simple and opinionated logging library. plays well with aws lambda + cloudwatch.",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "repository": "ehmpathy/sdk-logs",
   "homepage": "https://github.com/ehmpathy/sdk-logs",
   "keywords": [
@@ -57,6 +57,7 @@
     "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi"
   },
   "dependencies": {
+    "@aws-sdk/client-cloudwatch-logs": "3.1040.0",
     "@ehmpathy/error-fns": "^1.3.7",
     "domain-glossary-procedure": "^1.0.0",
     "domain-objects": "0.31.10",
@@ -83,12 +84,12 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.41.4",
+    "rhachet": "1.41.7",
     "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-bhuild": "0.21.7",
+    "rhachet-roles-ehmpathy": "1.35.5",
     "rhachet-roles-rhachet": "^0.1.7",
     "test-fns": "1.4.2",
     "tsc-alias": "1.8.10",