René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Opt-in Call Tracing Mode","articleBody":"## Motivation\n\nCrossing the Swift \u003c-\u003e JavaScript bridge is expensive, but today JavaScriptKit users have almost no visibility into how the bridge is actually used at runtime. As a result, performance issues related to excessive calls or unintended data bouncing across the bridge are often identified only by intuition.\n\nTo make performance work more data-driven, we want a minimal observability mechanism that allows users to trace when and how JavaScriptKit bridge calls happen, without imposing overhead on production builds.\n\n## Overview\n\nThis proposal introduces an optional tracing hook API, focused purely on providing hook points at bridge crossings.\n\nThe key design constraints are:\n\n- Tracing must be opt-in and compile-time gated\n- When disabled, there must be no runtime overhead\n- JavaScriptKit itself should not perform logging or aggregation\n- The API should be flexible enough to integrate with user-defined tracing systems\n\nTo achieve this, tracing hooks are only compiled when a specific SwiftPM package trait is enabled. When the trait is not enabled (default), the feature is entirely absent from the binary.\n\nFor each bridge crossing, JavaScriptKit calls a *start hook* provided by the user. That hook returns a closure, which JavaScriptKit later invokes at the *end* of the bridge crossing. This closure-based pairing avoids the need for JavaScriptKit to manage call IDs or start/end bookkeeping.\n\n## API Design (draft)\n\nThe initial scope covers two kinds of bridge crossings.\n\n### Swift -\u003e JavaScript calls\n\nWhen Swift code calls into JavaScript via JavaScriptKit, a tracing hook is invoked at the start and end of the call.\n\n- If a JavaScript function is called directly (i.e. without a receiver), the hook receives the function object and arguments.\n- If a JavaScript method is called, the hook receives the receiver object, the method name, and arguments.\n\n### JavaScript -\u003e Swift calls (JSClosure)\n\nWhen a JSClosure is invoked from the JavaScript side, a tracing hook is invoked.\n\nThe hook receives the file name and line number where the JSClosure was created. This information is already tracked by JavaScriptKit and can be forwarded without additional runtime cost.\n\n### API shape\n\n```swift\n#if Tacing\npublic struct JSTracing {\n  public static let default = JSTracing()\n\n  public enum JSCallInfo {\n    case function(function: JSObject, arguments: [JSValue])\n    case method(receiver: JSObject, methodName: String, arguments: [JSValue])\n  }\n\n  /// Register a hook for Swift to JavaScript calls.\n  ///\n  /// - Returns: A cleanup closure that unregisters the hook.\n  public func addJSCallHook(\n    _ hook: @escaping (_ info: JSCallInfo) -\u003e (() -\u003e Void)?\n  ) -\u003e () -\u003e Void\n\n  public struct JSClosureCallInfo {\n    /// The file identifier where the called JSClosure is defined\n    public let fileID: StaticString\n    /// The line number where the called JSClosure is defined\n    public let line: UInt\n  }\n  /// Register a hook for JavaScript to Swift calls via JSClosure.\n  ///\n  /// - Returns: A cleanup closure that unregisters the hook.\n  public func addJSClosureCallHook(\n    _ hook: @escaping (_ info: JSClosureCallInfo) -\u003e (() -\u003e Void)?\n  ) -\u003e () -\u003e Void\n}\n#endif\n```\n\nUsage:\n\n```swift\nlet remove = JSTracing.default.addJSCallHook { info in\n  let start = now()\n  return {\n    record(info, now() - start)\n  }\n}\n\ndefer { remove() }\n```","author":{"url":"https://github.com/kateinoigakukun","@type":"Person","name":"kateinoigakukun"},"datePublished":"2026-01-29T05:09:23.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/547/JavaScriptKit/issues/547"}