@hue-run/sdk 0.21.1 → 0.23.0

package/dist/cli/import-formats/reader.js

@@ -0,0 +1,364 @@
+import { conversionFailure, MAX_SOURCE_NESTING, nestedTooDeep, sha256Hex, } from "../traces-import-convert.js";
+import { decodeContainer, parseValues } from "./containers.js";
+import { applyIdentityKeys, traceIdentity } from "./identity.js";
+import { binaryValues } from "./otlp-protobuf.js";
+import { adapterFor, importAdapters, unrecognizedReason } from "./registry.js";
+import { RowTraceCollector, rowTraceId } from "./rows.js";
+/**
+ * Reads source files through the containers and the format registry (`registry.ts`) and gathers
+ * every trace they hold, with what could not be read: files, records (lines of JSON Lines,
+ * records of a JSON array) and traces, each named with where it was found.
+ */
+/** Records of one file reported as not read, or notes on one file; past this many the rest are
+ * counted. */
+const MAX_REPORTED_PER_FILE = 100;
+/** Records of a JSON array no format reads, in a row from its start, after which the rest of the
+ * array is not looked at: it is not an export of any format. */
+const MAX_UNCLAIMED_RUN = 1000;
+/** One file's reported records: the first `MAX_REPORTED_PER_FILE` kept, the rest counted. */
+class Reported {
+    file;
+    items = [];
+    more = 0;
+    constructor(file) {
+        this.file = file;
+    }
+    add(item) {
+        if (this.items.length < MAX_REPORTED_PER_FILE)
+            this.items.push({ file: this.file, ...item });
+        else
+            this.more++;
+    }
+    /** The kept items in the order of the file, and one counting the rest. */
+    finish(what) {
+        const items = this.items.sort((a, b) => (a.line ?? 0) - (b.line ?? 0) || (a.record ?? 0) - (b.record ?? 0));
+        return this.more ? [...items, { file: this.file, reason: `${this.more} more ${what}` }] : items;
+    }
+}
+/** Where a duplicate was first read, as the report names it from `file`. */
+function where(earlier, file) {
+    const position = earlier.line !== undefined
+        ? `line ${earlier.line}`
+        : earlier.record !== undefined
+            ? `record ${earlier.record}`
+            : "";
+    if (earlier.file === file)
+        return position || "earlier in the file";
+    return position ? `${earlier.file} ${position}` : earlier.file;
+}
+export class ImportReader {
+    options;
+    /** Run-wide collectors, by format id or by the key formats that share one name. */
+    collectors = new Map();
+    /** The shared collector key of each format that named one. */
+    sharedKeys = new Map();
+    rowCollectors = new Map();
+    whole = [];
+    /** Traces already refused and named; a collector's own refusal of one is not repeated. */
+    refusedTraces = new Set();
+    /** The file names each content digest was read under. */
+    fileNames = new Map();
+    supported = new Map();
+    result;
+    /** `unsupported` is where files that cannot be read are listed, in the order they are read. */
+    constructor(options) {
+        this.options = options;
+        this.result = {
+            unsupported: options.unsupported ?? [],
+            skipped: [],
+            notes: [],
+            refused: [],
+        };
+    }
+    /** Reads one file's bytes; returns the size of its decoded content. */
+    read(file, raw) {
+        const decoded = decodeContainer(raw, this.options.maxFileBytes);
+        if ("unsupported" in decoded) {
+            this.result.unsupported.push({ file, reason: decoded.unsupported });
+            return raw.byteLength;
+        }
+        const binary = binaryValues(decoded.bytes, this.options.maxFileBytes);
+        const parsed = binary ?? parseValues(decoded.bytes);
+        if ("unsupported" in parsed) {
+            this.result.unsupported.push({ file, reason: parsed.unsupported });
+            return decoded.bytes.byteLength;
+        }
+        const size = () => ("bytes" in parsed ? parsed.bytes() : decoded.bytes.byteLength);
+        const digest = sha256Hex(decoded.bytes);
+        const skipped = new Reported(file);
+        const notes = new Reported(file);
+        if (decoded.note)
+            notes.add({ reason: decoded.note });
+        const failures = [];
+        let claimed = false;
+        let firstReason;
+        /** Converts a value with the format that claims it; the reason it was not read otherwise. */
+        const offer = (value, source) => {
+            const adapter = adapterFor(value);
+            if (!adapter)
+                return unrecognizedReason(value);
+            try {
+                this.convert(adapter, value, file, source, notes);
+            }
+            catch (error) {
+                const failure = conversionFailure(error);
+                if (!failure)
+                    throw error;
+                failures.push(failure.message);
+                return failure.message;
+            }
+            claimed = true;
+            const key = `${file}\u0000${adapter.id}`;
+            if (!this.supported.has(key))
+                this.supported.set(key, { file, format: adapter.id, traces: 0 });
+            return undefined;
+        };
+        const tooDeep = `JSON nested more than ${MAX_SOURCE_NESTING} levels deep`;
+        /** The records of an array no format reads whole, each offered on its own. */
+        const offerRecords = (records, source, line) => {
+            let run = 0;
+            let claimedAny = false;
+            for (const [index, element] of records.entries()) {
+                if (!claimedAny && run >= MAX_UNCLAIMED_RUN) {
+                    skipped.add({
+                        ...line,
+                        reason: `${records.length - index} more records not read: no format reads the first ${MAX_UNCLAIMED_RUN}`,
+                    });
+                    return;
+                }
+                let problem;
+                if (nestedTooDeep(element))
+                    problem = tooDeep;
+                else {
+                    let text;
+                    // A record's text is made only when a format asks for it.
+                    problem = offer(element, {
+                        digest,
+                        unsafeIntegers: source.unsafeIntegers,
+                        get text() {
+                            return (text ??= JSON.stringify(element));
+                        },
+                        get bytes() {
+                            return Buffer.byteLength(this.text);
+                        },
+                        ...line,
+                        index,
+                    });
+                }
+                if (problem === undefined)
+                    claimedAny = true;
+                else {
+                    run++;
+                    skipped.add({ ...line, record: index + 1, reason: problem });
+                }
+            }
+        };
+        for (const item of parsed.values) {
+            const line = item.line !== undefined ? { line: item.line } : {};
+            const source = {
+                digest,
+                get text() {
+                    return item.text;
+                },
+                get bytes() {
+                    return Buffer.byteLength(item.text);
+                },
+                unsafeIntegers: item.unsafeIntegers,
+                ...line,
+            };
+            if (item.note)
+                notes.add({ ...line, reason: item.note });
+            const deep = nestedTooDeep(item.value);
+            const reason = deep ? tooDeep : offer(item.value, source);
+            firstReason ??= reason;
+            if (reason === undefined)
+                continue;
+            // An array no format reads whole (or too deep to read whole) is read record by record.
+            if (Array.isArray(item.value) &&
+                item.value.length &&
+                (deep || adapterFor(item.value) === undefined)) {
+                offerRecords(item.value, source, line);
+                continue;
+            }
+            skipped.add({ ...line, reason });
+        }
+        for (const problem of parsed.problems)
+            skipped.add(problem);
+        if (!claimed) {
+            // Nothing in the file was read: the file is reported, not each of its records.
+            this.result.unsupported.push({
+                file,
+                reason: failures[0] ?? firstReason ?? parsed.problems[0]?.reason ?? "no value was read",
+            });
+            return size();
+        }
+        const names = this.fileNames.get(digest) ?? new Set();
+        this.fileNames.set(digest, names.add(file));
+        this.result.skipped.push(...skipped.finish("records were not read"));
+        this.result.notes.push(...notes.finish("notes"));
+        return size();
+    }
+    rows(format) {
+        let collector = this.rowCollectors.get(format);
+        if (!collector) {
+            collector = new RowTraceCollector(format, this.options.keys);
+            this.rowCollectors.set(format, collector);
+        }
+        return collector;
+    }
+    convert(adapter, value, file, source, notes) {
+        const at = {
+            file,
+            ...(source.line !== undefined ? { line: source.line } : {}),
+            ...(source.index !== undefined ? { record: source.index + 1 } : {}),
+        };
+        // Rows the value gave and those an identical copy of which was already read elsewhere: a
+        // value that gave nothing new is noted, so a collapsed duplicate is never silent.
+        let rows = 0;
+        let duplicates = 0;
+        let earlier;
+        const repeats = new Map();
+        const context = {
+            source,
+            keys: this.options.keys ?? {},
+            row: (row) => {
+                rows++;
+                const copy = this.rows(adapter.id).add(row, source.digest, at);
+                if (copy) {
+                    duplicates++;
+                    earlier ??= copy;
+                }
+            },
+            event: (event) => this.rows(adapter.id).addEvent(event, source.digest, repeats),
+            trace: (trace) => {
+                trace.format = adapter.id;
+                trace.sourceDigests.add(source.digest);
+                this.whole.push(trace);
+            },
+            refuse: (reason, traceKey) => {
+                const traceId = traceKey === undefined ? undefined : rowTraceId(adapter.id, traceKey);
+                if (traceId)
+                    this.refusedTraces.add(traceId);
+                this.result.refused.push({ ...at, ...(traceId ? { trace_id: traceId } : {}), reason });
+            },
+            collector: (create, shared) => {
+                if (shared !== undefined)
+                    this.sharedKeys.set(adapter.id, shared);
+                const key = shared ?? adapter.id;
+                // A format always creates the same kind of collector, and formats that share one create
+                // the same kind, so the one held is a T.
+                const held = this.collectors.get(key);
+                if (held)
+                    return held;
+                const created = create();
+                this.collectors.set(key, created);
+                return created;
+            },
+        };
+        adapter.convert(value, context);
+        if (rows && duplicates === rows && earlier)
+            notes.add({
+                ...(at.line !== undefined ? { line: at.line } : {}),
+                ...(at.record !== undefined ? { record: at.record } : {}),
+                reason: `the same ${rows === 1 ? "record" : "records"} as ${where(earlier, file)}, read once`,
+            });
+    }
+    /** Every trace read, merged across files: the same trace from two sources is one trace when
+     * its spans agree, and refused when they differ. */
+    finish() {
+        const traces = new Map();
+        const conflicts = new Map();
+        const kept = new Set();
+        // A trace refused after another format's copy of it was merged is left out with it.
+        const refuse = (traceId, reason) => {
+            if (traceId !== undefined)
+                traces.delete(traceId);
+            if (traceId !== undefined && this.refusedTraces.has(traceId))
+                return;
+            if (traceId !== undefined)
+                this.refusedTraces.add(traceId);
+            this.result.refused.push({ ...(traceId !== undefined ? { trace_id: traceId } : {}), reason });
+        };
+        const merge = (trace) => {
+            if (this.refusedTraces.has(trace.traceId))
+                return;
+            const held = traces.get(trace.traceId);
+            if (!held)
+                traces.set(trace.traceId, trace);
+            else if (JSON.stringify(held.entries) !== JSON.stringify(trace.entries))
+                conflicts.set(trace.traceId, "the trace appears in two sources with different content");
+            else
+                for (const digest of trace.sourceDigests)
+                    held.sourceDigests.add(digest);
+        };
+        const finishedShared = new Set();
+        for (const adapter of importAdapters) {
+            const shared = this.sharedKeys.get(adapter.id);
+            // A shared collector is finished once, under the first of its formats.
+            const done = shared !== undefined && finishedShared.has(shared);
+            if (shared !== undefined)
+                finishedShared.add(shared);
+            for (const [collector, rowFormat] of [
+                [done ? undefined : this.collectors.get(shared ?? adapter.id), false],
+                [this.rowCollectors.get(adapter.id), true],
+            ]) {
+                if (!collector)
+                    continue;
+                const finished = collector.finish();
+                for (const problem of finished.refused)
+                    refuse(problem.traceId, problem.reason);
+                for (const trace of finished.traces) {
+                    if (rowFormat || shared === undefined)
+                        trace.format = adapter.id;
+                    // Spans the shared emitter wrote already carry the identity keys' user and session.
+                    if (!rowFormat && !collector.appliesKeys)
+                        kept.add(trace);
+                    merge(trace);
+                }
+            }
+        }
+        for (const trace of this.whole) {
+            kept.add(trace);
+            merge(trace);
+        }
+        for (const [traceId, reason] of conflicts)
+            refuse(traceId, reason);
+        // A trace a shared collector gathered from files of several formats counts for each file
+        // under the format it was read with.
+        const group = (format) => this.sharedKeys.get(format) ?? format;
+        const byGroup = new Map();
+        for (const entry of this.supported.values()) {
+            const key = `${entry.file}\u0000${group(entry.format)}`;
+            if (!byGroup.has(key))
+                byGroup.set(key, entry);
+        }
+        const ordered = [];
+        for (const trace of [...traces.values()].sort((a, b) => (a.traceId < b.traceId ? -1 : 1))) {
+            try {
+                if (kept.has(trace))
+                    applyIdentityKeys(trace, this.options.keys ?? {});
+                const identity = traceIdentity(trace.entries);
+                if (identity)
+                    trace.identity = identity;
+                else
+                    delete trace.identity;
+            }
+            catch (error) {
+                const failure = conversionFailure(error);
+                if (!failure)
+                    throw error;
+                refuse(trace.traceId, failure.message);
+                continue;
+            }
+            ordered.push(trace);
+            for (const digest of trace.sourceDigests)
+                for (const name of this.fileNames.get(digest) ?? []) {
+                    const entry = this.supported.get(`${name}\u0000${trace.format}`) ??
+                        byGroup.get(`${name}\u0000${group(trace.format)}`);
+                    if (entry)
+                        entry.traces++;
+                }
+        }
+        return { traces: ordered, supported: [...this.supported.values()], ...this.result };
+    }
+}

