@httpland/sfv-parser

sfv-parser

Structured Field Values for HTTP parser and serializer.

Compliant with RFC 8941, Structured Field Values for HTTP.

Documentation

• Structured data types

Parsing

Specify field value and field type(List, Dictionary, Item) for parser.

import { parseSfv } from "https://deno.land/x/sfv_parser@$VERSION/parse.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const result = parseSfv("sugar, tea, rum", "List");

assertEquals(result, {
  "type": "List",
  "value": [
    {
      "type": "Item",
      "value": [
        { "type": "Token", "value": "sugar" },
        { "type": "Parameters", "value": [] },
      ],
    },
    {
      "type": "Item",
      "value": [
        { "type": "Token", "value": "tea" },
        { "type": "Parameters", "value": [] },
      ],
    },
    {
      "type": "Item",
      "value": [
        { "type": "Token", "value": "rum" },
        { "type": "Parameters", "value": [] },
      ],
    },
  ],
});

Syntax error

If field value has an invalid syntax, it may throw a SyntaxError.

import { parseSfv } from "https://deno.land/x/sfv_parser@$VERSION/parse.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => parseSfv("this, is, list", "Dictionary"));

Serialization

Serialize Sfv into string.

import { stringifySfv } from "https://deno.land/x/sfv_parser@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const sfv = {
  "type": "List",
  "value": [
    {
      "type": "Item",
      "value": [
        { "type": "Token", "value": "sugar" },
        { "type": "Parameters", "value": [] },
      ],
    },
    {
      "type": "Item",
      "value": [
        { "type": "Token", "value": "tea" },
        { "type": "Parameters", "value": [] },
      ],
    },
    {
      "type": "Item",
      "value": [
        { "type": "Token", "value": "rum" },
        { "type": "Parameters", "value": [] },
      ],
    },
  ],
} as const;

assertEquals(stringifySfv(sfv), "sugar, tea, rum");

RangeError

The range of possible values for Integer and Decimal is specified. If this is violated, RangeError may be thrown.

For example, the possible values of type Integer range from -999,999,999,999,999 to 999,999,999,999,999.

import {
  Dictionary,
  Integer,
  Item,
  Parameters,
  stringifySfv,
} from "https://deno.land/x/sfv_parser@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

const sfv = new Dictionary({
  foo: new Item(
    [new Integer(10e14), new Parameters()],
  ),
});

assertThrows(() => stringifySfv(sfv));

TypeError

If Data type contains invalid characters, it may throw TypeError.

For example, Token must be compliant with <sf-token>.

import {
  Item,
  List,
  Parameters,
  stringifySfv,
  Token,
} from "https://deno.land/x/sfv_parser@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

const sfv = new List([
  new Item(
    [new Token("<invalid>"), new Parameters()],
  ),
]);

assertThrows(() => stringifySfv(sfv));

Type constructor

Provides a utility of type constructor for structured data types.

This saves you the trouble of typing the type field.

List

Representation of Rfc 8941, 3.1. Lists.

import {
  type InnerList,
  type Item,
  List,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: (Item | InnerList)[];
const list = new List(input);

yield:

{
  "type": "List",
  "value": "<Item | InnerList>[]"
}

InnerList

Representation of Rfc 8941, 3.1.1. Inner Lists.

import {
  InnerList,
  type Item,
  type Parameters,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const items: Item[];
declare const parameters: Parameters;
const innerList = new InnerList([items, parameters]);

or,

import {
  InnerList,
  type Item,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const items: Item[];
const innerList = new InnerList(items);

yield:

{
  "type": "InnerList",
  "value": ["<Item>[]", "<Parameters>"]
}

Parameters

Representation of Rfc 8941, 3.1.2. Parameters.

import {
  type BareItem,
  Parameters,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const bareItem: BareItem;
const parameters = new Parameters({
  "<key>": bareItem,
});

or,

import {
  type BareItem,
  Parameters,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const bareItem: BareItem;
const parameters = new Parameters([
  ["<key>", bareItem],
]);

yield:

{
  "type": "Boolean",
  "value": "[string, <BareItem>][]"
}

Dictionary

Representation of Rfc 8941, 3.2. Dictionaries.

import {
  Dictionary,
  type InnerList,
  type Item,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: Item | InnerList;
const dictionary = new Dictionary({ "<key>": input });

or,

import {
  Dictionary,
  type InnerList,
  type Item,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: Item | InnerList;
const dictionary = new Dictionary([
  ["<key>", input],
]);

yield:

{
  "type": "Dictionary",
  "value": "[string, <Item | InnerList>][]"
}

Item

Representation of Rfc 8941, 3.3. Items.

import {
  type BareItem,
  Item,
  type Parameters,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const bareItem: BareItem;
declare const parameters: Parameters;

const item = new Item([bareItem, parameters]);

or,

import {
  type BareItem,
  Item,
} from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const bareItem: BareItem;

const item = new Item(bareItem);

yield:

{
  "type": "Item",
  "value": ["<BareItem>", "<Parameters>"]
}

Integer

Representation of RFC 8941, 3.3.1. Integers.

import { Integer } from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: number;
const integer = new Integer(input);

yield:

{
  "type": "Integer",
  "value": "<number>"
}

Decimal

Representation of Rfc 8941, 3.3.2. Decimals.

import { Decimal } from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: number;
const decimal = new Decimal(input);

yield:

{
  "type": "Decimal",
  "value": "<number>"
}

String

Representation of Rfc 8941, 3.3.3. Strings.

import { String } from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: string;
const string = new String(input);

yield:

{
  "type": "String",
  "value": "<string>"
}

Token

Representation of RFC 8941, 3.3.4. Tokens.

import { Token } from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: string;
const token = new Token(input);

yield:

{
  "type": "Token",
  "value": "<string>"
}

Binary

Representation of Rfc 8941,3.3.5. Byte Sequences.

import { Binary } from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: Uint8Array;
const binary = new Binary(input);

yield:

{
  "type": "Binary",
  "value": "<Uint8Array>"
}

Boolean

Representation of Rfc 8941, 3.3.6. Booleans.

import { Boolean } from "https://deno.land/x/sfv_parser@$VERSION/types.ts";

declare const input: boolean;
const boolean = new Boolean(input);

yield:

{
  "type": "Boolean",
  "value": "<boolean>"
}

Coverage

All test cases in structured-field-tests have been passed.

All test case

API

All APIs can be found in the deno doc.

License

Copyright © 2023-present httpland.

Released under the MIT license