@mikrojs/native 0.0.7

package/runtime/ble/ble.ts

@@ -0,0 +1,231 @@
+import {err, ok} from 'mikrojs/result'
+import {Ble as NativeBle} from 'native:ble'
+
+import type {Result} from '../result/types.js'
+import type {
+  AdvertiseHandle,
+  AdvertiseOptions,
+  Ble,
+  BleError,
+  Characteristic,
+  CharacteristicProperty,
+  Peripheral,
+  PeripheralEventMap,
+  Service,
+} from './types.js'
+import {parseUuid} from './uuid.js'
+import {ADV_PAYLOAD_MAX, computeAdvertisingPayloadSize, validateInterval} from './validators.js'
+
+// Inline constructors for the JS-side validated variants (native:ble doesn't
+// emit these — they come from validateInterval, validateServices, and the
+// advertise payload-size check). Kept as `const` factories so validators.ts
+// can stay decoupled from the BleError shape for unit testing.
+const invalidIntervalFactory = {
+  InvalidInterval: (min: number, max: number) => ({name: 'InvalidInterval' as const, min, max}),
+  AdvertisingPayloadTooLarge: (bytes: number, max: number) => ({
+    name: 'AdvertisingPayloadTooLarge' as const,
+    bytes,
+    max,
+  }),
+}
+
+// ── Characteristic property bitmask (must match native side) ────────
+// Native code reads these as BLE_GATT_CHR_F_* flags via a lookup table.
+const PROP_READ = 0x01
+const PROP_WRITE = 0x02
+const PROP_WRITE_WITHOUT_RESPONSE = 0x04
+const PROP_NOTIFY = 0x08
+const PROP_INDICATE = 0x10
+
+const PROP_BY_NAME: Record<CharacteristicProperty, number> = {
+  read: PROP_READ,
+  write: PROP_WRITE,
+  writeWithoutResponse: PROP_WRITE_WITHOUT_RESPONSE,
+  notify: PROP_NOTIFY,
+  indicate: PROP_INDICATE,
+}
+
+function propertiesToBitmask(props: readonly CharacteristicProperty[]): number {
+  let mask = 0
+  for (const p of props) mask |= PROP_BY_NAME[p] ?? 0
+  return mask
+}
+
+// ── Service/characteristic validation ───────────────────────────────
+
+function invalidProps(uuid: string, reason: string): BleError {
+  return {name: 'InvalidProperties', uuid, reason}
+}
+
+function validateCharacteristic(char: Characteristic): BleError | undefined {
+  if (parseUuid(char.uuid) === null) return {name: 'InvalidUuid', value: char.uuid}
+
+  if (!Array.isArray(char.properties) || char.properties.length === 0) {
+    return invalidProps(char.uuid, 'at least one property required')
+  }
+  // Array.isArray widens readonly arrays to any[]; cast back for the lookup.
+  const props = char.properties as readonly CharacteristicProperty[]
+  for (const p of props) {
+    if (PROP_BY_NAME[p] === undefined) {
+      return invalidProps(char.uuid, `unknown property: ${String(p)}`)
+    }
+  }
+
+  if (char.writeMode !== undefined && char.writeMode !== 'advisory') {
+    return invalidProps(
+      char.uuid,
+      `writeMode '${String(char.writeMode)}' is not supported in this release`,
+    )
+  }
+  if (char.security !== undefined && char.security !== 'open') {
+    return invalidProps(
+      char.uuid,
+      `security '${String(char.security)}' is not supported in this release`,
+    )
+  }
+
+  return undefined
+}
+
+function validateService(service: Service): BleError | undefined {
+  if (parseUuid(service.uuid) === null) return {name: 'InvalidUuid', value: service.uuid}
+
+  if (!Array.isArray(service.characteristics) || service.characteristics.length === 0) {
+    return invalidProps(service.uuid, 'service must declare at least one characteristic')
+  }
+
+  const seen = new Set<string>()
+  for (const char of service.characteristics) {
+    const charErr = validateCharacteristic(char)
+    if (charErr) return charErr
+    const normalized = parseUuid(char.uuid)!.normalized
+    if (seen.has(normalized)) return {name: 'DuplicateCharacteristic', uuid: normalized}
+    seen.add(normalized)
+  }
+
+  return undefined
+}
+
+function validateServices(services: Service[]): BleError | undefined {
+  const seen = new Set<string>()
+  for (const service of services) {
+    const svcErr = validateService(service)
+    if (svcErr) return svcErr
+    const normalized = parseUuid(service.uuid)!.normalized
+    if (seen.has(normalized)) return invalidProps(service.uuid, 'duplicate service uuid')
+    seen.add(normalized)
+  }
+  return undefined
+}
+
+/**
+ * Converts the user-facing `Service[]` shape into the normalized form the
+ * native module expects: property arrays become bitmasks, UUIDs are
+ * normalized to their canonical lowercase form so that subsequent
+ * setValue / notify calls can use the same UUID strings in any case and
+ * still match what's registered. The `onWrite` callback is passed through
+ * as-is; the native side dup-refs it during GATT registration.
+ */
+function normalizeServices(services: Service[]) {
+  return services.map((s) => ({
+    uuid: parseUuid(s.uuid)!.normalized,
+    characteristics: s.characteristics.map((c) => ({
+      uuid: parseUuid(c.uuid)!.normalized,
+      properties: propertiesToBitmask(c.properties),
+      value: c.value,
+      onWrite: c.onWrite,
+    })),
+  }))
+}
+
+const native = new NativeBle()
+
+const ble: Ble = {
+  get name(): string {
+    return native.getName()
+  },
+  set name(value: string) {
+    native.setName(value)
+  },
+
+  get address(): string {
+    const result = native.getAddress()
+    return result.ok ? result.value : ''
+  },
+
+  get txPower(): number {
+    const result = native.getTxPower()
+    return result.ok ? result.value : 0
+  },
+  set txPower(dbm: number) {
+    native.setTxPower(dbm)
+  },
+
+  stop(): Result<void, BleError> {
+    return native.stop()
+  },
+}
+
+const peripheral: Peripheral = {
+  async advertise(options: AdvertiseOptions = {}): Promise<Result<AdvertiseHandle, BleError>> {
+    const intervalError = validateInterval(options.interval, invalidIntervalFactory)
+    if (intervalError) return err(intervalError)
+
+    if (options.services !== undefined) {
+      const svcErr = validateServices(options.services)
+      if (svcErr) return err(svcErr)
+    }
+
+    const payloadSize = computeAdvertisingPayloadSize(options, native.getName().length)
+    if (payloadSize > ADV_PAYLOAD_MAX) {
+      return err(invalidIntervalFactory.AdvertisingPayloadTooLarge(payloadSize, ADV_PAYLOAD_MAX))
+    }
+
+    const nativeOptions = {
+      ...options,
+      services: options.services ? normalizeServices(options.services) : undefined,
+    }
+
+    const result = native.advertise(nativeOptions as Parameters<typeof native.advertise>[0])
+    if (!result.ok) return result
+
+    const handle: AdvertiseHandle = {
+      stop(): Result<void, BleError> {
+        return native.stopAdvertising()
+      },
+      setValue(
+        serviceUuid: string,
+        characteristicUuid: string,
+        value: Uint8Array,
+      ): Result<void, BleError> {
+        const svc = parseUuid(serviceUuid)
+        if (!svc) return err({name: 'InvalidUuid' as const, value: serviceUuid})
+        const chr = parseUuid(characteristicUuid)
+        if (!chr) return err({name: 'InvalidUuid' as const, value: characteristicUuid})
+        return native.setValue(svc.normalized, chr.normalized, value)
+      },
+      notify(
+        serviceUuid: string,
+        characteristicUuid: string,
+        value: Uint8Array,
+      ): Result<void, BleError> {
+        const svc = parseUuid(serviceUuid)
+        if (!svc) return err({name: 'InvalidUuid' as const, value: serviceUuid})
+        const chr = parseUuid(characteristicUuid)
+        if (!chr) return err({name: 'InvalidUuid' as const, value: characteristicUuid})
+        return native.notify(svc.normalized, chr.normalized, value)
+      },
+    }
+    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)
+  },
+}
+
+export {ble, peripheral}

