@apify/actor-utils 0.1.0 → 0.1.3-beta.0

package/README.md

@@ -47,25 +47,30 @@ every AJV error per item:
 ### 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.
 
 ## Options

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { safePushData, isSchemaValidationError } from './src/safePushData.js';
+export type { ValidationError, DroppedItem, SafePushDataResult, SafePushDataOptions, PushFn, } from './src/safePushData.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,YAAY,EACR,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,MAAM,GACT,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { safePushData, isSchemaValidationError } from './src/safePushData.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,46 @@
+declare const SCHEMA_ERROR_TYPE = "schema-validation-error";
+export interface ValidationError {
+    instancePath: string;
+    schemaPath?: string;
+    keyword: string;
+    params?: Record<string, unknown>;
+    message?: string;
+}
+interface InvalidItem {
+    itemPosition: number;
+    validationErrors: ValidationError[];
+}
+interface SchemaValidationError {
+    type: typeof SCHEMA_ERROR_TYPE;
+    statusCode: 400;
+    message: string;
+    data: {
+        invalidItems: InvalidItem[];
+    };
+}
+export declare function isSchemaValidationError(err: unknown): err is SchemaValidationError;
+export interface DroppedItem<T> {
+    item: T;
+    errors: ValidationError[];
+}
+export interface SafePushDataResult<T> {
+    pushed: number;
+    dropped: DroppedItem<T>[];
+    attempts: number;
+}
+export interface SafePushDataOptions {
+    maxAttempts?: number;
+}
+export type PushFn<T> = (items: T[]) => Promise<unknown>;
+/**
+ * Push `input` via `pushFn`, surviving Apify dataset schema-validation
+ * failures by cleaning offending items and retrying.
+ *
+ * `pushFn` is mandatory and intentionally not bundled — a CI check forbids
+ * 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)`.
+ */
+export declare function safePushData<T>(pushFn: PushFn<T>, input: T | T[], options?: SafePushDataOptions): Promise<SafePushDataResult<T>>;
+export {};
+//# sourceMappingURL=safePushData.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safePushData.d.ts","sourceRoot":"","sources":["../../src/safePushData.ts"],"names":[],"mappings":"AAWA,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"}

package/dist/src/safePushData.js

