Cowarray NPM | npm.io

cowarray

Implementation of copy-on-write for JavaScript arrays using ES2015 Proxy Objects

cowarray is an experimental project written in TypeScript. It seeks to completely decouple test source code from the actual library source code and just happens to provide an implementation of copy-on-write for JavaScript arrays using ES2015 Proxy Objects for something to do.

If you are looking for a way to architect your own TypeScript project, this project might give you some ideas. That being the case, you are probably best off cloning or forking the development project off GitHub and studying the source.

cowarray was created and is maintained by me, Justin Johansson, just out of curiosity about ES2015 Proxy Objects.

Features

Fully and transparently supports all ES3, ES5 and ES2015 Array properties and methods via a Proxy
Proxied subject array is only ever copied when an attempt is made to write to it
TypeScript source, compiled to and delivered as readable JavaScript
Library module shipped with TypeScript type declaration file(s) for benefit of TypeScript application consumers
cowarray API uses TypeScript generic function signatures to preserve array semantics

Requirements

JavaScript engine with ES2015 Proxy support (e.g. Node >= 6.5.0, up-to-date standards-compliant browsers). Check MDN.

Installation

Via NPM

npm install --save cowarray

API

From JavaScript with CommonJS require

// Choose cowarrayLax or cowarrayStrict as documented in the source code.
// cowarrayLax is best choice for most applications.
var cowarray = require('cowarray').cowarrayLax;
//var cowarray = require('cowarray').cowarrayStrict;

const input_array_not_to_be_modified = ['the', 'quick', 'red', 'fox'];

const working_array_which_may_be_modified = cowarray(input_array_not_to_be_modified);
working_array_which_may_be_modified[2] = 'brown';

// working_array_which_may_be_modified is now [ 'the', 'quick', 'brown', 'fox' ]
console.log("working_array_which_may_be_modified", working_array_which_may_be_modified);

// input_array_not_to_be_modified is still [ 'the', 'quick', 'red', 'fox' ]
console.log("input_array_not_to_be_modified", input_array_not_to_be_modified);

Testcode in TypeScript or JavaScript/ES2015 with ES2015 import

// Choose cowarrayLax or cowarrayStrict as documented in the source code.
// cowarrayLax is best choice for most applications.
import { cowarrayLax as cowarray } from 'cowarray';
//import { cowarrayStrict as cowarray } from 'cowarray';

import * as test from 'tape';

test('cowarray test', function (t) {
  t.equal(typeof cowarray, 'function');

  const witness_123 = [1, 2, 3];
  const witness_1234 = [1, 2, 3, 4];

  // Get a copy of the 1st witness (to ensure that it is not modified)
  const ar = witness_123.slice(0);
  t.deepEqual(ar, witness_123);

  // Make a COW array over ar. Note that the type annotation `number[]`
  // is not necessary; it is just to verify that the TypeScript compiler
  // is making proper use of the type declaration file provided by the
  // cowarray library module.
  const cw: number[] = cowarray(ar);
  t.equal(cw instanceof Array, true);
  t.deepEqual(cw, ar);

  // Now modify cw to be equal to the 2nd witness
  cw.push(4);
  t.deepEqual(cw, witness_1234);

  // Original ar should not have been modified
  t.deepEqual(ar, witness_123);

  // It would be nice to prove/show that ar is only copied when there
  // is an attempt to modify it via it's COW proxy.  However, because
  // ES2015 Proxy Objects are so transparent to application code, it is
  // difficult to demonstrate this without putting a trace print inside
  // of the cowarray library code itself.

  t.end();
});

Feedback

cowarray is currently a work-in-progress as far as it strives to be an exemplary TypeScript project. Feedback, especially suggestions for documentation & development workflow improvement, is most welcome via the project's issues pages on GitHub.