package/dist/cli/import-formats/registry.d.ts

@@ -0,0 +1,36 @@
+import type { ImportAdapter } from "./adapter.js";
+/**
+ * The source formats `hue traces import prepare` reads, and how a new one is added.
+ *
+ * How a file is read (`reader.ts`):
+ * 1. Containers (`containers.ts`): gzip or zstd is undone, the text decoded, and the JSON read as
+ *    one document, or as JSON Lines whose every line is read on its own. A line that is not JSON
+ *    is reported with its number and the rest of the file is read.
+ * 2. Detection: each value (the document, or each line) is offered to the formats below in this
+ *    order and the first whose `detect` claims it converts it. A JSON array no format claims
+ *    whole is read record by record the same way. A value or record no format claims is
+ *    reported with the reason {@link unrecognizedReason} gives, never guessed at.
+ * 3. Conversion: the format's `convert` maps the value to canonical span rows (`rows.ts`), which
+ *    one emitter turns into the OTLP spans Hue reads, or hands whole traces or a collector of its
+ *    own to the context. A malformed record refuses its trace, never the file.
+ * 4. Identity (`identity.ts`): each trace's user and session are read from the emitted spans the
+ *    way Hue reads them, after `--user-key` and `--session-key` are applied.
+ *
+ * Adding a format:
+ * - Write `import-formats/<id>.ts` exporting an {@link ImportAdapter}: `detect` by distinctive
+ *   top-level keys (never a file name, never a shape another format claims), and `convert` that
+ *   maps each record to a `SpanRow` (`rows.ts`) with `context.row` (inside `readRecords`, so a bad
+ *   record refuses only its trace). Map the vendor's ids, parent, times (`nanosFrom`), kind,
+ *   model, content, tool call, usage, error, and the user and conversation the record names
+ *   (never from a tool's arguments or result); keep the whole record in `record`. Leave a field
+ *   the source does not record unset: the emitter's documented rules fill in instants and say so.
+ * - Add it to {@link importAdapters} below, and a fixture to the exclusivity test so no format
+ *   claims another's records.
+ * - `manifestFormat` stays `otlp_json` until Hue's import registration lists the new id.
+ */
+export declare const importAdapters: readonly ImportAdapter[];
+/** The format that claims a value, the first in registry order. */
+export declare const adapterFor: (value: unknown) => ImportAdapter | undefined;
+export declare const adapterById: (id: string) => ImportAdapter | undefined;
+/** Why no format claims a value. */
+export declare function unrecognizedReason(value: unknown): string;

