feat: add default analytics

Author: twlite

packages/cache/src/use-cache.ts

@@ -1,5 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { AsyncFunction, GenericFunction } from 'commandkit';
+import {
+  AsyncFunction,
+  defer,
+  GenericFunction,
+  getCommandKit,
+} from 'commandkit';
+import { AnalyticsEvents } from 'commandkit/analytics';
 import { randomUUID } from 'node:crypto';
 import ms, { type StringValue } from 'ms';
 import { getCacheProvider } from './cache-plugin';
@@ -90,6 +96,7 @@ function useCache<R extends any[], F extends AsyncFunction<R>>(
   }
 
   const memo = (async (...args) => {
+    const analytics = getCommandKit()?.analytics;
     const keyHash = await stableHash({
       fnId: metadata.id,
       buildId: metadata.buildId,
@@ -126,12 +133,28 @@ function useCache<R extends any[], F extends AsyncFunction<R>>(
           storedFn.lastAccess = Date.now();
         }
 
+        const start = performance.now();
         const cached = await provider.get(effectiveKey);
+        const end = performance.now() - start;
+
         if (cached && cached.value != null) {
+          defer(() =>
+            analytics?.track({
+              name: AnalyticsEvents.CACHE_HIT,
+              id: 'commandkit',
+              data: {
+                time: end.toFixed(2),
+                tags: Array.from(storedFn?.tags ?? []),
+              },
+            }),
+          );
+
           return cached.value;
         }
 
+        const rawStart = performance.now();
         const result = await fn(...args);
+        const rawEnd = performance.now() - rawStart;
 
         if (result != null) {
           const ttl = context.params.ttl;
@@ -148,6 +171,21 @@ function useCache<R extends any[], F extends AsyncFunction<R>>(
           });
         }
 
+        defer(() =>
+          analytics?.track({
+            name: AnalyticsEvents.CACHE_MISS,
+            id: 'commandkit',
+            data: {
+              time: rawEnd.toFixed(2),
+              tags: Array.from(
+                context.params.tags.size
+                  ? context.params.tags
+                  : (storedFn?.tags ?? []),
+              ),
+            },
+          }),
+        );
+
         return result;
       },
     );
@@ -232,6 +270,14 @@ export async function revalidateTag(tag: string): Promise<void> {
 
   // Batch delete operations for better performance
   await Promise.all(entries.map((entry) => provider.delete(entry.key)));
+
+  defer(() =>
+    getCommandKit()?.analytics?.track({
+      name: AnalyticsEvents.CACHE_REVALIDATED,
+      id: 'commandkit',
+      data: { tag },
+    }),
+  );
 }
 
 /**

packages/commandkit/analytics.cjs

@@ -1,6 +1,7 @@
 const { getCommandKit } = require('./dist/context/async-context.js');
 const { AnalyticsEngine } = require('./dist/analytics/analytics-engine.js');
 const { noAnalytics } = require('./dist/analytics/utils.js');
+const { AnalyticsEvents } = require('./dist/analytics/constants.js');
 
 function useAnalytics() {
     const commandkit = getCommandKit(true);
@@ -12,6 +13,7 @@ function track(event) {
 }
 
 module.exports = {
+    AnalyticsEvents,
     AnalyticsEngine,
     useAnalytics,
     noAnalytics,

packages/commandkit/analytics.d.ts

@@ -3,6 +3,7 @@ import type { AnalyticsEngine } from './dist/analytics/analytics-engine';
 export * from './dist/analytics/analytics-engine';
 export * from './dist/analytics/analytics-provider';
 export { noAnalytics } from './dist/analytics/utils';
+export { AnalyticsEvents } from './dist/analytics/constants';
 
 export function useAnalytics(): AnalyticsEngine;
 export function track(event: AnalyticsEvent): Promise<void>;

packages/commandkit/src/analytics/constants.ts

@@ -1,3 +1,14 @@
 import { randomUUID } from 'node:crypto';
 
 export const DO_NOT_TRACK_KEY = `COMMANDKIT_ANALYTICS__DO_NOT_TRACK::${randomUUID()}`;
+
+export const AnalyticsEvents = {
+  COMMAND_EXECUTION: 'command_execution',
+  // @commandkit/cache
+  CACHE_HIT: 'cache_hit',
+  CACHE_MISS: 'cache_miss',
+  CACHE_REVALIDATED: 'cache_revalidated',
+} as const;
+
+export type AnalyticsEvent =
+  (typeof AnalyticsEvents)[keyof typeof AnalyticsEvents];

packages/commandkit/src/app/commands/AppCommandRunner.ts

@@ -16,6 +16,7 @@ import {
   useEnvironment,
 } from '../../context/async-context';
 import { CommandKitErrorCodes, isErrorType } from '../../utils/error-codes';
+import { AnalyticsEvents } from '../../analytics/constants';
 
 export class AppCommandRunner {
   public constructor(private handler: AppCommandHandler) {}
@@ -94,12 +95,14 @@ export class AppCommandRunner {
         );
       }
 
+      const analytics = commandkit.analytics;
+
       if (fn) {
         try {
           const _executeCommand = makeContextAwareFunction(
             env,
             async () => {
-              env.registerDeferredFunction((env) => {
+              env.registerDeferredFunction(async (env) => {
                 env.markEnd();
                 const error = env.getExecutionError();
                 const marker = env.getMarker();
@@ -110,12 +113,36 @@ export class AppCommandRunner {
                     `[${marker} - ${time}] Error executing command: ${error.stack || error}`,
                   );
 
+                  await analytics.track({
+                    name: AnalyticsEvents.COMMAND_EXECUTION,
+                    id:
+                      prepared.command?.data?.command?.name ??
+                      prepared.command.command.name,
+                    data: {
+                      error: true,
+                      executionTime: env.getExecutionTime().toFixed(2),
+                      type: executionMode,
+                    },
+                  });
+
                   return;
                 }
 
                 Logger.info(
                   `[${marker} - ${time}] Command executed successfully`,
                 );
+
+                await analytics.track({
+                  name: AnalyticsEvents.COMMAND_EXECUTION,
+                  id:
+                    prepared.command?.data?.command?.name ??
+                    prepared.command.command.name,
+                  data: {
+                    error: false,
+                    executionTime: env.getExecutionTime().toFixed(2),
+                    type: executionMode,
+                  },
+                });
               });
 
               return fn(ctx.clone());

packages/commandkit/src/index.ts

@@ -23,6 +23,7 @@ export {
   debounce,
   stopEvents,
   StopEventPropagationError,
+  defer,
 } from './utils/utilities';
 export type { CommandKitHMREvent } from './utils/dev-hooks';
 export * from './utils/constants';