@tasker-systems/tasker 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @tasker-systems/tasker
 
-TypeScript worker for the Tasker workflow orchestration system. Supports Bun (native FFI), Node.js (via koffi), and Deno runtimes.
+TypeScript worker for the Tasker workflow orchestration system. Supports Bun, Node.js (both via koffi/Node-API), and Deno runtimes.
 
 ## Status
 
@@ -9,10 +9,10 @@ Production ready. TypeScript worker bindings provide full step handler execution
 ## Installation
 
 ```bash
-# Bun (recommended - native FFI support)
-bun add @tasker-systems/tasker
+# Bun (recommended)
+bun add @tasker-systems/tasker koffi
 
-# Node.js (requires koffi for FFI)
+# Node.js
 npm install @tasker-systems/tasker koffi
 ```
 
@@ -97,7 +97,7 @@ workers/typescript/
 
 ## Technology Stack
 
-- **FFI Layer**: Bun native FFI / koffi (Node.js)
+- **FFI Layer**: koffi (Node-API, works with both Bun and Node.js)
 - **Build Tool**: tsup
 - **Runtime**: Bun, Node.js 18+, or Deno
 - **Testing**: Bun test runner
@@ -109,8 +109,8 @@ workers/typescript/
 
 | Runtime | FFI Mechanism | Status |
 |---------|---------------|--------|
-| Bun | Native `bun:ffi` | Recommended |
-| Node.js | koffi | Supported |
+| Bun | koffi (Node-API) | Recommended |
+| Node.js | koffi (Node-API) | Supported |
 | Deno | `Deno.dlopen` | Experimental |
 
 ## License

package/dist/ffi/index.d.ts

@@ -60,10 +60,12 @@ declare function getLibraryPath(basePath?: string): string;
  * FfiLayer - Owns FFI runtime loading and lifecycle.
  *
  * This class encapsulates the FFI runtime management:
- * - Runtime detection (Bun, Node.js, Deno)
+ * - Runtime detection (Node.js, Bun, Deno)
  * - Library path discovery
  * - Runtime loading and unloading
  *
+ * Both Node.js and Bun use koffi (Node-API) for stable FFI.
+ *
  * Design principles:
  * - Explicit construction: No singleton pattern
  * - Clear ownership: Owns the runtime instance
