@mikrojs/native 0.8.0-pr-115.g87a99f9 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.8.0-pr-115.g87a99f9",
+  "version": "0.8.0",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -78,7 +78,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.8.0-pr-115.g87a99f9"
+    "@mikrojs/quickjs": "0.8.0"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/internal.d.ts

@@ -128,17 +128,13 @@ declare module 'native:pin' {
 }
 
 declare module 'native:sleep' {
-  import type {SleepError} from '@mikrojs/native/runtime/sleep/types'
-  import type {Result} from 'mikrojs/result'
+  import type {DeepWakeupSources, LightWakeupSources} from '@mikrojs/native/runtime/sleep/types'
 
-  export function deepSleep(ms: number): never
-  export function lightSleep(ms: number): Result<void, SleepError>
+  export function deepSleep(sources: DeepWakeupSources): never
+  export function lightSleep(sources: LightWakeupSources): void
   export function getWakeupCause(): string
-  export function enableTimerWakeup(us: number): Result<void, SleepError>
-  export function enableGpioWakeup(pin: number, level: number): Result<void, SleepError>
-  export function enableExt0Wakeup(pin: number, level: number): Result<void, SleepError>
-  export function enableExt1Wakeup(pinMask: number, mode: number): Result<void, SleepError>
-  export function disableWakeupSource(source?: string): Result<void, SleepError>
+  export function canWakeFromExt0(): boolean
+  export function canWakeFromExt1(): boolean
 }
 
 declare module 'native:http' {

package/runtime/sleep/sleep.ts

@@ -1,13 +1,17 @@
-export {
-  deepSleep,
-  disableWakeupSource,
-  enableExt0Wakeup,
-  enableExt1Wakeup,
-  enableGpioWakeup,
-  enableTimerWakeup,
-  getWakeupCause,
-  lightSleep,
-} from 'native:sleep'
+import {deepSleep as nativeDeepSleep, lightSleep as nativeLightSleep} from 'native:sleep'
+
+import type {DeepWakeupSources, LightWakeupSources} from './types.js'
+
+export type {DeepWakeupSources, LightWakeupSources, RtcGpio, WakeupLevel} from './types.js'
+export {canWakeFromExt0, canWakeFromExt1} from 'native:sleep'
+
+export function deepSleep(sources: DeepWakeupSources | number): never {
+  return nativeDeepSleep(typeof sources === 'number' ? {timer: sources} : sources)
+}
+
+export function lightSleep(sources: LightWakeupSources | number): void {
+  nativeLightSleep(typeof sources === 'number' ? {timer: sources} : sources)
+}
 
 export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))

package/runtime/sleep/types.ts

@@ -1,44 +1,67 @@
-import type {Result} from '../result/types.js'
+export type WakeupLevel = 'high' | 'low'
 
-export type SleepError =
-  | {name: 'WakeupConfigFailed'; message: string}
-  | {name: 'LightSleepFailed'; message: string}
-  | {name: 'DisableWakeupFailed'; message: string}
-
-export declare function deepSleep(time: number): never
-
-export declare function lightSleep(time: number): Result<void, SleepError>
+/** A GPIO pin number that must be RTC-capable for deep-sleep wake.
+ *  Set varies per chip:
+ *  - ESP32-C6 / H2: 0–7 (LP_GPIO0–LP_GPIO7)
+ *  - ESP32-C3: 0–5
+ *  - ESP32-S2 / S3: 0–21 (LP_IO0–LP_IO21)
+ *  - ESP32: subset of 0–39 (see datasheet for RTC_GPIO mapping)
+ *
+ *  Not statically validated — passing a non-RTC pin throws at runtime.
+ */
+export type RtcGpio = number
 
-export declare function getWakeupCause(): string
+/** Sources that can wake the chip from light sleep. */
+export type LightWakeupSources = {
+  /** Wake after this many milliseconds. Fractional values are allowed
+   *  (e.g. `0.01` = 10 µs). */
+  timer?: number
+  /** Wake when `pin` reaches `level`. Any GPIO works — no RTC-capable
+   *  constraint. */
+  gpio?: {pin: number; level: WakeupLevel}
+}
 
