lib0 1.0.0-rc.21 → 1.0.0-rc.23

package/src/delta/rdt.js

@@ -25,7 +25,9 @@
  * back as a fresh change on its side. A fix on one side and a fix on the other are concurrent, so they
  * are rebased against each other: the pending pair `{ a, b }` is run through `transformer.apply`, whose
  * machinery already transposes the two sides. This repeats until neither side reports a fix, so fixes
- * must converge to a fixpoint (a well-behaved RDT applies them idempotently).
+ * must converge to a fixpoint (a well-behaved RDT applies them idempotently). All of this fix traffic
+ * is applied with the {@link correctionOrigin} origin, while an ordinary mapped change carries the binding
+ * itself — see the "Origins" section of {@link RDT}.
  *
  * On creation a binding first **synchronizes the initial state**: `a`'s current state (`a.delta`)
  * is projected through the transformer, and the projection is diffed against `b`'s current state
@@ -87,6 +89,12 @@ export { $domDelta, domRDT } from './rdt/dom.js'
  * it just received. The `origin` argument to `applyDelta` is optional and defaults to `null` (an
  * anonymous/local change); the emitted event always carries whatever value was supplied.
  *
+ * A {@link Binding} distinguishes the two kinds of changes it produces. An ordinary change mapped
+ * over from the other side carries the binding itself as its origin. A change that adjusts a side's
+ * own earlier change after the fact — a fix returned by the opposite RDT transformed back, or a
+ * transformer self-heal — carries {@link correctionOrigin}, so a consumer that applied a delta can recognise
+ * that (part of) its change was reverted or amended.
+ *
  * ## `Delta` vs `DeltaBuilder`
  *
  * The interface is parameterized by a {@link import('./delta.js').DeltaConf DeltaConf} (like a
@@ -124,15 +132,30 @@ export const $rdt = /** @type {Schema<RDT<any>>} */ (/* @__PURE__ */ s.$custom(o
   typeof o.destroy === 'function'
 ))
 
+/**
+ * The {@link RDT origin} carried by every change a {@link Binding} applies as an after-the-fact
+ * adjustment to a side's own change: a fix returned by the opposite RDT's `applyDelta` transformed back
+ * onto the side that produced the original change, a transformer self-heal (including during the
+ * initial-state sync), and every later round of the fix-convergence loop (fixes of fixes). A "fix"
+ * covers invariant corrections as well as rebased concurrent edits (see `./rdt/dom.js`). An ordinary
+ * mapped change carries the binding itself instead — see the "Origins" section of {@link RDT}. The
+ * value is a plain string, so `origin === 'correction'` works without importing this constant.
+ *
+ * @type {'correction'}
+ */
+export const correctionOrigin = 'correction'
+
 /**
  * Propagate a pair of concurrent changes between the two sides of `binding` until they converge.
  *
  * `ta` / `tb` are changes that have ALREADY been applied to `a` / `b` (an incoming `'delta'`, or a fix
  * returned by a previous `applyDelta`). Each is mapped onto the other side via the transformer —
  * `apply` rebases the two against each other — and the mapped results are applied, which may yield
- * further RDT fixes. We repeat until neither side reports a fix. Every change it applies to either side
- * uses the `binding` itself as its {@link RDT origin} — from each side's perspective the binding is what
- * produced the mapped change.
+ * further RDT fixes. We repeat until neither side reports a fix. `aOrigin` / `bOrigin` are the
+ * {@link RDT origins} for the first round's applications: the side receiving the ordinary mapped
+ * change is handed the `binding` itself, while the side that produced the triggering change only ever
+ * receives adjustments (a transformer self-heal), tagged {@link correctionOrigin}. After the first round
+ * every applied change derives from a fix, so both origins become {@link correctionOrigin}.
  *
  * `ta`/`tb` are shared read deltas (an event payload, or a fix that was also written into the producing
  * RDT's state), so they are {@link delta.cloneDeep deep-cloned} into private builders before the
@@ -143,15 +166,19 @@ export const $rdt = /** @type {Schema<RDT<any>>} */ (/* @__PURE__ */ s.$custom(o
  * @param {Binding<A,B>} binding
  * @param {any} ta change already applied on `a` — a shared read delta (event payload or a fix), or `null`
  * @param {any} tb change already applied on `b` — a shared read delta (event payload or a fix), or `null`
+ * @param {any} [aOrigin] origin for the first-round application onto `a`; defaults to {@link correctionOrigin}
+ * @param {any} [bOrigin] origin for the first-round application onto `b`; defaults to {@link correctionOrigin}
  */
-const propagate = (binding, ta, tb) => {
+const propagate = (binding, ta, tb, aOrigin = correctionOrigin, bOrigin = correctionOrigin) => {
   while ((ta != null && !ta.isEmpty()) || (tb != null && !tb.isEmpty())) {
     const tres = binding.t.apply(dt.createTransformResult(
       ta != null ? delta.cloneDeep(ta) : null,
       tb != null ? delta.cloneDeep(tb) : null
     ))
-    ta = tres.a != null ? binding.a.applyDelta(tres.a, binding) : null
-    tb = tres.b != null ? binding.b.applyDelta(tres.b, binding) : null
+    ta = tres.a != null ? binding.a.applyDelta(tres.a, aOrigin) : null
+    tb = tres.b != null ? binding.b.applyDelta(tres.b, bOrigin) : null
+    aOrigin = correctionOrigin
+    bOrigin = correctionOrigin
   }
 }
 
@@ -197,14 +224,16 @@ export class Binding {
      */
     this.b = b
     this._mux = mux.createMutex()
-    this._achanged = this.a.on('delta', d => this._mux(() => propagate(this, d, null)))
-    this._bchanged = this.b.on('delta', d => this._mux(() => propagate(this, null, d)))
+    this._achanged = this.a.on('delta', d => this._mux(() => propagate(this, d, null, correctionOrigin, this)))
+    this._bchanged = this.b.on('delta', d => this._mux(() => propagate(this, null, d, this, correctionOrigin)))
     this.a.on('destroy', this.destroy)
     this.b.on('destroy', this.destroy)
     // Sync the initial state. `a` is the source of truth: project its current state through the
     // transformer (`applyA`) — which also yields any self-heal correction for `a` (`tres.a`) — then
     // diff the projection against `b`'s current state and apply the difference so `b` ends up
     // matching `a`'s projection. Any fixes the two sides report are reconciled via `propagate`.
+    // The self-heal onto `a` adjusts a's own state, so it is a `correction`; the diff onto `b` is an
+    // ordinary binding-produced change.
     // NOTE: `delta.diff` is content-only (it excludes marks), so cursor marks present on `a` at bind
     // time are NOT transferred to `b` here; marks ride only on subsequent live `applyA`/`applyB`.
     // Wrapped in the mutex so these `applyDelta` calls don't echo back through the listeners above.
@@ -214,7 +243,7 @@ export class Binding {
       // transformer — which rebases its input in place — projects it. A shallow `clone` would still share
       // those frozen children and corrupt / fail on the live state (see `delta.cloneDeep`).
       const tres = this.t.applyA(delta.cloneDeep(this.a.delta))
-      const fa = tres.a ? this.a.applyDelta(tres.a, this) : null
+      const fa = tres.a ? this.a.applyDelta(tres.a, correctionOrigin) : null
       // `diff` shares nested children with `tres.b` by default, and `tres.b` is a (possibly stateful)
       // transformer's output that may still alias its internal state — so `clone` keeps the diff
       // independent, since it is then applied into `b` (which freezes it) and propagated onward.

package/src/diff.js

@@ -77,7 +77,7 @@ export const simpleDiff = simpleDiffString
  *
  * @param {Array<T>} a The old version of the array
  * @param {Array<T>} b The updated version of the array
- * @param {function(T, T):boolean} [compare]
+ * @param {(a: T, b: T) => boolean} [compare]
  * @return {SimpleDiff<Array<T>>} The diff description.
  */
 export const simpleDiffArray = (a, b, compare = equalityStrict) => {

package/src/encoding.js

@@ -53,7 +53,7 @@ export class Encoder {
 export const createEncoder = () => new Encoder()
 
 /**
- * @param {function(Encoder):void} f
+ * @param {(encoder: Encoder) => void} f
  */
 export const encode = (f) => {
   const encoder = createEncoder()
@@ -622,7 +622,7 @@ export const writeAny = (encoder, data) => {
  */
 export class RleEncoder extends Encoder {
   /**
-   * @param {function(Encoder, T):void} writer
+   * @param {(encoder: Encoder, value: T) => void} writer
    */
   constructor (writer) {
     super()

package/src/environment.common.js

@@ -0,0 +1,41 @@
+/**
+ * Environment detection primitives shared by `environment.js` and `storage.js`.
+ *
+ * Internal module (not exported in `package.json`) — it exists so that `storage.js` can check
+ * `isBrowser` without importing `environment.js`, which imports `storage.js` (circular import).
+ */
+
+/* c8 ignore next */
+export const isNode = /* @__PURE__ */(() => typeof process !== 'undefined' && process.release && /node|io\.js/.test(process.release.name) && Object.prototype.toString.call(typeof process !== 'undefined' ? process : 0) === '[object process]')()
+
+/**
+ * True iff this script is running in deno
+ * @type {boolean}
+ */
+/* c8 ignore next 2 */
+// @ts-ignore
+export const isDeno = /* @__PURE__ */(() => typeof Deno !== 'undefined')()
+
+/* c8 ignore start */
+export const globalScope = /* @__PURE__ */(() =>/** @type {any} */ (typeof globalThis !== 'undefined'
+  ? globalThis
+  : typeof window !== 'undefined'
+    ? window
+    // @ts-ignore
+    : typeof global !== 'undefined' ? global : {}))()
+/* c8 ignore stop */
+
+/**
+ * True iff this script is running in a browser-family environment — either a DOM main
+ * thread (`window` + `document`) or a WebWorker / ServiceWorker (a `WorkerGlobalScope`,
+ * which has `btoa`/`atob`/`fetch` but no DOM). Excludes Node and Deno.
+ * @type {boolean}
+ */
+/* c8 ignore next */
+export const isBrowser = /* @__PURE__ */(() =>
+  !isNode && !isDeno && (
+    (typeof window !== 'undefined' && typeof document !== 'undefined') ||
+    // WebWorker / ServiceWorker: no window/document, but a worker global scope
+    (typeof globalScope.WorkerGlobalScope !== 'undefined' && globalScope.self instanceof globalScope.WorkerGlobalScope)
+  )
+)()

package/src/environment.js

@@ -9,20 +9,10 @@ import * as string from './string.js'
 import * as conditions from './conditions.js'
 import * as storage from './storage.js'
 import * as f from './function.js'
+import { isNode, globalScope } from './environment.common.js'
 
-/* c8 ignore next */
-export const isNode = /* @__PURE__ */(() => typeof process !== 'undefined' && process.release && /node|io\.js/.test(process.release.name) && Object.prototype.toString.call(typeof process !== 'undefined' ? process : 0) === '[object process]')()
-
-/**
- * True iff this script is running in deno
- * @type {boolean}
- */
-/* c8 ignore next 2 */
-// @ts-ignore
-export const isDeno = /* @__PURE__ */(() => typeof Deno !== 'undefined')()
+export { isNode, isDeno, isBrowser } from './environment.common.js'
 
-/* c8 ignore next */
-export const isBrowser = /* @__PURE__ */(() => typeof window !== 'undefined' && typeof document !== 'undefined' && !isNode)()
 /* c8 ignore next */
 export const isMac = /* @__PURE__ */(() => typeof navigator !== 'undefined' ? /Mac/.test(navigator.platform) : false)()
 
@@ -168,13 +158,4 @@ export const supportsColor = /* @__PURE__ */(() => forceColor || (
 ))()
 /* c8 ignore stop */
 
-/* c8 ignore start */
-const globalScope = /* @__PURE__ */(() =>/** @type {any} */ (typeof globalThis !== 'undefined'
-  ? globalThis
-  : typeof window !== 'undefined'
-    ? window
-    // @ts-ignore
-    : typeof global !== 'undefined' ? global : {}))()
-/* c8 ignore stop */
-
 export { globalScope as global }

package/src/error.js

@@ -12,8 +12,12 @@
 export const create = s => new Error(s)
 
 /**
+ * `@type` (not `@param`/`@return`) is required for the `never` return to affect control-flow
+ * analysis — a call to a never-returning function only terminates a code path if the callee is
+ * declared with an explicit type annotation.
+ *
  * @throws {Error}
- * @return {never}
+ * @type {() => never}
  */
 /* c8 ignore next 3 */
 export const methodUnimplemented = () => {
@@ -22,7 +26,7 @@ export const methodUnimplemented = () => {
 
 /**
  * @throws {Error}
- * @return {never}
+ * @type {() => never}
  */
 /* c8 ignore next 3 */
 export const unexpectedCase = () => {
@@ -30,7 +34,9 @@ export const unexpectedCase = () => {
 }
 
 /**
- * @param {boolean} property
- * @return {asserts property is true}
+ * `@type` (not `@param`/`@return`) is required — an assertion signature only narrows if the
+ * callee is declared with an explicit type annotation.
+ *
+ * @type {(property: boolean) => asserts property is true}
  */
 export const assert = property => { if (!property) throw create('Assert failed') }

package/src/eventloop.js

@@ -21,7 +21,7 @@ const _runQueue = () => {
 }
 
 /**
- * @param {function():void} f
+ * @param {() => void} f
  */
 export const enqueue = f => {
   queue.push(f)
@@ -36,7 +36,7 @@ export const enqueue = f => {
  */
 
 /**
- * @param {function(number):void} clearFunction
+ * @param {(timeoutId: number) => void} clearFunction
  */
 const createTimeoutClass = clearFunction => class TT {
   /**
@@ -73,7 +73,7 @@ export const interval = (timeout, callback) => new Interval(setInterval(callback
 export const Animation = createTimeoutClass(arg => typeof requestAnimationFrame !== 'undefined' && cancelAnimationFrame(arg))
 
 /**
- * @param {function(number):void} cb
+ * @param {(timestamp: number) => void} cb
  * @return {TimeoutObject}
  */
 /* c8 ignore next */

package/src/function.js

@@ -30,7 +30,7 @@ export const nop = () => {}
 
 /**
  * @template T
- * @param {function():T} f
+ * @param {() => T} f
  * @return {T}
  */
 export const apply = f => f()

package/src/indexeddb.js

@@ -26,7 +26,7 @@ export const rtop = request => promise.create((resolve, reject) => {
 
 /**
  * @param {string} name
- * @param {function(IDBDatabase):any} initDB Called when the database is first created
+ * @param {(db: IDBDatabase) => any} initDB Called when the database is first created
  * @return {Promise<IDBDatabase>}
  */
 export const openDB = (name, initDB) => promise.create((resolve, reject) => {
@@ -193,7 +193,7 @@ export const getAllKeysValues = (store, range, limit) =>
 
 /**
  * @param {any} request
- * @param {function(IDBCursorWithValue):void|boolean|Promise<void|boolean>} f
+ * @param {(cursor: IDBCursorWithValue) => void|boolean|Promise<void|boolean>} f
  * @return {Promise<void>}
  */
 const iterateOnRequest = (request, f) => promise.create((resolve, reject) => {
@@ -214,7 +214,7 @@ const iterateOnRequest = (request, f) => promise.create((resolve, reject) => {
  * Iterate on keys and values
  * @param {IDBObjectStore} store
  * @param {IDBKeyRange|null} keyrange
- * @param {function(any,any):void|boolean|Promise<void|boolean>} f Callback that receives (value, key)
+ * @param {(value: any, key: any) => void|boolean|Promise<void|boolean>} f Callback that receives (value, key)
  * @param {'next'|'prev'|'nextunique'|'prevunique'} direction
  */
 export const iterate = (store, keyrange, f, direction = 'next') =>
@@ -225,7 +225,7 @@ export const iterate = (store, keyrange, f, direction = 'next') =>
  *
  * @param {IDBObjectStore} store
  * @param {IDBKeyRange|null} keyrange
- * @param {function(any):void|boolean|Promise<void|boolean>} f callback that receives the key
+ * @param {(key: any) => void|boolean|Promise<void|boolean>} f callback that receives the key
  * @param {'next'|'prev'|'nextunique'|'prevunique'} direction
  */
 export const iterateKeys = (store, keyrange, f, direction = 'next') =>

package/src/indexeddbV2.js

@@ -28,7 +28,7 @@ export const bindPledge = (p, request) => {
 
 /**
  * @param {string} name
- * @param {function(IDBDatabase):any} initDB Called when the database is first created
+ * @param {(db: IDBDatabase) => any} initDB Called when the database is first created
  * @return {pledge.PledgeInstance<IDBDatabase>}
  */
 export const openDB = (name, initDB) => {
@@ -194,7 +194,7 @@ export const getAllKeysValues = (store, range, limit) => pledge.createWithDepend
 /**
  * @param {pledge.PledgeInstance<void>} p
  * @param {any} request
- * @param {function(IDBCursorWithValue):void|boolean|Promise<void|boolean>} f
+ * @param {(cursor: IDBCursorWithValue) => void|boolean|Promise<void|boolean>} f
  */
 const iterateOnRequest = (p, request, f) => {
   request.onerror = p.cancel.bind(p)
@@ -215,7 +215,7 @@ const iterateOnRequest = (p, request, f) => {
  * Iterate on keys and values
  * @param {pledge.Pledge<IDBObjectStore>} store
  * @param {pledge.Pledge<IDBKeyRange|null>} keyrange
- * @param {function(any,any):void|boolean|Promise<void|boolean>} f Callback that receives (value, key)
+ * @param {(value: any, key: any) => void|boolean|Promise<void|boolean>} f Callback that receives (value, key)
  * @param {'next'|'prev'|'nextunique'|'prevunique'} direction
  */
 export const iterate = (store, keyrange, f, direction = 'next') => pledge.createWithDependencies((p, store, keyrange) => {
@@ -227,7 +227,7 @@ export const iterate = (store, keyrange, f, direction = 'next') => pledge.create
  *
  * @param {pledge.Pledge<IDBObjectStore>} store
  * @param {pledge.Pledge<IDBKeyRange|null>} keyrange
- * @param {function(any):void|boolean|Promise<void|boolean>} f callback that receives the key
+ * @param {(key: any) => void|boolean|Promise<void|boolean>} f callback that receives the key
  * @param {'next'|'prev'|'nextunique'|'prevunique'} direction
  */
 export const iterateKeys = (store, keyrange, f, direction = 'next') => pledge.createWithDependencies((p, store, keyrange) => {

package/src/iterator.js

@@ -7,7 +7,7 @@
 /**
  * @template T,R
  * @param {Iterator<T>} iterator
- * @param {function(T):R} f
+ * @param {(v: T) => R} f
  * @return {IterableIterator<R>}
  */
 export const mapIterator = (iterator, f) => ({
@@ -23,7 +23,7 @@ export const mapIterator = (iterator, f) => ({
 
 /**
  * @template T
- * @param {function():IteratorResult<T>} next
+ * @param {() => IteratorResult<T>} next
  * @return {IterableIterator<T>}
  */
 export const createIterator = next => ({
@@ -40,7 +40,7 @@ export const createIterator = next => ({
 /**
  * @template T
  * @param {Iterator<T>} iterator
- * @param {function(T):boolean} filter
+ * @param {(v: T) => boolean} filter
  */
 export const iteratorFilter = (iterator, filter) => createIterator(() => {
   let res
@@ -53,7 +53,7 @@ export const iteratorFilter = (iterator, filter) => createIterator(() => {
 /**
  * @template T,M
  * @param {Iterator<T>} iterator
- * @param {function(T):M} fmap
+ * @param {(v: T) => M} fmap
  */
 export const iteratorMap = (iterator, fmap) => createIterator(() => {
   const { done, value } = iterator.next()

package/src/list.js

@@ -45,7 +45,7 @@ export class List {
   }
 
   /**
-   * @param {function(N):any} f
+   * @param {(node: N) => any} f
    */
   forEach (f) {
     forEach(this, f)
@@ -53,7 +53,7 @@ export class List {
 
   /**
    * @template M
-   * @param {function(N):M} f
+   * @param {(node: N) => M} f
    * @return {Array<M>}
    */
   map (f) {
@@ -206,7 +206,7 @@ export const popEnd = list =>
  * @template M
  *
  * @param {List<N>} list
- * @param {function(N):M} f
+ * @param {(node: N) => M} f
  * @return {Array<M>}
  */
 export const map = (list, f) => {
@@ -232,7 +232,7 @@ export const toArray = list => map(list, id)
 /**
  * @template {ListNode} N
  * @param {List<N>} list
- * @param {function(N):any} f
+ * @param {(node: N) => any} f
  */
 export const forEach = (list, f) => {
   let n = list.start

package/src/logging.common.js

@@ -16,7 +16,7 @@ export const UNCOLOR = symbol.create()
 
 /* c8 ignore start */
 /**
- * @param {Array<undefined|string|Symbol|Object|number|function():any>} args
+ * @param {Array<undefined|string|Symbol|Object|number|(() => any)>} args
  * @return {Array<string|object|number|undefined>}
  */
 export const computeNoColorLoggingArgs = args => {
@@ -58,9 +58,9 @@ let lastLoggingTime = time.getUnixTime()
 
 /* c8 ignore start */
 /**
- * @param {function(...any):void} _print
+ * @param {(...args: Array<any>) => void} _print
  * @param {string} moduleName
- * @return {function(...any):void}
+ * @return {(...args: Array<any>) => void}
  */
 export const createModuleLogger = (_print, moduleName) => {
   const color = loggingColors[nextColor]

package/src/logging.js

@@ -32,7 +32,7 @@ const _browserStyleMap = {
 }
 
 /**
- * @param {Array<string|Symbol|Object|number|function():any>} args
+ * @param {Array<string|Symbol|Object|number|(() => any)>} args
  * @return {Array<string|object|number>}
  */
 /* c8 ignore start */
@@ -174,7 +174,7 @@ export const groupEnd = () => {
 }
 
 /**
- * @param {function():Node} createNode
+ * @param {() => Node} createNode
  */
 /* c8 ignore next 2 */
 export const printDom = (createNode) =>
@@ -378,6 +378,6 @@ export const createVConsole = (dom) => new VConsole(dom)
 
 /**
  * @param {string} moduleName
- * @return {function(...any):void}
+ * @return {(...args: Array<any>) => void}
  */
 export const createModuleLogger = (moduleName) => common.createModuleLogger(print, moduleName)

package/src/logging.node.js

@@ -23,7 +23,7 @@ const _nodeStyleMap = {
 
 /* c8 ignore start */
 /**
- * @param {Array<string|undefined|Symbol|Object|number|function():Array<any>>} args
+ * @param {Array<string|undefined|Symbol|Object|number|(() => Array<any>)>} args
  * @return {Array<string|object|number|undefined>}
  */
 const computeNodeLoggingArgs = (args) => {
@@ -137,7 +137,7 @@ export const groupEnd = () => {
 }
 
 /**
- * @param {function():Node} _createNode
+ * @param {() => Node} _createNode
  */
 /* c8 ignore next 2 */
 export const printDom = (_createNode) => {}
@@ -158,7 +158,7 @@ export const createVConsole = (_dom) => {}
 
 /**
  * @param {string} moduleName
- * @return {function(...any):void}
+ * @return {(...args: Array<any>) => void}
  */
 /* c8 ignore next */
 export const createModuleLogger = (moduleName) => common.createModuleLogger(print, moduleName)

package/src/map.js

@@ -44,7 +44,7 @@ export const copy = m => {
  *
  * @function
  * @template {Map<any, any>} MAP
- * @template {MAP extends Map<any,infer V> ? function():V : unknown} CF
+ * @template {MAP extends Map<any,infer V> ? (() => V) : unknown} CF
  * @param {MAP} map
  * @param {MAP extends Map<infer K,any> ? K : unknown} key
  * @param {CF} createT
@@ -66,7 +66,7 @@ export const setIfUndefined = (map, key, createT) => {
  * @template V
  * @template R
  * @param {Map<K,V>} m
- * @param {function(V,K):R} f
+ * @param {(value: V, key: K) => R} f
  * @return {Array<R>}
  */
 export const map = (m, f) => {
@@ -86,7 +86,7 @@ export const map = (m, f) => {
  * @template K
  * @template V
  * @param {Map<K,V>} m
- * @param {function(V,K):boolean} f
+ * @param {(value: V, key: K) => boolean} f
  * @return {boolean}
  */
 export const any = (m, f) => {
@@ -105,7 +105,7 @@ export const any = (m, f) => {
  * @template K
  * @template V
  * @param {Map<K,V>} m
- * @param {function(V,K):boolean} f
+ * @param {(value: V, key: K) => boolean} f
  * @return {boolean}
  */
 export const all = (m, f) => {

package/src/mutex.js

@@ -6,8 +6,8 @@
 
 /**
  * @callback mutex
- * @param {function():void} cb Only executed when this mutex is not in the current stack
- * @param {function():void} [elseCb] Executed when this mutex is in the current stack
+ * @param {() => void} cb Only executed when this mutex is not in the current stack
+ * @param {() => void} [elseCb] Executed when this mutex is in the current stack
  */
 
 /**

package/src/object.js

@@ -37,7 +37,7 @@ export const values = Object.values
 /**
  * @template V
  * @param {{[k:string]:V}} obj
- * @param {function(V,string):any} f
+ * @param {(value: V, key: string) => any} f
  */
 export const forEach = (obj, f) => {
   for (const key in obj) {
@@ -50,7 +50,7 @@ export const forEach = (obj, f) => {
  *
  * @template R
  * @param {Object<string,any>} obj
- * @param {function(any,string):R} f
+ * @param {(value: any, key: string) => R} f
  * @return {Array<R>}
  */
 export const map = (obj, f) => {

package/src/observable.js

@@ -15,7 +15,7 @@ import * as array from './array.js'
  * This is basically a (better typed) duplicate of Observable, which will replace Observable in the
  * next release.
  *
- * @template {{[key in keyof EVENTS]: function(...any):void}} EVENTS
+ * @template {{[key in keyof EVENTS]: (...args: Array<any>) => void}} EVENTS
  */
 export class ObservableV2 {
   constructor () {

package/src/pair.js

@@ -37,14 +37,14 @@ export const createReversed = (right, left) => new Pair(left, right)
 /**
  * @template L,R
  * @param {Array<Pair<L,R>>} arr
- * @param {function(L, R):any} f
+ * @param {(left: L, right: R) => any} f
  */
 export const forEach = (arr, f) => arr.forEach(p => f(p.left, p.right))
 
 /**
  * @template L,R,X
  * @param {Array<Pair<L,R>>} arr
- * @param {function(L, R):X} f
+ * @param {(left: L, right: R) => X} f
  * @return {Array<X>}
  */
 export const map = (arr, f) => arr.map(p => f(p.left, p.right))

package/src/pledge.js

@@ -45,11 +45,11 @@ export class PledgeInstance {
     this._v = null
     this.isResolved = false
     /**
-     * @type {Array<function(Val):void> | null}
+     * @type {Array<(val: Val) => void> | null}
      */
     this._whenResolved = []
     /**
-     * @type {Array<function(CancelReason):void> | null}
+     * @type {Array<(reason: CancelReason) => void> | null}
      */
     this._whenCanceled = []
   }
@@ -93,7 +93,7 @@ export class PledgeInstance {
 
   /**
    * @template R
-   * @param {function(Val):Pledge<R>} f
+   * @param {(val: Val) => Pledge<R>} f
    * @return {PledgeInstance<R>}
    */
   map (f) {
@@ -117,7 +117,7 @@ export class PledgeInstance {
   }
 
   /**
-   * @param {function(Val):void} f
+   * @param {(val: Val) => void} f
    */
   whenResolved (f) {
     if (this.isResolved) {
@@ -187,7 +187,7 @@ export const createWithDependencies = (init, ...deps) => {
 /**
  * @template R
  * @param {Pledge<R>} p
- * @param {function(R):void} f
+ * @param {(res: R) => void} f
  */
 export const whenResolved = (p, f) => {
   if (p instanceof PledgeInstance) {
@@ -199,7 +199,7 @@ export const whenResolved = (p, f) => {
 /**
  * @template {Pledge<unknown>} P
  * @param {P} p
- * @param {P extends PledgeInstance<unknown, infer CancelReason> ? function(CancelReason):void : function(any):void} f
+ * @param {P extends PledgeInstance<unknown, infer CancelReason> ? ((reason: CancelReason) => void) : ((reason: any) => void)} f
  */
 export const whenCanceled = (p, f) => {
   if (p instanceof PledgeInstance) {