Implement can-symbol

[justinbmeyer]

Related issues:

• can-operate proposal (in progress) canjs#2931 - can-operate
• Formalize .serialize(), .get(), hasOwnProperty, getOwnPropertyNames, .keys, etc ~21 can-define#63 - formalize .serialize(), .get(), etc
• Allow someone to access keys can-define#126 - access keys on can-define
• Change types to use a property Symbol check? can-util#103 - Use symbol instead of types

Symbols (and corresponding expected value)

All CanJS symbols will be prefixed with can.

Type detection:

• isMapLike Boolean - Item has values at keys
• isListLike Boolean - Item has values at enumerated keys
• isValueLike Boolean - Item has a single value
• isFunctionLike Boolean - Item can be called with arguments
• isConstructorLike Boolean

Shape detection:

• getOwnKeyNames - How to get a list of all the keys on this object. Returns an iterator.
• keyDescriptor - Returns information about this key. Probably info beyond Object.getPropertyDescriptor would normally provide.
• getValueDescriptor - Returns information about the value contained in this observable.
• iterator - Same as iterator
• proto

Get / Set:

• getValue
• setValue
• getKeyValue
• setKeyValue

Call:

• call
• apply
• new

Observe:

• onValue cb() -> valueIndex
• offValue cb()
• onKeyValue cb() -> valueIndex
• offKeyValue cb() -> valueIndex
• keyDependencies - The observable dependencies of a property in a map-like structure.
• valueDependencies - The observable dependencies of a value-like structure.

Methods

.for(key)

var canSymbol = require("can-symbol");

// env supports Symbols:
canSymbol('bar') //-> Symbol('bar')

// env doesn't support Symbols
// return can-symbol-bar to avoid conflicts
canSymbol('bar') //-> 'can-symbol-bar'

.keyFor( description )

Questions

• How would promises and streams work?

[matthewp]

Symbol has two APIs: Symbol('foo') !== Symbol('foo') and Symbol.for('foo') === Symbol.for('foo'). The latter is saved in an internal map so that each call gets the same symbol back. Will can-symbol have both of these as well?

[justinbmeyer]

@matthewp These are really only for "well known" symbols. They are there primarily for can-operate to use. It's to house "statefulness". There can be only one version of these symbols for CanJS to work.

tldr; We only need Symbol.for.

[matthewp]

We need private Symbols in can-zone.

[justinbmeyer]

Why?

[matthewp]

They are semi-private properties. They are unenumerable and can only be touched by outside code if they use Object.getOwnPropertySymbols and even then you can't get the string key used to make that symbol (so effectively you can't tell what a Symbol represents).

[matthewp]

One place where we use them is here: https://github.com/canjs/can-zone/blob/master/lib/zones/xhr.js#L21 to detect of an XHR request should come from the XHR_CACHE that is returned by server rendering.

[justinbmeyer]

This is going to change to a symbol polyfill that also includes the above registered symbols.