package/runtime/ble/types.ts

@@ -0,0 +1,194 @@
+import type {Result} from '../result/types.js'
+
+/** Advertising interval range in milliseconds. */
+export interface AdvertiseInterval {
+  /** Minimum interval. Non-connectable: ≥ 20ms. Connectable: ≥ 100ms. */
+  min: number
+  /** Maximum interval. ≤ 10240ms. Must be ≥ min. */
+  max: number
+}
+
+/**
+ * A property that a GATT characteristic exposes. The set of declared properties
+ * determines which operations centrals can perform.
+ */
+export type CharacteristicProperty =
+  | 'read'
+  | 'write'
+  | 'writeWithoutResponse'
+  | 'notify'
+  | 'indicate'
+
+/**
+ * A GATT characteristic declaration. The `uuid` is either a 16-bit shorthand
+ * (`"180f"`) or a full 128-bit form (`"6e400001-b5a3-f393-e0a9-e50e24dcca9e"`).
+ */
+export interface Characteristic {
+  uuid: string
+  properties: readonly CharacteristicProperty[]
+  /**
+   * Initial value for the characteristic. Updated via `handle.setValue()` at
+   * runtime. When a central performs a GATT read, it sees the current value.
+   */
+  value?: Uint8Array
+  /**
+   * Called after a central writes to this characteristic. Runs asynchronously
+   * on the JS loop thread after the write has already been acknowledged at
+   * the GATT layer — it is advisory only and cannot reject the write. The
+   * only accepted `writeMode` is `'advisory'`, which is also the default.
+   */
+  onWrite?: (value: Uint8Array) => void
+  /**
+   * Only `'advisory'` is accepted. Advisory writes are acknowledged at the
+   * GATT layer before `onWrite` runs, so the handler cannot reject the write.
+   */
+  writeMode?: 'advisory'
+  /**
+   * Only `'open'` is accepted. Characteristics are accessible without
+   * authentication or encryption.
+   */
+  security?: 'open'
+}
+
+/** A GATT service declaration containing one or more characteristics. */
+export interface Service {
+  uuid: string
+  characteristics: Characteristic[]
+}
+
+export interface AdvertiseOptions {
+  /** Device name included in the advertising packet. Defaults to `ble.name`. */
+  name?: string
+  /**
+   * Whether centrals can connect to the advertising device. Defaults to
+   * `false` (broadcaster mode). Set to `true` together with `services` to
+   * run a connectable GATT peripheral.
+   */
+  connectable?: boolean
+  /**
+   * GATT services to register on the peripheral. Services are declared
+   * upfront and frozen for the lifetime of the BLE stack — to change them,
+   * call `ble.stop()` and `advertise()` again.
+   */
+  services?: Service[]
+  /** Advertising interval range. Defaults to NimBLE's defaults (~100–150ms). */
+  interval?: AdvertiseInterval
+  /**
+   * Include the current TX power as a 3-byte field in the advertising payload.
+   * Useful for RSSI-based distance estimation.
+   */
+  includeTxPower?: boolean
+  /**
+   * Manufacturer-specific data bytes. The first two bytes must be the company ID
+   * (little-endian) per the BLE spec.
+   */
+  manufacturerData?: Uint8Array
+}
+
+export interface AdvertiseHandle {
+  /** Stops this advertising session. Does not tear down the BLE stack. */
+  stop(): Result<void, BleError>
+  /**
+   * Updates the cached value of a characteristic. Subsequent GATT reads by
+   * connected centrals will return the new bytes. Does not push updates to
+   * subscribers. Use `notify()` to both update and push in one call, or
+   * call `setValue()` followed by `notify()` if you want explicit control.
+   *
+   * Returns `err(NoSuchCharacteristic)` if either UUID is unknown.
+   */
+  setValue(
+    serviceUuid: string,
+    characteristicUuid: string,
+    value: Uint8Array,
+  ): Result<void, BleError>
+  /**
+   * Sends a notification with the given bytes to every currently-subscribed
+   * central. The characteristic must declare `'notify'` in its properties,
+   * and centrals must have enabled notifications via the CCCD descriptor.
+   *
+   * If no central is subscribed, this is a silent no-op and returns ok.
+   * If the payload exceeds the minimum MTU across active subscribers minus
+   * the 3-byte ATT header, returns `err(ValueTooLarge)` without sending.
+   * Per-subscriber send failures (backpressure, dropped connection) are
+   * logged at warn level and do not cause this call to return an error;
+   * notify is explicitly best-effort.
+   *
+   * This also updates the characteristic's cached value so subsequent
+   * reads return the notified bytes.
+   */
+  notify(serviceUuid: string, characteristicUuid: string, value: Uint8Array): Result<void, BleError>
+}
+
+export type BleError =
+  | {name: 'StackInitFailed'; message: string}
+  | {name: 'ControllerInitFailed'; message: string}
+  | {name: 'AlreadyAdvertising'}
+  | {name: 'NotInitialized'}
+  | {name: 'AdvertiseStartFailed'; message: string}
+  | {name: 'AdvertiseStopFailed'; message: string}
+  | {name: 'AdvertisingPayloadTooLarge'; bytes: number; max: number}
+  | {name: 'InvalidInterval'; min: number; max: number}
+  | {name: 'InvalidUuid'; value: string}
+  | {name: 'DuplicateCharacteristic'; uuid: string}
+  | {name: 'InvalidProperties'; uuid: string; reason: string}
+  | {name: 'GattRegistrationFailed'; message: string}
+  | {name: 'GattAlreadyRegistered'}
+  | {name: 'NoSuchCharacteristic'; uuid: string}
+  | {name: 'NotConnected'}
+  | {name: 'ValueTooLarge'; uuid: string; bytes: number; max: number}
+  | {name: 'NotifyFailed'; message: string}
+  | {name: 'StackShutdown'}
+  | {name: 'SetFailed'; message: string}
+  | {name: 'GetFailed'; message: string}
+
+export interface Ble {
+  /** Device name used in advertising. Defaults to `"mikrojs-xxxxxx"` (last 3 bytes of MAC). */
+  name: string
+  /** Global radio TX power in dBm. Valid range depends on the chip. */
+  txPower: number
+  /** BLE MAC address as `"aa:bb:cc:dd:ee:ff"`. */
+  readonly address: string
+  /**
+   * Tears down the BLE stack entirely, reclaiming all RAM.
+   * The next BLE call re-initializes from scratch.
+   */
+  stop(): Result<void, BleError>
+}
+
+/** Information about a connected central. */
+export interface ConnectionInfo {
+  /** Opaque stable identifier for this connection (NimBLE conn_handle). */
+  id: number
+  /** The peer's BLE address in canonical `"aa:bb:cc:dd:ee:ff"` form. */
+  address: string
+  /** Current negotiated ATT MTU in bytes. */
+  mtu: number
+}
+
+/** Information about a mid-session MTU change. */
+export interface MtuInfo {
+  id: number
+  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
+}
+
+export declare const ble: Ble
+export declare const peripheral: Peripheral

