Diagnostics & the glue points

media is wired into the same four glue points every @dudousxd/nestjs-* library shares. None of them are required to use media — they're how it composes with the rest of the ecosystem when you want it to.

1. Diagnostics channels

Every layer of the library publishes to node:diagnostics_channel with the standard ecosystem envelope. This is the lowest-coupling integration there is: media doesn't import Telescope or know it exists — it just emits, and anything that cares subscribes. When nobody's listening, publishing is a no-op (a cheap hasSubscribers check), so it's always on by default with no measurable cost.

// channel: nestjs:media:<event>
{ ts: number, lib: 'media', event: 'attach', payload: { id, ownerType, ownerId, collection, disk, path, size, mimeType } }

Every event

Each event is its own channel (nestjs:media:<event>) carrying a typed payload. The full set (MEDIA_DIAGNOSTIC_EVENTS is exported for convenience):

This is what makes "do something on upload start / end" a two-line subscription — no hooks API to learn, just the channel:

import { subscribe } from 'node:diagnostics_channel';
import type { MediaDiagnosticEnvelope, UploadCompletePayload } from '@dudousxd/nestjs-media-core';

subscribe('nestjs:media:upload.start', (msg) => {
  console.log('upload started', (msg as MediaDiagnosticEnvelope).payload);
});

subscribe('nestjs:media:upload.complete', (msg) => {
  const { key, size } = (msg as MediaDiagnosticEnvelope<UploadCompletePayload>).payload;
  metrics.observe('media.upload.bytes', size, { key });
});

Each emitter takes emitDiagnostics: false to opt out (MediaLibrary, ResumableUploadManager, AttachmentManager). See @dudousxd/nestjs-diagnostics for the cross-ecosystem convention this follows.

2. Telescope

@dudousxd/nestjs-media-telescope ships a MediaWatcher that subscribes to those channels and records a media entry per event — so attaches, deletes, conversions, uploads, and attachments show up in the Telescope console next to your requests, queries, jobs, and mails, correlated under the same batch. It records every milestone but skips per-chunk upload.progress so a large resumable upload doesn't flood the timeline (progress stays on its channel for your own code).

import { MediaWatcher } from '@dudousxd/nestjs-media-telescope';
// add new MediaWatcher() to your telescope watcher list

That's the entire integration: media emits, the watcher records. No changes to your media code, no coupling between the packages beyond the channel name.

Running alongside the generic diagnostics bridge

If you also run @dudousxd/nestjs-diagnostics-telescope's generic bridge, you don't need to hand-maintain an exclude list to avoid double-recording. MediaWatcher.register() claims every event it records via the diagnostics claim registry, so the generic bridge's watcher skips them automatically at record time — you get one Telescope entry per event, not two. The one thing that doesn't change: upload.progress isn't claimed (this watcher doesn't record it either), so if you don't want it flooding the generic bridge too, mute it there yourself with mediaDiagnosticKey('upload.progress') in that bridge's exclude option.

3. Codegen

@dudousxd/nestjs-media-codegen contributes a typed media client to your generated output, so the front-end gets uploadMedia() + mediaUrl() with no hand-written upload protocol. The emitted file is a thin binding over the runtime client (it bakes in your tus base path and re-exports), which is the point of the next section. See Codegen.

4. React

@dudousxd/nestjs-media-react provides useMediaUpload() and <MediaUploader/>, built on the same resumable client — progress, status, and resume handled for you.

Why this shape

Every glue point here is opt-in and decoupled. media is useful with none of them (it's a storage + media library on its own), better with each of them, and never forced to depend on Telescope, the codegen runtime, or React to function. That's the ecosystem contract: libraries emit on shared channels and ship satellite packages, so you assemble exactly the surface you need.