actor-qc

Quality-check telemetry helpers for Apify actors.

A tiny set of helpers that record whether a data-quality expectation held, then get out of the way. Each helper emits a single structured log line (through Crawlee's log) and returns, narrows, or throws — so it drops inline into scraping code without changing its shape.

Install

npm install actor-qc

@crawlee/core is a peer dependency (already present in Crawlee/Apify actors):

npm install @crawlee/core

Log line format

qc:<verb>:<key>   { ...ctx, key, verb }

• verb — which helper fired (check | guard | assert | gate).
• key — a caller-supplied label, normalized to [a-z0-9-].
• ctx — optional caller fields, merged first so they can never overwrite the canonical key/verb fields.

Lines are meant to be split on : and aggregated downstream, where volume and timeline per qc:<verb>:<key> answer "how often does this check fail?" or "is this branch still reached?".

Helpers

| Helper | Level | Control flow | Narrows types | | -------- | --------- | ----------------- | ------------- | | check | warning | returns boolean | no | | guard | warning | returns boolean | yes (guard) | | assert | error | throws on failure | yes (asserts) | | gate | info | none (fire & log) | n/a |

import { assert, check, gate, guard } from "actor-qc";

// keep going, but record the miss
if (!check(items.length > 0, "items-found", { url })) return;

// apply a predicate and narrow on success
if (guard((p): p is number => p != null, price, "has-price")) {
  price.toFixed(2);
}

// fail fast when continuing is pointless
assert(response.ok, "http-ok", { status: response.status });

// breadcrumb: how often do we hit the slow path?
gate("html-fallback", { url });

Telemetry is best-effort and never breaks a run — the only helper that throws is assert, and it does so by design after logging.

License

ISC