0
# Output Area Model
1

2
The Output Area Model provides the core data management layer for JupyterLab output areas. It manages collections of output items with observable state changes, stream consolidation, and JSON serialization support.
3

4
## Capabilities
5

6
### Output Area Model Interface
7

8
Core interface defining the contract for output area data models.
9

10
```typescript { .api }
11
/**
12
 * Interface for output area model providing observable data management
13
 */
14
interface IOutputAreaModel extends IDisposable {
15
  /** Signal emitted when an output item changes (emits the index) */
16
  readonly stateChanged: ISignal<IOutputAreaModel, number>;
17
  
18
  /** Signal emitted when the list of items changes */
19
  readonly changed: ISignal<IOutputAreaModel, IOutputAreaModel.ChangedArgs>;
20
  
21
  /** The number of output items in the model */
22
  readonly length: number;
23
  
24
  /** Whether the output area is trusted for executing untrusted content */
25
  trusted: boolean;
26
  
27
  /** The content factory used by the model for creating output items */
28
  readonly contentFactory: IOutputAreaModel.IContentFactory;
29
  
30
  /**
31
   * Get an output item at the specified index
32
   * @param index - The index of the item to retrieve
33
   * @returns The output model at the specified index
34
   */
35
  get(index: number): IOutputModel;
36
  
37
  /**
38
   * Remove characters from the end of the last stream output
39
   * @param number - Number of characters to remove
40
   */
41
  removeStreamOutput(number: number): void;
42
  
43
  /**
44
   * Append text to the last stream output
45
   * @param text - Text to append
46
   */
47
  appendStreamOutput(text: string): void;
48
  
49
  /**
50
   * Add an output item, potentially combining with previous stream output
51
   * @param output - The notebook output to add
52
   * @returns The total number of outputs after addition
53
   */
54
  add(output: nbformat.IOutput): number;
55
  
56
  /**
57
   * Remove an output item at the specified index
58
   * @param index - The index of the item to remove
59
   */
60
  remove(index: number): void;
61
  
62
  /**
63
   * Set the output value at the specified index
64
   * @param index - The index to set
65
   * @param output - The notebook output to set
66
   */
67
  set(index: number, output: nbformat.IOutput): void;
68
  
69
  /**
70
   * Clear all output items
71
   * @param wait - If true, delay clearing until next output is added
72
   */
73
  clear(wait?: boolean): void;
74
  
75
  /**
76
   * Deserialize the model from JSON notebook output format
77
   * @param values - Array of notebook outputs to load
78
   */
79
  fromJSON(values: nbformat.IOutput[]): void;
80
  
81
  /**
82
   * Serialize the model to JSON notebook output format
83
   * @returns Array of notebook outputs
84
   */
85
  toJSON(): nbformat.IOutput[];
86
}
87
```
88

89
### Output Area Model Implementation
90

91
Default implementation of the output area model with stream consolidation and change notifications.
92

93
```typescript { .api }
94
/**
95
 * Default implementation of IOutputAreaModel with observable behavior
96
 */
97
class OutputAreaModel implements IOutputAreaModel {
98
  /**
99
   * Create a new output area model
100
   * @param options - Configuration options for the model
101
   */
102
  constructor(options?: IOutputAreaModel.IOptions);
103
  
104
  /** Signal emitted when an output item state changes */
105
  get stateChanged(): ISignal<IOutputAreaModel, number>;
106
  
107
  /** Signal emitted when the output list changes */
108
  get changed(): ISignal<IOutputAreaModel, IOutputAreaModel.ChangedArgs>;
109
  
110
  /** Number of output items in the model */
111
  get length(): number;
112
  
113
  /** Whether the model is trusted for untrusted content execution */
114
  get trusted(): boolean;
115
  set trusted(value: boolean);
116
  
117
  /** Content factory for creating output models */
118
  readonly contentFactory: IOutputAreaModel.IContentFactory;
119
  
120
  /** Whether the model has been disposed */
121
  get isDisposed(): boolean;
122
  
123
  /**
124
   * Dispose of the model and clean up resources
125
   */
126
  dispose(): void;
127
  
128
  /**
129
   * Get an output model at the specified index
130
   * @param index - Index of the output to retrieve
131
   * @returns The output model at the index
132
   */
133
  get(index: number): IOutputModel;
134
  
135
  /**
136
   * Set an output at the specified index
137
   * @param index - Index to set the output at
138
   * @param value - Notebook output to set
139
   */
140
  set(index: number, value: nbformat.IOutput): void;
141
  
142
  /**
143
   * Remove characters from the end of the last stream output
144
   * @param number - Number of characters to remove from the end
145
   */
146
  removeStreamOutput(number: number): void;
147
  
148
  /**
149
   * Append text to the last stream output
150
   * @param text - Text to append to the stream
151
   */
152
  appendStreamOutput(text: string): void;
153
  
154
  /**
155
   * Add an output, with intelligent stream consolidation
156
   * @param output - Notebook output to add
157
   * @returns Total number of outputs after addition
158
   */
159
  add(output: nbformat.IOutput): number;
160
  
161
  /**
162
   * Remove an output at the given index
163
   * @param index - Index of output to remove
164
   */
165
  remove(index: number): void;
166
  
167
  /**
168
   * Clear all outputs from the model
169
   * @param wait - If true, delay clearing until next output
170
   */
171
  clear(wait?: boolean): void;
172
  
173
  /**
174
   * Load outputs from JSON notebook format
175
   * @param values - Array of notebook outputs to load
176
   */
177
  fromJSON(values: nbformat.IOutput[]): void;
178
  
179
  /**
180
   * Export outputs to JSON notebook format
181
   * @returns Array of notebook outputs
182
   */
183
  toJSON(): nbformat.IOutput[];
184
  
185
  /**
186
   * Determine whether a new output should be combined with the previous one
187
   * @param options - Object containing the new output and last model
188
   * @returns Whether the outputs should be combined
189
   * 
190
   * #### Notes
191
   * This method is called only when both outputs are stream messages of the same type.
192
   * The default implementation always returns true, but subclasses can override this
193
   * to provide custom combination logic.
194
   */
195
  protected shouldCombine(options: {
196
    value: nbformat.IOutput;
197
    lastModel: IOutputModel;
198
  }): boolean;
199
}
200
```
201

