Use @internal to improve suggestions

TypeScript's autocomplete will suggest pretty much any symbol that
is transitively exported in your package. This includes a lot of
internal functions and objects that exist for no-op or testing
purposes and should not be used by customers.

Use the `@internal` JSDoc annotation and the `stripInternal` option
in `tsconfig.json` to avoid internal functions from being declared
in the `.d.ts` files, preventing TypeScript's autocomplete from
suggesting them.

Added on top of the changes in #1123, which should be merged first.

src/check_in/event.ts

@@ -1,8 +1,11 @@
 import type { Cron } from "./cron"
 
+/** @internal */
 export type EventKind = "start" | "finish"
+/** @internal */
 export type EventCheckInType = "cron" | "heartbeat"
 
+/** @internal */
 export class Event {
   identifier: string
   digest?: string

src/check_in/heartbeat.ts

@@ -2,16 +2,19 @@ import { stubbable } from "../utils"
 
 const HEARTBEAT_INTERVAL_MILLISECONDS = 30_000
 
+/** @internal */
 export const heartbeatInterval = stubbable(
   () => HEARTBEAT_INTERVAL_MILLISECONDS
 )
 
 let continuousHeartbeats: NodeJS.Timeout[] = []
 
+/** @internal */
 export function addContinuousHeartbeat(interval: NodeJS.Timeout) {
   continuousHeartbeats.push(interval)
 }
 
+/** @internal */
 export function killContinuousHeartbeats() {
   continuousHeartbeats.forEach(clearInterval)
   continuousHeartbeats = []

src/check_in/scheduler.ts

@@ -6,6 +6,7 @@ import { ndjsonStringify, stubbable } from "../utils"
 const INITIAL_DEBOUNCE_MILLISECONDS = 100
 const BETWEEN_TRANSMISSIONS_DEBOUNCE_MILLISECONDS = 10_000
 
+/** @internal */
 export const debounceTime = stubbable(
   (lastTransmission: number | undefined): number => {
     if (lastTransmission === undefined) {
@@ -33,6 +34,7 @@ class PendingPromiseSet<T> extends Set<Promise<T>> {
   }
 }
 
+/** @internal */
 export class Scheduler {
   pendingTransmissions: PendingPromiseSet<any> = new PendingPromiseSet()
   events: Event[] = []
@@ -146,8 +148,10 @@ export class Scheduler {
   }
 }
 
+/** @internal */
 export let scheduler = new Scheduler()
 
+/** @internal */
 export async function resetScheduler() {
   await scheduler.shutdown()
   scheduler = new Scheduler()

src/config/configmap.ts

@@ -1,5 +1,6 @@
 import type { AppsignalOptions } from "./options"
 
+/** @internal */
 export const ENV_TO_KEY_MAPPING = {
   APPSIGNAL_ACTIVE: "active",
   APPSIGNAL_APP_ENV: "environment",
@@ -42,6 +43,7 @@ export const ENV_TO_KEY_MAPPING = {
   APP_REVISION: "revision"
 } satisfies Record<string, keyof AppsignalOptions>
 
+/** @internal */
 export const PRIVATE_ENV_MAPPING: Record<string, keyof AppsignalOptions> = {
   _APPSIGNAL_ACTIVE: "active",
   _APPSIGNAL_APP_ENV: "environment",
@@ -79,6 +81,7 @@ export const PRIVATE_ENV_MAPPING: Record<string, keyof AppsignalOptions> = {
   _APP_REVISION: "revision"
 }
 
+/** @internal */
 export const JS_TO_RUBY_MAPPING: Record<keyof AppsignalOptions, string> = {
   active: "active",
   bindAddress: "bind_address",
@@ -121,6 +124,7 @@ export const JS_TO_RUBY_MAPPING: Record<keyof AppsignalOptions, string> = {
   workingDirectoryPath: "working_directory_path"
 }
 
+/** @internal */
 export const BOOL_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_ACTIVE",
   "APPSIGNAL_ENABLE_HOST_METRICS",
@@ -135,6 +139,7 @@ export const BOOL_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_SEND_SESSION_DATA"
 ]
 
+/** @internal */
 export const STRING_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_APP_ENV",
   "APPSIGNAL_APP_NAME",
@@ -156,6 +161,7 @@ export const STRING_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APP_REVISION"
 ]
 
+/** @internal */
 export const LIST_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_DNS_SERVERS",
   "APPSIGNAL_FILTER_PARAMETERS",
@@ -167,10 +173,12 @@ export const LIST_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_REQUEST_HEADERS"
 ]
 
+/** @internal */
 export const LIST_OR_BOOL_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_DISABLE_DEFAULT_INSTRUMENTATIONS"
 ]
 
+/** @internal */
 export const FLOAT_KEYS: (keyof typeof ENV_TO_KEY_MAPPING)[] = [
   "APPSIGNAL_CPU_COUNT"
 ]

src/extension.ts

@@ -6,6 +6,7 @@ import { Data } from "./internal/data"
  * The public interface for the extension.
  *
  * @class
+ * @internal
  */
 export class Extension {
   static isLoaded = extensionLoaded

src/extension_wrapper.ts

@@ -72,4 +72,5 @@ try {
   } as ExtensionWrapper
 }
 
+/** @internal */
 export = mod

src/heartbeat.ts

@@ -32,6 +32,7 @@ function consoleAndLoggerWarn(message: string) {
   Client.internalLogger.warn(message)
 }
 
+/** @internal */
 export const heartbeatClassWarnOnce = once(
   consoleAndLoggerWarn,
   "The class `Heartbeat` has been deprecated. " +
@@ -40,6 +41,7 @@ export const heartbeatClassWarnOnce = once(
     "in order to remove this message."
 )
 
+/** @internal */
 export const heartbeatHelperWarnOnce = once(
   consoleAndLoggerWarn,
   "The helper `heartbeat` has been deprecated. " +
@@ -48,6 +50,7 @@ export const heartbeatHelperWarnOnce = once(
     "in order to remove this message."
 )
 
+/** @deprecated Use `checkIn.cron` (`import { checkIn } from "@appsignal/nodejs"`) instead. */
 export function heartbeat(name: string): void
 export function heartbeat<T>(name: string, fn: () => T): T
 export function heartbeat<T>(name: string, fn?: () => T): T | undefined {
@@ -56,6 +59,7 @@ export function heartbeat<T>(name: string, fn?: () => T): T | undefined {
   return (cron as (name: string, fn?: () => T) => T | undefined)(name, fn)
 }
 
+/** @deprecated Use `checkIn.Cron` (`import { checkIn } from "@appsignal/nodejs"`) instead. */
 export const Heartbeat = new Proxy(Cron, {
   construct(target, args: ConstructorParameters<typeof Cron>) {
     heartbeatClassWarnOnce()

src/internal/data.ts

@@ -1,5 +1,6 @@
 import { datamap, dataarray } from "../extension_wrapper"
 
+/** @internal */
 export class Data {
   public static generate(data: Array<any> | Record<string, any>) {
     if (data.constructor.name === "Object") {

src/internal_logger.ts

@@ -1,6 +1,7 @@
 import winston from "winston"
 const { combine, timestamp, printf } = winston.format
 
+/** @internal */
 export interface InternalLogger {
   error(message: string): void
   warn(message: string): void
@@ -9,6 +10,7 @@ export interface InternalLogger {
   trace(message: string): void
 }
 
+/** @internal */
 export class BaseInternalLogger {
   type: string
   level: string

src/noops/internal_logger.ts

@@ -1,5 +1,6 @@
 import { InternalLogger } from "../internal_logger"
 
+/** @internal */
 export class NoopInternalLogger implements InternalLogger {
   error(_message: string) {
     // noop
@@ -18,4 +19,5 @@ export class NoopInternalLogger implements InternalLogger {
   }
 }
 
+/** @internal */
 export const noopInternalLogger = new NoopInternalLogger()

src/noops/logger.ts

@@ -1,5 +1,6 @@
 import { Logger, LoggerAttributes } from "../logger"
 
+/** @internal */
 export class NoopLogger implements Logger {
   trace(_message: string, _attributes?: LoggerAttributes) {
     // noop
@@ -21,4 +22,5 @@ export class NoopLogger implements Logger {
   }
 }
 
+/** @internal */
 export const noopLogger = new NoopLogger()

src/noops/metrics.ts

@@ -1,6 +1,7 @@
 import { Metrics } from "../metrics"
 import { Probes } from "../probes"
 
+/** @internal */
 export class NoopMetrics extends Metrics {
   #probes = new Probes({ run: false })
 

src/probes/index.ts

@@ -43,13 +43,15 @@ export class Probes {
   }
 }
 
+/** @internal */
 type ProbeRunner = {
   readonly count: number
   register(name: string, fn: () => void): void
   unregister(name: string): void
   clear(): void
 }
 
+/** @internal */
 class BaseProbeRunner extends EventEmitter implements ProbeRunner {
   #timers = new Map<string, NodeJS.Timeout>()
 
@@ -98,6 +100,7 @@ class BaseProbeRunner extends EventEmitter implements ProbeRunner {
   }
 }
 
+/** @internal */
 class NoopProbeRunner implements ProbeRunner {
   readonly count: number = 0
 

src/probes/v8/index.ts

@@ -3,8 +3,10 @@ import v8 from "v8"
 import os from "os"
 import { Client } from "../../client"
 
+/** @internal */
 export const PROBE_NAME = "v8_stats"
 
+/** @internal */
 export function init(meter: Metrics) {
   function setGauge(key: string, value: number) {
     const hostname = Client.config.data.hostname || os.hostname()

src/span_processor.ts

@@ -68,6 +68,7 @@ export class SpanProcessor implements OpenTelemetrySpanProcessor {
   }
 }
 
+/** @internal */
 export class TestModeSpanProcessor implements OpenTelemetrySpanProcessor {
   #filePath: string
 

src/transmitter.ts

@@ -36,6 +36,7 @@ class MaxRedirectsError extends Error {
   }
 }
 
+/** @internal */
 export class Transmitter {
   #config: Configuration
   #url: string

src/utils.ts

@@ -10,6 +10,7 @@ const SECOND_TO_NANOSECONDS = Math.pow(10, NANOSECOND_DIGITS)
  * seconds and nanoseconds.
  *
  * @function
+ * @internal
  */
 export function getAgentTimestamps(timestamp: number) {
   const sec = Math.round(timestamp / 1000)
@@ -21,6 +22,7 @@ export function getAgentTimestamps(timestamp: number) {
 
 /**
  * Checks if the given path is writable by the process.
+ * @internal
  */
 export function isWritable(path: string) {
   try {
@@ -35,6 +37,7 @@ export function isWritable(path: string) {
  * Returns a high-resolution time tuple containing the current time in seconds and nanoseconds.
  *
  * @function
+ * @internal
  */
 export function hrTime(performance = perf_hooks.performance): {
   sec: number
@@ -56,23 +59,28 @@ function numberToHrtime(epochMillis: number) {
   return [seconds, nanoseconds]
 }
 
+/** @internal */
 export function processGetuid() {
   return (process.getuid ?? (() => -1))()
 }
 
+/** @internal */
 export function ndjsonStringify(elements: any[]): string {
   return elements.map(element => JSON.stringify(element)).join("\n")
 }
 
+/** @internal */
 export function ndjsonParse(data: string): any[] {
   return data.split("\n").map(line => JSON.parse(line))
 }
 
+/** @internal */
 export type Stub<F extends (...args: any[]) => any> = F & {
   set: (fn: F) => void
   reset: () => void
 }
 
+/** @internal */
 export function stubbable<T extends any[], U>(
   original: (...args: T) => U
 ): Stub<(...args: T) => U> {

tsconfig.json

@@ -6,9 +6,7 @@
   ],
   "compilerOptions": {
     "rootDir": "./src",
-    "outDir": "./dist"
-  },
-  "compilerOptions": {
+    "outDir": "./dist",
     /* Basic Options */
     // "incremental": true,                   /* Enable incremental compilation */
     "target": "es2018",                       /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */
@@ -68,5 +66,6 @@
     /* Experimental Options */
     // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
     // "emitDecoratorMetadata": true          /* Enables experimental support for emitting type metadata for decorators. */
+    "stripInternal": true,
   }
 }