@@ -0,0 +1,285 @@
+// safePushData: parse the Apify dataset schema-validation error, repair the
+// offending items (strip bad fields, placeholder missing required ones), and
+// retry the push.
+//
+// NOTE: instead of recursively healing the data one error-round at a time, we
+// could parse the Actor's `dataset_schema.json` up front and fix every item in
+// a single pass (we'd know each field's expected type / constraints without
+// waiting for the API to report them). That would avoid the multi-round retry
+// loop, but requires heavier code (locating + loading the schema, resolving
+// $refs, walking the schema tree). Something to consider in the future.
+const SCHEMA_ERROR_TYPE = 'schema-validation-error';
+export function isSchemaValidationError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.type !== SCHEMA_ERROR_TYPE)
+        return false;
+    if (e.statusCode !== 400)
+        return false;
+    return Array.isArray(e.data?.invalidItems);
+}
+/**
+ * Push `input` via `pushFn`, surviving Apify dataset schema-validation
+ * failures by cleaning offending items and retrying.
+ *
+ * `pushFn` is mandatory and intentionally not bundled — a CI check forbids
+ * 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)`.
+ */
+export async function safePushData(pushFn, input, options = {}) {
+    const items = Array.isArray(input) ? input : [input];
+    // Happy path: assume validation will succeed (the overwhelmingly common
+    // case). No working copies, no maps, no per-item wrapper objects — just
+    // hand the caller's array to pushFn and return on success.
+    try {
+        await pushFn(items);
+        return { pushed: items.length, dropped: [], attempts: 1 };
+    }
+    catch (err) {
+        if (!isSchemaValidationError(err))
+            throw err;
+        // Clamp to >=1: the initial push above always counts as one attempt,
+        // so 0/negative would make the reported `attempts` lie about it.
+        return cleanAndRetry(pushFn, items, err, Math.max(1, options.maxAttempts ?? 5));
+    }
+}
+async function cleanAndRetry(pushFn, originalItems, initialError, maxAttempts) {
+    // working[i] is what we'll send on the next push. We mutate this array
+    // in place (splicing drops, replacing cleaned entries); the caller's
+    // `originalItems` is never touched.
+    const working = originalItems.slice();
+    // Parallel to `working`. Holds the original (untouched) reference so a
+    // dropped report shows what the caller actually passed in, even if the
+    // item was partially cleaned before being dropped on a later round.
+    const originalAt = originalItems.slice();
+    // Parallel to `working`. Tracks which paths inside each item are
+    // placeholders we set (vs. real user data). Needed so we can chase
+    // follow-up type/minLength/enum errors on the placeholder field
+    // without looping forever; for user-supplied fields the existing
+    // "delete the field" behaviour stays in effect.
+    const placeholderPaths = originalItems.map(() => new Set());
+    // Parallel to `working`. The validation errors that were last reported
+    // for this position — kept so a give-up drop (maxAttempts exceeded) can
+    // still report *why*, not just that it gave up.
+    const lastErrorsAt = originalItems.map(() => []);
+    const dropped = [];
+    let attempts = 1;
+    let lastError = initialError;
+    while (true) {
+        // Process this round's errors. Highest position first so the splices
+        // below don't shift positions we still need to look at.
+        const invalids = lastError.data.invalidItems.slice().sort((a, b) => b.itemPosition - a.itemPosition);
+        for (const invalid of invalids) {
+            const i = invalid.itemPosition;
+            // Guard against a malformed/unexpected error payload (e.g. a
+            // position outside the batch we actually sent) instead of
+            // crashing on `working[i]` being undefined.
+            if (i < 0 || i >= working.length) {
+                console.log(`safePushData: ignoring out-of-range itemPosition ${i} in validation error response.`);
+                continue;
+            }
+            const cleaned = cleanItemFields(working[i], invalid.validationErrors, placeholderPaths[i]);
+            if (cleaned === null) {
+                dropped.push({ item: originalAt[i], errors: invalid.validationErrors });
+                working.splice(i, 1);
+                originalAt.splice(i, 1);
+                placeholderPaths.splice(i, 1);
+                lastErrorsAt.splice(i, 1);
+            }
+            else {
+                working[i] = cleaned;
+                lastErrorsAt[i] = invalid.validationErrors;
+            }
+        }
+        console.log(`safePushData: schema validation failed on attempt ${attempts}: ` +
+            `${lastError.data.invalidItems.length} invalid item(s); ` +
+            `retrying with ${working.length} item(s).`);
+        if (working.length === 0) {
+            return { pushed: originalItems.length - dropped.length, dropped, attempts };
+        }
+        attempts++;
+        if (attempts > maxAttempts) {
+            console.log(`safePushData: gave up after ${maxAttempts} attempts with ${working.length} item(s) still failing.`);
+            for (let i = 0; i < working.length; i++) {
+                dropped.push({ item: originalAt[i], errors: lastErrorsAt[i] });
+            }
+            return { pushed: originalItems.length - dropped.length, dropped, attempts: maxAttempts };
+        }
+        try {
+            await pushFn(working);
+            return { pushed: originalItems.length - dropped.length, dropped, attempts };
+        }
+        catch (err) {
+            if (!isSchemaValidationError(err))
+                throw err;
+            lastError = err;
+        }
+    }
+}
+// Try to repair a single item given its AJV errors. Returns null when the
+// item can't be salvaged.
+//
+// Mutates `placeholderPaths` to record any fields we filled in ourselves,
+// so the caller can keep iterating on them across rounds.
+function cleanItemFields(item, validationErrors, placeholderPaths) {
+    // structuredClone so we never mutate the caller's data.
+    const cloned = structuredClone(item);
+    for (const err of validationErrors) {
+        const instancePath = err.instancePath || '';
+        const path = parseJsonPointer(instancePath);
+        // Root-level errors describe the item as a whole.
+        if (path.length === 0) {
+            // Missing required field: insert a placeholder and remember we
+            // did so. The next round will see a `type` error on this path
+            // and we'll upgrade null to a type-appropriate value.
+            if (err.keyword === 'required' && typeof err.params?.missingProperty === 'string') {
+                const prop = err.params.missingProperty;
+                cloned[prop] = null;
+                placeholderPaths.add(`/${prop}`);
+                continue;
+            }
+            // Strip an unknown property reported at the root.
+            if (err.keyword === 'additionalProperties' && typeof err.params?.additionalProperty === 'string') {
+                delete cloned[err.params.additionalProperty];
+                continue;
+            }
+            // type/format/etc. at the root means the item itself is the wrong shape.
+            return null;
+        }
+        // Errors on a path we placeholder'd: try to satisfy the constraint
+        // rather than delete the field (deleting would re-trigger required).
+        if (placeholderPaths.has(instancePath)) {
+            const fix = placeholderFor(err);
+            if (fix.ok) {
+                setAtPath(cloned, path, fix.value);
+                continue;
+            }
+            // Constraint we don't know how to satisfy on a placeholder field
+            // (e.g. pattern, custom format). Give up on this item.
+            return null;
+        }
+        // additionalProperties errors point at the *parent* object; the
+        // offending key is in params, not in instancePath.
+        if (err.keyword === 'additionalProperties' && typeof err.params?.additionalProperty === 'string') {
+            deleteAtPath(cloned, [...path, err.params.additionalProperty]);
+            continue;
+        }
+        // User-supplied field with a violation we don't try to coerce.
+        // Strip it; if the schema declares it required, the next push will
+        // re-add a placeholder.
+        deleteAtPath(cloned, path);
+    }
+    return cloned;
+}
+// Pick a value that will satisfy `err.keyword` on a placeholder field.
+// Returns ok:false when we don't have a sensible default; the caller drops
+// the item in that case.
+//
+// We deliberately only placeholder the four "empty" values — `''`, `[]`, `{}`,
+// and `null`. These are unambiguously empty and can't be mistaken for real
+// data. We do NOT fabricate values for `enum`, `format`, `minLength`, numeric
+// bounds, etc.: a made-up email, a first-enum-value, or a `'_'.repeat(N)`
+// string all silently poison the customer's dataset with plausible-looking
+// junk. Better to drop the item than to lie about its contents. As a result
+// the only keyword we handle is `type` (only for those four target types) —
+// everything else falls through to ok:false and the item is dropped.
+function placeholderFor(err) {
+    const params = err.params ?? {};
+    if (err.keyword !== 'type')
+        return { ok: false };
+    // params.type is the expected type as a string, or an array of strings
+    // when the field allows multiple types (e.g. `['string', 'null']`).
+    const types = Array.isArray(params.type) ? params.type : [params.type];
+    // Union type that permits null: prefer null. It's the cleanest possible
+    // placeholder — it commits to no concrete value at all — so whenever the
+    // schema allows it, that's what we use.
+    if (types.length > 1 && types.includes('null')) {
+        return { ok: true, value: null };
+    }
+    // Otherwise take the first allowed type we have an "empty" default for.
+    // integer / number / boolean are intentionally absent: 0 / false read as
+    // real data, so a field of only those types is dropped instead.
+    for (const t of types) {
+        switch (t) {
+            case 'null':
+                return { ok: true, value: null };
+            case 'string':
+                return { ok: true, value: '' };
+            case 'array':
+                return { ok: true, value: [] };
+            case 'object':
+                return { ok: true, value: {} };
+            default:
+                break;
+        }
+    }
+    return { ok: false };
+}
+// Parse a JSON Pointer (RFC 6901) into decoded segments.
+// "" -> []; "/foo/bar" -> ["foo","bar"]; "/tags/0" -> ["tags","0"].
+function parseJsonPointer(pointer) {
+    if (!pointer)
+        return [];
+    return pointer
+        .split('/')
+        .slice(1)
+        .map((seg) => seg.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+// Delete the value at `path` inside `obj`. Arrays splice (so later
+// `/tags/N` errors in the same round line up with their original indices).
+function deleteAtPath(obj, path) {
+    if (path.length === 0)
+        return false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let cursor = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        if (cursor == null || typeof cursor !== 'object')
+            return false;
+        cursor = Array.isArray(cursor) ? cursor[Number(key)] : cursor[key];
+    }
+    if (cursor == null || typeof cursor !== 'object')
+        return false;
+    const last = path[path.length - 1];
+    if (Array.isArray(cursor)) {
+        const idx = Number(last);
+        if (!Number.isInteger(idx) || idx < 0 || idx >= cursor.length)
+            return false;
+        cursor.splice(idx, 1);
+        return true;
+    }
+    if (Object.prototype.hasOwnProperty.call(cursor, last)) {
+        delete cursor[last];
+        return true;
+    }
+    return false;
+}
+// Set the value at `path` inside `obj`. Creates nothing — the path must
+// already exist (placeholder fields are created at the root, not nested).
+function setAtPath(obj, path, value) {
+    if (path.length === 0)
+        return false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let cursor = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        if (cursor == null || typeof cursor !== 'object')
+            return false;
+        cursor = Array.isArray(cursor) ? cursor[Number(key)] : cursor[key];
+    }
+    if (cursor == null || typeof cursor !== 'object')
+        return false;
+    const last = path[path.length - 1];
+    if (Array.isArray(cursor)) {
+        const idx = Number(last);
+        if (!Number.isInteger(idx) || idx < 0)
+            return false;
+        cursor[idx] = value;
+        return true;
+    }
+    cursor[last] = value;
+    return true;
+}
+//# sourceMappingURL=safePushData.js.map

