Ajeeb Signals

Signals system for Ajeeb, based on [ES6 Generators][generators]. This package is intended to unite and supersede [@ajeeb/coroutines][ajeeb-coro] and [@ajeeb/input][ajeeb-input].

This package is a work in progress. Use at your own risk.

Overview

A signal is an object that represents a stream of events, a suspension point for coroutines, and a store of value. The four things you can do with a signal are:

emit* a value through a signal
await* a signal's emission in a coroutine
read* a signal's most recently emitted value
subscribe* to a signal's emissions with a callback

These operations turn out to be really effective building blocks for the kind of asynchronous code that makes up the playful systems Ajeeb is designed for.

$3

#### Main API
``js
const signal = new Signal()

// run coroutine up to its first yield then await the signal
go(function* () {
// ...

// await signal's emission, coroutine will not run
// until signal.emit is called
const x = yield signal
})

// ... elsewhere

// emit the signal to unblock any awaiting coroutines
signal.emit(9)

// read the most recent emitted value any any time
signal.value // => 9

// subscribe to a signal with a conventional callback
signal.on(v => ...)
`

#### Update Loop
`js
const frame = new Signal()

// Ajeeb is agnostic to the graphics frameworks you use
const object = framework.makeObject(...)

go(function*(){
while(true) {
delta = yield frame
object.rotation.x += delta
}
})

// emit frame signal once per frame
let lastTime = 0
function tick(time) {
requestAnimationFrame(tick)
frame.emit((time - lastTime) / 1000)
lastTime = time
}
`

#### DOM Events
`js
const mouse = Signal.event(document.body, "mousepressed")

go(function* () {
const eventData = yield mouse
console.log('clicked', eventData.clientX, eventData.clientY)
})
`

#### Combinators
`js
const timeout = new Signal()
setTimeout(timeout.emit, 5000)

const click = new Signal()
const button = document.createElement('button')
button.value = "five seconds to click me!"
document.body.appendChild(button)
button.addEventListener('click', click.emit)

go(function* () {
yield* first(timeout, click)
// this code will not run until one of timeout or click has emitted
if(timeout.emitted) {
console.log("too slow!")
} else if(click.emitted) {
console.log("you clicked me!")
}
document.body.removeChild(button)
})
`

Other Systems

$3

Historically the Ajeeb system had a [coroutine][ajeeb-coro] system which provided a [Schedule][ajeeb-schedule] to contain and run coroutines and an [input][ajeeb-input] system to manage input. This was used to great effect in the many places Ajeeb was deployed but had its limitations. The semantics of the schedule were that yield would pause coroutines until the next tick, which meant to await long running asynchronous operations you were forced to poll a value once per frame. Also, managing and passing around a Schedule instance was messy.

Ajeeb Signals can seamlessly consume callback and [Promise][js-promises]-based APIs, which Ajeeb Coroutines could not. The lack of a schedule makes client code cleaner and certain edge cases much easier to implement.

$3

Signals could conceivably be built on [JavaScript's Promises][js-promises] but they are limited in two ways

1. Little control over execution order

We need rock solid guarantees of determinism and code execution order for these systems to be usable as foundational abstractions. Promises are scheduled by the JavaScript host event loop and the exact order of evaluation between scheduled promises is not defined. This is OK when you're waiting on things like network requests but intolerable for many of the interesting use cases Signals can address, namely waiting on coroutines and other asynchronous code.

2. No way to cancel a Promise

Being able to cancel a waiting coroutine and allow it to clean up after itself turns out to be a critical feature of asynchronous systems -- and is often missing. Ajeeb Signals leverage JavaScript's [try/finally][js-try-finally] machinery to enable this with minimal ceremony, but Promises simply cannot be cancelled.

$3

JavaScript is built on the notion of "events" and C# even has them [built into the language][csharp-events]. They are similar so Ajeeb Signals in that you can emit values to through them but, critically, they cannot be awaited, making them less useful in coroutines or for the construction of state machines.

$3

[Godot has signals][godot-signals] and since 4.0 they are awaitable in coroutines, making them very similar to Ajeeb's signals. A difference is that in Godot signals are part of a larger engine, with object-oriented semantics and other organizational ideas, where in Ajeeb signals and coroutines are meant to be the main organizational principles that everything else is built on.

Legal and Attribution

Ajeeb is free and unencumbered software released into the public domain under the terms of the CC0 1.0 UNIVERSAL license.

Attribution is appreciated but not required. When attributing a mention to the effect of "This project makes use of Ajeeb, originally by Ramsey Nasser" and/or a link to https://ajeeb.games/` is sufficient.

Author's Intent

While this software may legally be used by anyone, it is not for everyone.

This software is the result of a great deal of joyful labor on the part of the author, and it is shared freely in the hope that individuals, students, artists, and worker cooperatives will benefit from its use and study in any capacity, commercial and otherwise. The author made this for you.

It is absolutely not intended for use in service of capital, in pursuit of profit for a minority off the labor of others, or by organizations that differentiate their owners and their workers.

If you own such an organization, know that the author believes that you are a bad person, and that you should step aside and allow your enterprise to be run democratically by your employees with equal stake and say in its management. The author did not make this for you, and holds you in contempt.

If you work for such an organization, know that the author believes that you are being exploited, and that you should start organizing towards converting your workplace into a cooperative or unionizing at the very least. The author is on your side, hopes this software lightens the burden of your labor.

We have nothing to lose but our chains and a better world is possible.

---

¹ There are plans for a fourth operation -- to subscribe to a signal using a conventional callback

[generators]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*
[ajeeb-input]: https://ajeeb.games/js/input/
[ajeeb-coro]: https://ajeeb.games/js/coroutines/
[godot-signals]: https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html
[csharp-events]: https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/events/
[js-promises]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
[js-try-finally]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch
[ajeeb-schedule]: https://ajeeb.games/js/coroutines/classes/Schedule.html