package/dist/cli/import-formats/registry.js

@@ -0,0 +1,71 @@
+import { isObject } from "../traces-import-convert.js";
+import { agentEventAdapters } from "./agent-events.js";
+import { atif } from "./atif.js";
+import { braintrust } from "./braintrust.js";
+import { langfuse, langfuseObservations } from "./langfuse.js";
+import { langsmithRuns } from "./langsmith.js";
+import { mlflowTraces } from "./mlflow.js";
+import { opikTraces } from "./opik.js";
+import { otelFamilyAdapters } from "./otel-family.js";
+import { otlpJson } from "./otlp.js";
+import { weaveCalls } from "./weave.js";
+/**
+ * The source formats `hue traces import prepare` reads, and how a new one is added.
+ *
+ * How a file is read (`reader.ts`):
+ * 1. Containers (`containers.ts`): gzip or zstd is undone, the text decoded, and the JSON read as
+ *    one document, or as JSON Lines whose every line is read on its own. A line that is not JSON
+ *    is reported with its number and the rest of the file is read.
+ * 2. Detection: each value (the document, or each line) is offered to the formats below in this
+ *    order and the first whose `detect` claims it converts it. A JSON array no format claims
+ *    whole is read record by record the same way. A value or record no format claims is
+ *    reported with the reason {@link unrecognizedReason} gives, never guessed at.
+ * 3. Conversion: the format's `convert` maps the value to canonical span rows (`rows.ts`), which
+ *    one emitter turns into the OTLP spans Hue reads, or hands whole traces or a collector of its
+ *    own to the context. A malformed record refuses its trace, never the file.
+ * 4. Identity (`identity.ts`): each trace's user and session are read from the emitted spans the
+ *    way Hue reads them, after `--user-key` and `--session-key` are applied.
+ *
+ * Adding a format:
+ * - Write `import-formats/<id>.ts` exporting an {@link ImportAdapter}: `detect` by distinctive
+ *   top-level keys (never a file name, never a shape another format claims), and `convert` that
+ *   maps each record to a `SpanRow` (`rows.ts`) with `context.row` (inside `readRecords`, so a bad
+ *   record refuses only its trace). Map the vendor's ids, parent, times (`nanosFrom`), kind,
+ *   model, content, tool call, usage, error, and the user and conversation the record names
+ *   (never from a tool's arguments or result); keep the whole record in `record`. Leave a field
+ *   the source does not record unset: the emitter's documented rules fill in instants and say so.
+ * - Add it to {@link importAdapters} below, and a fixture to the exclusivity test so no format
+ *   claims another's records.
+ * - `manifestFormat` stays `otlp_json` until Hue's import registration lists the new id.
+ */
+export const importAdapters = [
+    otlpJson,
+    langfuseObservations,
+    langfuse,
+    atif,
+    braintrust,
+    ...otelFamilyAdapters,
+    langsmithRuns,
+    mlflowTraces,
+    opikTraces,
+    weaveCalls,
+    ...agentEventAdapters,
+];
+/** The format that claims a value, the first in registry order. */
+export const adapterFor = (value) => importAdapters.find((adapter) => adapter.detect(value));
+export const adapterById = (id) => importAdapters.find((adapter) => adapter.id === id);
+/** Why no format claims a value. */
+export function unrecognizedReason(value) {
+    if (Array.isArray(value))
+        return value.length ? "a JSON array of no recognized format" : "an empty JSON array";
+    if (!isObject(value))
+        return "not a JSON object";
+    if (Array.isArray(value.resourceLogs) || Array.isArray(value.resource_logs))
+        return "an OTLP logs export; only traces are imported";
+    if (Array.isArray(value.resourceMetrics) || Array.isArray(value.resource_metrics))
+        return "an OTLP metrics export; only traces are imported";
+    for (const key of ["data", "events", "observations"])
+        if (Array.isArray(value[key]) && !value[key].length)
+            return "an export page with no records";
+    return "a JSON document of no recognized format";
+}

