JSPM

@datadog/js-core

0.0.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 567531
  • Score
    100M100P100Q170986F
  • License Apache-2.0

Package Exports

  • @datadog/js-core/monitor
  • @datadog/js-core/time
  • @datadog/js-core/util

Readme

@datadog/js-core

Runtime-agnostic core utilities shared across Datadog JavaScript SDKs.

Installation

npm install @datadog/js-core
# or
yarn add @datadog/js-core

API

The package exposes named sub-paths (e.g. @datadog/js-core/time). Import only what you need. There is no root entry point — always import from a sub-path.

Sub-paths are resolved via the exports field in package.json (for modern bundlers and native Node ESM/CJS) with a physical <name>/package.json fallback for legacy resolvers (webpack 4, etc.).

TypeScript users need "moduleResolution": "bundler", "node16", or "nodenext" in their tsconfig.json to resolve sub-path exports correctly.

@datadog/js-core/time

Time utilities that work in any JavaScript runtime.

import {
  dateNow,
  timeStampNow,
  relativeNow,
  clocksNow,
  clocksOrigin,
  elapsed,
  addDuration,
  toServerDuration,
  relativeToClocks,
  timeStampToClocks,
  toRelativeTime,
  toTimeStamp,
  getTimeOrigin,
  isRelativeTime,
  clockDrift,
  ONE_SECOND,
  ONE_MINUTE,
  ONE_HOUR,
  ONE_DAY,
  ONE_YEAR,
} from '@datadog/js-core/time'
import type { Duration, ServerDuration, TimeStamp, RelativeTime, ClocksState } from '@datadog/js-core/time'

Types

Export Description
ClocksState Pair of { relative: RelativeTime, timeStamp: TimeStamp }.
Duration Branded number — duration in ms.
RelativeTime Branded number — time relative to navigation/process start in ms (sourced from performance.now()).
ServerDuration Branded number — duration in ns (server intake format).
TimeStamp Branded number — Unix epoch timestamp in ms.

Constants

Export Value Description
ONE_DAY 86_400_000 One day in ms.
ONE_HOUR 3_600_000 One hour in ms.
ONE_MINUTE 60_000 One minute in ms.
ONE_SECOND 1000 One second in ms.
ONE_YEAR 31_536_000_000 One year in ms.

Functions

Export Description
addDuration(a, b) Adds two time values, preserving the branded type (TimeStamp, RelativeTime, or Duration).
clockDrift() Clock drift in ms between Date.now() and performance.now() relative to navigation start.
clocksNow() Current time as a ClocksState (both relative and absolute).
clocksOrigin() Origin clocks state: relative = 0, timeStamp = getTimeOrigin().
dateNow() Current Unix timestamp in ms. Prefer over Date.now() to guard against broken polyfills.
elapsed(start, end) Duration between two timestamps or relative times.
getTimeOrigin() Time origin as a TimeStamp (cached). Falls back to performance.timeOrigin when performance.timing is unavailable (Service Workers, Node.js).
isRelativeTime(time) Heuristic type guard: returns true if the value is likely a RelativeTime (< one year).
relativeNow() Current relative time in ms since navigation/process start (performance.now()).
relativeToClocks(relative) Converts a RelativeTime to a ClocksState with a drift-corrected TimeStamp.
timeStampNow() Current Unix timestamp as a TimeStamp.
timeStampToClocks(ts) Converts a TimeStamp to a ClocksState with its corresponding RelativeTime.
toRelativeTime(ts) Returns the RelativeTime for a given absolute TimeStamp.
toServerDuration(d) Converts a Duration (ms) to a ServerDuration (ns). Returns undefined if the input is undefined.
toTimeStamp(relative) Returns the absolute TimeStamp for a given RelativeTime.

@datadog/js-core/monitor

Error-monitoring utilities that wrap callbacks to catch, report, and suppress SDK-internal exceptions.

Each consumer creates its own isolated monitor via createMonitor(display, onMonitorErrorCollected), so error-collection state is not shared between SDKs. The display (from createDisplay in @datadog/js-core/util) controls the log prefix. Both arguments are required and fixed for the lifetime of the monitor. Caught errors are logged to the console via the given display, but only when debug mode is on (toggled globally via setDebugMode from @datadog/js-core/util).

import { createMonitor } from '@datadog/js-core/monitor'
import { createDisplay, setDebugMode } from '@datadog/js-core/util'

const display = createDisplay('Datadog Browser SDK:')
const { monitor, callMonitored, monitored, monitorError } = createMonitor(display, (error) => reportToTelemetry(error))

setDebugMode(true) // global: also log caught errors to the console

Functions

Export Description
createMonitor(display, onError) Creates an isolated monitor using the given Display for debug output and required error callback. Returns instance methods.

Monitor instance (returned by createMonitor)

Method Description
callMonitored(fn, context?, args?) Calls fn with error handling. Returns the function's result, or undefined if it throws.
monitor(fn) Wraps a function so that any thrown exception is caught and reported instead of propagating.
monitored Legacy class-method decorator equivalent to wrapping the method with monitor.
monitorError(e) Reports an error directly: logs it if debug mode is on, then forwards it to the error callback.

@datadog/js-core/util

General-purpose utilities.

import {
  createDisplay,
  setDebugMode,
  getDebugMode,
  ConsoleApiName,
  globalConsole,
  originalConsoleMethods,
} from '@datadog/js-core/util'
import type { Display } from '@datadog/js-core/util'

Types

Export Description
Display Console methods pre-bound to the original (unpatched) console, prefixed.

Constants

Export Description
ConsoleApiName Enum-like map of the console method names (log, debug, info, warn, error).
globalConsole Alias for the global console, resilient to bundler console.* stripping.
originalConsoleMethods The original (unpatched) console methods, captured at module load.

Functions

Export Description
createDisplay(prefix) Returns a Display bound to the original console methods, prefixing every message with prefix. Guards against patched console.
getDebugMode() Returns whether debug mode is currently enabled.
setDebugMode(enabled) Global debug-mode toggle. SDKs check getDebugMode() to decide whether to emit internal diagnostic logs to the console.