@mikrojs/native 0.0.7

package/runtime/result/types.ts

@@ -0,0 +1,60 @@
+export declare class PanicError extends Error {
+  constructor(message: string, options?: {cause?: unknown})
+}
+
+export interface OkResult<T> {
+  readonly ok: true
+  readonly value: T
+  readonly error?: never
+  map<U>(fn: (value: T) => U): OkResult<U>
+  mapErr<F>(fn: (error: never) => F): OkResult<T>
+  andThen<U, F>(fn: (value: T) => Result<U, F>): Result<U, F>
+  match<A, B>(handlers: {ok: (value: T) => A; err: (error: never) => B}): A
+  /** Get the value, or return the default if this is an Err. */
+  orDefault<D>(defaultValue: D): T | D
+  /** Get the value, or panic with the given message if this is an Err. */
+  orPanic(message: string): T
+}
+
+export interface ErrResult<E> {
+  readonly ok: false
+  readonly value?: never
+  readonly error: E
+  map<U>(fn: (value: never) => U): ErrResult<E>
+  mapErr<F>(fn: (error: E) => F): ErrResult<F>
+  andThen<U, F>(fn: (value: never) => Result<U, F>): ErrResult<E>
+  match<A, B>(handlers: {ok: (value: never) => A; err: (error: E) => B}): B
+  /** Return the default value since this is an Err. */
+  orDefault<D>(defaultValue: D): D
+  /** Always panics with the given message since this is an Err. The error is included as cause. */
+  orPanic(message: string): never
+}
+
+export type Result<T, E> = OkResult<T> | ErrResult<E>
+
+export declare function ok(): OkResult<void>
+export declare function ok<T>(value: T): OkResult<T>
+
+export declare function err<E>(error: E): ErrResult<E>
+
+type VariantDef = Record<string, (...args: any[]) => Record<string, unknown>>
+
+type ErrorConstructors<D extends VariantDef> = {
+  [K in keyof D & string]: (...args: Parameters<D[K]>) => {name: K} & ReturnType<D[K]>
+}
+
+export type ErrorOf<T extends Record<string, (...args: any[]) => any>> = {
+  [K in keyof T & string]: ReturnType<T[K]>
+}[keyof T & string]
+
+export declare function defineError<D extends VariantDef>(
+  name: string,
+  variants: D,
+): ErrorConstructors<D>
+
+/** Raw error shape returned by native mik__result_err(). */
+export interface NativeError {
+  readonly code: number
+  readonly message: string
+  readonly errno?: number
+}

package/runtime/schema/schema.ts

