@solidrt/flux-types 0.0.26 → 0.0.28

package/README.md

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

package/gui/gpu.d.ts

@@ -36,6 +36,65 @@ declare module "flux:gpu" {
   ): number
   /** Update a shader texture's float uniforms by name and re-render it. */
   export function setShaderParams(id: number, params: Record<string, number>): void
+
+  export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
+  /**
+   * One float attribute of an interleaved vertex. The attribute list's order
+   * defines the byte layout; locations are resolved by name against the
+   * vertex shader's `in` declarations.
+   */
+  export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
+
+  /**
+   * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
+   * the given size and render it once. Sources without a `#version` line get
+   * a 300 es preamble declaring `iResolution`/`iTime` (no vUV: varyings are
+   * the pipeline's own). `attributes` describes one interleaved vertex in
+   * `buffer` (a {@link createBuffer} id); omit both for attributeless
+   * rendering via gl_VertexID. `vertexCount` defaults to the whole buffer
+   * (buffer size / vertex stride). With `depth: true` the pipeline gets a
+   * private depth buffer, cleared and tested on every render. The target is
+   * cleared to `clearColor` (default transparent black) before each draw.
+   * Returns a texture id: display it with `<texture src>`, drive uniforms via
+   * the `params` prop or {@link setShaderParams}, destroy with
+   * {@link destroyTexture}.
+   */
+  export function createPipeline(
+    vertexSrc: string,
+    fragmentSrc: string,
+    width: number,
+    height: number,
+    opts?: {
+      params?: Record<string, number>
+      textures?: Record<string, number>
+      attributes?: VertexAttribute[]
+      buffer?: number
+      topology?: Topology
+      vertexCount?: number
+      depth?: boolean
+      clearColor?: [number, number, number, number]
+    },
+  ): number
+
+  /**
+   * Create a vertex buffer from raw bytes (interleave attribute data to match
+   * the pipeline's attribute list). Buffer ids are their own space, separate
+   * from texture ids.
+   */
+  export function createBuffer(data: Uint8Array): number
+  /**
+   * Overwrite part of a vertex buffer at `byteOffset` (default 0), within the
+   * size it was created with. Pipelines drawing from the buffer re-render
+   * with their last-applied params.
+   */
+  export function writeBuffer(id: number, data: Uint8Array, byteOffset?: number): void
+  /** Destroy a vertex buffer. Destroy pipelines drawing from it first. */
+  export function destroyBuffer(id: number): void
+  /**
+   * Set how many vertices a pipeline texture draws and re-render it, e.g.
+   * after writing a variable amount of dynamic geometry into its buffer.
+   */
+  export function setDrawCount(id: number, count: number): void
   /**
    * Capture a render-tree node's subtree into a new GPU texture, resolving once
    * it has been rendered on the next paint pass. The node must be attached to

package/index.d.ts

@@ -7,6 +7,8 @@
 /// <reference path="./modules/p2p.d.ts" />
 /// <reference path="./modules/net.d.ts" />
 /// <reference path="./modules/mdns.d.ts" />
+/// <reference path="./modules/wasm.d.ts" />
+/// <reference path="./modules/ffi.d.ts" />
 
 // Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
 // ships no lib.dom / @types/bun: these declarations are the sole source for

package/modules/ffi.d.ts

@@ -0,0 +1,63 @@
+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
+  type FfiTypeName = "i32" | "i64" | "f32" | "f64" | "ptr"
+
+  /** One symbol declaration. `returns` defaults to "void". */
+  type SymbolDecl = {
+    args: FfiTypeName[]
+    returns?: FfiTypeName | "void"
+  }
+
+  /** 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). 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.
+   *
+   * 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.
+     */
+    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: FfiValue[]) => 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 `len` bytes out of process memory at `ptr`. No bounds checking is
+     * possible: a bad pointer is undefined behavior.
+     */
+    readMemory(ptr: FfiValue, len: number): Uint8Array
+    /** Copy `bytes` into process memory at `ptr`. Same caveat as readMemory. */
+    writeMemory(ptr: FfiValue, bytes: Uint8Array | ArrayBuffer): void
+  }
+}

