@apm-js-collab/code-transformer 0.7.2 → 0.8.0

package/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
 

package/index.d.ts

@@ -0,0 +1,6 @@
+import type { InstrumentationConfig, InstrumentationMatcher } from './pkg/orchestrion_js';
+/**
+ * Create a new instrumentation matcher from an array of instrumentation configs.
+ */
+export declare function create(configs: InstrumentationConfig[], dc_module?: string | null): InstrumentationMatcher;
+export type { FunctionKind, FunctionQuery, InstrumentationConfig, InstrumentationMatcher, ModuleMatcher, ModuleType, TransformOutput, Transformer, } from './pkg/orchestrion_js';

package/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.create = create;
+// ./pkg/orchestrion_js.js has a side effect of loading the wasm binary. 
+// We only want that if the library is actually used!
+var cachedCreate;
+/**
+ * Create a new instrumentation matcher from an array of instrumentation configs.
+ */
+function create(configs, dc_module) {
+    if (!cachedCreate) {
+        cachedCreate = require('./pkg/orchestrion_js.js').create;
+    }
+    if (cachedCreate === undefined) {
+        throw new Error("Failed to load '@apm-js-collab/code-transformer'");
+    }
+    return cachedCreate(configs, dc_module);
+}

package/package.json

@@ -1,26 +1,30 @@
 {
   "name": "@apm-js-collab/code-transformer",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/apm-js-collab/orchestrion-js.git"
   },
   "files": [
-    "./pkg/orchestrion_js_bg.wasm",
     "./pkg/orchestrion_js.js",
     "./pkg/orchestrion_js.d.ts",
+    "./index.js",
+    "./index.d.ts",
     "LICENSE",
     "NOTICE"
   ],
-  "main": "./pkg/orchestrion_js.js",
-  "types": "./pkg/orchestrion_js.d.ts",
+  "main": "./index.js",
+  "types": "./index.d.ts",
   "scripts": {
-    "build": "wasm-pack build --target nodejs --release -- --features wasm",
+    "build": "wasm-pack build --target nodejs --release -- --features wasm && yarn build:wrapper && yarn build:inline-binary",
+    "build:wrapper": "tsc index.ts --declaration --module commonjs",
+    "build:inline-binary": "node inline-binary.js",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
+    "@types/node": "^18.0.0",
     "source-map": "^0.7.6",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",

package/pkg/orchestrion_js.d.ts

@@ -1,5 +1,8 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * Create a new instrumentation matcher from an array of instrumentation configs.
+ */
 export function create(configs: InstrumentationConfig[], dc_module?: string | null): InstrumentationMatcher;
 /**
  * Output of a transformation operation
@@ -15,34 +18,78 @@ export interface TransformOutput {
     map: string | undefined;
 }
 
+/**
+ * Configuration for injecting instrumentation code
+ */
 export interface InstrumentationConfig {
+    /**
+     * The name of the diagnostics channel to publish to
+     */
     channelName: string;
+    /**
+     * The module matcher to identify the module and file to instrument
+     */
     module: ModuleMatcher;
+    /**
+     * The function query to identify the function to instrument
+     */
     functionQuery: FunctionQuery;
 }
 
+/**
+ * Describes the module and file path you would like to match
+ */
 export interface ModuleMatcher {
+    /**
+     * The name of the module you want to match
+     */
     name: string;
+    /**
+     * The semver range that you want to match
+     */
     versionRange: string;
+    /**
+     * The path of the file you want to match from the module root
+     */
     filePath: string;
 }
 
+/**
+ * Describes which function to instrument
+ */
 export type FunctionQuery = { className: string; methodName: string; kind: FunctionKind; index?: number } | { className: string; index?: number } | { methodName: string; kind: FunctionKind; index?: number } | { functionName: string; kind: FunctionKind; index?: number } | { expressionName: string; kind: FunctionKind; index?: number };
 
+/**
+ * The kind of function - Sync or returns a promise
+ */
 export type FunctionKind = "Sync" | "Async";
 
+/**
+ * The type of module being passed - ESM, CJS or unknown
+ */
 export type ModuleType = "esm" | "cjs" | "unknown";
 
+/**
+ * The InstrumentationMatcher is responsible for matching specific modules
+ */
 export class InstrumentationMatcher {
   private constructor();
   free(): void;
+  /**
+   * Get a transformer for the given module name, version and file path.
+   * Returns `undefined` if no matching instrumentations are found.
+   */
   getTransformer(module_name: string, version: string, file_path: string): Transformer | undefined;
 }
+/**
+ * The Transformer is responsible for transforming JavaScript code.
+ */
 export class Transformer {
   private constructor();
   free(): void;
   /**
-   * 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.
    */