Official spec for transformer protocol

[tgriesser]

@swannodette if you recall, this was something I had asked about and while I don't recall the exact reason for not having a transformer protocol implemented in transducers-js, I do remember there was a reason.

I've been thinking about it a bit lately, and I do think it's worthwhile to be able to define, particularly for JavaScript where it's much simpler to bake this into the prototype rather than defining as a lookup map of handlers as in transit-js.

As more libraries in JavaScript begin implementing this protocol (this was prompted by @kevinbeaty's excellent transducer PR on the ramda.js project), I wanted to see if there could be an agreed upon spec for the transformer before things get too far along.

This is the implementation kicked off by @jlongster

var t = require('./transducers');
Immutable.Vector.prototype[t.protocols.transformer] = {
  init: function() {
    return Immutable.Vector().asMutable();
  },
  result: function(vec) {
    return vec.asImmutable();
  },
  step: function(vec, x) {
    return vec.push(x);
  }
};

For starters - the use of a Symbol('transformer') is problematic as Symbol() creates a unique value (Symbol('transformer') !== Symbol('transformer')), and so you lose any interop when defined independently in multiple libraries.

I'd propose all transformer protocols be implemented as a @@transformer string (similar to @@iterator) until if/when the transformer is officially recognized in the well known symbols list.

I'd also propose that the spec behave similarly to an iterator, in that it is a function which returns the transformer, rather than as just an object proposed above:

Immutable.Vector.prototype['@@transformer'] = function() {
  return {
    init: function() {
      return new Immutable.Vector().asMutable();
    },
    result: function(vec) {
      return vec.asImmutable();
    },
    step: function(vec, x) {
      return vec.push(x);
    }
  };
}

This makes the implementation more useful, as it can refer to the current object in the init to know what value makes to init, should the object be subclassed:

SomeObject.prototype['@@transformer'] = function() {
  var obj = this;
  return {
    init: function() {
      return new obj.constructor()
    },
    step: function(result, arr) {
      return result.set(arr[0], arr[1]);
    },
    result: function(obj) {
      return obj;
    }    
  };
}

[kevinbeaty]

For starters - the use of a Symbol('transformer') is problematic as Symbol() creates a unique value (Symbol('transformer') !== Symbol('transformer')), and so you lose any interop when defined independently in multiple libraries.

This is a very good point. I'm going to open a new PR on Ramda to remove the Symbol until this is worked out. It's not being exposed, nor documented, nor otherwise used internally other than to initialize _into.

[swannodette]

@tgriesser @kevinbeaty

Seems to me the logic should be more like the following:

var TRANSFORMER = null;

if(typeof Symbol != "undefined") {
    TRANSFORMER = Symbol.for("cognitect/transformer");
} else {
    TRANSFORMER = "@@cognitect/transformer";
}

Globally stealing names seems like a really bad idea.

[tgriesser]

Aren't we looking for something which behaves similar to __transducers_reduced__? - but in this case a standard duck-type for defining an object as a transformable which works between libraries?

I agree that stealing top-level names via Symbol.for wouldn't be ideal

[swannodette]

@tgriesser I'm suggesting that Symbols are the right path forward, using Symbol.for is fine as long as you namespace.

var ITransducer = {
    reduced: Symbol.for("cognitect/reduced"),
    transformer: Symbol.for("cognitect/transformer"),
    /* ... */
};

This seems like a good approach to me. Perhaps this is what @jlongster already did?

[jlongster]

I thought I had done that but I know I reworked the protocol in v2 of my lib so I must have dropped that: https://github.com/jlongster/transducers.js/blob/master/transducers.js#L8

Symbol.for is the right approach, but since it is supposed to be library-agnostic maybe transduce/transformer or something like that? I agree about namespacing. Symbols were supposed to get around namespacing but are only good for library-specific approaches... Here it doesn't really matter whether we use a symbol or not, imho

[jlongster]

I would suggest maybe we could have a separate library that defines these symbols that we all use, but that requires an equality check. And because npm loves to duplicate libraries, I don't think that will really work. Bah.

[swannodette]

@jlongster Symbol.for always returns the same thing. Dupes would only be across JS Contexts but I've always considered that a lost cause honestly. I suspect that Symbols will consistently compare faster than Strings in the future, that's the primary reason to prefer them.

[tgriesser]

Symbol.for is the right approach, but since it is supposed to be library-agnostic

Yeah, this is the main thing I'm looking for, just a way of making it library agnostic...

Then the second concern was whether the value is a function which defines/returns the transformer (which makes things a bit more flexible and is similar to an iterator), or just a plain object.

[swannodette]

Libraries could do the following:

var stringProp = "@@cognitect/transformer",
    symProp = typeof Symbol != "undefined" ? Symbol.for("cognitect/transformer") : stringProp;

x[stringProp] = x[symProp] = function() {
   /* ... */
};