@sdxc/http 2026.9.28 → 2026.9.30

package/README.md

@@ -189,19 +189,68 @@ and returns a plain
 import { csv, markdown, xml } from "@sdxc/http/response";
 
 xml("<root><item>Hello</item></root>"); // text/xml
-csv("name,age\nAda,36"); // text/csv
+csv("name,age\nAda,36"); // text/csv; charset=utf-8
 markdown("# Hello"); // text/markdown
 ```
 
 `json(body, init?)` serializes any value through `Response.json`. `text`, `html`, `css`,
-`javascript`, `xml`, `csv` and `markdown` each take a string and write their own type.
+`javascript`, `xml` and `markdown` each take a string and write their own type.
 `pdf(body, init?)` writes `application/pdf` and takes a `Blob`, `ArrayBuffer` or
 `ReadableStream`.
 
+#### `csv(body: string | ReadableStream<Uint8Array>, init?: ResponseInit): Response`
+
+Writes `text/csv; charset=utf-8`, so a client decodes accented and non-Latin cells as UTF-8.
+The body is a whole document or a stream of its UTF-8 bytes, which sends each row as it is
+written instead of holding the file in memory:
+
+```typescript
+import { csv } from "@sdxc/http/response";
+
+let encoder = new TextEncoder();
+
+return csv(
+	new ReadableStream<Uint8Array>({
+		async start(controller) {
+			controller.enqueue(encoder.encode("name,city\r\n"));
+			for await (let row of readRows()) {
+				controller.enqueue(encoder.encode(`${row.name},${row.city}\r\n`));
+			}
+			controller.close();
+		},
+	}),
+);
+```
+
+#### `attachment(filename: string): string`
+
+A [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition)
+value that makes a response a download saved under `filename`. The quoted `filename` always
+holds an ASCII version of the name, with quotes and backslashes escaped and every other
+character outside printable ASCII shown as `_`. A name that needed such a replacement also
+gets an RFC 8187 `filename*`, which browsers prefer, carrying the exact name in UTF-8.
+
+```typescript
+import { attachment } from "@sdxc/http/response";
+
+attachment("report.csv");
+// 'attachment; filename="report.csv"'
+attachment("Café report.csv");
+// "attachment; filename=\"Caf_ report.csv\"; filename*=UTF-8''Caf%C3%A9%20report.csv"
+attachment("報告.csv");
+// "attachment; filename=\"__.csv\"; filename*=UTF-8''%E5%A0%B1%E5%91%8A.csv"
+```
+
+Pass it in the `headers` of any builder, so a CSV or a PDF download keeps its own type:
+
+```typescript
+return csv(report, { headers: { "Content-Disposition": attachment("report-2026-08.csv") } });
+```
+
 #### `file(body: Blob | ArrayBuffer | ReadableStream, filename: string, init?: ResponseInit): Response`
 
-A download: `application/octet-stream` plus
-`Content-Disposition: attachment; filename="…"`.
+A download of opaque bytes: `application/octet-stream` plus the `Content-Disposition` that
+`attachment(filename)` writes.
 
 #### `stream(body: ReadableStream, init?: ResponseInit): Response`
 

package/dist/response.d.ts

@@ -73,16 +73,18 @@ export declare function javascript(body: string, init?: ResponseInit): Response;
  */
 export declare function xml(body: string, init?: ResponseInit): Response;
 /**
- * Creates a Response with CSV content and appropriate Content-Type header.
- * @param body - The CSV string to send
+ * Creates a Response with `text/csv; charset=utf-8`, for a whole document or one streamed
+ * as it is written. The charset parameter is what makes a client decode non-ASCII cells as
+ * UTF-8 instead of its locale's legacy encoding.
+ * @param body - The CSV document, or a stream of its UTF-8 bytes
  * @param init - Optional response options (status, headers, etc.)
  * @returns A new Response instance with CSV content
  * @example
  * return csv("name,age\nJohn,30\nJane,25");
  * @example
- * return csv("id,value\n1,100", { headers: { "Content-Disposition": "attachment; filename=data.csv" } });
+ * return csv(rows, { headers: { "Content-Disposition": attachment("report.csv") } });
  */
-export declare function csv(body: string, init?: ResponseInit): Response;
+export declare function csv(body: string | ReadableStream<Uint8Array>, init?: ResponseInit): Response;
 /**
  * Creates a Response with Markdown content and appropriate Content-Type header.
  * @param body - The Markdown string to send
@@ -107,8 +109,20 @@ export declare function markdown(body: string, init?: ResponseInit): Response;
  */
 export declare function pdf(body: Blob | ArrayBuffer | ReadableStream, init?: ResponseInit): Response;
 /**
- * Creates a Response for file downloads with Content-Disposition header.
- * Sets appropriate headers to trigger browser download behavior.
+ * An RFC 6266 `Content-Disposition: attachment` value for a download's file name. Every
+ * name gets a quoted ASCII `filename`, with characters outside printable ASCII shown as `_`;
+ * such a name also gets an RFC 8187 `filename*`, which clients prefer, carrying it exactly.
+ * @param filename - The name the download is saved as
+ * @returns The header value
+ * @example
+ * attachment("report.csv"); // 'attachment; filename="report.csv"'
+ * @example
+ * attachment("Café.csv"); // "attachment; filename=\"Caf_.csv\"; filename*=UTF-8''Caf%C3%A9.csv"
+ */
+export declare function attachment(filename: string): string;
+/**
+ * Creates a Response for a file download, with the name written by `attachment` so a quote
+ * or a non-ASCII character in it reaches the client intact.
  * @param body - The file content as Blob, ArrayBuffer, or ReadableStream
  * @param filename - The filename to suggest for the download
  * @param init - Optional response options (status, headers, etc.)

package/dist/response.js

@@ -96,18 +96,20 @@ export function xml(body, init) {
     return new Response(body, { ...init, headers });
 }
 /**
- * Creates a Response with CSV content and appropriate Content-Type header.
- * @param body - The CSV string to send
+ * Creates a Response with `text/csv; charset=utf-8`, for a whole document or one streamed
+ * as it is written. The charset parameter is what makes a client decode non-ASCII cells as
+ * UTF-8 instead of its locale's legacy encoding.
+ * @param body - The CSV document, or a stream of its UTF-8 bytes
  * @param init - Optional response options (status, headers, etc.)
  * @returns A new Response instance with CSV content
  * @example
  * return csv("name,age\nJohn,30\nJane,25");
  * @example
- * return csv("id,value\n1,100", { headers: { "Content-Disposition": "attachment; filename=data.csv" } });
+ * return csv(rows, { headers: { "Content-Disposition": attachment("report.csv") } });
  */
 export function csv(body, init) {
     let headers = new Headers(init?.headers);
-    headers.set("Content-Type", ContentType.CSV);
+    headers.set("Content-Type", `${ContentType.CSV}; charset=utf-8`);
     return new Response(body, { ...init, headers });
 }
 /**
@@ -142,8 +144,49 @@ export function pdf(body, init) {
     return new Response(body, { ...init, headers });
 }
 /**
- * Creates a Response for file downloads with Content-Disposition header.
- * Sets appropriate headers to trigger browser download behavior.
+ * Characters outside printable ASCII, which a quoted `filename` cannot carry. Matched per
+ * code point, so an astral character becomes one fallback character.
+ */
+const NON_PRINTABLE_ASCII = /[^\x20-\x7E]/gu;
+/** The two characters a quoted-string must escape with a backslash. */
+const QUOTED_STRING_SPECIALS = /["\\]/g;
+/** RFC 8187 `attr-char`: the bytes an `ext-value` may carry without percent-encoding. */
+const ATTR_CHAR = /^[A-Za-z0-9!#$&+\-.^_`|~]$/;
+/**
+ * An RFC 8187 `ext-value` for a name, percent-encoding every UTF-8 byte outside
+ * `attr-char`. A lone surrogate encodes as U+FFFD, so every string yields a valid value.
+ * @param value - The name to encode
+ * @returns The value with its `UTF-8''` prefix
+ */
+function extValue(value) {
+    let encoded = "UTF-8''";
+    for (let byte of new TextEncoder().encode(value)) {
+        let char = String.fromCharCode(byte);
+        encoded += ATTR_CHAR.test(char) ? char : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+    return encoded;
+}
+/**
+ * An RFC 6266 `Content-Disposition: attachment` value for a download's file name. Every
+ * name gets a quoted ASCII `filename`, with characters outside printable ASCII shown as `_`;
+ * such a name also gets an RFC 8187 `filename*`, which clients prefer, carrying it exactly.
+ * @param filename - The name the download is saved as
+ * @returns The header value
+ * @example
+ * attachment("report.csv"); // 'attachment; filename="report.csv"'
+ * @example
+ * attachment("Café.csv"); // "attachment; filename=\"Caf_.csv\"; filename*=UTF-8''Caf%C3%A9.csv"
+ */
+export function attachment(filename) {
+    let fallback = filename.replaceAll(NON_PRINTABLE_ASCII, "_");
+    let value = `attachment; filename="${fallback.replaceAll(QUOTED_STRING_SPECIALS, "\\$&")}"`;
+    if (fallback !== filename)
+        value += `; filename*=${extValue(filename)}`;
+    return value;
+}
+/**
+ * Creates a Response for a file download, with the name written by `attachment` so a quote
+ * or a non-ASCII character in it reaches the client intact.
  * @param body - The file content as Blob, ArrayBuffer, or ReadableStream
  * @param filename - The filename to suggest for the download
  * @param init - Optional response options (status, headers, etc.)
@@ -156,7 +199,7 @@ export function pdf(body, init) {
 export function file(body, filename, init) {
     let headers = new Headers(init?.headers);
     headers.set("Content-Type", ContentType.OctetStream);
-    headers.set("Content-Disposition", `attachment; filename="${filename}"`);
+    headers.set("Content-Disposition", attachment(filename));
     return new Response(body, { ...init, headers });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/http",
-	"version": "2026.9.28",
+	"version": "2026.9.30",
 	"description": "Response builders, content negotiation, and HTTP caching for the Fetch API",
 	"license": "MIT",
 	"type": "module",
@@ -19,9 +19,9 @@
 		"@sdxc/duration": "2026.9.15",
 		"@sdxc/location": "2026.9.11",
 		"@sdxc/result": "2026.9.15",
-		"remix": "3.0.0-rc.2"
+		"remix": "3.0.0-rc.4"
 	},
-	"gitHead": "00c01e349b11f65b9f47902c5345a817e8afd2b1",
+	"gitHead": "81432d2333817dfd7ee61634baff813432ecee9c",
 	"publishConfig": {
 		"access": "public"
 	},