parse-nested-form-data 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * @author Christian Schurr <chris@schurr.dev>
  */
 /**
- * Thrown when a path is used multiple times or has missmatching path parts.
+ * Thrown when a path is used multiple times or has mismatching path parts.
  *
  * @example
  * ```ts
@@ -23,6 +23,7 @@
  * formData.append('a', 'c')
  * parseFormData(formData)
  * // throws DuplicateKeyError('a')
+ * ```
  *
  * @example
  * ```ts
@@ -35,8 +36,8 @@
  *
  */
 export declare class DuplicateKeyError extends Error {
-    key: string;
-    constructor(key: string);
+  key: string;
+  constructor(key: string);
 }
 /**
  * Thrown when an array is used at the same path with an order parameter and
@@ -61,14 +62,16 @@ export declare class DuplicateKeyError extends Error {
  * ```
  */
 export declare class MixedArrayError extends Error {
-    key: string;
-    constructor(key: string);
+  key: string;
+  constructor(key: string);
 }
 /**
- * Thrown when a path part would access or assign a property on
- * `Object.prototype` (`__proto__`, `constructor`, `prototype`). Rejected
- * regardless of whether pollution would actually occur, to keep input
- * unambiguous.
+ * Thrown when an object path part is `__proto__`, `constructor` or
+ * `prototype`, which could modify `Object.prototype`. The names are rejected
+ * at any position in the path. Entries with other names on `Object.prototype`
+ * (`toString`, ...) are removed instead (see `parseFormData`).
+ * `key` is the path up to the forbidden part, cut to 100 characters plus `...`
+ * when it's longer.
  *
  * @example
  * ```ts
@@ -79,12 +82,48 @@ export declare class MixedArrayError extends Error {
  * ```
  */
 export declare class ForbiddenKeyError extends Error {
-    key: string;
-    constructor(key: string);
+  key: string;
+  constructor(key: string);
 }
