Class: Media

Lazy, re-openable view over a binary asset (image, audio, video, document).

Remarks

Dual-peer to @nhtio/adk!Tokenizable (silo) and @nhtio/adk!SpooledArtifact (handle). Wraps a @nhtio/adk!MediaReader contract — the framework owns the contract, the implementor owns the storage backend. Bytes are reached only through the reader; the primitive itself never inlines bytes.

Construction requires trustTier and modalityHazard — the framework refuses to guess provenance or decoding hazard. Ergonomic factories (Media.userAttachment, Media.toolGenerated, Media.retrievedPublic, Media.retrievedPrivate) force the labelling decision at the call site without becoming defaults on the bare constructor.

Constructors

Constructor

new Media(raw: RawMedia): Media;

Parameters

Parameter	Type	Description
raw	RawMedia	The raw media input validated against rawMediaSchema.

Returns

Media

Throws

@nhtio/adk/exceptions!E_INVALID_INITIAL_MEDIA_VALUE when raw does not satisfy the schema.

Throws

@nhtio/adk/exceptions!E_NOT_A_MEDIA_READER when raw.reader does not implement @nhtio/adk!MediaReader.

Properties

Property	Modifier	Type	Default value	Description
filename	readonly	string	undefined	Filename surfaced to providers that key on it.
id	readonly	string	undefined	Stable unique identifier.
kind	readonly	"audio" | "image" | "video" | "document"	undefined	Media kind.
mimeType	readonly	string	undefined	MIME type of the underlying bytes.
modalityHazard	readonly	"inert" | "extractable-instructions" | "opaque-perceptual"	undefined	Modality hazard declared at construction time.
source	readonly	string | undefined	undefined	Optional provenance pointer.
stash	readonly	Registry	undefined	Mutable per-instance metadata register; middleware pipelines append to this.
trustTier	readonly	"first-party" | "third-party-public" | "third-party-private"	undefined	Trust tier declared at construction time.
MediaKind	static	readonly ["image", "audio", "video", "document"]	MediaKind	The set of recognised media kinds. Exposed for downstream schemas that need to discriminate on kind.
MediaModalityHazard	static	readonly ["inert", "extractable-instructions", "opaque-perceptual"]	MediaModalityHazard	The set of recognised modality hazards.
MediaTrustTier	static	readonly ["first-party", "third-party-public", "third-party-private"]	MediaTrustTier	The set of recognised trust tiers.
schema	static	ObjectSchema<RawMedia>	rawMediaSchema	Validator schema that accepts a RawMedia object.

Methods

asBase64()

asBase64(): Promise<string>;

Drains the reader's stream and returns the underlying bytes as a base64 string.

Returns

Promise<string>

Remarks

Cross-environment: prefers Node's Buffer.from(buf).toString('base64') when available; otherwise chunk-encodes through btoa with a 0x8000-byte window to avoid stack overflow on large buffers.

---

asBytes()

asBytes(): Promise<Uint8Array<ArrayBufferLike>>;

Drains the reader's stream and returns the underlying bytes as a single Uint8Array.

Returns

Promise<Uint8Array<ArrayBufferLike>>

Remarks

Convenience for callers that need the full buffer (e.g. inline base64 encoding). Forces full materialisation — large assets should be piped through Media.stream instead.

---

byteLength()

byteLength(): Promise<number | undefined>;

Returns the total number of bytes in the underlying data, or undefined if unknown.

Returns

Promise<number | undefined>

The byte length, or undefined when the underlying source cannot report it.

---

stream()

stream(): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;

Re-opens the underlying byte source and returns a fresh ReadableStream.

Returns

Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>

A drainable ReadableStream over the underlying bytes.

---

toJSON()

toJSON(): SerializedMedia;

Returns the metadata-only serialisation of this Media. Bytes and the reader are stripped so naive event/log serialisation never materialises bytes.

Returns

SerializedMedia

Remarks

Implementations that have cheap, already-cached byteLength may opt to include it; this default implementation omits it to preserve the "lazy by default" invariant. Consumers that need byteLength on the serialised payload should call await media.byteLength() and merge the result.

---

isMedia()

static isMedia(value: unknown): value is Media;

Returns true if value is a Media instance.

Parameters

Parameter	Type	Description
value	unknown	The value to test.

Returns

value is Media

true when value is a Media instance.

Remarks

Uses @nhtio/adk!isInstanceOf for cross-realm safety.

---

retrievedPrivate()

static retrievedPrivate(args: {
  filename: string;
  id?: string;
  kind: "audio" | "image" | "video" | "document";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Factory: constructs a Media retrieved from a private third-party source.

Parameters

Parameter	Type
args	{ filename: string; id?: string; kind: "audio" | "image" | "video" | "document"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; }
args.filename	string
args.id?	string
args.kind	"audio" | "image" | "video" | "document"
args.mimeType	string
args.reader	MediaReader
args.source?	string
args.stash?	Record<string, MediaStashEntry>

Returns

Media

Remarks

Pre-fills trustTier: 'third-party-private' and derives modalityHazard from kind.

---

retrievedPublic()

static retrievedPublic(args: {
  filename: string;
  id?: string;
  kind: "audio" | "image" | "video" | "document";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Factory: constructs a Media retrieved from a public third-party source.

Parameters

Parameter	Type
args	{ filename: string; id?: string; kind: "audio" | "image" | "video" | "document"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; }
args.filename	string
args.id?	string
args.kind	"audio" | "image" | "video" | "document"
args.mimeType	string
args.reader	MediaReader
args.source?	string
args.stash?	Record<string, MediaStashEntry>

Returns

Media

Remarks

Pre-fills trustTier: 'third-party-public' and derives modalityHazard from kind.

---

toolGenerated()

static toolGenerated(args: {
  filename: string;
  id?: string;
  kind: "audio" | "image" | "video" | "document";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Factory: constructs a Media produced by a first-party tool.

Parameters

Parameter	Type
args	{ filename: string; id?: string; kind: "audio" | "image" | "video" | "document"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; }
args.filename	string
args.id?	string
args.kind	"audio" | "image" | "video" | "document"
args.mimeType	string
args.reader	MediaReader
args.source?	string
args.stash?	Record<string, MediaStashEntry>

Returns

Media

Remarks

Pre-fills trustTier: 'first-party' and derives modalityHazard from kind.

---

userAttachment()

static userAttachment(args: {
  filename: string;
  id?: string;
  kind: "audio" | "image" | "video" | "document";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Factory: constructs a Media representing a user-supplied attachment.

Parameters

Parameter	Type
args	{ filename: string; id?: string; kind: "audio" | "image" | "video" | "document"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; }
args.filename	string
args.id?	string
args.kind	"audio" | "image" | "video" | "document"
args.mimeType	string
args.reader	MediaReader
args.source?	string
args.stash?	Record<string, MediaStashEntry>

Returns

Media

Remarks

Pre-fills trustTier: 'third-party-private' and derives modalityHazard from kind (document → 'extractable-instructions'; everything else → 'opaque-perceptual'). Use the bare constructor when the conservative kind→hazard mapping is wrong for your case.