// The only file under src/ that may spell the platform's missing value, an optional member (`?:`), // optional chaining, or nullish coalescing. Mutation sharding assumes a flat src/ (scripts/mutate.mjs), so // this boundary stays here rather than in a subdirectory. // // Oid's brand is `string & { readonly [brand] }`. The same intersection on the platform missing value is // `never` (TypeScript 7), so it cannot carry a phantom. The brand is this file: every platform read comes // through a function here, and what leaves is Option from result.ts (the one Option). Null stays a wire value. import { none, some, type Option } from './result.js'; // The platform missing value as a test, for a hot loop where an Option per read would allocate (otel.ts flatValue). export function isMissing(value: unknown): value is undefined { return value === undefined; } // Drops only the platform missing value. Null stays Some(null). export function fromNullable(value: T): Option> { if (isMissing(value)) return none; // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the missing value is excluded; a generic T does not narrow return some(value as Exclude); } // `?.` and `??` collapse null and the platform missing value. That collapse happens here, once. export function fromNullish(value: T): Option> { if (value === null || isMissing(value)) return none; // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- null and the missing value are excluded; a generic T does not narrow return some(value as Exclude); } // A field typed as Option that a JavaScript caller omitted. A real Option passes through; omission is None. export function asOption(value: Option | undefined): Option { if (isMissing(value)) return none; return value; } // A platform API that still demands its missing value. The word stays in this file; callers pass the result on. export function unwrapOrAbsent(value: Option): T | undefined { if (value.tag === 'none') return undefined; return value.value; } // A field of any value, as `value?.[key]` read it: None when the value is not an object, lacks the field, or holds // null or the platform missing value there. The one reader for thrown values and foreign records. export function field(value: unknown, key: string): Option { if (typeof value !== 'object' || value === null || !(key in value)) return none; return fromNullish(Reflect.get(value, key)); } // A function's last parameter that a caller may leave out or pass as the platform missing value, so an optional signal // is forwarded as it is (`inner.read(offset, length, signal)`). Spread as a rest parameter: `...signal: SignalArg`. export type SignalArg = [signal?: AbortSignal | undefined]; // ---- the input edge ---- // What a caller may leave out of a record: every key optional, and an explicit missing value means the same as // leaving the key out. Entry points declare their options as Input and parse them once with withDefaults; // past that line the record is total and no code asks whether a field is there. export type Input = { readonly [K in keyof T]?: T[K] | undefined }; // Fill every key the caller left out (or passed as the missing value) from `defaults`. Keys outside `defaults` are not // read: the config's type is the schema. `defaults` is the caller's fresh record (a mutable default such as a quirks // object must not be shared between two calls), so it is filled in place and returned. // An options or spec argument after its signature default (`= {}`): a plain object. null, a number or an array is the // caller's error, answered as bad_request by the entry point that names it (#296). undefined never reaches it. export function isArgObject(value: unknown): boolean { return typeof value === 'object' && value !== null && !Array.isArray(value); } export function withDefaults(input: Input | null | undefined, defaults: T): T { if (input === null || isMissing(input)) return defaults; // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the keys of T, as Object.keys cannot type them for (const key of Object.keys(defaults) as Array) { const given = input[key]; // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Input[K] without its missing value is T[K] if (!isMissing(given)) defaults[key] = given as T[keyof T]; } return defaults; } // A record the caller owns and shares between calls (a transport's learned quirks): fill the keys it lacks in place, // so the caller's object stays the one every later call sees, and return it as the total type. export function fillIn(target: Input, defaults: T): T { // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the keys of T, as Object.keys cannot type them for (const key of Object.keys(defaults) as Array) { // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a writable view of the caller's record, filled key by key if (isMissing(target[key])) (target as { [K in keyof T]: T[K] })[key] = defaults[key]; } // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- every key of T is now present return target as T; } // Direct index read: a negative index is absent, not the element from the end (that is Array#at's other behaviour). type Indexed = ArrayLike & { at(index: number): T | undefined }; export function at(items: Indexed, index: number): Option { // A non-integer or a negative index is absent. Array#at would coerce 1.5 to 1 and wrap -1 to the last element. // Past the end is a missing read, which fromNullable turns into None (no separate length test: it would be the same result). if (!Number.isInteger(index) || index < 0) return none; return fromNullable(items.at(index)); } // Same read, with the caller's domain fallback. Does not allocate an Option (hot paths: hex tables, byte scans). export function atOr(items: Indexed, index: number, fallback: T): T { if (!Number.isInteger(index) || index < 0) return fallback; const value = items.at(index); if (isMissing(value)) return fallback; return value; } export function mapGet(table: ReadonlyMap, key: K): Option { return fromNullable(table.get(key)); } export function readKey(obj: T, key: K): Option> { return fromNullable(obj[key]); } // Invalid JSON is None. JSON null is Some(null); callers that want null as absence use fromNullish on the value. export function jsonDecode(text: string): Option { try { const value: unknown = JSON.parse(text); return fromNullable(value); } catch { return none; } } // A byte index is in [lo, hi]. Out of range, a non-integer index, and a hole are not. No Option allocation: // UTF-8 and the pack parsers ask this per byte. export function byteInRange(buf: Uint8Array, index: number, lo: number, hi: number): boolean { if (!Number.isInteger(index) || index < 0) return false; const value = buf.at(index); // Stryker disable next-line LogicalOperator: a missing byte compared with >= is false, so dropping the missing test changes no result (it is there for the type) return value !== undefined && value >= lo && value <= hi; }