@mikrojs/native 0.18.2 → 0.18.3-next.20260829153835

package/runtime/schema/types.ts

@@ -2,17 +2,153 @@ import type {Result} from '../result/types.js'
 
 type Primitive = string | number | boolean
 
-export interface StringSchema {
+export type Format = 'url' | 'hostname' | 'ipv4' | 'mac' | 'email'
+
+export type Unit =
+  | 'm'
+  | 'kg'
+  | 's'
+  | 'A'
+  | 'K'
+  | 'cd'
+  | 'mol'
+  | 'Hz'
+  | 'rad'
+  | 'sr'
+  | 'N'
+  | 'Pa'
+  | 'J'
+  | 'W'
+  | 'C'
+  | 'V'
+  | 'F'
+  | 'Ohm'
+  | 'S'
+  | 'Wb'
+  | 'T'
+  | 'H'
+  | 'Cel'
+  | 'lm'
+  | 'lx'
+  | 'Bq'
+  | 'Gy'
+  | 'Sv'
+  | 'kat'
+  | 'm2'
+  | 'm3'
+  | 'm/s'
+  | 'm/s2'
+  | 'm3/s'
+  | 'W/m2'
+  | 'cd/m2'
+  | 'bit'
+  | 'bit/s'
+  | 'lat'
+  | 'lon'
+  | 'pH'
+  | 'dB'
+  | 'dBW'
+  | 'count'
+  | '/'
+  | '%RH'
+  | '%EL'
+  | 'EL'
+  | '1/s'
+  | 'S/m'
+  | 'B'
+  | 'VA'
+  | 'VAs'
+  | 'var'
+  | 'vars'
+  | 'J/m'
+  | 'kg/m3'
+  | 'deg'
+  | 'NTU'
+  | 'ms'
+  | 'min'
+  | 'h'
+  | 'MHz'
+  | 'kW'
+  | 'kVA'
+  | 'kvar'
+  | 'Ah'
+  | 'Wh'
+  | 'kWh'
+  | 'varh'
+  | 'kvarh'
+  | 'kVAh'
+  | 'Wh/km'
+  | 'KiB'
+  | 'GB'
+  | 'Mbit/s'
+  | 'B/s'
+  | 'MB/s'
+  | 'mV'
+  | 'mA'
+  | 'dBm'
+  | 'ug/m3'
+  | 'mm/h'
+  | 'm/h'
+  | 'ppm'
+  | '/100'
+  | '/1000'
+  | 'hPa'
+  | 'mm'
+  | 'cm'
+  | 'km'
+  | 'km/h'
+  | 'ppb'
+  | 'ppt'
+  | 'VAh'
+  | 'mg/l'
+  | 'ug/l'
+  | 'g/l'
+  | 'us'
+  | 'kHz'
+  | 'GHz'
+  | 'mW'
+  | 'uA'
+  | 'uV'
+  | 'mAh'
+  | 'MiB'
+  | 'kB'
+  | 'MB'
+  | 'kbit/s'
+  | 'KiB/s'
+  | 'kohm'
+  | 'Mohm'
+  | 'kPa'
+  | 'bar'
+  | 'Bd'
+
+/* Display annotations, carried by every node a form can render. They never
+ * change what validates. Not on optional(): the wrapper expresses absence, the
+ * node it wraps expresses identity, so annotations go on the inner. */
+interface Annotated {
+  readonly title?: string
+  readonly description?: string
+}
+
+export interface StringSchema extends Annotated {
   readonly kind: 'string'
   readonly default?: string
+  readonly mask?: boolean
+  readonly minLength?: number
+  readonly maxLength?: number
+  readonly format?: Format
 }
 
-export interface NumberSchema {
+export interface NumberSchema extends Annotated {
   readonly kind: 'number'
   readonly default?: number
+  readonly mask?: boolean
+  readonly min?: number
+  readonly max?: number
+  readonly integer?: boolean
+  readonly unit?: Unit
 }
 
-export interface BooleanSchema {
+export interface BooleanSchema extends Annotated {
   readonly kind: 'boolean'
   readonly default?: boolean
 }
@@ -21,19 +157,23 @@ export interface UnknownSchema {
   readonly kind: 'unknown'
 }
 
-export interface LiteralSchema<T extends Primitive = Primitive> {
+export interface LiteralSchema<T extends Primitive = Primitive> extends Annotated {
   readonly kind: 'literal'
   readonly value: T
   readonly default?: T
 }
 
-export interface ArraySchema<S extends Schema = Schema> {
+export interface ArraySchema<S extends Schema = Schema> extends Annotated {
   readonly kind: 'array'
   readonly element: S
   readonly default?: unknown
+  readonly minItems?: number
+  readonly maxItems?: number
 }
 
-export interface ObjectSchema<Shape extends Record<string, Schema> = Record<string, Schema>> {
+export interface ObjectSchema<
+  Shape extends Record<string, Schema> = Record<string, Schema>,
+> extends Annotated {
   readonly kind: 'object'
   readonly shape: Shape
 }
@@ -43,13 +183,17 @@ export interface OptionalSchema<S extends Schema = Schema> {
   readonly inner: S
 }
 
-export interface TupleSchema<Elements extends readonly Schema[] = readonly Schema[]> {
+export interface TupleSchema<
+  Elements extends readonly Schema[] = readonly Schema[],
+> extends Annotated {
   readonly kind: 'tuple'
   readonly elements: Elements
   readonly default?: unknown
 }
 
-export interface UnionSchema<Members extends readonly Schema[] = readonly Schema[]> {
+export interface UnionSchema<
+  Members extends readonly Schema[] = readonly Schema[],
+> extends Annotated {
   readonly kind: 'union'
   readonly members: Members
   readonly default?: unknown
@@ -58,7 +202,7 @@ export interface UnionSchema<Members extends readonly Schema[] = readonly Schema
 export interface TaggedUnionSchema<
   Key extends string = string,
   Branches extends Record<string, ObjectSchema> = Record<string, ObjectSchema>,
-> {
+> extends Annotated {
   readonly kind: 'taggedUnion'
   readonly key: Key
   readonly branches: Branches
@@ -162,22 +306,52 @@ type InferReadObject<Shape> = {
 
 export type SchemaError = {name: 'ValidationFailed'; message: string; path: string}
 
-export interface ScalarOptions<T> {
+export interface DisplayOptions {
+  readonly title?: string
+  readonly description?: string
+}
+export interface ScalarOptions<T> extends DisplayOptions {
   readonly default?: T
 }
-export interface DefaultOption<T> {
+export interface DefaultOption<T> extends DisplayOptions {
   readonly default?: T
 }
+export interface MaskableOptions<T> extends ScalarOptions<T> {
+  readonly mask?: boolean
+}
+export interface StringOptions<T> extends MaskableOptions<T> {
+  readonly minLength?: number
+  readonly maxLength?: number
+  readonly format?: Format
+}
+export interface NumberOptions<T> extends MaskableOptions<T> {
+  readonly min?: number
+  readonly max?: number
+  readonly integer?: boolean
+  readonly unit?: Unit
+}
+export interface ArrayOptions<T> extends DefaultOption<T> {
+  readonly minItems?: number
+  readonly maxItems?: number
+}
+export interface EnumEntry<T extends Primitive> {
+  readonly value: T
+  readonly title?: string
+  readonly description?: string
+}
+type EnumMembers<Entries extends readonly EnumEntry<Primitive>[]> = {
+  [K in keyof Entries]: LiteralSchema<Entries[K]['value']>
+}
 
 /* Mirrors core.ts: the constructors record a `default` annotation in their
  * return type, which is what lets InferRead see it. */
 type Defaulted<S, D> = [D] extends [undefined] ? S : S & {readonly default: unknown}
 
 export declare function string<D extends string | undefined = undefined>(
-  options?: ScalarOptions<D>,
+  options?: StringOptions<D>,
 ): Defaulted<StringSchema, D>
 export declare function number<D extends number | undefined = undefined>(
-  options?: ScalarOptions<D>,
+  options?: NumberOptions<D>,
 ): Defaulted<NumberSchema, D>
 export declare function boolean<D extends boolean | undefined = undefined>(
   options?: ScalarOptions<D>,
@@ -190,7 +364,7 @@ export declare function literal<T extends Primitive, D extends T | undefined = u
 export declare function array<
   S extends Schema,
   D extends NoInfer<Infer<S>>[] | undefined = undefined,
->(element: S, options?: DefaultOption<D>): Defaulted<ArraySchema<S>, D>
+>(element: S, options?: ArrayOptions<D>): Defaulted<ArraySchema<S>, D>
 export declare function object<Shape extends Record<string, Schema>>(
   shape: Shape,
   options?: DefaultOption<never>,
@@ -204,6 +378,10 @@ export declare function union<
   Members extends readonly Schema[],
   D extends NoInfer<Infer<UnionSchema<Members>>> | undefined = undefined,
 >(members: [...Members], options?: DefaultOption<D>): Defaulted<UnionSchema<Members>, D>
+export declare function enumOf<
+  const Entries extends readonly EnumEntry<Primitive>[],
+  D extends Entries[number]['value'] | undefined = undefined,
+>(entries: Entries, options?: DefaultOption<D>): Defaulted<UnionSchema<EnumMembers<Entries>>, D>
 export declare function taggedUnion<
   Key extends string,
   Branches extends Record<string, ObjectSchema>,

package/runtime/sys/types.ts

@@ -1,7 +1,12 @@
 import type {Result} from '../result/types.js'
 
 export interface MemoryUsage {
+  /** Bytes allocated from the JS heap. On device this counts real
+   *  allocator block sizes (requested bytes rounded up to the heap's
+   *  granularity), so it reflects what the heap actually spends; small
+   *  run-to-run variation is normal. */
   heapUsed: number
+  /** The JS heap's configured memory limit in bytes. */
   heapTotal: number
   /** Free system heap in bytes (0 on host) */
   systemFree: number
@@ -87,6 +92,11 @@ export declare function gc(): void
 /** Firmware version string (e.g. "0.1.0") */
 export declare const version: string
 
+/** Values {@link BoardInfo.features} can contain. `wifi`, `ble` and `bt` need
+ *  both the silicon and the matching stack compiled into the firmware;
+ *  `ieee802154` reports silicon alone. */
+export type BoardFeature = 'wifi' | 'ble' | 'bt' | 'ieee802154'
+
 export interface BoardInfo {
   /** Board name from the firmware build (e.g. "xiao-esp32c6") or "generic" */
   name: string
@@ -97,7 +107,7 @@ export interface BoardInfo {
   /** Silicon revision (major * 100 + minor on ESP32, 0 on host) */
   revision: number
   /** Supported features (e.g. ["wifi", "ble"]) */
-  features: string[]
+  features: BoardFeature[]
   /** Flash size in bytes (0 on host) */
   flash: number
   /** PSRAM size in bytes (0 if unavailable) */

package/src/mem.cpp

@@ -9,15 +9,56 @@
 
 /*
  * QuickJS uses malloc_usable_size to track memory consumption against its
- * memory limit. ESP-IDF lacks a standard malloc_usable_size, and the
- * heap_caps_get_allocated_size alternative reports block sizes including
- * allocator overhead, causing QuickJS to over-count usage.
+ * memory limit. When the platform reports live-allocation sizes
+ * (malloc_usable_size hook: libc malloc_usable_size / malloc_size,
+ * heap_caps_get_allocated_size on ESP-IDF), allocations are returned as-is
+ * and QuickJS accounts blocks by their real (rounded-up) size.
  *
- * We prepend each allocation with a size_t header storing the requested size.
+ * Without the hook, each allocation is prepended with a size_t header
+ * storing the requested size. That costs one word of RAM per live block —
+ * ~13 KB across a loaded app's ~3400 blocks on a 32-bit device — which is
+ * why the hook path is preferred.
+ *
+ * The mode is latched at the first allocation and never changes, so every
+ * pointer is freed the same way it was allocated. Platforms install before
+ * the first runtime exists (ESP32 and node have theirs as the compile-time
+ * default), so the latch sees the final platform. The latch is a single
+ * word-sized store (null = unlatched, mik__hdr_usable_size = header mode),
+ * so concurrent first allocations on a dual-core target can at worst both
+ * compute and store the same value — there is no two-variable ordering to
+ * observe half-done.
  */
 
 #define HDR_SIZE sizeof(size_t)
 
+static inline size_t hdr_read(void* user) {
+    size_t sz;
+    memcpy(&sz, static_cast<char*>(user) - HDR_SIZE, sizeof(sz));
+    return sz;
+}
+
+/* Header-mode usable_size; doubles as the latch marker for that mode. */
+static size_t mik__hdr_usable_size(const void* ptr) {
+    return hdr_read(const_cast<void*>(ptr));
+}
+
+typedef size_t (*MIKUsableSizeFn)(const void*);
+static MIKUsableSizeFn g_usable_size_fn = nullptr; /* null = not latched yet */
+
+static inline MIKUsableSizeFn usable_size_fn(void) {
+    MIKUsableSizeFn fn = g_usable_size_fn;
+    if (!fn) {
+        const MIKPlatform* p = MIK_GetPlatform();
+        fn = (p && p->malloc_usable_size) ? p->malloc_usable_size : mik__hdr_usable_size;
+        g_usable_size_fn = fn;
+    }
+    return fn;
+}
+
+static inline size_t hdr_size(void) {
+    return usable_size_fn() == mik__hdr_usable_size ? HDR_SIZE : 0;
+}
+
 /* Fault injection for the host OOM tests: fail the JS-heap allocators after
  * a countdown, and keep a net live-allocation counter across every allocator
  * here (all of them free through mik__free, so one counter balances). */
@@ -39,6 +80,11 @@ static bool oom_inject_should_fail(void) {
     g_oom_countdown--;
     return false;
 }
+
+void mik__usable_size_latch_override(size_t (*fn)(const void*)) {
+    g_usable_size_fn = fn ? fn : mik__hdr_usable_size;
+}
+
 #define OOM_INJECT_FAIL() oom_inject_should_fail()
 #define LIVE_ALLOCS_ADD(d) (g_live_allocs += (d))
 #else
@@ -46,27 +92,22 @@ static bool oom_inject_should_fail(void) {
 #define LIVE_ALLOCS_ADD(d) ((void)0)
 #endif
 
-static inline size_t hdr_read(void* user) {
-    size_t sz;
-    memcpy(&sz, static_cast<char*>(user) - HDR_SIZE, sizeof(sz));
-    return sz;
-}
-
-static inline void hdr_write(void* raw, size_t sz) {
-    memcpy(raw, &sz, sizeof(sz));
+static inline void hdr_write(void* raw, size_t size, size_t hdr) {
+    if (hdr) memcpy(raw, &size, sizeof(size));
 }
 
 size_t mik__malloc_usable_size(const void* ptr) {
     if (!ptr) return 0;
-    return hdr_read(const_cast<void*>(ptr));
+    return usable_size_fn()(ptr);
 }
 
 void* mik__malloc(size_t size) {
-    void* raw = malloc(size + HDR_SIZE);
+    size_t hdr = hdr_size();
+    void* raw = malloc(size + hdr);
     if (!raw) return nullptr;
-    hdr_write(raw, size);
+    hdr_write(raw, size, hdr);
     LIVE_ALLOCS_ADD(1);
-    return static_cast<char*>(raw) + HDR_SIZE;
+    return static_cast<char*>(raw) + hdr;
 }
 
 void* mik__mallocz(size_t size) { return mik__calloc(1, size); }
@@ -74,26 +115,28 @@ void* mik__mallocz(size_t size) { return mik__calloc(1, size); }
 void* mik__calloc(size_t count, size_t size) {
     if (size && count > SIZE_MAX / size) return nullptr;
     size_t total = count * size;
-    void* raw = calloc(1, total + HDR_SIZE);
+    size_t hdr = hdr_size();
+    void* raw = calloc(1, total + hdr);
     if (!raw) return nullptr;
-    hdr_write(raw, total);
+    hdr_write(raw, total, hdr);
     LIVE_ALLOCS_ADD(1);
-    return static_cast<char*>(raw) + HDR_SIZE;
+    return static_cast<char*>(raw) + hdr;
 }
 
 void mik__free(void* ptr) {
     if (!ptr) return;
     LIVE_ALLOCS_ADD(-1);
-    free(static_cast<char*>(ptr) - HDR_SIZE);
+    free(static_cast<char*>(ptr) - hdr_size());
 }
 
 void* mik__realloc(void* ptr, size_t size) {
-    void* raw = ptr ? static_cast<char*>(ptr) - HDR_SIZE : nullptr;
-    raw = realloc(raw, size + HDR_SIZE);
+    size_t hdr = hdr_size();
+    void* raw = ptr ? static_cast<char*>(ptr) - hdr : nullptr;
+    raw = realloc(raw, size + hdr);
     if (!raw) return nullptr;
-    hdr_write(raw, size);
+    hdr_write(raw, size, hdr);
     if (!ptr) LIVE_ALLOCS_ADD(1);
-    return static_cast<char*>(raw) + HDR_SIZE;
+    return static_cast<char*>(raw) + hdr;
 }
 
 /* QuickJS-heap allocator. When the PSRAM flag is set, route through the
@@ -115,51 +158,54 @@ bool mik__is_quickjs_heap_psram(void) {
 
 void* mik__js_malloc(size_t size) {
     if (OOM_INJECT_FAIL()) return nullptr;
+    size_t hdr = hdr_size();
     void* raw = nullptr;
     if (g_quickjs_heap_psram) {
         const MIKPlatform* p = MIK_GetPlatform();
         if (p && p->malloc_psram) {
-            raw = p->malloc_psram(size + HDR_SIZE);
+            raw = p->malloc_psram(size + hdr);
         }
     }
-    if (!raw) raw = malloc(size + HDR_SIZE);
+    if (!raw) raw = malloc(size + hdr);
     if (!raw) return nullptr;
-    hdr_write(raw, size);
+    hdr_write(raw, size, hdr);
     LIVE_ALLOCS_ADD(1);
-    return static_cast<char*>(raw) + HDR_SIZE;
+    return static_cast<char*>(raw) + hdr;
 }
 
 void* mik__js_calloc(size_t count, size_t size) {
     if (OOM_INJECT_FAIL()) return nullptr;
     if (size && count > SIZE_MAX / size) return nullptr;
     size_t total = count * size;
+    size_t hdr = hdr_size();
     void* raw = nullptr;
     if (g_quickjs_heap_psram) {
         const MIKPlatform* p = MIK_GetPlatform();
         if (p && p->calloc_psram) {
-            raw = p->calloc_psram(1, total + HDR_SIZE);
+            raw = p->calloc_psram(1, total + hdr);
         }
     }
-    if (!raw) raw = calloc(1, total + HDR_SIZE);
+    if (!raw) raw = calloc(1, total + hdr);
     if (!raw) return nullptr;
-    hdr_write(raw, total);
+    hdr_write(raw, total, hdr);
     LIVE_ALLOCS_ADD(1);
-    return static_cast<char*>(raw) + HDR_SIZE;
+    return static_cast<char*>(raw) + hdr;
 }
 
 void* mik__js_realloc(void* ptr, size_t size) {
     if (OOM_INJECT_FAIL()) return nullptr;
-    void* raw = ptr ? static_cast<char*>(ptr) - HDR_SIZE : nullptr;
+    size_t hdr = hdr_size();
+    void* raw = ptr ? static_cast<char*>(ptr) - hdr : nullptr;
     void* new_raw = nullptr;
     if (g_quickjs_heap_psram) {
         const MIKPlatform* p = MIK_GetPlatform();
         if (p && p->realloc_psram) {
-            new_raw = p->realloc_psram(raw, size + HDR_SIZE);
+            new_raw = p->realloc_psram(raw, size + hdr);
         }
     }
-    if (!new_raw) new_raw = realloc(raw, size + HDR_SIZE);
+    if (!new_raw) new_raw = realloc(raw, size + hdr);
     if (!new_raw) return nullptr;
-    hdr_write(new_raw, size);
+    hdr_write(new_raw, size, hdr);
     if (!ptr) LIVE_ALLOCS_ADD(1);
-    return static_cast<char*>(new_raw) + HDR_SIZE;
+    return static_cast<char*>(new_raw) + hdr;
 }

package/src/mik_ota_client.cpp

@@ -384,10 +384,9 @@ void MIKOtaClient::Check(const MIKOtaCheckOptions& options, MIKOtaCheckSink sink
  * config — the floor is what bounds the damage a mistyped document can do. */
 constexpr uint32_t kMinCheckinIntervalMs = 30000;
 
-void MIKOtaClient::Watch(const MIKOtaWatchOptions& options) {
+bool MIKOtaClient::Watch(const MIKOtaWatchOptions& options) {
     if (!Enrollment(&watch_registry_url_, &watch_bearer_)) {
-        Log(MIK_LOG_INFO, "ota: device not enrolled; run `mikro ota enroll` to enable OTA updates");
-        return;
+        return false;
     }
     watch_options_ = options;
     if (watch_options_.checkin_interval_ms < kMinCheckinIntervalMs) {
@@ -402,6 +401,7 @@ void MIKOtaClient::Watch(const MIKOtaWatchOptions& options) {
     wait_started_ms_ = Now();
     deadline_ms_ = wait_started_ms_ + scheduled_delay_ms_;
     pending_wait_ = PendingWait::kInitial;
+    return true;
 }
 
 void MIKOtaClient::SetCheckinInterval(uint32_t interval_ms) {

package/src/mik_sys.cpp

@@ -187,15 +187,23 @@ static JSValue mik__sys_board(JSContext* ctx) {
     JS_SetPropertyStr(ctx, obj, "cores", JS_NewInt32(ctx, chip_info.cores));
     JS_SetPropertyStr(ctx, obj, "revision", JS_NewInt32(ctx, chip_info.revision));
 
-    /* Features as string array */
+    /* Features as string array. Callers use this to decide whether an
+     * optional module will work, so a radio only counts when the silicon
+     * has it AND the stack behind it was compiled in. */
     JSValue features = JS_NewArray(ctx);
     uint32_t fi = 0;
+#ifdef CONFIG_ESP_WIFI_ENABLED
     if (chip_info.features & CHIP_FEATURE_WIFI_BGN)
         JS_SetPropertyUint32(ctx, features, fi++, JS_NewString(ctx, "wifi"));
+#endif
+#ifdef CONFIG_BT_ENABLED
     if (chip_info.features & CHIP_FEATURE_BLE)
         JS_SetPropertyUint32(ctx, features, fi++, JS_NewString(ctx, "ble"));
     if (chip_info.features & CHIP_FEATURE_BT)
         JS_SetPropertyUint32(ctx, features, fi++, JS_NewString(ctx, "bt"));
+#endif
+    /* No stack to gate on: mikrojs has no 802.15.4 API, so this stays a
+     * plain silicon report. */
     if (chip_info.features & CHIP_FEATURE_IEEE802154)
         JS_SetPropertyUint32(ctx, features, fi++, JS_NewString(ctx, "ieee802154"));
     JS_SetPropertyStr(ctx, obj, "features", features);