diff --git a/types/json-form-data/index.d.ts b/types/json-form-data/index.d.ts new file mode 100644 index 0000000000..6761c0908b --- /dev/null +++ b/types/json-form-data/index.d.ts @@ -0,0 +1,171 @@ +// Type definitions for json-form-data 1.5 +// Project: https://github.com/hyperatom/json-form-data +// Definitions by: Aaron Ross +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +interface ValidJSON { + [key: string]: ValidJSON | ValidJSONValue | ValidJSONValue[] | FileList; +} + +type ValidJSONValue = string | number | boolean | File | Blob | Date | null | undefined; + +/** + * Formatting options for modifying the final generated FormData object. + * + * ## Defaults + * + * const defaultOpts = { + * showLeafArrayIndexes: true, + * includeNullValues: false, + * mapping: value => { + * if (typeof value === 'boolean') { + * return +value ? '1' : '0'; + * } + * + * return value; + * } + * } + */ +interface FormatOptions { + /** + * Include index values in arrays (default: `true`). + * + * ## Examples + * + * const json = { ids: [1, 2, 3] }; + * const withArrayIndices = asFormData(json, { showLeafArrayIndex: true }); + * // => FormData { + * // ids[0]: '1', + * // ids[1]: '2', + * // ids[2]: '3', + * // } + * const withoutArrayIndices = asFormData(json, { showLeafArrayIndex: false }); + * // => FormData { + * // ids[]: '1', + * // ids[]: '2', + * // ids[]: '3', + * // } + * + */ + showLeafArrayIndexes?: boolean; + /** + * Include null values in output (default: `false`). + * + * ## Examples + * + * const json = { foo: 1, bar: null }; + * const withoutNullValues = asFormData(json, { includeNullValues: false }); + * // => FormData { + * // foo: '1' + * // } + * const withNullValues = asFormData(json, { includeNullValues: true }); + * // => FormData { + * // foo: '1' + * // bar: 'null' + * // } + * + */ + includeNullValues?: boolean; + /** + * Modify outmost leaf values before calling formData.append. Default behaviour + * is to output boolean values as '1'/'0' (true/false) and all other values + * without modification. + * + * ## Examples + * + * const json = { foo: true, bar: false }; + * const data = asFormData(json); + * // => FormData { + * // foo: '1', + * // bar: '0', + * // } + * const mapping = value => `foo_${value}`; + * const custom = asFormData(json, { mapping }); + * // => FormData { + * // foo: 'foo_true', + * // bar: 'foo_false' + * // } + * + */ + mapping?: (value: ValidJSONValue) => string | Blob; +} + +/** + * Iterate all keys/values in a JSON object (including nested values/arrays) and + * generate a FormData object with corresponding keys/values. + * + * ## Example Usage + * + * const json = { + * prop1: 'test', + * prop2: 2, + * prop3: null, + * prop4: undefined, + * prop5: true, + * prop6: false, + * prop7: new File(['file content'], 'my_file.txt'), + * prop8: { + * prop1: 'test', + * prop2: 2, + * prop3: null, + * prop4: undefined, + * prop5: true, + * prop6: false, + * prop7: [ + * 'test', + * 2, + * null, + * undefined, + * true, + * false + * ] + * } + * }; + * asFormData(json); + * + * generates the following FormData: + * + * prop1 + * test + * + * prop2 + * 2 + * + * prop5 + * 1 + * + * prop6 + * 0 + * + * prop7 + * Content-Disposition: form-data; name="My File"; filename="my_file.txt" + * Content-Type: text/plain + * + * prop8[prop1] + * test + * + * prop8[prop2] + * 2 + * + * prop8[prop5] + * 1 + * + * prop8[prop6] + * 0 + * + * prop8[prop7][0] + * test + * + * prop8[prop7][1] + * 2 + * + * prop8[prop7][2] + * 1 + * + * prop8[prop7][3] + * 0 + */ +declare const asFormData: FormDataFormatter; +type FormDataFormatter = (json: ValidJSON, opts?: FormatOptions) => FormData; + +export = asFormData; diff --git a/types/json-form-data/json-form-data-tests.ts b/types/json-form-data/json-form-data-tests.ts new file mode 100644 index 0000000000..a19f3a8788 --- /dev/null +++ b/types/json-form-data/json-form-data-tests.ts @@ -0,0 +1,28 @@ +import asFormData = require('json-form-data'); + +// $ExpectError +asFormData(); + +// $ExpectType FormData +asFormData({}); + +const json = { + prop1: 'test', + prop2: 2, + prop3: null, + prop4: undefined, + prop5: true, + prop6: false, + prop7: new File(['file content'], 'my_file.txt'), + prop8: { + prop1: 'test', + prop2: 2, + prop3: null, + prop4: undefined, + prop5: true, + prop6: false, + prop7: ['test', 2, null, undefined, true, false], + }, +}; +// $ExpectType FormData +asFormData(json); diff --git a/types/json-form-data/tsconfig.json b/types/json-form-data/tsconfig.json new file mode 100644 index 0000000000..2709dce9a9 --- /dev/null +++ b/types/json-form-data/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": ["dom", "es6"], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": ["../"], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": ["index.d.ts", "json-form-data-tests.ts"] +} diff --git a/types/json-form-data/tslint.json b/types/json-form-data/tslint.json new file mode 100644 index 0000000000..f93cf8562a --- /dev/null +++ b/types/json-form-data/tslint.json @@ -0,0 +1,3 @@ +{ + "extends": "dtslint/dt.json" +}