package/runtime/ble/uuid.ts

@@ -0,0 +1,89 @@
+// BLE UUID parsing. Pure helper, no native dependency.
+//
+// BLE has two practical UUID sizes:
+//   - 16-bit: SIG-assigned UUIDs like 0x180F (Battery Service). Written as
+//     4 hex characters: "180f".
+//   - 128-bit: vendor-custom UUIDs. Written in canonical dashed form:
+//     "6e400001-b5a3-f393-e0a9-e50e24dcca9e".
+//
+// 32-bit UUIDs exist in the spec but are nearly never used in practice; we
+// don't accept them here. Users who need one can write the full 128-bit form.
+
+/** Parsed 16-bit UUID. */
+export interface ParsedUuid16 {
+  readonly kind: 16
+  /** The 16-bit value, 0..0xFFFF. */
+  readonly value: number
+  /** Normalized lowercase form, e.g. "180f". */
+  readonly normalized: string
+}
+
+/** Parsed 128-bit UUID. */
+export interface ParsedUuid128 {
+  readonly kind: 128
+  /**
+   * 16 bytes in network / big-endian order — the same order you'd read off
+   * a formatted UUID string like "0000180f-0000-1000-8000-00805f9b34fb".
+   * Native code is responsible for converting to NimBLE's internal
+   * little-endian representation when building `ble_uuid128_t`.
+   */
+  readonly bytes: Uint8Array
+  /** Normalized lowercase form, e.g. "6e400001-b5a3-f393-e0a9-e50e24dcca9e". */
+  readonly normalized: string
+}
+
+export type ParsedUuid = ParsedUuid16 | ParsedUuid128
+
+const HEX_16 = /^[0-9a-fA-F]{4}$/
+const HEX_128 = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
+
+/**
+ * Parses a BLE UUID string into a structured form. Accepts:
+ *   - 4-char shorthand for 16-bit UUIDs: `"180f"`, `"180F"`
+ *   - Full 128-bit form with dashes: `"6e400001-b5a3-f393-e0a9-e50e24dcca9e"`
+ *
+ * Leading/trailing whitespace is not accepted. Returns `null` for invalid
+ * input so the caller can wrap the original value in an `InvalidUuid` error.
+ */
+export function parseUuid(input: unknown): ParsedUuid | null {
+  if (typeof input !== 'string') return null
+
+  if (HEX_16.test(input)) {
+    return {
+      kind: 16,
+      value: Number.parseInt(input, 16),
+      normalized: input.toLowerCase(),
+    }
+  }
+
+  if (HEX_128.test(input)) {
+    const normalized = input.toLowerCase()
+    const hexOnly = normalized.replace(/-/g, '')
+    const bytes = new Uint8Array(16)
+    for (let i = 0; i < 16; i++) {
+      bytes[i] = Number.parseInt(hexOnly.substring(i * 2, i * 2 + 2), 16)
+    }
+    return {kind: 128, bytes, normalized}
+  }
+
+  return null
+}
+
+/**
+ * Compares two parsed UUIDs for equality. Two 16-bit UUIDs are equal iff
+ * their values match; two 128-bit UUIDs are equal iff all 16 bytes match.
+ * A 16-bit and a 128-bit UUID are never equal here — callers that want to
+ * compare a 16-bit shorthand against its canonical 128-bit expansion should
+ * normalize to one form first.
+ */
+export function uuidsEqual(a: ParsedUuid, b: ParsedUuid): boolean {
+  if (a.kind !== b.kind) return false
+  if (a.kind === 16) return a.value === (b as ParsedUuid16).value
+  const ab = a.bytes
+  const bb = (b as ParsedUuid128).bytes
+  if (ab.length !== bb.length) return false
+  for (let i = 0; i < ab.length; i++) {
+    if (ab[i] !== bb[i]) return false
+  }
+  return true
+}