package/dist/cli/import-formats/row-platform-fields.d.ts

@@ -0,0 +1,32 @@
+import { type JsonValue } from "../traces-import-convert.js";
+/**
+ * Field readers the row-platform formats (LangSmith, MLflow, Opik, W&B Weave) share: their
+ * records are JSON objects whose instants are ISO 8601 text and whose metadata names the end user
+ * and conversation under the field names applications commonly give them.
+ */
+export type JsonObject = Record<string, JsonValue>;
+export declare const object: (value: JsonValue | undefined) => JsonObject | undefined;
+export declare const text: (value: JsonValue | undefined) => string | undefined;
+/** A token count as recorded, when it is a nonnegative integer. */
+export declare const count: (value: JsonValue | undefined) => number | undefined;
+/** The first of `names` that holds an identifier in `fields`. */
+export declare function first(fields: JsonObject | undefined, names: readonly string[]): string | undefined;
+/** The end user a metadata map names: the fields Hue reads in a metadata map, in its order
+ * (`userId`, `user_id`, `langfuse_user_id`), then OpenTelemetry's `user.id` and `enduser.id`
+ * as an exporter copied them in. `user.id` beside `user.account_uuid` is a Claude Code
+ * installation, not a user, and is passed over as Hue passes it over. */
+export declare function metadataUser(metadata: JsonObject | undefined): string | undefined;
+/** The metadata fields applications name the conversation by. */
+export declare const SESSION_FIELDS: string[];
+/**
+ * An ISO 8601 instant as Unix nanoseconds: `T` or a space between date and time (Python's
+ * `str(datetime)` writes a space), up to nine fractional digits, and `Z` or an offset. An instant
+ * without a zone is UTC, as LangSmith documents its run times and its SDK reads them.
+ */
+export declare function isoNanos(value: JsonValue | undefined): bigint;
+/** A JSON value recorded as itself or as its JSON text (a column a warehouse export stores as
+ * text); text that is not JSON, or nests too deep to read, is undefined. Integers beyond
+ * JavaScript's range stay decimal text. */
+export declare function jsonOf(value: JsonValue | undefined): JsonValue | undefined;
+/** A field that must be a JSON object when present, recorded as one or as its JSON text. */
+export declare function objectField(value: JsonValue | undefined, what: string): JsonObject | undefined;

