@solidrt/flux-types 0.0.65 → 0.0.67

package/README.md

@@ -46,7 +46,7 @@ rely on must be named.
 
 - `Flux` global (`version`, `capabilities`).
 - `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
-  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:tty`, `flux:path`, `flux:wasm`, `flux:ffi`,
+  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:tty`, `flux:path`, `flux:wasm`,
   and (on a gui-enabled runtime)
   `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,

package/gui/rendertree.d.ts

@@ -1,7 +1,7 @@
 // The render-tree bridge (gui-enabled runtime only): the low-level surface the
 // renderer drives to build and mutate the native tree - create/insert/delete
 // nodes, write properties, query layout, measure text. Displaying the built
-// tree is the runner's concern ("srt:render" in lattice), not part of this
+// tree is the runner's concern ("sol:render" in lattice), not part of this
 // module; requestFrame here only schedules a future frame.
 
 declare module "flux:rendertree" {

package/gui/spatial.d.ts

@@ -155,7 +155,7 @@ declare module "flux:spatial" {
    * left alone, so rewriting the whole array to move one component never
    * restarts the others (a held write's target counts, so re-sending it
    * does not restart its delay). Each settled component fires one
-   * "spatialTransitionEnd" engine event (srt:events), payload
+   * "spatialTransitionEnd" engine event (sol:events), payload
    * `{ node, component: NodeComponent }` - on a live node; a leaving
    * node's settles feed its free instead (exitNode).
    */
@@ -646,7 +646,7 @@ declare module "flux:spatial" {
    * positive fades in, negative out; past 0 the player is removed).
    * When a player finishes or is removed without finishing (faded out,
    * clip or target destroyed), the "spatialClipEnd" engine event
-   * (srt:events) fires with payload { player, reason: "finished" |
+   * (sol:events) fires with payload { player, reason: "finished" |
    * "dropped" }, before the same frame's handlers.
    */
   export function createPlayer(clip: ClipId, targets: NodeId[], speed: number, loop: boolean, weight: number, fade: number): PlayerId
@@ -661,7 +661,7 @@ declare module "flux:spatial" {
    * the player's time each advance, and its travel since the previous
    * advance (continuous across a loop wrap, weighted by the player's
    * weight) is reported as one "spatialRootMotion" engine event
-   * (srt:events) per advance, payload { player, x, y, z, yaw }, before
+   * (sol:events) per advance, payload { player, x, y, z, yaw }, before
    * the frame's handlers. The translation is given in the root's CURRENT
    * facing (the clip's own turn so far undone), i.e. the character's
    * local frame. `rotation`, a rotation channel of the same clip (the

package/index.d.ts

@@ -11,7 +11,6 @@
 /// <reference path="./modules/net.d.ts" />
 /// <reference path="./modules/mdns.d.ts" />
 /// <reference path="./modules/wasm.d.ts" />
-/// <reference path="./modules/ffi.d.ts" />
 /// <reference path="./modules/isolate.d.ts" />
 /// <reference path="./modules/test.d.ts" />
 
@@ -32,7 +31,7 @@
 // microphone/gpu are flux:* modules like the rest; requestAnimationFrame stays a
 // global (web-standard name). flux:rendertree is the render-tree bridge the
 // renderer drives; displaying the built tree (renderFrame) is the runner's
-// concern (srt:render in lattice), not part of flux.
+// concern (sol:render in lattice), not part of flux.
 /// <reference path="./gui/rendertree.d.ts" />
 /// <reference path="./gui/camera.d.ts" />
 /// <reference path="./gui/microphone.d.ts" />

package/modules/isolate.d.ts

@@ -70,7 +70,7 @@ declare module "flux:isolate" {
   /**
    * A handle on an isolate module: a `"use isolate"` module in a SolidRT
    * project (id = its path relative to the source root, without extension),
-   * or `isolates/<id>.bin`/`.js` next to the entry under standalone flux. Each property is
+   * or `isolates/<id>.fluxbc`/`.js` next to the entry under standalone flux. Each property is
    * an async function that runs the export of that name in a second runtime
    * on its own thread (own heap, own event loop, the non-gui `flux:*`
    * modules). Arguments and results are copied ({@link Sendable}).

package/modules/test.d.ts

@@ -1,6 +1,6 @@
 /**
  * Tests for a flux program: `test` registers one and `expect` asserts
- * inside it. A test file is run by a test host, `srt test <file>` (the
+ * inside it. A test file is run by a test host, `sol test <file>` (the
  * `flux` binary's `--test` mode underneath); imported anywhere else the
  * module throws, since nothing would run the tests.
  *
@@ -28,7 +28,7 @@
  * `Math.random()`, are the same on every run and do not depend on the
  * tests that ran before. It is the engine's generator in kind and
  * resolution, only its start is fixed. An isolate the test spawns is
- * seeded too, with a seed derived from the test's. `srt test --seed <n>`
+ * seeded too, with a seed derived from the test's. `sol test --seed <n>`
  * runs the tests on another sequence.
  *
  * A test that does not finish within 5 seconds of real time fails as timed
@@ -88,6 +88,15 @@ declare module "flux:test" {
     /** The same matchers, inverted: each throws when it does hold. */
     not: Matchers
 
+    /**
+     * For a promise: the same matchers on its rejection reason, each
+     * awaiting the promise first and returning a promise to await in turn.
+     * A promise that fulfills fails the matcher, with or without `not`.
+     * `toThrow` sees the reason as the thrown value, so a rejection reads
+     * like a throw: `await expect(p).rejects.toThrow("no such file")`.
+     */
+    rejects: RejectionMatchers
+
     /** The same value, as `Object.is` sees it: `NaN` is `NaN`, `0` is not `-0`, and two equal objects are not the same. */
     toBe(expected: unknown): void
 
@@ -139,4 +148,11 @@ declare module "flux:test" {
     toBeGreaterThan(expected: number | bigint): void
     toBeGreaterThanOrEqual(expected: number | bigint): void
   }
+
+  /** The matchers of `expect(promise).rejects`: `Matchers`, each returning a promise. */
+  export type RejectionMatchers = {
+    [K in Exclude<keyof Matchers, "rejects">]: Matchers[K] extends (...args: infer A) => void
+      ? (...args: A) => Promise<void>
+      : RejectionMatchers
+  }
 }

package/modules/wasm.d.ts

@@ -1,10 +1,16 @@
 // There is no `WebAssembly` global in flux; this module is the entire wasm
-// surface. Modules run in a pure interpreter (wasmi, no JIT), so this is a
-// portability tool - one compiled module runs on every flux target with no
-// native binaries or dlopen - not a speed tool. Tight typed compute runs
-// somewhat faster than the same loop in JavaScript (a small constant
-// factor, nowhere near browser wasm speed), and every host call costs
-// extra marshalling, so call-heavy code can end up slower.
+// surface. One compiled module runs on every flux target with no native
+// binaries or dlopen, and it is the route for app code that needs more than
+// the JavaScript interpreter. Where the device allows generated code
+// (desktop, 64-bit Android) a module is compiled to machine code on the
+// device the first time it is seen - at install for a `.wasm` under
+// `assets/`, otherwise at `new Module` - and `Flux.capabilities` lists
+// `wasm-native`; a tight typed kernel then runs 18x to 960x faster than the
+// same loop in JavaScript. Where it does not (iOS, 32-bit Android) the
+// module is interpreted and still runs compute 4x to 88x faster than
+// JavaScript. The boundary is the cost on both lanes: a host call out of
+// the module costs 3x to 7x a plain JavaScript call, so keep calls coarse:
+// one call per frame handing over a buffer, never one per entity.
 // Imports must be scalar-signature functions only (no imported
 // memory, globals or tables), which constrains the toolchain on the other
 // side: default emscripten output imports its memory and is rejected, while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",

package/modules/ffi.d.ts

@@ -1,92 +0,0 @@
-declare module "flux:ffi" {
-  /**
-   * A scalar ffi value. i32/f32/f64 marshal as number; i64 and ptr marshal as
-   * BigInt (an address or i64 does not fit a JS number without precision
-   * loss). A number is also accepted where an i64 or ptr is expected.
-   */
-  type FfiValue = number | bigint
-  /**
-   * What a `symbols.*` call accepts per argument. Where a `ptr` is declared,
-   * an ArrayBuffer or typed array may be passed instead of an address: its
-   * data pointer (view offset respected) is handed to the native call and the
-   * buffer stays valid for the call's duration, so native code may read from
-   * and write into it (out-parameters, result buffers). Do not keep such an
-   * address past the call. A detached buffer throws.
-   */
-  type FfiArg = FfiValue | ArrayBuffer | ArrayBufferView
-  type FfiTypeName = "i32" | "i64" | "f32" | "f64" | "ptr"
-
-  /**
-   * One symbol declaration. `returns` defaults to "void". A missing symbol
-   * fails the load unless `optional` is set, in which case its `symbols`
-   * entry is `undefined` (test for it before calling).
-   */
-  type SymbolDecl = {
-    args: FfiTypeName[]
-    returns?: FfiTypeName | "void"
-    optional?: boolean
-  }
-
-  /** The symbols to resolve at load time, keyed by exported name. */
-  type Symbols = Record<string, SymbolDecl>
-
-  /**
-   * A JS function backing a minted C function pointer. Called synchronously
-   * while a `symbols.*` call is on the stack; its return value is coerced to
-   * the callback's declared result type ("void" ignores it). Unlike a call
-   * argument, a callback may not return a buffer as a ptr (the address would
-   * dangle once the callback returns). A throw cannot
-   * abort the native frame: the callback returns zeroes, the native call runs
-   * to completion, and the exception is rethrown after it returns.
-   */
-  type CallbackFunction = (...args: FfiValue[]) => FfiValue | void
-
-  /**
-   * A native shared library. The native counterpart of `flux:wasm`'s Module:
-   * declare what you need up front, every declared symbol must resolve
-   * (unless marked optional).
-   *
-   * There is NO sandbox: the library runs with full process rights, loading
-   * runs its constructors, and a declared signature that does not match the
-   * real ABI is undefined behavior. Only load trusted code.
-   */
-  export class Library {
-    /**
-     * Load a shared library from bytes (e.g. a bundled binary import; written
-     * to a temp file behind the scenes) or a filesystem path, and resolve
-     * every declared symbol. A missing symbol throws unless declared
-     * `optional`.
-     */
-    constructor(source: Uint8Array | ArrayBuffer | string, symbols: Symbols)
-    /**
-     * The declared symbols as bound JS functions, keyed by name. Destructure
-     * once and reuse: the object is rebuilt on each access.
-     */
-    readonly symbols: Record<string, (...args: FfiArg[]) => FfiValue | undefined>
-    /**
-     * Mint a C function pointer (returned as a BigInt address) that invokes
-     * `func` when the library calls it during a `symbols.*` call. Callbacks
-     * may only fire while such a call is on the stack, on the same thread;
-     * the pointer stays valid for the lifetime of the library.
-     */
-    callback(func: CallbackFunction, decl: SymbolDecl): bigint
-    /**
-     * Copy `count` elements out of process memory at `ptr`, in native byte
-     * order. Without `type` (or with "u8") that is `count` bytes as a
-     * Uint8Array; with an ffi type name it is `count` elements as the matching
-     * typed array. No bounds checking is possible: a bad pointer is undefined
-     * behavior.
-     */
-    readMemory(ptr: FfiValue, count: number, type?: "u8"): Uint8Array
-    readMemory(ptr: FfiValue, count: number, type: "i32"): Int32Array
-    readMemory(ptr: FfiValue, count: number, type: "i64"): BigInt64Array
-    readMemory(ptr: FfiValue, count: number, type: "f32"): Float32Array
-    readMemory(ptr: FfiValue, count: number, type: "f64"): Float64Array
-    readMemory(ptr: FfiValue, count: number, type: "ptr"): BigUint64Array
-    /**
-     * Copy the bytes of a typed array or ArrayBuffer into process memory at
-     * `ptr`. Same caveat as readMemory.
-     */
-    writeMemory(ptr: FfiValue, bytes: ArrayBufferView | ArrayBuffer): void
-  }
-}