@spikard/node 0.9.0 → 0.10.1

package/dist/index.mjs

@@ -0,0 +1,1645 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/server.ts
+import { createRequire as createRequire2 } from "module";
+
+// src/upload.ts
+var UploadFile = class {
+  /** Original filename from the client */
+  filename;
+  /** MIME type of the uploaded file */
+  contentType;
+  /** Size of the file in bytes */
+  size;
+  /** Additional headers associated with this file field */
+  headers;
+  /** Internal buffer storing file contents */
+  _content;
+  /** Current read position in the buffer */
+  _position = 0;
+  /**
+   * Create a new UploadFile instance
+   *
+   * @param filename - Original filename from the client
+   * @param content - File contents as Buffer
+   * @param contentType - MIME type (defaults to "application/octet-stream")
+   * @param size - File size in bytes (computed from content if not provided)
+   * @param headers - Additional headers from the multipart field
+   */
+  constructor(filename, content, contentType = null, size = null, headers = null) {
+    this.filename = filename;
+    this.contentType = contentType ?? "application/octet-stream";
+    this.size = size ?? content.length;
+    this.headers = headers ?? {};
+    this._content = content;
+  }
+  /**
+   * Read file contents synchronously
+   *
+   * @param size - Number of bytes to read (-1 for all remaining)
+   * @returns File contents as Buffer
+   */
+  read(size = -1) {
+    if (size === -1) {
+      const result2 = this._content.subarray(this._position);
+      this._position = this._content.length;
+      return result2;
+    }
+    const end = Math.min(this._position + size, this._content.length);
+    const result = this._content.subarray(this._position, end);
+    this._position = end;
+    return result;
+  }
+  /**
+   * Read file contents asynchronously
+   *
+   * Since the file is already in memory from Rust parsing, this is a simple wrapper.
+   *
+   * @param size - Number of bytes to read (-1 for all remaining)
+   * @returns File contents as Buffer
+   */
+  async readAsync(size = -1) {
+    return this.read(size);
+  }
+  /**
+   * Read entire file as UTF-8 text
+   *
+   * @returns File contents as string
+   */
+  text() {
+    return this._content.toString("utf-8");
+  }
+  /**
+   * Read entire file as UTF-8 text asynchronously
+   *
+   * @returns File contents as string
+   */
+  async textAsync() {
+    return this.text();
+  }
+  /**
+   * Seek to a position in the file
+   *
+   * @param offset - Position to seek to
+   * @param whence - How to interpret offset (0=absolute, 1=relative, 2=from end)
+   * @returns New absolute position
+   */
+  seek(offset, whence = 0) {
+    switch (whence) {
+      case 0:
+        this._position = Math.max(0, Math.min(offset, this._content.length));
+        break;
+      case 1:
+        this._position = Math.max(0, Math.min(this._position + offset, this._content.length));
+        break;
+      case 2:
+        this._position = Math.max(0, Math.min(this._content.length + offset, this._content.length));
+        break;
+      default:
+        throw new Error(`Invalid whence value: ${whence}`);
+    }
+    return this._position;
+  }
+  /**
+   * Seek to a position in the file asynchronously
+   *
+   * @param offset - Position to seek to
+   * @param whence - How to interpret offset (0=absolute, 1=relative, 2=from end)
+   * @returns New absolute position
+   */
+  async seekAsync(offset, whence = 0) {
+    return this.seek(offset, whence);
+  }
+  /**
+   * Get current position in the file
+   *
+   * @returns Current byte position
+   */
+  tell() {
+    return this._position;
+  }
+  /**
+   * Get the underlying Buffer
+   *
+   * @returns Complete file contents as Buffer
+   */
+  getBuffer() {
+    return this._content;
+  }
+  /**
+   * Close the file (no-op for in-memory files, provided for API compatibility)
+   */
+  close() {
+  }
+  /**
+   * Close the file asynchronously (no-op, provided for API compatibility)
+   */
+  async closeAsync() {
+  }
+  /**
+   * String representation of the upload file
+   */
+  toString() {
+    return `UploadFile(filename=${JSON.stringify(this.filename)}, contentType=${JSON.stringify(this.contentType)}, size=${this.size})`;
+  }
+  /**
+   * JSON representation for debugging
+   */
+  toJSON() {
+    return {
+      filename: this.filename,
+      contentType: this.contentType,
+      size: this.size,
+      headers: this.headers
+    };
+  }
+};
+
+// src/converters.ts
+function isFileMetadata(value) {
+  return typeof value === "object" && value !== null && "filename" in value && "content" in value;
+}
+function convertFileMetadataToUploadFile(fileData) {
+  const { filename, content, size, content_type, content_encoding } = fileData;
+  let buffer;
+  if (content_encoding === "base64") {
+    buffer = Buffer.from(content, "base64");
+  } else {
+    buffer = Buffer.from(content, "utf-8");
+  }
+  return new UploadFile(filename, buffer, content_type ?? null, size ?? null);
+}
+function processUploadFileFields(value) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (isFileMetadata(item)) {
+        return convertFileMetadataToUploadFile(item);
+      }
+      return processUploadFileFields(item);
+    });
+  }
+  if (isFileMetadata(value)) {
+    return convertFileMetadataToUploadFile(value);
+  }
+  const result = {};
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = processUploadFileFields(val);
+  }
+  return result;
+}
+function convertMultipartTestPayload(payload) {
+  const result = {};
+  if (payload.fields) {
+    Object.assign(result, payload.fields);
+  }
+  if (payload.files && payload.files.length > 0) {
+    const filesByName = {};
+    for (const file of payload.files) {
+      const fileMetadata = {
+        filename: file.filename || file.name,
+        content: file.content,
+        content_type: file.contentType
+      };
+      const uploadFile = convertFileMetadataToUploadFile(fileMetadata);
+      if (!filesByName[file.name]) {
+        filesByName[file.name] = [];
+      }
+      const files = filesByName[file.name];
+      if (files) {
+        files.push(uploadFile);
+      }
+    }
+    for (const [name, files] of Object.entries(filesByName)) {
+      result[name] = files.length === 1 ? files[0] : files;
+    }
+  }
+  return result;
+}
+function convertHandlerBody(body) {
+  if (typeof body === "object" && body !== null && "__spikard_multipart__" in body && typeof body.__spikard_multipart__ === "object") {
+    const multipart = body.__spikard_multipart__;
+    return convertMultipartTestPayload(multipart);
+  }
+  return processUploadFileFields(body);
+}
+
+// src/request.ts
+var RequestImpl = class {
+  method;
+  path;
+  params;
+  pathParams;
+  query;
+  queryParams;
+  headers;
+  cookies;
+  body;
+  dependencies;
+  #jsonCache;
+  #formCache;
+  constructor(data) {
+    this.method = data.method;
+    this.path = data.path;
+    const pathParams = data.params ?? data.pathParams ?? {};
+    const queryParams = data.query ?? extractQueryParams(data.queryParams) ?? {};
+    this.params = pathParams;
+    this.pathParams = pathParams;
+    this.query = queryParams;
+    this.queryParams = queryParams;
+    this.headers = normalizeHeaders(data.headers ?? {});
+    this.cookies = data.cookies ?? {};
+    this.body = convertBodyToBuffer(data.body);
+    this.dependencies = data.dependencies;
+  }
+  json() {
+    if (this.#jsonCache !== void 0) {
+      return this.#jsonCache;
+    }
+    if (!this.body || this.body.length === 0) {
+      throw new Error("No body available to parse as JSON");
+    }
+    const raw = this.body.toString("utf-8");
+    const parsed = JSON.parse(raw);
+    const converted = convertHandlerBody(parsed);
+    this.#jsonCache = converted;
+    return converted;
+  }
+  form() {
+    if (this.#formCache !== void 0) {
+      return this.#formCache;
+    }
+    if (!this.body || this.body.length === 0) {
+      throw new Error("No body available to parse as form data");
+    }
+    const text = this.body.toString("utf-8");
+    const params = new URLSearchParams(text);
+    const form = {};
+    for (const [key, value] of params.entries()) {
+      form[key] = value;
+    }
+    this.#formCache = form;
+    return form;
+  }
+};
+var normalizeHeaders = (headers) => Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+var extractQueryParams = (queryParams) => {
+  if (!queryParams || typeof queryParams !== "object") {
+    return void 0;
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(queryParams)) {
+    result[key] = String(value);
+  }
+  return result;
+};
+var convertBodyToBuffer = (body) => {
+  if (body === null || body === void 0) {
+    return null;
+  }
+  if (Array.isArray(body)) {
+    if (body.length === 0 || body.every((b) => typeof b === "number")) {
+      return Buffer.from(body);
+    }
+    return Buffer.from(JSON.stringify(body), "utf-8");
+  }
+  if (typeof body === "object") {
+    return Buffer.from(JSON.stringify(body), "utf-8");
+  }
+  if (typeof body === "string") {
+    return Buffer.from(body, "utf-8");
+  }
+  return null;
+};
+function createRequest(data) {
+  return new RequestImpl(data);
+}
+
+// src/streaming.ts
+import { createRequire } from "module";
+var STREAM_HANDLE_PROP = "__spikard_stream_handle";
+var nativeBinding = null;
+var loadBinding = () => {
+  try {
+    const require2 = createRequire(import.meta.url);
+    return require2("../index.js");
+  } catch {
+    console.warn("[spikard-node] Native binding not found. Please run: pnpm build:native");
+    return null;
+  }
+};
+nativeBinding = loadBinding();
+var createHandle = (iterator, init) => {
+  if (nativeBinding && typeof nativeBinding.createStreamingHandle === "function") {
+    return { kind: "native", handle: nativeBinding.createStreamingHandle(iterator, init), init };
+  }
+  return { kind: "js", iterator, init };
+};
+var StreamingResponse = class {
+  [STREAM_HANDLE_PROP];
+  constructor(stream, init) {
+    const iterator = toAsyncIterator(stream);
+    this[STREAM_HANDLE_PROP] = createHandle(iterator, init ?? {});
+  }
+};
+function isStreamingResponse(value) {
+  return Boolean(value) && value instanceof StreamingResponse;
+}
+var getStreamingHandle = (response) => response[STREAM_HANDLE_PROP];
+function toAsyncIterator(source) {
+  if (source && typeof source.next === "function") {
+    const iterator = source;
+    if (typeof iterator[Symbol.asyncIterator] === "function") {
+      return iterator;
+    }
+    return {
+      next: (...args) => iterator.next(...args),
+      [Symbol.asyncIterator]() {
+        return this;
+      }
+    };
+  }
+  if (source && typeof source[Symbol.asyncIterator] === "function") {
+    return source[Symbol.asyncIterator]();
+  }
+  throw new TypeError("StreamingResponse requires an async iterator or generator");
+}
+
+// src/handler-wrapper.ts
+var NATIVE_HANDLER_FLAG = /* @__PURE__ */ Symbol("spikard.nativeHandler");
+var formatHandlerResult = (result, objectMode) => {
+  if (objectMode) {
+    if (result !== void 0 && result !== null && typeof result === "object") {
+      if ("status" in result) {
+        return result;
+      }
+      if (isStreamingResponse(result)) {
+        return result;
+      }
+      return { status: 200, body: result };
+    }
+    return result === void 0 ? { status: 200, body: null } : { status: 200, body: result };
+  }
+  if (isStreamingResponse(result)) {
+    return result;
+  }
+  if (result === void 0) {
+    return "null";
+  }
+  if (typeof result === "string") {
+    return result;
+  }
+  return JSON.stringify(result);
+};
+var isNativeHandler = (handler) => Boolean(handler?.[NATIVE_HANDLER_FLAG]);
+function markNative(handler) {
+  handler[NATIVE_HANDLER_FLAG] = true;
+  return handler;
+}
+function markRawBody(handler, prefersRaw) {
+  handler.__spikard_raw_body = prefersRaw;
+  return handler;
+}
+function prepareRequest(requestInput) {
+  let actualInput = requestInput;
+  if (Array.isArray(requestInput) && requestInput.length === 1) {
+    actualInput = requestInput[0];
+  }
+  const objectMode = typeof actualInput === "object" && actualInput !== null;
+  const data = objectMode ? actualInput : JSON.parse(actualInput);
+  const request = createRequest(data);
+  return { request, objectMode };
+}
+function wrapHandler(handler) {
+  const isHandlerAsync = handler.constructor.name === "AsyncFunction";
+  if (isHandlerAsync) {
+    const nativeHandler2 = async (requestInput) => {
+      const { request, objectMode } = prepareRequest(requestInput);
+      const result = await handler(request);
+      return formatHandlerResult(result, objectMode);
+    };
+    return markNative(markRawBody(nativeHandler2, true));
+  }
+  const nativeHandler = (requestInput) => {
+    const { request, objectMode } = prepareRequest(requestInput);
+    const result = handler(request);
+    return formatHandlerResult(result, objectMode);
+  };
+  return markNative(markRawBody(nativeHandler, true));
+}
+function wrapBodyHandler(handler) {
+  const isHandlerAsync = handler.constructor.name === "AsyncFunction";
+  if (isHandlerAsync) {
+    const nativeHandler2 = async (requestInput) => {
+      const { request, objectMode } = prepareRequest(requestInput);
+      const body = request.json();
+      const result = await handler(body, request);
+      return formatHandlerResult(result, objectMode);
+    };
+    return markNative(markRawBody(nativeHandler2, true));
+  }
+  const nativeHandler = (requestInput) => {
+    const { request, objectMode } = prepareRequest(requestInput);
+    const body = request.json();
+    const result = handler(body, request);
+    return formatHandlerResult(result, objectMode);
+  };
+  return markNative(markRawBody(nativeHandler, true));
+}
+
+// src/server.ts
+var nativeBinding2;
+function loadBinding2() {
+  try {
+    const require2 = createRequire2(import.meta.url);
+    return require2("../index.js");
+  } catch {
+    console.warn("[spikard-node] Native binding not found. Please run: pnpm build:native");
+    return {
+      runServer: () => {
+        throw new Error("Native binding not built. Run: pnpm build:native");
+      }
+    };
+  }
+}
+nativeBinding2 = loadBinding2();
+function runServer(app, config = {}) {
+  const handlers = {};
+  const routes = (app.routes || []).map((route2) => {
+    const handler = app.handlers?.[route2.handler_name];
+    if (!handler) return route2;
+    const nativeHandler = isNativeHandler(handler) ? handler : wrapHandler(handler);
+    handlers[route2.handler_name] = nativeHandler;
+    const isAsync = nativeHandler.constructor.name === "AsyncFunction";
+    return { ...route2, is_async: isAsync };
+  });
+  nativeBinding2.runServer({ ...app, handlers, routes }, config);
+}
+
+// src/app.ts
+var ASYNC_GENERATOR_REGISTRY = /* @__PURE__ */ new Map();
+var ASYNC_GENERATOR_COUNTER = 0;
+var isAsyncGenerator = (value) => {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+};
+var normalizeDependencyKey = (key) => key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/-/g, "_").toLowerCase();
+var inferDependsOn = (factory) => {
+  const source = factory.toString();
+  const parenMatch = source.match(/^[^(]*\(([^)]*)\)/);
+  if (parenMatch) {
+    const rawParams = (parenMatch[1] ?? "").split(",").map((param) => param.trim()).filter((param) => param.length > 0);
+    return rawParams.filter((param) => !param.startsWith("{") && !param.startsWith("[")).map((param) => param.replace(/^\.{3}/, "")).map((param) => param.split("=")[0]?.trim() ?? "").filter((param) => param.length > 0).map((param) => normalizeDependencyKey(param));
+  }
+  const arrowMatch = source.match(/^\s*([A-Za-z0-9_$]+)\s*=>/);
+  if (arrowMatch) {
+    return [normalizeDependencyKey(arrowMatch[1] ?? "")].filter((param) => param.length > 0);
+  }
+  return [];
+};
+var parseDependencies = (payload) => {
+  if (typeof payload === "string") {
+    try {
+      const parsed = JSON.parse(payload);
+      return parsed ?? {};
+    } catch {
+      return {};
+    }
+  }
+  if (typeof payload === "object" && payload !== null) {
+    return payload;
+  }
+  return {};
+};
+var wrapDependencyFactory = (factory) => {
+  return async (payload) => {
+    const deps = parseDependencies(payload);
+    const cleanupId = deps.__cleanup_id__;
+    if (typeof cleanupId === "string") {
+      const generator = ASYNC_GENERATOR_REGISTRY.get(cleanupId);
+      if (generator) {
+        ASYNC_GENERATOR_REGISTRY.delete(cleanupId);
+        if (typeof generator.return === "function") {
+          await generator.return(void 0);
+        }
+      }
+      return JSON.stringify({ ok: true });
+    }
+    const result = await factory(deps);
+    if (isAsyncGenerator(result)) {
+      const { value } = await result.next();
+      const id = `gen_${ASYNC_GENERATOR_COUNTER++}`;
+      ASYNC_GENERATOR_REGISTRY.set(id, result);
+      return JSON.stringify({ __async_generator__: true, value, cleanup_id: id });
+    }
+    return result === void 0 ? "null" : JSON.stringify(result);
+  };
+};
+var Spikard = class {
+  routes = [];
+  handlers = {};
+  websocketRoutes = [];
+  websocketHandlers = {};
+  lifecycleHooks = {
+    onRequest: [],
+    preValidation: [],
+    preHandler: [],
+    onResponse: [],
+    onError: []
+  };
+  dependencies = {};
+  /**
+   * Add a route to the application
+   *
+   * @param metadata - Route configuration metadata
+   * @param handler - Handler function (sync or async)
+   */
+  addRoute(metadata, handler) {
+    this.routes.push(metadata);
+    this.handlers[metadata.handler_name] = handler;
+  }
+  /**
+   * Register a WebSocket route (message-based)
+   */
+  websocket(path2, handler, options = {}) {
+    const handlerName = options.handlerName ?? `ws_${this.websocketRoutes.length}_${path2}`.replace(/[^a-zA-Z0-9_]/g, "_");
+    const handlerWrapper = { handleMessage: handler };
+    if (options.messageSchema) {
+      handlerWrapper._messageSchema = options.messageSchema;
+    }
+    if (options.responseSchema) {
+      handlerWrapper._responseSchema = options.responseSchema;
+    }
+    const route2 = {
+      method: "GET",
+      path: path2,
+      handler_name: handlerName,
+      request_schema: options.messageSchema,
+      response_schema: options.responseSchema,
+      parameter_schema: void 0,
+      file_params: void 0,
+      is_async: true
+    };
+    this.websocketRoutes.push(route2);
+    this.websocketHandlers[handlerName] = handlerWrapper;
+  }
+  /**
+   * Run the server
+   *
+   * @param options - Server configuration
+   */
+  run(options = {}) {
+    runServer(this, options);
+  }
+  /**
+   * Register an onRequest lifecycle hook
+   *
+   * Runs before routing. Can inspect/modify the request or short-circuit with a response.
+   *
+   * @param hook - Async function that receives a request and returns either:
+   *               - The (possibly modified) request to continue processing
+   *               - A Response object to short-circuit the request pipeline
+   * @returns The hook function (for decorator usage)
+   *
+   * @example
+   * ```typescript
+   * app.onRequest(async (request) => {
+   *   console.log(`Request: ${request.method} ${request.path}`);
+   *   return request;
+   * });
+   * ```
+   */
+  onRequest(hook) {
+    this.lifecycleHooks.onRequest.push(hook);
+    return hook;
+  }
+  /**
+   * Register a preValidation lifecycle hook
+   *
+   * Runs after routing but before validation. Useful for rate limiting.
+   *
+   * @param hook - Async function that receives a request and returns either:
+   *               - The (possibly modified) request to continue processing
+   *               - A Response object to short-circuit the request pipeline
+   * @returns The hook function (for decorator usage)
+   *
+   * @example
+   * ```typescript
+   * app.preValidation(async (request) => {
+   *   if (tooManyRequests()) {
+   *     return { error: "Rate limit exceeded", status: 429 };
+   *   }
+   *   return request;
+   * });
+   * ```
+   */
+  preValidation(hook) {
+    this.lifecycleHooks.preValidation.push(hook);
+    return hook;
+  }
+  /**
+   * Register a preHandler lifecycle hook
+   *
+   * Runs after validation but before the handler. Ideal for authentication/authorization.
+   *
+   * @param hook - Async function that receives a request and returns either:
+   *               - The (possibly modified) request to continue processing
+   *               - A Response object to short-circuit the request pipeline
+   * @returns The hook function (for decorator usage)
+   *
+   * @example
+   * ```typescript
+   * app.preHandler(async (request) => {
+   *   if (!validToken(request.headers.authorization)) {
+   *     return { error: "Unauthorized", status: 401 };
+   *   }
+   *   return request;
+   * });
+   * ```
+   */
+  preHandler(hook) {
+    this.lifecycleHooks.preHandler.push(hook);
+    return hook;
+  }
+  /**
+   * Register an onResponse lifecycle hook
+   *
+   * Runs after the handler executes. Can modify the response.
+   *
+   * @param hook - Async function that receives a response and returns the (possibly modified) response
+   * @returns The hook function (for decorator usage)
+   *
+   * @example
+   * ```typescript
+   * app.onResponse(async (response) => {
+   *   response.headers["X-Frame-Options"] = "DENY";
+   *   return response;
+   * });
+   * ```
+   */
+  onResponse(hook) {
+    this.lifecycleHooks.onResponse.push(hook);
+    return hook;
+  }
+  /**
+   * Register an onError lifecycle hook
+   *
+   * Runs when an error occurs. Can customize error responses.
+   *
+   * @param hook - Async function that receives an error response and returns a (possibly modified) response
+   * @returns The hook function (for decorator usage)
+   *
+   * @example
+   * ```typescript
+   * app.onError(async (response) => {
+   *   response.headers["Content-Type"] = "application/json";
+   *   return response;
+   * });
+   * ```
+   */
+  onError(hook) {
+    this.lifecycleHooks.onError.push(hook);
+    return hook;
+  }
+  /**
+   * Register a dependency value or factory
+   *
+   * Provides a value or factory function to be injected into handlers.
+   * Dependencies are matched by parameter name or can be accessed via the
+   * request context.
+   *
+   * @param key - Unique identifier for the dependency
+   * @param valueOrFactory - Static value or factory function
+   * @param options - Configuration options for the dependency
+   * @returns The Spikard instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * // Simple value dependency
+   * app.provide('app_name', 'MyApp');
+   * app.provide('max_connections', 100);
+   *
+   * // Factory dependency
+   * app.provide('db_pool', async ({ database_url }) => {
+   *   return await createPool(database_url);
+   * }, { dependsOn: ['database_url'], singleton: true });
+   *
+   * // Use in handler
+   * app.get('/config', async (request, { app_name, db_pool }) => {
+   *   return { app: app_name, pool: db_pool };
+   * });
+   * ```
+   */
+  provide(key, valueOrFactory, options) {
+    const normalizedKey = normalizeDependencyKey(key);
+    const isFactory = typeof valueOrFactory === "function";
+    const factory = isFactory ? wrapDependencyFactory(valueOrFactory) : void 0;
+    const explicitDependsOn = options?.dependsOn;
+    const inferredDependsOn = isFactory && explicitDependsOn === void 0 ? inferDependsOn(valueOrFactory) : [];
+    const dependsOn = (explicitDependsOn ?? inferredDependsOn).map((depKey) => normalizeDependencyKey(depKey));
+    this.dependencies[normalizedKey] = {
+      isFactory,
+      value: isFactory ? void 0 : valueOrFactory,
+      factory,
+      dependsOn,
+      singleton: options?.singleton ?? false,
+      cacheable: options?.cacheable ?? !isFactory
+    };
+    return this;
+  }
+  /**
+   * Get all registered lifecycle hooks
+   *
+   * @returns Dictionary of hook lists by type
+   */
+  getLifecycleHooks() {
+    return {
+      onRequest: [...this.lifecycleHooks.onRequest ?? []],
+      preValidation: [...this.lifecycleHooks.preValidation ?? []],
+      preHandler: [...this.lifecycleHooks.preHandler ?? []],
+      onResponse: [...this.lifecycleHooks.onResponse ?? []],
+      onError: [...this.lifecycleHooks.onError ?? []]
+    };
+  }
+};
+
+// src/background.ts
+var background_exports = {};
+__export(background_exports, {
+  run: () => run
+});
+import { backgroundRun } from "../index.js";
+function run(work) {
+  const task = async () => {
+    await work();
+    return void 0;
+  };
+  backgroundRun(task);
+}
+
+// src/grpc.ts
+var GrpcStatusCode = /* @__PURE__ */ ((GrpcStatusCode2) => {
+  GrpcStatusCode2[GrpcStatusCode2["OK"] = 0] = "OK";
+  GrpcStatusCode2[GrpcStatusCode2["CANCELLED"] = 1] = "CANCELLED";
+  GrpcStatusCode2[GrpcStatusCode2["UNKNOWN"] = 2] = "UNKNOWN";
+  GrpcStatusCode2[GrpcStatusCode2["INVALID_ARGUMENT"] = 3] = "INVALID_ARGUMENT";
+  GrpcStatusCode2[GrpcStatusCode2["DEADLINE_EXCEEDED"] = 4] = "DEADLINE_EXCEEDED";
+  GrpcStatusCode2[GrpcStatusCode2["NOT_FOUND"] = 5] = "NOT_FOUND";
+  GrpcStatusCode2[GrpcStatusCode2["ALREADY_EXISTS"] = 6] = "ALREADY_EXISTS";
+  GrpcStatusCode2[GrpcStatusCode2["PERMISSION_DENIED"] = 7] = "PERMISSION_DENIED";
+  GrpcStatusCode2[GrpcStatusCode2["RESOURCE_EXHAUSTED"] = 8] = "RESOURCE_EXHAUSTED";
+  GrpcStatusCode2[GrpcStatusCode2["FAILED_PRECONDITION"] = 9] = "FAILED_PRECONDITION";
+  GrpcStatusCode2[GrpcStatusCode2["ABORTED"] = 10] = "ABORTED";
+  GrpcStatusCode2[GrpcStatusCode2["OUT_OF_RANGE"] = 11] = "OUT_OF_RANGE";
+  GrpcStatusCode2[GrpcStatusCode2["UNIMPLEMENTED"] = 12] = "UNIMPLEMENTED";
+  GrpcStatusCode2[GrpcStatusCode2["INTERNAL"] = 13] = "INTERNAL";
+  GrpcStatusCode2[GrpcStatusCode2["UNAVAILABLE"] = 14] = "UNAVAILABLE";
+  GrpcStatusCode2[GrpcStatusCode2["DATA_LOSS"] = 15] = "DATA_LOSS";
+  GrpcStatusCode2[GrpcStatusCode2["UNAUTHENTICATED"] = 16] = "UNAUTHENTICATED";
+  return GrpcStatusCode2;
+})(GrpcStatusCode || {});
+var GrpcError = class extends Error {
+  /**
+   * gRPC status code
+   */
+  code;
+  /**
+   * Create a new gRPC error
+   *
+   * @param code - gRPC status code
+   * @param message - Error message
+   */
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "GrpcError";
+  }
+};
+function createUnaryHandler(methodName, handler, requestType, responseType) {
+  return {
+    async handleRequest(request) {
+      if (request.methodName !== methodName) {
+        throw new GrpcError(12 /* UNIMPLEMENTED */, `Method ${request.methodName} not implemented`);
+      }
+      const req = requestType.decode(request.payload);
+      const result = await handler(req, request.metadata);
+      let response;
+      let responseMetadata;
+      if (result && typeof result === "object" && "response" in result) {
+        response = result.response;
+        responseMetadata = result.metadata;
+      } else {
+        response = result;
+      }
+      const encoded = responseType.encode(response).finish();
+      if (responseMetadata) {
+        return {
+          payload: Buffer.from(encoded),
+          metadata: responseMetadata
+        };
+      }
+      return {
+        payload: Buffer.from(encoded)
+      };
+    }
+  };
+}
+function createServiceHandler(methods) {
+  return {
+    async handleRequest(request) {
+      const handler = methods[request.methodName];
+      if (!handler) {
+        throw new GrpcError(12 /* UNIMPLEMENTED */, `Method ${request.methodName} not implemented`);
+      }
+      return handler.handleRequest(request);
+    }
+  };
+}
+
+// src/routing.ts
+function route(path2, options = {}) {
+  return (handler) => {
+    const methods = options.methods ? Array.isArray(options.methods) ? options.methods : [options.methods] : ["GET"];
+    const metadata = {
+      method: methods.join(","),
+      path: path2,
+      handler_name: handler.name || "anonymous",
+      request_schema: options.bodySchema ?? void 0,
+      response_schema: options.responseSchema ?? void 0,
+      parameter_schema: options.parameterSchema ?? void 0,
+      cors: options.cors ?? void 0,
+      is_async: true
+    };
+    handler.__route_metadata__ = metadata;
+    return handler;
+  };
+}
+function get(path2, options = {}) {
+  return route(path2, { ...options, methods: ["GET"] });
+}
+function post(path2, options = {}) {
+  return route(path2, { ...options, methods: ["POST"] });
+}
+function put(path2, options = {}) {
+  return route(path2, { ...options, methods: ["PUT"] });
+}
+function del(path2, options = {}) {
+  return route(path2, { ...options, methods: ["DELETE"] });
+}
+function patch(path2, options = {}) {
+  return route(path2, { ...options, methods: ["PATCH"] });
+}
+
+// src/testing.ts
+import fs from "fs/promises";
+import { createRequire as createRequire3 } from "module";
+import path from "path";
+import { gunzipSync, gzipSync } from "zlib";
+var MockWebSocketConnection = class {
+  handler;
+  queue = [];
+  constructor(handler) {
+    this.handler = handler;
+  }
+  async send_json(message) {
+    const response = await this.handler(message);
+    this.queue.push(response);
+  }
+  async sendJson(message) {
+    return this.send_json(message);
+  }
+  async sendText(text) {
+    return this.send_json(text);
+  }
+  async receive_json() {
+    return this.queue.shift();
+  }
+  async receiveJson() {
+    return this.receive_json();
+  }
+  async receiveText() {
+    const value = await this.receive_json();
+    return typeof value === "string" ? value : JSON.stringify(value);
+  }
+  async receiveBytes() {
+    const value = await this.receive_json();
+    if (Buffer.isBuffer(value)) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return Buffer.from(value);
+    }
+    return Buffer.from(JSON.stringify(value));
+  }
+  async receiveMessage() {
+    return this.receive_json();
+  }
+  async close() {
+  }
+};
+var nativeTestClient = null;
+var loadNativeTestClient = () => {
+  try {
+    const require2 = createRequire3(import.meta.url);
+    const binding = require2("../index.js");
+    return binding.TestClient;
+  } catch {
+    return null;
+  }
+};
+nativeTestClient = loadNativeTestClient();
+var isNativeCtor = nativeTestClient !== null;
+var JsTestResponse = class {
+  constructor(statusCode, headers, body) {
+    this.statusCode = statusCode;
+    this.headerBag = headers;
+    this.body = body;
+  }
+  body;
+  headerBag;
+  headers() {
+    return this.headerBag;
+  }
+  text() {
+    return this.decodeBody().toString("utf-8");
+  }
+  json() {
+    const raw = this.text();
+    if (raw.length === 0) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  bytes() {
+    return this.decodeBody();
+  }
+  decodeBody() {
+    const encoding = (this.headerBag["content-encoding"] ?? "").toLowerCase();
+    if (encoding === "gzip") {
+      try {
+        return gunzipSync(this.body);
+      } catch {
+        return this.body;
+      }
+    }
+    return this.body;
+  }
+  /**
+   * Extract GraphQL data from response
+   *
+   * @returns The data field from GraphQL response, or null/undefined if not present
+   */
+  graphqlData() {
+    const response = this.json();
+    return typeof response === "object" && response !== null && "data" in response ? response.data : void 0;
+  }
+  /**
+   * Extract GraphQL errors from response
+   *
+   * @returns Array of GraphQL error objects, or empty array if none present
+   */
+  graphqlErrors() {
+    const response = this.json();
+    return typeof response === "object" && response !== null && Array.isArray(response.errors) ? response.errors : [];
+  }
+};
+var JsNativeClient = class {
+  routes;
+  handlers;
+  dependencies;
+  config;
+  rateLimitBuckets;
+  websocketRoutes;
+  websocketHandlers;
+  constructor(routesJson, _websocketRoutesJson, handlers, websocketHandlers, dependencies, _lifecycleHooks, config) {
+    this.routes = JSON.parse(routesJson);
+    this.websocketRoutes = JSON.parse(_websocketRoutesJson ?? "[]");
+    this.handlers = handlers;
+    this.websocketHandlers = websocketHandlers;
+    this.dependencies = dependencies;
+    this.config = config;
+    this.rateLimitBuckets = /* @__PURE__ */ new Map();
+  }
+  matchRoute(method, path2) {
+    const cleanedPath = path2.split("?")[0] ?? path2;
+    for (const route2 of this.routes) {
+      if (route2.method.toUpperCase() !== method.toUpperCase()) {
+        continue;
+      }
+      const params = this.extractParams(route2.path, cleanedPath);
+      if (params) {
+        return { handlerName: route2.handler_name, params, route: route2 };
+      }
+    }
+    throw new Error(`No route matched ${method} ${path2}`);
+  }
+  extractParams(pattern, actual) {
+    const patternParts = pattern.split("/").filter(Boolean);
+    const actualParts = actual.split("/").filter(Boolean);
+    const hasTailParam = patternParts.some((part) => part.includes(":path"));
+    if (!hasTailParam && patternParts.length !== actualParts.length) {
+      return null;
+    }
+    if (hasTailParam && actualParts.length < patternParts.length - 1) {
+      return null;
+    }
+    const params = {};
+    for (let i = 0; i < patternParts.length; i += 1) {
+      const patternPart = patternParts[i];
+      const actualPart = actualParts[i];
+      if (!patternPart || !actualPart) {
+        return null;
+      }
+      if (patternPart.startsWith(":") || patternPart.startsWith("{") && patternPart.endsWith("}")) {
+        const isPathTailParam = patternPart.includes(":path");
+        const rawKey = patternPart.startsWith("{") ? patternPart.slice(1, -1).split(":")[0] : patternPart.slice(1);
+        const key = rawKey ?? "";
+        if (isPathTailParam) {
+          params[key] = decodeURIComponent(actualParts.slice(i).join("/"));
+          return params;
+        }
+        params[key] = decodeURIComponent(actualPart);
+        continue;
+      }
+      if (patternPart !== actualPart) {
+        return null;
+      }
+    }
+    return params;
+  }
+  buildQuery(path2) {
+    const query = {};
+    const url = new URL(path2, "http://localhost");
+    url.searchParams.forEach((value, key) => {
+      if (!(key in query)) {
+        query[key] = value;
+      }
+    });
+    return query;
+  }
+  validateParams(route2, params) {
+    const schema = route2.parameter_schema;
+    if (!schema?.properties) {
+      return null;
+    }
+    for (const [key, meta] of Object.entries(schema.properties)) {
+      if (meta.source !== "path") {
+        continue;
+      }
+      const raw = params[key];
+      if (raw === void 0) {
+        continue;
+      }
+      if (meta.format === "date" || meta.format === "date-time") {
+        const parsed = new Date(raw);
+        if (Number.isNaN(parsed.valueOf())) {
+          return new JsTestResponse(422, {}, Buffer.from(""));
+        }
+        params[key] = parsed;
+      }
+    }
+    return null;
+  }
+  async invoke(method, path2, headers, body) {
+    const routeMatch = (() => {
+      try {
+        return this.matchRoute(method, path2);
+      } catch {
+        return null;
+      }
+    })();
+    if (!routeMatch) {
+      const staticResponse = await this.serveStatic(path2);
+      if (staticResponse) {
+        return staticResponse;
+      }
+      throw new Error(`No route matched ${method} ${path2}`);
+    }
+    const { handlerName, params, route: route2 } = routeMatch;
+    const handler = this.handlers[handlerName];
+    if (!handler) {
+      throw new Error(`Handler not found for ${handlerName}`);
+    }
+    if (this.config?.rateLimit && this.isRateLimited(route2.path)) {
+      return new JsTestResponse(429, {}, Buffer.from(""));
+    }
+    const validationResponse = this.validateParams(route2, params);
+    if (validationResponse) {
+      return validationResponse;
+    }
+    const requestPayload = {
+      method,
+      path: path2,
+      params,
+      query: this.buildQuery(path2),
+      headers: headers ?? {},
+      cookies: {},
+      body: this.encodeBody(body),
+      dependencies: this.dependencies ?? void 0
+    };
+    const result = await handler(this.safeStringify(requestPayload));
+    const response = await this.toResponse(result);
+    return this.applyCompression(response, headers);
+  }
+  async toResponse(result) {
+    if (isStreamingResponse(result)) {
+      const handle = getStreamingHandle(result);
+      if (handle.kind === "js") {
+        const buffers = [];
+        for await (const chunk of handle.iterator) {
+          if (chunk === null || chunk === void 0) {
+            continue;
+          }
+          if (Buffer.isBuffer(chunk)) {
+            buffers.push(chunk);
+            continue;
+          }
+          if (typeof chunk === "string") {
+            buffers.push(Buffer.from(chunk));
+            continue;
+          }
+          if (chunk instanceof ArrayBuffer || ArrayBuffer.isView(chunk)) {
+            const view = ArrayBuffer.isView(chunk) ? Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength) : Buffer.from(chunk);
+            buffers.push(view);
+            continue;
+          }
+          buffers.push(Buffer.from(this.safeStringify(chunk)));
+        }
+        const bodyBuffer = buffers.length === 0 ? Buffer.alloc(0) : Buffer.concat(buffers);
+        return new JsTestResponse(handle.init.statusCode ?? 200, handle.init.headers ?? {}, bodyBuffer);
+      }
+    }
+    if (typeof result === "string") {
+      try {
+        const parsed = JSON.parse(result);
+        if (parsed && typeof parsed === "object" && ("status" in parsed || "statusCode" in parsed || "body" in parsed)) {
+          const statusCode = parsed.status ?? parsed.statusCode ?? 200;
+          const textBody = typeof parsed.body === "string" || parsed.body === void 0 ? parsed.body ?? "" : JSON.stringify(parsed.body);
+          return new JsTestResponse(statusCode, parsed.headers ?? {}, Buffer.from(textBody));
+        }
+      } catch {
+      }
+      return new JsTestResponse(200, {}, Buffer.from(result));
+    }
+    if (result && typeof result === "object" && ("status" in result || "statusCode" in result)) {
+      const payload = result;
+      const statusCode = payload.status ?? payload.statusCode ?? 200;
+      const textBody = typeof payload.body === "string" || payload.body === void 0 ? payload.body ?? "" : JSON.stringify(payload.body);
+      return new JsTestResponse(statusCode, payload.headers ?? {}, Buffer.from(textBody));
+    }
+    const text = this.safeStringify(result);
+    return new JsTestResponse(200, {}, Buffer.from(text));
+  }
+  isRateLimited(routePath) {
+    if (!this.config?.rateLimit) {
+      return false;
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const key = routePath;
+    const existing = this.rateLimitBuckets.get(key);
+    const bucket = existing && existing.resetAt === now ? existing : { tokens: this.config.rateLimit.burst, resetAt: now };
+    if (bucket.tokens <= 0) {
+      this.rateLimitBuckets.set(key, bucket);
+      return true;
+    }
+    bucket.tokens -= 1;
+    this.rateLimitBuckets.set(key, bucket);
+    return false;
+  }
+  async serveStatic(targetPath) {
+    const normalized = targetPath.split("?")[0] ?? targetPath;
+    const staticConfig = this.config?.staticFiles ?? [];
+    for (const entry of staticConfig) {
+      if (!normalized.startsWith(entry.routePrefix)) {
+        continue;
+      }
+      const relative = normalized.slice(entry.routePrefix.length);
+      const resolved = relative === "/" || relative === "" ? "index.html" : relative.replace(/^\//, "");
+      const filePath = path.join(entry.directory, resolved);
+      try {
+        const contents = await fs.readFile(filePath);
+        const contentType = this.detectContentType(filePath);
+        const headers = {
+          "content-type": contentType
+        };
+        if (entry.cacheControl) {
+          headers["cache-control"] = entry.cacheControl;
+        }
+        const bodyBuffer = contentType.startsWith("text/") ? Buffer.from(contents.toString("utf-8").replace(/\n$/, "")) : contents;
+        return new JsTestResponse(200, headers, bodyBuffer);
+      } catch {
+      }
+    }
+    return null;
+  }
+  detectContentType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+      case ".txt":
+        return "text/plain";
+      case ".html":
+      case ".htm":
+        return "text/html";
+      case ".json":
+        return "application/json";
+      case ".xml":
+        return "application/xml";
+      case ".csv":
+        return "text/csv";
+      case ".png":
+        return "image/png";
+      case ".jpg":
+      case ".jpeg":
+        return "image/jpeg";
+      case ".pdf":
+        return "application/pdf";
+      default:
+        return "application/octet-stream";
+    }
+  }
+  applyCompression(response, requestHeaders) {
+    const config = this.config?.compression;
+    const acceptsGzip = (this.lookupHeader(requestHeaders, "accept-encoding") ?? "").includes("gzip");
+    if (!config || !config.gzip || !acceptsGzip) {
+      return response;
+    }
+    const rawBody = response.bytes();
+    if (rawBody.length < (config.minSize ?? 0)) {
+      return response;
+    }
+    const gzipped = gzipSync(rawBody, { level: config.quality ?? 6 });
+    const headers = { ...response.headers(), "content-encoding": "gzip" };
+    return new JsTestResponse(response.statusCode, headers, gzipped);
+  }
+  lookupHeader(headers, name) {
+    if (!headers) {
+      return void 0;
+    }
+    const target = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+      if (key.toLowerCase() === target) {
+        return value;
+      }
+    }
+    return void 0;
+  }
+  safeStringify(value) {
+    return JSON.stringify(value, (_key, val) => {
+      if (typeof val === "bigint") {
+        return val.toString();
+      }
+      return val;
+    });
+  }
+  encodeBody(body) {
+    if (body === null) {
+      return null;
+    }
+    if (typeof body === "object" && ("__spikard_multipart__" in body || "__spikard_form__" in body)) {
+      return Array.from(Buffer.from(this.safeStringify(body)));
+    }
+    if (Buffer.isBuffer(body)) {
+      return Array.from(body);
+    }
+    return body;
+  }
+  async get(path2, headers) {
+    return this.invoke("GET", path2, headers, null);
+  }
+  async post(path2, headers, body) {
+    return this.invoke("POST", path2, headers, body);
+  }
+  async put(path2, headers, body) {
+    return this.invoke("PUT", path2, headers, body);
+  }
+  async delete(path2, headers) {
+    return this.invoke("DELETE", path2, headers, null);
+  }
+  async patch(path2, headers, body) {
+    return this.invoke("PATCH", path2, headers, body);
+  }
+  async head(path2, headers) {
+    return this.invoke("HEAD", path2, headers, null);
+  }
+  async options(path2, headers) {
+    return this.invoke("OPTIONS", path2, headers, null);
+  }
+  async trace(path2, headers) {
+    return this.invoke("TRACE", path2, headers, null);
+  }
+  async websocket(_path) {
+    const match = this.websocketRoutes?.find((route2) => route2.path === _path);
+    if (!match) {
+      throw new Error("WebSocket testing is not available in the JS fallback client");
+    }
+    const handlerEntry = this.websocketHandlers?.[match.handler_name];
+    if (!handlerEntry) {
+      throw new Error("WebSocket testing is not available in the JS fallback client");
+    }
+    const handler = handlerEntry && typeof handlerEntry.handleMessage === "function" ? handlerEntry.handleMessage : null;
+    if (!handler) {
+      throw new Error("WebSocket testing is not available in the JS fallback client");
+    }
+    const mock = new MockWebSocketConnection(async (msg) => handler(msg));
+    return mock;
+  }
+};
+var defaultNativeClientFactory = (routesJson, websocketRoutesJson, handlers, websocketHandlers, dependencies, lifecycleHooks, config) => {
+  if (isNativeCtor && nativeTestClient) {
+    return new nativeTestClient(
+      routesJson,
+      websocketRoutesJson,
+      handlers,
+      websocketHandlers,
+      dependencies,
+      lifecycleHooks,
+      config
+    );
+  }
+  return new JsNativeClient(
+    routesJson,
+    websocketRoutesJson,
+    handlers,
+    websocketHandlers,
+    dependencies,
+    lifecycleHooks,
+    config
+  );
+};
+var nativeClientFactory = defaultNativeClientFactory;
+var TestClient = class {
+  app;
+  nativeClient;
+  looksLikeStringHandler(fn) {
+    const source = fn.toString();
+    return source.includes("requestJson") || source.includes("request_json") || source.includes("JSON.parse") || source.includes("JSON.parse(");
+  }
+  /**
+   * Create a new test client
+   *
+   * @param app - Spikard application with routes and handlers
+   */
+  constructor(app) {
+    if (!app || !Array.isArray(app.routes)) {
+      throw new Error("Invalid Spikard app: missing routes array");
+    }
+    this.app = app;
+    const routesJson = JSON.stringify(app.routes);
+    const websocketRoutesJson = JSON.stringify(app.websocketRoutes ?? []);
+    const handlerEntries = Object.entries(app.handlers || {});
+    const handlersMap = Object.fromEntries(
+      handlerEntries.map(([name, handler]) => {
+        const prefersParsedBody = this.looksLikeStringHandler(handler);
+        const nativeHandler = isNativeHandler(handler) || prefersParsedBody ? handler : wrapHandler(handler);
+        if (prefersParsedBody) {
+          nativeHandler.__spikard_raw_body = false;
+        } else if (nativeHandler.__spikard_raw_body === void 0) {
+          nativeHandler.__spikard_raw_body = true;
+        }
+        return [name, nativeHandler];
+      })
+    );
+    const websocketHandlersMap = app.websocketHandlers || {};
+    const config = app.config ?? null;
+    const dependencies = app.dependencies ?? null;
+    const lifecycleHooks = app.getLifecycleHooks?.() ?? null;
+    this.nativeClient = nativeClientFactory(
+      routesJson,
+      websocketRoutesJson,
+      handlersMap,
+      websocketHandlersMap,
+      dependencies,
+      lifecycleHooks,
+      config
+    );
+  }
+  /**
+   * Make a GET request
+   *
+   * @param path - Request path
+   * @param headers - Optional request headers
+   * @returns Response promise
+   */
+  async get(path2, headers) {
+    return this.nativeClient.get(path2, headers || null);
+  }
+  /**
+   * Make a POST request
+   *
+   * @param path - Request path
+   * @param options - Request options
+   * @returns Response promise
+   */
+  async post(path2, options) {
+    return this.nativeClient.post(path2, this.buildHeaders(options), this.buildBody(options));
+  }
+  /**
+   * Make a PUT request
+   *
+   * @param path - Request path
+   * @param options - Request options
+   * @returns Response promise
+   */
+  async put(path2, options) {
+    return this.nativeClient.put(path2, this.buildHeaders(options), this.buildBody(options));
+  }
+  /**
+   * Make a DELETE request
+   *
+   * @param path - Request path
+   * @param headers - Optional request headers
+   * @returns Response promise
+   */
+  async delete(path2, headers) {
+    return this.nativeClient.delete(path2, headers || null);
+  }
+  /**
+   * Make a PATCH request
+   *
+   * @param path - Request path
+   * @param options - Request options
+   * @returns Response promise
+   */
+  async patch(path2, options) {
+    return this.nativeClient.patch(path2, this.buildHeaders(options), this.buildBody(options));
+  }
+  /**
+   * Make a HEAD request
+   *
+   * @param path - Request path
+   * @param headers - Optional request headers
+   * @returns Response promise
+   */
+  async head(path2, headers) {
+    return this.nativeClient.head(path2, headers || null);
+  }
+  /**
+   * Make an OPTIONS request
+   *
+   * @param path - Request path
+   * @param options - Request options
+   * @returns Response promise
+   */
+  async options(path2, options) {
+    return this.nativeClient.options(path2, this.buildHeaders(options));
+  }
+  /**
+   * Make a TRACE request
+   *
+   * @param path - Request path
+   * @param headers - Optional request headers
+   * @returns Response promise
+   */
+  async trace(path2, options) {
+    return this.nativeClient.trace(path2, this.buildHeaders(options));
+  }
+  buildHeaders(options) {
+    if (!options?.headers || Object.keys(options.headers).length === 0) {
+      return null;
+    }
+    return options.headers;
+  }
+  buildBody(options) {
+    if (!options) {
+      return null;
+    }
+    if (options.multipart) {
+      return {
+        __spikard_multipart__: {
+          fields: options.multipart.fields ?? {},
+          files: options.multipart.files ?? []
+        }
+      };
+    }
+    if (options.form) {
+      return {
+        __spikard_form__: options.form
+      };
+    }
+    if ("json" in options) {
+      return options.json ?? null;
+    }
+    return null;
+  }
+  /**
+   * Connect to a WebSocket endpoint
+   *
+   * Uses the native test client to create an in-memory WebSocket connection.
+   *
+   * @param path - WebSocket path
+   * @returns WebSocket test connection
+   */
+  async websocketConnect(path2) {
+    const handlerName = this.app.websocketRoutes?.find((r) => r.path === path2)?.handler_name;
+    const handlerEntry = handlerName ? this.app.websocketHandlers?.[handlerName] : void 0;
+    const handler = handlerEntry && typeof handlerEntry.handleMessage === "function" ? handlerEntry.handleMessage : null;
+    if (handler) {
+      const mock = new MockWebSocketConnection(async (msg) => handler(msg));
+      return mock;
+    }
+    const routeMatch = this.app.routes.find((r) => r.path === path2);
+    if (routeMatch) {
+      const handlerFn = this.app.handlers?.[routeMatch.handler_name];
+      if (handlerFn) {
+        const mock = new MockWebSocketConnection(async (msg) => {
+          const payload = typeof msg === "string" ? msg : JSON.stringify(msg);
+          const result = await handlerFn(payload);
+          if (typeof result === "string") {
+            try {
+              return JSON.parse(result);
+            } catch {
+              return result;
+            }
+          }
+          return result;
+        });
+        return mock;
+      }
+    }
+    return this.nativeClient.websocket(path2);
+  }
+  /**
+   * Send a GraphQL query/mutation
+   *
+   * Convenience method for sending GraphQL queries and mutations.
+   *
+   * @param query - GraphQL query string
+   * @param variables - Optional GraphQL variables object
+   * @param operationName - Optional GraphQL operation name
+   * @returns Response promise
+   *
+   * @example
+   * ```typescript
+   * const response = await client.graphql('query { user(id: "1") { id name } }');
+   * const user = response.graphqlData().user;
+   * ```
+   */
+  async graphql(query, variables, operationName) {
+    const json = { query };
+    if (variables !== null && variables !== void 0) {
+      json.variables = variables;
+    }
+    if (operationName !== null && operationName !== void 0) {
+      json.operationName = operationName;
+    }
+    return this.post("/graphql", { json });
+  }
+  /**
+   * Send a GraphQL query and get HTTP status separately
+   *
+   * Returns status information alongside the response for cases where
+   * you need both the HTTP status and the full response details.
+   *
+   * @param query - GraphQL query string
+   * @param variables - Optional GraphQL variables object
+   * @param operationName - Optional GraphQL operation name
+   * @returns Promise with status and response details
+   */
+  async graphqlWithStatus(query, variables, operationName) {
+    const response = await this.graphql(query, variables, operationName);
+    return {
+      status: response.statusCode,
+      statusCode: response.statusCode,
+      headers: JSON.stringify(response.headers()),
+      bodyText: response.text()
+    };
+  }
+  /**
+   * Cleanup resources when test client is done
+   */
+  async cleanup() {
+  }
+};
+export {
+  GrpcError,
+  GrpcStatusCode,
+  Spikard,
+  StreamingResponse,
+  TestClient,
+  UploadFile,
+  background_exports as background,
+  createServiceHandler,
+  createUnaryHandler,
+  del,
+  get,
+  patch,
+  post,
+  put,
+  route,
+  runServer,
+  wrapBodyHandler,
+  wrapHandler
+};
+//# sourceMappingURL=index.mjs.map