motorcycle/motorcycle.ts

Your Type-Safe, Declarative and Reactive Toolkit for Modern Composable and Event-Driven Development

Motorcycle.ts

A statically-typed, functional and reactive framework for modern browsers

Packages

• @motorcycle/types -- A shared-kernel of types for Motorcycle
• @motorcycle/stream -- Functional and reactive event streams for Motorcycle.ts
• @motorcycle/run -- A statically-typed, functional and reactive framework for modern browsers
• @motorcycle/test -- Testing functions for Motorcycle.ts
• @motorcycle/dom -- Declarative, functional, reactive abstractions for the DOM
• @motorcycle/mostly-dom -- Motorcycle.ts adapter for mostly-dom

Examples

• Counter
• Traffic Light
• Sokoban -- A type of transport puzzle, in which the player pushes boxes or crates around in a warehouse, trying to get them to storage locations.
• Drag-n-Drop -- A simple drag-n-drop reorderable list.

Developing

Requirements

• Latest stable version of Node
• Latest stable version of Yarn

For generating changelog (for those with NPM publishing rights)

• Ruby >= v2.1.0
• Github Personal Access Token
  • Save the access token you generated for later usage

In your terminal, run the following:

Note: sudo may be required for all of the following terminal commands.

# If you're on a Debian-based Linux Distribution, install rake
gem install rake

# Install Github Changelog Generator
gem install github_changelog_generator

In your .bash_profile, .zshrc or equivalent shell configuration file, add the following:

export CHANGELOG_GITHUB_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN_GENERATED_ABOVE

In a new terminal, you should now be able to successfully run yarn changelog to generate an up-to-date CHANGELOG.md.

motorcycle.ts's Issues

Improve @motorcycle/run semantically

The current code, v4.1.0, explicitly mentions UI and Application, which is somewhat misleading and hints a specific architecture. Motorcycle's only general suggestion, however, is to separate pure functions from side effects.

Instead of ...

export function run<
  Sources extends Readonly<Record<string, any>>,
  Sinks extends Readonly<Record<string, Stream<any>>>
>(UI: Component<Sources, Sinks>, Application: EffectfulComponent<Sinks, Sources>)

... rename UI to Main, Application to IO, and EffectfulComponent to IOComponent.

Now, the main entry point to a Motorcycle application is Main, a regular component, and the side effects entry point is IO, an IO component, which by its name and type indicates side effects.

@motorcycle/http

API to be discussed and split into issues

feat: Component type

Component<Sources, Sinks> = (sources: Sources) => Sinks

feat: re-export @most/types

chore: Create documentation generation

stream: switch from 167 to @typed/prelude

META: Create and document issue labels

Stream package v1.7.0 is incompatible

@motorcycle/[email protected] is incompatible with the other packages and causes type errors. See #141.

add documentation to isolateDom

@motorcycle/router

API to be discussed and split into issues

@motorcycle/i18n

API to be discussed and split into issues

Feat: rexport @most/core

• only export source and combinator functions

Create examples

feat: createProxy()

import { Stream } from '@motorcycle/types'

export interface Proxy<A> {
  readonly attach: (source: Stream<A>) => Stream<A>
  readonly stream: Stream<A>
}

export function createProxy<A>(): Proxy<A>

• should be able to create circular dependencies
• should not have memory leaks

Implement `last` stream combinator

See https://github.com/mostjs-community/last for more information on what it does

mostly-dom: switch from 167 to @typed/prelude

feat: combineObj

Previous inspiration https://github.com/mostjs-community/combineObj

@motorcycle/history

API needs to be discussed and split into issues

export switchLatest from @most/core

feat: EffectfulComponent type

Motorcycle.ts Goals

This issue is not meant to be taken as-is but as a flexible starting point to work from, likely being broken into many smaller issues.

Overall design goals

• Better separation of concerns
• Smaller packages
• Improve writing tests with Motorcycle
• More tests -- everything should be done with TDD
• Better types
• Better documentation
• Less dependencies

Things that need to be done for release

Chores

• Create and document issue labels
  Documented in the wiki!
• Document git workflow
• Create a code of conduct
• Switch out npm for yarn

Features

@motorcycle/types

A shared-kernel for types to reuse across many packages

• re-export types from @most/types
• Component<Sources, Sinks> = (sources: Sources) => Sinks
• EffectfulComponent<Sinks, Sources> = (sinks: Sinks>) => Sources

@motorcycle/stream

A most distribution with additional combinators for making motorcycle application
easier to develop.

Export functions/types from

• @most/core -- stream factories and combinators only

