{"id":28684876,"url":"https://github.com/node-modules/formstream","last_synced_at":"2025-06-14T03:07:24.765Z","repository":{"id":5000749,"uuid":"6158982","full_name":"node-modules/formstream","owner":"node-modules","description":"multipart/form-data encoded stream, helper for file upload.","archived":false,"fork":false,"pushed_at":"2024-06-07T05:23:05.000Z","size":239,"stargazers_count":144,"open_issues_count":8,"forks_count":19,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-06-04T10:09:36.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/node-modules.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-10-10T14:52:12.000Z","updated_at":"2025-03-10T10:40:50.000Z","dependencies_parsed_at":"2024-06-06T08:36:24.616Z","dependency_job_id":"42fde633-fa32-447f-ac34-5955ee0e091b","html_url":"https://github.com/node-modules/formstream","commit_stats":{"total_commits":43,"total_committers":7,"mean_commits":6.142857142857143,"dds":0.3023255813953488,"last_synced_commit":"fbd15189e7bdbe5d6d647ffbde22503819ad18d3"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-modules%2Fformstream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-modules%2Fformstream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-modules%2Fformstream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-modules%2Fformstream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/node-modules","download_url":"https://codeload.github.com/node-modules/formstream/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-modules%2Fformstream/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258777202,"owners_count":22756066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-14T03:07:22.766Z","updated_at":"2025-06-14T03:07:24.752Z","avatar_url":"https://github.com/node-modules.png","language":"JavaScript","readme":"# formstream\n\n[![NPM version][npm-image]][npm-url]\n[![CI](https://github.com/node-modules/formstream/actions/workflows/ci.yml/badge.svg)](https://github.com/node-modules/formstream/actions/workflows/ci.yml)\n[![Test coverage][codecov-image]][codecov-url]\n[![npm download][download-image]][download-url]\n\n[npm-image]: https://img.shields.io/npm/v/formstream.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/formstream\n[codecov-image]: https://codecov.io/github/node-modules/formstream/coverage.svg?branch=master\n[codecov-url]: https://codecov.io/github/node-modules/formstream?branch=master\n[download-image]: https://img.shields.io/npm/dm/formstream.svg?style=flat-square\n[download-url]: https://npmjs.org/package/formstream\n\nA [multipart/form-data](http://tools.ietf.org/html/rfc2388) encoded stream, helper for file upload.\n\n## Install\n\n```bash\nnpm install formstream\n```\n\n## Quick Start\n\n```js\nvar formstream = require('formstream');\nvar http = require('http');\n\nvar form = formstream();\n\n// form.file('file', filepath, filename);\nform.file('file', './logo.png', 'upload-logo.png');\n\n// other form fields\nform.field('foo', 'fengmk2').field('love', 'aerdeng');\n\n// even send file content buffer directly\n// form.buffer(name, buffer, filename, mimeType)\nform.buffer('file2', new Buffer('This is file2 content.'), 'foo.txt');\n\nvar options = {\n  method: 'POST',\n  host: 'upload.cnodejs.net',\n  path: '/store',\n  headers: form.headers()\n};\nvar req = http.request(options, function (res) {\n  console.log('Status: %s', res.statusCode);\n  res.on('data', function (data) {\n    console.log(data.toString());\n  });\n});\n\nform.pipe(req);\n```\n\n### Chaining\n\n```js\nvar fs = require('fs');\nvar formstream = require('formstream');\n\nvar filepath = './logo.png';\nfs.stat(filepath, function (err, stat) {\n  formstream()\n    .field('status', 'share picture')\n    .field('access_token', 'your access token')\n    .file('pic', filepath, 'logo.png', stat.size)\n    .pipe(process.stdout); // your request stream\n});\n```\n\n### Set min chunk buffer size\n\nSome web servers have a limit on the number of chunks, and you can set `minChunkSize` to ensure the size of chunk sent to the server.\n\n```js\nvar fs = require('fs');\nvar FormStream = require('formstream');\n\nvar filepath = './big-file.zip';\nfs.stat(filepath, function (err, stat) {\n  new FormStream({\n    // send \u003e= 2MB chunk buffer size to the server\n    minChunkSize: 1024 * 1024 * 2,\n  }).field('status', 'share file')\n    .field('access_token', 'your access token')\n    .file('file', filepath, 'big-file.zip', stat.size)\n    .pipe(process.stdout); // your request stream\n});\n```\n\n## API Doc\n\n### formstream([options])\n\nCreate a form instance.\n\n#### Arguments\n\n- **options.minChunkSize** Number - min chunk size to emit data event\n\n#### Returns\n\nForm - form instance\n\n### FormStream#field(name, value)\n\nAdd a normal field to the form.\n\n#### Arguments\n\n- **name** String - Name of field\n- **value** String - Value of field\n\n#### Returns\n\nForm - form instance\n\n### FormStream#file(name, filepath[, filename][, filesize])\n\nAdd a local file to be uploaded to the form.\n\n#### Arguments\n\n- **name** String - Name of file field\n- **filepath** String - Local path of the file to be uploaded\n- ***filename*** String - Optional. Name of the file (will be the base name of `filepath` if empty)\n- ***filesize*** Number - Optional. Size of the file (will not generate `Content-Length` header if not specified)\n\n#### Returns\n\nForm - form instance\n\n### FormStream#buffer(name, buffer, filename[, contentType])\n\nAdd a buffer as a file to upload.\n\n#### Arguments\n\n- **name** String - Name of field\n- **buffer** Buffer - The buffer to be uploaded\n- **filename** String - The file name that tells the remote server\n- ***contentType*** String - Optional. Content-Type (aka. MIME Type) of content (will be infered with `filename` if empty)\n\n#### Returns\n\nForm - form instance\n\n### FormStream#stream(name, stream, filename[, contentType][, size])\n\nAdd a readable stream as a file to upload. Event 'error' will be emitted if an error occured.\n\n#### Arguments\n\n- **name** String - Name of field\n- **stream** [stream.Readable](http://nodejs.org/api/stream.html#stream_class_stream_readable) - A readable stream to be piped\n- **filename** String - The file name that tells the remote server\n- ***contentType*** String - Optional. Content-Type (aka. MIME Type) of content (will be infered with `filename` if empty)\n- ***size*** Number - Optional. Size of the stream (will not generate `Content-Length` header if not specified)\n\n#### Returns\n\nForm - form instance\n\n### FormStream#headers([headers])\n\nGet headers for the request.\n\n#### Arguments\n\n- **headers** Object - Additional headers\n\n#### Example\n\n```js\nvar headers = form.headers({\n  'Authorization': 'Bearer kei2akc92jmznvnkeh09sknzdk',\n  'Accept': 'application/vnd.github.v3.full+json'\n});\n```\n\n#### Returns\n\nObject - Headers to be sent.\n\n### Event 'error'\n\nEmitted if there was an error receiving data.\n\n### Event 'data'\n\nThe 'data' event emits when a Buffer was used.\n\nSee [Node.js Documentation](http://nodejs.org/api/stream.html#stream_event_data) for more.\n\n### Event 'end'\n\nEmitted when the stream has received no more 'data' events will happen.\n\nSee [Node.js Documentation](http://nodejs.org/api/stream.html#stream_event_end) for more.\n\n## License\n\n[MIT](LICENSE)\n\n\u003c!-- GITCONTRIBUTOR_START --\u003e\n\n## Contributors\n\n|[\u003cimg src=\"https://avatars.githubusercontent.com/u/156269?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003efengmk2\u003c/b\u003e\u003c/sub\u003e](https://github.com/fengmk2)\u003cbr/\u003e|[\u003cimg src=\"https://avatars.githubusercontent.com/u/288288?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003exingrz\u003c/b\u003e\u003c/sub\u003e](https://github.com/xingrz)\u003cbr/\u003e|[\u003cimg src=\"https://avatars.githubusercontent.com/u/32174276?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003esemantic-release-bot\u003c/b\u003e\u003c/sub\u003e](https://github.com/semantic-release-bot)\u003cbr/\u003e|[\u003cimg src=\"https://avatars.githubusercontent.com/u/13151189?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003efjc0k\u003c/b\u003e\u003c/sub\u003e](https://github.com/fjc0k)\u003cbr/\u003e|[\u003cimg src=\"https://avatars.githubusercontent.com/u/18096247?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003emrspeiser\u003c/b\u003e\u003c/sub\u003e](https://github.com/mrspeiser)\u003cbr/\u003e|[\u003cimg src=\"https://avatars.githubusercontent.com/u/985607?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003edead-horse\u003c/b\u003e\u003c/sub\u003e](https://github.com/dead-horse)\u003cbr/\u003e|\n| :---: | :---: | :---: | :---: | :---: | :---: |\n[\u003cimg src=\"https://avatars.githubusercontent.com/u/7326406?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eshaozj\u003c/b\u003e\u003c/sub\u003e](https://github.com/shaozj)\u003cbr/\u003e\n\nThis project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Wed May 15 2024 00:34:12 GMT+0800`.\n\n\u003c!-- GITCONTRIBUTOR_END --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnode-modules%2Fformstream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnode-modules%2Fformstream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnode-modules%2Fformstream/lists"}