docs: README and TypeScript docs (#40)

Author: timfish

README.md

@@ -1,22 +1,183 @@
 # `@apm-js-collab/code-transformer`
 
-This is a temporary fork of [`DataDog/orchestrion-js`](https://github.com/DataDog/orchestrion-js/). We intend all changes to be upstreamed to the original repository, 
+This is a fork of
+[`DataDog/orchestrion-js`](https://github.com/DataDog/orchestrion-js/).
 
-This is a library for instrumenting Node.js libraries at build or load time.
+This is a library to aid in instrumenting Node.js libraries at build or load
+time.
 
-It provides `VisitMut` implementations for SWC's AST nodes, which can be used to insert tracing code into matching functions. 
-It can be used in SWC plugins, or anything else that mutates JavaScript ASTs using SWC.
+It uses SWC's Rust AST walker to inject code that calls Node.js
+[`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel).
 
-`@apm-js-collab/code-transformer` is built as a JavaScript module, which can be used from Node.js.
+You likely don't want to use this library directly; instead, consider using:
+
+- [`@apm-js-collab/tracing-hooks/`](https://github.com/apm-js-collab/tracing-hooks/)
+  - ESM and `require` hooks to instrument modules as they are loaded.
+- [`apm-js-collab/code-transformer-bundler-plugins`](https://github.com/apm-js-collab/code-transformer-bundler-plugins)
+  - Bundler plugins for webpack, Vite, Rollup and esbuild to instrument modules
+    at build time.
+
+## JavaScript
+
+`@apm-js-collab/code-transformer` exposes the Rust library as a WebAssembly
+module.
+
+### Building
 
 To build the JavaScript module:
+
 - Ensure you have [Rust installed](https://www.rust-lang.org/tools/install)
-- Install the wasm toolchain `rustup target add wasm32-unknown-unknown --toolchain stable`
-- Install dependencies and build the module `npm install && npm run build`
+- Install the wasm toolchain\
+  `rustup target add wasm32-unknown-unknown --toolchain stable`
+- Install dependencies and build the module\
+  `npm install && npm run build`
+
+### Usage
+
+```javascript
+import * as codeTransformer from "@apm-js-collab/code-transformer";
+
+// The full instrumentation config
+const instrumentation = {
+    // The name of the diagnostics channel
+    channelName: "my-channel",
+    // Define the module you'd like to inject tracing channels into
+    module: {
+        name: "my-module",
+        versionRange: ">=1.0.0",
+        filePath: "./dist/index.js",
+    },
+    // Define the function you'd like to instrument
+    // (e.g., match a method named 'foo' that returns a Promise)
+    functionQuery: {
+        methodName: "fetch",
+        kind: "Async",
+    },
+};
+
+// Create an InstrumentationMatcher with an array of instrumentation configs
+const matcher = codeTransformer.create([instrumentation]);
+
+// Get a transformer for a specific module
+const transformer = matcher.getTransformer(
+    "my-module",
+    "1.2.3",
+    "./dist/index.js",
+);
+
+if (transformer === undefined) {
+    throw new Error("No transformer found for module");
+}
+
+// Transform code
+const inputCode = "async function fetch() { return 42; }";
+const result = transformer.transform(inputCode, "unknown");
+console.log(result.code);
+
+// Both the matcher and transformer should be freed after use!
+matcher.free();
+transformer.free();
+```
+
+### API Reference
+
+```ts
+type ModuleType = "esm" | "cjs" | "unknown";
+type FunctionKind = "Sync" | "Async";
+```
+
+#### **`FunctionQuery` Variants**
+
+```ts
+type FunctionQuery =
+    | // Match class constructor
+    { className: string; index?: number }
+    | // Match class method
+    {
+        className: string;
+        methodName: string;
+        kind: FunctionKind;
+        index?: number;
+    }
+    | // Match method on objects
+    { methodName: string; kind: FunctionKind; index?: number }
+    | // Match standalone function
+    { functionName: string; kind: FunctionKind; index?: number }
+    | // Match arrow function or function expression
+    { expressionName: string; kind: FunctionKind; index?: number };
+```
+
+#### **`ModuleMatcher`**
+
+```ts
+type ModuleMatcher = {
+    name: string; // Module name
+    versionRange: string; // Matching semver range
+    filePath: string; // Path to the file from the module root
+};
+```
+
+#### **`InstrumentationConfig`**
+
+```ts
+type InstrumentationConfig = {
+    channelName: string; // Name of the diagnostics channel
+    module: ModuleMatcher;
+    functionQuery: FunctionQuery;
+};
+```
+
+### Functions
+
+```ts
+create(configs: InstrumentationConfig[], dc_module?: string | null): InstrumentationMatcher;
+```
+
+Create a matcher for one or more instrumentation configurations.
+
+- `configs` - Array of instrumentation configurations.
+- `dc_module` - Optional module to import `diagnostics_channel` API from.
+
+#### **`InstrumentationMatcher`**
+
+```ts
+getTransformer(module_name: string, version: string, file_path: string): Transformer | undefined;
+```
+
+Gets a transformer for a specific module and file.
+
+Returns a `Transformer` for the given module, or `undefined` if there were no
+matching instrumentation configurations.
+
+- `module_name` - Name of the module.
+- `version` - Version of the module.
+- `file_path` - Path to the file from the module root.
+
+```ts
+free(): void;
+```
+
+Free the matcher memory when it's no longer needed.
+
+#### **`Transformer`**
+
+```ts
+transform(code: string, module_type: ModuleType, sourcemap?: string | undefined): TransformOutput;
+```
+
+Transforms the code, injecting tracing as configured.
+
+Returns `{ code, map }`. `map` will be undefined if no sourcemap was supplied.
+
+- `code` - The JavaScript/TypeScript code to transform.
+- `module_type` - The type of module being transformed.
+- `sourcemap` - Optional existing source map for the code.
 
-## Contributing
+```ts
+free(): void;
+```
 
-See CONTRIBUTING.md
+Free the transformer memory when it's no longer needed.
 
 ## License
 

src/config.rs

@@ -13,10 +13,14 @@ use std::path::PathBuf;
     serde(rename_all = "camelCase")
 )]
 #[derive(Debug, Clone)]
+/// Describes the module and file path you would like to match
 pub struct ModuleMatcher {
+    /// The name of the module you want to match
     pub name: String,
+    /// The semver range that you want to match
     #[tsify(type = "string")]
     pub version_range: Range,
+    /// The path of the file you want to match from the module root
     pub file_path: PathBuf,
 }
 
@@ -59,9 +63,13 @@ impl ModuleMatcher {
     tsify(into_wasm_abi, from_wasm_abi)
 )]
 #[derive(Debug, Clone)]
+/// Configuration for injecting instrumentation code
 pub struct InstrumentationConfig {
+    /// The name of the diagnostics channel to publish to
     pub channel_name: String,
+    /// The module matcher to identify the module and file to instrument
     pub module: ModuleMatcher,
+    /// The function query to identify the function to instrument
     pub function_query: FunctionQuery,
 }
 

src/function_query.rs

@@ -11,6 +11,7 @@ pub(crate) enum FunctionType {
     Method,
 }
 
+/// The kind of function - Sync or returns a promise
 #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Clone)]
@@ -40,6 +41,7 @@ impl FunctionKind {
     derive(serde::Serialize, serde::Deserialize),
     serde(untagged, rename_all_fields = "camelCase")
 )]
+/// Describes which function to instrument
 #[derive(Debug, Clone)]
 pub enum FunctionQuery {
     // The order here matters because this enum is untagged, serde will try

src/wasm.rs

@@ -13,6 +13,7 @@ use wasm_bindgen::prelude::*;
     derive(tsify::Tsify),
     tsify(into_wasm_abi, from_wasm_abi)
 )]
+/// The type of module being passed - ESM, CJS or unknown
 pub enum ModuleType {
     ESM,
     CJS,
@@ -30,11 +31,14 @@ impl From<ModuleType> for IsModule {
 }
 
 #[wasm_bindgen]
+/// The InstrumentationMatcher is responsible for matching specific modules
 pub struct InstrumentationMatcher(Instrumentor);
 
 #[wasm_bindgen]
 impl InstrumentationMatcher {
     #[wasm_bindgen(js_name = "getTransformer")]
+    /// Get a transformer for the given module name, version and file path.
+    /// Returns `undefined` if no matching instrumentations are found.
     pub fn get_transformer(
         &mut self,
         module_name: &str,
@@ -54,11 +58,13 @@ impl InstrumentationMatcher {
 }
 
 #[wasm_bindgen]
+/// The Transformer is responsible for transforming JavaScript code.
 pub struct Transformer(InstrumentationVisitor);
 
 #[wasm_bindgen]
 impl Transformer {
-    /// Transform the given JavaScript code with optional sourcemap support.
+    /// Transform JavaScript code and optionally sourcemap.
+    ///
     /// # Errors
     /// Returns an error if the transformation fails to find injection points.
     #[wasm_bindgen]
@@ -75,6 +81,7 @@ impl Transformer {
     }
 }
 
+/// Create a new instrumentation matcher from an array of instrumentation configs.
 #[wasm_bindgen]
 #[must_use]
 pub fn create(