@lessonkit/core 0.9.1 → 0.9.3

package/dist/index.cjs

@@ -219,14 +219,14 @@ function createTrackingClient(opts) {
   const buffer = [];
   let flushInFlight = null;
   let disposed = false;
+  let disposing = false;
   let intervalId;
-  const flush = () => {
-    if (disposed || flushInFlight) return;
-    if (!buffer.length) return;
+  const runFlush = () => {
+    if (!buffer.length) return Promise.resolve();
     const events = buffer.splice(0, buffer.length);
     let sent = 0;
     let succeeded = false;
-    flushInFlight = Promise.resolve().then(async () => {
+    return Promise.resolve().then(async () => {
       if (batchSink) {
         await batchSink(events);
       } else {
@@ -238,28 +238,47 @@ function createTrackingClient(opts) {
       succeeded = true;
     }).catch(() => {
       buffer.unshift(...events.slice(sent));
-    }).finally(() => {
+    }).then(() => {
+      if (succeeded && buffer.length > 0 && !disposed) {
+        return runFlush();
+      }
+    });
+  };
+  const flush = () => {
+    if (disposed) return Promise.resolve();
+    if (flushInFlight) return flushInFlight;
+    if (!buffer.length) return Promise.resolve();
+    flushInFlight = runFlush().finally(() => {
       flushInFlight = null;
-      if (succeeded && !disposed && buffer.length > 0) flush();
     });
+    return flushInFlight;
   };
-  intervalId = flushIntervalMs > 0 ? globalThis.setInterval(flush, flushIntervalMs) : void 0;
+  const drainAll = async () => {
+    await flush();
+    while (buffer.length > 0) {
+      await flush();
+    }
+  };
+  intervalId = flushIntervalMs > 0 ? globalThis.setInterval(() => void flush(), flushIntervalMs) : void 0;
   intervalId?.unref?.();
   return {
     track: (event) => {
-      if (disposed) return;
+      if (disposed || disposing) return;
       buffer.push(event);
-      if (buffer.length >= maxBatchSize) flush();
+      if (buffer.length >= maxBatchSize) void flush();
     },
     flush,
     dispose: () => {
-      if (disposed) return;
+      if (disposed || disposing) return Promise.resolve();
+      disposing = true;
       if (intervalId !== void 0) {
         globalThis.clearInterval(intervalId);
         intervalId = void 0;
       }
-      flush();
-      disposed = true;
+      return drainAll().finally(() => {
+        disposed = true;
+        disposing = false;
+      });
     }
   };
 }
@@ -317,11 +336,32 @@ function createPluginHost(plugins = []) {
     }
     return filtered;
   };
-  const composeTrackingSink = (sink, ctx) => {
+  const deliverTelemetryBatch = (events, ctx) => {
+    for (const plugin of list) {
+      plugin.onTelemetryBatch?.(events, ctx);
+    }
+    return events;
+  };
+  const composeTrackingSink = (sink, ctxSource) => {
+    if (!sink) return void 0;
+    const resolveCtx = () => typeof ctxSource === "function" ? ctxSource() : ctxSource;
+    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}`;
+    const layers = [];
     let composed = sink;
     for (const plugin of list) {
-      if (!plugin.wrapTrackingSink || !composed) continue;
-      composed = plugin.wrapTrackingSink(composed, ctx);
+      if (!plugin.wrapTrackingSink) continue;
+      const inner = composed;
+      const layer = { plugin, inner, wrapped: null, lastCtxKey: "" };
+      layers.push(layer);
+      composed = (event) => {
+        const ctx = resolveCtx();
+        const key = ctxKey(ctx);
+        if (!layer.wrapped || layer.lastCtxKey !== key) {
+          layer.wrapped = layer.plugin.wrapTrackingSink(layer.inner, ctx) ?? layer.inner;
+          layer.lastCtxKey = key;
+        }
+        return layer.wrapped(event);
+      };
     }
     return composed;
   };
@@ -339,6 +379,7 @@ function createPluginHost(plugins = []) {
     disposeAll,
     runTelemetry,
     runTelemetryBatch,
+    deliverTelemetryBatch,
     composeTrackingSink,
     scoreAssessment
   };

package/dist/index.d.cts

@@ -113,8 +113,8 @@ type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
     track: (event: TelemetryEvent) => void;
-    flush?: () => void;
-    dispose?: () => void;
+    flush?: () => void | Promise<void>;
+    dispose?: () => void | Promise<void>;
 };
 
 declare const telemetryCatalogVersion: 1;
@@ -198,7 +198,9 @@ type PluginHost = {
     disposeAll: () => void;
     runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
     runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext) => TelemetrySink | undefined;
+    /** Invoke only `onTelemetryBatch` hooks; events were already filtered at emit time. */
+    deliverTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
+    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext | (() => LessonkitPluginContext)) => TelemetrySink | undefined;
     scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
 };
 declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;

package/dist/index.d.ts

@@ -113,8 +113,8 @@ type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
     track: (event: TelemetryEvent) => void;
-    flush?: () => void;
-    dispose?: () => void;
+    flush?: () => void | Promise<void>;
+    dispose?: () => void | Promise<void>;
 };
 
 declare const telemetryCatalogVersion: 1;
@@ -198,7 +198,9 @@ type PluginHost = {
     disposeAll: () => void;
     runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
     runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext) => TelemetrySink | undefined;
+    /** Invoke only `onTelemetryBatch` hooks; events were already filtered at emit time. */
+    deliverTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
+    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext | (() => LessonkitPluginContext)) => TelemetrySink | undefined;
     scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
 };
 declare function defineLessonkitPlugin(plugin: LessonkitPlugin): LessonkitPlugin;

package/dist/index.js

@@ -179,14 +179,14 @@ function createTrackingClient(opts) {
   const buffer = [];
   let flushInFlight = null;
   let disposed = false;
+  let disposing = false;
   let intervalId;
-  const flush = () => {
-    if (disposed || flushInFlight) return;
-    if (!buffer.length) return;
+  const runFlush = () => {
+    if (!buffer.length) return Promise.resolve();
     const events = buffer.splice(0, buffer.length);
     let sent = 0;
     let succeeded = false;
-    flushInFlight = Promise.resolve().then(async () => {
+    return Promise.resolve().then(async () => {
       if (batchSink) {
         await batchSink(events);
       } else {
@@ -198,28 +198,47 @@ function createTrackingClient(opts) {
       succeeded = true;
     }).catch(() => {
       buffer.unshift(...events.slice(sent));
-    }).finally(() => {
+    }).then(() => {
+      if (succeeded && buffer.length > 0 && !disposed) {
+        return runFlush();
+      }
+    });
+  };
+  const flush = () => {
+    if (disposed) return Promise.resolve();
+    if (flushInFlight) return flushInFlight;
+    if (!buffer.length) return Promise.resolve();
+    flushInFlight = runFlush().finally(() => {
       flushInFlight = null;
-      if (succeeded && !disposed && buffer.length > 0) flush();
     });
+    return flushInFlight;
   };
-  intervalId = flushIntervalMs > 0 ? globalThis.setInterval(flush, flushIntervalMs) : void 0;
+  const drainAll = async () => {
+    await flush();
+    while (buffer.length > 0) {
+      await flush();
+    }
+  };
+  intervalId = flushIntervalMs > 0 ? globalThis.setInterval(() => void flush(), flushIntervalMs) : void 0;
   intervalId?.unref?.();
   return {
     track: (event) => {
-      if (disposed) return;
+      if (disposed || disposing) return;
       buffer.push(event);
-      if (buffer.length >= maxBatchSize) flush();
+      if (buffer.length >= maxBatchSize) void flush();
     },
     flush,
     dispose: () => {
-      if (disposed) return;
+      if (disposed || disposing) return Promise.resolve();
+      disposing = true;
       if (intervalId !== void 0) {
         globalThis.clearInterval(intervalId);
         intervalId = void 0;
       }
-      flush();
-      disposed = true;
+      return drainAll().finally(() => {
+        disposed = true;
+        disposing = false;
+      });
     }
   };
 }
@@ -277,11 +296,32 @@ function createPluginHost(plugins = []) {
     }
     return filtered;
   };
-  const composeTrackingSink = (sink, ctx) => {
+  const deliverTelemetryBatch = (events, ctx) => {
+    for (const plugin of list) {
+      plugin.onTelemetryBatch?.(events, ctx);
+    }
+    return events;
+  };
+  const composeTrackingSink = (sink, ctxSource) => {
+    if (!sink) return void 0;
+    const resolveCtx = () => typeof ctxSource === "function" ? ctxSource() : ctxSource;
+    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}`;
+    const layers = [];
     let composed = sink;
     for (const plugin of list) {
-      if (!plugin.wrapTrackingSink || !composed) continue;
-      composed = plugin.wrapTrackingSink(composed, ctx);
+      if (!plugin.wrapTrackingSink) continue;
+      const inner = composed;
+      const layer = { plugin, inner, wrapped: null, lastCtxKey: "" };
+      layers.push(layer);
+      composed = (event) => {
+        const ctx = resolveCtx();
+        const key = ctxKey(ctx);
+        if (!layer.wrapped || layer.lastCtxKey !== key) {
+          layer.wrapped = layer.plugin.wrapTrackingSink(layer.inner, ctx) ?? layer.inner;
+          layer.lastCtxKey = key;
+        }
+        return layer.wrapped(event);
+      };
     }
     return composed;
   };
@@ -299,6 +339,7 @@ function createPluginHost(plugins = []) {
     disposeAll,
     runTelemetry,
     runTelemetryBatch,
+    deliverTelemetryBatch,
     composeTrackingSink,
     scoreAssessment
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",