@sdxc/structured-fields 0.0.0-pre.1

package/dist/lib/stringify.js

@@ -0,0 +1,352 @@
+import { failure, success } from "@sdxc/result";
+import { encodeBase64 } from "./base64.js";
+import { StructuredFieldStringifyError } from "./errors.js";
+import { Decimal, DisplayString, Token } from "./values.js";
+/** The largest magnitude an Integer may carry: fifteen nines. */
+const MAX_INTEGER = 999_999_999_999_999;
+/** A Decimal's integer part may carry at most twelve digits. */
+const MAX_DECIMAL_INTEGER_DIGITS = 12;
+/** The key grammar (section 3.1.2). */
+const KEY = /^[a-z*][a-z0-9_\-.*]*$/;
+/** The token grammar (section 3.3.4). */
+const TOKEN = /^[A-Za-z*][!#$%&'*+\-.^_`|~0-9A-Za-z:/]*$/;
+/** The characters an sf-string may carry: visible ASCII and space. */
+const STRING_CHARS = /^[\x20-\x7e]*$/;
+/** A UTF-16 surrogate without its pair, which has no UTF-8 encoding. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Encodes a Display String's text into the octets it percent-encodes. */
+const UTF8 = new TextEncoder();
+/**
+ * Serializes a value as its definition's top-level type (RFC 9651 section 4.1). An empty
+ * List or Dictionary serializes as `""`, which RFC 9651 reads as "do not send the field".
+ *
+ * @param value - The model, or members written in their shorthand forms
+ * @param type - The top-level type the field's definition fixes
+ * @returns The canonical text, or the path to the value with no representation
+ */
+export function stringifyField(value, type) {
+    let state = { error: null };
+    let text;
+    if (type === "list")
+        text = serializeList(value, state);
+    else if (type === "dictionary")
+        text = serializeDictionary(value, state);
+    else
+        text = serializeItem(value, [], state);
+    return state.error ? failure(state.error) : success(text);
+}
+/**
+ * Records a failure unless an earlier one is already recorded.
+ *
+ * @param state - The shared failure slot
+ * @param message - Why the value has no representation
+ * @param path - Where the value sits
+ * @returns `""`, so a serializer writes `return reject(…)`
+ */
+function reject(state, message, path) {
+    state.error ??= new StructuredFieldStringifyError(message, path);
+    return "";
+}
+/**
+ * @param value - Anything
+ * @returns Whether it is a plain object usable as Parameters or a Dictionary
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * @param value - Anything
+ * @returns Whether it is one of the bare item types
+ */
+function isBareItem(value) {
+    return (typeof value === "number" ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        value instanceof Token ||
+        value instanceof Decimal ||
+        value instanceof DisplayString ||
+        value instanceof Uint8Array ||
+        value instanceof Date);
+}
+/**
+ * @param value - A member in any accepted form
+ * @returns Whether it is an Inner List, the one form carrying `items`
+ */
+function isInnerList(value) {
+    return isRecord(value) && !isBareItem(value) && "items" in value;
+}
+/**
+ * Serializes a List (section 4.1.1), members joined by `, `.
+ *
+ * @param list - The members
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeList(list, state) {
+    if (!Array.isArray(list))
+        return reject(state, "List must be an array", []);
+    return list.map((member, index) => serializeMember(member, [index], state)).join(", ");
+}
+/**
+ * Serializes a Dictionary (section 4.1.2). A member whose value is `true` writes the
+ * bare key followed by its parameters.
+ *
+ * @param dictionary - The members, keyed
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeDictionary(dictionary, state) {
+    if (!isRecord(dictionary))
+        return reject(state, "Dictionary must be an object", []);
+    let parts = [];
+    for (let [key, member] of Object.entries(dictionary)) {
+        let text = serializeKey(key, [key], state);
+        if (member === true) {
+            parts.push(text);
+        }
+        else if (!isBareItem(member) && !isInnerList(member) && member.value === true) {
+            parts.push(text + serializeParameters(member.params, [key, "params"], state));
+        }
+        else {
+            parts.push(`${text}=${serializeMember(member, [key], state)}`);
+        }
+    }
+    return parts.join(", ");
+}
+/**
+ * Serializes a List or Dictionary member in any of its accepted forms.
+ *
+ * @param member - A bare item, an Item or an Inner List
+ * @param path - Where the member sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeMember(member, path, state) {
+    if (isInnerList(member))
+        return serializeInnerList(member, path, state);
+    return serializeItem(member, path, state);
+}
+/**
+ * Serializes an Inner List (section 4.1.1.1): items separated by spaces inside
+ * parentheses, then the list's parameters.
+ *
+ * @param list - The items and parameters
+ * @param path - Where the Inner List sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeInnerList(list, path, state) {
+    if (!Array.isArray(list.items))
+        return reject(state, "Inner List items must be an array", path);
+    let items = list.items.map((item, index) => serializeItem(item, [...path, "items", index], state));
+    return `(${items.join(" ")})${serializeParameters(list.params, [...path, "params"], state)}`;
+}
+/**
+ * Serializes an Item (section 4.1.3), written bare or with parameters.
+ *
+ * @param item - A bare item, or its value with parameters
+ * @param path - Where the Item sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeItem(item, path, state) {
+    if (isBareItem(item))
+        return serializeBareItem(item, path, state);
+    if (!isRecord(item) || !("value" in item)) {
+        return reject(state, "Expected a bare item, an Item or an Inner List", path);
+    }
+    let value = serializeBareItem(item.value, [...path, "value"], state);
+    return value + serializeParameters(item.params, [...path, "params"], state);
+}
+/**
+ * Serializes Parameters (section 4.1.1.2); a `true` value writes the bare key.
+ *
+ * @param params - The parameters, absent for none
+ * @param path - Where the parameters sit
+ * @param state - The shared failure slot
+ * @returns The text, each parameter prefixed with `;`
+ */
+function serializeParameters(params, path, state) {
+    if (params === undefined)
+        return "";
+    if (!isRecord(params))
+        return reject(state, "Parameters must be an object", path);
+    let output = "";
+    for (let key of Object.keys(params)) {
+        let value = params[key];
+        output += `;${serializeKey(key, [...path, key], state)}`;
+        if (value !== true)
+            output += `=${serializeBareItem(value, [...path, key], state)}`;
+    }
+    return output;
+}
+/**
+ * Serializes a key (section 4.1.1.3).
+ *
+ * @param key - The key
+ * @param path - Where the keyed value sits
+ * @param state - The shared failure slot
+ * @returns The key
+ */
+function serializeKey(key, path, state) {
+    if (!KEY.test(key)) {
+        return reject(state, "Key must be lowercase letters, digits, `_-.*`, first a letter or `*`", path);
+    }
+    return key;
+}
+/**
+ * Serializes a bare item (section 4.1.3.1), choosing the type from the JavaScript value.
+ * A `number` that is an integer is an Integer, and any other `number` a Decimal.
+ *
+ * @param value - The bare item
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeBareItem(value, path, state) {
+    if (typeof value === "number") {
+        return Number.isInteger(value)
+            ? serializeInteger(value, path, state)
+            : serializeDecimal(value, path, state);
+    }
+    if (value instanceof Decimal)
+        return serializeDecimal(value.value, path, state);
+    if (typeof value === "string")
+        return serializeString(value, path, state);
+    if (value instanceof Token)
+        return serializeToken(value.value, path, state);
+    if (value instanceof Uint8Array)
+        return `:${encodeBase64(value)}:`;
+    if (typeof value === "boolean")
+        return value ? "?1" : "?0";
+    if (value instanceof Date)
+        return serializeDate(value, path, state);
+    if (value instanceof DisplayString)
+        return serializeDisplayString(value.value, path, state);
+    return reject(state, "Value is not a Structured Field bare item", path);
+}
+/**
+ * Serializes an Integer (section 4.1.4), at most fifteen digits.
+ *
+ * @param value - An integral number
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The digits, `-` first when negative
+ */
+function serializeInteger(value, path, state) {
+    if (Math.abs(value) > MAX_INTEGER)
+        return reject(state, "Integer is outside ±999,999,999,999,999", path);
+    return String(value + 0);
+}
+/**
+ * Serializes a Decimal (section 4.1.5): rounded half-to-even to three fractional digits,
+ * at most twelve integer digits, trailing fractional zeros dropped but one digit kept.
+ * Rounding works on the number's shortest decimal representation, so `0.0025` rounds as
+ * the decimal text it was written as, to `0.002`.
+ *
+ * @param value - The number
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeDecimal(value, path, state) {
+    if (!Number.isFinite(value))
+        return reject(state, "Decimal must be a finite number", path);
+    let magnitude = Math.abs(value);
+    if (magnitude >= 1e12)
+        return reject(state, "Decimal has more than 12 integer digits", path);
+    let thousandths = roundToThousandths(magnitude);
+    let integer = thousandths / 1000n;
+    if (integer.toString().length > MAX_DECIMAL_INTEGER_DIGITS) {
+        return reject(state, "Decimal has more than 12 integer digits", path);
+    }
+    let fraction = (thousandths % 1000n).toString().padStart(3, "0").replace(/0+$/, "") || "0";
+    return `${value < 0 ? "-" : ""}${integer}.${fraction}`;
+}
+/**
+ * Rounds a non-negative number below 1e12 to a whole count of thousandths, half-to-even,
+ * reading its digits from `toString` so the rounding sees the decimal the caller wrote.
+ *
+ * @param magnitude - The absolute value
+ * @returns Thousandths, as a bigint to keep every digit exact
+ */
+function roundToThousandths(magnitude) {
+    if (magnitude < 1e-6)
+        return 0n;
+    let [whole = "0", fraction = ""] = magnitude.toString().split(".");
+    let kept = BigInt(whole + fraction.slice(0, 3).padEnd(3, "0"));
+    let rest = fraction.slice(3);
+    if (rest === "")
+        return kept;
+    let first = rest.charCodeAt(0) - 48;
+    let beyondHalf = /[1-9]/.test(rest.slice(1));
+    if (first > 5 || (first === 5 && (beyondHalf || kept % 2n === 1n)))
+        return kept + 1n;
+    return kept;
+}
+/**
+ * Serializes a String (section 4.1.6): visible ASCII and space, escaping `"` and `\`.
+ *
+ * @param value - The string
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The quoted text
+ */
+function serializeString(value, path, state) {
+    if (!STRING_CHARS.test(value)) {
+        return reject(state, "String may only carry visible ASCII and space; use DisplayString", path);
+    }
+    return `"${value.replace(/["\\]/g, "\\$&")}"`;
+}
+/**
+ * Serializes a Token (section 4.1.7).
+ *
+ * @param value - The token text
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The token
+ */
+function serializeToken(value, path, state) {
+    if (!TOKEN.test(value))
+        return reject(state, "Token breaks the token grammar", path);
+    return value;
+}
+/**
+ * Serializes a Date (section 4.1.10): `@` and whole seconds since the epoch.
+ *
+ * @param value - The Date
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeDate(value, path, state) {
+    let time = value.getTime();
+    if (Number.isNaN(time))
+        return reject(state, "Date is invalid", path);
+    if (time % 1000 !== 0)
+        return reject(state, "Date must be whole seconds", path);
+    return `@${serializeInteger(time / 1000, path, state)}`;
+}
+/**
+ * Serializes a Display String (section 4.1.11): `%"`, then each UTF-8 octet as itself
+ * when it is visible ASCII other than `%` and `"`, and as lowercase `%xx` otherwise.
+ *
+ * @param value - The Unicode text
+ * @param path - Where it sits
+ * @param state - The shared failure slot
+ * @returns The text
+ */
+function serializeDisplayString(value, path, state) {
+    if (LONE_SURROGATE.test(value))
+        return reject(state, "Display String has an unpaired surrogate", path);
+    let output = '%"';
+    for (let octet of UTF8.encode(value)) {
+        if (octet === 0x25 || octet === 0x22 || octet < 0x20 || octet > 0x7e) {
+            output += `%${octet.toString(16).padStart(2, "0")}`;
+        }
+        else {
+            output += String.fromCharCode(octet);
+        }
+    }
+    return `${output}"`;
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The Structured Field value model as types: what `parse` produces and what `stringify`
+ * accepts. Kept in one namespace so a caller writes `SF.Dictionary` next to the functions
+ * that read and write one.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Decimal, DisplayString, Token } from "./values.js";
+/**
+ * Groups the Structured Field value model under a single import surface.
+ */
+export declare namespace SF {
+    /**
+     * Integer and Decimal as `number` and `Decimal`, String as `string`, Token as `Token`,
+     * Byte Sequence as `Uint8Array`, Boolean as `boolean`, Date as `Date`,
+     * Display String as `DisplayString`.
+     */
+    type BareItem = number | Decimal | string | Token | Uint8Array | boolean | Date | DisplayString;
+    /** Keys in insertion order, on a null-prototype object. */
+    type Parameters = Record<string, BareItem>;
+    /**
+     * A bare item with its parameters.
+     *
+     * @template Value - The bare item type the field allows
+     */
+    interface Item<Value extends BareItem = BareItem> {
+        value: Value;
+        params: Parameters;
+    }
+    /** A parenthesized list of items, itself carrying parameters. */
+    interface InnerList {
+        items: Item[];
+        params: Parameters;
+    }
+    /** One List or Dictionary member. */
+    type Member = Item | InnerList;
+    /** Members in field order. */
+    type List = Member[];
+    /** Members keyed in field order, on a null-prototype object. */
+    type Dictionary = Record<string, Member>;
+    /** The top-level type a field's definition fixes. */
+    type FieldType = "list" | "dictionary" | "item";
+    /** The value `parse` produces for each field type. */
+    interface ValueOf {
+        list: List;
+        dictionary: Dictionary;
+        item: Item;
+    }
+    /** An Item as `stringify` accepts it, with `params` optional. */
+    interface ItemInput {
+        value: BareItem;
+        params?: Parameters;
+    }
+    /** An Inner List as `stringify` accepts it, each item bare or with parameters. */
+    interface InnerListInput {
+        items: Array<BareItem | ItemInput>;
+        params?: Parameters;
+    }
+    /**
+     * What `stringify` accepts: the parsed model, or any member written as its bare value
+     * (a member without parameters), and `params` optional everywhere.
+     */
+    type MemberInput = BareItem | ItemInput | InnerListInput;
+    /** The value `stringify` accepts for each field type. */
+    interface InputOf {
+        list: MemberInput[];
+        dictionary: Record<string, MemberInput>;
+        item: BareItem | ItemInput;
+    }
+    /**
+     * A Standard Schema whose `validate` answers synchronously, which is every
+     * `remix/data-schema` schema. Header parsing sits on hot paths that stay synchronous,
+     * so a schema with an async refinement is a type error here.
+     *
+     * @template Output - What the schema produces
+     */
+    type SyncSchema<Output = unknown> = StandardSchemaV1<unknown, Output> & {
+        readonly "~standard": {
+            validate(value: unknown, options?: StandardSchemaV1.Options): StandardSchemaV1.Result<Output>;
+        };
+    };
+}

package/dist/lib/values.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The bare item wrappers for the three RFC 9651 types a JavaScript primitive cannot tell
+ * apart from another type: Token from String, Decimal from Integer, Display String from
+ * String. Each keeps its type through a parse and stringify round trip.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * An sf-token: a bare word such as `HIT` or `text/html`, distinct from the sf-string `"HIT"`.
+ * Construction always succeeds; `stringify` checks the token grammar when it writes one.
+ */
+export declare class Token {
+    readonly value: string;
+    /**
+     * @param value - The token text, written without quotes
+     */
+    constructor(value: string);
+    /**
+     * @returns The token text, so a Token interpolates as the word it carries
+     */
+    toString(): string;
+}
+/**
+ * An sf-decimal, so `1.0` stays a Decimal through a round trip where a plain `1` would be
+ * written as an Integer. `stringify` rounds it half-to-even to three fractional digits.
+ */
+export declare class Decimal {
+    readonly value: number;
+    /**
+     * @param value - The number to write as a Decimal
+     */
+    constructor(value: number);
+    /**
+     * @returns The number, so a Decimal takes part in arithmetic and comparisons directly
+     */
+    valueOf(): number;
+}
+/**
+ * An sf-displaystring: Unicode text, written as `%"…"` with its non-ASCII UTF-8 bytes
+ * percent-encoded. A plain JavaScript string is an sf-string, which only carries ASCII.
+ */
+export declare class DisplayString {
+    readonly value: string;
+    /**
+     * @param value - The Unicode text to carry
+     */
+    constructor(value: string);
+    /**
+     * @returns The Unicode text
+     */
+    toString(): string;
+}

package/dist/lib/values.js

@@ -0,0 +1,65 @@
+/**
+ * The bare item wrappers for the three RFC 9651 types a JavaScript primitive cannot tell
+ * apart from another type: Token from String, Decimal from Integer, Display String from
+ * String. Each keeps its type through a parse and stringify round trip.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * An sf-token: a bare word such as `HIT` or `text/html`, distinct from the sf-string `"HIT"`.
+ * Construction always succeeds; `stringify` checks the token grammar when it writes one.
+ */
+export class Token {
+    value;
+    /**
+     * @param value - The token text, written without quotes
+     */
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * @returns The token text, so a Token interpolates as the word it carries
+     */
+    toString() {
+        return this.value;
+    }
+}
+/**
+ * An sf-decimal, so `1.0` stays a Decimal through a round trip where a plain `1` would be
+ * written as an Integer. `stringify` rounds it half-to-even to three fractional digits.
+ */
+export class Decimal {
+    value;
+    /**
+     * @param value - The number to write as a Decimal
+     */
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * @returns The number, so a Decimal takes part in arithmetic and comparisons directly
+     */
+    valueOf() {
+        return this.value;
+    }
+}
+/**
+ * An sf-displaystring: Unicode text, written as `%"…"` with its non-ASCII UTF-8 bytes
+ * percent-encoded. A plain JavaScript string is an sf-string, which only carries ASCII.
+ */
+export class DisplayString {
+    value;
+    /**
+     * @param value - The Unicode text to carry
+     */
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * @returns The Unicode text
+     */
+    toString() {
+        return this.value;
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,56 @@
+import type { Schema } from "remix/data-schema";
+import type { SF } from "./index.js";
+/** The schema builders, as one catalog of functions. */
+export interface StructuredFieldSchemas {
+    /** An Integer, checked against the RFC range of fifteen digits. */
+    integer(): Schema<SF.BareItem, number>;
+    /** A Decimal or Integer, output as `number`. */
+    decimal(): Schema<SF.BareItem, number>;
+    /**
+     * A Token, output as its text; with a list, narrowed to those literals.
+     *
+     * @template T - The literals the field allows
+     */
+    token<const T extends string = string>(allowed?: readonly T[]): Schema<SF.BareItem, T>;
+    /** A Display String, output as its text. A plain sf-string is `s.string()`. */
+    displayString(): Schema<SF.BareItem, string>;
+    /** A Byte Sequence. */
+    bytes(): Schema<SF.BareItem, Uint8Array>;
+    /** A Date. */
+    date(): Schema<SF.BareItem, Date>;
+    /**
+     * An Item: its bare value through `value`, its parameters through `params`, which pass
+     * through untouched when no parameter schema is given.
+     *
+     * @template V - The bare value's output
+     * @template P - The parameters' output
+     */
+    item<V, P = SF.Parameters>(value: SF.SyncSchema<V>, params?: SF.SyncSchema<P>): Schema<SF.Member, {
+        value: V;
+        params: P;
+    }>;
+    /**
+     * An Item whose parameters the caller ignores, output as its bare value alone.
+     *
+     * @template V - The bare value's output
+     */
+    value<V>(value: SF.SyncSchema<V>): Schema<SF.Member, V>;
+    /**
+     * An Inner List of items matching `item`.
+     *
+     * @template I - Each item's output
+     * @template P - The list parameters' output
+     */
+    innerList<I, P = SF.Parameters>(item: SF.SyncSchema<I>, params?: SF.SyncSchema<P>): Schema<SF.Member, {
+        items: I[];
+        params: P;
+    }>;
+}
+/**
+ * The Structured Field schema builders. Each call returns a fresh schema, and none holds
+ * state, so a field's schema is built once at module scope and reused on every request.
+ *
+ * @example s.object({ u: s.optional(sf.value(sf.integer())) })
+ * @example sf.item(sf.token(), s.object({ ttl: s.optional(sf.integer()) }))
+ */
+export declare const sf: StructuredFieldSchemas;