@asterflow/response 1.0.10 → 1.1.0

package/README.md

@@ -10,202 +10,52 @@
 
 </div>
 
-> Unified HTTP response adapter system for AsterFlow applications.
+> Type-safe HTTP response builder with status-code helpers, header/cookie management, and binary file responses.
 
 ## 📦 Installation
 
 ```bash
-npm install @asterflow/response
-# or
 bun install @asterflow/response
 ```
 
-## 💡 About
+### ✨ Features
 
-@asterflow/response provides a type-safe, unified response system for AsterFlow applications. It standardizes HTTP response handling across different runtimes while maintaining full type safety and providing convenient helper methods for common HTTP status codes.
+- **Typed status codes** — `response.status(code)` narrows the accepted body type to what that code expects
+- **Shorthand helpers** — `success`, `created`, `noContent`, `badRequest`, `unauthorized`, `forbidden`, `notFound`, `validationError`, `internalServerError`
+- **JSON responses** — `.json(data)` sends the body and sets `Content-Type: application/json`
+- **Binary/file responses** — `.file(data, contentType?)` sends a `Uint8Array` as raw bytes; without a `contentType`, it's detected from the data's magic bytes (PNG, JPEG, GIF, PDF, BMP, ICO, GZIP, ZIP, WEBP), falling back to `application/octet-stream`
+- **Headers and cookies** — `setHeader`/`setCookie`, each chainable and reflected in the response's type
+- **Runtime conversion** — `toResponse()` for the standard Web `Response`, `toServerResponse(res)` for Node's `http.ServerResponse`
 
-## ✨ Features
+## ❓ How to Use
 
-- **Complete Type Safety:** Full TypeScript support with type inference for responses, status codes, and body types
-- **Status Code Helpers:** Built-in methods for common HTTP status codes (200, 201, 400, 404, etc.)
-- **Header Management:** Type-safe header manipulation with method chaining
-- **Cookie Support:** Integrated cookie management system
-- **Content Type Detection:** Automatic content type detection and JSON serialization
-- **Multi-Runtime Support:** Compatible with standard Response and Node.js ServerResponse
-- **Immutable Design:** Response objects are immutable, promoting safer code patterns
-- **Method Chaining:** Fluent API for building complex responses
+```ts
+import { AsterResponse } from '@asterflow/response'
 
-## 🚀 Usage
-
-### Basic Response
-
-```typescript
-import { Response } from '@asterflow/response'
-
-// Simple text response
-const response = new Response()
-  .success({ message: 'Hello World!' })
-
-// With status code
-const response = new Response()
+const response = new AsterResponse()
   .status(201)
-  .send({ id: 1, name: 'User' })
-```
-
-### Status Code Helpers
-
-```typescript
-import { Response } from '@asterflow/response'
-
-// Success responses
-const success = new Response().success({ data: 'Success!' })
-const created = new Response().created({ id: 1 })
-const noContent = new Response().noContent()
-
-// Error responses
-const badRequest = new Response().badRequest({ error: 'Invalid input' })
-const unauthorized = new Response().unauthorized({ error: 'Not authenticated' })
-const forbidden = new Response().forbidden({ error: 'Access denied' })
-const notFound = new Response().notFound({ error: 'Resource not found' })
-const zodError = new Response().zodError({ errors: ['Validation failed'] })
-```
-
-### Headers and Cookies
-
-```typescript
-import { Response } from '@asterflow/response'
-
-const response = new Response()
-  .success({ message: 'Hello!' })
-  .setHeader('X-Custom-Header', 'custom-value')
-  .setHeader('Cache-Control', 'no-cache')
-  .setCookie('session', 'abc123')
-  .setCookie('theme', 'dark')
-
-// Headers and cookies are fully typed
-console.log(response.header) // Map with typed entries
-console.log(response.cookies) // Map with typed entries
+  .setHeader('X-Request-Id', 'abc123')
+  .json({ id: 1, name: 'User' })
 ```
 
-### JSON Responses
+Sending a file works the same way — pass the bytes, and the content type is sniffed automatically if you don't already know it:
 
-```typescript
-import { Response } from '@asterflow/response'
+```ts
+import { readFile } from 'fs/promises'
+import { AsterResponse } from '@asterflow/response'
 
-// Automatic JSON serialization
-const jsonResponse = new Response()
-  .json({ 
-    users: [
-      { id: 1, name: 'John' },
-      { id: 2, name: 'Jane' }
-    ]
-  })
-
-// Content-Type automatically set to application/json
+const data = await readFile('avatar.png')
+const response = new AsterResponse().file(data) // Content-Type: image/png
 ```
 