@@ -0,0 +1,321 @@
+import {defineError, err, ok} from 'mikrojs/result'
+
+import type {Result} from '../result/types.js'
+
+export const SchemaError = defineError('SchemaError', {
+  ValidationFailed: (message: string, path: string) => ({message, path}),
+})
+export type SchemaError = ReturnType<typeof SchemaError.ValidationFailed>
+
+// ── Schema types ────────────────────────────────────────────────────
+
+type Primitive = string | number | boolean
+
+export interface StringSchema {
+  readonly kind: 'string'
+}
+
+export interface NumberSchema {
+  readonly kind: 'number'
+}
+
+export interface BooleanSchema {
+  readonly kind: 'boolean'
+}
+
+export interface UnknownSchema {
+  readonly kind: 'unknown'
+}
+
+export interface LiteralSchema<T extends Primitive = Primitive> {
+  readonly kind: 'literal'
+  readonly value: T
+}
+
+export interface ArraySchema<S extends Schema = Schema> {
+  readonly kind: 'array'
+  readonly element: S
+}
+
+export interface ObjectSchema<Shape extends Record<string, Schema> = Record<string, Schema>> {
+  readonly kind: 'object'
+  readonly shape: Shape
+}
+
+export interface OptionalSchema<S extends Schema = Schema> {
+  readonly kind: 'optional'
+  readonly inner: S
+}
+
+export interface TupleSchema<Elements extends readonly Schema[] = readonly Schema[]> {
+  readonly kind: 'tuple'
+  readonly elements: Elements
+}
+
+export interface UnionSchema<Members extends readonly Schema[] = readonly Schema[]> {
+  readonly kind: 'union'
+  readonly members: Members
+}
+
+export interface TaggedUnionSchema<
+  Key extends string = string,
+  Branches extends Record<string, ObjectSchema> = Record<string, ObjectSchema>,
+> {
+  readonly kind: 'taggedUnion'
+  readonly key: Key
+  readonly branches: Branches
+}
+
+export type Schema =
+  | StringSchema
+  | NumberSchema
+  | BooleanSchema
+  | UnknownSchema
+  | LiteralSchema
+  | ArraySchema
+  | ObjectSchema
+  | OptionalSchema
+  | TupleSchema
+  | UnionSchema
+  | TaggedUnionSchema
+
+// ── Type inference ──────────────────────────────────────────────────
+
+type Simplify<T> = {[K in keyof T]: T[K]} & {}
+
+export type Infer<S> = S extends StringSchema
+  ? string
+  : S extends NumberSchema
+    ? number
+    : S extends BooleanSchema
+      ? boolean
+      : S extends UnknownSchema
+        ? unknown
+        : S extends LiteralSchema<infer T>
+          ? T
+          : S extends ArraySchema<infer E>
+            ? Infer<E>[]
+            : S extends ObjectSchema<infer Shape>
+              ? Simplify<InferObject<Shape>>
+              : S extends TupleSchema<infer Elements>
+                ? InferTuple<Elements>
+                : S extends OptionalSchema<infer Inner>
+                  ? Infer<Inner> | undefined
+                  : S extends UnionSchema<infer Members>
+                    ? InferUnion<Members>
+                    : S extends TaggedUnionSchema<infer Key, infer Branches>
+                      ? InferTaggedUnion<Key, Branches>
+                      : never
+
+type InferObject<Shape> = {
+  [K in keyof Shape as Shape[K] extends OptionalSchema ? never : K]: Infer<Shape[K]>
+} & {
+  [K in keyof Shape as Shape[K] extends OptionalSchema ? K : never]?: Infer<Shape[K]>
+}
+
+type InferTuple<Elements> = Elements extends readonly [infer Head, ...infer Tail]
+  ? [Infer<Head>, ...InferTuple<Tail>]
+  : []
+
+type InferUnion<Members> = Members extends readonly [infer Head, ...infer Tail]
+  ? Infer<Head> | InferUnion<Tail>
+  : never
+
+type InferTaggedUnion<Key extends string, Branches> = {
+  [Tag in keyof Branches & string]: {[K in Key]: Tag} & Infer<Branches[Tag]>
+}[keyof Branches & string]
+
+// ── Schema constructors ─────────────────────────────────────────────
+
+export function string(): StringSchema {
+  return {kind: 'string'}
+}
+
+export function number(): NumberSchema {
+  return {kind: 'number'}
+}
+
+export function boolean(): BooleanSchema {
+  return {kind: 'boolean'}
+}
+
+export function unknown(): UnknownSchema {
+  return {kind: 'unknown'}
+}
+
+export function literal<T extends Primitive>(value: T): LiteralSchema<T> {
+  return {kind: 'literal', value}
+}
+
+export function array<S extends Schema>(element: S): ArraySchema<S> {
+  return {kind: 'array', element}
+}
+
+export function object<Shape extends Record<string, Schema>>(shape: Shape): ObjectSchema<Shape> {
+  return {kind: 'object', shape}
+}
+
+export function tuple<Elements extends readonly Schema[]>(
+  elements: [...Elements],
+): TupleSchema<Elements> {
+  return {kind: 'tuple', elements}
+}
+
+export function optional<S extends Schema>(inner: S): OptionalSchema<S> {
+  return {kind: 'optional', inner}
+}
+
+export function union<Members extends readonly Schema[]>(
+  members: [...Members],
+): UnionSchema<Members> {
+  return {kind: 'union', members}
+}
+
+export function taggedUnion<Key extends string, Branches extends Record<string, ObjectSchema>>(
+  key: Key,
+  branches: Branches,
+): TaggedUnionSchema<Key, Branches> {
+  return {kind: 'taggedUnion', key, branches}
+}
+
+// ── Parse ───────────────────────────────────────────────────────────
+
+export function parse<S extends Schema>(schema: S, value: unknown): Result<Infer<S>, SchemaError> {
+  const result = validate(schema, value, '')
+  if (result !== null) return result as Result<Infer<S>, SchemaError>
+  return ok(value as Infer<S>)
+}
+
+function typeOf(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
+function validate(
+  schema: Schema,
+  value: unknown,
+  path: string,
+): ReturnType<typeof err<SchemaError>> | null {
+  switch (schema.kind) {
+    case 'string':
+      if (typeof value !== 'string')
+        return err(SchemaError.ValidationFailed(`expected string, got ${typeOf(value)}`, path))
+      return null
+
+    case 'number':
+      if (typeof value !== 'number' || Number.isNaN(value))
+        return err(SchemaError.ValidationFailed(`expected number, got ${typeOf(value)}`, path))
+      return null
+
+    case 'boolean':
+      if (typeof value !== 'boolean')
+        return err(SchemaError.ValidationFailed(`expected boolean, got ${typeOf(value)}`, path))
+      return null
+
+    case 'unknown':
+      return null
+
+    case 'literal':
+      if (value !== schema.value)
+        return err(
+          SchemaError.ValidationFailed(
+            `expected ${JSON.stringify(schema.value)}, got ${JSON.stringify(value)}`,
+            path,
+          ),
+        )
+      return null
+
+    case 'array': {
+      if (!Array.isArray(value))
+        return err(SchemaError.ValidationFailed(`expected array, got ${typeOf(value)}`, path))
+      for (let i = 0; i < value.length; i++) {
+        const result = validate(schema.element, value[i], `${path}[${i}]`)
+        if (result !== null) return result
+      }
+      return null
+    }
+
+    case 'object': {
+      if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return err(SchemaError.ValidationFailed(`expected object, got ${typeOf(value)}`, path))
+      const obj = value as Record<string, unknown>
+      const keys = Object.keys(schema.shape)
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i]!
+        const fieldSchema = schema.shape[key]!
+        const fieldPath = `${path}.${key}`
+        if (fieldSchema.kind === 'optional') {
+          if (key in obj) {
+            const result = validate(fieldSchema, obj[key], fieldPath)
+            if (result !== null) return result
+          }
+        } else {
+          if (!(key in obj))
+            return err(SchemaError.ValidationFailed(`missing required field`, fieldPath))
+          const result = validate(fieldSchema, obj[key], fieldPath)
+          if (result !== null) return result
+        }
+      }
+      return null
+    }
+
+    case 'tuple': {
+      if (!Array.isArray(value))
+        return err(SchemaError.ValidationFailed(`expected array, got ${typeOf(value)}`, path))
+      if (value.length !== schema.elements.length)
+        return err(
+          SchemaError.ValidationFailed(
+            `expected ${schema.elements.length} elements, got ${value.length}`,
+            path,
+          ),
+        )
+      for (let i = 0; i < schema.elements.length; i++) {
+        const result = validate(schema.elements[i]!, value[i], `${path}[${i}]`)
+        if (result !== null) return result
+      }
+      return null
+    }
+
+    case 'optional': {
+      if (value === undefined) return null
+      return validate(schema.inner, value, path)
+    }
+
+    case 'union': {
+      for (let i = 0; i < schema.members.length; i++) {
+        const result = validate(schema.members[i]!, value, path)
+        if (result === null) return null
+      }
+      return err(SchemaError.ValidationFailed(`value did not match any union member`, path))
+    }
+
+    case 'taggedUnion': {
+      if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return err(SchemaError.ValidationFailed(`expected object, got ${typeOf(value)}`, path))
+      const obj = value as Record<string, unknown>
+      const tag = obj[schema.key]
+      if (tag === undefined)
+        return err(
+          SchemaError.ValidationFailed(`missing discriminator field`, `${path}.${schema.key}`),
+        )
+      if (typeof tag !== 'string' && typeof tag !== 'number' && typeof tag !== 'boolean')
+        return err(
+          SchemaError.ValidationFailed(
+            `expected primitive discriminator, got ${typeOf(tag)}`,
+            `${path}.${schema.key}`,
+          ),
+        )
+      const branch = schema.branches[tag as string]
+      if (branch === undefined)
+        return err(
+          SchemaError.ValidationFailed(
+            `unknown tag ${JSON.stringify(tag)}`,
+            `${path}.${schema.key}`,
+          ),
+        )
+      return validate(branch, value, path)
+    }
+  }
+  return err(SchemaError.ValidationFailed(`unknown schema kind: ${(schema as any).kind}`, path))
+}

