feat(qc-logging): add qc logging and basic type utils

.github/scripts/before-beta-release.js

@@ -35,4 +35,4 @@ function addBetaSuffixToVersion(version) {
         .map((v) => Number(v.match(/\.(\d+)$/)[1]));
     const lastPrereleaseNumber = Math.max(-1, ...prereleaseNumbers);
     return `${version}-beta.${lastPrereleaseNumber + 1}`;
-}
+}

.github/workflows/_update_release_metadata.yaml

@@ -82,4 +82,4 @@ jobs:
               uses: apify/actions/signed-commit@v1.0.0
               with:
                   message: 'chore(release): Update changelog and package version [skip ci]'
-                  github-token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+                  github-token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}

.github/workflows/manual_publish_to_npm.yaml

@@ -50,4 +50,4 @@ jobs:
             - name: Publish
               run: npm publish --provenance --tag ${{ inputs.tag }}
               env:
-                  NODE_AUTH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}
+                  NODE_AUTH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}

.github/workflows/manual_release_stable.yaml

@@ -78,4 +78,4 @@ jobs:
                       {
                           "ref": "${{ needs.release_metadata.outputs.changelog_commitish }}",
                           "tag": "latest"
-                      }
+                      }

.github/workflows/on_master.yaml

@@ -55,4 +55,4 @@ jobs:
                       {
                           "ref": "${{ needs.release_metadata.outputs.changelog_commitish }}",
                           "tag": "beta"
-                      }
+                      }

CHANGELOG.md

@@ -4,5 +4,4 @@ All notable changes to this project will be documented in this file.
 
 ## [0.1.2](https://github.com/apify/apify-actor-utils/releases/tag/v0.1.2) (2026-07-22)
 
-
-## [0.1.1](https://github.com/apify/apify-actor-utils/releases/tag/v0.1.1) (2026-07-22)
+## [0.1.1](https://github.com/apify/apify-actor-utils/releases/tag/v0.1.1) (2026-07-22)

package.json

@@ -16,6 +16,14 @@
         ".": {
             "types": "./dist/index.d.ts",
             "default": "./dist/index.js"
+        },
+        "./qc-logger": {
+            "types": "./dist/src/qc-logger/index.d.ts",
+            "default": "./dist/src/qc-logger/index.js"
+        },
+        "./type-utils": {
+            "types": "./dist/src/type-utils/index.d.ts",
+            "default": "./dist/src/type-utils/index.js"
         }
     },
     "files": [
@@ -59,5 +67,8 @@
         "typescript": "^6.0.3",
         "typescript-eslint": "^8.62.1"
     },
-    "license": "ISC"
+    "license": "ISC",
+    "peerDependencies": {
+        "@apify/log": "^2.5.44"
+    }
 }

src/qc-logger/assert.ts

@@ -0,0 +1,27 @@
+import { type Ctx, emit, formatMessage } from './structured-logger.js';
+
+/**
+ * Glorified assertion that also logs at `error` level. Throws a plain `Error`
+ * by default; pass e.g. Crawlee's `NonRetryableError` or `CriticalError` to
+ * control what the failure means to the crawler.
+ *
+ *
+ * ```ts
+ * const someEnvVar = process.env.SOME_ENV_VAR; // string | undefined
+ * assert(typeof someEnvVar === "string", "some-env-var");
+ * // someEnvVar is now guaranteed to be a `string`, unless the assertion fails.
+ * assert(someEnvVar, "some-env-var");
+ * // someEnvVar is now guaranteed to be a truthy `string` (non-empty), unless the assertion fails.
+ * ```
+ */
+export function assert(
+    cond: unknown,
+    key: string,
+    ctx?: Ctx,
+    ErrorCtor: new (message: string) => Error = Error,
+): asserts cond {
+    if (cond) return;
+    const error = new ErrorCtor(formatMessage('assert', key));
+    emit('error', 'assert', key, { ...ctx, name: error.name, stack: error.stack });
+    throw error;
+}

src/qc-logger/checkpoint.ts

@@ -0,0 +1,45 @@
+import { type Ctx, emit } from './structured-logger.js';
+
+/**
+ * Logs an `info`-level checkpoint marking that a point in the run was reached.
+ * Unlike the `is*` predicates or {@link assert}, this has no condition — it
+ * always emits — so it's meant for tracing progress through a run.
+ *
+ * @param key - Identifies the checkpoint; emitted as `qc:checkpoint:<key>`.
+ * @param ctx - Optional extra fields to attach to the log line.
+ *
+ * @example
+ * ```ts
+ * checkpoint("started");
+ * // logs `qc:checkpoint:started`
+ *
+ * await doWork();
+ * checkpoint("work-done", { itemsProcessed: 42 });
+ * // logs `qc:checkpoint:work-done` with { itemsProcessed: 42 }
+ * ```
+ */
+export function checkpoint(key: string, ctx?: Ctx): void {
+    emit('info', 'checkpoint', key, ctx);
+}
+
+/**
+ * Conditionally logs an `info`-level checkpoint — only when `cond` is truthy.
+ * A convenience wrapper over {@link checkpoint} for guarding a marker behind a
+ * condition without an explicit `if` at the call site.
+ *
+ * @param cond - The condition; the checkpoint is emitted only when it's truthy.
+ * @param key - Identifies the checkpoint; emitted as `qc:checkpoint:<key>`.
+ * @param ctx - Optional extra fields to attach to the log line.
+ *
+ * @example
+ * ```ts
+ * checkpointIf(items.length === 0, "empty-batch");
+ * // logs `qc:checkpoint:empty-batch` only when the batch is empty
+ *
+ * checkpointIf(retries > 3, "many-retries", { retries });
+ * // logs `qc:checkpoint:many-retries` with { retries } only past the threshold
+ * ```
+ */
+export function checkpointIf(cond: unknown, key: string, ctx?: Ctx): void {
+    if (cond) checkpoint(key, ctx);
+}

src/qc-logger/index.ts

@@ -0,0 +1,5 @@
+export { checkpoint, checkpointIf } from './checkpoint.js';
+export { assert } from './assert.js';
+export { isFalsy, isTruthy, isNullish, isDefined } from './is.js';
+export { emit, formatMessage } from './structured-logger.js';
+export type { Ctx } from './structured-logger.js';