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]);

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]);

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

Released under the MIT license