@solidrt/flux-types 0.0.50 → 0.0.52

package/modules/subprocess.d.ts

@@ -14,6 +14,15 @@ declare module "flux:subprocess" {
      * as UTF-8 strings.
      */
     encoding?: "buffer" | "utf8"
+    /**
+     * `spawn()` only: the child outlives this engine and this process. It is
+     * never killed on drop or reload, has no stdin/stdout/stderr pipes (all
+     * null: `stdout`/`stderr` iterate to nothing, `write` fails) and runs in
+     * its own process group, so a Ctrl+C to the parent does not reach it.
+     * `pid`, `kill()` and `status()` still work. Cannot combine with `stdin`.
+     * What a dev tool uses to launch another runtime instance.
+     */
+    detached?: boolean
   }
 
   /** The buffered result of a child run to completion via {@link Command.output}. */

package/modules/tty.d.ts

@@ -0,0 +1,69 @@
+declare module "flux:tty" {
+  /**
+   * Whether stdin is a terminal this process can use. False for a pipe, a
+   * file, or no stdin at all (a GUI launch), the cases where nobody is there
+   * to prompt; on unix also false for a job backgrounded from an interactive
+   * shell (`cmd &`), which still has the terminal as stdin but would be
+   * stopped by job control the moment it touched it.
+   */
+  export let isTTY: boolean
+  /** One key press in raw mode (see {@link setRawMode}). */
+  export interface Key {
+    /**
+     * Node's keypress names: "return", "backspace", "tab", "escape",
+     * "delete", "insert", "up", "down", "left", "right", "home", "end",
+     * "pageup", "pagedown", "space", "f1".."f12", or the lowercase letter
+     * or symbol typed.
+     */
+    name: string
+    /** The character typed, with its case, for a printable key; else undefined. */
+    char: string | undefined
+    ctrl: boolean
+    /** Alt (Option) held. */
+    meta: boolean
+    shift: boolean
+  }
+  /**
+   * Listen for input on stdin. `"line"` delivers one line per call as the
+   * terminal's own line discipline hands it over (cooked mode: the terminal
+   * does the editing), with the newline stripped; `"key"` delivers one key
+   * press per call while raw mode is on (and nothing arrives as a line
+   * then); `"close"` fires once when stdin reaches end of file (Ctrl-D in
+   * cooked mode, or the pipe closing). A listener holds the process alive
+   * until it unsubscribes; after `"close"` nothing can come, so every tty
+   * listener is dropped then, and a later `on` registers nothing. stdin is
+   * read once per process: a second engine in the same process (an isolate)
+   * gets no input.
+   *
+   * @param event  `"line"`, `"key"` or `"close"`.
+   * @param callback  Receives the line text or the {@link Key}; nothing for
+   *                  `"close"`.
+   * @returns An unsubscribe function.
+   */
+  export function on(event: "line", callback: (line: string) => void): () => void
+  export function on(event: "key", callback: (key: Key) => void): () => void
+  export function on(event: "close", callback: () => void): () => void
+  /**
+   * Like {@link on}, but the listener fires at most once and then unsubscribes.
+   */
+  export function once(event: "line", callback: (line: string) => void): () => void
+  export function once(event: "key", callback: (key: Key) => void): () => void
+  export function once(event: "close", callback: () => void): () => void
+  /**
+   * Switch the terminal's raw mode: no echo, no line editing, no signal keys
+   * (Ctrl-C arrives as a key), and stdin delivers `"key"` events instead of
+   * `"line"`s. The change applies from the next read: a line the terminal
+   * is already collecting is delivered as a line. Turn it off before
+   * exiting; the runtime also restores the terminal on exit and on a panic,
+   * but not on a kill. Throws when stdin is not a terminal.
+   *
+   * While raw, `console.log` output still breaks lines correctly (the
+   * runtime writes "\r\n"); your own {@link write} calls must use "\r\n".
+   */
+  export function setRawMode(on: boolean): void
+  /**
+   * Write `text` to stdout as is and flush: no newline appended, unlike
+   * `console.log`. What a prompt needs.
+   */
+  export function write(text: string): void
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "license": "MIT",
+  "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
   "types": "index.d.ts",
   "files": [

package/standards/abort.d.ts

@@ -0,0 +1,36 @@
+// The web-standard abort primitives. A deliberate subset: an `onabort`
+// handler property only (no addEventListener), a plain-object event (not an
+// Event instance), and no `AbortSignal.timeout`/`any`. Without `DOMException`
+// the default abort reason is an `Error` whose `name` is "AbortError".
+
+/** The event passed to {@link AbortSignal.onabort}. */
+interface AbortEvent {
+  type: "abort"
+}
+
+interface AbortSignal {
+  /** True once the signal has been aborted. */
+  readonly aborted: boolean
+  /** The abort reason; `undefined` until aborted. */
+  readonly reason: any
+  /** Called once when the signal aborts. */
+  onabort: ((event: AbortEvent) => void) | null
+  /** Throws `reason` if the signal is aborted; no-op otherwise. */
+  throwIfAborted(): void
+}
+
+declare let AbortSignal: {
+  prototype: AbortSignal
+  /** An already-aborted signal. */
+  abort(reason?: any): AbortSignal
+}
+
+declare class AbortController {
+  /** The controller's signal; the same object on every read. */
+  readonly signal: AbortSignal
+  /**
+   * Abort the signal with `reason` (default: an `Error` named "AbortError")
+   * and fire its `onabort`. Aborting an already-aborted signal is a no-op.
+   */
+  abort(reason?: any): void
+}

package/standards/crypto.d.ts

@@ -0,0 +1,18 @@
+// crypto. The Web Crypto surface flux provides: `subtle.digest` only. No key
+// material, no encryption, no random: an app hashes bytes (content
+// addressing, integrity checks) and the rest of the standard waits for a need.
+
+interface SubtleCrypto {
+  /**
+   * Hash `data` (a Uint8Array or ArrayBuffer) with `algorithm`, one of
+   * "SHA-256", "SHA-384", "SHA-512" (as a string or `{ name }`). Resolves to
+   * the digest as an ArrayBuffer. Other algorithms (SHA-1 included) reject.
+   */
+  digest(algorithm: string | { name: string }, data: Uint8Array | ArrayBuffer): Promise<ArrayBuffer>
+}
+
+interface Crypto {
+  readonly subtle: SubtleCrypto
+}
+
+declare var crypto: Crypto

package/standards/fetch.d.ts

@@ -1,6 +1,6 @@
 // The Fetch API cluster (Headers, Request, Response, fetch). A deliberate subset
 // of the WHATWG Fetch standard: flux provides exactly these members and no more
-// (no Blob, FormData, ReadableStream, clone(), AbortSignal, ...).
+// (no Blob, FormData, ReadableStream, clone(), ...).
 // Grouped in one file because the four share BodyInit/HeadersInit and reference
 // each other.
 
@@ -70,6 +70,13 @@ interface RequestInit {
    * throttled.
    */
   cache?: "force-cache" | "reload" | "default" | "no-store" | "no-cache"
+  /**
+   * Abort signal for `fetch`: aborting rejects the fetch promise with the
+   * signal's `reason` and drops the request mid-flight; a fetch on an
+   * already-aborted signal rejects without sending anything. Ignored by the
+   * `Request` constructor.
+   */
+  signal?: AbortSignal
 }
 
 /**

package/standards/time.d.ts

@@ -2,14 +2,20 @@
 // from the browser in two ways: the delay is required, and no extra callback
 // arguments are forwarded.
 //
-// In a GUI runtime the whole time surface here is FRAME-STEPPED: timers and
-// performance.now() march on the same paced timeline as onFrame and
-// requestAnimationFrame, quantized to frames. So timer resolution is one
-// frame (~16 ms at 60 Hz; a setTimeout of 0 runs on the next frame), an
-// interval fires at most once per frame, and pausing the runtime clock (the
-// dev tools' set_time_scale 0) freezes all of it together deterministically.
-// Date.now() is the wall-clock escape hatch: it always reports real calendar
-// time. Headless flux (scripts, servers) keeps ordinary wall-clock timers.
+// In a GUI runtime the timers are FRAME-QUANTIZED but WALL-ACCURATE: a
+// deadline is measured against the real clock from the moment of
+// registration, and firing happens on frame boundaries. So a timer fires at
+// the first frame at or after its deadline - at least `ms` after
+// registration, at most one frame late (~16 ms at 60 Hz; a setTimeout of 0
+// runs on the next frame) - and deadlines do not drift when frames run
+// slow. An interval fires at most once per frame (missed periods collapse
+// instead of storming). Pausing the runtime clock (the dev tools'
+// set_time_scale 0) freezes timers and frame callbacks together; a timer
+// that came due while the app was suspended (backgrounded) fires on the
+// resume frame. performance.now() is real elapsed time, for measuring
+// work; the onFrame / requestAnimationFrame timestamp is a separate paced
+// animation timeline. Date.now() is calendar time. Headless flux (scripts,
+// servers) keeps ordinary wall-clock timers.
 
 /**
  * Run `callback` after at least `ms` milliseconds. Returns a timer id for
@@ -33,17 +39,16 @@ declare function queueMicrotask(callback: () => void): void
 
 declare let performance: {
   /**
-   * Milliseconds since a monotonic origin (high-resolution, not wall-clock). Use
-   * for measuring durations, not for calendar time. In a GUI runtime this is
-   * the paced frame timeline (same clock as the onFrame/requestAnimationFrame
-   * timestamps, frozen while the runtime clock is paused); for real elapsed
-   * wall time use Date.now().
+   * Milliseconds elapsed since the runtime started (high-resolution,
+   * monotonic, sub-millisecond). Real time: it keeps advancing across
+   * synchronous work and while the runtime clock is paused, so it is the
+   * clock for measuring durations. For frame time use the onFrame /
+   * requestAnimationFrame timestamp; for calendar time use Date.now().
    */
   now(): number
   /**
-   * Wall-clock time (ms since the Unix epoch) when the runtime started. Unlike
-   * the browser, timeOrigin + now() is not the current wall-clock time: now()
-   * runs on the paced runtime timeline, which can be frozen or scaled.
+   * Wall-clock time (ms since the Unix epoch) when the runtime started, so
+   * timeOrigin + now() tracks Date.now().
    */
   readonly timeOrigin: number
 }