@checkstack/common 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @checkstack/common
 
+## 0.14.0
+
+### Minor Changes
+
+- 13373ce: Break the publish-time dependency cycle between `@checkstack/backend-api` and `@checkstack/cache-api` / `@checkstack/queue-api`.
+
+  `cache-api` and `queue-api` only ever used `Logger` and `Migration` from `backend-api` as `import type`, yet declared `@checkstack/backend-api` as a runtime dependency. In the monorepo this is harmless (everything resolves via `workspace:*`), but once published, `bun publish` freezes each `workspace:*` into a concrete pin of the _other_ package's then-current version. Because the dependency is mutual, a consumer installing these packages from the registry must resolve `backend-api -> cache-api -> backend-api -> ...` backward through release history until it reaches ancient versions that shipped raw `workspace:*` ranges and a long-removed `@checkstack/cache-api@0.1.0` pin - which fail to resolve. This surfaced as `bun install` errors (and a missing `checkstack-dev` binary) in freshly scaffolded standalone plugins.
+
+  `Logger` and `Migration` now live in `@checkstack/common` (a dependency-free leaf package). `@checkstack/backend-api` re-exports both for backward compatibility, so existing `import type { Logger, Migration } from "@checkstack/backend-api"` call sites are unchanged. `cache-api` and `queue-api` now depend on `@checkstack/common` instead of `@checkstack/backend-api`, removing the cycle.
+
 ## 0.13.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/common",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -20,7 +20,7 @@
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.4"
+    "@checkstack/scripts": "0.4.0"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./types";
+export * from "./logger";
+export * from "./migration";
 export * from "./actor";
 export * from "./pagination";
 export * from "./routes";

package/src/logger.ts

@@ -0,0 +1,46 @@
+/**
+ * Backend logger interface used everywhere in the platform via `RpcContext.logger`
+ * and the various `coreServices.logger` accessors.
+ *
+ * Each method accepts a free-form trailing argument list (`...args: unknown[]`)
+ * so the long-standing varargs callsites - `logger.error("…", err)` where `err`
+ * is an `Error`, or `logger.info("…", value1, value2)` - keep working unchanged.
+ *
+ * For NEW code, prefer the structured-metadata shape:
+ *
+ *   logger.info("did something", { userId, durationMs });
+ *
+ * Winston's `splat` handling treats a single trailing plain object as
+ * structured metadata (merged into the log entry), and an `Error` instance as
+ * a special-cased error (with stack). Either shape lands in the same vararg
+ * slot here, so this signature covers both without overload churn.
+ *
+ * Auto-injected metadata (when the request flows through
+ * `correlationMiddleware`): `{ correlationId, pluginId, userId? }`. Do NOT
+ * include secrets in the structured-metadata object - it is forwarded
+ * verbatim to the log destination.
+ *
+ * Lives in `@checkstack/common` (rather than `@checkstack/backend-api`) so that
+ * low-level packages such as `@checkstack/cache-api` and `@checkstack/queue-api`
+ * can reference it without taking a dependency on `backend-api` - which would
+ * create a publish-time dependency cycle. `@checkstack/backend-api` re-exports
+ * it for backward compatibility.
+ */
+export interface Logger {
+  info(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  /**
+   * Returns a derived logger with the supplied metadata bound to every
+   * subsequent log entry. Used by `correlationMiddleware` to attach
+   * `{ correlationId, pluginId, userId? }`, and available to handlers that
+   * want a tighter scope (e.g. `ctx.logger.child({ jobId })`).
+   *
+   * Optional only to keep minimal test-mock logger objects compatible with
+   * this interface - production loggers (Winston via `core/backend`) always
+   * implement it. Call sites that rely on metadata binding should branch
+   * on presence and fall back to the base logger when it is not available.
+   */
+  child?(meta: Record<string, unknown>): Logger;
+}

package/src/migration.ts

@@ -0,0 +1,21 @@
+/**
+ * Type-safe migration from one data version to another.
+ * Used for backward-compatible schema evolution (see `Versioned` /
+ * `MigrationBuilder` in `@checkstack/backend-api`).
+ *
+ * Lives in `@checkstack/common` (rather than `@checkstack/backend-api`) so that
+ * low-level packages such as `@checkstack/cache-api` and `@checkstack/queue-api`
+ * can reference it without taking a dependency on `backend-api` - which would
+ * create a publish-time dependency cycle. `@checkstack/backend-api` re-exports
+ * it for backward compatibility.
+ */
+export interface Migration<TFrom = unknown, TTo = unknown> {
+  /** Version number migrating from */
+  fromVersion: number;
+  /** Version number migrating to (must be fromVersion + 1) */
+  toVersion: number;
+  /** Human-readable description of what this migration does */
+  description: string;
+  /** Migration function that transforms old data to new format */
+  migrate(data: TFrom): TTo | Promise<TTo>;
+}