@knime/hub-features 1.26.2 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @knime/hub-features
 
+## 1.27.0
+
+### Minor Changes
+
+- 3a49573: Rework API for analytic events and the underlying schema
+
 ## 1.26.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/hub-features",
-  "version": "1.26.2",
+  "version": "1.27.0",
   "description": "Vue components & composables for shared hub features",
   "repository": {
     "type": "git",
@@ -62,6 +62,8 @@
   "scripts": {
     "type-check": "vue-tsc --noEmit -p tsconfig.vitest.json --composite false",
     "test:unit": "TZ='Europe/Berlin' vitest",
-    "generate-analytics-events": "json2ts ./src/analytics/schema/schema.json > ./src/analytics/schema/schema.d.ts"
+    "generate-analytics-events": "pnpm generate-event-types && pnpm generate-event-functions",
+    "generate-event-types": "json2ts ./src/analytics/schema/schema.json > ./src/analytics/schema/schema.d.ts",
+    "generate-event-functions": "node ./src/analytics/schema/code-generator.js"
   }
 }

package/src/analytics/README.md

@@ -2,86 +2,32 @@
 
 ## Preface
 
-This package provides helpers related to analytics events. It provides 2 main behaviors:
-
-- Provides a builder function that creates and normalizes event payloads
-- Provides a sender function that forwards a given event payload to a third party API.
-  The implementation of the third-party API is up to the consumer as long as it satisfies the adapter contract
-
-The main reason why these behaviors are split are for increased flexibility and to also enable this feature being used on a setup where the creation of the event is separated to the sending of the event. Like for example, on host/guest application combination where there's an iframe communication layer between both apps.
+This package provides functions that can produce analytics events.
 
 ## Usage examples
 
-### Building event payloads
-
-As stated above, some applications might only care (or have the correct setup) to construct events based on different code paths and user interactions.
+This package makes no assumption of how the events are sent. Therefore, one must supply a "sender" as
+part of the initialization.
 
 ```ts
 import { analyticsEvents } from "@knime/hub-features/analytics";
 
-// Create a small factory bound to your context
-const { newEvent } = analyticsEvents.eventBuilder({ jobId: "job-123" });
-
-// Build an event. Event ids are strongly-typed, combining their special format
-// and validating payloads, if required
-const event = newEvent({ id: "kai_prompted::kaiqa_button_prompt" });
-
-// once you have this event object, the application can decide what to do with it.
-// Whether that is sending it through an iframe as a message or some other event bus. OR sending it directly if it's so desired (see Sending events section)
-```
-
-### Keeping types in-sync
-
-Due to the strict-type setup and the shape of the API of this package, reusing the type signature
-of the function that creates the events can be tricky. However, this is helpful, for example, if you want to
-wrap the create function with some other behavior of your own but keep the strong-type guarantees.
-Below you can see an example for this use-case:
-
-```ts
-import {
-  analyticsEvents,
-  type CreateEventFn,
-} from "@knime/hub-features/analytics";
-
-const myCustomFunction: CreateEventFn = (...args) => {
-  const { newEvent } = analyticsEvents.eventBuilder(TheNeededContext);
-
-  // do something before
-
-  const event = newEvent(...args);
-
-  // do something with event
+// Create a sender, which can be pretty much any object that provides a `send` function
+const mySender = {
+  send: ({ event }) => {
+    // do something with event (e.g send over WS, dispatch to an iframe's parent, etc)
+  },
 };
-```
-
-In this case, the type signature of `myCustomFunction` will match the one of `newEvent`, just like
-in the previous example.
-
-### Sending events
-
-As stated in the preface, to send events, you need to provide an adapter
-
-```ts
-import {
-  analyticsEvents,
-  type AnalyticsAdapter,
-} from "@knime/hub-features/analytics";
-
-const myAdapter: AnalyticsAdapter = {
-  sendEvent({ event, metadata, idParser }) {
-    console.log("Parsed id", idParser(event.id));
-    console.log("Metadata", metadata);
-    console.log("Event", event)
-  }
-}
-
-// create the sender
-const sender = analyticsEvents.eventSender(myAdapter);
-
-// some event
-const { newEvent } = analyticsEvents.eventBuilder(TheNeededContext);
-const event = newEvent(...);
 
-// then...
-sender.send(event);
+// Initialize the tracker
+type SomeContext = { myContextField: string };
+const eventTracker = analyticsEvents.init<SomeContext>({
+  context: { myContextField: "foo-123" },
+  sender: mySender,
+});
+
+// Track an event. `someEvent` here is a placeholder name. In reality, the API will provide named functions that
+// strongly-typed and may or may not require payload depending on the event's definition. Under the hood this will
+// use the configured sender to forward your event
+eventTracker.someEvent();
 ```

