@honua/react 0.1.0-beta.0 → 0.1.2-beta.0

package/query-planner/semantic-canonical.js

@@ -0,0 +1,62 @@
+import { parseSourceSchemaV2 } from "../contract/schema.js";
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { parseSemanticQuery } from "./semantic.js";
+import { HonuaQueryPlanningError } from "./types.js";
+export const SEMANTIC_QUERY_CANONICAL_KIND = "honua.semantic-query-canonical";
+export const SEMANTIC_QUERY_CANONICAL_VERSION = 1;
+export const SEMANTIC_QUERY_HASH_DOMAIN = "honua.semantic-query.hash.v1";
+const MAX_IDENTITY_VERSION_BYTES = 4096;
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * Serialize a validated semantic query plus its schema/CRS/policy identity.
+ * Object keys are UTF-8 deterministically ordered; array order stays
+ * significant. Volatile execution state is not accepted by the semantic AST.
+ */
+export function serializeCanonicalSemanticQuery(value, options = {}) {
+    const schema = verifiedSchema(options.schema);
+    const query = parseSemanticQuery(value, {
+        ...(schema ? { schema } : {}),
+        ...(options.protocol !== undefined ? { protocol: options.protocol } : {}),
+    });
+    const identity = {
+        schemaFingerprint: schema?.fingerprint ?? null,
+        crsVersion: identityVersion(options.crsVersion, "crsVersion"),
+        policyVersion: identityVersion(options.policyVersion, "policyVersion"),
+        protocol: options.protocol ?? null,
+    };
+    return canonicalStringify(toJsonValue({
+        kind: SEMANTIC_QUERY_CANONICAL_KIND,
+        version: SEMANTIC_QUERY_CANONICAL_VERSION,
+        identity,
+        query,
+    }));
+}
+/** Return a fresh UTF-8 byte copy of the canonical semantic-query envelope. */
+export function canonicalSemanticQueryBytes(value, options = {}) {
+    return TEXT_ENCODER.encode(serializeCanonicalSemanticQuery(value, options));
+}
+/** Domain-separated SHA-256 identity for a canonical semantic query. */
+export function hashSemanticQuery(value, options = {}) {
+    return sha256(`${SEMANTIC_QUERY_HASH_DOMAIN}\n${serializeCanonicalSemanticQuery(value, options)}`);
+}
+function verifiedSchema(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return parseSourceSchemaV2(value);
+    }
+    catch {
+        throw new HonuaQueryPlanningError("invalid-query", "Canonical semantic-query identity requires a valid schema");
+    }
+}
+function identityVersion(value, name) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== "string" || value.length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", `${name} must be a non-empty string when supplied`);
+    }
+    if (TEXT_ENCODER.encode(value).byteLength > MAX_IDENTITY_VERSION_BYTES) {
+        throw new HonuaQueryPlanningError("invalid-query", `${name} exceeds the ${MAX_IDENTITY_VERSION_BYTES}-byte bound`);
+    }
+    return value;
+}

package/query-planner/semantic-compat.d.ts

@@ -0,0 +1,10 @@
+import type { LegacyWhereDialectFor, LegacyWhereProtocol, NativeFilter } from "./semantic-types.js";
+/**
+ * Convert deprecated v1 `Query.where` text into an explicitly tagged native
+ * filter. This is a migration bridge, not a protocol-neutral parser.
+ *
+ * @deprecated Build a typed semantic filter instead. Keep this only while a
+ * v1 caller still owns protocol-native `where` text.
+ */
+export declare function legacyWhereToNativeFilter<TProtocol extends LegacyWhereProtocol>(protocol: TProtocol, where: string): NativeFilter<LegacyWhereDialectFor<TProtocol>>;
+//# sourceMappingURL=semantic-compat.d.ts.map

package/query-planner/semantic-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-compat.d.ts","sourceRoot":"","sources":["../../../src/query-planner/semantic-compat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAepG;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,SAAS,mBAAmB,EAC7E,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,MAAM,GACZ,YAAY,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAsBhD"}

package/query-planner/semantic-compat.js

