agentfootprint/dist/esm/lib/boundedJson.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * The UTF-8 bytes `value` serializes to — `JSON.stringify` and all its
 * escaping included: a control character or a lone surrogate is six bytes
 * (`\u0001`), a quote or a backslash two, a BMP character up to three, an
 * astral one four. THE measure for every bound stated in serialized bytes —
 * {@link copyJson}'s, the answer account's (`answer-account/size.ts`). `0`
 * for a value JSON writes nothing for (`undefined`, a function). The text
 * JSON writes holds no lone surrogate (each is escaped), so its UTF-8 length
 * is exact.
 */
export declare function jsonBytes(value: unknown): number;
/**
 * The longest prefix of `text`, in whole code points, whose JSON string form
 * (its quotes excluded) is at most `maxBytes` UTF-8 bytes — `text` itself
 * when it fits. Each code point is measured by JSON's own escaping
 * ({@link jsonBytes}), never by a second table of it.
 *
 * @example
 * ```ts
 * cutToJsonBytes('abc', 2);              // 'ab'
 * cutToJsonBytes('\u0001\u0001', 6);     // '\u0001' — JSON writes each as six bytes
 * ```
 */
export declare function cutToJsonBytes(text: string, maxBytes: number): string;
export declare function ownData(value: unknown, allowed?: readonly string[]): Record<string, unknown>;
/** A list as {@link readOwnList} read it. */
export interface OwnList {
    /** The entries read, in index order — a hole or an accessor entry is `undefined` (its getter never called). */
    readonly entries: readonly unknown[];
    /** How many entries the list holds past the bound — counted, never read. */
    readonly unread: number;
}
/**
 * Read a list the way {@link copyJson} reads an array — a plain array only
 * (`Array.prototype`), its own `length`, the own DATA property at each index —
 * as a READER that does not refuse an ordinary array: at most `maxEntries`
 * entries, a hole or an accessor entry read as `undefined` (the getter is never
 * called), and the entries past the bound counted in `unread`, never walked. It
 * never calls the list's iterator, an index getter or a method, so an ordinary
 * array from a record the library did not build cannot hide its entries or run
 * code inside the reader. `undefined` when `value` is not a plain array: the
 * caller says what that means for its own question, the conservative way.
 *
 * The guarantee covers an ordinary (non-Proxy) array and its own index
 * accessors and iterator, nothing more. A Proxy around an array passes
 * `Array.isArray`, and its traps (`getPrototypeOf`, `getOwnPropertyDescriptor`)
 * run code inside the reader and can throw out of it; a revoked Proxy throws
 * from `Array.isArray` itself. An entry is handed back as it is: a getter on an
 * entry object runs when the caller reads that property.
 *
 * @example
 * ```ts
 * const list = ['a'];
 * list.length = 3;                                                      // a hole at 1 and 2
 * Object.defineProperty(list, Symbol.iterator, { value: function* () {} }); // never called
 * readOwnList(list, 2); // { entries: ['a', undefined], unread: 1 }
 * ```
 */
export declare function readOwnList(value: unknown, maxEntries: number): OwnList | undefined;
/** JSON copy without invoking toJSON/getters or silently dropping data. */
export declare function copyJson(value: unknown, maxBytes: number, freeze: boolean, maxDepth?: number): unknown;