[WIP] Additional types

Author: JamieMagee

lib/entityCoordinates.d.ts

@@ -11,7 +11,7 @@ export interface EntityCoordinatesSpec {
 }
 
 /** Represents entity coordinates for a software component */
-declare class EntityCoordinates {
+export declare class EntityCoordinates {
   /** The type of the entity (e.g., 'npm', 'maven', 'git') */
   type?: string
 

lib/entityCoordinates.js

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft Corporation and others. Licensed under the MIT license.
 // SPDX-License-Identifier: MIT
 
-/** @typedef {import('./entityCoordinates')} EntityCoordinates */
 /** @typedef {import('./entityCoordinates').EntityCoordinatesSpec} EntityCoordinatesSpec */
 
 /** Property flag for namespace normalization */
@@ -42,11 +41,6 @@ class EntityCoordinates {
    *
    * @param {EntityCoordinatesSpec | EntityCoordinates | null | undefined} spec - The specification object or existing
    *   EntityCoordinates instance
-   * @param {string} [spec.type] - The type of the entity
-   * @param {string} [spec.provider] - The provider of the entity
-   * @param {string} [spec.namespace] - The namespace of the entity
-   * @param {string} [spec.name] - The name of the entity
-   * @param {string} [spec.revision] - The revision/version of the entity
    * @returns {EntityCoordinates | null} New EntityCoordinates instance or null if spec is falsy
    */
   static fromObject(spec) {
@@ -78,7 +72,7 @@ class EntityCoordinates {
   static fromUrn(urn) {
     if (!urn) return null
     // eslint-disable-next-line no-unused-vars
-    const [scheme, type, provider, namespace, name, revToken, revision] = urn.split(':')
+    const [, type, provider, namespace, name, , revision] = urn.split(':')
     return new EntityCoordinates(type, provider, namespace, name, revision)
   }
 

lib/mockInsights.d.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation and others. Licensed under the MIT license.
+// SPDX-License-Identifier: MIT
+
+import { TelemetryClient, Contracts } from 'applicationinsights'
+
+/** Mock implementation of Application Insights client for testing and development */
+declare class MockInsights {
+  /** The underlying Application Insights client, if any */
+  client: TelemetryClient | null
+
+  /**
+   * Creates a new MockInsights instance
+   *
+   * @param client - Optional Application Insights client to wrap
+   */
+  constructor(client?: TelemetryClient | null)
+
+  /**
+   * Sets up the mock insights client or configures Application Insights
+   *
+   * @param key - Application Insights instrumentation key or 'mock' for testing
+   * @param echo - Whether to echo telemetry to both mock and real client
+   */
+  static setup(key?: string | null, echo?: boolean): void
+
+  /**
+   * Tracks an exception
+   *
+   * @param exceptionTelemetry - The exception telemetry data
+   */
+  trackException(exceptionTelemetry: Contracts.ExceptionTelemetry): void
+
+  /**
+   * Tracks a trace message
+   *
+   * @param traceTelemetry - The trace telemetry data
+   */
+  trackTrace(traceTelemetry: Contracts.TraceTelemetry): void
+}
+
+export = MockInsights

lib/mockInsights.js

@@ -3,34 +3,79 @@
 
 const appInsights = require('applicationinsights')
 
+/**
+ * @typedef {import('applicationinsights').TelemetryClient} TelemetryClient
+ *
+ * @typedef {import('applicationinsights').Contracts.ExceptionTelemetry} ExceptionTelemetry
+ *
+ * @typedef {import('applicationinsights').Contracts.TraceTelemetry} TraceTelemetry
+ */
+
+/**
+ * Mock implementation of Application Insights client for testing and development. This class provides a lightweight
+ * alternative to the full Application Insights client, allowing for console-based logging of telemetry data during
+ * development and testing.
+ */
 class MockInsights {
+  /**
+   * Creates a new MockInsights instance
+   *
+   * @param {TelemetryClient | null} [client=null] - Optional Application Insights client to wrap. Default is `null`
+   */
   constructor(client = null) {
+    /**
+     * The underlying Application Insights client, if any
+     *
+     * @type {TelemetryClient | null}
+     */
     this.client = client
   }
 
+  /**
+   * Sets up the mock insights client or configures Application Insights. This method configures the global Application
+   * Insights client based on the provided key.
+   *
+   * @param {string | null} [key=null] - Application Insights instrumentation key or 'mock' for testing. Default is
+   *   `null`
+   * @param {boolean} [echo=false] - Whether to echo telemetry to both mock and real client. Default is `false`
+   * @returns {void}
+   */
   static setup(key = null, echo = false) {
     // exit if we we are already setup
     if (appInsights.defaultClient instanceof MockInsights) return
-    if (!key || key === 'mock') appInsights.defaultClient = new MockInsights()
+    if (!key || key === 'mock') appInsights.defaultClient = /** @type {any} */ (new MockInsights())
     else {
       appInsights.setup(key).setAutoCollectPerformance(false).setAutoCollectDependencies(true).start()
-      if (echo) appInsights.defaultClient = new MockInsights(appInsights.defaultClient)
+      if (echo) appInsights.defaultClient = /** @type {any} */ (new MockInsights(appInsights.defaultClient))
     }
   }
 
+  /**
+   * Tracks an exception by logging it to the console and optionally forwarding to Application Insights.
+   *
+   * @param {ExceptionTelemetry} exceptionTelemetry - The exception telemetry data
+   * @returns {void}
+   */
   trackException(exceptionTelemetry) {
     console.log('Exception: ')
     console.dir(exceptionTelemetry.exception)
-    if (this.client) this.client.trackException(exceptionTelemetry)
+    if (this.client) this.client.trackException(/** @type {ExceptionTelemetry} */ (exceptionTelemetry))
   }
 
+  /**
+   * Tracks a trace message by logging it to the console and optionally forwarding to Application Insights. The trace is
+   * formatted with severity level indicators for easy console reading.
+   *
+   * @param {TraceTelemetry} traceTelemetry - The trace telemetry data
+   * @returns {void}
+   */
   trackTrace(traceTelemetry) {
     // const severities = ['Verbose', 'Info', 'Warning', 'Error', 'Critical'];
     const severities = ['V', 'I', 'W', 'E', 'C']
     const hasProperties = traceTelemetry.properties && Object.keys(traceTelemetry.properties).length > 0
     const propertyString = hasProperties ? `${JSON.stringify(traceTelemetry.properties)}` : ''
     console.log(`[${severities[traceTelemetry.severity]}] ${traceTelemetry.message}${propertyString}`)
-    if (this.client) this.client.trackTrace(traceTelemetry)
+    if (this.client) this.client.trackTrace(/** @type {TraceTelemetry} */ (traceTelemetry))
   }
 }
 module.exports = MockInsights

package-lock.json

@@ -76,13 +76,17 @@
   },
   "devDependencies": {
     "@tsconfig/node18": "18.2.4",
+    "@tsconfig/strictest": "2.0.5",
     "@types/chai": "4.3.3",
     "@types/deep-equal-in-any-order": "1.0.4",
     "@types/express": "4.17.17",
     "@types/lodash": "4.17.16",
+    "@types/memory-cache": "0.2.6",
     "@types/mocha": "8.2.3",
     "@types/node": "18.15.11",
+    "@types/pako": "1.0.1",
     "@types/sinon": "5.0.7",
+    "@types/winston": "2.3.9",
     "chai": "^4.1.2",
     "chai-as-promised": "^7.1.1",
     "deep-equal-in-any-order": "^1.0.10",

package.json

@@ -0,0 +1,50 @@
+import { Logger } from '../../providers/logging'
+
+/** Base configuration options common to all cache implementations */
+export interface BaseCacheOptions {
+  /** Optional logger instance for logging cache operations */
+  logger?: Logger
+  /** Default time-to-live in seconds for cached items */
+  defaultTtlSeconds?: number
+}
+
+/** Generic cache interface that all cache implementations should follow */
+export interface CacheInterface {
+  /**
+   * Initializes the cache
+   *
+   * @returns Promise that resolves when initialization is complete
+   */
+  initialize(): Promise<void>
+
+  /**
+   * Cleanup method called when cache is no longer needed
+   *
+   * @returns Promise that resolves when cleanup is complete
+   */
+  done(): Promise<void>
+
+  /**
+   * Retrieves an item from the cache
+   *
+   * @param item - The key of the item to retrieve
+   * @returns The cached value or null if not found or expired
+   */
+  get(item: string): Promise<any> | any
+
+  /**
+   * Stores an item in the cache
+   *
+   * @param item - The key to store the value under
+   * @param value - The value to cache
+   * @param ttlSeconds - Time-to-live in seconds (optional)
+   */
+  set(item: string, value: any, ttlSeconds?: number): Promise<void> | void
+
+  /**
+   * Removes an item from the cache
+   *
+   * @param item - The key of the item to remove
+   */
+  delete(item: string): Promise<void> | void
+}

providers/caching/index.d.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Amazon.com, Inc. or its affiliates and others. Licensed under the MIT license.
+// SPDX-License-Identifier: MIT
+
+import { BaseCacheOptions, CacheInterface } from '.'
+
+/** Configuration options for MemoryCache */
+export interface MemoryCacheOptions extends BaseCacheOptions {}
+
+/** In-memory cache implementation */
+declare class MemoryCache implements CacheInterface {
+  /** The underlying memory cache instance */
+  private cache: any
+
+  /** Default TTL in seconds for cached items */
+  private defaultTtlSeconds: number
+
+  /**
+   * Creates a new MemoryCache instance
+   *
+   * @param options - Configuration options for the cache
+   */
+  constructor(options: MemoryCacheOptions)
+
+  /**
+   * Initializes the cache (async for interface compatibility)
+   *
+   * @returns Promise that resolves when initialization is complete
+   */
+  initialize(): Promise<void>
+
+  /**
+   * Cleanup method called when cache is no longer needed
+   *
+   * @returns Promise that resolves when cleanup is complete
+   */
+  done(): Promise<void>
+
+  /**
+   * Retrieves an item from the cache
+   *
+   * @param item - The key of the item to retrieve
+   * @returns The cached value or null if not found or expired
+   */
+  get(item: string): any
+
+  /**
+   * Stores an item in the cache
+   *
+   * @param item - The key to store the value under
+   * @param value - The value to cache
+   * @param ttlSeconds - Time-to-live in seconds (optional, uses default if not provided)
+   */
+  set(item: string, value: any, ttlSeconds?: number): void
+
+  /**
+   * Removes an item from the cache
+   *
+   * @param item - The key of the item to remove
+   */
+  delete(item: string): void
+}
+
+/**
+ * Factory function to create a new MemoryCache instance
+ *
+ * @param options - Configuration options for the cache
+ * @returns A new MemoryCache instance
+ */
+declare function createMemoryCache(options?: MemoryCacheOptions): MemoryCache
+
+export default createMemoryCache
+export { MemoryCache }