-/** Configure timer wakeup source (microseconds). */
-export declare function enableTimerWakeup(us: number): Result<void, SleepError>
+/** Sources that can wake the chip from deep sleep. */
+export type DeepWakeupSources = {
+  /** Wake after this many milliseconds. Fractional values are allowed. */
+  timer?: number
+  /** Wake on a single RTC GPIO. ESP32 / S2 / S3 only — throws on
+   *  C3 / C6 / H2 (use `ext1` instead). */
+  ext0?: {pin: RtcGpio; level: WakeupLevel}
+  /** Wake when any of `pins` matches `mode`. Pins must be RTC-capable.
+   *
+   *  Caveat — original ESP32 chip only: the EXT1 hardware on the
+   *  original ESP32 cannot honor "any-low" with more than one pin (the
+   *  silicon always requires *every* selected pin to be low, not any).
+   *  Multi-pin `{mode: 'any-low'}` throws on ESP32; single-pin works,
+   *  and `'any-high'` works for any pin count. Every newer chip
+   *  (C3, C5, C6, S2, S3, …) supports multi-pin `'any-low'` natively. */
+  ext1?: {pins: RtcGpio[]; mode: 'any-low' | 'any-high'}
+}
 
 /**
- * Configure GPIO wakeup for light sleep.
- * @param pin GPIO pin number
- * @param level GPIO interrupt type (e.g. 4 = low, 5 = high)
+ * Enter deep sleep. Pass a `DeepWakeupSources` object, or a number as
+ * shorthand for `{timer: ms}`. The chip resets on wake.
  */
-export declare function enableGpioWakeup(pin: number, level: number): Result<void, SleepError>
+export declare function deepSleep(ms: number): never
+export declare function deepSleep(sources: DeepWakeupSources): never
 
 /**
- * Configure ext0 wakeup for deep sleep (ESP32, ESP32-S2, ESP32-S3 only).
- * @param pin RTC GPIO pin number
- * @param level 0 = low, 1 = high
+ * Enter light sleep. Pass a `LightWakeupSources` object, or a number as
+ * shorthand for `{timer: ms}`. Execution resumes from the call site
+ * after waking.
  */
-export declare function enableExt0Wakeup(pin: number, level: number): Result<void, SleepError>
+export declare function lightSleep(ms: number): void
+export declare function lightSleep(sources: LightWakeupSources): void
 
-/**
- * Configure ext1 wakeup for deep sleep.
- * @param pinMask Bitmask of RTC GPIO pins
- * @param mode 0 = ESP_EXT1_WAKEUP_ALL_LOW, 1 = ESP_EXT1_WAKEUP_ANY_HIGH
- */
-export declare function enableExt1Wakeup(pinMask: number, mode: number): Result<void, SleepError>
+/** Returns `true` if the current chip supports EXT0 wakeup
+ *  (ESP32, ESP32-S2, ESP32-S3). Use to gate `deepSleep({ext0: …})`
+ *  calls when targeting boards across the ESP32 family. */
+export declare function canWakeFromExt0(): boolean
 
-/**
- * Disable a wakeup source. If no source is specified, all sources are disabled.
- * @param source Optional: "timer", "ext0", "ext1", "gpio", "touchpad", "ulp"
- */
-export declare function disableWakeupSource(source?: string): Result<void, SleepError>
+/** Returns `true` if the current chip supports EXT1 wakeup. Every
+ *  chip mikrojs targets except ESP32-C3. Use to gate
+ *  `deepSleep({ext1: …})` calls. */
+export declare function canWakeFromExt1(): boolean
 
 export declare function sleep(ms: number): Promise<void>

package/runtime/sys/sys.ts

@@ -1,4 +1,5 @@
 import {err, ok, PanicError, type Result} from 'mikrojs/result'
+import {getWakeupCause as nativeGetWakeupCause} from 'native:sleep'
 import * as native from 'native:sys'
 
 export function uptime(): {boot: number; rtc: number} {
@@ -40,6 +41,10 @@ export function restart(): never {
   return native.restart() as never
 }
 
+export function getWakeupCause(): string {
+  return nativeGetWakeupCause()
+}
+
 export function exit(_exitCode?: number): never {
   return native.restart() as never
 }

package/runtime/sys/types.ts

@@ -124,6 +124,11 @@ export declare const firmware: {
 
 export declare function restart(): never
 
+/** Reason the device woke up this boot. Set after deep sleep (or first
+ *  boot). One of: `'timer'`, `'ext0'`, `'ext1'`, `'gpio'`, or `'undefined'`
+ *  (cold boot or unknown). */
+export declare function getWakeupCause(): string
+
 export declare function exit(exitCode?: number): never
 
 /** Immediately crash with an error message. Use for unrecoverable situations. */