jsdoc for factories, some unit tests, microsoft#123884

src/vs/vscode.proposed.d.ts

@@ -1240,19 +1240,18 @@ declare module 'vscode' {
 
 	// todo@API document which mime types are supported out of the box and
 	// which are considered secure
-
-	// code specific mime types
-	// application/x.notebook.error-traceback
-	// application/x.notebook.stdout
-	// application/x.notebook.stderr
-	// application/x.notebook.stream
 	export class NotebookCellOutputItem {
 
-		static error(err: Error): NotebookCellOutputItem;
-
-		static stdout(value: string): NotebookCellOutputItem;
-
-		static stderr(value: string): NotebookCellOutputItem;
+		/**
+		 * Factory function to create a `NotebookCellOutputItem` from a string.
+		 *
+		 * *Note* that an UTF-8 encoder is used to create bytes for the string.
+		 *
+		 * @param value A string/
+		 * @param mime Optional MIME type, defaults to `text/plain`.
+		 * @returns A new output item object.
+		 */
+		static text(value: string, mime?: string): NotebookCellOutputItem;
 
 		/**
 		 * Factory function to create a `NotebookCellOutputItem` from
@@ -1264,31 +1263,50 @@ declare module 'vscode' {
 		 *
 		 * @param value A JSON-stringifyable value.
 		 * @param mime Optional MIME type, defaults to `application/json`
+		 * @returns A new output item object.
 		 */
 		static json(value: any, mime?: string): NotebookCellOutputItem;
 
 		/**
-		 * Factory function to create a `NotebookCellOutputItem` from a string.
+		 * Factory function to create a `NotebookCellOutputItem` from bytes.
 		 *
-		 * *Note* that an UTF-8 encoder is used to create bytes for the string.
+		 * @param value An array of unsigned 8-bit integers.
+		 * @param mime Optional MIME type, defaults to `application/octet-stream`.
+		 * @returns A new output item object.
+		 */
+		//todo@API bytes, raw, buffer?
+		static bytes(value: Uint8Array, mime?: string): NotebookCellOutputItem;
+
+		/**
+		 * Factory function to create a `NotebookCellOutputItem` that uses
+		 * uses the `application/x.notebook.stdout` mime type.
 		 *
-		 * @param value A string/
-		 * @param mime Optional MIME type, defaults to `text/plain`.
+		 * @param value A string.
+		 * @returns A new output item object.
 		 */
-		static text(value: string, mime?: string): NotebookCellOutputItem;
+		static stdout(value: string): NotebookCellOutputItem;
 
 		/**
+		 * Factory function to create a `NotebookCellOutputItem` that uses
+		 * uses the `application/x.notebook.stderr` mime type.
 		 *
-		 * @param value
-		 * @param mime Optional MIME type, defaults to `application/octet-stream`.
+		 * @param value A string.
+		 * @returns A new output item object.
 		 */
-		//todo@API bytes, raw, buffer?
-		static bytes(value: Uint8Array, mime?: string): NotebookCellOutputItem;
+		static stderr(value: string): NotebookCellOutputItem;
+
+		/**
+		 * Factory function to create a `NotebookCellOutputItem` that uses
+		 * uses the `application/x.notebook.error` mime type.
+		 *
+		 * @param value An error object.
+		 * @returns A new output item object.
+		 */
+		static error(value: Error): NotebookCellOutputItem;
 
 		mime: string;
 
-		//todo@API string or Unit8Array?
-		// value: string | Uint8Array | unknown;
+		//todo@API only Unit8Array
 		value: Uint8Array | unknown;
 
 		metadata?: { [key: string]: any };

src/vs/workbench/api/common/extHostTypes.ts

@@ -3112,7 +3112,7 @@ export class NotebookCellOutputItem {
 		return typeof (<vscode.NotebookCellOutputItem>obj).mime === 'string';
 	}
 
-	static error(err: Error): NotebookCellOutputItem {
+	static error(err: Error | { name: string, message?: string, stack?: string }): NotebookCellOutputItem {
 		const obj = {
 			name: err.name,
 			message: err.message,
@@ -3129,18 +3129,20 @@ export class NotebookCellOutputItem {
 		return NotebookCellOutputItem.text(value, 'application/x.notebook.stderr');
 	}
 
-	static json(value: any, mime: string = 'application/json'): NotebookCellOutputItem {
-		const rawStr = JSON.stringify(value, undefined, '\t');
-		return NotebookCellOutputItem.text(rawStr, mime);
+	static bytes(value: Uint8Array, mime: string = 'application/octet-stream'): NotebookCellOutputItem {
+		return new NotebookCellOutputItem(mime, value);
 	}
 
+	static #encoder = new TextEncoder();
+
 	static text(value: string, mime: string = 'text/plain'): NotebookCellOutputItem {
-		const bytes = new TextEncoder().encode(String(value));
+		const bytes = NotebookCellOutputItem.#encoder.encode(String(value));
 		return new NotebookCellOutputItem(mime, bytes);
 	}
 
-	static bytes(value: Uint8Array, mime: string = 'application/octet-stream'): NotebookCellOutputItem {
-		return new NotebookCellOutputItem(mime, value);
+	static json(value: any, mime: string = 'application/json'): NotebookCellOutputItem {
+		const rawStr = JSON.stringify(value, undefined, '\t');
+		return NotebookCellOutputItem.text(rawStr, mime);
 	}
 
 	constructor(

src/vs/workbench/test/browser/api/extHostTypes.test.ts

@@ -682,4 +682,42 @@ suite('ExtHostTypes', function () {
 		assert.deepStrictEqual(newCustom.mycustom, undefined);
 		assert.deepStrictEqual(newCustom.anotherCustom, { display: 'hello2' });
 	});
+
+	test('NotebookCellOutputItem - factories', function () {
+
+		// --- err
+
+		let item = types.NotebookCellOutputItem.error(new Error());
+		assert.strictEqual(item.mime, 'application/x.notebook.error');
+		item = types.NotebookCellOutputItem.error({ name: 'Hello' });
+		assert.strictEqual(item.mime, 'application/x.notebook.error');
+
+		// --- JSON
+
+		item = types.NotebookCellOutputItem.json(1);
+		assert.strictEqual(item.mime, 'application/json');
+		assert.deepStrictEqual(item.value, new TextEncoder().encode(JSON.stringify(1)));
+
+		item = types.NotebookCellOutputItem.json(1, 'foo');
+		assert.strictEqual(item.mime, 'foo');
+		assert.deepStrictEqual(item.value, new TextEncoder().encode(JSON.stringify(1)));
+
+		item = types.NotebookCellOutputItem.json(true);
+		assert.strictEqual(item.mime, 'application/json');
+		assert.deepStrictEqual(item.value, new TextEncoder().encode(JSON.stringify(true)));
+
+		item = types.NotebookCellOutputItem.json([true, 1, 'ddd']);
+		assert.strictEqual(item.mime, 'application/json');
+		assert.deepStrictEqual(item.value, new TextEncoder().encode(JSON.stringify([true, 1, 'ddd'], undefined, '\t')));
+
+		// --- text
+
+		item = types.NotebookCellOutputItem.text('Hęłlö');
+		assert.strictEqual(item.mime, 'text/plain');
+		assert.deepStrictEqual(item.value, new TextEncoder().encode('Hęłlö'));
+
+		item = types.NotebookCellOutputItem.text('Hęłlö', 'foo/bar');
+		assert.strictEqual(item.mime, 'foo/bar');
+		assert.deepStrictEqual(item.value, new TextEncoder().encode('Hęłlö'));
+	});
 });