@@ -146,9 +148,9 @@ declare class FfiLayer {
      * Static method for finding the library path without creating an instance.
      * Useful for test utilities and pre-flight checks.
      *
-     * REQUIRES: TASKER_FFI_LIBRARY_PATH environment variable to be set.
-     * This explicit requirement prevents confusion from automatic debug/release
-     * library discovery and ensures intentional configuration at build/runtime.
+     * Resolution order:
+     * 1. TASKER_FFI_LIBRARY_PATH environment variable (explicit override)
+     * 2. Bundled native library in the package's native/ directory
      *
      * @param _callerDir Deprecated parameter, kept for API compatibility
      * @returns Path to the library if found and exists, null otherwise
@@ -163,40 +165,37 @@ declare class FfiLayer {
     /**
      * Create a runtime adapter for the configured runtime type.
      *
-     * NOTE: We use koffi (NodeRuntime) for both Node.js and Bun because:
-     * - bun:ffi is experimental with known bugs (per Bun docs)
-     * - koffi is stable and works with both Node.js and Bun via Node-API
-     * - See: https://bun.sh/docs/runtime/node-api
+     * NOTE: We use koffi (NodeRuntime) for both Node.js and Bun.
+     * koffi is stable and works with both runtimes via Node-API.
+     * See: https://bun.sh/docs/runtime/node-api
      */
     private createRuntime;
 }
 
 /**
- * Node.js FFI runtime adapter using koffi.
- *
- * This adapter uses the koffi package to interface with the Rust native library.
- * Koffi is a modern, actively maintained FFI library with prebuilt binaries.
+ * Deno FFI runtime adapter using Deno.dlopen.
  *
- * Install: npm install koffi
+ * This adapter uses Deno's built-in FFI to interface with the Rust native library.
+ * It requires --unstable-ffi and --allow-ffi flags.
  */
 
 /**
- * Node.js FFI runtime implementation using koffi
+ * Deno FFI runtime implementation using Deno.dlopen
  */
-declare class NodeRuntime extends BaseTaskerRuntime {
-    readonly name: string;
+declare class DenoRuntime extends BaseTaskerRuntime {
+    readonly name = "deno";
     private lib;
-    private koffi;
+    private encoder;
     get isLoaded(): boolean;
     load(libraryPath: string): Promise<void>;
     unload(): void;
     private ensureLoaded;
     /**
-     * Read a C string from a pointer and free the Rust-allocated memory.
-     *
-     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
+     * Creates a null-terminated C string buffer.
+     * With 'buffer' FFI type, we return Uint8Array directly.
      */
-    private readAndFreeRustString;
+    private toCString;
+    private fromCString;
     getVersion(): string;
     getRustVersion(): string;
     healthCheck(): boolean;
@@ -229,51 +228,31 @@ declare class NodeRuntime extends BaseTaskerRuntime {
 }
 
 /**
- * Bun FFI runtime adapter using koffi (via Node-API).
- *
- * Bun supports Node-API modules natively, so we use koffi (the same FFI
- * library as NodeRuntime) rather than bun:ffi. This gives us:
- * - Stable, well-tested string/pointer handling
- * - Identical behavior across Node.js and Bun
- * - No manual Buffer→pointer conversion bugs
- *
- * See: https://bun.sh/docs/runtime/node-api
- */
-
-/**
- * Bun FFI runtime implementation using koffi (Node-API).
+ * Node.js FFI runtime adapter using koffi.
  *
- * Extends NodeRuntime since both use koffi for FFI. The only difference
- * is the runtime name identifier used for logging and diagnostics.
- */
-declare class BunRuntime extends NodeRuntime {
-    readonly name = "bun";
-}
-
-/**
- * Deno FFI runtime adapter using Deno.dlopen.
+ * This adapter uses the koffi package to interface with the Rust native library.
+ * Koffi is a modern, actively maintained FFI library with prebuilt binaries.
  *
- * This adapter uses Deno's built-in FFI to interface with the Rust native library.
- * It requires --unstable-ffi and --allow-ffi flags.
+ * Install: npm install koffi
  */
 
 /**
- * Deno FFI runtime implementation using Deno.dlopen
+ * Node.js FFI runtime implementation using koffi
  */
-declare class DenoRuntime extends BaseTaskerRuntime {
-    readonly name = "deno";
+declare class NodeRuntime extends BaseTaskerRuntime {
+    readonly name: string;
     private lib;
-    private encoder;
+    private koffi;
     get isLoaded(): boolean;
     load(libraryPath: string): Promise<void>;
     unload(): void;
     private ensureLoaded;
     /**
-     * Creates a null-terminated C string buffer.
-     * With 'buffer' FFI type, we return Uint8Array directly.
+     * Read a C string from a pointer and free the Rust-allocated memory.
+     *
+     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
      */
-    private toCString;
-    private fromCString;
+    private readAndFreeRustString;
     getVersion(): string;
     getRustVersion(): string;
     healthCheck(): boolean;
@@ -305,4 +284,4 @@ declare class DenoRuntime extends BaseTaskerRuntime {
     clientHealthCheck(): ClientResult;
 }
 
-export { BaseTaskerRuntime, BootstrapConfig, BootstrapResult, BunRuntime, DenoRuntime, FfiDispatchMetrics, FfiDomainEvent, FfiLayer, type FfiLayerConfig, FfiStepEvent, LogFields, NodeRuntime, type RuntimeInfo, type RuntimeType, StepExecutionResult, StopResult, TaskerRuntime, WorkerStatus, detectRuntime, getLibraryPath, getRuntimeInfo, isBun, isDeno, isNode };
+export { BaseTaskerRuntime, BootstrapConfig, BootstrapResult, DenoRuntime, FfiDispatchMetrics, FfiDomainEvent, FfiLayer, type FfiLayerConfig, FfiStepEvent, LogFields, NodeRuntime, type RuntimeInfo, type RuntimeType, StepExecutionResult, StopResult, TaskerRuntime, WorkerStatus, detectRuntime, getLibraryPath, getRuntimeInfo, isBun, isDeno, isNode };