package/dist/src/safePushData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safePushData.js","sourceRoot":"","sources":["../../src/safePushData.ts"],"names":[],"mappings":"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"}

package/dist/src/type-utils/index.d.ts

@@ -0,0 +1,3 @@
+export { unreachable } from './unreachable.js';
+export type { Falsy, Nullish, Truthy, Defined } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/type-utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/type-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/type-utils/index.js

@@ -0,0 +1,2 @@
+export { unreachable } from './unreachable.js';
+//# sourceMappingURL=index.js.map

package/dist/src/type-utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/type-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/type-utils/types.d.ts

@@ -0,0 +1,23 @@
+export type Falsy = false | 0 | '' | null | undefined;
+export type Nullish = null | undefined;
+/**
+ * Narrows `T` to only its truthy members by stripping every {@link Falsy}
+ * value (`false`, `0`, `''`, `null`, `undefined`).
+ *
+ * Unlike `Exclude<T, Falsy>`, this checks each falsy literal individually so a
+ * broad type such as `boolean` or `number` is preserved rather than collapsed:
+ * `boolean` only loses `false` if `false` is the whole type, not when it's part
+ * of `boolean`. Object types short-circuit first, so `''`/`0` don't accidentally
+ * match structural (`{}`) types.
+ *
+ * @example
+ * ```ts
+ * type A = Truthy<string | undefined>;   // string
+ * type B = Truthy<0 | 1 | 2>;            // 1 | 2
+ * type C = Truthy<'' | 'hello'>;         // 'hello'
+ * type D = Truthy<false>;                // never
+ * ```
+ */
+export type Truthy<T> = T extends object ? T : false extends T ? never : 0 extends T ? never : '' extends T ? never : null extends T ? never : undefined extends T ? never : T;
+export type Defined<T> = Exclude<T, Nullish>;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/type-utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/type-utils/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AACtD,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAEhB,CAAC,SAAS,MAAM,GACV,CAAC,GACD,KAAK,SAAS,CAAC,GACb,KAAK,GACL,CAAC,SAAS,CAAC,GACT,KAAK,GACL,EAAE,SAAS,CAAC,GACV,KAAK,GACL,IAAI,SAAS,CAAC,GACZ,KAAK,GACL,SAAS,SAAS,CAAC,GACjB,KAAK,GACL,CAAC,CAAC;AAEtB,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC"}

