Class: Media
Defined in: lib/classes/media.ts:233
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;Defined in: lib/classes/media.ts:300
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 | Defined in |
|---|---|---|---|---|---|
filename | readonly | string | undefined | Filename surfaced to providers that key on it. | lib/classes/media.ts:275 |
id | readonly | string | undefined | Stable unique identifier. | lib/classes/media.ts:269 |
kind | readonly | "audio" | "document" | "image" | "video" | undefined | Media kind. | lib/classes/media.ts:271 |
mimeType | readonly | string | undefined | MIME type of the underlying bytes. | lib/classes/media.ts:273 |
modalityHazard | readonly | "inert" | "extractable-instructions" | "opaque-perceptual" | undefined | Modality hazard declared at construction time. | lib/classes/media.ts:281 |
source | readonly | string | undefined | undefined | Optional provenance pointer. | lib/classes/media.ts:277 |
stash | readonly | Registry | undefined | Mutable per-instance metadata register; middleware pipelines append to this. | lib/classes/media.ts:283 |
trustTier | readonly | "first-party" | "third-party-public" | "third-party-private" | undefined | Trust tier declared at construction time. | lib/classes/media.ts:279 |
MediaKind | static | readonly ["image", "audio", "video", "document"] | MediaKind | The set of recognised media kinds. Exposed for downstream schemas that need to discriminate on kind. | lib/classes/media.ts:243 |
MediaModalityHazard | static | readonly ["inert", "extractable-instructions", "opaque-perceptual"] | MediaModalityHazard | The set of recognised modality hazards. | lib/classes/media.ts:253 |
MediaTrustTier | static | readonly ["first-party", "third-party-public", "third-party-private"] | MediaTrustTier | The set of recognised trust tiers. | lib/classes/media.ts:248 |
schema | static | ObjectSchema<RawMedia> | rawMediaSchema | Validator schema that accepts a RawMedia object. | lib/classes/media.ts:237 |
Methods
asBase64()
asBase64(): Promise<string>;Defined in: lib/classes/media.ts:419
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>>;Defined in: lib/classes/media.ts:389
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>;Defined in: lib/classes/media.ts:378
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>>>;Defined in: lib/classes/media.ts:369
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;Defined in: lib/classes/media.ts:434
Returns the metadata-only serialisation of this Media. Bytes and the reader are stripped so naive event/log serialisation never materialises bytes.
Returns
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;Defined in: lib/classes/media.ts:264
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" | "document" | "image" | "video";
mimeType: string;
reader: MediaReader;
source?: string;
stash?: Record<string, MediaStashEntry>;
}): Media;Defined in: lib/classes/media.ts:521
Factory: constructs a Media retrieved from a private third-party source.
Parameters
| Parameter | Type |
|---|---|
args | { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; } |
args.filename | string |
args.id? | string |
args.kind | "audio" | "document" | "image" | "video" |
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" | "document" | "image" | "video";
mimeType: string;
reader: MediaReader;
source?: string;
stash?: Record<string, MediaStashEntry>;
}): Media;Defined in: lib/classes/media.ts:499
Factory: constructs a Media retrieved from a public third-party source.
Parameters
| Parameter | Type |
|---|---|
args | { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; } |
args.filename | string |
args.id? | string |
args.kind | "audio" | "document" | "image" | "video" |
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" | "document" | "image" | "video";
mimeType: string;
reader: MediaReader;
source?: string;
stash?: Record<string, MediaStashEntry>;
}): Media;Defined in: lib/classes/media.ts:477
Factory: constructs a Media produced by a first-party tool.
Parameters
| Parameter | Type |
|---|---|
args | { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; } |
args.filename | string |
args.id? | string |
args.kind | "audio" | "document" | "image" | "video" |
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" | "document" | "image" | "video";
mimeType: string;
reader: MediaReader;
source?: string;
stash?: Record<string, MediaStashEntry>;
}): Media;Defined in: lib/classes/media.ts:455
Factory: constructs a Media representing a user-supplied attachment.
Parameters
| Parameter | Type |
|---|---|
args | { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record<string, MediaStashEntry>; } |
args.filename | string |
args.id? | string |
args.kind | "audio" | "document" | "image" | "video" |
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.