feat: add trackTime async helper for timing sync/async functions

README.md

@@ -43,4 +43,30 @@ $ getAbbreviatedResponse({
         ...
    });
 $ endTime('abbr', "getAbbreviatedResponse");
-```
+```
+
+# Usage - trackTime (async helper)
+
+`trackTime` wraps any sync or async function, automatically recording its duration as a Server-Timing metric. It returns the function's result directly.
+
+```typescript
+import { trackTime } from 'lambda-server-timing';
+
+// Time an async database query
+const user = await trackTime('db-query', async () => {
+  return await dynamodb.get({ TableName: 'users', Key: { id } }).promise();
+}, 'Fetch user from DynamoDB');
+
+// Time an external API call
+const data = await trackTime('external-api', async () => {
+  const res = await fetch('https://api.example.com/data');
+  return res.json();
+});
+
+// Also works with sync functions
+const result = trackTime('compute', () => {
+  return heavyComputation(input);
+}, 'Heavy computation');
+```
+
+If the wrapped function throws an error, `trackTime` still records the timing before re-throwing, so you get visibility into failed operations too.

index.d.ts

@@ -21,6 +21,15 @@ export declare const startTime: (name: string, description?: string) => void;
  * @returns TimeObject
  * Records the duration of a metric and sets a metric timing
  */
+/**
+ * @param name - Unique identifier for the metric
+ * @param fn - Async function to time
+ * @param description - Optional human-readable description
+ *
+ * @returns The return value of the provided function
+ * Wraps an async function, automatically recording its duration as a metric
+ */
+export declare const trackTime: <T>(name: string, fn: () => T | Promise<T>, description?: string) => Promise<T>;
 export declare const endTime: (name: string, description?: string) => void | Record<string, unknown>;
 interface TimeObject {
     name: string;