0
# Output Interfaces
1

2
Type-safe interfaces for all cell output types including execution results, display data, streams, and errors, with comprehensive type guard functions for runtime type checking.
3

4
## Capabilities
5

6
### Output Union Type and Base Interface
7

8
Core output type definitions and the base interface all outputs extend.
9

10
```typescript { .api }
11
/**
12
 * An output union type representing all possible output types
13
 */
14
type IOutput = IUnrecognizedOutput | IExecuteResult | IDisplayData | IStream | IError;
15

16
/**
17
 * The valid output types
18
 */
19
type OutputType = 'execute_result' | 'display_data' | 'stream' | 'error' | 'update_display_data';
20

21
/**
22
 * The base output type that all outputs extend
23
 */
24
interface IBaseOutput extends PartialJSONObject {
25
  /** Type of cell output */
26
  output_type: string;
27
}
28

29
/**
30
 * Cell output metadata type alias
31
 */
32
type OutputMetadata = PartialJSONObject;
33
```
34

35
### Execute Result Interface
36

37
Interface for outputs produced by code execution that return a value.
38

39
```typescript { .api }
40
/**
41
 * Result of executing a code cell that produces a return value
42
 */
43
interface IExecuteResult extends IBaseOutput {
44
  /** Type of cell output */
45
  output_type: 'execute_result';
46
  /** A result's prompt number */
47
  execution_count: ExecutionCount;
48
  /** A mime-type keyed dictionary of data */
49
  data: IMimeBundle;
50
  /** Cell output metadata */
51
  metadata: OutputMetadata;
52
}
53
```
54

55
**Usage Example:**
56

57
```typescript
58
import { IExecuteResult, IMimeBundle } from "@jupyterlab/nbformat";
59

60
const executeResult: IExecuteResult = {
61
  output_type: 'execute_result',
62
  execution_count: 1,
63
  data: {
64
    'text/plain': '42',
65
    'application/json': { value: 42 }
66
  },
67
  metadata: {}
68
};
69
```
70

71
### Display Data Interface
72

73
Interface for rich display outputs like images, HTML, and other media.
74

75
```typescript { .api }
76
/**
77
 * Data displayed as a result of code cell execution
78
 */
79
interface IDisplayData extends IBaseOutput {
80
  /** Type of cell output */
81
  output_type: 'display_data';
82
  /** A mime-type keyed dictionary of data */
83
  data: IMimeBundle;
84
  /** Cell output metadata */
85
  metadata: OutputMetadata;
86
}
87
```
88

89
**Usage Example:**
90

91
```typescript
92
import { IDisplayData } from "@jupyterlab/nbformat";
93

94
const displayData: IDisplayData = {
95
  output_type: 'display_data',
96
  data: {
97
    'text/html': '<h1>Hello World</h1>',
98
    'text/plain': 'Hello World'
99
  },
100
  metadata: {
101
    'text/html': {
102
      'isolated': true
103
    }
104
  }
105
};
106
```
107

108
### Display Update Interface
109

110
Interface for updating existing display outputs.
111

112
```typescript { .api }
113
/**
114
 * Data displayed as an update to existing display data
115
 */
116
interface IDisplayUpdate extends IBaseOutput {
117
  /** Type of cell output */
118
  output_type: 'update_display_data';
119
  /** A mime-type keyed dictionary of data */
120
  data: IMimeBundle;
121
  /** Cell output metadata */
122
  metadata: OutputMetadata;
123
}
124
```
125

126
### Stream Interface
127

128
Interface for text streams like stdout and stderr.
129

130
```typescript { .api }
131
/**
132
 * Stream output from a code cell
133
 */
134
interface IStream extends IBaseOutput {
135
  /** Type of cell output */
136
  output_type: 'stream';
137
  /** The name of the stream */
138
  name: StreamType;
139
  /** The stream's text output */
140
  text: MultilineString;
141
}
142

143
/**
144
 * An alias for a stream type
145
 */
146
type StreamType = 'stdout' | 'stderr';
147
```
148

149
**Usage Example:**
150