-### Integration with Different Runtimes
-
-#### Standard Web API
-
-```typescript
-import { Response } from '@asterflow/response'
-
-const response = new Response()
-  .success({ message: 'Hello World!' })
-
-// Convert to standard Response
-const webResponse = response.toResponse()
-```
-
-#### Node.js HTTP Server
-
-```typescript
-import { Response } from '@asterflow/response'
-import { createServer } from 'http'
-
-createServer((req, res) => {
-  const response = new Response()
-    .success({ message: 'Hello from Node.js!' })
-  
-  // Convert to ServerResponse
-  response.toServerResponse(res)
-})
-```
-
-### Advanced Type Safety
-
-```typescript
-import { Response } from '@asterflow/response'
-
-// Define custom response types
-type MyResponders = {
-  200: { message: string; data: unknown }
-  201: { id: number; message: string }
-  400: { error: string; details?: string[] }
-  404: { error: string }
-}
-
-const response = new Response<MyResponders>()
-  .success({ message: 'Success!', data: { id: 1 } }) // Fully typed
-  
-// TypeScript will enforce the correct shape for each status code
-```
-
-### Method Chaining
-
-```typescript
-import { Response } from '@asterflow/response'
-
-const response = new Response()
-  .status(201)
-  .setHeader('Location', '/users/123')
-  .setHeader('X-Request-ID', 'req-123')
-  .setCookie('last-action', 'create-user')
-  .json({ 
-    id: 123, 
-    message: 'User created successfully' 
-  })
-```
-
-## 🔧 API Reference
-
-### Core Methods
-
-- `status(code)` - Set HTTP status code
-- `getStatus()` - Get current status code
-- `send(data)` - Send response with data
-- `json(data)` - Send JSON response with proper Content-Type
-
-### Status Code Helpers
-
-- `success(data)` - 200 OK
-- `created(data)` - 201 Created
-- `noContent(data)` - 204 No Content
-- `badRequest(data)` - 400 Bad Request
-- `unauthorized(data)` - 401 Unauthorized
-- `forbidden(data)` - 403 Forbidden
-- `notFound(data)` - 404 Not Found
-- `zodError(data)` - 422 Unprocessable Entity
-
-### Header and Cookie Management
-
-- `setHeader(name, value)` - Add/update header
-- `setCookie(name, value)` - Add/update cookie
-
-### Runtime Conversion
-
-- `toResponse()` - Convert to standard Web API Response
-- `toServerResponse(serverRes)` - Write to Node.js ServerResponse
+Convert the finished response for whichever runtime you're on: `response.toResponse()` or `response.toServerResponse(res)`.
 
 ## 🔗 Related Packages
 