202
**Usage Examples:**
203

204
```typescript
205
import { OutputAreaModel } from "@jupyterlab/outputarea";
206

207
// Create a basic model
208
const model = new OutputAreaModel();
209

210
// Create a model with initial outputs and trust
211
const modelWithData = new OutputAreaModel({
212
  values: [
213
    {
214
      output_type: "stream",
215
      name: "stdout", 
216
      text: ["Hello World\n"]
217
    }
218
  ],
219
  trusted: true
220
});
221

222
// Listen for changes
223
model.changed.connect((sender, args) => {
224
  console.log(`Output list changed: ${args.type}`);
225
});
226

227
model.stateChanged.connect((sender, index) => {
228
  console.log(`Output at index ${index} changed`);
229
});
230

231
// Add various output types
232
model.add({
233
  output_type: "execute_result",
234
  execution_count: 1,
235
  data: {
236
    "text/plain": ["42"]
237
  },
238
  metadata: {}
239
});
240

241
model.add({
242
  output_type: "stream",
243
  name: "stderr",
244
  text: ["Error message\n"]
245
});
246

247
// Serialize to JSON
248
const outputs = model.toJSON();
249
console.log(outputs);
250

251
// Load from JSON
252
model.fromJSON(outputs);
253
```
254

255
### Content Factory
256

257
Factory interface and implementation for creating output models with customization support.
258

259
```typescript { .api }
260
/**
261
 * Interface for creating output models
262
 */
263
interface IOutputAreaModel.IContentFactory {
264
  /**
265
   * Create an output model for rendering
266
   * @param options - Options for the output model
267
   * @returns A new output model instance
268
   */
269
  createOutputModel(options: IOutputModel.IOptions): IOutputModel;
270
}
271

272
/**
273
 * Default content factory implementation
274
 */
275
class OutputAreaModel.ContentFactory implements IOutputAreaModel.IContentFactory {
276
  /**
277
   * Create an output model using the default OutputModel class
278
   * @param options - Options for creating the output model
279
   * @returns New OutputModel instance
280
   */
281
  createOutputModel(options: IOutputModel.IOptions): IOutputModel;
282
}
283

284
/**
285
 * Default content factory instance used when none is provided
286
 */
287
namespace OutputAreaModel {
288
  export const defaultContentFactory: OutputAreaModel.ContentFactory;
289
}
290
```
291

292
## Model Options and Types
293

294
```typescript { .api }
295
/**
296
 * Options for creating an output area model
297
 */
298
interface IOutputAreaModel.IOptions {
299
  /** Initial output values to populate the model */
300
  values?: nbformat.IOutput[];
301
  
302
  /** Whether the output should be treated as trusted (default: false) */
303
  trusted?: boolean;
304
  
305
  /** Content factory for creating output models (uses default if not provided) */
306
  contentFactory?: IOutputAreaModel.IContentFactory;
307
}
308

309
/**
310
 * Type alias for output list change arguments
311
 */
312
type IOutputAreaModel.ChangedArgs = IObservableList.IChangedArgs<IOutputModel>;
313
```
314

315
## Stream Processing
316

317
The model includes sophisticated stream processing capabilities:
318

319
- **Stream Consolidation**: Consecutive stream outputs of the same type are automatically merged
320
- **Text Processing**: Handles backspace, carriage return, and newline characters properly
321
- **Memory Management**: Prevents memory leaks in long-running stream outputs
322
- **Real-time Updates**: Provides incremental updates to stream content without full re-rendering