Stream-factory functions

• createProxy(): Proxy

Stream combinators

• mapProp :: string -> Stream a -> Stream a[string]
• switchCombine :: Stream [ (Stream a) ] -> Stream [ a ]
• switchMerge :: Stream [ (Stream a) ] -> Stream a
• observe :: (a -> *) -> Stream a -> Promise void
• drain :: Stream * -> Promise void

@motorcycle/run

The heart of Motorcycle, should be built on @motorcycle/stream

• run

@motorcycle/test

A place for test-related functions. Hopefully based on @most/virtual-stream

• API is to be discussed

@motorcycle/dom

Built on mostly-dom it should only export functions that are related to the DOM.

• API to be discussed

@motorcycle/html

Built on mostly-html it should only export functions that are related to server-side-rendering.

• API to be discussed

@motorcycle/history

• API to be discussed

@motorcycle/router

• API to be discussed

@motorcycle/http

• API to be discussed

@motorcycle/storage

Built on the DOM's Storage interface

• makeStorage(storage: Storage): Component<?, ?>

@motorcycle/i18n

• API to be discussed

Things that can be done after release

• Create a website
• Create examples

Switch from 167 to @typed/prelude

Export scheduler from @motorcycle/stream

feat: switchSinkOr

import { Stream } from '@motorcycle/types'

export function switchSinkOr<Sinks>(key: keyof Sinks, or$: Sinks[typeof key], sinks$: Stream<Sinks>): Sinks[typeof key] {
  return switchLatest(map((sinks: Sinks) => sinks[key] || or$, sinks$))
}

// example usage
const history$ = switchSinkOr('history$', empty(), sinks$)

Curry isolate

At the time of this writing, isolate accepts two arguments: component:Component<Sources, Sinks> and key:String, respectfully. When dealing with a list of components that need isolation, it could be beneficial to be able to map over a list of keys. E.g.:

const isolatedComponents = map(isolate(MyComponent), keys)

I will therefor propose that we curry the isolate function.

feat: mapSinks

import { Stream } from '@motorcycle/types'

export function mapSinks<Sinks extends { readonly [key: string]: Stream<any> }>(
  key: keyof Sinks, 
  sinks$: Stream<Array<Sinks>>): Stream<ReadonlyArray<Sinks[typeof key]>>; 

• must accept ArrayLike and ReadonlyArray

dom: Switch from 167 to @typed/prelude

mapList :: (a -> b) -> Stream (List a) -> Stream (List b)

hold is missing documentation

https://github.com/motorcyclets/motorcycle/blob/master/packages/stream/src/combinators/hold.ts#L5

Missing sample and sampleWith

@motorcycle/stream is missing sample and sampleWith.

@motorcycle/html

Built on mostly-html it should only export functions that are related to server-side-rendering.

API needs to be discussed and broken up into issues

Document git workflow

@motorcycle/test

A place for test-related functions. Hopefully based on @most/virtual-stream

API needs to be discussed

@motorcycle/storage

API to be discussed and split into issues

Renovate error: @motorcycle/types not found

Hi @TylorS,

I'm the author of the Renovate app/service. I wanted to alert you of an error I saw in my logs, that the dependency @motorcycle/types cannot be found.

It's referenced here: https://github.com/motorcyclets/motorcycle/blob/develop/packages/stream/package.json#L40

And it can't be found here: https://www.npmjs.com/package/@motorcycle/types

Unfortunately, this error means that Renovate can't update any of the packages in this package.json, the reason being: we choose not to update a package.json unless we can update its accompanying lock file, and we can only generate the lock file if yarn can install all modules.

Assuming it's a public module, you need to either remove it from the package.json or publish it to npm so that it can be found.

Let me know in case if I can help, or if I am misunderstanding anything.

Let renovate run less frequently

Investigate if we can configure renovate to only make PRs once a week (or so). If possible, implement it!

Generics order of EffectfulComponent

Is there a reason that Sinks comes before Sources in the generics typing for this instead of the other way around? Sources seems to be first in "all" the other types.

Update naming to match @most/core

As @most/core is getting closer and closer to v1.0, some functions have been renamed. I think we should also go through our API and reflect any renaming to continue to be @most/core + Motorcycle extras.

Type errors with latest releases

Code to reproduce the issue:

cd examples/sokoban
rm yarn.lock
yarn cache clean
yarn install
yarn upgrade
yarn start

Expected behavior:

The example should compile and run with webpack.

Actual behavior:

