Initial commit

ImmutableMap.md

@@ -0,0 +1,19 @@
+Immutable Map
+-------------
+
+### Examples
+
+__Initialization__
+```javascript
+const a = new ImmutableMap([['x', 1], ['y', 2]]);
+```
+
+__Extension__
+```javascript
+const b = a.set('z', 3);
+```
+
+__Type__
+```javascript
+typeof new ImmutableMap(); // 'map'
+```

ImmutableSet.md

@@ -0,0 +1,19 @@
+Immutable Set
+-------------
+
+### Examples
+
+__Initialization__
+```javascript
+const a = new ImmutableSet([1, 2]);
+```
+
+__Extension__
+```javascript
+const b = a.add(3);
+```
+
+__Type__
+```javascript
+typeof new ImmutableSet(); // 'set'
+```

Issues.md

@@ -0,0 +1,46 @@
+Known Issues
+------------
+
+### Referential/Physical Equality instead of Value Equality
+
+There are performance use cases where a deep equality is too expensive. For example, in a memoization process it can be faster to recompute than it is to do a deep equality on a large data structure.
+
+```javascript
+var memoizedInput;
+var memoizedResult;
+
+function calculate(input) {
+  if (memoizedInput !== input) {
+    memoizedResult = calculator(input);
+    memoizedInput = input;
+  }
+  return memoizedResult;
+}
+```
+
+However, since these values are immutable, it is possible for an implementation to reuse the same allocation. Therefore, these might have internal reference equality which would be a very fast lookup.
+
+It would be valuable to have a way to have both structural equality, which is the default of value types. However, it is also valuable to have physical equality. I propose that this physical equality needs a separate function.
+
+```javascript
+var memoizedInput;
+var memoizedResult;
+
+function calculate(input) {
+  if (Object.referenceEquals(memoizedInput, input)) {
+    memoizedResult = calculator(input);
+    memoizedInput = input;
+  }
+  return memoizedResult;
+}
+```
+
+Potentially memoization could be a built-in concept, however, that doesn't allow side-effects to be fired based on an equality check. That strategy is what powers libraries like React for interop with DOM.
+
+This could be solved in a separate proposal and potentially also includes Typed Objects and strings as well.
+
+### typeof
+
+The type of these objects are all types. This causes an explosion of new types. It doesn't work well with existing code that assume a finite set of types.
+
+Perhaps these types should share a single type such as 'record'?

README.md

@@ -0,0 +1,56 @@
+Immutable Records, Tuples, Maps and Sets for ECMAScript
+-------------------------------------------------------
+
+Immutability and referential transparency has many known benefits and ability for optimization. Several modern JavaScript libraries take advantage of this, and many more functional compile-to-JS languages.
+
+All these types provide value equality for both `==` and `===`.
+
+This proposal provides convenient syntax and semantics for immutable data structures and helpers to extend them. The actual implementation details of the extend operations are not covered by this spec but it's expected that engines optimize beyond just copying. E.g. using persistent data structures.
+
+### [Records](Records.md)
+
+Records are a new value type that represents an immutable object without a prototype.
+
+```javascript
+const xObj = #{ x: 1 }; // frozen value type
+const xyObj = #{ ...xObj, y: 2 }; // functional extension
+```
+
+### [Tuples](Tuples.md)
+
+Tuples are a new value type that represents an immutable array without a prototype and no .
+
+```javascript
+const xy = #[ x, y ]; // frozen value type
+const xyz = #[ ...xy, z ]; // functional extension
+```
+
+### [Immutable Map](ImmutableMap.md)
+
+ImmutableMap is an immutable version of Map. Any mutable operation returns a new ImmutableMap instead of mutating the existing reference.
+
+```javascript
+const a = new ImmutableMap([['x', 1], ['y', 2]]);
+const b = a.set('x', 3);
+a.get('x'); // 1
+b.get('y'); // 3
+```
+
+### [Immutable Set](ImmutableSet.md)
+
+ImmutableSet is an immutable version of Set. Any mutable operation returns a new ImmutableSet instead of mutating the existing reference.
+
+```javascript
+const a = new ImmutableSet([1, 2]);
+const b = a.add(3);
+a.size; // 2
+b.size; // 3
+```
+
+## [Status of this Proposal](https://github.com/tc39/ecma262)
+
+It is my intention to propose this as a Stage 0 proposal to ECMAScript 7.
+
+## [Known Issues](Issues.md)
+
+[See why this matters.](Issues.md)

Records.md

@@ -0,0 +1,51 @@
+Records
+-------
+
+### Examples
+
+__Initialization__
+```javascript
+const a = new Record({ x: 1, y: 2 });
+```
+
+__Initialization Sugar__
+```javascript
+const a = #{ x: 1, y: 2 };
+```
+
+__Extension__
+```javascript
+const b = new Record(Object.assign({}, a, { z: 3 }));
+```
+
+__Extension Sugar__
+```javascript
+const b = #{ ...a, z: 3 };
+```
+
+__Type__
+```javascript
+typeof #[]; // 'record'
+```
+
+### Syntax
+
+RecordLiteral:
+- `#` `{` (`...` AssignmentExpression)? `}`
+- `#` `{` PropertyDataAssignment (`,` PropertyDataAssignment)* (`,` `...` AssignmentExpression)? `}`
+
+PropertyDataAssignment:
+- PropertyName `:` AssignmentExpression
+
+### Comparison Semantics
+
+== and === test value equality.
+
+<, >= etc. test value order/equality in enumeration order.
+
+### Notes
+
+Enumeration always proceeds in lexicographic order of property names.
+
+== and === test value equality
+< etc. test value order/equality

Tuples.md

@@ -0,0 +1,50 @@
+Tuples
+------
+
+### Examples
+
+__Initialization__
+```javascript
+const a = new Tuple([1, 2]);
+```
+
+__Initialization Sugar__
+```javascript
+const a = #[1, 2];
+```
+
+__Extension__
+```javascript
+const b = a.concat(#[3, 4]);
+```
+
+__Extension Sugar__
+```javascript
+const b = #[...a, 3, 4];
+```
+
+__Type__
+```javascript
+typeof #[]; // 'tuple'
+```
+
+### Syntax
+
+TupleLiteral:
+- `#` `[` (TupleElement (`,` TupleElement)*)? `]`
+
+TupleElement:
+- AssignmentExpression
+- `...` AssignmentExpression
+
+### Comparison Semantics
+
+== and === test value equality.
+
+<, >= etc. test value order/equality in enumeration order.
+
+### Notes
+
+Enumeration always proceeds in numeric index order.
+
+`.length` cannot be greater than 2^32 - 1