move docs to jsdoc and rewrite the core to use buffers

Author: talentlessguy

.vscode/settings.json

@@ -9,4 +9,4 @@
     "source.organizeImports.biome": "explicit"
   },
   "typescript.tsdk": "node_modules/typescript/lib"
-}
+}

README.md

@@ -49,48 +49,6 @@ const server = createServer(async (req: ReqWithBody, res) => {
 })
 ```
 
-## API
-
-### `raw(req, res, cb)`
-
-Minimal body parsing without any formatting.
-
-### `text(req, res, cb)`
-
-Converts request body to string.
-
-### `urlencoded(req, res, cb)`
-
-Parses request body using `new URLSearchParams`.
-
-### `json(req, res, cb)`
-
-Parses request body using `JSON.parse`.
-
-### `multipart(req, res, cb)`
-
-Parses request body using `multipart/form-data` content type and boundary. Supports files as well.
-
-```js
-// curl -F "textfield=textfield" -F "someother=textfield with text" localhost:3000
-await multipart()(req, res, (err) => void err && console.log(err))
-res.end(req.body) // { textfield: ["textfield"], someother: ["textfield with text"] }
-```
-
-### `custom(fn)(req, res, cb)`
-
-Custom function for `parsec`.
-
-```js
-// curl -d "this text must be uppercased" localhost:3000
-await custom(
-  req,
-  (d) => d.toUpperCase(),
-  (err) => {}
-)
-res.end(req.body) // "THIS TEXT MUST BE UPPERCASED"
-```
-
 ### What is "parsec"?
 
 The parsec is a unit of length used to measure large distances to astronomical objects outside the Solar System.

src/index.ts

@@ -1,12 +1,14 @@
-import type { EventEmitter } from 'node:events'
+import { Buffer } from 'node:buffer'
 import type { IncomingMessage, ServerResponse as Response } from 'node:http'
 
 type NextFunction = (err?: any) => void
 
-// Extend the request object with body
+/**
+ * Request extension with a body
+ */
 export type ReqWithBody<T = any> = IncomingMessage & {
   body?: T
-} & EventEmitter
+}
 
 export const hasBody = (method: string) => ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)
 
@@ -15,45 +17,76 @@ const defaultPayloadLimit = 104857600 // 100KB
 export type LimitErrorFn = (limit: number) => Error
 
 export type ParserOptions = Partial<{
+  /**
+   * Limit payload size (in bytes)
+   * @default '100KB'
+   */
   payloadLimit: number
+  /**
+   * Custom error function for payload limit
+   */
   payloadLimitErrorFn: LimitErrorFn
 }>
 
 const defaultErrorFn: LimitErrorFn = (payloadLimit) => new Error(`Payload too large. Limit: ${payloadLimit} bytes`)
 
 // Main function
 export const p =
-  <T = any>(fn: (body: any) => any, payloadLimit = defaultPayloadLimit, payloadLimitErrorFn: LimitErrorFn = defaultErrorFn) =>
+  <T = any>(
+    fn: (body: Buffer) => void,
+    payloadLimit = defaultPayloadLimit,
+    payloadLimitErrorFn: LimitErrorFn = defaultErrorFn
+  ) =>
     async (req: ReqWithBody<T>, _res: Response, next: (err?: any) => void) => {
       try {
-        let body = ''
+        const body: Buffer[] = []
 
         for await (const chunk of req) {
-          if (body.length > payloadLimit) throw payloadLimitErrorFn(payloadLimit)
-          body += chunk
+          const totalSize = body.reduce((total, buffer) => total + buffer.byteLength, 0)
+          if (totalSize > payloadLimit) throw payloadLimitErrorFn(payloadLimit)
+          body.push(chunk as Buffer)
         }
 
-        return fn(body)
+        return fn(Buffer.concat(body))
       } catch (e) {
         next(e)
       }
     }
 
+/**
+ * Parse payload with a custom function
+ * @param fn
+ */
 const custom =
-  <T = any>(fn: (body: any) => any) =>
+  <T = any>(fn: (body: Buffer) => any) =>
     async (req: ReqWithBody, _res: Response, next: NextFunction) => {
       if (hasBody(req.method!)) req.body = await p<T>(fn)(req, _res, next)
       next()
     }
 
+/**
+ * Parse JSON payload
+ * @param options
+ */
 const json =
   ({ payloadLimit, payloadLimitErrorFn }: ParserOptions = {}) =>
     async (req: ReqWithBody, res: Response, next: NextFunction) => {
       if (hasBody(req.method!)) {
-        req.body = await p((x) => (x ? JSON.parse(x.toString()) : {}), payloadLimit, payloadLimitErrorFn)(req, res, next)
+        req.body = await p(
+          (x) => {
+            const str = td.decode(x)
+            return str ? JSON.parse(str) : {}
+          },
+          payloadLimit,
+          payloadLimitErrorFn
+        )(req, res, next)
       } else next()
     }
 
+/**
+ * Parse raw payload
+ * @param options
+ */
 const raw =
   ({ payloadLimit, payloadLimitErrorFn }: ParserOptions = {}) =>
     async (req: ReqWithBody, _res: Response, next: NextFunction) => {
@@ -62,46 +95,54 @@ const raw =
       } else next()
     }
 
+const td = new TextDecoder()
+/**
+ * Stringify request payload
+ * @param param0
+ * @returns
+ */
 const text =
   ({ payloadLimit, payloadLimitErrorFn }: ParserOptions = {}) =>
     async (req: ReqWithBody, _res: Response, next: NextFunction) => {
       if (hasBody(req.method!)) {
-        req.body = await p((x) => x.toString(), payloadLimit, payloadLimitErrorFn)(req, _res, next)
+        req.body = await p((x) => td.decode(x), payloadLimit, payloadLimitErrorFn)(req, _res, next)
       } else next()
     }
 
+/**
+ * Parse urlencoded payload
+ * @param options
+ */
 const urlencoded =
   ({ payloadLimit, payloadLimitErrorFn }: ParserOptions = {}) =>
     async (req: ReqWithBody, _res: Response, next: NextFunction) => {
       if (hasBody(req.method!)) {
         req.body = await p(
-          (x) => {
-            const urlSearchParam = new URLSearchParams(x.toString())
-            return Object.fromEntries(urlSearchParam.entries())
-          },
+          (x) => Object.fromEntries(new URLSearchParams(x.toString()).entries()),
           payloadLimit,
           payloadLimitErrorFn
         )(req, _res, next)
       } else next()
     }
 
 const getBoundary = (contentType: string) => {
-  // Extract the boundary from the Content-Type header
   const match = /boundary=(.+);?/.exec(contentType)
   return match ? `--${match[1]}` : null
 }
 
 const defaultFileSizeLimitErrorFn: LimitErrorFn = (limit) => new Error(`File too large. Limit: ${limit} bytes`)
 
-const parseMultipart = (body: string, boundary: string, { fileCountLimit, fileSizeLimit, fileSizeLimitErrorFn = defaultFileSizeLimitErrorFn }: MultipartOptions) => {
-  // Split the body into an array of parts
+const parseMultipart = (
+  body: string,
+  boundary: string,
+  { fileCountLimit, fileSizeLimit, fileSizeLimitErrorFn = defaultFileSizeLimitErrorFn }: MultipartOptions
+) => {
   const parts = body.split(new RegExp(`${boundary}(--)?`)).filter((part) => !!part && /content-disposition/i.test(part))
   const parsedBody: Record<string, (File | string)[]> = {}
 
   if (fileCountLimit && parts.length > fileCountLimit) throw new Error(`Too many files. Limit: ${fileCountLimit}`)
 
-  // Parse each part into a form data object
-  // biome-ignore lint/complexity/noForEach: <explanation>
+  // biome-ignore lint/complexity/noForEach: for...of fails
   parts.forEach((part) => {
     const [headers, ...lines] = part.split('\r\n').filter((part) => !!part)
     const data = lines.join('\r\n').trim()
@@ -120,28 +161,45 @@ const parseMultipart = (body: string, boundary: string, { fileCountLimit, fileSi
       parsedBody[name] = parsedBody[name] ? [...parsedBody[name], file] : [file]
       return
     }
-    // This is a regular field
     parsedBody[name] = parsedBody[name] ? [...parsedBody[name], data] : [data]
     return
   })
 
   return parsedBody
 }
 type MultipartOptions = Partial<{
+  /**
+   * Limit number of files
+   */
   fileCountLimit: number
+  /**
+   * Limit file size (in bytes)
+   */
   fileSizeLimit: number
+  /**
+   * Custom error function for file size limit
+   */
   fileSizeLimitErrorFn: LimitErrorFn
 }>
-
+/**
+ * Parse multipart form data (supports files as well)
+ *
+ * Does not restrict total payload size by default
+ * @param options
+ */
 const multipart =
-  ({ payloadLimit, payloadLimitErrorFn, ...opts }: MultipartOptions & ParserOptions = {}) =>
+  ({ payloadLimit = Number.POSITIVE_INFINITY, payloadLimitErrorFn, ...opts }: MultipartOptions & ParserOptions = {}) =>
     async (req: ReqWithBody, res: Response, next: NextFunction) => {
       if (hasBody(req.method!)) {
-        req.body = await p((x) => {
-          const boundary = getBoundary(req.headers['content-type']!)
-          if (boundary) return parseMultipart(x, boundary, opts)
-          return {}
-        }, payloadLimit, payloadLimitErrorFn)(req, res, next)
+        req.body = await p(
+          (x) => {
+            const boundary = getBoundary(req.headers['content-type']!)
+            if (boundary) return parseMultipart(td.decode(x), boundary, opts)
+            return {}
+          },
+          payloadLimit,
+          payloadLimitErrorFn
+        )(req, res, next)
         next()
       } else next()
     }