parse-nested-form-data 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [CHANGELOG](#changelog)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# CHANGELOG
+
+The changelog is automatically updated using
+[semantic-release](https://github.com/semantic-release/semantic-release). You
+can see it on the [releases page](../../releases).

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2022 Christian Schurr
+
+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,363 @@
+<div align="center">
+<h1>parse-nested-form-data</h1>
+
+<p>A tiny node module for parsing FormData by name into objects and arrays</p>
+</div>
+
+---
+
+<!-- prettier-ignore-start -->
+[![Build Status][build-badge]][build]
+[![Code Coverage][coverage-badge]][coverage]
+[![version][version-badge]][package]
+[![downloads][downloads-badge]][npmtrends]
+[![MIT License][license-badge]][license]
+[![All Contributors][all-contributors-badge]](#contributors-)
+[![PRs Welcome][prs-badge]][prs]
+[![Code of Conduct][coc-badge]][coc]
+<!-- prettier-ignore-end -->
+
+## The problem
+
+1.  You use Forms to upload data to your server (e.g. with remix-run)
+2.  You want a way to upload objects and arrays with booleans and numbers
+3.  You do not want to transfer the data per hand
+
+## This solution
+
+A parse functions that uses the name prop to tells the parser how to create an
+object out of the values. You can tell the parser to do not parse empty values.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Installation](#installation)
+- [Name](#name)
+  - [Boolean](#boolean)
+  - [Number](#number)
+  - [Null](#null)
+  - [Array](#array)
+  - [Object](#object)
+- [Basic Usage](#basic-usage)
+  - [Transform values](#transform-values)
+- [Advanced usage](#advanced-usage)
+  - [Options](#options)
+  - [removeEmptyString: `[boolean]`](#removeemptystring-boolean)
+  - [transformEntry: `(entry: [path: string, value: string | File], defaultTransform: DefaultTransform) => [string, string | JsonLeafValue]`](#transformentry-entry-path-string-value-string--file-defaulttransform-defaulttransform--string-string--jsonleafvalue)
+- [Issues](#issues)
+  - [🐛 Bugs](#-bugs)
+  - [💡 Feature Requests](#-feature-requests)
+- [Contributors ✨](#contributors-)
+- [LICENSE](#license)
+- [Special Thanks](#special-thanks)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Installation
+
+This module is distributed via [npm][npm] which is bundled with [node][node] and
+should be installed as one of your project's `dependencies`:
+
+```sh
+npm install parse-nested-form-data
+```
+
+## Name
+
+The name prop is used to tell the parser how to create an object out of the
+values. The name prop is a string that can contain the following characters:
+
+- `.`: to create a nested object
+- `[]`: to create an array (pushes value)
+- `[$order]`: to create an array (sets value at index and squashes array)
+- `&`: to transform the value to a boolean
+- `-`: to transform the value to null
+- `+`: to transform the value to a number
+
+### Boolean
+
+If the name prop starts with a `&` the value will be transformed to a boolean.
+
+True if the value has the following values:
+
+- `true`
+- `1`
+- `on`
+
+```ts
+const formData = new FormData()
+formData.append('&isTrue', 'true')
+formData.append('&isFalse', 'false')
+formData.append('&isTrue1', '1')
+formData.append('&isFalse1', '0')
+formData.append('&isTrue2', 'on')
+formData.append('&isFalse2', 'off')
+parseFormData(formData)
+// {
+//   isTrue: true,
+//   isFalse: false,
+//   isTrue1: true,
+//   isFalse1: false,
+//   isTrue2: true,
+//   isFalse2: false,
+// }
+```
+
+### Number
+
+If the name prop starts with a `+` the value will be transformed to a number.
+
+```ts
+const formData = new FormData()
+formData.append('+number', '1')
+formData.append('+number2', '1.1')
+formData.append('+number3', 'a')
+parseFormData(formData)
+// {
+//   number: 1,
+//   number2: 1.1,
+//   number3: NaN,
+// }
+```
+
+### Null
+
+If the name prop starts with a `-` the value will be transformed to null.
+
+```ts
+const formData = new FormData()
+formData.append('-null', 'null')
+formData.append('-ignored', 'ignored')
+parseFormData(formData)
+// {
+//   null: null,
+//   ignored: null,
+// }
+```
+
+### Array
+
+If a path of the name prop ends with `[]` the value will be pushed to an array.
+If the path of the name prop ends with `[$order]` the value will be set at the
+index of the order. Cannot be mixed with `[]`.
+
+```ts
+const formData = new FormData()
+formData.append('array[0]', '1')
+formData.append('array[1]', '2')
+formData.append('array[2]', '3')
+formData.append('array[3]', '4')
+parseFormData(formData)
+// {
+//   array: ['1', '2', '3', '4'],
+// }
+```
+
+```ts
+const formData = new FormData()
+formData.append('array[]', '1')
+formData.append('array[]', '2')
+formData.append('array[]', '3')
+parseFormData(formData)
+// {
+//   array: ['1', '2', '3'],
+// }
+```
+
+Also works with nested objects:
+
+```ts
+const formData = new FormData()
+formData.append('array[0].a', '1')
+formData.append('array[1].a', '2')
+formData.append('array[2].a', '3')
+parseFormData(formData)
+// {
+//   array: [{a: '1'}, {a: '2'}, {a: '3'}],
+// }
+```
+
+Also works with nested arrays:
+
+```ts
+const formData = new FormData()
+formData.append('array[0][]', '1')
+formData.append('array[0][]', '2')
+formData.append('array[1][]', '3')
+formData.append('array[1][]', '4')
+parseFormData(formData)
+// {
+//   array: [['1', '2'], ['3', '4']],
+// }
+```
+
+### Object
+
+If the name prop contains a `.` the value will be nested in an object.
+
+```ts
+const formData = new FormData()
+formData.append('object.a', '1')
+formData.append('object.b', '2')
+parseFormData(formData)
+// {
+//   object: {
+//     a: '1',
+//     b: '2',
+//   },
+// }
+```
+
+## Basic Usage
+
+### Transform values
+
+```ts
+const formData = new FormData()
+formData.append('+a', '1')
+formData.append('&b', 'true')
+formData.append('-c', 'null')
+formData.append('d', 'foo')
+parseFormData(formData, defaultTransform)
+// => {a: 1, b: true, c: null, d: 'foo'}
+```
+
+## Advanced usage
+
+Complex examples:
+
+```ts
+const formData = new FormData()
+formData.append('a[].b.c', '1')
+formData.append('a[].b.d', '2')
+formData.append('a[]', '3')
+formData.append('b[0]', '4')
+formData.append('+b[100]', '5')
+parseFormData(formData)
+// {
+//   a: [
+//     {
+//       b: {
+//         c: '1',
+//         d: '2',
+//       },
+//     },
+//     '3',
+//   ],
+//   b: ['4', 5],
+// }
+```
+
+### Options
+
+The second argument is an option object with following properties:
+
+### removeEmptyString: `[boolean]`
+
+_Default: `false`_
+
+If `true` empty strings will be removed from the result.
+
+```ts
+const formData = new FormData()
+formData.append('foo[1].foo', '')
+formData.append('foo[1].bar', 'test2')
+formData.append('foo[0].foo', 'test3')
+formData.append('foo[0].baz', '4')
+
+parseFormData(formData, {removeEmptyString: true})
+// {foo: [{foo: 'test3', baz: '4'}, {bar: 'test2'}]}
+```
+
+### transformEntry: `(entry: [path: string, value: string | File], defaultTransform: DefaultTransform) => [string, string | JsonLeafValue]`
+
+```ts
+const formData = new FormData()
+formData.append('a', 'a')
+formData.append('b', 'b')
+parseFormData(formData, {
+  transformEntry: ([path, value], defaultTransform) => {
+    return {
+      path,
+      value:
+        typeof value === 'string'
+          ? value.toUpperCase()
+          : defaultTransform(value),
+    }
+  },
+})
+// => {a: 'A', b: 'B'}
+```
+
+## Issues
+
+_Looking to contribute? Look for the [Good First Issue][good-first-issue]
+label._
+
+### 🐛 Bugs
+
+Please file an issue for bugs, missing documentation, or unexpected behavior.
+
+[**See Bugs**][bugs]
+
+### 💡 Feature Requests
+
+Please file an issue to suggest new features. Vote on feature requests by adding
+a 👍. This helps maintainers prioritize what to work on.
+
+[**See Feature Requests**][requests]
+
+## Contributors ✨
+
+Thanks goes to these people ([emoji key][emojis]):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+  </tr>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors][all-contributors] specification.
+Contributions of any kind welcome!
+
+## LICENSE
+
+MIT
+
+## Special Thanks
+
+Special thanks to Kent C. Dodds and his [match-sorter][match-sorter] package
+where most of the setup is from.
+
+<!-- prettier-ignore-start -->
+[npm]: https://www.npmjs.com
+[node]: https://nodejs.org
+[build-badge]: https://img.shields.io/github/workflow/status/milamer/parse-nested-form-data/validate?logo=github&style=flat-square
+[build]: https://github.com/milamer/parse-nested-form-data/actions?query=workflow%3Avalidate
+[coverage-badge]: https://img.shields.io/codecov/c/github/milamer/parse-nested-form-data.svg?style=flat-square
+[coverage]: https://codecov.io/github/milamer/parse-nested-form-data
+[version-badge]: https://img.shields.io/npm/v/parse-nested-form-data.svg?style=flat-square
+[package]: https://www.npmjs.com/package/parse-nested-form-data
+[downloads-badge]: https://img.shields.io/npm/dm/parse-nested-form-data.svg?style=flat-square
+[npmtrends]: https://www.npmtrends.com/parse-nested-form-data
+[license-badge]: https://img.shields.io/npm/l/parse-nested-form-data.svg?style=flat-square
+[license]: https://github.com/milamer/parse-nested-form-data/blob/master/LICENSE
+[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
+[prs]: http://makeapullrequest.com
+[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
+[coc]: https://github.com/milamer/parse-nested-form-data/blob/master/CODE_OF_CONDUCT.md
+[emojis]: https://github.com/all-contributors/all-contributors#emoji-key
+[all-contributors]: https://github.com/all-contributors/all-contributors
+[all-contributors-badge]: https://img.shields.io/github/all-contributors/milamer/parse-nested-form-data?color=orange&style=flat-square
+[bugs]: https://github.com/milamer/parse-nested-form-data/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3Abug
+[requests]: https://github.com/milamer/parse-nested-form-data/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement
+[good-first-issue]: https://github.com/milamer/parse-nested-form-data/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement+label%3A%22good+first+issue%22
+[match-sorter]: https://github.com/kentcdodds/match-sorter/blob/main/README.md
+<!-- prettier-ignore-end -->

package/dist/__tests__/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @name parse-nested-form-data
+ * @license MIT license.
+ * @copyright (c) 2022 Christian Schurr
+ * @author Christian Schurr <chris@schurr.dev>
+ */
+/**
+ * Thrown when a path is used multiple times or has missmatching path parts.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[0]', 'b')
+ * formData.append('a[0]', 'c')
+ * parseFormData(formData)
+ * // throws DuplicateKeyError('a[0]')
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a', 'b')
+ * formData.append('a', 'c')
+ * parseFormData(formData)
+ * // throws DuplicateKeyError('a')
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a', 'b')
+ * formData.append('a[]', 'c')
+ * parseFormData(formData)
+ * // throws DuplicateKeyError('a[]')
+ * ```
+ *
+ */
+export declare class DuplicateKeyError extends Error {
+    key: string;
+    constructor(key: string);
+}
+/**
+ * Thrown when an array is used at the same path with an order parameter and
+ * without an order parameter.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[0]', 'a')
+ * formData.append('a[]', 'b')
+ * parseFormData(formData)
+ * // => throws `MixedArrayError(a[])`
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[]', 'a')
+ * formData.append('a[0]', 'b')
+ * parseFormData(formData)
+ * // => throws `MixedArrayError(a[0])`
+ * ```
+ */
+export declare class MixedArrayError extends Error {
+    key: string;
+    constructor(key: string);
+}
+type JsonObject = {
+    [Key in string]?: JsonValue;
+};
+type JsonArray = Array<JsonValue>;
+type JsonValue = string | number | JsonObject | JsonArray | boolean | null | File;
+type JsonLeafValue = Exclude<JsonValue, JsonArray | JsonObject>;
+/**
+ * Default Transformer for `parseFormData`.
+ *
+ * Transforms a FormData Entry into a path and a `JsonLeafValue`.
+ *
+ * - `path` starts with `+` -> transform value to `number`
+ * - `path` starts with `&` -> transform value to `boolean`
+ * - `path` starts with `-` -> transform value to `null`
+ *
+ * @example
+ * ```ts
+ * const entry = ['a[0]', 'b']
+ * const result = defaultTransform(entry)
+ * // => {path: 'a[0]', value: 'b'}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const entry = ['+a[0]', '1']
+ * const result = defaultTransform(entry)
+ * // => {path: 'a[0]', value: 1}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const entry = ['&a[0]', 'true']
+ * const result = defaultTransform(entry)
+ * // => {path: 'a[0]', value: true}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const entry = ['-a[0]', 'null']
+ * const result = defaultTransform(entry)
+ * // => {path: 'a[0]', value: null}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const entry = ['a[0]', new File([''], 'file.txt')]
+ * const result = defaultTransform(entry)
+ * // => {path: 'a[0]', value: File}
+ * ```
+ *
+ *
+ * @param entry [path, value]: the FormData entry
+ * @returns the path and the transformed value
+ */
+declare function defaultTransform(entry: [path: string, value: string | File]): {
+    path: string;
+    value: JsonLeafValue;
+};
+type DefaultTransform = typeof defaultTransform;
+/**
+ * Options to change the behavior of `parseFormData`.
+ * @param transformEntry - a function to transform the FormData entry into a path and a value
+ * (default: `defaultTransform`)
+ * @param removeEmptyString - skip empty values '' (default: `false`)
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a', '')
+ * formData.append('b', 'b')
+ * const result = parseFormData(formData, {removeEmptyString: true})
+ * // => {b: 'b'}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a', 'a')
+ * formData.append('b', 'b')
+ * parseFormData(formData, {
+ *   transformEntry: ([path, value], defaultTransform) => {
+ *     return {
+ *       path,
+ *       value:
+ *         typeof value === 'string'
+ *           ? value.toUpperCase()
+ *           : defaultTransform(value),
+ *     }
+ *   },
+ * })
+ * // => {a: 'A', b: 'B'}
+ * ```
+ */
+export type ParseFormDataOptions = {
+    removeEmptyString?: boolean;
+    transformEntry?: (entry: [path: string, value: string | File], defaultTransform: DefaultTransform) => {
+        path: string;
+        value: JsonLeafValue;
+    };
+};
+/**
+ *
+ * Parses a FormData object to a JSON object. This is done by parsing the `name`
+ * attribute of each `FormDataEntryValue` and then inserting the value at the
+ * path. Also by default the start of the path is used to transform the value.
+ *
+ *
+ * In front of the whole `key`:
+ *  - `+` => parse to `Number`
+ *  - `-` => set value to `null`
+ *  - `&` => parse to `Boolean`
+ *
+ * - `.` between path parts => nest into `objects`
+ * - `[\d*]` after path part => push to array in order `\d` or push to end if `[]`
+ *
+
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('+a', '1')
+ * formData.append('&b', 'true')
+ * formData.append('-c', 'null')
+ * formData.append('d', 'foo')
+ * parseFormData(formData, defaultTransform)
+ * // => {a: 1, b: true, c: null, d: 'foo'}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a.b', 'foo')
+ * parseFormData(formData)
+ * // => {a: {b: 'foo'}}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[0]', 'foo')
+ * formData.append('a[1]', 'bar')
+ * parseFormData(formData)
+ * // => {a: ['foo', 'bar']}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[]', 'foo')
+ * formData.append('a[]', 'bar')
+ * parseFormData(formData)
+ * // => {a: ['foo', 'bar']}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[0]', 'foo')
+ * parseFormData(formData, {transformEntry: (path, value) => {path, value: value + 'bar'}})
+ * // => {a: ['foobar']}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[0]', 'foo')
+ * formData.append('a[1]', '')
+ * parseFormData(formData, {removeEmptyString: true})
+ * // => {a: ['foo']}
+ * ```
+ *
+ * @param {Iterable<[string, string | File]>} formData - an iterator of an [`path`, `value`] tuple
+ * - `path` := `^(\+|\-|\&)?([^\.]+?(\[\d*\])*)(\.[^\.]+?(\[\d*\])*)*$` (e.g. `+a[][1].b`)
+ * - `value` := `string` or `File`
+ * @param {ParseFormDataOptions} options - options for parsing the form data
+ * - `transformEntry` - a function to transform the path and the value before
+ *    inserting the value at the path in the resulting object (default: `defaultTransform`)
+ * - `removeEmptyString` - if `true` removes all entries where the value is an empty string
+ * @returns {JsonObject} the parsed JSON object
+ * @throws `DuplicateKeyError` if
+ * - a path part is an object and the path part is already defined as an object
+ * - a path part is an array and the path part is already defined as an array
+ * @throws `MixedArrayError` if at a specific path part an unordered array is
+ * defined and at a later path part an ordered array is defined or vice versa
+ * - e.g. `a[0]` and `a[]`
+ * - e.g. `a[]` and `a[0]`
+ */
+export declare function parseFormData(formData: Iterable<[string, string | File]>, { removeEmptyString, transformEntry, }?: ParseFormDataOptions): JsonObject;
+export {};