@mikrojs/native 0.5.1 → 0.6.0-pr-70.gc88e298

package/CMakeLists.txt

@@ -50,6 +50,7 @@ set(MIKROJS_CORE_SOURCES
     src/mik_repl.cpp
     src/mik_app_config.cpp
     src/mik_udp.cpp
+    src/mik_observable.cpp
 )
 
 add_library(mikrojs STATIC
@@ -80,7 +81,7 @@ endif()
 include(cmake/mikrojs_bytecode.cmake)
 mikrojs_generate_bytecode(
     RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime"
-    MODULES cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared neopixel pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
+    MODULES cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared neopixel observable observable/operators pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
     MODULE_PREFIX "mikrojs"
     SYMBOL_PREFIX "mikrojs"
     TARGET gen_bytecode
@@ -161,6 +162,7 @@ if(BUILD_TESTING)
         test/stream_test.cpp
         test/runtime_recycle_test.cpp
         test/udp_test.cpp
+        test/observable_test.cpp
     )
 
     target_link_libraries(mikrojs_tests PRIVATE mikrojs)

package/include/mikrojs/private.h

@@ -215,6 +215,9 @@ JSModuleDef* mik__result_init(JSContext* ctx);
 /* UDP module (mik_udp.cpp) */
 JSModuleDef* mik__udp_init(JSContext* ctx);
 
+/* Observable module (mik_observable.cpp) */
+JSModuleDef* mik__observable_init(JSContext* ctx);
+
 bool mik__repl_is_evaluating(void);
 
 /* REPL protocol mode (mik_repl.cpp) — used by mik_console.cpp, mik_stdio.cpp */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.5.1",
+  "version": "0.6.0-pr-70.gc88e298",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -56,6 +56,8 @@
     "./runtime/kv/shared": "./runtime/kv/shared.ts",
     "./runtime/kv/types": "./runtime/kv/types.ts",
     "./runtime/neopixel/types": "./runtime/neopixel/types.ts",
+    "./runtime/observable/operators": "./runtime/observable/operators.ts",
+    "./runtime/observable/types": "./runtime/observable/types.ts",
     "./runtime/pin/types": "./runtime/pin/types.ts",
     "./runtime/pwm/types": "./runtime/pwm/types.ts",
     "./runtime/reader/types": "./runtime/reader/types.ts",
@@ -76,7 +78,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.5.1"
+    "@mikrojs/quickjs": "0.6.0-pr-70.gc88e298"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/ble/ble.ts

@@ -1,3 +1,4 @@
+import {Observable} from 'mikrojs/observable'
 import {err, ok} from 'mikrojs/result'
 import {Ble as NativeBle} from 'native:ble'
 
@@ -9,8 +10,9 @@ import type {
   BleError,
   Characteristic,
   CharacteristicProperty,
+  ConnectionInfo,
+  MtuInfo,
   Peripheral,
-  PeripheralEventMap,
   Service,
 } from './types.js'
 import {parseUuid} from './uuid.js'
@@ -140,6 +142,16 @@ function normalizeServices(services: Service[]) {
 
 const native = new NativeBle()
 
+/* Per-event multicast sources backed by a single native.on registration each.
+ * See observable.md → Module integration. */
+const _onConnect = Observable.withEmitters<ConnectionInfo>()
+const _onDisconnect = Observable.withEmitters<ConnectionInfo>()
+const _onMtu = Observable.withEmitters<MtuInfo>()
+
+native.on('connect', (info) => _onConnect.next(info as ConnectionInfo))
+native.on('disconnect', (info) => _onDisconnect.next(info as ConnectionInfo))
+native.on('mtu', (info) => _onMtu.next(info as MtuInfo))
+
 const ble: Ble = {
   get name(): string {
     return native.getName()
@@ -219,13 +231,9 @@ const peripheral: Peripheral = {
     return ok(handle)
   },
 
-  on<K extends keyof PeripheralEventMap>(event: K, listener: PeripheralEventMap[K]) {
-    native.on(event, listener as (...args: unknown[]) => void)
-  },
-
-  off<K extends keyof PeripheralEventMap>(event: K, listener: PeripheralEventMap[K]) {
-    native.off(event, listener as (...args: unknown[]) => void)
-  },
+  onConnect: _onConnect.observable,
+  onDisconnect: _onDisconnect.observable,
+  onMtu: _onMtu.observable,
 }
 
 export {ble, peripheral}

package/runtime/ble/types.ts

@@ -1,3 +1,4 @@
+import type {Observable} from '../observable/types.js'
 import type {Result} from '../result/types.js'
 
 /** Advertising interval range in milliseconds. */
@@ -171,23 +172,15 @@ export interface MtuInfo {
   mtu: number
 }
 
-export interface PeripheralEventMap {
-  connect: (info: ConnectionInfo) => void
-  disconnect: (info: ConnectionInfo) => void
-  mtu: (info: MtuInfo) => void
-}
-
 export interface Peripheral {
   /** Start advertising. Returns a handle whose `stop()` ends this session. */
   advertise(options?: AdvertiseOptions): Promise<Result<AdvertiseHandle, BleError>>
-  /**
-   * Register a listener for a peripheral lifecycle event. Listeners are
-   * called on the JS loop thread in registration order. Safe to register
-   * before calling `advertise()`.
-   */
-  on<K extends keyof PeripheralEventMap>(event: K, listener: PeripheralEventMap[K]): void
-  /** Remove a previously-registered listener. */
-  off<K extends keyof PeripheralEventMap>(event: K, listener: PeripheralEventMap[K]): void
+  /** Emits when a central connects. Subscribers are dispatched on the JS loop thread. */
+  readonly onConnect: Observable<ConnectionInfo>
+  /** Emits when a central disconnects. */
+  readonly onDisconnect: Observable<ConnectionInfo>
+  /** Emits when a connected central renegotiates its ATT MTU. */
+  readonly onMtu: Observable<MtuInfo>
 }
 
 export declare const ble: Ble

package/runtime/internal.d.ts

@@ -25,6 +25,10 @@ declare module 'native:result' {
   export function err<E>(error: E): ErrResult<E>
 }
 
+declare module 'native:observable' {
+  export {Observable} from '@mikrojs/native/runtime/observable/types'
+}
+
 declare module 'native:sys' {
   import type {JsMemoryUsage} from './sys/types.js'
   export function evalScript(code: string): Promise<{value: unknown}>

package/runtime/observable/native-observable.node-shim.ts

@@ -0,0 +1,212 @@
+/* eslint-disable no-console */
+/* console.error inside dispatch matches the mik_call_handler precedent in
+ * the C runtime (log + continue, isolated to that subscriber). */
+
+// Host-side shim for `native:observable`, used only in vitest (Node) where
+// the mikrojs C runtime isn't available. Keep in sync with mik_observable.cpp.
+//
+// Mirrors the locked design in .claude/plans/observable.md:
+// - subscribe() returns a Subscription with unsubscribe() (no AbortSignal)
+// - no error channel — throws caught + logged at the dispatch boundary,
+//   isolated to that subscriber
+// - sync emission allowed
+// - pipe-only composition (operators live in operators.ts)
+// - withEmitters() factory: {observable, next, complete}
+
+class Subscriber<T> {
+  closed = false
+  private next_fn: ((v: T) => void) | undefined
+  private complete_fn: (() => void) | undefined
+  private teardowns: Array<() => void> = []
+
+  constructor(observer: unknown) {
+    if (observer == null) return
+    if (typeof observer === 'function') {
+      this.next_fn = observer as (v: T) => void
+    } else if (typeof observer === 'object') {
+      const o = observer as {next?: (v: T) => void; complete?: () => void}
+      if (typeof o.next === 'function') this.next_fn = o.next
+      if (typeof o.complete === 'function') this.complete_fn = o.complete
+    } else {
+      throw new TypeError('subscribe: observer must be a function, object, undefined, or null')
+    }
+  }
+
+  next(value: T): void {
+    if (this.closed) return
+    if (this.next_fn) {
+      try {
+        this.next_fn(value)
+      } catch (err) {
+        console.error(err)
+      }
+    }
+  }
+
+  complete(): void {
+    if (this.closed) return
+    this.closed = true
+    if (this.complete_fn) {
+      try {
+        this.complete_fn()
+      } catch (err) {
+        console.error(err)
+      }
+    }
+    this.runTeardowns()
+  }
+
+  addTeardown(fn: () => void): void {
+    if (typeof fn !== 'function') {
+      throw new TypeError('addTeardown: argument must be a function')
+    }
+    if (this.closed) {
+      try {
+        fn()
+      } catch (err) {
+        console.error(err)
+      }
+      return
+    }
+    this.teardowns.push(fn)
+  }
+
+  // Used by Subscription.unsubscribe — silent (no observer.complete call).
+  closeSilently(): void {
+    if (this.closed) return
+    this.closed = true
+    this.runTeardowns()
+  }
+
+  private runTeardowns(): void {
+    const list = this.teardowns
+    this.teardowns = []
+    for (let i = list.length - 1; i >= 0; i--) {
+      try {
+        list[i]!()
+      } catch (err) {
+        console.error(err)
+      }
+    }
+  }
+}
+
+class Subscription {
+  constructor(private subscriber: Subscriber<unknown>) {}
+  unsubscribe(): void {
+    this.subscriber.closeSilently()
+  }
+}
+
+type SubscribeCallback<T> = (sub: Subscriber<T>) => void
+
+export class Observable<Ok, Err = never> {
+  // The shim doesn't actually use `_phantom` at runtime; the type parameters are
+  // purely for type-level alignment with the public interface.
+  declare readonly _phantom: [Ok, Err]
+  #cb: SubscribeCallback<unknown>
+
+  constructor(cb: SubscribeCallback<unknown>) {
+    if (typeof cb !== 'function') {
+      throw new TypeError('Observable: constructor requires a function argument')
+    }
+    this.#cb = cb
+  }
+
+  subscribe(observer?: unknown): Subscription {
+    const sub = new Subscriber<unknown>(observer)
+    try {
+      this.#cb(sub)
+    } catch (err) {
+      sub.closeSilently()
+      throw err
+    }
+    return new Subscription(sub)
+  }
+
+  pipe(...ops: Array<(o: Observable<unknown, unknown>) => Observable<unknown, unknown>>) {
+    let current: Observable<unknown, unknown> = this as unknown as Observable<unknown, unknown>
+    for (const op of ops) {
+      if (typeof op !== 'function') {
+        throw new TypeError('pipe: arguments must be operator functions')
+      }
+      current = op(current)
+    }
+    return current
+  }
+
+  static from(src: unknown): Observable<unknown, unknown> {
+    if (src instanceof Observable) return src
+    if (
+      src != null &&
+      (typeof src === 'object' || typeof src === 'function') &&
+      typeof (src as {then?: unknown}).then === 'function'
+    ) {
+      // Promise-shaped
+      return new Observable<unknown>((sub) => {
+        ;(src as PromiseLike<unknown>).then((value) => {
+          if (sub.closed) return
+          sub.next(value)
+          if (sub.closed) return
+          sub.complete()
+        })
+      })
+    }
+    if (
+      src != null &&
+      (typeof src === 'object' || typeof src === 'string') &&
+      typeof (src as {[Symbol.iterator]?: unknown})[Symbol.iterator] === 'function'
+    ) {
+      return new Observable<unknown>((sub) => {
+        for (const value of src as Iterable<unknown>) {
+          if (sub.closed) return
+          sub.next(value)
+        }
+        if (!sub.closed) sub.complete()
+      })
+    }
+    throw new TypeError('Observable.from: source must be a Promise, Iterable, or Observable')
+  }
+
+  static withEmitters<Ok, Err = never>(): {
+    observable: Observable<Ok, Err>
+    next: (value: unknown) => void
+    complete: () => void
+  } {
+    const subs: Array<Subscriber<unknown>> = []
+    let completed = false
+
+    const observable = new Observable<unknown>((sub) => {
+      if (completed) {
+        sub.complete()
+        return
+      }
+      subs.push(sub)
+      sub.addTeardown(() => {
+        const i = subs.indexOf(sub)
+        if (i >= 0) subs.splice(i, 1)
+      })
+    })
+
+    const next = (value: unknown) => {
+      if (completed) return
+      // Snapshot to be resilient against mid-dispatch unsubscribes.
+      const snapshot = subs.slice()
+      for (const s of snapshot) {
+        if (!s.closed) s.next(value)
+      }
+    }
+
+    const complete = () => {
+      if (completed) return
+      completed = true
+      const snapshot = subs.slice()
+      subs.length = 0
+      for (const s of snapshot) {
+        if (!s.closed) s.complete()
+      }
+    }
+
+    return {observable: observable as unknown as Observable<Ok, Err>, next, complete}
+  }
+}

package/runtime/observable/observable.ts

@@ -0,0 +1 @@
+export {Observable} from 'native:observable'

package/runtime/observable/operators.ts

@@ -0,0 +1,129 @@
+/* eslint-disable no-console */
+/* console.error inside operator dispatch is intentional: it matches the
+ * existing mik_call_handler precedent in the C layer (log + continue rather
+ * than panic). See .claude/plans/observable.md → Errors section. */
+
+/* Operators for `Observable.pipe(...)`. Each is a factory returning a
+ * function `(source) => Observable`. Composition is pure pipe — no method
+ * chaining on Observable itself.
+ *
+ * M0 scope: operators apply to non-fallible streams (`Err = never`). For
+ * fallible streams (`Observable<Ok, Err>` with Err != never), corresponding
+ * Result-aware operators (`mapOk`, `filterOk`, ...) ship when a concrete
+ * consumer asks. Today no module produces fallible event streams.
+ *
+ * See `.claude/plans/observable.md` for the full design.
+ */
+
+/* Importing from `mikrojs/observable` (not `native:observable`) so this
+ * module typechecks from any package that already re-exports it. At runtime
+ * `mikrojs/observable` resolves to the bytecode bundle which re-exports the
+ * native class; at typecheck it resolves to the ambient `declare class` in
+ * runtime/observable/types.ts. */
+import {Observable} from 'mikrojs/observable'
+
+/* Map values through a transform. Throws inside `fn` are caught at the
+ * dispatch boundary; the bad value is dropped for that subscription, others
+ * are unaffected. */
+export const map =
+  <A, B>(fn: (value: A) => B) =>
+  (source: Observable<A>): Observable<B> =>
+    new Observable<B>((sub) => {
+      const upstream = source.subscribe({
+        next: (value) => {
+          let next: B
+          try {
+            next = fn(value)
+          } catch (err) {
+            console.error(err)
+            return
+          }
+          sub.next(next)
+        },
+        complete: () => sub.complete(),
+      })
+      sub.addTeardown(() => upstream.unsubscribe())
+    })
+
+/* Pass through values matching `pred`. `pred` errors are caught + logged. */
+export const filter =
+  <A>(pred: (value: A) => boolean) =>
+  (source: Observable<A>): Observable<A> =>
+    new Observable<A>((sub) => {
+      const upstream = source.subscribe({
+        next: (value) => {
+          let keep: boolean
+          try {
+            keep = pred(value)
+          } catch (err) {
+            console.error(err)
+            return
+          }
+          if (keep) sub.next(value)
+        },
+        complete: () => sub.complete(),
+      })
+      sub.addTeardown(() => upstream.unsubscribe())
+    })
+
+/* Take at most n values, then complete. n <= 0 completes immediately. */
+export const take =
+  (n: number) =>
+  <A>(source: Observable<A>): Observable<A> =>
+    new Observable<A>((sub) => {
+      if (n <= 0) {
+        sub.complete()
+        return
+      }
+      let remaining = n
+      const upstream = source.subscribe({
+        next: (value) => {
+          if (remaining <= 0) return
+          remaining--
+          sub.next(value)
+          if (remaining === 0) sub.complete()
+        },
+        complete: () => sub.complete(),
+      })
+      sub.addTeardown(() => upstream.unsubscribe())
+    })
+
+/* Stop emitting when `notifier` emits its first value. Notifier completing
+ * without emitting is NOT a trigger — primary keeps going. */
+export const takeUntil =
+  (notifier: Observable<unknown, unknown>) =>
+  <A>(source: Observable<A>): Observable<A> =>
+    new Observable<A>((sub) => {
+      const upstream = source.subscribe({
+        next: (value) => sub.next(value),
+        complete: () => sub.complete(),
+      })
+      const notifierSub = notifier.subscribe({
+        next: () => sub.complete(),
+      })
+      sub.addTeardown(() => {
+        notifierSub.unsubscribe()
+        upstream.unsubscribe()
+      })
+    })
+
+/* Run `fn` when the subscription ends for any reason (unsubscribe or
+ * natural completion). Throws inside `fn` are caught + logged so other
+ * teardowns still run. RxJS naming. */
+export const finalize =
+  (fn: () => void) =>
+  <A>(source: Observable<A>): Observable<A> =>
+    new Observable<A>((sub) => {
+      const upstream = source.subscribe({
+        next: (value) => sub.next(value),
+        complete: () => sub.complete(),
+      })
+      sub.addTeardown(() => {
+        upstream.unsubscribe()
+        try {
+          fn()
+        } catch (err) {
+          console.error(err)
+        }
+      })
+    })

package/runtime/observable/types.ts

@@ -0,0 +1,80 @@
+import type {Result} from '../result/types.js'
+
+/* Push-shaped, composable event stream. See observable.md (worktree branch)
+ * for the full design. */
+
+export type NextArg<Ok, Err> = [Err] extends [never] ? Ok : Result<Ok, Err>
+
+export type Observer<Ok, Err = never> = [Err] extends [never]
+  ? {next?: (value: Ok) => void; complete?: () => void}
+  : {next?: (value: Result<Ok, Err>) => void; complete?: () => void}
+
+export type NextFn<Ok, Err = never> = [Err] extends [never]
+  ? (value: Ok) => void
+  : (value: Result<Ok, Err>) => void
+
+export interface Subscriber<Ok, Err = never> {
+  next(value: NextArg<Ok, Err>): void
+  complete(): void
+  addTeardown(fn: () => void): void
+  readonly closed: boolean
+}
+
+export type SubscribeCallback<Ok, Err> = (subscriber: Subscriber<Ok, Err>) => void
+
+export interface Subscription {
+  unsubscribe(): void
+}
+
+export type OperatorFunction<TIn, EIn, TOut, EOut> = (
+  source: Observable<TIn, EIn>,
+) => Observable<TOut, EOut>
+
+export declare class Observable<Ok, Err = never> {
+  constructor(cb: SubscribeCallback<Ok, Err>)
+  subscribe(observer?: Observer<Ok, Err> | NextFn<Ok, Err>): Subscription
+
+  pipe(): Observable<Ok, Err>
+  pipe<A>(op1: OperatorFunction<Ok, Err, A, Err>): Observable<A, Err>
+  pipe<A, B>(
+    op1: OperatorFunction<Ok, Err, A, Err>,
+    op2: OperatorFunction<A, Err, B, Err>,
+  ): Observable<B, Err>
+  pipe<A, B, C>(
+    op1: OperatorFunction<Ok, Err, A, Err>,
+    op2: OperatorFunction<A, Err, B, Err>,
+    op3: OperatorFunction<B, Err, C, Err>,
+  ): Observable<C, Err>
+  pipe<A, B, C, D>(
+    op1: OperatorFunction<Ok, Err, A, Err>,
+    op2: OperatorFunction<A, Err, B, Err>,
+    op3: OperatorFunction<B, Err, C, Err>,
+    op4: OperatorFunction<C, Err, D, Err>,
+  ): Observable<D, Err>
+  pipe<A, B, C, D, E>(
+    op1: OperatorFunction<Ok, Err, A, Err>,
+    op2: OperatorFunction<A, Err, B, Err>,
+    op3: OperatorFunction<B, Err, C, Err>,
+    op4: OperatorFunction<C, Err, D, Err>,
+    op5: OperatorFunction<D, Err, E, Err>,
+  ): Observable<E, Err>
+  pipe<A, B, C, D, E, F>(
+    op1: OperatorFunction<Ok, Err, A, Err>,
+    op2: OperatorFunction<A, Err, B, Err>,
+    op3: OperatorFunction<B, Err, C, Err>,
+    op4: OperatorFunction<C, Err, D, Err>,
+    op5: OperatorFunction<D, Err, E, Err>,
+    op6: OperatorFunction<E, Err, F, Err>,
+  ): Observable<F, Err>
+
+  static from<X, E>(p: Promise<Result<X, E>>): Observable<X, E>
+  static from<T>(p: Promise<T>): Observable<T, never>
+  static from<T>(it: Iterable<T>): Observable<T, never>
+  static from<Ok, Err>(o: Observable<Ok, Err>): Observable<Ok, Err>
+
+  static withEmitters<Ok, Err = never>(): {
+    observable: Observable<Ok, Err>
+    next: (value: NextArg<Ok, Err>) => void
+    complete: () => void
+  }
+}

package/runtime/udp/types.ts

@@ -1,3 +1,4 @@
+import type {Observable} from '../observable/types.js'
 import type {Result} from '../result/types.js'
 
 export type UdpFamily = 'ipv4' | 'ipv6'
@@ -31,19 +32,31 @@ export type UdpError =
   | {name: 'Closed'}
   | {name: 'NotBound'}
 
+/** Inbound datagram delivered via `socket.onMessage`. */
+export interface UdpMessage {
+  msg: Uint8Array
+  from: PeerAddress
+}
+
 export interface UdpSocket {
   readonly port: number
   readonly family: UdpFamily | 'dual'
   /**
    * Counter incremented each time an inbound datagram is dropped:
    * - the per-socket queue is full,
-   * - no `onMessage` handler is set when a packet arrives,
+   * - no subscriber is attached to `onMessage` when a packet arrives,
    * - or the datagram is larger than the 1500-byte receive buffer
    *   (typical Ethernet MTU; covers CoAP / mDNS / SNTP / DNS).
    */
   dropped: number
 
-  onMessage: ((msg: Uint8Array, from: PeerAddress) => void) | null
+  /**
+   * Stream of inbound datagrams. Subscribing attaches the native dispatch
+   * once the first subscriber is added; the last `unsubscribe()` detaches
+   * it again. Multiple subscribers fan out from one native registration.
+   * Completes when `close()` is called.
+   */
+  readonly onMessage: Observable<UdpMessage>
 
   send(data: Uint8Array | string, to: PeerAddress): Promise<Result<void, UdpError>>
   joinMulticastGroup(group: MulticastGroup): Result<void, UdpError>