mako-taco / decoratethis Goto Github PK

another idea (sorry :)... it could be useful to assert that a function implements a chaining API, i.e. that it returns whatever this context the function was called in, using something like @returns(Self):

class Foo {
  constructor() {
    this.total = 0;
  }

  @param(Number)
  @returns(Self)
  add(number) {
    this.total += number;
    return this;
  }
}

new Foo().add(12).add(43).add(52);

Obviously it wouldn't make sense to use this with @param though. Maybe this would be more suitable as a new decorator, @chainable() or something.

This looks like a great library.

Would you consider building it to ES5 before publishing on npm? I want to be able to require it without having to do require('babel/register') first.

Allow supporting an optional middle argument.

foo('a', 'b', function() {})
foo('a', function() {})

See http://joebain.github.io/args.js/ for an example.

Cross posting an issue I ran into when implementing a similar project a couple months back (https://github.com/megawac/lodash-decorators)

Decorators are not instance level in current state, wycats/javascript-decorators#13, meaning if you create multiple instances of a class you may be surprised. Example:

class X() {
   constructor(y) {
        this.x = y;
   }
   @memoize
   foo() {
     return this.x;
   }
}

console.log(x1.foo(1), x2.foo(1)) // What should x2 be

If you can think of a reasonable way to address that issue (I'm leaning towards WeakMaps myself, I'd be interested)

(This will apply to a number of other decorators such as debounce)

Ideally, i'd like to have decorators replace JSDocs for documenting code, which means we need a way to generate pretty docs from a decorated class or object. AFAIK, there are no AST-generating libraries which handle decorator syntax, so that will need to be solved first.

Proposed syntax:

let typedef = {name: String, age: Number}

@jsdoc(options)
class T {
  @param(Type, 'Description for arg0')
  @param(typedef, 'Description for arg1')
  method(arg0, arg1) {
  }
}

Requirements:

• Docs must be stripped out upon minification of code
• CLI must produce a folder of HTML docs in a configurable location
• Reasonable support of describing duck-typed / complex types

Any class decorated with @jsdoc will have docs exported by a CLI tool.

import {param, returns} from 'DecorateThis';

Shouldn't it be import {param, returns} from 'decorate-this';?

For ES7 async functions (or any other method that returns a promise), it would be nice to be able to type-check the fulfillment value of the promise (should it ever resolve).

The API could look like this:

class Foo {
  @returns(PromiseOf(Number))
  async someMethod() {
    await something();
    return 123;
  }
}

...although looking at the validator class, I'm not sure how that would work. Maybe a new decorator would be better, similar to returns:

class Foo {
  @promises(Number)
  async someMethod() {
    await something();
    return 123;
  }
}

Either way, I imagine it working like this:

1. the return value has to be a thenable, otherwise a TypeError will be thrown synchronously (i.e. same behaviour as @returns({then: Function}).)
2. the wrapper function returns a new promise which
   1. waits for the original promise to resolve,
   2. type-checks the fulfillment value of the original promise
      • if it fails the type check, reject the new promise
      • if it passes the type check, resolve the new promise with the fulfillment value

Example taken from MDN:

function multiply(multiplier, ...theArgs) {
  return theArgs.map(function (element) {
    return multiplier * element;
  });
}

Currently there's no way to typecheck all of theArgs.

Maybe there could be a new rest decorator?

@param(Number)
@rest(Number)
@returns(Array)
function multiply(multiplier, ...theArgs) {
  return theArgs.map(function (element) {
    return multiplier * element;
  });
}

What about SetOf(type), like ArrayOf but for ES6 sets?

Maybe also MapOf(keyType, valueType)?

This also got me thinking about extensibility... for example, if I am using an a custom/library-provided collection type like Immutable.OrderedSet, is there some way I could define my own ImmutableOrderedSetOf(type) (which I could then compose with other built-ins like Optional or ArrayOf(), etc)?

Maybe extensibility could be provided with a 'custom' type checker, which lets you supply a callback to examine the value in a custom way, like this:

import {Custom} from 'decorate-this';

const ImmutableOrderedSetOf = Custom((value, type) => {
  return value instanceof Immutable.OrderedSet && value.every(item => {
    return item instanceof type;
  });
});

@param(ImmutableOrderedSetOf(String))
function (strings) {
  // ...
}

(I don't actually know if this would work, just an idea.)

It would be great to have an additional decorator, say @params, that would allow you to use a single decorator to typew the entire signature, ie

@params(String, Number)
function foobar (someString, someNumber) { ... }

How @param validations can be done in this way.

@param(Number, Number)
addToDimensions(x, y) {
    this.x += x;
    this.y += y;
}

Think it's more intuitive to understand. Currently its not supported.