package/dist/cli/import-formats/row-platform-fields.js

@@ -0,0 +1,76 @@
+import { ConversionError, isObject, parseNestedJsonText, } from "../traces-import-convert.js";
+import { identityText } from "./identity.js";
+export const object = (value) => isObject(value) ? value : undefined;
+export const text = (value) => typeof value === "string" && value ? value : undefined;
+/** A token count as recorded, when it is a nonnegative integer. */
+export const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+/** The first of `names` that holds an identifier in `fields`. */
+export function first(fields, names) {
+    for (const name of names) {
+        const value = identityText(fields?.[name]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+/** The end user a metadata map names: the fields Hue reads in a metadata map, in its order
+ * (`userId`, `user_id`, `langfuse_user_id`), then OpenTelemetry's `user.id` and `enduser.id`
+ * as an exporter copied them in. `user.id` beside `user.account_uuid` is a Claude Code
+ * installation, not a user, and is passed over as Hue passes it over. */
+export function metadataUser(metadata) {
+    const user = first(metadata, ["userId", "user_id", "langfuse_user_id"]);
+    if (user !== undefined)
+        return user;
+    const installation = metadata?.["user.account_uuid"] !== undefined;
+    return first(metadata, installation ? ["enduser.id"] : ["user.id", "enduser.id"]);
+}
+/** The metadata fields applications name the conversation by. */
+export const SESSION_FIELDS = [
+    "session_id",
+    "sessionId",
+    "thread_id",
+    "threadId",
+    "conversation_id",
+    "conversationId",
+    "gen_ai.conversation.id",
+];
+const ISO = /^(\d{4}-\d{2}-\d{2})[Tt ](\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(?:([Zz])|([+-]\d{2}):?(\d{2}))?$/;
+/**
+ * An ISO 8601 instant as Unix nanoseconds: `T` or a space between date and time (Python's
+ * `str(datetime)` writes a space), up to nine fractional digits, and `Z` or an offset. An instant
+ * without a zone is UTC, as LangSmith documents its run times and its SDK reads them.
+ */
+export function isoNanos(value) {
+    const match = typeof value === "string" ? ISO.exec(value) : null;
+    if (!match)
+        throw new ConversionError("Invalid source timestamp");
+    const zone = match[5] ? `${match[5]}:${match[6]}` : "Z";
+    const millis = Date.parse(`${match[1]}T${match[2]}${zone}`);
+    if (!Number.isSafeInteger(millis) || millis <= 0)
+        throw new ConversionError("Invalid source timestamp");
+    return BigInt(millis) * 1000000n + BigInt((match[3] ?? "").padEnd(9, "0"));
+}
+/** A JSON value recorded as itself or as its JSON text (a column a warehouse export stores as
+ * text); text that is not JSON, or nests too deep to read, is undefined. Integers beyond
+ * JavaScript's range stay decimal text. */
+export function jsonOf(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return parseNestedJsonText(value).value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A field that must be a JSON object when present, recorded as one or as its JSON text. */
+export function objectField(value, what) {
+    if (value === undefined || value === null)
+        return undefined;
+    const parsed = jsonOf(value);
+    if (parsed === null)
+        return undefined;
+    if (!isObject(parsed))
+        throw new ConversionError(`${what} is not a JSON object`);
+    return parsed;
+}