Class: Media

Defined in: src/lib/classes/media.ts:228

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: src/lib/classes/media.ts:295

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.	src/lib/classes/media.ts:270
`id`	`readonly`	`string`	`undefined`	Stable unique identifier.	src/lib/classes/media.ts:264
`kind`	`readonly`	`"document"` \| `"audio"` \| `"image"` \| `"video"`	`undefined`	Media kind.	src/lib/classes/media.ts:266
`mimeType`	`readonly`	`string`	`undefined`	MIME type of the underlying bytes.	src/lib/classes/media.ts:268
`modalityHazard`	`readonly`	`"inert"` \| `"extractable-instructions"` \| `"opaque-perceptual"`	`undefined`	Modality hazard declared at construction time.	src/lib/classes/media.ts:276
`source`	`readonly`	`string` \| `undefined`	`undefined`	Optional provenance pointer.	src/lib/classes/media.ts:272
`stash`	`readonly`	`Registry`	`undefined`	Mutable per-instance metadata register; middleware pipelines append to this.	src/lib/classes/media.ts:278
`trustTier`	`readonly`	`"first-party"` \| `"third-party-public"` \| `"third-party-private"`	`undefined`	Trust tier declared at construction time.	src/lib/classes/media.ts:274
`MediaKind`	`static`	readonly [`"image"`, `"audio"`, `"video"`, `"document"`]	`MediaKind`	The set of recognised media kinds. Exposed for downstream schemas that need to discriminate on `kind`.	src/lib/classes/media.ts:238
`MediaModalityHazard`	`static`	readonly [`"inert"`, `"extractable-instructions"`, `"opaque-perceptual"`]	`MediaModalityHazard`	The set of recognised modality hazards.	src/lib/classes/media.ts:248
`MediaTrustTier`	`static`	readonly [`"first-party"`, `"third-party-public"`, `"third-party-private"`]	`MediaTrustTier`	The set of recognised trust tiers.	src/lib/classes/media.ts:243
`schema`	`static`	`ObjectSchema`<`RawMedia`>	`rawMediaSchema`	Validator schema that accepts a RawMedia object.	src/lib/classes/media.ts:232

Methods

[ENCODE_METHOD]()

ENCODE_METHOD: unknown;

Defined in: src/lib/classes/media.ts:455

Serialise this Media into an @nhtio/encoder snapshot — the handle, never the bytes.

Returns

unknown

A snapshot consumed by Media.[DECODE_METHOD] / the encoder.

Remarks

Emits every metadata field plus the reader's @nhtio/adk!ReaderDescriptor (via its describe() method). The bytes are not inlined: decode re-binds the reader from the descriptor through a registered resolver. Throws @nhtio/adk!E_READER_NOT_DESCRIBABLE when the backing reader cannot describe itself (e.g. a fromWebFile Blob reader) — there is no serialisable handle to write, and silently dropping the reader would decode into a handle pointing at nothing.

Throws

@nhtio/adk!E_READER_NOT_DESCRIBABLE when the reader has no describe().

asBase64()

asBase64(): Promise<string>;

Defined in: src/lib/classes/media.ts:414

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: src/lib/classes/media.ts:384

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: src/lib/classes/media.ts:373

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: src/lib/classes/media.ts:364

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: src/lib/classes/media.ts:429

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.

[DECODE_METHOD]()

static DECODE_METHOD: Media;

Defined in: src/lib/classes/media.ts:484

Reconstruct a Media from an Media.[ENCODE_METHOD] snapshot.

Parameters

Parameter	Type	Description
`data`	`unknown`	The snapshot produced by Media.[ENCODE_METHOD].

Returns

Media

A fully-validated Media backed by a freshly-resolved reader.

Remarks

Re-binds the reader from the captured descriptor through the registered resolver (@nhtio/adk!resolveMediaReader), then re-validates via the normal constructor. Throws @nhtio/adk!E_NO_READER_RESOLVER when no resolver is registered for the descriptor's tag.

isMedia()

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

Defined in: src/lib/classes/media.ts:259

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: "document" | "audio" | "image" | "video";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Defined in: src/lib/classes/media.ts:583

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

Parameters

Parameter	Type
`args`	{ `filename`: `string`; `id?`: `string`; `kind`: `"document"` \| `"audio"` \| `"image"` \| `"video"`; `mimeType`: `string`; `reader`: `MediaReader`; `source?`: `string`; `stash?`: `Record`<`string`, `MediaStashEntry`>; }
`args.filename`	`string`
`args.id?`	`string`
`args.kind`	`"document"` \| `"audio"` \| `"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: "document" | "audio" | "image" | "video";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Defined in: src/lib/classes/media.ts:561

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

Parameters

Parameter	Type
`args`	{ `filename`: `string`; `id?`: `string`; `kind`: `"document"` \| `"audio"` \| `"image"` \| `"video"`; `mimeType`: `string`; `reader`: `MediaReader`; `source?`: `string`; `stash?`: `Record`<`string`, `MediaStashEntry`>; }
`args.filename`	`string`
`args.id?`	`string`
`args.kind`	`"document"` \| `"audio"` \| `"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: "document" | "audio" | "image" | "video";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Defined in: src/lib/classes/media.ts:539

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

Parameters

Parameter	Type
`args`	{ `filename`: `string`; `id?`: `string`; `kind`: `"document"` \| `"audio"` \| `"image"` \| `"video"`; `mimeType`: `string`; `reader`: `MediaReader`; `source?`: `string`; `stash?`: `Record`<`string`, `MediaStashEntry`>; }
`args.filename`	`string`
`args.id?`	`string`
`args.kind`	`"document"` \| `"audio"` \| `"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: "document" | "audio" | "image" | "video";
  mimeType: string;
  reader: MediaReader;
  source?: string;
  stash?: Record<string, MediaStashEntry>;
}): Media;

Defined in: src/lib/classes/media.ts:517

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

Parameters

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

What each pipeline owns

Envelopes

Persistence

Identity and Reasoning

Media

Class: Media ​

Remarks ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Throws ​

Throws ​

Properties ​

Methods ​

[ENCODE_METHOD]() ​

Returns ​

Remarks ​

Throws ​

asBase64() ​

Returns ​

Remarks ​

asBytes() ​

Returns ​

Remarks ​

byteLength() ​

Returns ​

stream() ​

Returns ​

toJSON() ​

Returns ​

Remarks ​

[DECODE_METHOD]() ​

Parameters ​

Returns ​

Remarks ​

isMedia() ​

Parameters ​

Returns ​

Remarks ​

retrievedPrivate() ​

Parameters ​

Returns ​

Remarks ​

retrievedPublic() ​

Parameters ​

Returns ​

Remarks ​

toolGenerated() ​

Parameters ​

Returns ​

Remarks ​

userAttachment() ​

Parameters ​

Returns ​

Remarks ​

Class: Media

Remarks

Constructors

Constructor

Parameters

Returns

Throws

Throws

Properties

Methods

[ENCODE_METHOD]()

Returns

Remarks

Throws

asBase64()

Returns

Remarks

asBytes()

Returns

Remarks

byteLength()

Returns

stream()

Returns

toJSON()

Returns

Remarks

[DECODE_METHOD]()

Parameters

Returns

Remarks

isMedia()

Parameters

Returns

Remarks

retrievedPrivate()

Parameters

Returns

Remarks

retrievedPublic()

Parameters

Returns

Remarks

toolGenerated()

Parameters

Returns

Remarks

userAttachment()

Parameters

Returns

Remarks