@apify/actor-utils 0.1.2 → 0.1.3-beta.1

package/README.md

@@ -17,13 +17,20 @@ await Actor.init();
 const result = await safePushData((batch) => Actor.pushData(batch), items);
 
 console.log(result);
-// { pushed: 2, dropped: [...], attempts: 2 }
+// { pushedCount: 2, droppedItems: [...], attemptCount: 2, pushResult: undefined }
 ```
 
 Accepts a single item or an array. `pushFn` is the first positional arg
 and is required — the library itself never imports the Apify SDK, and a
 CI check forbids `.pushData(` from appearing anywhere in the source.
 
+Whatever `pushFn` resolves to comes back as `pushResult`, so a push
+function with a meaningful return value stays usable:
+
+```ts
+const { pushResult } = await safePushData((batch) => client.dataset(id).pushItems(batch), items);
+```
+
 ## Performance notes
 
 The happy path is a single `try/await pushFn(items)` with **no extra
@@ -38,49 +45,88 @@ every AJV error per item:
 
 | Error                                | Action                                                                             |
 | ------------------------------------ | ---------------------------------------------------------------------------------- |
-| `required` at the root               | Set the missing field to `null` and mark the path as a placeholder.                |
-| `additionalProperties` at the root   | Delete the unknown property.                                                       |
+| `required` (at any depth)            | Set the missing field to `null` and mark the path as a placeholder.                |
+| `additionalProperties` (any depth)   | Delete the unknown property.                                                       |
 | `type` / `format` / etc. at the root | Item itself is the wrong shape → dropped.                                          |
 | Constraint on a **placeholder** path | Replace with a type-aware default (see below). If no default is known → dropped.   |
 | Constraint on **user-supplied** data | Delete the field. If the schema later marks it required, a placeholder takes over. |
+| Nothing on the item was actionable   | Item is dropped — an unchanged item would fail identically on the next push.       |
 
 ### Placeholder defaults
 
 When a constraint fires on a path we placeholder'd ourselves, the wrapper
-picks a value that should satisfy it:
-
-| AJV keyword                                             | Placeholder value               |
-| ------------------------------------------------------- | ------------------------------- |
-| `type: string`                                          | `''`                            |
-| `type: integer` / `number`                              | `0`                             |
-| `type: boolean`                                         | `false`                         |
-| `type: array`                                           | `[]`                            |
-| `type: object`                                          | `{}`                            |
-| `type: null`                                            | `null`                          |
-| `minLength: N` / `maxLength`                            | `'_'.repeat(N)` / `''`          |
-| `minimum: N` / `maximum`                                | `N`                             |
-| `exclusiveMinimum: N` / `exclusiveMaximum`              | `N + 1` / `N - 1`               |
-| `enum`                                                  | First allowed value             |
-| `format: email` / `uri` / `date` / `date-time` / `uuid` | a static valid example for each |
-| Anything else (`pattern`, custom formats…)              | Item is dropped.                |
+picks a value that should satisfy it. We deliberately only fill in the four
+**empty** values below — they're unambiguously empty and can't be mistaken
+for real data:
+
+| AJV keyword    | Placeholder value |
+| -------------- | ----------------- |
+| `type: string` | `''`              |
+| `type: array`  | `[]`              |
+| `type: object` | `{}`              |
+| `type: null`   | `null`            |
+| Anything else  | Item is dropped.  |
+
+When a field allows **multiple types** (e.g. `['string', 'null']`), the
+wrapper always picks `null` — it's the cleanest placeholder because it
+commits to no concrete value at all.
+
+Everything else (`enum`, `format`, `minLength`, numeric bounds, `type:
+integer` / `number` / `boolean`, …) is **not** placeholdered: a made-up
+email, a first-enum-value, or a fabricated number would silently poison the
+customer's dataset with plausible-looking junk, so the item is dropped
+instead.
 
 The retry loop chases one layer of errors per round
-(`required` → `type` → `minLength` → push) until either the push succeeds
+(`required` → `type` → push) until either the push succeeds
 or `maxAttempts` (default 5) is hit.
 
+### When the attempt cap is hit
+
+Items still failing on the last allowed attempt are dropped — but the rest
+of the batch is **not** lost with them. Because a rejected push stores
+nothing at all, the wrapper drops the incurable items and then makes one
+final push with the survivors, which the API already validated in the
+previous round. That final push is counted in `attemptCount`, so a run that
+exhausts `maxAttempts: 5` can report `attemptCount: 6`.
+
+## Logging
+
+Every failed round logs which fields went wrong, so you can fix the schema
+(or the scraper) without digging through the returned `droppedItems`:
+
+```
+safePushData: schema validation failed on attempt 1: 12 invalid item(s); repaired fields: /age (type), /name (required), /tags/[] (type); dropped 2 item(s) on unfixable fields: /email (format); retrying with 10 item(s).
+safePushData: gave up after 5 attempts; dropped 3 item(s) still failing on fields: /sku (pattern); pushing the 9 valid item(s) left.
+```
+
+The field list is a **set**, not a per-item breakdown — one bad field
+usually shows up on many items in a batch, and knowing which item had which
+problem rarely changes what you do about it. Array indices collapse
+(`/tags/0`, `/tags/7` → `/tags/[]`) for the same reason, and the list is
+capped at 20 entries with the rest reported as `(+N more)`.
+
 ## Options
 
-| Option        | Type     | Default | Notes                |
-| ------------- | -------- | ------- | -------------------- |
-| `maxAttempts` | `number` | `5`     | Hard cap on retries. |
+| Option        | Type     | Default | Notes                                                          |
+| ------------- | -------- | ------- | -------------------------------------------------------------- |
+| `maxAttempts` | `number` | `5`     | Cap on repair rounds, plus the final salvage push if it's hit. |
 
 ## Return shape
 
+Names say what they hold: `*Count` is a number, `*Items` is an array of
+objects.
+
 ```ts
-interface SafePushDataResult<T> {
-    pushed: number;
-    dropped: { item: T; errors: ValidationError[] }[];
-    attempts: number;
+interface SafePushDataResult<T, R = unknown> {
+    /** How many of the caller's items made it into the dataset. */
+    pushedCount: number;
+    /** The items we couldn't repair, each with the errors that doomed it. */
+    droppedItems: { item: T; errors: ValidationError[] }[];
+    /** How many times `pushFn` was actually called. */
+    attemptCount: number;
+    /** What the successful `pushFn` call resolved to; absent if none did. */
+    pushResult?: R;
 }
 ```
 

package/dist/src/qc-logger/assert.d.ts

@@ -0,0 +1,17 @@
+import { type Ctx } 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 declare function assert(cond: unknown, key: string, ctx?: Ctx, ErrorCtor?: new (message: string) => Error): asserts cond;
+//# sourceMappingURL=assert.d.ts.map

package/dist/src/qc-logger/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../../src/qc-logger/assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAuB,MAAM,wBAAwB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAClB,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,GAAG,EACT,SAAS,GAAE,KAAK,OAAO,EAAE,MAAM,KAAK,KAAa,GAClD,OAAO,CAAC,IAAI,CAKd"}

package/dist/src/qc-logger/assert.js

@@ -0,0 +1,23 @@
+import { 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, key, ctx, ErrorCtor = Error) {
+    if (cond)
+        return;
+    const error = new ErrorCtor(formatMessage('assert', key));
+    emit('error', 'assert', key, { ...ctx, name: error.name, stack: error.stack });
+    throw error;
+}
+//# sourceMappingURL=assert.js.map

package/dist/src/qc-logger/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../../src/qc-logger/assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,IAAI,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,MAAM,CAClB,IAAa,EACb,GAAW,EACX,GAAS,EACT,YAA4C,KAAK;IAEjD,IAAI,IAAI;QAAE,OAAO;IACjB,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/E,MAAM,KAAK,CAAC;AAChB,CAAC"}

package/dist/src/qc-logger/checkpoint.d.ts

@@ -0,0 +1,40 @@
+import { type Ctx } 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 declare function checkpoint(key: string, ctx?: Ctx): void;
+/**
+ * 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 declare function checkpointIf(cond: unknown, key: string, ctx?: Ctx): void;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/src/qc-logger/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../../src/qc-logger/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAQ,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAEvD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAExE"}

package/dist/src/qc-logger/checkpoint.js

@@ -0,0 +1,45 @@
+import { 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, ctx) {
+    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, key, ctx) {
+    if (cond)
+        checkpoint(key, ctx);
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/src/qc-logger/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../../src/qc-logger/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,GAAS;IAC7C,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,GAAW,EAAE,GAAS;IAC9D,IAAI,IAAI;QAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC"}

package/dist/src/qc-logger/index.d.ts

@@ -0,0 +1,6 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/qc-logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/qc-logger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/src/qc-logger/index.js

@@ -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';
+//# sourceMappingURL=index.js.map

package/dist/src/qc-logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/qc-logger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/src/qc-logger/is.d.ts

@@ -0,0 +1,116 @@
+import type { Defined, Falsy, Nullish, Truthy } from '../type-utils/types.js';
+import { type Ctx } from './structured-logger.js';
+/**
+ * Checks for falsy values and logs a `warning` when they are.
+ *
+ * Sample usage:
+ * ```ts
+ * if (isFalsy(someValue, "my-key-here")) {
+ *     // someValue is falsy, warning gets logged `qc:is:falsy:my-key-here`
+ *     return; // do my early return
+ * }
+ * ```
+ *
+ * The overloads narrow the return type based on what's statically known about
+ * `value`: a {@link Truthy} input returns the literal `false`, a {@link Falsy}
+ * input returns the literal `true`, and only genuinely uncertain values get the
+ * `value is Falsy & T` type guard. This means a redundant call — e.g.
+ * `isFalsy` on something the compiler already knows is truthy — produces a
+ * branch whose condition is a constant.
+ *
+ * Enable the `@typescript-eslint/no-unnecessary-condition` rule to have that
+ * surfaced as a lint error instead of a silent dead branch. The rule ships with
+ * both [typescript-eslint](https://typescript-eslint.io/rules/no-unnecessary-condition/)
+ * and [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-unnecessary-condition.html)
+ * (note: it requires type-aware linting).
+ */
+export declare function isFalsy<T>(value: Truthy<T>, key: string, ctx?: Ctx): false;
+export declare function isFalsy(value: Falsy, key: string, ctx?: Ctx): true;
+export declare function isFalsy<T>(value: T, key: string, ctx?: Ctx): value is Falsy & T;
+/**
+ * Checks for truthy values and logs a `warning` when they are — the
+ * inverse of {@link isFalsy}.
+ *
+ * Sample usage:
+ * ```ts
+ * if (isTruthy(someValue, "my-key-here")) {
+ *     // someValue is truthy, warning gets logged `qc:is:truthy:my-key-here`
+ *     return someValue; // do my early return
+ * }
+ * // fallback behavior here
+ * ```
+ *
+ * Mirroring {@link isFalsy}, the overloads narrow the return type based on what's
+ * statically known about `value`: a {@link Falsy} input returns the literal
+ * `false`, a {@link Truthy} input returns the literal `true`, and only genuinely
+ * uncertain values get the `value is Truthy<T>` type guard. A redundant call —
+ * e.g. `isTruthy` on something the compiler already knows is falsy — produces a
+ * branch whose condition is a constant.
+ *
+ * Enable the `@typescript-eslint/no-unnecessary-condition` rule to have that
+ * surfaced as a lint error instead of a silent dead branch. The rule ships with
+ * both [typescript-eslint](https://typescript-eslint.io/rules/no-unnecessary-condition/)
+ * and [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-unnecessary-condition.html)
+ * (note: it requires type-aware linting).
+ */
+export declare function isTruthy(value: Falsy, key: string, ctx?: Ctx): false;
+export declare function isTruthy<T>(value: Truthy<T>, key: string, ctx?: Ctx): true;
+export declare function isTruthy<T>(value: T, key: string, ctx?: Ctx): value is Truthy<T>;
+/**
+ * Checks for `null | undefined` values and logs a `warning` when they are.
+ * Unlike {@link isFalsy}, `0`, `false`, and `""` are not considered a match.
+ *
+ * Sample usage:
+ * ```ts
+ * if (isNullish(someValue, "my-key-here")) {
+ *     // someValue is null or undefined, warning gets logged `qc:is:nullish:my-key-here`
+ *     return; // do my early return
+ * }
+ * // keep on truckin'
+ * ```
+ *
+ * Like {@link isFalsy}, the overloads narrow the return type based on what's
+ * statically known about `value`: a {@link Defined} input returns the literal
+ * `false`, a {@link Nullish} input returns the literal `true`, and only
+ * genuinely uncertain values get the `value is Nullish & T` type guard. A
+ * redundant call — e.g. `isNullish` on something the compiler already knows is
+ * defined — produces a branch whose condition is a constant.
+ *
+ * Enable the `@typescript-eslint/no-unnecessary-condition` rule to have that
+ * surfaced as a lint error instead of a silent dead branch. The rule ships with
+ * both [typescript-eslint](https://typescript-eslint.io/rules/no-unnecessary-condition/)
+ * and [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-unnecessary-condition.html)
+ * (note: it requires type-aware linting).
+ */
+export declare function isNullish<T>(value: Defined<T>, key: string, ctx?: Ctx): false;
+export declare function isNullish(value: Nullish, key: string, ctx?: Ctx): true;
+export declare function isNullish<T>(value: T, key: string, ctx?: Ctx): value is Nullish & T;
+/**
+ * Checks that a value is neither `null` nor `undefined` and logs a
+ * `warning` when that's the case — the inverse of {@link isNullish}.
+ *
+ * Sample usage:
+ * ```ts
+ * if (isDefined(someValue, "my-key-here")) {
+ *     // someValue is neither null nor undefined, warning gets logged `qc:is:defined:my-key-here`
+ *     return; // do my early return
+ * }
+ * ```
+ *
+ * Like {@link isFalsy}, the overloads narrow the return type based on what's
+ * statically known about `value`: a {@link Nullish} input returns the literal
+ * `false`, a {@link Defined} input returns the literal `true`, and only
+ * genuinely uncertain values get the `value is Defined<T>` type guard. A
+ * redundant call — e.g. `isDefined` on something the compiler already knows is
+ * defined — produces a branch whose condition is a constant.
+ *
+ * Enable the `@typescript-eslint/no-unnecessary-condition` rule to have that
+ * surfaced as a lint error instead of a silent dead branch. The rule ships with
+ * both [typescript-eslint](https://typescript-eslint.io/rules/no-unnecessary-condition/)
+ * and [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-unnecessary-condition.html)
+ * (note: it requires type-aware linting).
+ */
+export declare function isDefined(value: Nullish, key: string, ctx?: Ctx): false;
+export declare function isDefined<T>(value: Defined<T>, key: string, ctx?: Ctx): true;
+export declare function isDefined<T>(value: T, key: string, ctx?: Ctx): value is Defined<T>;
+//# sourceMappingURL=is.d.ts.map

package/dist/src/qc-logger/is.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is.d.ts","sourceRoot":"","sources":["../../../src/qc-logger/is.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,KAAK,GAAG,EAAQ,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC;AAC5E,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;AACpE,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC;AAOjF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC;AACtE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;AAC5E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;AAOlF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;AACxE,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC;AAOrF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC;AACzE,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;AAC9E,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/src/qc-logger/is.js

@@ -0,0 +1,26 @@
+import { emit } from './structured-logger.js';
+export function isFalsy(value, key, ctx) {
+    const result = !value;
+    if (result)
+        emit('warning', 'is:falsy', key, ctx);
+    return result;
+}
+export function isTruthy(value, key, ctx) {
+    const result = Boolean(value);
+    if (result)
+        emit('warning', 'is:truthy', key, ctx);
+    return result;
+}
+export function isNullish(value, key, ctx) {
+    const result = value === undefined || value === null;
+    if (result)
+        emit('warning', 'is:nullish', key, ctx);
+    return result;
+}
+export function isDefined(value, key, ctx) {
+    const result = value !== undefined && value !== null;
+    if (result)
+        emit('warning', 'is:defined', key, ctx);
+    return result;
+}
+//# sourceMappingURL=is.js.map

package/dist/src/qc-logger/is.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is.js","sourceRoot":"","sources":["../../../src/qc-logger/is.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,IAAI,EAAE,MAAM,wBAAwB,CAAC;AA6BxD,MAAM,UAAU,OAAO,CAAI,KAAQ,EAAE,GAAW,EAAE,GAAS;IACvD,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC;IACtB,IAAI,MAAM;QAAE,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC;AAClB,CAAC;AA+BD,MAAM,UAAU,QAAQ,CAAI,KAAQ,EAAE,GAAW,EAAE,GAAS;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,MAAM;QAAE,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,MAAM,CAAC;AAClB,CAAC;AA+BD,MAAM,UAAU,SAAS,CAAI,KAAQ,EAAE,GAAW,EAAE,GAAS;IACzD,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;IACrD,IAAI,MAAM;QAAE,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC;AAClB,CAAC;AA8BD,MAAM,UAAU,SAAS,CAAI,KAAQ,EAAE,GAAW,EAAE,GAAS;IACzD,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;IACrD,IAAI,MAAM;QAAE,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/src/qc-logger/structured-logger.d.ts

@@ -0,0 +1,9 @@
+export type Ctx = Record<string, unknown>;
+/**
+ * Builds the canonical log line (`qc:<verb>:<key>`) without emitting it.
+ * Exposed so callers (e.g. `assert`) can reuse the exact same message when
+ * constructing an error to throw.
+ */
+export declare function formatMessage(qcVerb: string, rawKey: string): string;
+export declare function emit(level: 'debug' | 'info' | 'warning' | 'error', qcVerb: string, rawKey: string, ctx?: Ctx): string;
+//# sourceMappingURL=structured-logger.d.ts.map

package/dist/src/qc-logger/structured-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.d.ts","sourceRoot":"","sources":["../../../src/qc-logger/structured-logger.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAiB1C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM,CAcrH"}

package/dist/src/qc-logger/structured-logger.js

@@ -0,0 +1,38 @@
+import log from '@apify/log';
+/**
+ * Keys are part of the log line's parse structure (`qc:<verb>:<key>`)
+ * Turns any string into a valid qc key.
+ *
+ * If a key is completely invalid, it is replaced with "invalid-key".
+ */
+function normalizeKey(key) {
+    return (String(key)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-|-$/g, '') || 'invalid-key');
+}
+/**
+ * Builds the canonical log line (`qc:<verb>:<key>`) without emitting it.
+ * Exposed so callers (e.g. `assert`) can reuse the exact same message when
+ * constructing an error to throw.
+ */
+export function formatMessage(qcVerb, rawKey) {
+    return `qc:${qcVerb}:${normalizeKey(rawKey)}`;
+}
+export function emit(level, qcVerb, rawKey, ctx) {
+    let message;
+    try {
+        const qcKey = normalizeKey(rawKey);
+        message = formatMessage(qcVerb, rawKey);
+        // Caller ctx is spread first so it can never clobber the canonical fields.
+        // Run/actor identity is not attached here — Mezmo enriches lines with it.
+        log[level](message, { ...ctx, level, qcKey, qcVerb });
+        return message;
+    }
+    catch {
+        // Telemetry must never break a run.
+        message ??= `qc:unknown:qc-error-generating-key`;
+        return message;
+    }
+}
+//# sourceMappingURL=structured-logger.js.map

package/dist/src/qc-logger/structured-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.js","sourceRoot":"","sources":["../../../src/qc-logger/structured-logger.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,YAAY,CAAC;AAI7B;;;;;GAKG;AACH,SAAS,YAAY,CAAC,GAAW;IAC7B,OAAO,CACH,MAAM,CAAC,GAAG,CAAC;SACN,WAAW,EAAE;SACb,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,aAAa,CAC9C,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,MAAc;IACxD,OAAO,MAAM,MAAM,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,KAA6C,EAAE,MAAc,EAAE,MAAc,EAAE,GAAS;IACzG,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACxC,2EAA2E;QAC3E,0EAA0E;QAC1E,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QACtD,OAAO,OAAO,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACL,oCAAoC;QACpC,OAAO,KAAK,oCAAoC,CAAC;QACjD,OAAO,OAAO,CAAC;IACnB,CAAC;AACL,CAAC"}

package/dist/src/safePushData.d.ts

@@ -23,15 +23,23 @@ export interface DroppedItem<T> {
     item: T;
     errors: ValidationError[];
 }
-export interface SafePushDataResult<T> {
-    pushed: number;
-    dropped: DroppedItem<T>[];
-    attempts: number;
+export interface SafePushDataResult<T, R = unknown> {
+    /** How many of the caller's items made it into the dataset. */
+    pushedCount: number;
+    /** The items we couldn't repair, each with the errors that doomed it. */
+    droppedItems: DroppedItem<T>[];
+    /** How many times `pushFn` was actually called. */
+    attemptCount: number;
+    /**
+     * What the successful `pushFn` call resolved to (e.g. the API response).
+     * Absent when no push ever succeeded — i.e. when every item was dropped.
+     */
+    pushResult?: R;
 }
 export interface SafePushDataOptions {
     maxAttempts?: number;
 }
-export type PushFn<T> = (items: T[]) => Promise<unknown>;
+export type PushFn<T, R = unknown> = (items: T[]) => Promise<R>;
 /**
  * Push `input` via `pushFn`, surviving Apify dataset schema-validation
  * failures by cleaning offending items and retrying.
@@ -40,7 +48,9 @@ export type PushFn<T> = (items: T[]) => Promise<unknown>;
  * direct `.pushData()` calls in this library, so the binding lives at the
  * call site: `(b) => Actor.pushData(b)` or
  * `(b) => client.dataset(id).pushItems(b)`.
+ *
+ * Whatever `pushFn` resolves to is handed back untouched as `pushResult`.
  */
-export declare function safePushData<T>(pushFn: PushFn<T>, input: T | T[], options?: SafePushDataOptions): Promise<SafePushDataResult<T>>;
+export declare function safePushData<T, R = unknown>(pushFn: PushFn<T, R>, input: T | T[], options?: SafePushDataOptions): Promise<SafePushDataResult<T, R>>;
 export {};
 //# sourceMappingURL=safePushData.d.ts.map

package/dist/src/safePushData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safePushData.d.ts","sourceRoot":"","sources":["../../src/safePushData.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,iBAAiB,4BAA4B,CAAC;AAKpD,MAAM,WAAW,eAAe;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,WAAW;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACvC;AAKD,UAAU,qBAAqB;IAC3B,IAAI,EAAE,OAAO,iBAAiB,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,YAAY,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;CACzC;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB,CAMlF;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,EACd,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAehC"}
+{"version":3,"file":"safePushData.d.ts","sourceRoot":"","sources":["../../src/safePushData.ts"],"names":[],"mappings":"AAWA,QAAA,MAAM,iBAAiB,4BAA4B,CAAC;AAcpD,MAAM,WAAW,eAAe;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,WAAW;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACvC;AAKD,UAAU,qBAAqB;IAC3B,IAAI,EAAE,OAAO,iBAAiB,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,YAAY,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;CACzC;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB,CAMlF;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AAID,MAAM,WAAW,kBAAkB,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO;IAC9C,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/B,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,EAC7C,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,EACd,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAenC"}