-type JsonObject = {
-    [Key in string]?: JsonValue;
-};
+/**
+ * Thrown when a path has more path parts than the `depth` option allows.
+ * `key` is the path up to the first path part over the limit, cut to
+ * 100 characters plus `...` when it's longer.
+ * Within one entry the depth is checked first, so a path that's too deep throws
+ * `DepthLimitError` even if it would also throw another error, like a
+ * `ForbiddenKeyError` for `__proto__`.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a.b[0].c', 'x')
+ * parseFormData(formData, {depth: 2})
+ * // throws DepthLimitError('a.b[0]')
+ * ```
+ */
+export declare class DepthLimitError extends Error {
+  key: string;
+  constructor(key: string);
+}
+/**
+ * Thrown when an array index in a path is larger than `4294967294`, the
+ * largest index a JavaScript array can hold.
+ * `key` is the path up to that array part, cut to 100 characters plus `...`
+ * when it's longer.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a[4294967295]', 'b')
+ * parseFormData(formData)
+ * // throws InvalidPathError('a[4294967295]')
+ * ```
+ */
+export declare class InvalidPathError 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>;
@@ -137,8 +176,8 @@ type JsonLeafValue = Exclude<JsonValue, JsonArray | JsonObject>;
  * @returns the path and the transformed value
  */
 declare function defaultTransform(entry: [path: string, value: string | File]): {
-    path: string;
-    value: JsonLeafValue;
+  path: string;
+  value: JsonLeafValue;
 };
 type DefaultTransform = typeof defaultTransform;
 /**
@@ -146,6 +185,20 @@ type DefaultTransform = typeof defaultTransform;
  * @param transformEntry - a function to transform the FormData entry into a path and a value
  * (default: `defaultTransform`)
  * @param removeEmptyString - skip empty values '' (default: `false`)
+ * @param depth - the maximum number of path parts in a path, counting every
+ * part (`a.b[0]` has 3); a positive integer or `Infinity` (default: `Infinity`).
+ * For untrusted input, `32` is recommended; 2.0 will lower the default.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
+ * formData.append('a.b', 'x')
+ * parseFormData(formData, {depth: 2})
+ * // => {a: {b: 'x'}}
+ * formData.append('a.c.d', 'y')
+ * parseFormData(formData, {depth: 2})
+ * // throws DepthLimitError('a.c.d')
+ * ```
  *
  * @example
  * ```ts
@@ -162,13 +215,11 @@ type DefaultTransform = typeof defaultTransform;
  * formData.append('a', 'a')
  * formData.append('b', 'b')
  * parseFormData(formData, {
- *   transformEntry: ([path, value], defaultTransform) => {
+ *   transformEntry: (entry, defaultTransform) => {
+ *     const {path, value} = defaultTransform(entry)
  *     return {
  *       path,
- *       value:
- *         typeof value === 'string'
- *           ? value.toUpperCase()
- *           : defaultTransform(value),
+ *       value: typeof value === 'string' ? value.toUpperCase() : value,
  *     }
  *   },
  * })
@@ -176,11 +227,12 @@ type DefaultTransform = typeof defaultTransform;
  * ```
  */
 export type ParseFormDataOptions = {
-    removeEmptyString?: boolean;
-    transformEntry?: (entry: [path: string, value: string | File], defaultTransform: DefaultTransform) => {
-        path: string;
-        value: JsonLeafValue;
-    };
+  removeEmptyString?: boolean;
+  depth?: number;
+  transformEntry?: (entry: [path: string, value: string | File], defaultTransform: DefaultTransform) => {
+    path: string;
+    value: JsonLeafValue;
+  };
 };
 /**
  *
@@ -195,9 +247,9 @@ export type ParseFormDataOptions = {
  *  - `&` => parse to `Boolean`
  *
  * - `.` between path parts => nest into `objects`
+ * - `[key]` after path part => nest into `objects`, same as `.key`; the text
+ *   in brackets is the key as it is (`a[b.c]` => key `b.c`)
  * - `[\d*]` after path part => push to array in order `\d` or push to end if `[]`
- *
-
  *
  * @example
  * ```ts
@@ -206,7 +258,7 @@ export type ParseFormDataOptions = {
  * formData.append('&b', 'true')
  * formData.append('-c', 'null')
  * formData.append('d', 'foo')
- * parseFormData(formData, defaultTransform)
+ * parseFormData(formData)
  * // => {a: 1, b: true, c: null, d: 'foo'}
  * ```
  *
@@ -221,6 +273,15 @@ export type ParseFormDataOptions = {
  * @example
  * ```ts
  * const formData = new FormData()
+ * formData.append('a[b]', 'foo')
+ * formData.append('a.c', 'bar')
+ * parseFormData(formData)
+ * // => {a: {b: 'foo', c: 'bar'}}
+ * ```
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData()
  * formData.append('a[0]', 'foo')
  * formData.append('a[1]', 'bar')
  * parseFormData(formData)
@@ -240,7 +301,12 @@ export type ParseFormDataOptions = {
  * ```ts
  * const formData = new FormData()
  * formData.append('a[0]', 'foo')
- * parseFormData(formData, {transformEntry: (path, value) => {path, value: value + 'bar'}})
+ * parseFormData(formData, {
+ *   transformEntry: ([path, value]) => ({
+ *     path,
+ *     value: typeof value === 'string' ? value + 'bar' : value,
+ *   }),
+ * })
  * // => {a: ['foobar']}
  * ```
  *
@@ -254,20 +320,49 @@ export type ParseFormDataOptions = {
  * ```
  *
  * @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`
+ * - `path` := an optional prefix (`+`, `-`, `&`), then path parts: keys after
+ *   `.` or in brackets (`[key]`), and array parts `[]` or `[\d+]` (e.g.
+ *   `+a[][1].b[c]`)
+ * - `value` := `string` or `File` (native or polyfilled `File` values are kept
+ *   as they are)
  * @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
+ * - `depth` - the maximum number of path parts in a path, counting every part
+ *   (default: `Infinity`)
  * @returns {JsonObject} the parsed JSON object
+ * @throws `TypeError` if `depth` isn't a positive integer or `Infinity`
+ * @throws `DepthLimitError` if a path has more path parts than `depth`
+ * - e.g. `a.b[0]` with `depth: 2` => `DepthLimitError('a.b[0]')`
  * @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
+ * - two entries set a value at the same path
+ *   - e.g. `a` and `a`, `a[0]` and `a[0]`, `a.b` and `a[b]`
+ * - an entry uses a path part as an object, array or value and another entry
+ *   uses it differently
+ *   - e.g. `a` and `a.b`, `a.b` and `a[]`, `a[]` and `a.b`
+ * - the path starts with an array part
+ *   - e.g. `[0]` or `[]`
  * @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]`
+ * @throws `ForbiddenKeyError` if an object path part is `__proto__`,
+ * `constructor` or `prototype`
+ * - e.g. `__proto__.polluted`
+ * @throws `InvalidPathError` if an array index is larger than `4294967294`
+ * - e.g. `a[4294967295]`
+ *
+ * Every error's `key` is the path after `transformEntry`, not the field name
+ * (e.g. `+a.b.c` with `depth: 2` => `DepthLimitError('a.b.c')`).
+ *
+ * An entry with any other object path part named like a property on
+ * `Object.prototype` (`toString`, `hasOwnProperty`, ...) is removed from the
+ * result. It's parsed like any other entry first, so it causes the same errors
+ * as an unused name: an error doesn't tell the client which properties exist
+ * on the server's `Object.prototype`.
+ * - e.g. `user.toString` => `{}`
+ * - e.g. `user[toString]` => `{}`
  */
-export declare function parseFormData(formData: Iterable<[string, string | File]>, { removeEmptyString, transformEntry, }?: ParseFormDataOptions): JsonObject;
-export {};
+export declare function parseFormData(formData: Iterable<[string, string | File]>, { removeEmptyString, transformEntry, depth }?: ParseFormDataOptions): JsonObject;
+export {};