package/runtime/schema/types.ts

@@ -0,0 +1,152 @@
+import type {Result} from '../result/types.js'
+
+type Primitive = string | number | boolean
+
+export interface StringSchema {
+  readonly kind: 'string'
+}
+
+export interface NumberSchema {
+  readonly kind: 'number'
+}
+
+export interface BooleanSchema {
+  readonly kind: 'boolean'
+}
+
+export interface UnknownSchema {
+  readonly kind: 'unknown'
+}
+
+export interface LiteralSchema<T extends Primitive = Primitive> {
+  readonly kind: 'literal'
+  readonly value: T
+}
+
+export interface ArraySchema<S extends Schema = Schema> {
+  readonly kind: 'array'
+  readonly element: S
+}
+
+export interface ObjectSchema<Shape extends Record<string, Schema> = Record<string, Schema>> {
+  readonly kind: 'object'
+  readonly shape: Shape
+}
+
+export interface OptionalSchema<S extends Schema = Schema> {
+  readonly kind: 'optional'
+  readonly inner: S
+}
+
+export interface TupleSchema<Elements extends readonly Schema[] = readonly Schema[]> {
+  readonly kind: 'tuple'
+  readonly elements: Elements
+}
+
+export interface UnionSchema<Members extends readonly Schema[] = readonly Schema[]> {
+  readonly kind: 'union'
+  readonly members: Members
+}
+
+export interface TaggedUnionSchema<
+  Key extends string = string,
+  Branches extends Record<string, ObjectSchema> = Record<string, ObjectSchema>,
+> {
+  readonly kind: 'taggedUnion'
+  readonly key: Key
+  readonly branches: Branches
+}
+
+export type Schema =
+  | StringSchema
+  | NumberSchema
+  | BooleanSchema
+  | UnknownSchema
+  | LiteralSchema
+  | ArraySchema
+  | ObjectSchema
+  | OptionalSchema
+  | TupleSchema
+  | UnionSchema
+  | TaggedUnionSchema
+
+type Simplify<T> = {[K in keyof T]: T[K]} & {}
+
+export type Infer<S> = S extends StringSchema
+  ? string
+  : S extends NumberSchema
+    ? number
+    : S extends BooleanSchema
+      ? boolean
+      : S extends UnknownSchema
+        ? unknown
+        : S extends LiteralSchema<infer T>
+          ? T
+          : S extends ArraySchema<infer E>
+            ? ArraySchema extends S
+              ? []
+              : Infer<E>[]
+            : S extends ObjectSchema<infer Shape>
+              ? ObjectSchema extends S
+                ? object
+                : Simplify<InferObject<Shape>>
+              : S extends TupleSchema<infer Elements>
+                ? InferTuple<Elements>
+                : S extends OptionalSchema<infer Inner>
+                  ? OptionalSchema extends S
+                    ? OptionalSchema
+                    : Infer<Inner> | undefined
+                  : S extends UnionSchema<infer Members>
+                    ? InferUnion<Members>
+                    : S extends TaggedUnionSchema<infer Key, infer Branches>
+                      ? InferTaggedUnion<Key, Branches>
+                      : never
+
+type InferObject<Shape> = {
+  [K in keyof Shape as Shape[K] extends OptionalSchema ? never : K]: Infer<Shape[K]>
+} & {
+  [K in keyof Shape as Shape[K] extends OptionalSchema ? K : never]?: Infer<Shape[K]>
+}
+
+type InferTuple<Elements> = Elements extends readonly [infer Head, ...infer Tail]
+  ? [Infer<Head>, ...InferTuple<Tail>]
+  : []
+
+type InferUnion<Members> = Members extends readonly [infer Head, ...infer Tail]
+  ? Infer<Head> | InferUnion<Tail>
+  : never
+
+type InferTaggedUnion<Key extends string, Branches> = {
+  [Tag in keyof Branches & string]: {[K in Key]: Tag} & Infer<Branches[Tag]>
+}[keyof Branches & string]
+
+export type SchemaError = {name: 'ValidationFailed'; message: string; path: string}
+
+export declare function string(): StringSchema
+export declare function number(): NumberSchema
+export declare function boolean(): BooleanSchema
+export declare function unknown(): UnknownSchema
+export declare function literal<T extends Primitive>(value: T): LiteralSchema<T>
+export declare function array<S extends Schema>(element: S): ArraySchema<S>
+export declare function object<Shape extends Record<string, Schema>>(
+  shape: Shape,
+): ObjectSchema<Shape>
+export declare function tuple<Elements extends readonly Schema[]>(
+  elements: [...Elements],
+): TupleSchema<Elements>
+export declare function optional<S extends Schema>(inner: S): OptionalSchema<S>
+export declare function union<Members extends readonly Schema[]>(
+  members: [...Members],
+): UnionSchema<Members>
+export declare function taggedUnion<
+  Key extends string,
+  Branches extends Record<string, ObjectSchema>,
+>(key: Key, branches: Branches): TaggedUnionSchema<Key, Branches>
+export declare function parse<S extends Schema>(
+  schema: S,
+  value: unknown,
+): Result<Infer<S>, SchemaError>
+
+export declare const SchemaError: {
+  ValidationFailed: (message: string, path: string) => SchemaError
+}

