Add Typescript definition for node SDK

Author: ptondereau

.npmignore

@@ -1,2 +1,3 @@
 .gitlab
 release.sh
+*.test-d.ts

Makefile

@@ -25,6 +25,14 @@ else
 endif
 .PHONY: test
 
+test-types: npm-install ## Runs type definition tests
+ifdef GITLAB_CI
+	$(ON_NODE_PRUNE) npx tsd
+else
+	$(ON_NODE) npx tsd
+endif
+.PHONY: test-types
+
 eslint: npm-install ## Runs Eslint to report code style issues
 ifdef GITLAB_CI
 	$(ON_NODE_PRUNE) npx eslint src/ tests/

package.json

@@ -7,14 +7,20 @@
   },
   "description": "Blackfire Continuous Profiler continuously collects and uploads profiling data to the Blackfire servers",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "import": "./src/index.js",
       "require": "./src/index.js"
     }
   },
+  "engines": {
+    "node": ">=16.0.0"
+  },
   "scripts": {
-    "test": "jest --no-cache --runInBand --forceExit --detectOpenHandles --coverage"
+    "test": "jest --no-cache --runInBand --forceExit --detectOpenHandles --coverage",
+    "test:types": "tsd"
   },
   "author": "blackfire.io",
   "license": "MIT",
@@ -33,6 +39,7 @@
     "express-fileupload": "^1.4.0",
     "globals": "^15.11.0",
     "jest": "^29.7.0",
-    "pprof-format": "^2.0.7"
+    "pprof-format": "^2.0.7",
+    "tsd": "^0.33.0"
   }
-}
+}

src/index.d.ts

@@ -0,0 +1,22 @@
+export interface BlackfireConfiguration {
+  /** Name of the application. Defaults to 'my-node-app'. */
+  appName?: string;
+  /** Socket to the Blackfire agent. Defaults to platform-specific socket. */
+  agentSocket?: string;
+  /** Blackfire Server ID (should be defined with serverToken). */
+  serverId?: string;
+  /** Blackfire Server Token (should be defined with serverId). */
+  serverToken?: string;
+  /** Labels to add to the profile. */
+  labels?: Record<string, string>;
+  /** Timeout in milliseconds for the upload request. Defaults to 10000. */
+  uploadTimeoutMillis?: number;
+}
+
+export function start(config: BlackfireConfiguration): boolean;
+export function stop(): boolean;
+
+export const defaultConfig: Required<
+  Pick<BlackfireConfiguration, 'appName' | 'agentSocket' | 'uploadTimeoutMillis' | 'labels'>
+> &
+  Pick<BlackfireConfiguration, 'serverId' | 'serverToken'>;

src/index.test-d.ts

@@ -0,0 +1,37 @@
+import { expectType, expectError } from 'tsd';
+import { start, stop, defaultConfig, BlackfireConfiguration } from '.';
+
+// start() accepts a valid configuration and returns boolean
+expectType<boolean>(start({ appName: 'my-app' }));
+
+// start() accepts all configuration options
+expectType<boolean>(start({
+  appName: 'my-app',
+  agentSocket: 'tcp://127.0.0.1:8307',
+  serverId: 'server-id',
+  serverToken: 'server-token',
+  labels: { env: 'production' },
+  uploadTimeoutMillis: 5000,
+}));
+
+// start() accepts empty config (all fields optional)
+expectType<boolean>(start({}));
+
+// stop() returns boolean
+expectType<boolean>(stop());
+
+// defaultConfig has required fields
+expectType<string>(defaultConfig.appName);
+expectType<string>(defaultConfig.agentSocket);
+expectType<number>(defaultConfig.uploadTimeoutMillis);
+
+// defaultConfig.labels is always defined (not optional)
+expectType<Record<string, string>>(defaultConfig.labels);
+
+// start() rejects invalid types
+expectError(start({ appName: 123 }));
+expectError(start({ uploadTimeoutMillis: 'not-a-number' }));
+expectError(start({ labels: 'not-an-object' }));
+
+// start() rejects unknown properties
+expectError(start({ unknownProp: true }));