151
```typescript
152
import { IStream, StreamType } from "@jupyterlab/nbformat";
153

154
const streamOutput: IStream = {
155
  output_type: 'stream',
156
  name: 'stdout',
157
  text: ['Hello, world!', 'Line 2 of output']
158
};
159

160
const errorStream: IStream = {
161
  output_type: 'stream',
162
  name: 'stderr',
163
  text: 'Warning: deprecated function'
164
};
165
```
166

167
### Error Interface
168

169
Interface for error outputs including tracebacks.
170

171
```typescript { .api }
172
/**
173
 * Output of an error that occurred during code cell execution
174
 */
175
interface IError extends IBaseOutput {
176
  /** Type of cell output */
177
  output_type: 'error';
178
  /** The name of the error */
179
  ename: string;
180
  /** The value, or message, of the error */
181
  evalue: string;
182
  /** The error's traceback */
183
  traceback: string[];
184
}
185
```
186

187
**Usage Example:**
188

189
```typescript
190
import { IError } from "@jupyterlab/nbformat";
191

192
const errorOutput: IError = {
193
  output_type: 'error',
194
  ename: 'ValueError',
195
  evalue: 'invalid literal for int() with base 10: "abc"',
196
  traceback: [
197
    '\u001b[0;31m---------------------------------------------------------------------------\u001b[0m',
198
    '\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)',
199
    '\u001b[0;32m<ipython-input-1-abc>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m',
200
    '\u001b[0;31mValueError\u001b[0m: invalid literal for int() with base 10: "abc"'
201
  ]
202
};
203
```
204

205
### Unrecognized Output Interface
206

207
Interface for outputs that don't match known types.
208

209
```typescript { .api }
210
/**
211
 * Unrecognized output interface for unknown output types
212
 */
213
interface IUnrecognizedOutput extends IBaseOutput {}
214
```
215

216
### Output Type Guard Functions
217

218
Runtime type checking functions to determine output types.
219

220
```typescript { .api }
221
/**
222
 * Test whether an output is an execute result
223
 */
224
function isExecuteResult(output: IOutput): output is IExecuteResult;
225

226
/**
227
 * Test whether an output is from display data
228
 */
229
function isDisplayData(output: IOutput): output is IDisplayData;
230

231
/**
232
 * Test whether an output is from updated display data
233
 */
234
function isDisplayUpdate(output: IOutput): output is IDisplayUpdate;
235

236
/**
237
 * Test whether an output is from a stream
238
 */
239
function isStream(output: IOutput): output is IStream;
240

241
/**
242
 * Test whether an output is an error
243
 */
244
function isError(output: IOutput): output is IError;
245
```
246

247
**Usage Example:**
248

249
```typescript
250
import { 
251
  IOutput, 
252
  isExecuteResult, 
253
  isDisplayData, 
254
  isStream, 
255
  isError 
256
} from "@jupyterlab/nbformat";
257

258
function processOutputs(outputs: IOutput[]): void {
259
  outputs.forEach((output, index) => {
260
    if (isExecuteResult(output)) {
261
      console.log(`Output ${index}: Execute result (count: ${output.execution_count})`);
262
      console.log(`Data keys: ${Object.keys(output.data).join(', ')}`);
263
    } else if (isDisplayData(output)) {
264
      console.log(`Output ${index}: Display data`);
265
      console.log(`MIME types: ${Object.keys(output.data).join(', ')}`);
266
    } else if (isStream(output)) {
267
      console.log(`Output ${index}: ${output.name} stream`);
268
      const text = Array.isArray(output.text) ? output.text.join('') : output.text;
269
      console.log(`Content: ${text.substring(0, 50)}...`);
270
    } else if (isError(output)) {
271
      console.log(`Output ${index}: Error - ${output.ename}: ${output.evalue}`);
272
      console.log(`Traceback lines: ${output.traceback.length}`);
273
    } else {
274
      console.log(`Output ${index}: Unrecognized type: ${output.output_type}`);
275
    }
276
  });
277
}
278

279
// Example: Filter only error outputs
280
function getErrors(outputs: IOutput[]): IError[] {
281
  return outputs.filter(isError);
282
}
283

284
// Example: Get all text content from stream outputs
285
function getStreamText(outputs: IOutput[]): string {
286
  return outputs
287
    .filter(isStream)
288
    .map(stream => Array.isArray(stream.text) ? stream.text.join('') : stream.text)
289
    .join('');
290
}
291
```