@@ -0,0 +1,35 @@
+import { parseSemanticQuery } from "./semantic.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const LEGACY_WHERE_DIALECT = {
+    "geoservices-feature-service": "geoservices-sql92",
+    "geoservices-map-service": "geoservices-sql92",
+    "geoservices-image-service": "geoservices-sql92",
+    "ogc-features": "cql2-text",
+    "ogc-records": "cql2-text",
+    stac: "cql2-text",
+    odata: "odata-4.0",
+    geoparquet: "duckdb-sql",
+};
+/**
+ * Convert deprecated v1 `Query.where` text into an explicitly tagged native
+ * filter. This is a migration bridge, not a protocol-neutral parser.
+ *
+ * @deprecated Build a typed semantic filter instead. Keep this only while a
+ * v1 caller still owns protocol-native `where` text.
+ */
+export function legacyWhereToNativeFilter(protocol, where) {
+    const dialect = typeof protocol === "string" && Object.prototype.hasOwnProperty.call(LEGACY_WHERE_DIALECT, protocol)
+        ? LEGACY_WHERE_DIALECT[protocol]
+        : undefined;
+    if (!dialect) {
+        throw new HonuaQueryPlanningError("unsupported-query", "The supplied protocol has no lossless raw-where compatibility dialect");
+    }
+    if (typeof where !== "string" || where.trim().length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", "Legacy raw where must be a non-empty string");
+    }
+    const query = parseSemanticQuery({
+        kind: "features",
+        filter: { kind: "native", dialect, payload: { format: "text", text: where } },
+    }, { protocol });
+    return query.filter;
+}

package/query-planner/semantic-compiler.d.ts