package/dist/src/type-utils/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/type-utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/type-utils/types.ts"],"names":[],"mappings":""}

package/dist/src/type-utils/unreachable.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Asserts that a code path is unreachable, enabling exhaustiveness checks.
+ *
+ * Pass a value of type `never` to this function to let the TypeScript compiler
+ * verify that all cases of a union have been handled. If a new variant is added
+ * to the union but not handled, the call becomes a compile-time error. At
+ * runtime, reaching this function throws an `Error`.
+ *
+ * @param x - The value that should be of type `never` at this point.
+ * @throws {Error} Always throws, since this code should never be reached.
+ *
+ * @example
+ * ```ts
+ * type Shape = 'circle' | 'square';
+ *
+ * function area(shape: Shape): number {
+ *     switch (shape) {
+ *         case 'circle':
+ *             return Math.PI;
+ *         case 'square':
+ *             return 1;
+ *         default:
+ *             // Compile-time error here if a new Shape variant is unhandled.
+ *             return unreachable(shape);
+ *     }
+ * }
+ * ```
+ */
+export declare function unreachable(x: never): never;
+//# sourceMappingURL=unreachable.d.ts.map

package/dist/src/type-utils/unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../../../src/type-utils/unreachable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAE3C"}

package/dist/src/type-utils/unreachable.js

@@ -0,0 +1,32 @@
+/**
+ * Asserts that a code path is unreachable, enabling exhaustiveness checks.
+ *
+ * Pass a value of type `never` to this function to let the TypeScript compiler
+ * verify that all cases of a union have been handled. If a new variant is added
+ * to the union but not handled, the call becomes a compile-time error. At
+ * runtime, reaching this function throws an `Error`.
+ *
+ * @param x - The value that should be of type `never` at this point.
+ * @throws {Error} Always throws, since this code should never be reached.
+ *
+ * @example
+ * ```ts
+ * type Shape = 'circle' | 'square';
+ *
+ * function area(shape: Shape): number {
+ *     switch (shape) {
+ *         case 'circle':
+ *             return Math.PI;
+ *         case 'square':
+ *             return 1;
+ *         default:
+ *             // Compile-time error here if a new Shape variant is unhandled.
+ *             return unreachable(shape);
+ *     }
+ * }
+ * ```
+ */
+export function unreachable(x) {
+    throw new Error(`unreachable: ${x}`);
+}
+//# sourceMappingURL=unreachable.js.map

