feat: Adds development tools to simplify the console.log story for non-cloud implementations

Author: thecodedrift

.changeset/clever-monkeys-dream.md

@@ -0,0 +1,5 @@
+---
+"@taskless/loader": patch
+---
+
+Creates the packcheck utility for validating Lua scripting packs. This makes it possible to check your own Taskless packs without having to upload them to the Taskless server. The packcheck commands takes a pack or config (in yaml), and stands up a mock service worker to emulate the full Taskless lifecycle. It then returns the response as a consolidated JSON object you can assert on.

examples/programatic.ts

@@ -37,7 +37,7 @@ rules:
         taskless.capture("status", response.getStatus())
 `;
 
-const t = await taskless(process.env.TASKLESS_API_KEY);
+const t = taskless(process.env.TASKLESS_API_KEY);
 t.add(pack);
 await t.load();
 

package.json

@@ -11,6 +11,7 @@
     "codegen": "tsx scripts/generate.ts",
     "husky": "husky",
     "lint-staged": "lint-staged",
+    "packcheck": "tsx scripts/packcheck.ts",
     "prepare": "husky",
     "prettier": "prettier",
     "syncpack": "syncpack",
@@ -29,6 +30,11 @@
       "types": "./dist/core.d.ts",
       "import": "./dist/core.js",
       "require": "./dist/core.cjs"
+    },
+    "./dev/packcheck": {
+      "types": "./dist/dev/packcheck.d.ts",
+      "import": "./dist/dev/packcheck.js",
+      "require": "./dist/dev/packcheck.cjs"
     }
   },
   "files": [

src/dev/packcheck.ts

@@ -0,0 +1,71 @@
+/* eslint-disable n/no-process-env */
+import process from "node:process";
+import { type ConsolePayload, taskless } from "@~/core.js";
+import { http } from "msw";
+import { setupServer } from "msw/node";
+
+type Fixture = {
+  request: Request;
+  response: Response;
+};
+
+/**
+ * Packcheck - simple tool for checking your Taskless packs, easily integrated
+ * with your existing unit testing framework
+ */
+export async function packcheck(configOrPack: string, fixture: Fixture) {
+  if (process.env.NODE_ENV === "production") {
+    throw new Error(
+      "Taskless `dev` actions cannot be used in production node environments"
+    );
+  }
+
+  const msw = setupServer(
+    http.all("*", async (info) => {
+      fixture.response.clone();
+    })
+  );
+  msw.listen();
+
+  const logs: ConsolePayload[] = [];
+
+  const t = taskless(undefined, {
+    network: false,
+    logging: true,
+    flushInterval: 0,
+    logLevel: "error",
+    __experimental: {
+      msw,
+    },
+    log: {
+      data(message) {
+        logs.push(JSON.parse(message) as ConsolePayload);
+      },
+    },
+  });
+
+  t.add(configOrPack);
+  await t.load();
+
+  await fetch(fixture.request);
+  await t.flush();
+
+  msw.close();
+
+  // merge any logs that share a request id into a single output
+  const grouped = new Map<string, ConsolePayload>();
+
+  for (const log of logs) {
+    if (grouped.has(log.requestId)) {
+      const existingLog = grouped.get(log.requestId)!;
+      existingLog.sequenceIds.push(...log.sequenceIds);
+      existingLog.dimensions.push(...log.dimensions);
+      grouped.set(log.requestId, existingLog);
+    } else {
+      grouped.set(log.requestId, { ...log });
+    }
+  }
+
+  const result = Array.from(grouped.values())[0] ?? {};
+  return result;
+}

src/lib/taskless.ts

@@ -11,12 +11,14 @@ import {
   type Pack,
   type InitOptions,
   type NetworkPayload,
-  type ConsolePayload,
   type CaptureCallback,
   type CaptureItem,
   type TasklessAPI,
   type Logger,
   type Config,
+  isConfig,
+  isPack,
+  type ConsolePayload,
 } from "@~/types.js";
 import { createClient, type NormalizeOAS } from "fets";
 import yaml from "js-yaml";
@@ -193,15 +195,28 @@ export const taskless = (
 
   /** Sends a set of entries to the registered logging function */
   const logEntries = (entries: CaptureItem[]) => {
+    // group all entries by their request id
+    const grouped = new Map<string, ConsolePayload>();
+
+    // convert entries to the grouped structure
     for (const entry of entries) {
-      logger.data(
-        JSON.stringify({
-          req: entry.requestId,
-          seq: entry.sequenceId,
-          dim: entry.dimension,
-          val: entry.value,
-        } satisfies ConsolePayload)
-      );
+      const group = grouped.get(entry.requestId) ?? {
+        requestId: entry.requestId,
+        sequenceIds: [],
+        dimensions: [],
+      };
+
+      group.sequenceIds.push(entry.sequenceId);
+      group.dimensions.push({
+        name: entry.dimension,
+        value: entry.value,
+      });
+
+      grouped.set(entry.requestId, group);
+    }
+
+    for (const [_id, line] of grouped.entries()) {
+      logger.data(JSON.stringify(line));
     }
   };
 
@@ -425,14 +440,26 @@ export const taskless = (
   }
 
   const api = {
-    /** add additional local packs programatically */
-    add(pack: string) {
+    /** add additional local packs programatically, or an entire configuration */
+    add(packOrConfig: string) {
       if (initialized) {
         throw new Error("A pack was added after Taskless was initialized");
       }
 
-      const data = typeof pack === "string" ? (yaml.load(pack) as Pack) : pack;
-      packs.push(data);
+      const data =
+        typeof packOrConfig === "string"
+          ? yaml.load(packOrConfig)
+          : packOrConfig;
+
+      const loadedConfig: Config = isConfig(data)
+        ? data
+        : {
+            schema: 1,
+            organizationId: "none",
+            packs: [...(isPack(data) ? [data] : [])],
+          };
+
+      packs.push(...loadedConfig.packs);
     },
 
     /** get the current logger */

src/types.ts

@@ -86,21 +86,58 @@ export type HookName = keyof NonNullable<Pack["hooks"]>;
 /** Pack sends collection */
 export type Permissions = Pack["permissions"];
 
+export function isConfig(value?: unknown): value is Config {
+  if (!value || typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const check = value as Config;
+
+  if (
+    check.organizationId !== undefined &&
+    Array.isArray(check.packs) &&
+    check.schema !== undefined
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export function isPack(value?: unknown): value is Pack {
+  if (!value || typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const check = value as Pack;
+
+  if (
+    check.name !== undefined &&
+    check.schema !== undefined &&
+    check.version !== undefined
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
 /** Network payload intended for Taskless */
 export type NetworkPayload = NonNullable<
   OASInput<NormalizeOAS<typeof openapi>, "/{version}/events", "post", "json">
 >;
 
 /** Console payload intended for stdout */
 export type ConsolePayload = {
-  /** The request ID */
-  req: string;
-  /** The sequenceID */
-  seq: string;
-  /** The dimension name */
-  dim: string;
-  /** The dimension's value */
-  val: string;
+  /** The request ID. Can be used on the backend to merge related logs from a request */
+  requestId: string;
+  /** The sequenceIDs connected to this log entry */
+  sequenceIds: string[];
+  /** The dimension name & value that are recorded */
+  dimensions: Array<{
+    name: string;
+    value: string;
+  }>;
 };
 
 /** The object generated during a telemetry capture */

test/env.spec.ts

@@ -2,7 +2,9 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execa } from "execa";
 import { vi, test as vitest, afterEach, describe, beforeAll } from "vitest";
+import { packcheck } from "../dist/dev/packcheck.js";
 import { taskless } from "../src/core.js";
+import sampleYaml from "./fixtures/sample.yaml?raw";
 import { defaultConfig, withHono } from "./helpers/server.js";
 
 const test = withHono(vitest);