improv: types

Author: dreamorosi

packages/logger/src/Logger.ts

@@ -26,6 +26,7 @@ import type {
   LoggerInterface,
 } from './types/Logger.js';
 import type {
+  LogKeys,
   PowertoolsLogData,
   UnformattedAttributes,
 } from './types/logKeys.js';
@@ -134,7 +135,7 @@ class Logger extends Utility implements LoggerInterface {
   /**
    * Temporary log attributes that can be appended with `appendKeys()` method.
    */
-  private temporaryLogAttributes: LogAttributes = {};
+  private temporaryLogAttributes: LogKeys = {};
   /**
    * Buffer used to store logs until the logger is initialized.
    *
@@ -210,7 +211,7 @@ class Logger extends Utility implements LoggerInterface {
   /**
    * @deprecated This method is deprecated and will be removed in the future major versions, please use {@link appendPersistentKeys() `appendPersistentKeys()`} instead.
    */
-  public addPersistentLogAttributes(attributes: LogAttributes): void {
+  public addPersistentLogAttributes(attributes: LogKeys): void {
     this.appendPersistentKeys(attributes);
   }
 
@@ -222,7 +223,7 @@ class Logger extends Utility implements LoggerInterface {
    *
    * @param attributes - The attributes to add to all log items.
    */
-  public appendKeys(attributes: LogAttributes): void {
+  public appendKeys(attributes: LogKeys): void {
     this.#appendKeys(attributes, 'temp');
   }
 
@@ -234,7 +235,7 @@ class Logger extends Utility implements LoggerInterface {
    *
    * @param attributes - The attributes to add to all log items.
    */
-  public appendPersistentKeys(attributes: LogAttributes): void {
+  public appendPersistentKeys(attributes: LogKeys): void {
     this.#appendKeys(attributes, 'persistent');
   }
 
@@ -519,7 +520,7 @@ class Logger extends Utility implements LoggerInterface {
   }
 
   /**
-   * Remove all temporary log attributes added with `appendKeys()` method.
+   * Remove all temporary log attributes added with {@link appendKeys() `appendKeys()`} method.
    */
   public resetKeys(): void {
     for (const key of Object.keys(this.temporaryLogAttributes)) {
@@ -552,7 +553,7 @@ class Logger extends Utility implements LoggerInterface {
   /**
    * @deprecated This method is deprecated and will be removed in the future major versions, please use {@link appendPersistentKeys() `appendPersistentKeys()`} instead.
    */
-  public setPersistentLogAttributes(attributes: LogAttributes): void {
+  public setPersistentLogAttributes(attributes: LogKeys): void {
     this.persistentLogAttributes = attributes;
   }
 
@@ -664,7 +665,7 @@ class Logger extends Utility implements LoggerInterface {
    * @param attributes - The attributes to add to the log item.
    * @param type - The type of the attributes to add.
    */
-  #appendKeys(attributes: LogAttributes, type: 'temp' | 'persistent'): void {
+  #appendKeys(attributes: LogKeys, type: 'temp' | 'persistent'): void {
     for (const attributeKey of Object.keys(attributes)) {
       if (this.#checkReservedKeyAndWarn(attributeKey) === false) {
         this.#keys.set(attributeKey, type);

packages/logger/src/types/Logger.ts

@@ -8,6 +8,7 @@ import type {
   Environment,
   LogAttributes,
   LogAttributesWithMessage,
+  LogKeys,
 } from './logKeys.js';
 
 /**
@@ -187,8 +188,8 @@ type LogItemExtraInput = [Error | string] | LogAttributes[];
  */
 type LoggerInterface = {
   addContext(context: Context): void;
-  addPersistentLogAttributes(attributes?: LogAttributes): void;
-  appendKeys(attributes?: LogAttributes): void;
+  appendPersistentKeys(attributes?: LogKeys): void;
+  appendKeys(attributes?: LogKeys): void;
   createChild(options?: ConstructorOptions): LoggerInterface;
   critical(input: LogItemMessage, ...extraInput: LogItemExtraInput): void;
   debug(input: LogItemMessage, ...extraInput: LogItemExtraInput): void;

packages/logger/src/types/logKeys.ts

@@ -24,7 +24,26 @@ type LogAttributes = { [key: string]: unknown };
  * This is the most common log attribute object and it's used as first argument in the logger methods.
  */
 type LogAttributesWithMessage = LogAttributes & {
+  /**
+   * Your log message.
+   */
   message: string;
+  /**
+   * This key is generated by the logger and cannot be set manually.
+   */
+  level?: never;
+  /**
+   * This key is generated by the logger and cannot be set manually.
+   */
+  sampling_rate?: never;
+  /**
+   * This key is generated by the logger and cannot be set manually.
+   */
+  service?: never;
+  /**
+   * This key is generated by the logger and cannot be set manually.
+   */
+  timestamp?: never;
 };
 
 /**
@@ -217,7 +236,31 @@ type LogKey =
   | keyof PowertoolsLambdaContextKeys
   | AutocompletableString;
 
+type LogKeys = { [key: string]: unknown } & {
+  /**
+   * This key is passed when emitting a log message and cannot be set manually.
+   */
+  message?: never;
+  /**
+   * This key is generated by the logger and cannot be added to the logger.
+   */
+  level?: never;
+  /**
+   * This key is generated by the logger and cannot be added to the logger.
+   */
+  sampling_rate?: never;
+  /**
+   * This key is generated by the logger and cannot be added to the logger.
+   */
+  service?: never;
+  /**
+   * This key is generated by the logger and cannot be added to the logger.
+   */
+  timestamp?: never;
+};
+
 export type {
+  LogKeys,
   LogAttributes,
   LogAttributesWithMessage,
   Environment,

packages/logger/tests/unit/workingWithkeys.test.ts

@@ -627,6 +627,7 @@ describe('Working with keys', () => {
 
     // Act
     logger.appendKeys({
+      // @ts-expect-error - testing invalid key at runtime
       level: 'Hello, World!',
     });
     logger.info('foo');
@@ -652,6 +653,7 @@ describe('Working with keys', () => {
 
     // Act
     logger.appendPersistentKeys({
+      // @ts-expect-error - testing invalid key at runtime
       timestamp: 'Hello, World!',
     });
     logger.info('foo');
@@ -707,6 +709,7 @@ describe('Working with keys', () => {
     logger.info(
       {
         message: 'foo',
+        // @ts-expect-error - testing invalid key at runtime
         timestamp: 'Hello, World!',
       },
       {