@stacksjs/zig-dtsx 0.9.10

package/src/index.ts

@@ -0,0 +1,222 @@
+/**
+ * TypeScript wrapper for the Zig DTS emitter using Bun FFI.
+ */
+import { dlopen, FFIType, type Pointer, ptr, suffix, toArrayBuffer } from 'bun:ffi'
+import { join } from 'node:path'
+
+const LIB_NAME = `libzig-dtsx.${suffix}`
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+const outLenBuffer = new BigUint64Array(1)
+const outLenBufferIsolated = new BigUint64Array(1)
+
+// Pre-allocated input buffer for encodeInto(); grows only when needed.
+// Avoids per-call Uint8Array allocation from encoder.encode().
+let inputBuf = new Uint8Array(4 * 1024 * 1024) // 4 MB initial
+
+// Try to find the shared library
+const libPaths = [
+  join(import.meta.dir, '..', 'zig-out', 'lib', LIB_NAME),
+  join(import.meta.dir, '..', `zig-out/lib/${LIB_NAME}`),
+]
+
+let lib: ReturnType<typeof dlopen> | null = null
+for (const libPath of libPaths) {
+  try {
+    lib = dlopen(libPath, {
+      process_source: {
+        args: [FFIType.ptr, FFIType.u64, FFIType.bool],
+        returns: FFIType.ptr,
+      },
+      process_source_with_len: {
+        args: [FFIType.ptr, FFIType.u64, FFIType.bool, FFIType.ptr],
+        returns: FFIType.ptr,
+      },
+      process_source_with_options: {
+        args: [FFIType.ptr, FFIType.u64, FFIType.bool, FFIType.bool],
+        returns: FFIType.ptr,
+      },
+      process_source_with_options_len: {
+        args: [FFIType.ptr, FFIType.u64, FFIType.bool, FFIType.bool, FFIType.ptr],
+        returns: FFIType.ptr,
+      },
+      result_length: {
+        args: [FFIType.ptr],
+        returns: FFIType.u64,
+      },
+      free_result: {
+        args: [FFIType.ptr, FFIType.u64],
+        returns: FFIType.void,
+      },
+      process_batch: {
+        args: [FFIType.ptr, FFIType.ptr, FFIType.u32, FFIType.bool, FFIType.ptr, FFIType.ptr, FFIType.u32],
+        returns: FFIType.void,
+      },
+      free_batch_results: {
+        args: [FFIType.ptr, FFIType.ptr, FFIType.u32],
+        returns: FFIType.void,
+      },
+    })
+    break
+  }
+  catch {
+    continue
+  }
+}
+
+const symbols = lib?.symbols as any
+const {
+  process_source,
+  process_source_with_len,
+  process_source_with_options,
+  process_source_with_options_len,
+  result_length,
+  free_result,
+  process_batch: _process_batch,
+  free_batch_results: _free_batch_results,
+} = symbols ?? {}
+
+function readResult(resultPtr: ReturnType<typeof process_source>, knownLen?: number): string {
+  if (!resultPtr) {
+    return ''
+  }
+
+  const len = knownLen ?? Number(result_length(resultPtr))
+  if (len === 0) {
+    free_result(resultPtr, 0)
+    return ''
+  }
+
+  const buf = toArrayBuffer(resultPtr, 0, len)
+  const result = decoder.decode(buf)
+
+  free_result(resultPtr, len)
+
+  return result
+}
+
+/**
+ * Process TypeScript source code and generate .d.ts declarations.
+ *
+ * @param sourceCode - The TypeScript source code to process
+ * @param keepComments - Whether to preserve comments in output (default: true)
+ * @param isolatedDeclarations - Skip initializer parsing when explicit type annotations exist (default: false)
+ * @returns The generated .d.ts declaration content
+ */
+export const ZIG_AVAILABLE: boolean = !!lib
+
+export function processSource(sourceCode: string, keepComments: boolean = true, isolatedDeclarations: boolean = false): string {
+  if (!lib) {
+    throw new Error(
+      `zig-dtsx shared library not found. Run 'zig build -Doptimize=ReleaseFast' first.`,
+    )
+  }
+  if (!sourceCode || sourceCode.length === 0) {
+    return ''
+  }
+
+  // Encode into pre-allocated buffer (grow if needed). Avoids a new Uint8Array per call.
+  const maxBytes = sourceCode.length * 3 // UTF-8 worst case
+  if (maxBytes > inputBuf.length) {
+    inputBuf = new Uint8Array(maxBytes)
+  }
+  const { written } = encoder.encodeInto(sourceCode, inputBuf)
+
+  if (isolatedDeclarations) {
+    if (process_source_with_options_len) {
+      const resultPtr = process_source_with_options_len(ptr(inputBuf), written, keepComments, true, ptr(outLenBufferIsolated))
+      return readResult(resultPtr, Number(outLenBufferIsolated[0]))
+    }
+
+    const resultPtr = process_source_with_options(ptr(inputBuf), written, keepComments, true)
+    return readResult(resultPtr)
+  }
+
+  if (process_source_with_len) {
+    const resultPtr = process_source_with_len(ptr(inputBuf), written, keepComments, ptr(outLenBuffer))
+    return readResult(resultPtr, Number(outLenBuffer[0]))
+  }
+
+  const resultPtr = process_source(ptr(inputBuf), written, keepComments)
+  return readResult(resultPtr)
+}
+
+/**
+ * Process multiple TypeScript source files in parallel.
+ * Uses Zig threads for true parallelism — faster than sequential processSource calls.
+ *
+ * @param sources - Array of TypeScript source code strings
+ * @param keepComments - Whether to preserve comments in output (default: true)
+ * @param threadCount - Number of worker threads (0 = auto-detect CPU count)
+ * @returns Array of generated .d.ts declaration strings
+ */
+export function processBatch(sources: string[], keepComments: boolean = true, threadCount: number = 0): string[] {
+  if (!lib) {
+    throw new Error(
+      `zig-dtsx shared library not found. Run 'zig build -Doptimize=ReleaseFast' first.`,
+    )
+  }
+  const count = sources.length
+  if (count === 0) return []
+
+  // Encode all sources into separate buffers and collect pointers
+  const encodedBuffers: Uint8Array[] = new Array(count)
+  const encodedLens: number[] = new Array(count)
+  for (let i = 0; i < count; i++) {
+    const src = sources[i]
+    if (!src || src.length === 0) {
+      encodedBuffers[i] = new Uint8Array(1)
+      encodedLens[i] = 0
+    }
+    else {
+      const buf = new Uint8Array(src.length * 3)
+      const { written } = encoder.encodeInto(src, buf)
+      encodedBuffers[i] = buf
+      encodedLens[i] = written
+    }
+  }
+
+  // Build pointer array (array of pointers to input buffers)
+  const inputPtrsArray = new BigUint64Array(count)
+  const inputLensArray = new BigUint64Array(count)
+  for (let i = 0; i < count; i++) {
+    inputPtrsArray[i] = BigInt(ptr(encodedBuffers[i]))
+    inputLensArray[i] = BigInt(encodedLens[i])
+  }
+
+  // Allocate output arrays
+  const outPtrsArray = new BigUint64Array(count)
+  const outLensArray = new BigUint64Array(count)
+
+  // Call batch API
+  _process_batch(
+    ptr(inputPtrsArray),
+    ptr(inputLensArray),
+    count,
+    keepComments,
+    ptr(outPtrsArray),
+    ptr(outLensArray),
+    threadCount,
+  )
+
+  // Read results
+  const results: string[] = new Array(count)
+  for (let i = 0; i < count; i++) {
+    const resultPtr = Number(outPtrsArray[i])
+    const resultLen = Number(outLensArray[i])
+    if (resultLen === 0) {
+      results[i] = ''
+    }
+    else {
+      const buf = toArrayBuffer(resultPtr as Pointer, 0, resultLen)
+      results[i] = decoder.decode(buf)
+    }
+  }
+
+  // Free all results at once
+  _free_batch_results(ptr(outPtrsArray), ptr(outLensArray), count)
+
+  return results
+}
+
+export default { processSource, processBatch } as { processSource: typeof processSource, processBatch: typeof processBatch }

