@voltts/serializer 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@voltts/serializer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Ultra-fast response serialization and content-type handling for Volt",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './serializer';

package/src/serializer.ts

@@ -0,0 +1,122 @@
+import { ResponseInitOptions } from './types';
+
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+const TEXT_CONTENT_TYPE = 'text/plain; charset=utf-8';
+const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
+const OCTET_CONTENT_TYPE = 'application/octet-stream';
+
+export function json(data: unknown, init?: number | ResponseInitOptions): Response {
+  if ((init === undefined || init === 200) && typeof Response.json === 'function') {
+    return Response.json(data);
+  }
+
+  const options = typeof init === 'number' ? { status: init } : init || {};
+  const status = options.status ?? 200;
+
+  // Use Bun's highly optimized Response.json when available
+  if (typeof Response.json === 'function') {
+    return Response.json(data, {
+      ...options,
+      status,
+      headers: {
+        'content-type': JSON_CONTENT_TYPE,
+        ...options.headers,
+      },
+    });
+  }
+
+  return new Response(JSON.stringify(data), {
+    ...options,
+    status,
+    headers: {
+      'content-type': JSON_CONTENT_TYPE,
+      ...options.headers,
+    },
+  });
+}
+
+export function text(text: string, init?: number | ResponseInitOptions): Response {
+  const options = typeof init === 'number' ? { status: init } : init || {};
+  return new Response(text, {
+    ...options,
+    status: options.status ?? 200,
+    headers: {
+      'content-type': TEXT_CONTENT_TYPE,
+      ...options.headers,
+    },
+  });
+}
+
+export function html(html: string, init?: number | ResponseInitOptions): Response {
+  const options = typeof init === 'number' ? { status: init } : init || {};
+  return new Response(html, {
+    ...options,
+    status: options.status ?? 200,
+    headers: {
+      'content-type': HTML_CONTENT_TYPE,
+      ...options.headers,
+    },
+  });
+}
+
+export function binary(buffer: BodyInit, contentType = OCTET_CONTENT_TYPE, init?: number | ResponseInitOptions): Response {
+  const options = typeof init === 'number' ? { status: init } : init || {};
+  return new Response(buffer, {
+    ...options,
+    status: options.status ?? 200,
+    headers: {
+      'content-type': contentType,
+      ...options.headers,
+    },
+  });
+}
+
+export function stream(readable: ReadableStream, contentType = OCTET_CONTENT_TYPE, init?: number | ResponseInitOptions): Response {
+  const options = typeof init === 'number' ? { status: init } : init || {};
+  return new Response(readable, {
+    ...options,
+    status: options.status ?? 200,
+    headers: {
+      'content-type': contentType,
+      ...options.headers,
+    },
+  });
+}
+
+export function serializeResponse(value: unknown, defaultStatus = 200): Response {
+  if (value instanceof Response) {
+    return value;
+  }
+
+  if (typeof value === 'object') {
+    if (value === null) {
+      return new Response(null, { status: 204 });
+    }
+
+    // Fast-path: 99% of API responses are plain objects/arrays with 200 status
+    if (defaultStatus === 200 && typeof Response.json === 'function' && ((value as any).constructor === Object || Array.isArray(value))) {
+      return Response.json(value);
+    }
+
+    if (value instanceof Blob || value instanceof ArrayBuffer || value instanceof Uint8Array) {
+      return binary(value as BodyInit, OCTET_CONTENT_TYPE, defaultStatus);
+    }
+
+    if (value instanceof ReadableStream) {
+      return stream(value, OCTET_CONTENT_TYPE, defaultStatus);
+    }
+
+    return json(value, defaultStatus);
+  }
+
+  if (typeof value === 'string') {
+    return text(value, defaultStatus);
+  }
+
+  if (value === undefined) {
+    return new Response(null, { status: 204 });
+  }
+
+  return text(String(value), defaultStatus);
+}
+

package/src/types.ts

@@ -0,0 +1,11 @@
+export type ResponseInitOptions = {
+  status?: number;
+  statusText?: string;
+  headers?: HeadersInit;
+};
+
+export type Serializer<T = any> = (data: T) => string;
+
+export interface SerializerOptions {
+  detectContentType?: boolean;
+}

package/test/serializer.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'bun:test';
+import { html, json, serializeResponse, text } from '../src/index';
+
+describe('@voltts/serializer', () => {
+  it('serializes JSON responses with correct headers', async () => {
+    const res = json({ hello: 'volt' }, 201);
+    expect(res.status).toBe(201);
+    expect(res.headers.get('content-type')).toContain('application/json');
+    const data = await res.json();
+    expect(data).toEqual({ hello: 'volt' });
+  });
+
+  it('serializes text responses', async () => {
+    const res = text('Plain text response', 200);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toContain('text/plain');
+    expect(await res.text()).toBe('Plain text response');
+  });
+
+  it('serializes HTML responses', async () => {
+    const res = html('<h1>Volt</h1>', 200);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toContain('text/html');
+    expect(await res.text()).toBe('<h1>Volt</h1>');
+  });
+
+  it('automatically detects and serializes arbitrary handler return values', async () => {
+    // 1. Primitive string
+    const resStr = serializeResponse('hello');
+    expect(resStr.headers.get('content-type')).toContain('text/plain');
+    expect(await resStr.text()).toBe('hello');
+
+    // 2. Object
+    const resObj = serializeResponse({ a: 1 });
+    expect(resObj.headers.get('content-type')).toContain('application/json');
+    expect(await resObj.json()).toEqual({ a: 1 });
+
+    // 3. Null / Undefined -> 204 No Content
+    const resNull = serializeResponse(null);
+    expect(resNull.status).toBe(204);
+
+    // 4. Pass-through Response
+    const raw = new Response('raw', { status: 418 });
+    const resRaw = serializeResponse(raw);
+    expect(resRaw.status).toBe(418);
+  });
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.