Docs: Document BridgeJS generic functions

Author: krodak

Plugins/BridgeJS/README.md

@@ -98,7 +98,7 @@ graph LR
 | `Dictionary<K, V>` | `Record<K, V>` | - | [#495](https://github.com/swiftwasm/JavaScriptKit/issues/495) |
 | `Set<T>` | `Set<T>` | - | [#397](https://github.com/swiftwasm/JavaScriptKit/issues/397) |
 | `Foundation.URL` | `string` | - | [#496](https://github.com/swiftwasm/JavaScriptKit/issues/496) |
-| Generics | - | - | [#398](https://github.com/swiftwasm/JavaScriptKit/issues/398) |
+| Generics (top-level functions) | `<T>(value: T, type: BridgeType<T>)` | - | ✅ |
 
 ### Import-specific (TypeScript -> Swift)
 

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/BridgeJS-Internals/Design-Rationale.md

@@ -32,6 +32,14 @@ So even if you cache the property name (e.g. with `CachedJSStrings`), you are st
 
 BridgeJS avoids this by generating **separate** access paths per property or method. Each generated getter/setter or function call has a stable shape at the engine level, so the IC can stay monomorphic or polymorphic and the fast path is used.
 
+## Generic imports
+
+An imported generic `@JSFunction` (`func parse<T: _BridgedSwiftGenericBridgeable>(...)`) lets one piece of glue serve many concrete types. The generic value crosses using the type's own stack ABI, and a runtime type ID (interned once via `swift_js_resolve_type_id`) selects the matching JS codec, so the type-agnostic glue can lower and lift the right representation without a specialized path per call site.
+
+## Generic exports
+
+An exported generic `@JS` function reuses the same stack ABI and codec table, with the dispatch reversed. The WebAssembly entry point is a concrete `@_expose` thunk that takes the runtime type ID as a trailing `Int32`. It looks the ID up in a codegen-emitted registry of `_BridgedSwiftGenericBridgeable` types, reifies `T` through an opened existential, and runs an unspecialized helper that pops the argument from the stack, calls your function, and pushes the result. The JavaScript wrapper resolves the `BridgeType<T>` token to the same interned ID and uses the matching codec to lower the argument and lift the return. Because this depends on existential types, generic exports are excluded under Embedded Swift.
+
 ## What to read next
 
 - ABI and binary interface details will be documented in this section as they stabilize.

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Function.md

@@ -136,6 +136,77 @@ export type Exports = {
 }
 ```
 
+### Generic functions
+
+A `@JS` function can be generic over a type parameter constrained to `_BridgedSwiftGenericBridgeable`. The concrete type chosen at the call site crosses the bridge:
+
+```swift
+import JavaScriptKit
+
+@JS public func identity<T: _BridgedSwiftGenericBridgeable>(_ value: T) -> T {
+    return value
+}
+```
+
+`T` must be a bridgeable type: a supported primitive (`Bool`, any fixed-width integer such as `Int`/`UInt`/`Int8`…`UInt64`, `Float`, `Double`, `String`, or `JSValue`), or a `@JS` struct, `final @JS class`, or `@JS enum` in your module. You do not write any conformance yourself; marking a type `@JS` makes it usable as `T` (see <doc:Supported-Types>).
+
+Because TypeScript erases generics, the JavaScript caller passes a `BridgeType<T>` token as the last argument so the bridge can select the right type at runtime. The tokens come from a generated `BridgeTypes` map exported at the top level of `bridge-js.js`; import it directly rather than reading it from the `exports` object:
+
+```javascript
+import { BridgeTypes } from "./bridge-js.js";
+
+const x = exports.identity(42, BridgeTypes.Int);
+const p = exports.identity({ x: 1, y: 2 }, BridgeTypes.MyPoint);
+```
+
+Concrete parameters keep their positions; the token is always appended last. The non-generic parameters of a generic `@JS` function may be any supported bridged type, including value types such as `@JS` structs, arrays, dictionaries, and associated-value enums alongside the generic parameter. The generated TypeScript declarations look like:
+
+```typescript
+export type BridgeType<T> = string & { readonly __bridgeType?: (value: T) => void };
+export const BridgeTypes: { Bool: BridgeType<boolean>; Int: BridgeType<number>; Float: BridgeType<number>; Double: BridgeType<number>; String: BridgeType<string>; MyPoint: BridgeType<MyPoint>; };
+export type Exports = {
+    identity<T>(value: T, typeT: BridgeType<T>): T;
+}
+```
+
+A single bare `T` may be used in more than one parameter, such as `pair<T>(_ a: T, _ b: T) -> T`; each generic value is lowered with the same token, and the arguments are not reordered.
+
+A function may also declare multiple distinct generic parameters, such as `combine<T, U>(_ a: T, _ b: U) -> T`. Each distinct generic parameter takes its own `BridgeType` token, appended after the regular arguments in declaration order, and each generic value crosses the bridge with its own type's codec:
+
+```swift
+@JS public func combine<T: _BridgedSwiftGenericBridgeable, U: _BridgedSwiftGenericBridgeable>(_ a: T, _ b: U) -> T {
+    a
+}
+```
+
+```javascript
+import { BridgeTypes } from "./bridge-js.js";
+
+const first = exports.combine(7, "hello", BridgeTypes.Int, BridgeTypes.String);
+```
+
+```typescript
+export type Exports = {
+    combine<T, U>(a: T, b: U, typeT: BridgeType<T>, typeU: BridgeType<U>): T;
+}
+```
+
+The generic parameter may also be wrapped as `[T]`, `T?`, or `[String: T]` in parameters and the result:
+
+```swift
+@JS public func firstOrNil<T: _BridgedSwiftGenericBridgeable>(_ values: [T]) -> T? {
+    values.first
+}
+```
+
+```typescript
+export type Exports = {
+    firstOrNil<T>(values: T[], typeT: BridgeType<T>): T | null;
+}
+```
+
+The result must be one of the declared generic parameters (such as `T` or `U`), a supported wrapper of one (`[T]`, `T?`, `[String: T]`), or `Void`. A generic parameter that is never used in any parameter is rejected, and returning a concrete non-`Void` type from a generic `@JS` function is not supported. Generic `@JS` functions must be top-level and synchronous (see <doc:Unsupported-Features>).
+
 ## Supported Features
 
 | Swift Feature | Status |
@@ -148,6 +219,6 @@ export type Exports = {
 | Throwing JS exception: `func x() throws(JSException)` | ✅ |
 | Throwing any exception: `func x() throws` | ❌ |
 | Async methods: `func x() async` | ✅ |
-| Generics | ❌ |
+| Generic parameter/result types (constrained to `_BridgedSwiftGenericBridgeable`) | ✅ |
 | Opaque types: `func x() -> some P`, `func y(_: some P)` | ❌ |
 | Default parameter values: `func x(_ foo: String = "")` | ✅ (See <doc:Exporting-Swift-Default-Parameters>) |

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Importing-JavaScript/Importing-JS-Function.md

@@ -41,11 +41,41 @@ If you used `from: .global`, do not pass the function in `getImports()`; the run
 
 Bound functions are `throws(JSException)`. Call them with `try` or `try?`; they throw when the JavaScript implementation throws.
 
+## Generic functions
+
+A `@JSFunction` can be generic over a type parameter constrained to `_BridgedSwiftGenericBridgeable`. The concrete type chosen at the call site then crosses the bridge:
+
+```swift
+@JSFunction func parse<T: _BridgedSwiftGenericBridgeable>(_ json: String) throws(JSException) -> T
+
+let user: User = try parse(jsonString)
+```
+
+`T` must be a bridgeable type: a supported primitive (`Bool`, any fixed-width integer such as `Int`/`UInt`/`Int8`…`UInt64`, `Float`, `Double`, `String`, or `JSValue`), or a `@JS` struct, `final @JS class`, or `@JS enum` in your module. You do not write any conformance yourself; marking a type `@JS` makes it usable as `T` (see <doc:Supported-Types>). Generics are not supported for `async`, `@JSClass` members, or `where` clauses (see <doc:Unsupported-Features>).
+
+A generic type parameter may be used in more than one parameter, an imported function may declare more than one distinct generic parameter, and a generic result type may be used on a function that takes no generic parameters (the JavaScript implementation produces the value):
+
+```swift
+@JSFunction func pickFirst<T: _BridgedSwiftGenericBridgeable>(_ a: T, _ b: T) throws(JSException) -> T
+
+@JSFunction func makeValue<T: _BridgedSwiftGenericBridgeable>() throws(JSException) -> T
+
+@JSFunction func combine<T: _BridgedSwiftGenericBridgeable, U: _BridgedSwiftGenericBridgeable>(_ a: T, _ b: U) throws(JSException) -> U
+```
+
+The generic parameter may also be wrapped as `[T]`, `T?`, or `[String: T]` in parameters and the result:
+
+```swift
+@JSFunction func roundTrip<T: _BridgedSwiftGenericBridgeable>(_ values: [T]) throws(JSException) -> [T]
+
+@JSFunction func lookup<T: _BridgedSwiftGenericBridgeable>(_ values: [String: T]) throws(JSException) -> T?
+```
+
 ## Supported features
 
 | Feature | Status |
 |:--|:--|
 | Primitive parameter/result types (e.g. `Double`, `Bool`) | ✅ |
 | `String` parameter/result type | ✅ |
+| Generic parameter/result types (constrained to `_BridgedSwiftGenericBridgeable`) | ✅ |
 | Async function | ❌ |
-| Generics | ❌ |

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Supported-Types.md

@@ -31,6 +31,18 @@ When using `JSTypedArray<T>` (or convenience typealiases) in `@JS` signatures, t
 
 See <doc:Exporting-Swift-Array> for usage details.
 
+## Generic type parameters
+
+A generic type parameter constrained to `_BridgedSwiftGenericBridgeable` is supported as a parameter or result type in both directions: an imported `@JSFunction` (see <doc:Importing-JS-Function>) and an exported `@JS` function (see <doc:Exporting-Swift-Function>). The types that satisfy that constraint are:
+
+- `Bool`, `Float`, `Double`, `String`, and `JSValue`
+- every fixed-width integer: `Int`, `UInt`, `Int8`/`Int16`/`Int32`/`Int64`, and `UInt8`/`UInt16`/`UInt32`/`UInt64`
+- any `@JS` struct, `final @JS class`, or `@JS enum` (case, raw-value, or associated-value) in your module
+
+You do not write the conformance by hand: marking a type `@JS` (or using a built-in primitive) is what makes it usable as the generic argument.
+
+The generic parameter may be used bare (`T`) or wrapped in `[T]`, `T?`, or `[String: T]`. Other or nested wrappings (for example `[T?]`, `[[T]]`, or `[Int: T]`) are not supported. `JSObject` cannot be used as the generic argument; use `JSValue` instead.
+
 ## See Also
 
 - <doc:Generating-from-TypeScript>

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Unsupported-Features.md

@@ -34,3 +34,17 @@ While using `@JS` types from another Swift module is supported, it is not possib
 ### Exporting Swift: types from another Swift package
 
 Types defined in a separate Swift package cannot yet be referenced from `@JS` declarations in your package.
+
+## Generics
+
+Generic functions are supported in both directions, through a type parameter constrained to `_BridgedSwiftGenericBridgeable`: an imported `@JSFunction` (see <doc:Importing-JS-Function>) and an exported `@JS` function (see <doc:Exporting-Swift-Function>). A function may declare one or more distinct generic parameters, such as `combine<T, U>(_ a: T, _ b: U) -> T`. The following forms are not supported and produce build-time diagnostics:
+
+- `async` generic functions.
+- Generic methods inside `@JSClass` types or static members (generics are top-level only).
+- `where` clauses on a generic declaration.
+- A declared generic parameter that is not used in any parameter.
+- An exported generic function that returns a concrete, non-`Void` type. The result of an exported generic function must be one of the declared generic parameters or `Void`.
+
+The generic parameter may be used bare (`T`) or wrapped in `[T]`, `T?`, or `[String: T]`. Nested or other wrappings, such as `[T?]`, `[[T]]`, `T??`, or `[Int: T]`, are not supported and produce build-time diagnostics. `JSObject` cannot be used as the generic argument (it is a non-final class); use `JSValue` instead.
+
+Exported generic functions additionally require runtime existential support, so they are not available under Embedded Swift. Imported generics remain available there.