@gcmdev/faxios 0.2.2 → 0.2.3

package/src/lib/helpers/toFormData.ts

@@ -91,7 +91,7 @@ const predicates = utils.toFlatObject(utils, {}, null as unknown as false, funct
  */
 function toFormData(obj: unknown, formData?: GenericFormData | null, options?: Record<string, unknown>): GenericFormData {
   if (!utils.isObject(obj)) {
-    throw new TypeError("target must be an object");
+    throw new FaxiosError("target must be an object", FaxiosError.ERR_BAD_REQUEST);
   }
 
   const FormDataCtor = (globalThis as Record<string, unknown>)["FormData"] as (new () => GenericFormData) | undefined;
@@ -120,16 +120,16 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
   const visitor = (options["visitor"] || defaultVisitor) as SerializerVisitor;
   const dots = options["dots"];
   const indexes = options["indexes"];
-  const _Blob = options["Blob"] || (typeof (globalThis as Record<string, unknown>)["Blob"] !== "undefined" && (globalThis as Record<string, unknown>)["Blob"]);
+  const _Blob = (options["Blob"] || (globalThis as Record<string, unknown>)["Blob"]) as (new (parts: Array<unknown>) => unknown) | undefined;
   const maxDepth =
     options["maxDepth"] === undefined
       ? DEFAULT_FORM_DATA_MAX_DEPTH
       : (options["maxDepth"] as number);
-  const useBlob = _Blob && utils.isSpecCompliantForm(formData);
+  const useBlob = typeof _Blob === "function" && utils.isSpecCompliantForm(formData);
   const stack: Array<unknown> = [];
 
   if (!utils.isFunction(visitor)) {
-    throw new TypeError("visitor must be a function");
+    throw new FaxiosError("visitor must be a function", FaxiosError.ERR_BAD_OPTION_VALUE);
   }
 
   function convertValue(value: unknown): unknown {
@@ -143,16 +143,15 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
       return String(value);
     }
 
-    if (!useBlob && utils.isBlob(value)) {
-      throw new FaxiosError("Blob is not supported. Use a Buffer instead.");
+    if (!useBlob && (utils.isBlob(value) || utils.isArrayBuffer(value) || utils.isTypedArray(value))) {
+      throw new FaxiosError(
+        "Binary FormData values need a spec-compliant FormData and a Blob constructor (set the `Blob` option)",
+        FaxiosError.ERR_NOT_SUPPORT
+      );
     }
 
     if (utils.isArrayBuffer(value) || utils.isTypedArray(value)) {
-      const BlobCtor = (globalThis as Record<string, unknown>)["Blob"] as (new (parts: Array<unknown>) => unknown) | undefined;
-      if (useBlob && typeof BlobCtor === "function") {
-        return new BlobCtor([ value ]);
-      }
-      throw new FaxiosError("Blob is required for binary FormData values in this environment", FaxiosError.ERR_NOT_SUPPORT);
+      return new (_Blob as new (parts: Array<unknown>) => unknown)([ value ]);
     }
 
     return value;
@@ -250,11 +249,12 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     return false;
   }
 
-  const exposedHelpers: FormDataVisitorHelpers = Object.assign(predicates, {
-    defaultVisitor: defaultVisitor,
+  const exposedHelpers: FormDataVisitorHelpers = {
+    ...predicates,
+    defaultVisitor,
     convertValue,
     isVisitable,
-  });
+  };
 
   function build(value: unknown, path?: Array<number | string>, depth = 0): void {
     if (utils.isUndefined(value)) return;
@@ -262,7 +262,7 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     throwIfMaxDepthExceeded(depth);
 
     if (stack.indexOf(value) !== -1) {
-      throw new Error("Circular reference detected in " + (path ?? []).join("."));
+      throw new FaxiosError("Circular reference detected in " + (path ?? []).join("."), FaxiosError.ERR_BAD_REQUEST);
     }
 
     stack.push(value);
@@ -286,10 +286,6 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     stack.pop();
   }
 
-  if (!utils.isObject(obj)) {
-    throw new TypeError("data must be an object");
-  }
-
   build(obj);
 
   return formData;

package/src/lib/helpers/trackStream.ts

@@ -1,3 +1,6 @@
+import FaxiosError from "../core/FaxiosError.js";
+import utils from "../utils.js";
+
 type ReadableStreamController = {
   close: () => void;
   enqueue: (chunk: Uint8Array) => void;
@@ -16,9 +19,31 @@ type ReadableStreamCtor = new (source: ReadableStreamSource, init?: ReadableStre
 
 const ReadableStreamGlobal = (globalThis as Record<string, unknown>)["ReadableStream"] as ReadableStreamCtor | undefined;
 
-type ByteChunk = { byteLength: number; slice: (start: number, end?: number) => ByteChunk; };
+const textEncoder = typeof TextEncoder === "function" ? new TextEncoder() : undefined;
+
+// View the chunk's bytes without copying them. Strings are UTF-8 encoded; anything else is not
+// a byte chunk and is rejected rather than silently converted.
+const toBytes = (chunk: unknown): Uint8Array => {
+  if (chunk instanceof Uint8Array) {
+    return chunk;
+  }
+  if (utils.isArrayBufferView(chunk)) {
+    const view = chunk as ArrayBufferView;
+    return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+  }
+  if (utils.isArrayBuffer(chunk)) {
+    return new Uint8Array(chunk as ArrayBuffer);
+  }
+  if (utils.isString(chunk) && textEncoder) {
+    return textEncoder.encode(chunk as string);
+  }
+  throw new FaxiosError(
+    "Stream chunk must be a Uint8Array, another ArrayBufferView, an ArrayBuffer or a string, got " + utils.kindOf(chunk),
+    FaxiosError.ERR_BAD_REQUEST
+  );
+};
 
-const streamChunk = function* (chunk: ByteChunk, chunkSize?: number): Generator<ByteChunk> {
+const streamChunk = function* (chunk: Uint8Array, chunkSize?: number): Generator<Uint8Array> {
   const len = chunk.byteLength;
 
   if (!chunkSize || len < chunkSize) {
@@ -31,31 +56,31 @@ const streamChunk = function* (chunk: ByteChunk, chunkSize?: number): Generator<
 
   while (pos < len) {
     end = pos + chunkSize;
-    yield chunk.slice(pos, end);
+    yield chunk.subarray(pos, end);
     pos = end;
   }
 };
 
-const readBytes = async function* (iterable: AsyncIterable<ByteChunk> | unknown, chunkSize?: number): AsyncGenerator<ByteChunk> {
+const readBytes = async function* (iterable: unknown, chunkSize?: number): AsyncGenerator<Uint8Array> {
   for await (const chunk of readStream(iterable)) {
-    yield* streamChunk(chunk, chunkSize);
+    yield* streamChunk(toBytes(chunk), chunkSize);
   }
 };
 
 type ReaderLike = {
   cancel: () => Promise<void>;
-  read: () => Promise<{ done: boolean; value: ByteChunk; }>;
+  read: () => Promise<{ done: boolean; value: unknown; }>;
 };
 
 type StreamLike = {
-  [Symbol.asyncIterator]?: () => AsyncIterator<ByteChunk>;
+  [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
   getReader?: () => ReaderLike;
 };
 
-const readStream = async function* (stream: unknown): AsyncGenerator<ByteChunk> {
+const readStream = async function* (stream: unknown): AsyncGenerator<unknown> {
   const s = stream as StreamLike;
   if (s[Symbol.asyncIterator]) {
-    yield* s as AsyncIterable<ByteChunk>;
+    yield* s as AsyncIterable<unknown>;
     return;
   }
 
@@ -104,9 +129,12 @@ export const trackStream = (stream: unknown, chunkSize: number | undefined, onPr
             const loadedBytes = (bytes += len);
             onProgress(loadedBytes);
           }
-          controller.enqueue(new Uint8Array(value as unknown as ArrayBuffer));
+          controller.enqueue(value);
         }
         catch (err) {
+          // Cancel the source so its lock and connection are released. The original error wins
+          // over a failure to cancel.
+          await iterator.return(undefined).catch(() => {});
           _onFinish(err);
           throw err;
         }

package/src/lib/types.ts

@@ -152,6 +152,8 @@ export interface SerializerVisitor {
 }
 
 export interface SerializerOptions {
+  /** FormData only: Blob constructor used to wrap `ArrayBuffer` and typed-array values. Defaults to `globalThis.Blob`. */
+  Blob?: new (parts: Array<BlobPart>) => Blob;
   dots?: boolean;
   indexes?: boolean | null;
   /** Maximum nesting depth to serialize; deeper objects throw `ERR_FORM_DATA_DEPTH_EXCEEDED`. `Infinity` disables the check. */
@@ -279,7 +281,19 @@ export interface FaxiosRequestConfig<D = unknown> {
   maxBodyLength?: number;
   maxContentLength?: number;
   method?: StringLiteralsOrString<Method>;
+  /**
+   * Called with download progress. For a content-encoded response (any `Content-Encoding`
+   * other than `identity`) `total` is `undefined` and `lengthComputable` is `false`.
+   * An error thrown (or a rejected promise returned) by the callback is caught and ignored;
+   * the request settles normally.
+   */
   onDownloadProgress?: (progressEvent: FaxiosProgressEvent) => void;
+  /**
+   * Called with upload progress where faxios can stream the request body, which today is
+   * Node.js. It is not called in browsers or web workers (see #209).
+   * An error thrown (or a rejected promise returned) by the callback is caught and ignored;
+   * the request settles normally.
+   */
   onUploadProgress?: (progressEvent: FaxiosProgressEvent) => void;
   params?: Record<string, unknown> | URLSearchParams;
   paramsSchema?: StandardSchemaV1;

package/src/lib/utils.ts

@@ -448,6 +448,9 @@ function merge(this: unknown, ...objs: Array<unknown>): Record<string, unknown>
   const caseless = ctx && ctx.caseless;
   const skipUndefined = ctx && ctx.skipUndefined;
   const result: Record<string | symbol, unknown> = {};
+  // Caseless mode: lowercased key -> the key already written to `result`. Only assignValue
+  // writes to `result`, so this index is complete.
+  const caselessKeys = new Map<string, string>();
   const assignValue = (val: unknown, key: unknown) => {
     const keyStr = key as string | symbol;
     // Skip dangerous property names to prevent prototype pollution
@@ -455,9 +458,9 @@ function merge(this: unknown, ...objs: Array<unknown>): Record<string, unknown>
       return;
     }
 
-    // findKey lowercases the key, so caseless lookup only applies to strings —
-    // symbol keys are identity-matched.
-    const targetKey: string | symbol = (caseless && typeof keyStr === "string" ? (findKey(result, keyStr) ?? (keyStr)) : (keyStr));
+    // Caseless lookup only applies to strings — symbol keys are identity-matched.
+    const lowerKey = caseless && typeof keyStr === "string" ? keyStr.toLowerCase() : undefined;
+    const targetKey: string | symbol = (lowerKey === undefined ? keyStr : (caselessKeys.get(lowerKey) ?? keyStr));
     // Read via own-prop only — a bare `result[targetKey]` walks the prototype
     // chain, so a polluted Object.prototype value could surface here and get
     // copied into the merged result.
@@ -474,6 +477,9 @@ function merge(this: unknown, ...objs: Array<unknown>): Record<string, unknown>
     else if (!skipUndefined || !isUndefined(val)) {
       result[targetKey] = val;
     }
+    if (lowerKey !== undefined && hasOwnProperty(result, targetKey)) {
+      caselessKeys.set(lowerKey, targetKey as string);
+    }
   };
 
   for (let i = 0, l = objs.length; i < l; i++) {