/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Duration } from "@matter/general"; import type { Metatype } from "./Metatype.js"; /** * A FieldValue represents a concrete value for a datatype. Most values are primitives but some values we encode with * specialized typed objects so we can capture the original semantic meaning. */ export type FieldValue = null | string | number | bigint | boolean | Date | Duration | FieldValue[] | FieldValue.Properties | FieldValue.Reference | FieldValue.Percent | FieldValue.Celsius | FieldValue.Bytes | FieldValue.None; /** * Create a FieldValue (or undefined) from a naked JavaScript value. * * Assumes that objects and arrays already contain valid FieldValues. */ export declare function FieldValue(value: unknown): FieldValue | undefined; export declare namespace FieldValue { const percent = "percent"; type percent = typeof percent; const celsius = "celsius"; type celsius = typeof celsius; const reference = "reference"; type reference = typeof reference; const properties = "properties"; type properties = typeof properties; const bytes = "bytes"; type bytes = typeof bytes; const none = "none"; type none = typeof none; /** * A field value that allows type extension. */ type Open = FieldValue | { type: string; }; /** * If a field value isn't a primitive type, it's an object with a type field indicating one of these types. */ type Type = percent | celsius | reference | properties | bytes | none; /** * Test for one of the special placeholder types. */ function is(value: Open | undefined, type: Type): "" | 0 | 0n | boolean | null | undefined; /** * Flag for an invalid value. Not part of the FieldValue union but returned when casting to a field value if the * cast is impossible */ const Invalid: unique symbol; type Invalid = typeof Invalid; /** * Flag for an "Undefined"/No value. Can be used in overrides to reset fields */ type None = { type: none; }; const None: None; /** * Reference to a named field */ type Reference = { type: reference; name: string; }; function Reference(name: string): Reference; /** * Celsius value, typically .1°C or .01°C */ type Celsius = { type: celsius; value: number; }; function Celsius(value: number): Celsius; /** * Percent value, units of either 1% (.01) or .01% (.0001) */ type Percent = { type: percent; value: number; }; function Percent(value: number): Percent; /** * A set of struct property values keyed by name. */ type Properties = { type: properties; properties: Record; }; /** * Byte value, encoded as hex string. */ type Bytes = { type: bytes; value: string; }; function Bytes(value: AllowSharedBufferSource | string): Bytes; /** * Convert the field value to a "defacto-standard" form. */ function serialize(value: FieldValue): string; /** * The numeric form of a value that counts something — a length, a bit position, a number of entries. * * Such a count is bounded by what a message can carry, so it states itself as a number even where a value of the * same type would need more. */ function countValue(value: Open | undefined, typeName?: string): number | undefined; /** * Given a type name as a hint, do our best to convert a field value to the number it states. * * States a `bigint` for a magnitude a number does not state exactly, which is where the values of a 64 bit type * live, so arithmetic on the result must accept either. {@link countValue} is the number-valued form. */ function numericValue(value: Open | undefined, typeName?: string): number | bigint | undefined; /** * Extract object properties from the value. */ function objectValue(value: FieldValue | undefined): Record | undefined; /** * Unwrap wrapped values, leave others as-is. */ function unwrap(value: FieldValue | undefined, typeName?: string): string | number | bigint | boolean | FieldValue[] | Date | Record | null | undefined; /** * The value a definition states, or undefined where it states none. * * An override states {@link None} to remove a value the specification states, and only validation turns the marker * into an absence, so a model that was never validated still carries it. */ function stated(value: FieldValue | undefined): FieldValue | undefined; /** * Get the referenced name if the FieldValue is a reference. */ function referenced(value: Open | undefined): string | undefined; /** * Convert an arbitrary value to a proper FieldValue. * * @param type casts to a native equivalent of this type * @param value value to cast * * @returns the cast value or FieldValue.Invalid if cast is not possible */ function cast(type: T, value: any): FieldValue | FieldValue.Invalid | undefined; } //# sourceMappingURL=FieldValue.d.ts.map