@@ -0,0 +1,64 @@
+import { type CrsDefinition, type ExecutableCrsBinding, type JsonPrimitive, type LogicalField, type SourceProtocol, type SourceSchemaV2 } from "../contract/schema.js";
+import type { SemanticQuery, SourceSpatiality } from "./semantic-types.js";
+/** Fidelity attached to a successful semantic compiler result. */
+export type SemanticCompilerFidelity = "exact" | "approximate";
+/** Stable reasons a valid semantic query cannot be represented by a compiler. */
+export type SemanticCompilerUnsupportedCode = "unsupported-crs" | "crs-transform-required" | "unsupported-distance" | "unsupported-field-type" | "unsupported-geometry" | "unsupported-native-filter" | "unsupported-node" | "unsupported-projection" | "unsupported-sort" | "unsupported-source";
+/** Path-addressed, deterministic unsupported outcome. */
+export interface SemanticCompilerDiagnostic {
+    readonly code: SemanticCompilerUnsupportedCode;
+    readonly path: string;
+    readonly message: string;
+}
+/** Stable fidelity loss carried beside an approximate compiled artifact. */
+export interface SemanticCompilerLoss {
+    readonly code: "spatial-envelope-reduction";
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * A compiler never silently drops a node. Valid but non-representable queries
+ * produce an explicit unsupported result; malformed queries still throw the
+ * common planning error before an artifact can be constructed.
+ */
+export type SemanticCompilationResult<TArtifact> = {
+    readonly outcome: "compiled";
+    readonly fidelity: SemanticCompilerFidelity;
+    readonly losses: readonly SemanticCompilerLoss[];
+    readonly artifact: TArtifact;
+} | {
+    readonly outcome: "unsupported";
+    readonly fidelity: "unsupported";
+    readonly diagnostics: readonly [SemanticCompilerDiagnostic, ...SemanticCompilerDiagnostic[]];
+};
+/** Ordered bind value for parameterized semantic SQL. */
+export interface SemanticSqlParameter {
+    /** One-based position matching the corresponding `?` in SQL text. */
+    readonly position: number;
+    readonly role: "literal" | "geometry" | "bbox" | "distance";
+    readonly value: JsonPrimitive;
+    readonly field?: string;
+    readonly logicalType?: string;
+}
+export type RuntimeSemanticQuery<TProtocol extends SourceProtocol> = SemanticQuery<Record<string, unknown>, TProtocol, SourceSpatiality>;
+interface SemanticCompilerBuild<TArtifact> {
+    readonly artifact: TArtifact;
+    readonly losses?: readonly SemanticCompilerLoss[];
+}
+/** @internal Verify untrusted schema/query values once at the compiler boundary. */
+export declare function prepareSemanticCompilerQuery<TProtocol extends SourceProtocol>(value: unknown, schemaValue: SourceSchemaV2, protocol: TProtocol): {
+    readonly query: RuntimeSemanticQuery<TProtocol>;
+    readonly schema: SourceSchemaV2;
+};
+/** @internal Convert compiler-local unsupported failures into the public union. */
+export declare function runSemanticCompiler<TArtifact>(compile: () => SemanticCompilerBuild<TArtifact>): SemanticCompilationResult<TArtifact>;
+/** @internal Stop compilation at an exact query path without constructing a request. */
+export declare function semanticUnsupported(code: SemanticCompilerUnsupportedCode, path: string, message: string): never;
+/** @internal Resolve one validated logical field. */
+export declare function semanticSchemaField(schema: SourceSchemaV2, name: string, path: string): LogicalField;
+/** @internal Compare executable CRS semantics without volatile provenance. */
+export declare function sameExecutableCrs(left: ExecutableCrsBinding, right: ExecutableCrsBinding): boolean;
+/** @internal Compare a requested output definition with a field binding. */
+export declare function sameCrsDefinition(left: CrsDefinition, right: CrsDefinition): boolean;
+export {};
+//# sourceMappingURL=semantic-compiler.d.ts.map

package/query-planner/semantic-compiler.d.ts.map

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

package/query-planner/semantic-compiler.js

@@ -0,0 +1,81 @@
+import { parseSourceSchemaV2, } from "../contract/schema.js";
+import { canonicalStringify, toJsonValue } from "./canonical.js";
+import { parseSemanticQuery } from "./semantic.js";
+import { HonuaQueryPlanningError } from "./types.js";
+class SemanticCompilerUnsupported extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.diagnostic = diagnostic;
+        this.name = "SemanticCompilerUnsupported";
+    }
+}
+/** @internal Verify untrusted schema/query values once at the compiler boundary. */
+export function prepareSemanticCompilerQuery(value, schemaValue, protocol) {
+    let schema;
+    try {
+        schema = parseSourceSchemaV2(schemaValue);
+    }
+    catch {
+        throw new HonuaQueryPlanningError("invalid-query", "Semantic compilation requires a valid SourceSchemaV2");
+    }
+    const query = parseSemanticQuery(value, { schema, protocol });
+    return { query, schema };
+}
+/** @internal Convert compiler-local unsupported failures into the public union. */
+export function runSemanticCompiler(compile) {
+    try {
+        const built = compile();
+        const losses = [...(built.losses ?? [])];
+        return deepFreeze({
+            outcome: "compiled",
+            fidelity: losses.length === 0 ? "exact" : "approximate",
+            losses,
+            artifact: built.artifact,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof SemanticCompilerUnsupported))
+            throw error;
+        return deepFreeze({
+            outcome: "unsupported",
+            fidelity: "unsupported",
+            diagnostics: [error.diagnostic],
+        });
+    }
+}
+/** @internal Stop compilation at an exact query path without constructing a request. */
+export function semanticUnsupported(code, path, message) {
+    throw new SemanticCompilerUnsupported({ code, path, message });
+}
+/** @internal Resolve one validated logical field. */
+export function semanticSchemaField(schema, name, path) {
+    const field = schema.fields.find((candidate) => candidate.name === name);
+    if (!field) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} references unknown schema field ${JSON.stringify(name)}`);
+    }
+    return field;
+}
+/** @internal Compare executable CRS semantics without volatile provenance. */
+export function sameExecutableCrs(left, right) {
+    return crsBindingIdentity(left) === crsBindingIdentity(right);
+}
+/** @internal Compare a requested output definition with a field binding. */
+export function sameCrsDefinition(left, right) {
+    return canonicalStringify(toJsonValue(left)) === canonicalStringify(toJsonValue(right));
+}
+function crsBindingIdentity(binding) {
+    return canonicalStringify(toJsonValue({
+        definition: binding.definition,
+        coordinateOrder: binding.coordinateOrder,
+        coordinateEpoch: binding.coordinateEpoch ?? null,
+    }));
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}

package/query-planner/semantic-literals.d.ts

@@ -0,0 +1,30 @@
+import type { LogicalField } from "../contract/schema.js";
+/** Trace from one public semantic field to its exact protocol request name. */
+export interface SemanticCompilerFieldMapping {
+    readonly logicalField: string;
+    readonly physicalPath: readonly string[];
+    readonly requestField: string;
+}
+/** @internal Record each field mapping once, in first-use order. */
+export declare function recordSemanticFieldMapping(mappings: SemanticCompilerFieldMapping[], field: LogicalField, requestField: string): void;
+/** @internal Sort mapping evidence by Unicode scalar value, independent of locale/ICU data. */
+export declare function sortSemanticFieldMappings(mappings: readonly SemanticCompilerFieldMapping[]): readonly SemanticCompilerFieldMapping[];
+/** @internal Quote one SQL-92 identifier without changing its Unicode spelling. */
+export declare function sql92Identifier(value: string, path: string): string;
+/** @internal Compile an OData structural-property path with no alias rewriting. */
+export declare function odataPropertyPath(segments: readonly string[], path: string): string;
+/** @internal SQL/OData single-quoted string literal with quote doubling. */
+export declare function quotedSemanticString(value: string, path: string): string;
+/** @internal Convert a finite JavaScript number to a deterministic non-exponent decimal. */
+export declare function finiteDecimalNumber(value: number, path: string): string;
+/** @internal Validate an exact JSON string-encoded integer or decimal. */
+export declare function exactDecimalText(value: string, path: string): string;
+/** @internal Validate one bounded, credential-free source version token. */
+export declare function verifiedSemanticSourceVersion(value: unknown, path: string): string | undefined;
+/** @internal Validate a bounded source locator string. */
+export declare function verifiedSemanticSourceText(value: unknown, path: string): string;
+/** @internal Admit already-bounded protocol-native text without URL control bytes or an empty expression. */
+export declare function verifiedSemanticNativeText(value: string, path: string, dialect: string): string;
+/** @internal Domain-separated identity of the exact request pre-image. */
+export declare function semanticRequestFingerprint(domain: string, value: unknown): `sha256:${string}`;
+//# sourceMappingURL=semantic-literals.d.ts.map

package/query-planner/semantic-literals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-literals.d.ts","sourceRoot":"","sources":["../../../src/query-planner/semantic-literals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAa1D,+EAA+E;AAC/E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oEAAoE;AACpE,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,4BAA4B,EAAE,EACxC,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAGN;AAED,+FAA+F;AAC/F,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,SAAS,4BAA4B,EAAE,CAEzC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAenF;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxE;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CASpE;AAED,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW9F;AAED,0DAA0D;AAC1D,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAU/E;AAED,6GAA6G;AAC7G,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ/F;AAED,0EAA0E;AAC1E,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,MAAM,EAAE,CAE7F"}

package/query-planner/semantic-literals.js

@@ -0,0 +1,133 @@
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { semanticUnsupported } from "./semantic-compiler.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const MAX_SOURCE_IDENTITY_TEXT = 512;
+const MAX_PHYSICAL_SEGMENT_TEXT = 512;
+const MAX_ODATA_IDENTIFIER_CODE_POINTS = 128;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: request identities and identifiers reject control bytes
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+const ODATA_IDENTIFIER = /^[_\p{ID_Start}][_\p{ID_Continue}]*$/u;
+const DECIMAL_TEXT = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+/** @internal Record each field mapping once, in first-use order. */
+export function recordSemanticFieldMapping(mappings, field, requestField) {
+    if (mappings.some((candidate) => candidate.logicalField === field.name))
+        return;
+    mappings.push({ logicalField: field.name, physicalPath: [...field.path], requestField });
+}
+/** @internal Sort mapping evidence by Unicode scalar value, independent of locale/ICU data. */
+export function sortSemanticFieldMappings(mappings) {
+    return [...mappings].sort((left, right) => compareUnicodeScalars(left.logicalField, right.logicalField));
+}
+/** @internal Quote one SQL-92 identifier without changing its Unicode spelling. */
+export function sql92Identifier(value, path) {
+    verifiedPhysicalSegment(value, path);
+    return `"${value.replace(/"/g, '""')}"`;
+}
+/** @internal Compile an OData structural-property path with no alias rewriting. */
+export function odataPropertyPath(segments, path) {
+    if (segments.length === 0) {
+        semanticUnsupported("unsupported-source", path, "OData fields require a non-empty physical property path");
+    }
+    for (const segment of segments) {
+        verifiedPhysicalSegment(segment, path);
+        if (!ODATA_IDENTIFIER.test(segment) || [...segment].length > MAX_ODATA_IDENTIFIER_CODE_POINTS) {
+            semanticUnsupported("unsupported-source", path, "OData cannot represent a physical property path segment in its bounded simple-identifier grammar");
+        }
+    }
+    return segments.join("/");
+}
+/** @internal SQL/OData single-quoted string literal with quote doubling. */
+export function quotedSemanticString(value, path) {
+    if (CONTROL_CHARACTER.test(value)) {
+        semanticUnsupported("unsupported-node", path, "Text literals containing control characters are not portable");
+    }
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** @internal Convert a finite JavaScript number to a deterministic non-exponent decimal. */
+export function finiteDecimalNumber(value, path) {
+    if (!Number.isFinite(value)) {
+        semanticUnsupported("unsupported-field-type", path, "The request dialect requires a finite numeric literal");
+    }
+    return expandExponent(Object.is(value, -0) ? "0" : String(value));
+}
+/** @internal Validate an exact JSON string-encoded integer or decimal. */
+export function exactDecimalText(value, path) {
+    if (!DECIMAL_TEXT.test(value)) {
+        semanticUnsupported("unsupported-field-type", path, "String-encoded numeric literals require a canonical non-exponent decimal");
+    }
+    return value;
+}
+/** @internal Validate one bounded, credential-free source version token. */
+export function verifiedSemanticSourceVersion(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        value.length > MAX_SOURCE_IDENTITY_TEXT ||
+        CONTROL_CHARACTER.test(value)) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} is invalid`);
+    }
+    return value;
+}
+/** @internal Validate a bounded source locator string. */
+export function verifiedSemanticSourceText(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        value.length > MAX_SOURCE_IDENTITY_TEXT ||
+        CONTROL_CHARACTER.test(value)) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} is invalid`);
+    }
+    return value;
+}
+/** @internal Admit already-bounded protocol-native text without URL control bytes or an empty expression. */
+export function verifiedSemanticNativeText(value, path, dialect) {
+    if (value.trim().length === 0) {
+        semanticUnsupported("unsupported-native-filter", path, `${dialect} native expression is empty`);
+    }
+    if (CONTROL_CHARACTER.test(value)) {
+        semanticUnsupported("unsupported-native-filter", path, `${dialect} native expression contains a control character`);
+    }
+    return value;
+}
+/** @internal Domain-separated identity of the exact request pre-image. */
+export function semanticRequestFingerprint(domain, value) {
+    return sha256(`${domain}\n${canonicalStringify(toJsonValue(value))}`);
+}
+function verifiedPhysicalSegment(value, path) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_PHYSICAL_SEGMENT_TEXT ||
+        CONTROL_CHARACTER.test(value)) {
+        semanticUnsupported("unsupported-source", path, "The physical field path contains an unsafe segment");
+    }
+}
+function expandExponent(value) {
+    const match = /^(-?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(value);
+    if (!match)
+        return value;
+    const sign = match[1] ?? "";
+    const integer = match[2] ?? "0";
+    const fraction = match[3] ?? "";
+    const exponent = Number(match[4]);
+    const digits = `${integer}${fraction}`;
+    const decimalPosition = integer.length + exponent;
+    if (decimalPosition <= 0)
+        return `${sign}0.${"0".repeat(-decimalPosition)}${digits}`;
+    if (decimalPosition >= digits.length)
+        return `${sign}${digits}${"0".repeat(decimalPosition - digits.length)}`;
+    return `${sign}${digits.slice(0, decimalPosition)}.${digits.slice(decimalPosition)}`;
+}
+function compareUnicodeScalars(left, right) {
+    const leftScalars = [...left];
+    const rightScalars = [...right];
+    const length = Math.min(leftScalars.length, rightScalars.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPoint = leftScalars[index]?.codePointAt(0) ?? 0;
+        const rightPoint = rightScalars[index]?.codePointAt(0) ?? 0;
+        if (leftPoint !== rightPoint)
+            return leftPoint < rightPoint ? -1 : 1;
+    }
+    if (leftScalars.length === rightScalars.length)
+        return 0;
+    return leftScalars.length < rightScalars.length ? -1 : 1;
+}