package/runtime/ble/validators.ts

@@ -0,0 +1,61 @@
+// Pure validation helpers for the BLE module. Extracted so they can be
+// unit-tested on the host without pulling in the native `native:ble` module.
+
+import type {AdvertiseInterval, AdvertiseOptions, BleError} from './types.js'
+
+// BLE spec bounds for advertising interval, in milliseconds.
+// Non-connectable and connectable modes have different minimums at the spec
+// level. We use the looser non-connectable bound in JS and let NimBLE enforce
+// the stricter connectable limit at advertise_start time.
+export const MIN_INTERVAL_MS = 20
+export const MAX_INTERVAL_MS = 10240
+
+// BLE advertising packet is 31 bytes.
+export const ADV_PAYLOAD_MAX = 31
+
+// Must mirror the BleError factory in ble.ts. Decoupled here so validators
+// don't import from a file that touches the native module.
+type BleErrorFactory = {
+  InvalidInterval: (min: number, max: number) => BleError
+  AdvertisingPayloadTooLarge: (bytes: number, max: number) => BleError
+}
+
+export function validateInterval(
+  interval: AdvertiseInterval | undefined,
+  factory: BleErrorFactory,
+): BleError | undefined {
+  if (interval === undefined) return undefined
+  const {min, max} = interval
+  if (
+    !Number.isFinite(min) ||
+    !Number.isFinite(max) ||
+    min < MIN_INTERVAL_MS ||
+    max > MAX_INTERVAL_MS ||
+    min > max
+  ) {
+    return factory.InvalidInterval(min, max)
+  }
+  return undefined
+}
+
+/**
+ * Estimates the total bytes the advertising packet will occupy with the
+ * given options. Accounts for the mandatory flags field, the device name,
+ * the optional TX power field, and optional manufacturer data.
+ *
+ * Each AD structure costs 2 bytes of overhead (length byte + type byte)
+ * plus the payload size.
+ */
+export function computeAdvertisingPayloadSize(
+  options: AdvertiseOptions,
+  fallbackNameLength: number,
+): number {
+  let total = 3 // flags: 1 length + 1 type + 1 byte value
+  const nameLen = options.name !== undefined ? options.name.length : fallbackNameLength
+  if (nameLen > 0) total += 2 + nameLen
+  if (options.includeTxPower) total += 3
+  if (options.manufacturerData !== undefined) {
+    total += 2 + options.manufacturerData.length
+  }
+  return total
+}