package/dist/src/type-utils/unreachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.js","sourceRoot":"","sources":["../../../src/type-utils/unreachable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,WAAW,CAAC,CAAQ;IAChC,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/package.json

@@ -1,63 +1,74 @@
 {
-    "name": "@apify/actor-utils",
-    "version": "0.1.0",
-    "type": "module",
-    "description": "Wrapper around Actor.pushData that survives dataset schema-validation failures by stripping offending fields and retrying. Callers pass the actual push function as pushFn.",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/apify-projects/apify-actor-utils.git"
+  "name": "@apify/actor-utils",
+  "version": "0.1.3-beta.0",
+  "type": "module",
+  "description": "Wrapper around Actor.pushData that survives dataset schema-validation failures by stripping offending fields and retrying. Callers pass the actual push function as pushFn.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apify/apify-actor-utils.git"
+  },
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "engines": {
-        "node": ">=22.6.0"
+    "./qc-logger": {
+      "types": "./dist/src/qc-logger/index.d.ts",
+      "default": "./dist/src/qc-logger/index.js"
     },
-    "types": "./dist/index.d.ts",
-    "main": "./dist/index.js",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "default": "./dist/index.js"
-        }
-    },
-    "files": [
-        "dist/index.js",
-        "dist/index.js.map",
-        "dist/index.d.ts",
-        "dist/index.d.ts.map",
-        "dist/src"
-    ],
-    "scripts": {
-        "build": "tsc",
-        "typecheck": "tsc --noEmit",
-        "lint": "eslint",
-        "lint:fix": "eslint --fix",
-        "format": "prettier --write .",
-        "format:check": "prettier --check .",
-        "test": "tsc && node --test dist/test/*.test.js",
-        "check:pushdata": "node scripts/check-pushdata.mjs",
-        "check-unused": "knip",
-        "ci": "npm run typecheck && npm run lint && npm run format:check && npm run check:pushdata && npm test",
-        "probe": "node scripts/probe-errors.mjs",
-        "prepare": "husky .husky || true"
-    },
-    "lint-staged": {
-        "*.js": "eslint",
-        "*.ts": "eslint",
-        "*.mjs": "eslint"
-    },
-    "devDependencies": {
-        "@apify/eslint-config": "^1.2.0",
-        "@apify/tsconfig": "^0.1.2",
-        "@types/node": "^25.9.1",
-        "apify-client": "^2.10.0",
-        "eslint": "^9.39.4",
-        "eslint-config-prettier": "^10.1.8",
-        "globals": "^17.7.0",
-        "husky": "^9.1.7",
-        "knip": "^5.88.1",
-        "lint-staged": "^15.5.2",
-        "prettier": "^3.9.4",
-        "typescript": "^6.0.3",
-        "typescript-eslint": "^8.62.1"
-    },
-    "license": "ISC"
+    "./type-utils": {
+      "types": "./dist/src/type-utils/index.d.ts",
+      "default": "./dist/src/type-utils/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/index.d.ts",
+    "dist/index.d.ts.map",
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "tsc && node --test dist/test/*.test.js",
+    "check:pushdata": "node scripts/check-pushdata.mjs",
+    "check-unused": "knip",
+    "ci": "npm run typecheck && npm run lint && npm run format:check && npm run check:pushdata && npm test",
+    "probe": "node scripts/probe-errors.mjs",
+    "prepare": "husky .husky || true"
+  },
+  "lint-staged": {
+    "*.js": "eslint",
+    "*.ts": "eslint",
+    "*.mjs": "eslint"
+  },
+  "devDependencies": {
+    "@apify/eslint-config": "^1.2.0",
+    "@apify/tsconfig": "^0.1.2",
+    "@types/node": "^25.9.1",
+    "apify-client": "^2.10.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "husky": "^9.1.7",
+    "knip": "^5.88.1",
+    "lint-staged": "^15.5.2",
+    "prettier": "^3.9.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
+  },
+  "license": "ISC",
+  "peerDependencies": {
+    "@apify/log": "^2.5.44"
+  }
 }