dojo / actions

:rocket: Dojo 2 - a command library.

dojo

This is the foundation package for the Dojo 1 Toolkit. While still being maintained, new development is primarily focused on modern Dojo.

Checkout the Dojo framework website or if you want a more detailed technical status and overview, checkout the Dojo roadmap.

This package is sometimes referred to as the “core”, it contains the most generally applicable sub-packages and modules. The dojo package covers a wide range of functionality like Ajax, DOM manipulation, class-type programming, events, promises, data stores, drag-and-drop and internationalization libraries.

Installing

Installation instructions are available at dojotoolkit.org/download.

Getting Started

If you are starting out with Dojo, the following resources are available to you:

• Tutorials

• Reference Guide

• API Documentation

• Community Forum

What to Use Dojo For and When to Use It

The following is a brief sampling of some of the areas where Dojo may prove to be the right tool for your next project:

• For keeping your code fast and maintainable, Dojo offers an asynchronous module definition (AMD) loader -- encapsulating pieces of code into useful units, loading small JavaScript files only when they are needed, and loading files separately even when they are dependent on one another.

• When you want to easily extend existing classes, share functionality among a number of classes, and maximize code reuse, Dojo provides class-like inheritance and “mixins.”

• For creating advanced and customizable user interfaces out of refined, efficient, and modular pieces, Dojo’s Dijit framework offers several dozen enterprise-ready widgets -- including buttons, textboxes, form widgets with built-in validation, layout elements, and much more -- along with themes to lend them a consistent look. All of this is available for mobile environments as well.

• For working with advanced vector graphics, Dojo’s GFX API can render graphics in a wide variety of formats, with support for seamless manipulation (skewing, rotating, resizing), gradients, responding to mouse events, and more.

• The dojox/charting library supports powerful data visualization and dynamic charting, including a variety of 2D plots and animated charting elements.

• When you need feature-rich, lightweight, and mobile-friendly grids/tables, Dojo offers the dgrid widget, along with customizable default themes and accompanying features such as in-cell editing, row/cell selection, column resizing/reordering, keyboard handling, pagination, and more.

• Dojo is the officially supported framework for the ArcGIS API for JavaScript, one of the most widely used enterprise-grade APIs for web mapping and spatial analysis -- learning to use Dojo will open doors to creating richer web mapping applications using that API.

License and Copyright

The Dojo Toolkit (including this package) is dual licensed under BSD 3-Clause and AFL. For more information on the license please see the License Information. The Dojo Toolkit is Copyright (c) 2005-2018, JS Foundation. All rights reserved.

actions's Issues

Upgrade to typescript 2.4.1

Improve usability of actions by "templeting" common use cases

TypeScript 2.0 for dojo/actions

readonly visibility modifier for TS2.0+

Discussion: chronological history

One use-case for mementos that I'm not seeing explicitly accounted for is keeping the memento history in a chronological stream or queue -- each memento is time-stamped. This allows a user to select a specific point in time and get the associated memento.

I'm not seeing anything that would prevent this, just wondering if this use-case has been considered, and if the implementation is amenable to it.

Discussion: binding

Should the actions package include helpers for binding to objects to automatically observe and maintain history?

Poor typing usability

While working on dojo/examples#56 I found it nearly impossible to correctly type actions.

There is an assumption that the options passed to the do() implementation have an event object, and that object has a target property. That makes sense when actions are used as event listeners but often actions call other actions, passing an arbitrary object.

Furthermore, the do() method is assumed to return a Task which resolves with the (same type as) the target.

Correctly changing the typing of an action requires three types (DoOptions, TargettedEventObject and ActionState). This requires a fair amount of understanding of the action internals.

Typing an action which handles keypress events is nearly impossible since the KeyboardEvent type is not compatible with the TargettedEventObject. It has a target of course (an HTMLElement), but the do() implementation may return an entirely different object.

---

I'd like to see an interface closer to this:

interface ActionMixin<T, O> {
  do(options?: O): Task<T>;
}

type Action<T, O> = Stateful<ActionState> & ActionMixin<T, O>;

The default createAction export should create Action<any, any> instances. It should take type arguments, e.g. createAction<any, KeyboardEvent>() should create an action that can handle keyboard events. In the TodoMVC example, a createAction<any, Item>() should create an action that is called with todo items.

We could export other constructors to make it easier to create the current "targeted event" actions.

---

I'm not sure whether ActionState deserves to be a generic. It's tempting but we can't provide default values for generics, and the more arguments Action takes the harder it is to customize the typing.

Action options should allow typing of events

Action accept a typing of a target, but they should also allow generics for the event type all together, to allow additional property to be flowed through to the do() function.

Actions are not typed to be able to observe their state on creation.

Currently this does not work.

Actions Features

In doing the initial prototype, here are a few things that I thought of that we should consider for actions:

• do() returns a promise with redo() and undo(). It is up the method implementor to figure out what it actually needs to do to undo something. A potential improvement is that the action.state is cloned after .do() and passed into undo()/redo(). This way if you fire off a bunch of .do() you don't have to worry about how many you have in flight. Another way of managing this is that whatever is returned/resolved from the do() (or previous method in the chain) is passed into undo()/redo(). (Actually writing that down, I liked the second option)
• When no undo() method is specified upon instantiation, it results in a noop, which is resolved with no value. Maybe it makes sense to resolve with the previous value in the chain.
• Not sure what the best behaviour is for rejection/throws in a long chain. I realised I didn't actually code a behaviour, but I don't know if a long chain of .do().undo().redo() if each subsequent method should just reject with the previous value.
• Post instantiation, there is no designed way to replace the do()/undo()/redo() implementation methods. Don't know if that is desired/logical.
• There is no way of customising the returned promise further. Again, I don't know if this just adds arbitrary complexity.
• It isn't based on Evented. Therefore there are no built in event mechanisms. Again, I don't know if this is logical/expected.
• At run-time, calling do(), undo(), or redo() with different arity of arguments then specified in the interface does not pass these onto the implementation method. This is sort of "mean" in the sense that if you decided you want to pass something to undo(), your method won't receive it. Conceptually it would be anti-pattern to supply arguments to undo() but is it fair to actually discard them?

Update README to reflect alpha status

PR #20