@sdxc/structured-fields 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# @sdxc/structured-fields
+
+Parse and serialize RFC 9651 structured HTTP field values.
+
+## Installation
+
+```bash
+npm add @sdxc/structured-fields
+```
+
+Results are [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result) values, and the
+`./schema` builders compose with [`remix`](https://www.npmjs.com/package/remix)'s
+`remix/data-schema`. Both install alongside this package.
+
+[RFC 9651](https://www.rfc-editor.org/rfc/rfc9651) defines one grammar for new HTTP fields:
+`Priority`, `Cache-Status`, `RateLimit`, `Idempotency-Key`, `Repr-Digest` and the client hints
+are all a List, a Dictionary or an Item of typed bare values. This package implements the RFC's
+parsing and serialization algorithms, checked against the HTTP working group's
+[structured-field-tests](https://github.com/httpwg/structured-field-tests) suite. Every call
+names the field's top-level type (`"list"`, `"dictionary"` or `"item"`), because the RFC fixes
+it in the field's definition rather than in the text. Parsing fails the whole field on any
+error, as the RFC requires, and never returns a partial value.
+
+## Usage
+
+### Write A Field
+
+```typescript
+import { setField, stringify } from "@sdxc/structured-fields";
+
+setField(headers, "RateLimit", { limit: 10, remaining: 0, reset: 7 }, "dictionary");
+// RateLimit: limit=10, remaining=0, reset=7
+
+stringify({ value: 10, params: { w: 60 } }, "item"); // success: "10;w=60"
+```
+
+### Read The Untyped Model
+
+```typescript
+import { parse } from "@sdxc/structured-fields";
+
+let parsed = parse('ExampleCache; hit; ttl=376, "Origin"; fwd=uri-miss', "list");
+// success: [
+//   { value: Token("ExampleCache"), params: { hit: true, ttl: 376 } },
+//   { value: "Origin", params: { fwd: Token("uri-miss") } },
+// ]
+```
+
+### Read A Field Through A Schema
+
+```typescript
+import { isSuccess } from "@sdxc/result";
+import { getField } from "@sdxc/structured-fields";
+import { sf } from "@sdxc/structured-fields/schema";
+import * as s from "remix/data-schema";
+import * as checks from "remix/data-schema/checks";
+
+const PRIORITY = s.object({
+	u: s.optional(sf.value(sf.integer().pipe(checks.min(0), checks.max(7)))),
+	i: s.optional(sf.value(s.boolean())),
+});
+
+let priority = getField(request.headers, "Priority", "dictionary", PRIORITY);
+if (isSuccess(priority) && priority.data) {
+	priority.data.u; // number | undefined
+}
+```
+
+`sf.*` schemas hold no state, so declare a field's schema once at module scope.
+
+## API
+
+### `@sdxc/structured-fields`
+
+#### `parse(text, type, schema?)`
+
+Parses a field value as `type`. Without a schema it returns the model (`SF.ValueOf[type]`) or a
+`StructuredFieldParseError`. With a synchronous Standard Schema it validates the model and
+returns the schema's output, or a `ValidationError` carrying the issues. Several field lines
+joined with `,` (what `Headers#get` returns) are valid input.
+
+```typescript
+parse("u=1, i", "dictionary"); // success: { u: { value: 1, params: {} }, i: { value: true, params: {} } }
+parse("1, 2,", "list"); // failure: StructuredFieldParseError, position 5
+```
+
+#### `stringify(value, type)`
+
+Serializes to the canonical text, or fails with a `StructuredFieldStringifyError` whose `path`
+names the offending value. An empty List or Dictionary succeeds with `""`. Members may be
+written in their shorthand forms: a bare value for a member without parameters, `params`
+omitted anywhere.
+
+- A `number` that is an integer writes as an Integer (at most 15 digits), any other `number`
+  as a Decimal rounded half-to-even to three fractional digits
+- A `string` writes as a quoted sf-string, which carries printable ASCII only
+- A member or parameter whose value is `true` writes as the bare key
+- A `Date` writes as whole seconds; one with milliseconds fails
+
+```typescript
+stringify([1, 1.5, new Decimal(1)], "list"); // success: "1, 1.5, 1.0"
+stringify({ i: true, u: 3 }, "dictionary"); // success: "i, u=3"
+stringify("fü", "item"); // failure: use new DisplayString("fü")
+```
+
+#### `getField(headers, name, type, schema?)`
+
+Reads a field from `Headers` through `parse`. An absent field succeeds with `null`.
+
+#### `setField(headers, name, value, type)`
+
+Writes a field onto `Headers` through `stringify`, replacing any earlier value. An empty List or
+Dictionary deletes the field. A failure leaves `headers` untouched.
+
+#### `Token`, `Decimal`, `DisplayString`
+
+Wrappers, each holding a readonly `value`, for the bare item types a JavaScript primitive cannot
+tell apart: `new Token("HIT")` writes `HIT` where `"HIT"` writes `"HIT"`, `new Decimal(1)`
+writes `1.0`, and `new DisplayString("fü")` writes `%"f%c3%bc"`. `parse` returns them, so a
+round trip is lossless. Byte Sequences are `Uint8Array`, Dates are `Date`, Booleans are
+`boolean`.
+
+#### `StructuredFieldParseError`
+
+`position` is the offset into the field value where parsing stopped. RFC 9651 has recipients
+ignore an invalid field as a whole, so treat this failure as an absent field.
+
+#### `StructuredFieldStringifyError`
+
+`path` lists the keys and indices leading to the value with no representation, such as
+`[0, "params", "q"]`.
+
+#### `ValidationError`
+
+`remix/data-schema`'s error, re-exported so a caller branches on both failures from one import.
+`issues` holds the Standard Schema issues.
+
+#### `SF` (types)
+
+| Type                                                  | Meaning                                                                                  |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `SF.BareItem`                                         | `number \| Decimal \| string \| Token \| Uint8Array \| boolean \| Date \| DisplayString` |
+| `SF.Parameters`                                       | `Record<string, BareItem>` on a null-prototype object, in field order                    |
+| `SF.Item`                                             | `{ value, params }`                                                                      |
+| `SF.InnerList`                                        | `{ items: Item[], params }`                                                              |
+| `SF.Member`, `SF.List`, `SF.Dictionary`               | A List or Dictionary member, the List, and the Dictionary (null prototype)               |
+| `SF.FieldType`                                        | `"list" \| "dictionary" \| "item"`                                                       |
+| `SF.ValueOf`, `SF.InputOf`                            | What `parse` returns and what `stringify` accepts, per field type                        |
+| `SF.ItemInput`, `SF.InnerListInput`, `SF.MemberInput` | The shorthand member forms `stringify` accepts                                           |
+| `SF.SyncSchema<Output>`                               | A Standard Schema whose `validate` answers synchronously                                 |
+
+### `@sdxc/structured-fields/schema`
+
+#### `sf`
+
+Schema builders made with `remix/data-schema`'s `createSchema`, so they compose with
+`s.object`, `s.array`, `s.union`, `s.optional`, `.pipe()` and `.refine()`. Issues point at
+their place in the field, such as `["u", "value"]` or `[0, "items", 1, "value"]`, and carry an
+error-map code (`sf.integer`, `sf.token.allowed`, …) for localized messages.
+`StructuredFieldSchemas` is its type.
+
+| Builder                       | Accepts                           | Outputs                            |
+| ----------------------------- | --------------------------------- | ---------------------------------- |
+| `sf.integer()`                | An Integer within 15 digits       | `number`                           |
+| `sf.decimal()`                | A Decimal or an Integer           | `number`                           |
+| `sf.token(allowed?)`          | A Token, optionally one of a list | its text, narrowed to the literals |
+| `sf.displayString()`          | A Display String                  | `string`                           |
+| `sf.bytes()`                  | A Byte Sequence                   | `Uint8Array`                       |
+| `sf.date()`                   | A Date                            | `Date`                             |
+| `sf.item(value, params?)`     | An Item                           | `{ value, params }`                |
+| `sf.value(value)`             | An Item, parameters ignored       | the bare value's output            |
+| `sf.innerList(item, params?)` | An Inner List                     | `{ items, params }`                |
+
+A plain sf-string and a Boolean need no helper: `s.string()` and `s.boolean()`. Parameters and
+Dictionaries are `s.object(...)`, with `s.optional` for keys a field allows but does not
+require; the object schema's `unknownKeys` option decides what happens to the rest.
+
+## Pattern: Read RFC 9211 Cache-Status
+
+A List of cache hops, each a Token or String naming the cache, with typed parameters.
+
+```typescript
+import { getField } from "@sdxc/structured-fields";
+import { sf } from "@sdxc/structured-fields/schema";
+import * as s from "remix/data-schema";
+
+const HOP = sf.item(
+	s.union([sf.token(), s.string()]),
+	s.object({
+		hit: s.optional(s.boolean()),
+		fwd: s.optional(
+			sf.token([
+				"bypass",
+				"method",
+				"uri-miss",
+				"vary-miss",
+				"miss",
+				"request",
+				"stale",
+				"partial",
+			]),
+		),
+		ttl: s.optional(sf.integer()),
+		stored: s.optional(s.boolean()),
+	}),
+);
+
+let hops = getField(response.headers, "Cache-Status", "list", s.array(HOP));
+```
+
+## Pattern: An Idempotency-Key Item
+
+The field is an Item whose value is an sf-string. Reading unwraps it; writing quotes and escapes
+it.
+
+```typescript
+import { getField, stringify } from "@sdxc/structured-fields";
+import { sf } from "@sdxc/structured-fields/schema";
+import * as s from "remix/data-schema";
+
+let key = getField(request.headers, "Idempotency-Key", "item", sf.value(s.string()));
+let header = stringify("8e03978e-40d5-43e8-bc93-6894a57f9324", "item");
+// success: "\"8e03978e-40d5-43e8-bc93-6894a57f9324\""
+```
+
+## Pattern: Write Only The Members You Have
+
+`setField` deletes the field when the Dictionary ends up empty, so build the object from the
+values that exist and write it unconditionally.
+
+```typescript
+import { setField } from "@sdxc/structured-fields";
+
+let quota: Record<string, number> = {};
+if (limit !== null) quota.limit = limit;
+if (remaining !== null) quota.remaining = remaining;
+
+let written = setField(headers, "RateLimit", quota, "dictionary");
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published,
+written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one
+release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no
+compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/structured-fields": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every
+later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Parses and serializes RFC 9651 Structured Field Values: the grammar new HTTP fields such
+ * as `Priority`, `Cache-Status` and `Idempotency-Key` are written against, with a value
+ * model that round-trips, typed parsing through a schema, and `Headers` helpers.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { ValidationError } from "remix/data-schema";
+import type { SF } from "./lib/types.js";
+import { StructuredFieldParseError, StructuredFieldStringifyError } from "./lib/errors.js";
+export type { SF } from "./lib/types.js";
+export { StructuredFieldParseError, StructuredFieldStringifyError } from "./lib/errors.js";
+export { Decimal, DisplayString, Token } from "./lib/values.js";
+export { ValidationError };
+/**
+ * Parses a field value into the untyped model. Any error fails the whole field, as RFC 9651
+ * requires, so a failure never carries a partial value.
+ *
+ * @param text - The field value; several field lines joined with `,` (as `Headers#get` does)
+ * @param type - The top-level type the field's definition fixes
+ * @returns The model, or where the text stops being valid
+ * @example parse("u=1, i", "dictionary")
+ */
+export declare function parse<Type extends SF.FieldType>(text: string, type: Type): Result<SF.ValueOf[Type], StructuredFieldParseError>;
+/**
+ * Parses a field value, then validates the model against a schema, so the caller receives
+ * the schema's typed output or a failure naming why the field does not fit it.
+ *
+ * @param text - The field value
+ * @param type - The top-level type the field's definition fixes
+ * @param schema - A synchronous schema over the model, such as one built with `sf.*`
+ * @returns The schema's output, or a parse or validation failure
+ */
+export declare function parse<Type extends SF.FieldType, Schema extends SF.SyncSchema>(text: string, type: Type, schema: Schema): Result<StandardSchemaV1.InferOutput<Schema>, StructuredFieldParseError | ValidationError>;
+/**
+ * Serializes a value to its canonical field text. An empty List or Dictionary succeeds with
+ * `""`, which RFC 9651 reads as "do not send the field".
+ *
+ * @param value - The model, or any member written as its bare value
+ * @param type - The top-level type the field's definition fixes; a Dictionary keyed
+ *   `value` and `params` looks like an Item, so the value alone cannot say which to write
+ * @returns The text, or the path to the value with no RFC 9651 representation
+ * @example stringify({ value: 10, params: { w: 60 } }, "item") // "10;w=60"
+ */
+export declare function stringify<Type extends SF.FieldType>(value: SF.InputOf[Type], type: Type): Result<string, StructuredFieldStringifyError>;
+/**
+ * Reads a field from `Headers`. Repeated field lines arrive joined with `, `, which is how
+ * RFC 9651 combines them.
+ *
+ * @param headers - The request or response headers
+ * @param name - The field name
+ * @param type - The top-level type the field's definition fixes
+ * @returns The model, `null` when the field is absent, or why it is invalid
+ */
+export declare function getField<Type extends SF.FieldType>(headers: Headers, name: string, type: Type): Result<SF.ValueOf[Type] | null, StructuredFieldParseError>;
+/**
+ * Reads a field from `Headers` and validates it against a schema.
+ *
+ * @param headers - The request or response headers
+ * @param name - The field name
+ * @param type - The top-level type the field's definition fixes
+ * @param schema - A synchronous schema over the model
+ * @returns The schema's output, `null` when the field is absent, or why it does not fit
+ */
+export declare function getField<Type extends SF.FieldType, Schema extends SF.SyncSchema>(headers: Headers, name: string, type: Type, schema: Schema): Result<StandardSchemaV1.InferOutput<Schema> | null, StructuredFieldParseError | ValidationError>;
+/**
+ * Writes a field onto `Headers`, replacing any earlier value. An empty List or Dictionary
+ * deletes the field instead, since RFC 9651 treats an empty one as absent.
+ *
+ * @param headers - The headers to write
+ * @param name - The field name
+ * @param value - The model, or any member written as its bare value
+ * @param type - The top-level type the field's definition fixes
+ * @returns Success once written, or why the value has no representation, leaving
+ *   `headers` untouched
+ */
+export declare function setField<Type extends SF.FieldType>(headers: Headers, name: string, value: SF.InputOf[Type], type: Type): Result<void, StructuredFieldStringifyError>;

package/dist/index.js

@@ -0,0 +1,71 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { ValidationError } from "remix/data-schema";
+import { StructuredFieldParseError, StructuredFieldStringifyError } from "./lib/errors.js";
+import { parseField } from "./lib/parse.js";
+import { stringifyField } from "./lib/stringify.js";
+export { StructuredFieldParseError, StructuredFieldStringifyError } from "./lib/errors.js";
+export { Decimal, DisplayString, Token } from "./lib/values.js";
+export { ValidationError };
+export function parse(text, type, schema) {
+    let parsed = parseField(text, type);
+    if (isFailure(parsed) || schema === undefined)
+        return parsed;
+    return validateModel(parsed.data, schema);
+}
+/**
+ * Runs a schema over a parsed model. A schema that answers with a Promise despite its type
+ * fails validation, keeping every parse synchronous.
+ *
+ * @param model - The parsed field
+ * @param schema - The caller's schema
+ * @returns The schema's output, or its issues
+ */
+function validateModel(model, schema) {
+    let result = schema["~standard"].validate(model);
+    if (result instanceof Promise) {
+        return failure(new ValidationError([{ message: "Schema must validate synchronously" }]));
+    }
+    if (result.issues)
+        return failure(new ValidationError(result.issues));
+    return success(result.value);
+}
+/**
+ * Serializes a value to its canonical field text. An empty List or Dictionary succeeds with
+ * `""`, which RFC 9651 reads as "do not send the field".
+ *
+ * @param value - The model, or any member written as its bare value
+ * @param type - The top-level type the field's definition fixes; a Dictionary keyed
+ *   `value` and `params` looks like an Item, so the value alone cannot say which to write
+ * @returns The text, or the path to the value with no RFC 9651 representation
+ * @example stringify({ value: 10, params: { w: 60 } }, "item") // "10;w=60"
+ */
+export function stringify(value, type) {
+    return stringifyField(value, type);
+}
+export function getField(headers, name, type, schema) {
+    let text = headers.get(name);
+    if (text === null)
+        return success(null);
+    return schema === undefined ? parse(text, type) : parse(text, type, schema);
+}
+/**
+ * Writes a field onto `Headers`, replacing any earlier value. An empty List or Dictionary
+ * deletes the field instead, since RFC 9651 treats an empty one as absent.
+ *
+ * @param headers - The headers to write
+ * @param name - The field name
+ * @param value - The model, or any member written as its bare value
+ * @param type - The top-level type the field's definition fixes
+ * @returns Success once written, or why the value has no representation, leaving
+ *   `headers` untouched
+ */
+export function setField(headers, name, value, type) {
+    let text = stringifyField(value, type);
+    if (isFailure(text))
+        return text;
+    if (text.data === "")
+        headers.delete(name);
+    else
+        headers.set(name, text.data);
+    return success(undefined);
+}

package/dist/lib/base64.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Base64 for Byte Sequences over the platform's `atob` and `btoa`, which every runtime the
+ * package targets provides. Decoding follows the forgiving base64 algorithm, so missing
+ * padding and nonzero pad bits are accepted, as RFC 9651 section 4.2.7 asks of parsers.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Encodes bytes as padded standard base64, the canonical form RFC 9651 serializes.
+ *
+ * @param bytes - The Byte Sequence
+ * @returns Its base64 text
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Decodes standard base64 text whose characters the caller already restricted to the
+ * base64 alphabet and `=`.
+ *
+ * @param text - The text between a Byte Sequence's colons
+ * @returns The bytes, or `null` when padding sits anywhere but the end or the length
+ *   leaves a lone trailing character
+ */
+export declare function decodeBase64(text: string): Uint8Array | null;

package/dist/lib/base64.js

@@ -0,0 +1,44 @@
+/**
+ * Base64 for Byte Sequences over the platform's `atob` and `btoa`, which every runtime the
+ * package targets provides. Decoding follows the forgiving base64 algorithm, so missing
+ * padding and nonzero pad bits are accepted, as RFC 9651 section 4.2.7 asks of parsers.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Bytes converted per `String.fromCharCode` call, well under engines' argument limits. */
+const CHUNK_SIZE = 0x8000;
+/**
+ * Encodes bytes as padded standard base64, the canonical form RFC 9651 serializes.
+ *
+ * @param bytes - The Byte Sequence
+ * @returns Its base64 text
+ */
+export function encodeBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += CHUNK_SIZE) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + CHUNK_SIZE));
+    }
+    return btoa(binary);
+}
+/**
+ * Decodes standard base64 text whose characters the caller already restricted to the
+ * base64 alphabet and `=`.
+ *
+ * @param text - The text between a Byte Sequence's colons
+ * @returns The bytes, or `null` when padding sits anywhere but the end or the length
+ *   leaves a lone trailing character
+ */
+export function decodeBase64(text) {
+    let binary;
+    try {
+        binary = atob(text);
+    }
+    catch {
+        return null;
+    }
+    let bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The two failures the package reports, kept apart from the entry point so the parser
+ * and the serializer construct them without importing each other.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * The text is not a valid Structured Field of the requested type. RFC 9651 has the
+ * recipient ignore such a field as a whole, so a failure never carries a partial value.
+ */
+export declare class StructuredFieldParseError extends Error {
+    name: "StructuredFieldParseError";
+    /** Offset into the field value where parsing stopped, counting from 0. */
+    readonly position: number;
+    /**
+     * @param message - Human readable description of the failure
+     * @param position - Offset into the field value where parsing stopped
+     */
+    constructor(message: string, position: number);
+}
+/**
+ * A value has no RFC 9651 representation: a number out of range, a character outside a
+ * type's set, a key that breaks the key grammar, or a Date carrying milliseconds.
+ */
+export declare class StructuredFieldStringifyError extends Error {
+    name: "StructuredFieldStringifyError";
+    /** Where in the input the offending value sits, empty for the value itself. */
+    readonly path: Array<string | number>;
+    /**
+     * @param message - Human readable description of the failure
+     * @param path - Keys and indices leading to the offending value
+     */
+    constructor(message: string, path: Array<string | number>);
+}

package/dist/lib/errors.js

@@ -0,0 +1,41 @@
+/**
+ * The two failures the package reports, kept apart from the entry point so the parser
+ * and the serializer construct them without importing each other.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * The text is not a valid Structured Field of the requested type. RFC 9651 has the
+ * recipient ignore such a field as a whole, so a failure never carries a partial value.
+ */
+export class StructuredFieldParseError extends Error {
+    name = "StructuredFieldParseError";
+    /** Offset into the field value where parsing stopped, counting from 0. */
+    position;
+    /**
+     * @param message - Human readable description of the failure
+     * @param position - Offset into the field value where parsing stopped
+     */
+    constructor(message, position) {
+        super(`${message} at position ${position}`);
+        this.position = position;
+    }
+}
+/**
+ * A value has no RFC 9651 representation: a number out of range, a character outside a
+ * type's set, a key that breaks the key grammar, or a Date carrying milliseconds.
+ */
+export class StructuredFieldStringifyError extends Error {
+    name = "StructuredFieldStringifyError";
+    /** Where in the input the offending value sits, empty for the value itself. */
+    path;
+    /**
+     * @param message - Human readable description of the failure
+     * @param path - Keys and indices leading to the offending value
+     */
+    constructor(message, path) {
+        super(path.length === 0 ? message : `${message} at ${path.join(".")}`);
+        this.path = path;
+    }
+}

package/dist/lib/parse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The RFC 9651 section 4.2 parsing algorithms, step by step: the three top-level types,
+ * inner lists, parameters, keys and the eight bare item types. Any failure fails the whole
+ * field, so each step either returns its value or the `FAILED` marker with the reason set.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { SF } from "./types.js";
+import { StructuredFieldParseError } from "./errors.js";
+/**
+ * Parses a field value as its definition's top-level type (RFC 9651 section 4.2).
+ *
+ * @param text - The field value, several field lines joined with `,`
+ * @param type - The top-level type the field's definition fixes
+ * @returns The model, or where the text stops being valid
+ */
+export declare function parseField<Type extends SF.FieldType>(text: string, type: Type): Result<SF.ValueOf[Type], StructuredFieldParseError>;