Create README

Author: zefir-git

README.md

@@ -0,0 +1,109 @@
+# Multipart.ts
+
+A TypeScript library for multipart data parsing and creation.
+
+[**Documentation**](https://zefir-git.github.io/Multipart.ts)
+
+## Features
+
+- Parse any kind of `multipart/*`, e.g. `multipart/mixed`, `multipart/form-data`, `multipart/byteranges`, etc.
+- Create your own multipart with any parts
+- Create a Multipart instance from FormData
+- Serialise a Multipart instance into bytes (Uint8Array)
+- Works with Node.js and in the browser without any polyfills
+- Zero dependencies
+
+## Getting started
+
+Install using NPM
+
+```shell
+npm i multipart-ts
+```
+
+Import as native ESM
+
+```ts
+import {Multipart} from "multipart-ts";
+```
+
+This library uses mainly `Uint8Array` so that it works in the browser. In Node.js,
+you can use [`Buffer`](https://nodejs.org/api/buffer.html) as it is a superset of `Uint8Array`.
+In the browser, to convert a `string` to `Uint8Array` and vice-versa,
+use [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) and
+[`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) respectively.
+
+## Example
+
+### `node:http`
+
+```ts
+import http from "node:http";
+import {Component, Multipart} from "multipart-ts";
+
+http.createServer(async (req, res) => {
+    // Parse multipart request body
+    if (req.method === "POST" && req.headers["content-type"]) {
+
+        // get the request body
+        const chunks: Uint8Array[] = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        const body = Buffer.concat(chunks);
+
+        // create a multipart component to hold the content-type header (which includes the boundary) and the body
+        const component = new Component({
+                "Content-Type": req.headers["content-type"]
+            }, body);
+        // parse multipart from the component
+        const multipart = Multipart.part(component);
+        console.log(multipart);
+
+        res.end("ok");
+    }
+    // Return a multipart response
+    else if (req.method === "GET") {
+        const multipart = new Multipart(
+            [
+                new Component({
+                    "X-Foo": "Bar Baz",
+                    "Content-Type": "text/plain"
+                }, Buffer.from("Hello world!")),
+
+                // You can add nested multipart components
+                new Multipart([
+                    new Component({"Content-Type": "application/json"}, Buffer.from(JSON.stringify({foo: "bar"}))),
+                    new Component({}, [0x66, 0x6f, 0x6f, 0x20, 0x62, 0x61, 0x72])
+                ])
+            ],
+            "your-custom-boundary", // or omit to generate a random one
+            "multipart/mixed"
+        );
+        // use the content-type header generated by the multipart
+        res.setHeader("Content-Type", multipart.headers.get("Content-Type")!);
+        // send the multipart body bytes
+        res.end(multipart.body);
+    }
+    else res.end();
+}).listen(3000);
+```
+
+
+### Browser
+
+```ts
+import {Multipart, Component} from "multipart-ts";
+
+//create
+const multipart = new Multipart(
+    [new Component({"Content-Type": "text/plain"}, new TextEncoder().encode("Hello world!"))],
+    "your-custom-boundary", // or omit to generate a random one
+    "multipart/mixed"
+);
+
+// parse
+const data: Uint8Array = multipart.bytes();
+const parsed: Multipart = Multipart.parse(data);
+
+console.log(new TextDecoder().decode(parsed.parts[0].body)); // Hello world!
+```