# @httpland/sfv-parser

> Structured Field Values for HTTP parser and serializer

Latest version **1.1.0** (published 2023-04-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @httpland/sfv-parser
pnpm add @httpland/sfv-parser
yarn add @httpland/sfv-parser
bun add @httpland/sfv-parser
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2023-04-14 |
| First published | 2023-04-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 140.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | miyauci |
| Keywords | http, parse, parser, header, serializer, serialize, stringify, field, rfc-8941 |

## Links

- npm: https://www.npmjs.com/package/@httpland/sfv-parser
- Repository: https://github.com/httpland/sfv-parser
- Issues: https://github.com/httpland/sfv-parser/issues
- npm.io page: https://npm.io/package/@httpland/sfv-parser

## Dependencies (2)

- [@miyauci/isx](https://npm.io/package/@miyauci/isx.md) 1.3.0
- [round-half-even](https://npm.io/package/round-half-even.md) 1.3.0

## Recent versions

- 1.1.0 (latest) — 2023-04-14
- 1.1.0-beta.1 (beta) — 2023-04-13
- 1.0.1 — 2023-04-09
- 1.0.1-beta.1 — 2023-04-09
- 1.0.0 — 2023-04-08
- 1.0.0-beta.4 — 2023-04-08
- 1.0.0-beta.3 — 2023-04-07
- 1.0.0-beta.2 — 2023-04-07
- 1.0.0-beta.1 — 2023-04-06

## README

# sfv-parser

[![deno land](http://img.shields.io/badge/available%20on-deno.land/x-lightgrey.svg?logo=deno)](https://deno.land/x/sfv_parser)
[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/sfv_parser/mod.ts)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/httpland/sfv-parser)](https://github.com/httpland/sfv-parser/releases)
[![codecov](https://codecov.io/github/httpland/sfv-parser/branch/main/graph/badge.svg)](https://codecov.io/gh/httpland/sfv-parser)
[![GitHub](https://img.shields.io/github/license/httpland/sfv-parser)](https://github.com/httpland/sfv-parser/blob/main/LICENSE)

[![test](https://github.com/httpland/sfv-parser/actions/workflows/test.yaml/badge.svg)](https://github.com/httpland/sfv-parser/actions/workflows/test.yaml)
[![NPM](https://nodei.co/npm/@httpland/sfv-parser.png?mini=true)](https://nodei.co/npm/@httpland/sfv-parser/)

**S**tructured **F**ield **V**alues for HTTP parser and serializer.

Compliant with
[RFC 8941, Structured Field Values for HTTP](https://www.rfc-editor.org/rfc/rfc8941.html#name-lists).

## Documentation

- [Structured data types](./docs/data-types.md)

## Parsing

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

```ts
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`.

```ts
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](./docs/data-types.md#sfv) into string.

```ts
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`.

```ts
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>`](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.4-3).

```ts
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](./docs/data-types.md).

This saves you the trouble of typing the `type` field.

### List

Representation of
[Rfc 8941, 3.1. Lists](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1).

```ts
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:

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

### InnerList

Representation of
[Rfc 8941, 3.1.1. Inner Lists](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1.1).

```ts
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,

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

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

yield:

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

### Parameters

Representation of
[Rfc 8941, 3.1.2. Parameters](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1.2).

```ts
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,

```ts
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:

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

### Dictionary

Representation of
[Rfc 8941, 3.2. Dictionaries](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2).

```ts
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,

```ts
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:

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

### Item

Representation of
[Rfc 8941, 3.3. Items](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3).

```ts
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,

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

declare const bareItem: BareItem;

const item = new Item(bareItem);
```

yield:

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

### Integer

Representation of
[RFC 8941, 3.3.1. Integers](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.1).

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

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

yield:

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

### Decimal

Representation of
[Rfc 8941, 3.3.2. Decimals](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.2).

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

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

yield:

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

### String

Representation of
[Rfc 8941, 3.3.3. Strings](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.3).

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

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

yield:

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

### Token

Representation of
[RFC 8941, 3.3.4. Tokens](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.4).

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

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

yield:

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

### Binary

Representation of
[Rfc 8941,3.3.5. Byte Sequences](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.5).

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

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

yield:

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

### Boolean

Representation of
[Rfc 8941, 3.3.6. Booleans](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.6).

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

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

yield:

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

## Coverage

All test cases in
[structured-field-tests](https://github.com/httpwg/structured-field-tests) have
been passed.

[All test case](./e2e_test.ts)

## API

All APIs can be found in the
[deno doc](https://doc.deno.land/https/deno.land/x/sfv_parser/mod.ts).

## License

Copyright © 2023-present [httpland](https://github.com/httpland).

Released under the [MIT](./LICENSE) license

---
_Source: https://npm.io/package/@httpland/sfv-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._