ERROR in /home/frikki/.local/src/motorcyclets/motorcycle/examples/sokoban/node_modules/@motorcycle/stream/lib/sources/createProxy/ProxyStream.d.ts
(3,22): error TS2415: Class 'ProxyStream<A>' incorrectly extends base class 'MulticastSource<A>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<A>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<A>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/interaction/key.ts
(9,49): error TS2345: Argument of type 'Stream<KeyboardEvent>' is not assignable to parameter of type 'Stream<{ key: string; }>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<KeyboardEvent>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<{ key: string; }>, scheduler: Scheduler) => Disposable'.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(33,77): error TS2345: Argument of type 'Stream<string>' is not assignable to parameter of type 'Stream<{}>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<string>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<{}>, scheduler: Scheduler) => Disposable'.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(34,62): error TS2345: Argument of type 'Stream<string>' is not assignable to parameter of type 'Stream<{}>'.

ERROR in ./src/ui/UI.ts
(36,71): error TS2345: Argument of type 'Stream<State>' is not assignable to parameter of type 'Stream<State>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<State>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<State>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(41,60): error TS2345: Argument of type 'Stream<string>' is not assignable to parameter of type 'Stream<{}>'.

ERROR in ./src/ui/UI.ts
(47,5): error TS2345: Argument of type 'Stream<true>' is not assignable to parameter of type 'Stream<any>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<true>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<any>, scheduler: Scheduler) => Disposable'.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.
          Property 'currentTime' is missing in type 'Scheduler'.

ERROR in ./src/ui/UI.ts
(50,7): error TS2345: Argument of type 'Stream<{ levelCompleted: boolean; allLevelsCompleted: boolean; }>' is not assignable to parameter of type 'Stream<{ levelCompleted: boolean; allLevelsCompleted: boolean; }>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<{ levelCompleted: boolean; allLevelsCompleted: boolean; }>, scheduler: Scheduler) => ...' is not assignable to type '(sink: Sink<{ levelCompleted: boolean; allLevelsCompleted: boolean; }>, scheduler: Scheduler) => ...'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(60,53): error TS2345: Argument of type 'Stream<LevelCompletion>' is not assignable to parameter of type 'Stream<LevelCompletion>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<LevelCompletion>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<LevelCompletion>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(62,43): error TS2345: Argument of type 'Stream<true>' is not assignable to parameter of type 'Stream<any>'.

ERROR in ./src/ui/UI.ts
(66,45): error TS2345: Argument of type 'Stream<State>' is not assignable to parameter of type 'Stream<State>'.

ERROR in ./src/ui/UI.ts
(67,55): error TS2345: Argument of type 'Stream<State>' is not assignable to parameter of type 'Stream<State>'.

ERROR in ./src/ui/UI.ts
(68,56): error TS2345: Argument of type 'Stream<State>' is not assignable to parameter of type 'Stream<State>'.

ERROR in ./src/ui/UI.ts
(72,7): error TS2345: Argument of type 'Stream<number>' is not assignable to parameter of type 'Stream<number>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<number>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<number>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(74,5): error TS2345: Argument of type 'Stream<boolean>' is not assignable to parameter of type 'Stream<boolean>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<boolean>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<boolean>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/ui/UI.ts
(81,3): error TS2322: Type '{ view$: Stream<{}>; go$: Stream<Direction>; start$: Stream<true>; level$: Stream<number>; }' is not assignable to type 'UISinks'.
  Type '{ view$: Stream<{}>; go$: Stream<Direction>; start$: Stream<true>; level$: Stream<number>; }' is not assignable to type 'DomSinks'.
    Types of property 'view$' are incompatible.
      Type 'Stream<{}>' is not assignable to type 'Stream<VNode<Node, VNodeProps<Element, VNodeEvents<Element, ElementEventMap>>>>'.
        Types of property 'run' are incompatible.
          Type '(sink: Sink<{}>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<VNode<Node, VNodeProps<Element, VNodeEvents<Element, ElementEventMap>>>>, scheduler: ...'.
            Types of parameters 'scheduler' and 'scheduler' are incompatible.
              Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/application/keepState.ts
(14,40): error TS2345: Argument of type 'Stream<Direction>' is not assignable to parameter of type 'Stream<Direction>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<Direction>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<Direction>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/application/elapsedTime.ts
(12,3): error TS2322: Type 'Stream<number>' is not assignable to type 'Stream<Seconds>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<number>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<Seconds>, scheduler: Scheduler) => Disposable'.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/application/Application.ts
(12,31): error TS2345: Argument of type 'Stream<number>' is not assignable to parameter of type 'Stream<number>'.

