@solidrt/flux-types 0.0.66 → 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/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" />
 

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.66",
+  "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
-  }
-}