Convert TypedArray, ArrayBuffer and ArrayBufferView JS objects …

…to R raw atomic vectors (#363)

* Convert ArrayBuffer and ArrayBufferView objects to RRaw

* Update docs for ArrayBuffer conversion

* Add tests for converting ArrayBuffer to RRaw

* Update NEWS.md

NEWS.md

@@ -16,6 +16,8 @@
 
 * The `RCall` and `RFunction` classes now have a `capture(options, ...args)` method that captures output during evaluation.
 
+* JavaScript objects of type `TypedArray`, `ArrayBuffer`, and `ArrayBufferView` (e.g. `Uint8Array`) may now be used with the `RRaw` R object constructor. The generic `RObject` constructor now converts objects of this type to R raw atomic vectors by default.
+
 ## Breaking changes
 
 * The `captureR()` method now captures plots generated by the canvas graphics device by default. Captured plots are returned as an array of `ImageBitmap` objects in the property `images`. The previous behaviour may be restored either by manually starting a non-capturing `webr::canvas()` device during execution, or by including `captureGraphics: false` as part of the `options` argument. The default options for `evalR()` are set so that plotting is not captured, retaining the current behaviour.

src/docs/convert-js-to-r.qmd

@@ -51,16 +51,17 @@ The [`WebR` proxy classes](api/js/classes/WebR.WebR.md#properties) take a single
 
 The resulting R object type is chosen based on the contents of the JavaScript argument provided. When there is ambiguity, the following conversion rules are used,
 
-| Constructor Argument | R Type |
-|---------------------------------|---------------------------------------|
-| `null` | Logical `NA` |
-| `boolean` | Logical atomic vector |
-| `number` | Double atomic vector |
-| `{ re: 1, im: 2 }` | Complex atomic vector |
-| `string` | Character atomic vector |
-| JavaScript array | An atomic vector with type based on the above rules and following the coercion rules of R's `c()` function |
-| [Object of type `WebRDataJs`](convert-r-to-js.qmd#serialising-r-objects) | An R object type given by the `type` property in the provided object |
-| Other JavaScript object | Reserved for future use |
+| Constructor Argument | R Type |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `null` | Logical `NA` |
+| `boolean` | Logical atomic vector |
+| `number` | Double atomic vector |
+| `{ re: 1, im: 2 }` | Complex atomic vector |
+| `string` | Character atomic vector |
+| `TypedArray`, `ArrayBuffer`, `ArrayBufferView` | Raw atomic vector |
+| `Array` | An atomic vector of type following the coercion rules of R's `c()` function |
+| [Object of type `WebRDataJs`](convert-r-to-js.qmd#serialising-r-objects) | Given by the `type` property in the provided object |
+| Other JavaScript object | Reserved for future use |
 
 In the case of R lists provided as an [`WebRDataJs`](api/js/modules/RObject.md#webrdatajs), the above rules are applied recursively to also construct the objects provided within the list.
 

src/tests/webR/webr-main.test.ts

@@ -1,16 +1,17 @@
 import { WebR } from '../../webR/webr-main';
 import { Message } from '../../webR/chan/message';
 import {
- RDouble,
- RLogical,
+ RCall,
  RCharacter,
  RComplex,
- RList,
- RPairlist,
+ RDouble,
  REnvironment,
- RInteger,
  RFunction,
- RCall,
+ RInteger,
+ RList,
+ RLogical,
+ RPairlist,
+ RRaw,
 } from '../../webR/robj-main';
 
 const webR = new WebR({
@@ -375,6 +376,27 @@ describe('Create R vectors from JS arrays using RObject constructor', () => {
  })
  );
  });
+
+ test('Create a raw atomic vector', async () => {
+ const jsObj = new Uint8Array([0, 2, 4, 8, 16, 30, 52, 84, 128, 186]);
+ let rObj = (await new webR.RObject(jsObj)) as RRaw;
+ expect(await rObj.type()).toEqual('raw');
+ expect(await rObj.toJs()).toEqual(
+ expect.objectContaining({
+ values: Array.from(jsObj),
+ names: null,
+ })
+ );
+
+ rObj = (await new webR.RObject(jsObj.buffer)) as RRaw;
+ expect(await rObj.type()).toEqual('raw');
+ expect(await rObj.toJs()).toEqual(
+ expect.objectContaining({
+ values: Array.from(jsObj),
+ names: null,
+ })
+ );
+ });
 });
 
 describe('Create R objects from JS objects using proxy constructors', () => {
@@ -456,6 +478,18 @@ describe('Create R objects from JS objects using proxy constructors', () => {
  );
  });
 
+ test('Create a raw atomic vector using an ArrayBuffer', async () => {
+ const jsObj = new Uint8Array([1, 2, 6, 140, 16456, 8390720]);
+ const rObj = await new webR.RRaw(jsObj.buffer);
+ expect(await rObj.type()).toEqual('raw');
+ expect(await rObj.toJs()).toEqual(
+ expect.objectContaining({
+ values: Array.from(jsObj),
+ names: null,
+ })
+ );
+ });
+
  test('Create a list containing both a logical NA and R NULL', async () => {
  const jsObj = [true, 2, null, webR.objs.null];
  const rObj = await new webR.RList(jsObj);

src/webR/robj-worker.ts

@@ -116,6 +116,11 @@ function newObjectFromData(obj: WebRData): RObject {
  if (isComplex(obj)) {
  return new RComplex(obj);
  }
+
+ // JS Array-like objects
+ if (ArrayBuffer.isView(obj) || obj instanceof ArrayBuffer) {
+ return new RRaw(obj);
+ }
  if (Array.isArray(obj)) {
  return newObjectFromArray(obj);
  }
@@ -1076,6 +1081,9 @@ export class RCharacter extends RVectorAtomic<string> {
 
 export class RRaw extends RVectorAtomic<number> {
  constructor(val: WebRDataAtomic<number>) {
+ if (val instanceof ArrayBuffer) {
+ val = new Uint8Array(val);
+ }
  super(val, 'raw', RRaw.#newSetter);
  }
 

src/webR/robj.ts

@@ -78,6 +78,8 @@ export type WebRData =
  | WebRDataRaw
  | WebRDataJs
  | WebRData[]
+ | ArrayBuffer
+ | ArrayBufferView
  | { [key: string]: WebRData };
 
 /**
@@ -87,13 +89,13 @@ export type WebRData =
  */
 export type WebRDataAtomic<T> =
  | WebRDataScalar<T>
- | (T | null)[]
  | WebRDataJsAtomic<T>
- | NamedObject<T | null>;
+ | NamedObject<T | null>
+ | (T extends number ? ArrayBuffer | ArrayBufferView | (number | null)[] : (T | null)[]);
 
 /**
  * `WebRDataJs` objects form a tree structure, used when serialising R objects
- * into a JavaScript respresentation.
+ * into a JavaScript representation.
  *
  * Nested R objects are serialised using the {@link WebRDataJsNode} type,
  * forming branches in the resulting tree structure, with leaves formed by the

src/webR/utils.ts

@@ -33,6 +33,9 @@ export function replaceInObject<T>(
  if (obj === null || typeof obj !== 'object' || isImageBitmap(obj) ) {
  return obj;
  }
+ if (obj instanceof ArrayBuffer) {
+ return new Uint8Array(obj) as T;
+ }
  if (test(obj)) {
  return replacer(obj, ...replacerArgs) as T;
  }