ERROR in ./src/application/Application.ts
(14,43): error TS2345: Argument of type 'Stream<Stream<State>>' is not assignable to parameter of type 'Stream<Stream<State>>'.
  Type 'Stream<State>' is not assignable to type 'Stream<State>'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/application/Application.ts
(15,71): error TS2345: Argument of type 'Stream<State>' is not assignable to parameter of type 'Stream<State>'.

ERROR in ./src/application/Application.ts
(20,77): error TS2345: Argument of type 'Stream<number>' is not assignable to parameter of type 'Stream<number>'.

ERROR in ./src/application/Application.ts
(27,20): error TS2345: Argument of type 'Stream<Stream<Seconds>>' is not assignable to parameter of type 'Stream<Stream<Seconds>>'.
  Type 'Stream<Seconds>' is not assignable to type 'Stream<Seconds>'. Two different types with this name exist, but they are unrelated.
    Types of property 'run' are incompatible.
      Type '(sink: Sink<Seconds>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<Seconds>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they areunrelated.
        Types of parameters 'scheduler' and 'scheduler' are incompatible.
          Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/application/Application.ts
(32,3): error TS2322: Type '{ state$: Stream<State>; allLevelsCompleted$: Stream<boolean>; elapsedTime$: Stream<Seconds>; }' is not assignable to type 'ApplicationSources'.
  Types of property 'allLevelsCompleted$' are incompatible.
    Type 'Stream<boolean>' is not assignable to type 'Stream<boolean>'. Two different types with this name exist, but they are unrelated.
      Types of property 'run' are incompatible.
        Type '(sink: Sink<boolean>, scheduler: Scheduler) => Disposable' is not assignable to type '(sink: Sink<boolean>, scheduler: Scheduler) => Disposable'. Two different types with this name exist, but they are unrelated.
          Types of parameters 'scheduler' and 'scheduler' are incompatible.
            Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.

ERROR in ./src/bootstrap.ts
(19,40): error TS2345: Argument of type 'Stream<VNode<Node, VNodeProps<Element, VNodeEvents<Element, ElementEventMap>>>>' is not assignable to parameter of type 'Stream<VNode<Node, VNodeProps<Element, VNodeEvents<Element, ElementEventMap>>>>'.
  Types of property 'run' are incompatible.
    Type '(sink: Sink<VNode<Node, VNodeProps<Element, VNodeEvents<Element, ElementEventMap>>>>, scheduler: ...' is not assignable to type '(sink: Sink<VNode<Node, VNodeProps<Element, VNodeEvents<Element, ElementEventMap>>>>, scheduler: ...'. Two different types with this name exist, but they are unrelated.
      Types of parameters 'scheduler' and 'scheduler' are incompatible.
        Type 'Scheduler' is not assignable to type 'Scheduler'. Two different types with this name exist, but they are unrelated.
          Property 'now' is missing in type 'Scheduler'.

Versions of packages used:

motorcycle/[email protected]
motorcycle/[email protected]
motorcycle/[email protected]
motorcycle/[email protected]
motorcycle/[email protected]

--

Downgrading the dependencies to their prior versions solves the issue but is not a viable solution.

@motorcycle/dom

Built on mostly-dom it should only export functions that are related to the DOM.

API needs to be discussed and broken down into issues

feat: switchCombine

export function switchCombine<A>(stream: Stream<Array<Stream<A>>>): Stream<Array<A>>

• must accept ArrayLike and ReadonlyArray

Create a website

Website content:

• Blog
• Case studies
• E-books
• Whitepapers
• Advanced guides
• Infographics

feat: run

reimplement @motorcycle/run using @motocycle/types and @motorcycle/stream 1.0

Rename dragstartEvent to dragStartEvent

docs: Code of Conduct

@motorcycle/mostly-dom

Implement a small wrapper library using @motorcycle/dom that makes use of mostly-dom.

• isolate
• function createDomComponent(rootElement: Element, vNode$: Stream<VNode>): DomSource

feat: hold

hold:: Stream a -> Stream a

previous work https://github.com/mostjs/hold

switchMap not exported

switchMap is missing in the index re-export file: https://github.com/motorcyclets/motorcycle/blob/master/packages/stream/src/combinators/index.ts

Revisit commit message conventions in package.json

Currently we're using angular style commit messages in our NPM scripts. With #220 there will be almost no viable need for these style of commit messages and they should likely be removed.

feat: switchMerge

export function switchMerge<A>(streams$: Stream<Array<Stream<A>>): Stream<A>

• must accept ArrayLike and ReadonlyArray