package/runtime/cbor/cbor.ts

@@ -0,0 +1 @@
+export {decode, encode} from 'native:cbor'

package/runtime/cbor/types.ts

@@ -0,0 +1,8 @@
+import type {Result} from '../result/types.js'
+
+export type CborError =
+  | {name: 'EncodeFailed'; message: string}
+  | {name: 'DecodeFailed'; message: string}
+
+export declare function encode(value: unknown): Result<Uint8Array, CborError>
+export declare function decode(data: Uint8Array): Result<unknown, CborError>

package/runtime/console/types.ts

@@ -0,0 +1,50 @@
+import type {FormatFn, FormatString} from '../format/types.js'
+import type {InspectFn} from '../inspect/types.js'
+
+type ThemeToken =
+  | 'annotation'
+  | 'boolean'
+  | 'comment'
+  | 'date'
+  | 'error'
+  | 'warning'
+  | 'function'
+  | 'identifier'
+  | 'keyword'
+  | 'null'
+  | 'number'
+  | 'other'
+  | 'regexp'
+  | 'string'
+  | 'symbol'
+  | 'type'
+  | 'undefined'
+  | 'bigint'
+
+export type ColorizeFn = (themeToken: ThemeToken, value: string) => string
+
+export interface LogFn {
+  (fmt: FormatString, ...args: any[]): void
+
+  (...args: any[]): void
+}
+
+export type ConsoleAPI = {
+  log: LogFn
+  error: LogFn
+  info: LogFn
+  warn: LogFn
+  debug: LogFn
+}
+
+export declare function createConsole(config: {
+  inspect: InspectFn
+  colorize: ColorizeFn
+  format: FormatFn
+  stdout: {write: (output: string) => void}
+}): ConsoleAPI
+
+export declare const log: ConsoleAPI['log']
+export declare const info: ConsoleAPI['info']
+export declare const warn: ConsoleAPI['warn']
+export declare const error: ConsoleAPI['error']

package/runtime/env/env.ts

@@ -0,0 +1,17 @@
+import type {Env} from './types.js'
+
+export const env: Env = {
+  get(key: string): string | undefined {
+    return (import.meta.env as Record<string, string | undefined>)[key]
+  },
+  has(key: string): boolean {
+    return key in import.meta.env
+  },
+  require(key: string): string {
+    const value = (import.meta.env as Record<string, string | undefined>)[key]
+    if (value === undefined) {
+      throw new TypeError(`Required environment variable "${key}" is not set`)
+    }
+    return value
+  },
+}

package/runtime/env/types.ts

@@ -0,0 +1,12 @@
+export interface Env {
+  /** Get an environment variable, or `undefined` if not set. */
+  get(key: string): string | undefined
+
+  /** Check whether an environment variable is set. */
+  has(key: string): boolean
+
+  /** Get a required environment variable. Panics if not set. */
+  require(key: string): string
+}
+
+export declare const env: Env

package/runtime/format/types.ts

@@ -0,0 +1,4 @@
+export type FormatString = string & {}
+
+export type FormatFn = (fmt: FormatString, ...args: any[]) => string
+export declare const format: FormatFn