package/modules/fs.d.ts

@@ -16,6 +16,8 @@ declare module "flux:fs" {
     text(): Promise<string>
     /** Read the whole file as raw bytes. */
     bytes(): Promise<Uint8Array>
+    /** Read the whole file as an ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>
     /** Read and parse the file as JSON. */
     json(): Promise<any>
     /** Resolve to whether the file exists. */
@@ -40,6 +42,11 @@ declare module "flux:fs" {
     entries(): Promise<DirEntry[]>
     /** Resolve to whether the directory exists. */
     exists(): Promise<boolean>
+    /**
+     * Create the directory, including any missing parents. Succeeds if it
+     * already exists.
+     */
+    create(): Promise<void>
   }
 
   /**

package/modules/wasm.d.ts

@@ -0,0 +1,87 @@
+declare module "flux:wasm" {
+  /**
+   * A scalar wasm value. i32/f32/f64 marshal as number; i64 marshals as BigInt
+   * (an i64 does not fit a JS number without precision loss). A number is also
+   * accepted where an i64 is expected.
+   */
+  type WasmValue = number | bigint
+  type WasmTypeName = "i32" | "i64" | "f32" | "f64"
+
+  /** A function import a module requires, `{ module, name }`-keyed like the standard. */
+  type ImportInfo = {
+    module: string
+    name: string
+    params: WasmTypeName[]
+    results: WasmTypeName[]
+  }
+
+  /**
+   * An instance export. `params`/`results` are present only for functions with
+   * all-scalar signatures.
+   */
+  type ExportInfo =
+    | { name: string; kind: "function"; params: WasmTypeName[]; results: WasmTypeName[] }
+    | { name: string; kind: "memory" | "other" }
+
+  /**
+   * A host function backing a guest import. Called synchronously during an
+   * export call; must return values matching the import's declared results:
+   * nothing for zero results, a single value for one, an array for several.
+   * A throw aborts the wasm call and propagates. May re-enter the instance
+   * (e.g. via {@link Instance.callIndirect}).
+   */
+  type HostFunction = (...args: WasmValue[]) => WasmValue | WasmValue[] | void
+
+  /** Host functions keyed by import module then name, e.g. `{ env: { mul } }`. */
+  type Imports = Record<string, Record<string, HostFunction>>
+
+  export class Module {
+    /**
+     * Parse and validate a wasm binary (wat text bytes are also accepted).
+     * Throws on invalid input or on an unsupported import (non-function, or
+     * non-scalar signature).
+     */
+    constructor(bytes: Uint8Array | ArrayBuffer)
+    /**
+     * The function imports this module requires, in the order the host
+     * functions are indexed.
+     */
+    readonly imports: ImportInfo[]
+    /**
+     * Instantiate with host functions. Every listed import must resolve to a
+     * function; a missing or non-function entry throws.
+     */
+    instantiate(imports: Imports): Instance
+  }
+
+  /** An instantiated module. Created with {@link Module.instantiate}. */
+  export class Instance {
+    /** The module's exports. */
+    readonly exports: ExportInfo[]
+    /**
+     * Call an exported function. Arguments are coerced to the export's declared
+     * parameter types. Returns `undefined` for no results, the single value for
+     * one, or an array for several. Host imports hit during the call dispatch
+     * to the functions passed to `instantiate`; a throw from one aborts the
+     * call.
+     */
+    call(name: string, ...args: WasmValue[]): WasmValue | WasmValue[] | undefined
+    /**
+     * Call a function by its index in the module's exported function table:
+     * `table[index](...args)`. This is how a host function invokes a guest
+     * function pointer it received as an integer (e.g. a C callback). Same
+     * coercion and host-import dispatch rules as {@link call}; safe to use
+     * from within a host function (re-entrant).
+     */
+    callIndirect(index: number, ...args: WasmValue[]): WasmValue | WasmValue[] | undefined
+    /**
+     * The exported memory's current size in bytes, or `undefined` if the
+     * module exports no memory.
+     */
+    readonly memorySize: number | undefined
+    /** Copy `len` bytes out of the exported memory at `ptr`. */
+    readMemory(ptr: number, len: number): Uint8Array
+    /** Copy `bytes` into the exported memory at `ptr`. */
+    writeMemory(ptr: number, bytes: Uint8Array | ArrayBuffer): void
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",

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, arrayBuffer(), clone(), AbortSignal, ...).
+// (no Blob, FormData, ReadableStream, clone(), AbortSignal, ...).
 // Grouped in one file because the four share BodyInit/HeadersInit and reference
 // each other.
 
@@ -44,6 +44,28 @@ interface RequestInit {
   body?: BodyInit | null
   /** Request headers. */
   headers?: HeadersInit
+  /**
+   * Disk-cache policy, explicit and per call. flux never caches by default
+   * (like Node/Bun/Deno), and server cache headers (`cache-control`,
+   * `expires`, `etag`) are ignored entirely: the caller decides.
+   *
+   * - `"force-cache"`: serve from disk if stored, otherwise fetch and store.
+   *   No freshness, no TTL: the entry lives until evicted by the size cap or
+   *   overwritten by `"reload"`. Use for assets (images, audio, fonts);
+   *   versioned URLs are the normal way to handle updatable assets.
+   * - `"reload"`: fetch fresh and overwrite the stored entry.
+   * - `"default"`, `"no-store"`, `"no-cache"`: accepted, plain network
+   *   request (all equivalent to omitting the option here; there is no
+   *   freshness model to modulate).
+   *
+   * Only GET requests with 2xx responses are cached, keyed by URL; on other
+   * methods the option is ignored. Unknown values throw.
+   *
+   * Cached fetches queue on a small per-host concurrency limit so asset
+   * floods stay polite; disk hits and plain (uncached) fetches are never
+   * throttled.
+   */
+  cache?: "force-cache" | "reload" | "default" | "no-store" | "no-cache"
 }
 
 /**
@@ -62,6 +84,8 @@ interface Request {
   text(): Promise<string>
   /** Read the whole body as raw bytes. */
   bytes(): Promise<Uint8Array>
+  /** Read the whole body as an ArrayBuffer. */
+  arrayBuffer(): Promise<ArrayBuffer>
   /** Read and parse the whole body as JSON. */
   json(): Promise<any>
 }
@@ -93,6 +117,8 @@ interface Response {
   text(): Promise<string>
   /** Read the whole body as raw bytes. */
   bytes(): Promise<Uint8Array>
+  /** Read the whole body as an ArrayBuffer. */
+  arrayBuffer(): Promise<ArrayBuffer>
   /** Read and parse the whole body as JSON. */
   json(): Promise<any>
 }

package/standards/time.d.ts

@@ -7,15 +7,15 @@
  * {@link clearTimeout}.
  */
 declare function setTimeout(callback: () => void, ms: number): number
-/** Cancel a pending timeout. Throws on an unknown id. */
-declare function clearTimeout(id: number): void
+/** Cancel a pending timeout. Unknown or missing ids are ignored. */
+declare function clearTimeout(id?: number): void
 /**
  * Run `callback` every `ms` milliseconds. Returns a timer id for
  * {@link clearInterval}.
  */
 declare function setInterval(callback: () => void, ms: number): number
-/** Cancel a running interval. Throws on an unknown id. */
-declare function clearInterval(id: number): void
+/** Cancel a running interval. Unknown or missing ids are ignored. */
+declare function clearInterval(id?: number): void
 /**
  * Queue `callback` to run as a microtask: after the current job finishes, before
  * any timer fires.