package/runtime/sleep/sleep.ts

@@ -0,0 +1,14 @@
+export {
+  deepSleep,
+  disableWakeupSource,
+  enableExt0Wakeup,
+  enableExt1Wakeup,
+  enableGpioWakeup,
+  enableTimerWakeup,
+  getWakeupCause,
+  lightSleep,
+} from 'native:sleep'
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/runtime/sleep/types.ts

@@ -0,0 +1,44 @@
+import type {Result} from '../result/types.js'
+
+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>
+
+export declare function getWakeupCause(): string
+
+/** Configure timer wakeup source (microseconds). */
+export declare function enableTimerWakeup(us: number): Result<void, SleepError>
+
+/**
+ * Configure GPIO wakeup for light sleep.
+ * @param pin GPIO pin number
+ * @param level GPIO interrupt type (e.g. 4 = low, 5 = high)
+ */
+export declare function enableGpioWakeup(pin: number, level: number): Result<void, SleepError>
+
+/**
+ * Configure ext0 wakeup for deep sleep (ESP32, ESP32-S2, ESP32-S3 only).
+ * @param pin RTC GPIO pin number
+ * @param level 0 = low, 1 = high
+ */
+export declare function enableExt0Wakeup(pin: number, level: number): Result<void, SleepError>
+
+/**
+ * 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>
+
+/**
+ * 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>
+
+export declare function sleep(ms: number): Promise<void>

package/runtime/sntp/sntp.ts

@@ -0,0 +1,54 @@
+import {err, ok} from 'mikrojs/result'
+import {setTimezone, stop as nativeStop, sync as nativeSync} from 'native:sntp'
+
+import type {Result} from '../result/types.js'
+import type {Sntp, SntpError, SntpOptions, SntpSyncResult, SntpSyncResultWithStop} from './types.js'
+
+// native:sntp emits `InitFailed` / `Cancelled` directly; `Timeout` is a
+// JS-side variant (the Promise racer below owns the clock).
+
+const DEFAULT_SERVERS = ['pool.ntp.org']
+const DEFAULT_TIMEZONE = 'UTC0'
+const DEFAULT_TIMEOUT = 60_000
+
+function sync(
+  options: SntpOptions & {background: true},
+): Promise<Result<SntpSyncResultWithStop, SntpError>>
+function sync(
+  options?: SntpOptions & {background?: false},
+): Promise<Result<SntpSyncResult, SntpError>>
+function sync(
+  options?: SntpOptions & {background?: boolean},
+): Promise<Result<SntpSyncResult | SntpSyncResultWithStop, SntpError>> {
+  const servers = options?.servers ?? DEFAULT_SERVERS
+  const timezone = options?.timezone ?? DEFAULT_TIMEZONE
+  const background = options?.background ?? false
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT
+
+  const startResult = nativeSync(servers, timezone, background)
+  if (!startResult.ok) return Promise.resolve(startResult)
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      nativeStop()
+      resolve(err({name: 'Timeout' as const, ms: timeout}))
+    }, timeout)
+
+    void startResult.value.then((asyncResult) => {
+      clearTimeout(timer)
+      if (!asyncResult.ok) {
+        resolve(asyncResult)
+        return
+      }
+      const result: SntpSyncResult = {time: new Date(asyncResult.value.time)}
+      if (background) {
+        ;(result as SntpSyncResultWithStop).stop = () => nativeStop()
+      }
+      resolve(ok(result))
+    })
+  })
+}
+
+const sntp: Sntp = {sync, setTimezone}
+
+export {sntp}

package/runtime/sntp/types.ts

@@ -0,0 +1,38 @@
+import type {Result} from '../result/types.js'
+
+export interface SntpOptions {
+  /** NTP server(s). Default: ['pool.ntp.org'] */
+  servers?: string[]
+  /** POSIX TZ string, e.g. 'CET-1CEST,M3.5.0,M10.5.0/3'. Default: 'UTC0' */
+  timezone?: string
+  /** Milliseconds before timeout. Default: 60000 */
+  timeout?: number
+}
+
+export interface SntpSyncResult {
+  time: Date
+}
+
+export interface SntpSyncResultWithStop extends SntpSyncResult {
+  stop: () => void
+}
+
+export type SntpError =
+  | {name: 'InitFailed'; message: string}
+  | {name: 'Timeout'; ms: number}
+  | {name: 'Cancelled'}
+
+export interface Sntp {
+  sync(
+    options: SntpOptions & {background: true},
+  ): Promise<Result<SntpSyncResultWithStop, SntpError>>
+  sync(options?: SntpOptions & {background?: false}): Promise<Result<SntpSyncResult, SntpError>>
+  sync(
+    options?: SntpOptions & {background?: boolean},
+  ): Promise<Result<SntpSyncResult | SntpSyncResultWithStop, SntpError>>
+
+  /** Set the POSIX timezone string independently of sync. */
+  setTimezone(tz: string): void
+}
+
+export declare const sntp: Sntp