package/src/lib.zig

@@ -0,0 +1,254 @@
+/// C ABI exports for Bun FFI integration.
+/// Provides process_source(+len variants), result_length, free_result.
+const std = @import("std");
+const Scanner = @import("scanner.zig").Scanner;
+const emitter = @import("emitter.zig");
+
+const ProcessResult = struct {
+    ptr: [*]const u8,
+    len: usize,
+};
+
+fn emptyResult() ProcessResult {
+    const empty = std.heap.c_allocator.alloc(u8, 1) catch @panic("OOM");
+    empty[0] = 0;
+    return .{ .ptr = empty.ptr, .len = 0 };
+}
+
+/// Process TypeScript source → .d.ts output.
+/// Returns a pointer to the result string (null-terminated).
+/// Caller must call free_result() when done.
+export fn process_source(
+    input: [*]const u8,
+    len: usize,
+    keep_comments: bool,
+) [*]const u8 {
+    const result = processSourceInternal(input, len, keep_comments, false) catch {
+        // Return empty string on error — must be c_allocator-allocated so free_result() is safe
+        return emptyResult().ptr;
+    };
+    return result.ptr;
+}
+
+/// Process source and return output length through out_len.
+/// This avoids an extra pass in result_length() on the JS side.
+export fn process_source_with_len(
+    input: [*]const u8,
+    len: usize,
+    keep_comments: bool,
+    out_len: *u64,
+) [*]const u8 {
+    const result = processSourceInternal(input, len, keep_comments, false) catch {
+        out_len.* = 0;
+        return emptyResult().ptr;
+    };
+    out_len.* = @intCast(result.len);
+    return result.ptr;
+}
+
+/// Thread-local arena: reuse across calls to avoid repeated mmap/munmap syscalls.
+/// reset(.retain_capacity) keeps the backing memory warm in CPU cache.
+threadlocal var tls_arena: ?std.heap.ArenaAllocator = null;
+
+fn getOrInitArena() *std.heap.ArenaAllocator {
+    if (tls_arena == null) {
+        tls_arena = std.heap.ArenaAllocator.init(std.heap.c_allocator);
+    }
+    return &(tls_arena.?);
+}
+
+fn processSourceInternal(
+    input: [*]const u8,
+    len: usize,
+    keep_comments: bool,
+    isolated_declarations: bool,
+) !ProcessResult {
+    // Handle empty input
+    if (len == 0) {
+        const result = try std.heap.c_allocator.alloc(u8, 1);
+        result[0] = 0;
+        return .{ .ptr = result.ptr, .len = 0 };
+    }
+
+    const source = input[0..len];
+
+    // Reuse thread-local arena — reset frees all allocations but keeps backing pages
+    const arena = getOrInitArena();
+    _ = arena.reset(.retain_capacity);
+    const arena_alloc = arena.allocator();
+
+    // Scan
+    var scanner = Scanner.init(arena_alloc, source, keep_comments, isolated_declarations);
+    _ = try scanner.scan();
+
+    // Emit — result buffer uses c_allocator directly so it survives arena.reset().
+    // processDeclarations appends '\0' before toOwnedSlice, so the result is
+    // already null-terminated with no extra copy needed.
+    const default_import_order = [_][]const u8{"bun"};
+    const dts_output = try emitter.processDeclarations(
+        arena_alloc,
+        std.heap.c_allocator,
+        scanner.declarations.items,
+        source,
+        keep_comments,
+        &default_import_order,
+    );
+
+    // dts_output[0..len] is content, dts_output.ptr[len] == 0 (null terminator)
+    return .{ .ptr = dts_output.ptr, .len = dts_output.len };
+}
+
+/// Get the length of a result string (without null terminator)
+export fn result_length(ptr: [*]const u8) usize {
+    var i: usize = 0;
+    while (ptr[i] != 0) i += 1;
+    return i;
+}
+
+/// Free a result string previously returned by process_source
+export fn free_result(ptr: [*]const u8, len: usize) void {
+    const slice = @as([*]u8, @constCast(ptr))[0 .. len + 1]; // +1 for null terminator
+    std.heap.c_allocator.free(slice);
+}
+
+/// Process source with isolatedDeclarations option
+export fn process_source_with_options(
+    input: [*]const u8,
+    len: usize,
+    keep_comments: bool,
+    isolated_declarations: bool,
+) [*]const u8 {
+    const result = processSourceInternal(input, len, keep_comments, isolated_declarations) catch {
+        return emptyResult().ptr;
+    };
+    return result.ptr;
+}
+
+/// Same as process_source_with_options but returns length through out_len.
+export fn process_source_with_options_len(
+    input: [*]const u8,
+    len: usize,
+    keep_comments: bool,
+    isolated_declarations: bool,
+    out_len: *u64,
+) [*]const u8 {
+    const result = processSourceInternal(input, len, keep_comments, isolated_declarations) catch {
+        out_len.* = 0;
+        return emptyResult().ptr;
+    };
+    out_len.* = @intCast(result.len);
+    return result.ptr;
+}
+
+// ---------------------------------------------------------------------------
+// Batch API — process multiple files in parallel from a single FFI call
+// ---------------------------------------------------------------------------
+
+const BatchTask = struct {
+    input: [*]const u8,
+    input_len: usize,
+    keep_comments: bool,
+    out_ptr: *usize, // where to write result pointer
+    out_len: *u64, // where to write result length
+};
+
+fn batchWorker(tasks: []const BatchTask) void {
+    for (tasks) |task| {
+        const result = processSourceInternal(task.input, task.input_len, task.keep_comments, false) catch {
+            const empty = emptyResult();
+            task.out_ptr.* = @intFromPtr(empty.ptr);
+            task.out_len.* = 0;
+            continue;
+        };
+        task.out_ptr.* = @intFromPtr(result.ptr);
+        task.out_len.* = @intCast(result.len);
+    }
+}
+
+/// Process multiple files in parallel.
+/// inputs: array of pointers to source buffers
+/// input_lens: array of source lengths
+/// count: number of files
+/// keep_comments: whether to preserve comments
+/// out_ptrs: pre-allocated array where result pointers are written (as usize)
+/// out_lens: pre-allocated array where result lengths are written
+/// thread_count: number of worker threads (0 = auto-detect)
+export fn process_batch(
+    inputs: [*]const [*]const u8,
+    input_lens: [*]const u64,
+    count: u32,
+    keep_comments: bool,
+    out_ptrs: [*]usize,
+    out_lens: [*]u64,
+    thread_count: u32,
+) void {
+    const n: usize = @intCast(count);
+    if (n == 0) return;
+
+    // Build task list
+    const tasks = std.heap.c_allocator.alloc(BatchTask, n) catch return;
+    defer std.heap.c_allocator.free(tasks);
+
+    for (0..n) |i| {
+        tasks[i] = .{
+            .input = inputs[i],
+            .input_len = @intCast(input_lens[i]),
+            .keep_comments = keep_comments,
+            .out_ptr = &out_ptrs[i],
+            .out_len = &out_lens[i],
+        };
+    }
+
+    // Determine thread count
+    const max_threads: usize = if (thread_count > 0)
+        @intCast(thread_count)
+    else
+        @intCast(std.Thread.getCpuCount() catch 4);
+    const num_threads = @min(max_threads, n);
+
+    if (num_threads <= 1) {
+        // Single-threaded: process all sequentially
+        batchWorker(tasks);
+        return;
+    }
+
+    // Distribute tasks across threads
+    const threads = std.heap.c_allocator.alloc(std.Thread, num_threads) catch {
+        // Fallback to single-threaded
+        batchWorker(tasks);
+        return;
+    };
+    defer std.heap.c_allocator.free(threads);
+
+    const chunk_size = (n + num_threads - 1) / num_threads;
+    var thread_spawned: [64]bool = .{false} ** 64; // max 64 threads
+
+    for (0..num_threads) |t| {
+        const start = t * chunk_size;
+        if (start >= n) break;
+        const end = @min(start + chunk_size, n);
+        threads[t] = std.Thread.spawn(.{}, batchWorker, .{tasks[start..end]}) catch {
+            // If spawn fails, process this chunk on the main thread immediately
+            batchWorker(tasks[start..end]);
+            continue;
+        };
+        thread_spawned[t] = true;
+    }
+
+    // Join all successfully spawned threads
+    for (0..num_threads) |t| {
+        if (thread_spawned[t]) {
+            threads[t].join();
+        }
+    }
+}
+
+/// Free multiple results from a batch call.
+export fn free_batch_results(ptrs: [*]const usize, lens: [*]const u64, count: u32) void {
+    const n: usize = @intCast(count);
+    for (0..n) |i| {
+        const p: [*]u8 = @ptrFromInt(ptrs[i]);
+        const l: usize = @intCast(lens[i]);
+        std.heap.c_allocator.free(p[0 .. l + 1]); // +1 for null terminator
+    }
+}