-- [asterflow](https://www.npmjs.com/package/asterflow) - Core framework
-- [@asterflow/router](https://www.npmjs.com/package/@asterflow/router) - Type-safe routing system
-- [@asterflow/adapter](https://www.npmjs.com/package/@asterflow/adapter) - HTTP adapters for different runtimes
-- [@asterflow/request](https://www.npmjs.com/package/@asterflow/request) - Unified HTTP request system
-- [@asterflow/plugin](https://www.npmjs.com/package/@asterflow/plugin) - A modular and typed plugin system
+- Depended on by [@asterflow/adapter](https://www.npmjs.com/package/@asterflow/adapter) — builds error responses and passes `AsterResponse` to its runtime adapters
+- Depended on by [@asterflow/multipart](https://www.npmjs.com/package/@asterflow/multipart) — returns `AsterResponse` errors for malformed multipart requests
+- Depended on by [asterflow](https://www.npmjs.com/package/asterflow) — the core framework's request handler works with `AsterResponse`
 
 ## 📄 License
 
-MIT - See [LICENSE](https://github.com/AsterFlow/AsterFlow/blob/main/LICENSE) for more details.
+This project is licensed under the [MIT License](../../LICENSE).

package/dist/cjs/index.cjs

@@ -1,26 +1,53 @@
 "use strict";
-var d = Object.defineProperty;
-var i = Object.getOwnPropertyDescriptor;
-var h = Object.getOwnPropertyNames;
-var c = Object.prototype.hasOwnProperty;
-var y = (o, e) => {
+var i = Object.defineProperty;
+var c = Object.getOwnPropertyDescriptor;
+var x = Object.getOwnPropertyNames;
+var m = Object.prototype.hasOwnProperty;
+var u = (s, e) => {
   for (var t in e)
-    d(o, t, { get: e[t], enumerable: !0 });
-}, p = (o, e, t, n) => {
+    i(s, t, { get: e[t], enumerable: !0 });
+}, S = (s, e, t, o) => {
   if (e && typeof e == "object" || typeof e == "function")
-    for (let s of h(e))
-      !c.call(o, s) && s !== t && d(o, s, { get: () => e[s], enumerable: !(n = i(e, s)) || n.enumerable });
-  return o;
+    for (let n of x(e))
+      !m.call(s, n) && n !== t && i(s, n, { get: () => e[n], enumerable: !(o = c(e, n)) || o.enumerable });
+  return s;
 };
-var S = (o) => p(d({}, "__esModule", { value: !0 }), o);
+var C = (s) => S(i({}, "__esModule", { value: !0 }), s);
 // packages/response/src/index.ts
-var u = {};
-y(u, {
-  AsterResponse: () => r
+var B = {};
+u(B, {
+  AsterResponse: () => y,
+  sniffContentType: () => d
 });
-module.exports = S(u);
+module.exports = C(B);
+// packages/response/src/utils/sniffContentType.ts
+var R = [
+  { mimeType: "image/png", bytes: [137, 80, 78, 71, 13, 10, 26, 10] },
+  { mimeType: "image/jpeg", bytes: [255, 216, 255] },
+  { mimeType: "image/gif", bytes: [71, 73, 70, 56] },
+  { mimeType: "application/pdf", bytes: [37, 80, 68, 70] },
+  { mimeType: "image/bmp", bytes: [66, 77] },
+  { mimeType: "image/x-icon", bytes: [0, 0, 1, 0] },
+  { mimeType: "application/gzip", bytes: [31, 139] },
+  { mimeType: "application/zip", bytes: [80, 75, 3, 4] },
+  { mimeType: "image/webp", bytes: [87, 69, 66, 80], offset: 8 }
+], f = [82, 73, 70, 70];
+function h(s, e, t = 0) {
+  if (s.length < t + e.length) return !1;
+  for (let o = 0; o < e.length; o++)
+    if (s[t + o] !== e[o]) return !1;
+  return !0;
+}
+function d(s) {
+  for (let e of R)
+    if (!(e.mimeType === "image/webp" && !h(s, f)) && h(s, e.bytes, e.offset))
+      return e.mimeType;
+}
 // packages/response/src/controllers/Response.ts
-var r = class o {
+function p(s) {
+  return s instanceof Uint8Array;
+}
+var y = class s {
   _status;
   body;
   context;
@@ -48,6 +75,15 @@ var r = class o {
       }
     }, this;
   }
+  file(e, t) {
+    return this.send(e), this.context = {
+      ...this.context,
+      header: {
+        ...this.context.header,
+        "Content-Type": t ?? d(e) ?? "application/octet-stream"
+      }
+    }, this;
+  }
   success(e) {
     return this.status(200), this.send(e), this;
   }
@@ -96,11 +132,12 @@ var r = class o {
   toResponse() {
     let e = new Headers();
     e.set("Content-Type", "text/plain");
-    for (let [n, s] of Object.entries(this.context.header)) e.set(n, s);
-    (typeof this.body == "object" || Array.isArray(this.body)) && e.set("Content-Type", "application/json");
-    for (let [n, s] of Object.entries(this.context.cookies)) e.append("Set-Cookie", `${n}=${s}`);
-    let t = e.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
-    return new globalThis.Response(t, {
+    for (let [n, a] of Object.entries(this.context.header)) e.set(n, a);
+    let t = p(this.body);
+    t ? "Content-Type" in this.context.header || e.set("Content-Type", "application/octet-stream") : (typeof this.body == "object" || Array.isArray(this.body)) && e.set("Content-Type", "application/json");
+    for (let [n, a] of Object.entries(this.context.cookies)) e.append("Set-Cookie", `${n}=${a}`);
+    let o = t ? this.body : e.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
+    return new globalThis.Response(o, {
       status: this._status,
       headers: e
     });
@@ -108,16 +145,18 @@ var r = class o {
   toServerResponse(e) {
     let t = new Headers();
     t.set("Content-Type", "text/plain");
-    for (let [s, a] of Object.entries(this.context.header)) t.set(s, a);
-    (typeof this.body == "object" || Array.isArray(this.body)) && t.set("Content-Type", "application/json");
-    for (let [s, a] of Object.entries(this.context.cookies)) t.append("Set-Cookie", `${s}=${a}`);
-    let n = t.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
+    for (let [a, r] of Object.entries(this.context.header)) t.set(a, r);
+    let o = p(this.body);
+    o ? "Content-Type" in this.context.header || t.set("Content-Type", "application/octet-stream") : (typeof this.body == "object" || Array.isArray(this.body)) && t.set("Content-Type", "application/json");
+    for (let [a, r] of Object.entries(this.context.cookies)) t.append("Set-Cookie", `${a}=${r}`);
+    let n = o ? this.body : t.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
     e.writeHead(this._status, Object.fromEntries(t)), e.end(n);
   }
   static create() {
-    return new o();
+    return new s();
   }
 };
 0 && (module.exports = {
-  AsterResponse
+  AsterResponse,
+  sniffContentType
 });

package/dist/mjs/index.js

@@ -1,5 +1,31 @@
+// packages/response/src/utils/sniffContentType.ts
+var p = [
+  { mimeType: "image/png", bytes: [137, 80, 78, 71, 13, 10, 26, 10] },
+  { mimeType: "image/jpeg", bytes: [255, 216, 255] },
+  { mimeType: "image/gif", bytes: [71, 73, 70, 56] },
+  { mimeType: "application/pdf", bytes: [37, 80, 68, 70] },
+  { mimeType: "image/bmp", bytes: [66, 77] },
+  { mimeType: "image/x-icon", bytes: [0, 0, 1, 0] },
+  { mimeType: "application/gzip", bytes: [31, 139] },
+  { mimeType: "application/zip", bytes: [80, 75, 3, 4] },
+  { mimeType: "image/webp", bytes: [87, 69, 66, 80], offset: 8 }
+], c = [82, 73, 70, 70];
+function i(s, e, t = 0) {
+  if (s.length < t + e.length) return !1;
+  for (let o = 0; o < e.length; o++)
+    if (s[t + o] !== e[o]) return !1;
+  return !0;
+}
+function d(s) {
+  for (let e of p)
+    if (!(e.mimeType === "image/webp" && !i(s, c)) && i(s, e.bytes, e.offset))
+      return e.mimeType;
+}
 // packages/response/src/controllers/Response.ts
-var a = class d {
+function y(s) {
+  return s instanceof Uint8Array;
+}
+var h = class s {
   _status;
   body;
   context;
@@ -27,6 +53,15 @@ var a = class d {
       }
     }, this;
   }
+  file(e, t) {
+    return this.send(e), this.context = {
+      ...this.context,
+      header: {
+        ...this.context.header,
+        "Content-Type": t ?? d(e) ?? "application/octet-stream"
+      }
+    }, this;
+  }
   success(e) {
     return this.status(200), this.send(e), this;
   }
@@ -75,11 +110,12 @@ var a = class d {
   toResponse() {
     let e = new Headers();
     e.set("Content-Type", "text/plain");
-    for (let [o, s] of Object.entries(this.context.header)) e.set(o, s);
-    (typeof this.body == "object" || Array.isArray(this.body)) && e.set("Content-Type", "application/json");
-    for (let [o, s] of Object.entries(this.context.cookies)) e.append("Set-Cookie", `${o}=${s}`);
-    let t = e.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
-    return new globalThis.Response(t, {
+    for (let [a, n] of Object.entries(this.context.header)) e.set(a, n);
+    let t = y(this.body);
+    t ? "Content-Type" in this.context.header || e.set("Content-Type", "application/octet-stream") : (typeof this.body == "object" || Array.isArray(this.body)) && e.set("Content-Type", "application/json");
+    for (let [a, n] of Object.entries(this.context.cookies)) e.append("Set-Cookie", `${a}=${n}`);
+    let o = t ? this.body : e.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
+    return new globalThis.Response(o, {
       status: this._status,
       headers: e
     });
@@ -87,16 +123,18 @@ var a = class d {
   toServerResponse(e) {
     let t = new Headers();
     t.set("Content-Type", "text/plain");
-    for (let [s, n] of Object.entries(this.context.header)) t.set(s, n);
-    (typeof this.body == "object" || Array.isArray(this.body)) && t.set("Content-Type", "application/json");
-    for (let [s, n] of Object.entries(this.context.cookies)) t.append("Set-Cookie", `${s}=${n}`);
-    let o = t.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
-    e.writeHead(this._status, Object.fromEntries(t)), e.end(o);
+    for (let [n, r] of Object.entries(this.context.header)) t.set(n, r);
+    let o = y(this.body);
+    o ? "Content-Type" in this.context.header || t.set("Content-Type", "application/octet-stream") : (typeof this.body == "object" || Array.isArray(this.body)) && t.set("Content-Type", "application/json");
+    for (let [n, r] of Object.entries(this.context.cookies)) t.append("Set-Cookie", `${n}=${r}`);
+    let a = o ? this.body : t.get("Content-Type") === "application/json" ? JSON.stringify(this.body) : String(this.body);
+    e.writeHead(this._status, Object.fromEntries(t)), e.end(a);
   }
   static create() {
-    return new d();
+    return new s();
   }
 };
 export {
-  a as AsterResponse
+  h as AsterResponse,
+  d as sniffContentType
 };

package/dist/types/controllers/Response.d.ts

@@ -16,6 +16,25 @@ export declare class AsterResponse<RawResponder extends Responders = Responders,
         }>;
         cookies: Context["cookies"];
     }>;
+    /**
+     * Sends a raw `Buffer`/`Uint8Array` body (e.g. a file read from disk).
+     * Unlike `send`/`json`, the body is written to the response exactly as
+     * given - never `JSON.stringify`'d or `String()`'d - so the client
+     * receives just the file's bytes, no wrapping object.
+     *
+     * `contentType` is optional: pass it when you already know the MIME type
+     * (cheapest - skips detection entirely). Omitted, it's detected straight
+     * from `data`'s leading magic bytes via `sniffContentType` - O(1)
+     * relative to the payload size, it inspects at most ~12 bytes and never
+     * scans the buffer. Falls back to `application/octet-stream` only if
+     * nothing matches.
+     */
+    file(data: Uint8Array, contentType?: string): AsterResponse<RawResponder, BodySchema, StatusCode, {
+        header: Prettify<Context["header"] & {
+            "Content-Type": string;
+        }>;
+        cookies: Context["cookies"];
+    }>;
     success(data: BodySchema[200]): AsterResponse<RawResponder, BodySchema, 200, Context>;
     created(data: BodySchema[201]): AsterResponse<RawResponder, BodySchema, 201, Context>;
     noContent(data: BodySchema[204]): AsterResponse<RawResponder, BodySchema, 204, Context>;

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types/response';
 export * from './types/utils';
 export * from './controllers/Response';
+export * from './utils/sniffContentType';

package/dist/types/utils/sniffContentType.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Detects a binary payload's MIME type from its leading magic bytes -
+ * O(1) relative to payload size (inspects at most ~12 bytes, never scans
+ * the buffer), synchronous, no dependency. Covers the formats an upload
+ * endpoint commonly deals with; returns `undefined` when nothing matches so
+ * callers can fall back to `application/octet-stream` themselves.
+ */
+export declare function sniffContentType(data: Uint8Array): string | undefined;

package/package.json

@@ -1,12 +1,27 @@
 {
   "name": "@asterflow/response",
-  "version": "1.0.10",
+  "version": "1.1.0",
+  "description": "Type-safe HTTP response builder with status-code helpers, header/cookie management, and binary file responses.",
+  "keywords": [
+    "asterflow",
+    "response",
+    "http"
+  ],
   "main": "dist/cjs/index.cjs",
   "module": "dist/mjs/index.js",
   "types": "dist/types/index.d.ts",
   "typings": "dist/types/index.d.ts",
   "type": "module",
   "license": "MIT",
+  "author": "Ashu11-A",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AsterFlow/AsterFlow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AsterFlow/AsterFlow/issues"
+  },
+  "homepage": "https://github.com/AsterFlow/AsterFlow",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",