taist 0.2.17 → 0.2.18

package/instrument.js

@@ -92,6 +92,45 @@ export async function flushTraces() {
   }
 }
 
+/**
+ * Gracefully shutdown taist - call this before process exit.
+ * Waits for pending socket writes to complete and flushes remaining traces.
+ *
+ * This is the recommended way to ensure all traces are captured when integrating
+ * with applications that have their own shutdown hooks (e.g., Directus onShutdown).
+ *
+ * @param {number} timeoutMs - Maximum time to wait for pending writes (default: 2000ms)
+ * @returns {Promise<void>}
+ *
+ * @example
+ * // Directus integration
+ * import { gracefulShutdown } from 'taist/instrument';
+ *
+ * export default defineHook(({ onShutdown }) => {
+ *   onShutdown(async () => {
+ *     await gracefulShutdown();
+ *   });
+ * });
+ */
+export async function gracefulShutdown(timeoutMs = 2000) {
+  if (!reporter) return;
+
+  // Prevent SIGTERM handler from doing redundant work
+  if (reporter.shuttingDown || reporter.closed) return;
+  reporter.shuttingDown = true;
+
+  // 1. Wait for pending writes to complete
+  if (reporter._waitForPendingWrites) {
+    await reporter._waitForPendingWrites(timeoutMs);
+  }
+
+  // 2. Final flush of any buffered traces
+  await reporter.flush();
+
+  // 3. Close socket cleanly
+  reporter.close();
+}
+
 // Log initialization
 if (tracer.options.enabled) {
   logger.log('Instrumentation enabled');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taist",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Token-Optimized Testing Framework for AI-Assisted Development",
   "main": "index.js",
   "type": "module",

package/types/instrument.d.ts

@@ -111,6 +111,28 @@ export declare const reporter: TraceReporter;
  */
 export declare function flushTraces(): Promise<void>;
 
+/**
+ * Gracefully shutdown taist - call this before process exit.
+ * Waits for pending socket writes to complete and flushes remaining traces.
+ *
+ * This is the recommended way to ensure all traces are captured when integrating
+ * with applications that have their own shutdown hooks (e.g., Directus onShutdown).
+ *
+ * @param timeoutMs Maximum time to wait for pending writes (default: 2000ms)
+ * @returns Promise that resolves when shutdown is complete
+ *
+ * @example
+ * // Directus integration
+ * import { gracefulShutdown } from 'taist/instrument';
+ *
+ * export default defineHook(({ onShutdown }) => {
+ *   onShutdown(async () => {
+ *     await gracefulShutdown();
+ *   });
+ * });
+ */
+export declare function gracefulShutdown(timeoutMs?: number): Promise<void>;
+
 /**
  * Auto-instrument a module's exports
  * @param moduleExports Module exports object