package/src/analytics/analytics.ts

@@ -1,76 +1,90 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as functions from "./schema/event-functions";
 import type {
-  AnalyticsAdapter,
-  AnalyticsPayload,
-  Context,
-  CreateEventFn,
+  AnalyticsEvent,
+  AnalyticsEventSender,
+  DefaultContext,
   Metadata,
 } from "./types";
-import { eventID } from "./utils/eventIds";
-import { toSnakeCaseDeep } from "./utils/toSnakeCaseDeep";
 
 const METADATA: Metadata = Object.freeze({
-  version: "v1.0",
+  version: "v2.0",
 });
 
+/**
+ * Unwraps the inner function imported from the generated functions.
+ * With this supply the context here and just expose the inner function
+ * but also ensure we keep the same names and type constraints
+ */
+type UnwrapFunction<T> = T extends (ctx: DefaultContext) => infer R
+  ? R extends (...args: infer P) => infer Q
+    ? (...args: P) => Q
+    : never
+  : never;
+
+type FunctionMap = typeof functions;
+type Names = keyof FunctionMap;
+type BuilderFunctions = {
+  [K in Names]: UnwrapFunction<(typeof functions)[K]>;
+};
+
+type SenderFunctions = {
+  [K in Names]: (...args: Parameters<BuilderFunctions[K]>) => void;
+};
+
+/**
+ * This function creates an event builder, which lets you construct correct and strongly-typed
+ * event payloads according to the current schema used by this package
+ * @param context
+ * @returns
+ */
+function eventBuilder<T extends DefaultContext>(context: T) {
+  const unwrapped = Object.fromEntries(
+    Object.entries(functions).map(([name, fn]) => [name, fn(context)]),
+  ) as BuilderFunctions;
+
+  return { ...unwrapped };
+}
+
 export const analyticsEvents = Object.freeze({
   METADATA,
   /**
-   * This function creates an event builder, which lets you construct correct and strongly-typed
-   * event payloads according to the current schema used by this package
-   * @param context
-   * @returns
+   * Initialize the analytic event tracker
    */
-  eventBuilder: (context: Context) => {
-    const newEvent: CreateEventFn<AnalyticsPayload> = ({
-      id: eventId,
-      payload: eventData,
-    }) => {
-      // runtime check just in case - shouldn't be needed due to TS
-      if (!eventID(eventId).isValid()) {
-        throw new Error(`Implementation error: Invalid event id: ${eventId}`);
-      }
+  init: <T extends DefaultContext>(params: {
+    /**
+     * Context for the initialized tracker. This will remain unchanged throughout the lifecycle
+     * of this tracker
+     */
+    context: T;
+    /**
+     * Sender interface; will be used to determine how to handle each event when its
+     * corresponding track function is invoked
+     */
+    sender: AnalyticsEventSender;
+  }) => {
+    const builder = eventBuilder(params.context);
 
-      const uniqueEventId = crypto.randomUUID();
+    type AnyFn = (...args: any[]) => any;
 
-      const data = (() => {
-        if (!eventData) {
-          return undefined;
-        }
+    const wrapper: SenderFunctions = {} as SenderFunctions;
 
-        return toSnakeCaseDeep((eventData as unknown) ?? {});
-      })();
+    // keep all the same functions of the builder but wrap around them for extra behavior
+    Object.keys(builder).forEach((fnName) => {
+      const key = fnName as keyof SenderFunctions;
+      wrapper[key] = (...args: any[]) => {
+        // TS issue:
+        // ```A spread argument must either have a tuple type or be passed to a rest parameter.```
+        // This happens because when calling the methods generically, TS tries to join all function signatures
+        // into a union of tuples that contains all possible argument combinations for all of the functions.
+        // This leads to an unresolvable type error
+        // More details on the issue, see: https://github.com/microsoft/TypeScript/issues/49700
+        const event: AnalyticsEvent = (builder[key] as AnyFn)(...args);
 
-      const event = {
-        id: `editor_${eventId}`,
-        data: {
-          ...data,
-          // eslint-disable-next-line camelcase
-          job_id: context.jobId,
-          // eslint-disable-next-line camelcase
-          event_id: uniqueEventId,
-          timestamp: new Date().toISOString(),
-        },
+        params.sender.send({ event, metadata: METADATA });
       };
+    });
 
-      return event;
-    };
-
-    return { newEvent };
-  },
-  /**
-   * This function creates an event sender which will use an internal implementation of an adapter
-   * to forward the event's data to an external third-party provider
-   * @returns
-   */
-  eventSender: (adapter: AnalyticsAdapter) => {
-    const send = (event: AnalyticsPayload) => {
-      adapter.sendEvent({
-        event,
-        idParser: eventID(event.id).parse,
-        metadata: METADATA,
-      });
-    };
-
-    return { send };
+    return wrapper;
   },
 });

package/src/analytics/index.ts

@@ -1,2 +1,2 @@
 export * from "./analytics";
-export type { CreateEventFn, AnalyticsAdapter } from "./types";
+export type { AnalyticsEvent, AnalyticsEventSender } from "./types";

package/src/analytics/schema/code-generator.js

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const schemaPath = path.join(__dirname, "schema.json");
+const outputPath = path.join(__dirname, "event-functions.ts");
+
+const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+const events = schema.properties.events.properties;
+
+const TYPE_HELPERS = {
+  analyticsEvent: "AnalyticsEvent",
+  defaultContext: "DefaultContext",
+  fnParams: "EventFunctionArgs",
+  generatedStaticFields: "GeneratedStaticFields",
+  schemaStaticFields: "SchemaStaticFields",
+};
+
+const HEADER_LINES = [
+  "/* eslint-disable max-lines */",
+  "/* eslint-disable camelcase */",
+  "/* eslint-disable @typescript-eslint/no-explicit-any */",
+  "// AUTO-GENERATED FILE. DO NOT EDIT.",
+  `import type { ${Object.values(TYPE_HELPERS).join(", ")} } from "../types";`,
+  'import { toSnakeCaseDeep } from "../utils/toSnakeCaseDeep";',
+];
+const result = [];
+
+/**
+ * Generic event definition, read from the schema.json.
+ * @typedef {{
+ * 	properties: {
+ * 		data: { $ref?: string };
+ * 		[key: string]: any;
+ *  };
+ *  $comment?: string;
+ * }} EventDefinition
+ */
+
+/**
+ * Generate the JSDoc string for the generated event function, if it has a `$comment` field
+ * in the schema
+ * @param {EventDefinition} eventDef
+ * @returns {String}
+ */
+const generateJSDocComment = (eventDef) => {
+  // eslint-disable-next-line no-useless-concat
+  const jsdoc = "/**\n" + ` * ${eventDef.$comment}\n` + " */";
+  return jsdoc;
+};
+
+/**
+ * Resolves the const value from a property, handling both direct `const` and
+ * `allOf`-based patterns like `{ allOf: [{ $ref: "..." }, { const: "value" }] }`
+ * @param {{ const?: any; allOf?: Array<{ const?: any }> }} prop
+ * @returns {any | undefined}
+ */
+const resolveConst = (prop) => {
+  if (prop.const !== undefined) {
+    return prop.const;
+  }
+  if (Array.isArray(prop.allOf)) {
+    return prop.allOf.find((s) => s.const !== undefined)?.const;
+  }
+  return undefined;
+};
+
+/**
+ * Generates an event function for an event based on its name and definition
+ * @param {String} fnName
+ * @param {EventDefinition} eventDef
+ * @param {Boolean} isPayloadRequired whether the function requires a data payload
+ * @returns {String} function as a string to be added to the generated file
+ */
+const generateEventFunction = (fnName, eventDef, isPayloadRequired = true) => {
+  const params = isPayloadRequired
+    ? `eventData: ${TYPE_HELPERS.fnParams}<"${fnName}">`
+    : "";
+
+  let fn =
+    // function header
+    `export const ${fnName} = <T extends ${TYPE_HELPERS.defaultContext}>(ctx: T) => (${params}): ${TYPE_HELPERS.analyticsEvent} => {\n` +
+    // open object for static data and add properties that are static but generated at runtime
+    "  const staticData = {\n" +
+    "    ...toSnakeCaseDeep(ctx),\n" +
+    "    unique_event_id: crypto.randomUUID(),\n" +
+    "    timestamp: new Date().toISOString(),\n";
+
+  for (const [key, prop] of Object.entries(eventDef.properties)) {
+    // add properties that are static and whose values come from the schema
+    const constValue = resolveConst(prop);
+    if (constValue !== undefined) {
+      fn += `    ${key}: "${constValue}",\n`;
+    } else if (prop.type === "object" && prop.properties) {
+      // nested object (e.g. action): emit only sub-properties that have const values
+      fn += `    ${key}: {\n`;
+      for (const [subKey, subProp] of Object.entries(prop.properties)) {
+        const subConstValue = resolveConst(subProp);
+        if (subConstValue !== undefined) {
+          fn += `      ${subKey}: "${subConstValue}",\n`;
+        }
+      }
+      fn += "    },\n";
+    }
+  }
+
+  // close object for staticData
+  fn += `  } satisfies ${TYPE_HELPERS.schemaStaticFields} & ${TYPE_HELPERS.generatedStaticFields};\n\n`;
+
+  const payload = isPayloadRequired
+    ? "{ ...staticData, payload: { ...toSnakeCaseDeep(eventData as Record<string, any>) } }"
+    : "{ ...staticData }";
+
+  fn += `  const event = { id: staticData.event_name, data: ${payload} };\n\n`;
+  fn += "  return event;\n";
+  fn += "};\n\n";
+
+  return fn;
+};
+
+/**
+ * Checks whether the given event definition has an empty payload or requires data
+ * @param {EventDefinition} eventDef
+ * @returns
+ */
+const hasEmptyPayload = (eventDef) => {
+  return Boolean(eventDef.properties.payload?.$ref?.includes("EmptyPayload"));
+};
+
+for (const [fnName, eventDef] of Object.entries(events)) {
+  const isPayloadRequired = !hasEmptyPayload(eventDef);
+  let fn = generateEventFunction(fnName, eventDef, isPayloadRequired);
+
+  if (eventDef.$comment) {
+    const jsdoc = generateJSDocComment(eventDef);
+    fn = `${jsdoc}\n${fn}`;
+  }
+
+  result.push(fn);
+}
+
+const fileContent = `${HEADER_LINES.join("\n")}\n\n${result.join("")}`;
+
+fs.writeFileSync(outputPath, fileContent, "utf8");
+// eslint-disable-next-line no-console
+console.log("Generated static data based on the Events JSON Schema.");